Immediate and deferred expansion documentation rewording

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Immediate and deferred expansion documentation rewording

Maris Razvan
Hello,

I was reading section 3.7 of the GNU make online manual
(https://www.gnu.org/software/make/manual/make.html#Reading-Makefiles),
especially the second paragraph:

"It’s important to understand this two-phase approach because it has a
direct impact on how variable and function expansion happens; this is
often a source of some confusion when writing makefiles. Here we will
present a summary of the phases in which expansion happens for
different constructs within the makefile. We say that expansion is
immediate if it happens during the first phase: in this case make will
expand any variables or functions in that section of a construct as
the makefile is parsed. We say that expansion is deferred if expansion
is not performed immediately. Expansion of a deferred construct is not
performed until either the construct appears later in an immediate
context, or until the second phase."

I believe this paragraph is not worded very accurately.

In the following I will try to show how I understand some of its sentences.

First, from the following two sentences "We say that expansion is
immediate if it happens during the first phase: in this case make will
expand any variables or functions in that section of a construct as
the makefile is parsed. We say that expansion is deferred if expansion
is not performed immediately." I understand the following:

    - each cmake construct (i.e. rule, variable definition, directive
and comment) has sections (e.g. a rule has 3 sections: targets,
prerequisites and recipe)
    - text written in some of these sections will be expanded
immediately (i.e. variable and function references are expanded);
    - text written in the remaining sections is not expanded immediately

However, the next sentence, "Expansion of a deferred construct is not
performed until either the construct appears later in an immediate
context, or until the second phase.", uses a different terminology and
does not seem to be accurate. The following questions arise:

    - what is a "deferred construct"?
    - how is a "deferred construct" expanded?
    - how can a "deferred construct" appear in an immediate context?

My impression is that this sentence intends to refer to both
["recursively expanded variables"] and [recipes] as being "deferred
constructs".
First, a "recursively expanded variable" can "appear in an immediate
context" (e.g. in the value of a "simply expanded variable"), however
it is not expanded during the second phase.
Furthermore, a deferred section of a rule (i.e. the recipe) is
expanded during the second phase, however it cannot "appear in an
immediate context".

As a conclusion, I think that the last sentence of the quoted
paragraph from section 3.7 uses the word "construct" to refer to both
"recursively expanded variables" and "recipes" (a completely different
meaning than the one used in the previous sentences) and it specifies
two situations when they are expanded (however one situations
appertains only to "recursively expanded variables" and the other only
to "recipes").

Am I misunderstanding something or is this paragraph wrong?


Thank you,
Razvan Maris

_______________________________________________
Bug-make mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/bug-make
Reply | Threaded
Open this post in threaded view
|

Re: Immediate and deferred expansion documentation rewording

Martin Dorey-2
 I understand the following

Apart from the word "cmake", that chimed with my understanding.

a completely different meaning than the one used in the previous sentences

I think the meanings are consistent if "a section of a construct" is itself a "construct".

> however one situations
> appertains only to "recursively expanded variables" and the other only
> to "recipes"

Right, but I don't see that this lack of precision makes the prose inaccurate.  I bet you could smith a couple of replacement sentences that I for one would find precise, accurate and clear.

While you're there, it isn't the value of the recursively expanded variable that appears in an immediate context, but a reference to the name of the variable.


From: Bug-make <bug-make-bounces+martin.dorey=[hidden email]> on behalf of Maris Razvan <[hidden email]>
Sent: Tuesday, October 1, 2019 09:31
To: [hidden email] <[hidden email]>
Subject: Immediate and deferred expansion documentation rewording
 
***** EXTERNAL EMAIL *****

Hello,

I was reading section 3.7 of the GNU make online manual
(https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.gnu.org%2Fsoftware%2Fmake%2Fmanual%2Fmake.html%23Reading-Makefiles&amp;data=01%7C01%7CMartin.Dorey%40hitachivantara.com%7C23088e5bf30149cbe4bf08d74692430e%7C18791e1761594f52a8d4de814ca8284a%7C0&amp;sdata=9xFlzXF0lPcKMZSlvCMHibwHJvbF2jwlvzXPNs5%2Fxcw%3D&amp;reserved=0),
especially the second paragraph:

"It’s important to understand this two-phase approach because it has a
direct impact on how variable and function expansion happens; this is
often a source of some confusion when writing makefiles. Here we will
present a summary of the phases in which expansion happens for
different constructs within the makefile. We say that expansion is
immediate if it happens during the first phase: in this case make will
expand any variables or functions in that section of a construct as
the makefile is parsed. We say that expansion is deferred if expansion
is not performed immediately. Expansion of a deferred construct is not
performed until either the construct appears later in an immediate
context, or until the second phase."

I believe this paragraph is not worded very accurately.

In the following I will try to show how I understand some of its sentences.

First, from the following two sentences "We say that expansion is
immediate if it happens during the first phase: in this case make will
expand any variables or functions in that section of a construct as
the makefile is parsed. We say that expansion is deferred if expansion
is not performed immediately." I understand the following:

    - each cmake construct (i.e. rule, variable definition, directive
and comment) has sections (e.g. a rule has 3 sections: targets,
prerequisites and recipe)
    - text written in some of these sections will be expanded
immediately (i.e. variable and function references are expanded);
    - text written in the remaining sections is not expanded immediately

However, the next sentence, "Expansion of a deferred construct is not
performed until either the construct appears later in an immediate
context, or until the second phase.", uses a different terminology and
does not seem to be accurate. The following questions arise:

    - what is a "deferred construct"?
    - how is a "deferred construct" expanded?
    - how can a "deferred construct" appear in an immediate context?

My impression is that this sentence intends to refer to both
["recursively expanded variables"] and [recipes] as being "deferred
constructs".
First, a "recursively expanded variable" can "appear in an immediate
context" (e.g. in the value of a "simply expanded variable"), however
it is not expanded during the second phase.
Furthermore, a deferred section of a rule (i.e. the recipe) is
expanded during the second phase, however it cannot "appear in an
immediate context".

As a conclusion, I think that the last sentence of the quoted
paragraph from section 3.7 uses the word "construct" to refer to both
"recursively expanded variables" and "recipes" (a completely different
meaning than the one used in the previous sentences) and it specifies
two situations when they are expanded (however one situations
appertains only to "recursively expanded variables" and the other only
to "recipes").

Am I misunderstanding something or is this paragraph wrong?


Thank you,
Razvan Maris

_______________________________________________
Bug-make mailing list
[hidden email]
https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Flists.gnu.org%2Fmailman%2Flistinfo%2Fbug-make&amp;data=01%7C01%7CMartin.Dorey%40hitachivantara.com%7C23088e5bf30149cbe4bf08d74692430e%7C18791e1761594f52a8d4de814ca8284a%7C0&amp;sdata=XupR6cKdUacRiRPKJqKaHn2RmdeaXMjEypqVTEJAco4%3D&amp;reserved=0

_______________________________________________
Bug-make mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/bug-make
Reply | Threaded
Open this post in threaded view
|

Re: Immediate and deferred expansion documentation rewording

Maris Razvan
Thank you for your answer. I have some follow-up questions.

>
> >  I understand the following
>
> Apart from the word "cmake", that chimed with my understanding.
>
> > a completely different meaning than the one used in the previous sentences
>
> I think the meanings are consistent if "a section of a construct" is itself a "construct".

Does this mean that the value in the definition of a recursively
expanded variable is considered to be a "construct", therefore it can
also be regarded as a "deferred construct"?

>
> > however one situations
> > appertains only to "recursively expanded variables" and the other only
> > to "recipes"
>
> Right, but I don't see that this lack of precision makes the prose inaccurate.  I bet you could smith a couple of replacement sentences that I for one would find precise, accurate and clear.
>
> While you're there, it isn't the value of the recursively expanded variable that appears in an immediate context, but a reference to the name of the variable.
>

This issue is related to my previous question. If the "deferred
construct" in the definition of a recursively expanded variable is the
value (not the variable itself, as I presumed in my original
question), how can that value "appear in an immediate context"?

_______________________________________________
Bug-make mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/bug-make
Reply | Threaded
Open this post in threaded view
|

Re: Immediate and deferred expansion documentation rewording

Martin Dorey-2
> the value in the definition of a recursively
> expanded variable is considered to be a "construct", therefore it can
> also be regarded as a "deferred construct"?

Yes.  I think it's useful to consider:

nam = exp

... as a construct of at least two sections, because nam is immediately evaluated, while the evaluation of exp is deferred.

how can that value "appear in an immediate context"?

It can't: that was my point in the last sentence of my previous post.  Given:

nam = exp

It's when $(nam) appears in an immediate context that exp gets evaluated.  exp needn't itself appear again.


From: Maris Razvan <[hidden email]>
Sent: Tuesday, October 1, 2019 13:19
To: Martin Dorey <[hidden email]>
Cc: [hidden email] <[hidden email]>
Subject: Re: Immediate and deferred expansion documentation rewording
 
***** EXTERNAL EMAIL *****

Thank you for your answer. I have some follow-up questions.

>
> >  I understand the following
>
> Apart from the word "cmake", that chimed with my understanding.
>
> > a completely different meaning than the one used in the previous sentences
>
> I think the meanings are consistent if "a section of a construct" is itself a "construct".

Does this mean that the value in the definition of a recursively
expanded variable is considered to be a "construct", therefore it can
also be regarded as a "deferred construct"?

>
> > however one situations
> > appertains only to "recursively expanded variables" and the other only
> > to "recipes"
>
> Right, but I don't see that this lack of precision makes the prose inaccurate.  I bet you could smith a couple of replacement sentences that I for one would find precise, accurate and clear.
>
> While you're there, it isn't the value of the recursively expanded variable that appears in an immediate context, but a reference to the name of the variable.
>

This issue is related to my previous question. If the "deferred
construct" in the definition of a recursively expanded variable is the
value (not the variable itself, as I presumed in my original
question), how can that value "appear in an immediate context"?

_______________________________________________
Bug-make mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/bug-make
Reply | Threaded
Open this post in threaded view
|

Re: Immediate and deferred expansion documentation rewording

Maris Razvan
>
> > the value in the definition of a recursively
> > expanded variable is considered to be a "construct", therefore it can
> > also be regarded as a "deferred construct"?
>
> Yes.  I think it's useful to consider:
>
> nam = exp
>
> ... as a construct of at least two sections, because nam is immediately evaluated, while the evaluation of exp is deferred.

As in my original question, I agree that the documentation implies
that constructs contain sections, some of which are immediately
expanded, while others have a deferred expansion. However I do not
think the documentation intends for these sections to be also regarded
as "constructs" (I believe the term "constructs" refers only to the
top-level components of a makefile: rules, variable definitions,
directives and comments).

> > how can that value "appear in an immediate context"?
>
> It can't: that was my point in the last sentence of my previous post.  Given:
>
> nam = exp
>
> It's when $(nam) appears in an immediate context that exp gets evaluated.  exp needn't itself appear again.

But if one considers the value in a recursively expanded variable to
be a "deferred construct", this type of "deferred construct" cannot
"appear in an immediate context", as you said, therefore the wording
from the manual: "Expansion of a deferred construct is not performed
until either the construct appears later in an immediate context" is
wrong, as there are no "deferred constructs" that can appear in an
immediate context.

However, if the documentation intended for a recursively expanded
variable (the variable as an entity, not some part of the parse tree)
to be considered a "deferred construct", then this "deferred
construct" can appear in an immediate context (it can be referenced,
and its expansion would mean the expansion of the value specified in
its definition). However, this meaning of "construct" does not match
the meaning of "construct" used in the previous sentences.

Either way the term "deferred construct" is interpreted, I still
believe that this paragraph is not clear or consistent with regards to
terminology.

_______________________________________________
Bug-make mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/bug-make