Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs on special method evaluation #4665

Merged
merged 2 commits into from
Dec 29, 2024
Merged

Update docs on special method evaluation #4665

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3ee18c0
Update docs on special method evaluation
mwichmann Dec 13, 2024
d6f0887
Fix a review comments on special methods [skip appveyor]
mwichmann Dec 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGES.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,9 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER
and other attributes rather than indexing into stat return.
- The update-release-info test is adapted to accept changed help output
introduced in Python 3.12.8/3.13.1.
- Update the User Guide Command() example which now shows a target name
being created from '${SOURCE.base}.out' to use a valid special
attribute and to explain what's being done in the example.


RELEASE 4.8.1 - Tue, 03 Sep 2024 17:22:20 -0700
Expand Down
4 changes: 4 additions & 0 deletions RELEASE.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,10 @@ DOCUMENTATION

- Improved Variables documentation.

- Update the User Guide Command() example which now shows a target name
being created from '${SOURCE.base}.out' to use a valid special
attribute and to explain what's being done in the example.

DEVELOPMENT
-----------

Expand Down
0 ...rated/examples/builderscommands_ex5_1.xml → ...rated/examples/builderscommands_ex3_1.xml
View file
Open in desktop
File renamed without changes.
64 changes: 39 additions & 25 deletions doc/user/builders-commands.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,37 +142,49 @@ foo.in

<para>

Note that &cv-link-SOURCE; and &cv-link-TARGET; are expanded
in the source and target as well, so you can write:
&cv-link-SOURCE; and &cv-link-TARGET; are expanded
in the source and target as well:

</para>

<scons_example name="builderscommands_ex3">
<file name="SConstruct" printme="1">
env.Command('${SOURCE.basename}.out', 'foo.in', build)
</file>
</scons_example>

<para>

which does the same thing as the previous example, but allows you
to avoid repeating yourself.

</para>
<!-- NOTE: this used to be an scons_example, but was not complete and
didn't have a matching scons_output, which meant problems were not
detected. The style of this line is now reused in the last example
of the section to make sure it's actually tested
(see issue #2905 - which was closed prematurely).
-->
<sconstruct>
env.Command('${SOURCE.base}.out', File('foo.in'), build)
</sconstruct>

<para>

It may be helpful to use the <parameter>action</parameter>
keyword to specify the action, is this makes things more clear
to the reader:
Which does the same thing as the previous example, but allows you
to write a more generic rule for transforming the source filename
to the target filename, since unlike regular Builders,
&Command; does not have any built-in rules for that.

</para>

<scons_example name="builderscommands_ex4">
<file name="SConstruct" printme="1">
env.Command('${SOURCE.basename}.out', 'foo.in', action=build)
</file>
</scons_example>
<tip><para>

The example uses a <firstterm>Node special attribute</firstterm>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this only true for Command() and not true for a builder?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

problem has to do with when evaluation happens, so same for all builders.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm, I forgot DocBook actually has a <sidebar> element. However, I like the rendering of <tip> better so leaving that, but adding a title to it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So I'd consider this a bug, but of course documenting it will hopefully keep people from running into that bug.
Is there anyway to indicate this in the docs? something like "currently...., but we have an issue filed to make this work so it may be resolved at some time in the future" ?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The word "currently" does appear in the prose; I didn't intend to say more in the "friendlier" user guide. The manpage doesn't mention this problem at all (was only trying to respond to the confusion that came from someone reading the UG), but we could add something there, maybe?

(<literal>.base</literal>, the file without its suffix),
a concept which has not been introduced yet,
but will appear in several subsequent examples
(see details in the Reference Manual section
<emphasis>Substitution: Special Attributes</emphasis>).
Due to the quirks of &SCons;' deferred evaluation scheme,
node special attribues do not currently work
in source and target arguments <emphasis>if</emphasis> the
replacement is a string (like <literal>'foo.in'</literal>).
They do work fine in strings describing actions.
You can give &SCons; a little help by
manually converting the filename string to a Node
(see <xref linkend="sect-creating-nodes"/>),
which is the approach used in the example.

</para></tip>

<para>

Expand All @@ -187,11 +199,13 @@ env.Command('${SOURCE.basename}.out', 'foo.in', action=build)
which include a message based on the type of action.
However, you can also construct the &Action; object yourself
to pass to &f-Command;, which gives you much more control.
Using the <parameter>action</parameter> keyword can also help
make such lines easier to read.
Here's an evolution of the example from above showing this approach:

</para>

<scons_example name="builderscommands_ex5">
<scons_example name="builderscommands_ex3">
<file name="SConstruct" printme="1">
env = Environment()

Expand All @@ -200,7 +214,7 @@ def build(target, source, env):
return None

act = Action(build, cmdstr="Building ${TARGET}")
env.Command('foo.out', 'foo.in', action=act)
env.Command('${SOURCE.base}.out', File('foo.in'), action=act)
</file>
<file name="foo.in">
foo.in
Expand All @@ -213,7 +227,7 @@ foo.in

</para>

<scons_output example="builderscommands_ex5" suffix="1">
<scons_output example="builderscommands_ex3" suffix="1">
<scons_output_command>scons -Q</scons_output_command>
</scons_output>

Expand Down
2 changes: 1 addition & 1 deletion doc/user/environments.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1876,9 +1876,9 @@ env = Environment()
env.Command('foo', [], '__ROOT__/usr/bin/printenv.py')
</file>
<file name="__ROOT__/usr/bin/printenv.py" chmod="0o755">
#!/usr/bin/env python
bdbaddog marked this conversation as resolved.
Show resolved Hide resolved
import os
import sys

if len(sys.argv) &gt; 1:
keys = sys.argv[1:]
else:
Expand Down
14 changes: 7 additions & 7 deletions doc/user/nodes.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ This file is processed by the bin/SConsDoc.py module.

</para>

<section>
<section id="sect-builder-nodelists">
<title>Builder Methods Return Lists of Target Nodes</title>

<para>
Expand Down Expand Up @@ -150,7 +150,7 @@ int main() { printf("Goodbye, world!\n"); }

</section>

<section>
<section id="sect-creating-nodes">
<title>Explicitly Creating File and Directory Nodes</title>

<para>
Expand Down Expand Up @@ -228,7 +228,7 @@ xyzzy = Entry('xyzzy')

</section>

<section>
<section id="sect-printing-nodes">
<title>Printing &Node; File Names</title>

<para>
Expand Down Expand Up @@ -290,7 +290,7 @@ int main() { printf("Hello, world!\n"); }

</section>

<section>
<section id="sect-node-names">
<title>Using a &Node;'s File Name as a String</title>

<para>
Expand Down Expand Up @@ -337,7 +337,7 @@ int main() { printf("Hello, world!\n"); }

</section>

<section>
<section id="sect-node-paths">
<title>&GetBuildPath;: Getting the Path From a &Node; or String</title>

<para>
Expand Down Expand Up @@ -384,7 +384,7 @@ print(env.GetBuildPath([n, "sub/dir/$VAR"]))

<!--

<section>
<section id="sect-node-contents">
<title>Fetching the Contents of a &Node;</title>

<para>
Expand Down Expand Up @@ -422,7 +422,7 @@ int main() { printf("Hello, world!\n"); }

<!--

<section>
<section id="sect-value-nodes">
<title>Python Value &Node;</title>

<para>
Expand Down
Loading