summaryrefslogtreecommitdiffstats
path: root/doc/user
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/command-line.in233
-rw-r--r--doc/user/command-line.sgml237
2 files changed, 456 insertions, 14 deletions
diff --git a/doc/user/command-line.in b/doc/user/command-line.in
index 09ee8ce..9367c09 100644
--- a/doc/user/command-line.in
+++ b/doc/user/command-line.in
@@ -73,12 +73,71 @@
</section>
<section>
+ <title>Getting at Command-Line Targets</title>
+
+ <para>
+
+ &SCons; supports a &COMMAND_LINE_TARGETS; variable
+ that lets you get at the list of targets that the
+ user specified on the command line.
+ You can use the targets to manipulate the
+ build in any way you wish.
+ As a simple example,
+ suppose that you want to print a reminder
+ to the user whenever a specific program is built.
+ You can do this by checking for the
+ target in the &COMMAND_LINE_TARGETS; list:
+
+ </para>
+
+ <scons_example name="COMMAND_LINE_TARGETS">
+ <file name="SConstruct" printme="1">
+ if 'bar' in COMMAND_LINE_TARGETS:
+ print "Don't forget to copy `bar' to the archive!"
+ Default(Program('foo.c'))
+ Program('bar.c')
+ </file>
+ <file name="foo.c">
+ foo.c
+ </file>
+ <file name="bar.c">
+ foo.c
+ </file>
+ </scons_example>
+
+ <para>
+
+ Then, running &SCons; with the default target
+ works as it always does,
+ but explicity specifying the &bar; target
+ on the command line generates the warning message:
+
+ </para>
+
+ <scons_output example="COMMAND_LINE_TARGETS">
+ <command>scons -Q</command>
+ <command>scons -Q bar</command>
+ </scons_output>
+
+ <para>
+
+ Another practical use for the &COMMAND_LINE_TARGETS; variable
+ might be to speed up a build
+ by only reading certain subsidiary &SConscript;
+ files if a specific target is requested.
+
+ </para>
+
+ </section>
+
+ <section>
<title>Controlling the Default Targets</title>
<para>
One of the most basic things you can control
- is which targets &SCons; will build by default.
+ is which targets &SCons; will build by default--that is,
+ when there are no targets specified on the command line.
As mentioned previously,
&SCons; will normally build every target
in or below the current directory
@@ -276,22 +335,182 @@
<command>scons -Q .</command>
</scons_output>
- </section>
+ <section>
+ <title>Getting at the List of Default Targets</title>
+
+ <para>
+
+ &SCons; supports a &DEFAULT_TARGETS; variable
+ that lets you get at the current list of default targets.
+ The &DEFAULT_TARGETS variable has
+ two important differences from the &COMMAND_LINE_TARGETS; variable.
+ First, the &DEFAULT_TARGETS; variable is a list of
+ internal &SCons; nodes,
+ so you need to convert the list elements to strings
+ if you want to print them or look for a specific target name.
+ Fortunately, you can do this easily
+ by using the Python <function>map</function> function
+ to run the list through <function>str</function>:
- <!--
+ </para>
+
+ <scons_example name="DEFAULT_TARGETS_1">
+ <file name="SConstruct" printme="1">
+ prog1 = Program('prog1.c')
+ Default(prog1)
+ print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS)
+ </file>
+ <file name="prog1.c">
+ prog1.c
+ </file>
+ </scons_example>
+
+ <para>
+
+ (Keep in mind that all of the manipulation of the
+ &DEFAULT_TARGETS; list takes place during the
+ first phase when &SCons; is reading up the &SConscript; files,
+ which is obvious if
+ we leave off the <literal>-Q</literal> flag when we run &SCons;:)
+
+ </para>
+
+ <scons_output example="DEFAULT_TARGETS_1">
+ <command>scons</command>
+ </scons_output>
+
+ <para>
+
+ Second,
+ the contents of the &DEFAULT_TARGETS; list change
+ in response to calls to the &Default: function,
+ as you can see from the following &SConstruct; file:
+
+ </para>
+
+ <scons_example name="DEFAULT_TARGETS_2">
+ <file name="SConstruct" printme="1">
+ prog1 = Program('prog1.c')
+ Default(prog1)
+ print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
+ prog2 = Program('prog2.c')
+ Default(prog2)
+ print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
+ </file>
+ <file name="prog1.c">
+ prog1.c
+ </file>
+ <file name="prog2.c">
+ prog2.c
+ </file>
+ </scons_example>
+
+ <para>
+
+ Which yields the output:
+
+ </para>
+
+ <scons_output example="DEFAULT_TARGETS_2">
+ <command>scons</command>
+ </scons_output>
+
+ <para>
+
+ In practice, this simply means that you
+ need to pay attention to the order in
+ which you call the &Default; function
+ and refer to the &DEFAULT_TARGETS; list,
+ to make sure that you don't examine the
+ list before you've added the default targets
+ you expect to find in it.
+
+ </para>
+
+ </section>
+
+ </section>
<section>
- <title>Getting at Command-Line Targets</title>
+ <title>Getting at the List of Build Targets, Regardless of Origin</title>
<para>
- XXX
+ We've already been introduced to the
+ &COMMAND_LINE_TARGETS; variable,
+ which contains a list of targets specified on the command line,
+ and the &DEFAULT_TARGETS; variable,
+ which contains a list of targets specified
+ via calls to the &Default; method or function.
+ Sometimes, however,
+ you want a list of whatever targets
+ &SCons; will try to build,
+ regardless of whether the targets came from the
+ command line or a &Default; call.
+ You could code this up by hand, as follows:
</para>
- </section>
+ <sconstruct>
+ if COMMAND_LINE_TARGETS:
+ targets = COMMAND_LINE_TARGETS
+ else:
+ targets = DEFAULT_TARGETS
+ </sconstruct>
- -->
+ <para>
+
+ &SCons;, however, provides a convenient
+ &BUILD_TARGETS; variable
+ that eliminates the need for this by-hand manipulation.
+ Essentially, the &BUILD_TARGETS; variable
+ contains a list of the command-line targets,
+ if any were specified,
+ and if no command-line targets were specified,
+ it contains a list of the targets specified
+ via the &Default; method or function.
+
+ </para>
+
+ <para>
+
+ Because &BUILD_TARGETS; may contain a list of &SCons; nodes,
+ you must convert the list elements to strings
+ if you want to print them or look for a specific target name,
+ just like the &DEFAULT_TARGETS; list:
+
+ </para>
+
+ <scons_example name="BUILD_TARGETS_1">
+ <file name="SConstruct" printme="1">
+ prog1 = Program('prog1.c')
+ Program('prog2.c')
+ Default(prog1)
+ print "BUILD_TARGETS is", map(str, BUILD_TARGETS)
+ </file>
+ <file name="prog1.c">
+ prog1.c
+ </file>
+ <file name="prog2.c">
+ prog2.c
+ </file>
+ </scons_example>
+
+ <para>
+
+ Notice how the value of &BUILD_TARGETS;
+ changes depending on whether a target is
+ specified on the command line:
+
+ </para>
+
+ <scons_output example="BUILD_TARGETS_1">
+ <command>scons -Q</command>
+ <command>scons -Q prog2</command>
+ <command>scons -Q -c .</command>
+ </scons_output>
+
+ </section>
<section>
<title>Command-Line <varname>variable</varname>=<varname>value</varname> Build Options</title>
diff --git a/doc/user/command-line.sgml b/doc/user/command-line.sgml
index 3377b69..f6f219c 100644
--- a/doc/user/command-line.sgml
+++ b/doc/user/command-line.sgml
@@ -72,12 +72,68 @@
</section>
<section>
+ <title>Getting at Command-Line Targets</title>
+
+ <para>
+
+ &SCons; supports a &COMMAND_LINE_TARGETS; variable
+ that lets you get at the list of targets that the
+ user specified on the command line.
+ You can use the targets to manipulate the
+ build in any way you wish.
+ As a simple example,
+ suppose that you want to print a reminder
+ to the user whenever a specific program is built.
+ You can do this by checking for the
+ target in the &COMMAND_LINE_TARGETS; list:
+
+ </para>
+
+ <programlisting>
+ if 'bar' in COMMAND_LINE_TARGETS:
+ print "Don't forget to copy `bar' to the archive!"
+ Default(Program('foo.c'))
+ Program('bar.c')
+ </programlisting>
+
+ <para>
+
+ Then, running &SCons; with the default target
+ works as it always does,
+ but explicity specifying the &bar; target
+ on the command line generates the warning message:
+
+ </para>
+
+ <literallayout>
+ % <userinput>scons -Q</userinput>
+ cc -c -o foo.o foo.c
+ cc -o foo foo.o
+ % <userinput>scons -Q bar</userinput>
+ Don't forget to copy `bar' to the archive!
+ cc -c -o bar.o bar.c
+ cc -o bar bar.o
+ </literallayout>
+
+ <para>
+
+ Another practical use for the &COMMAND_LINE_TARGETS; variable
+ might be to speed up a build
+ by only reading certain subsidiary &SConscript;
+ files if a specific target is requested.
+
+ </para>
+
+ </section>
+
+ <section>
<title>Controlling the Default Targets</title>
<para>
One of the most basic things you can control
- is which targets &SCons; will build by default.
+ is which targets &SCons; will build by default--that is,
+ when there are no targets specified on the command line.
As mentioned previously,
&SCons; will normally build every target
in or below the current directory
@@ -259,22 +315,189 @@
cc -o prog2 prog2.o
</literallayout>
- </section>
+ <section>
+ <title>Getting at the List of Default Targets</title>
+
+ <para>
+
+ &SCons; supports a &DEFAULT_TARGETS; variable
+ that lets you get at the current list of default targets.
+ The &DEFAULT_TARGETS variable has
+ two important differences from the &COMMAND_LINE_TARGETS; variable.
+ First, the &DEFAULT_TARGETS; variable is a list of
+ internal &SCons; nodes,
+ so you need to convert the list elements to strings
+ if you want to print them or look for a specific target name.
+ Fortunately, you can do this easily
+ by using the Python <function>map</function> function
+ to run the list through <function>str</function>:
+
+ </para>
+
+ <programlisting>
+ prog1 = Program('prog1.c')
+ Default(prog1)
+ print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS)
+ </programlisting>
- <!--
+ <para>
+
+ (Keep in mind that all of the manipulation of the
+ &DEFAULT_TARGETS; list takes place during the
+ first phase when &SCons; is reading up the &SConscript; files,
+ which is obvious if
+ we leave off the <literal>-Q</literal> flag when we run &SCons;:)
+
+ </para>
+
+ <literallayout>
+ % <userinput>scons</userinput>
+ scons: Reading SConscript files ...
+ DEFAULT_TARGETS is ['prog1']
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ cc -c -o prog1.o prog1.c
+ cc -o prog1 prog1.o
+ scons: done building targets.
+ </literallayout>
+
+ <para>
+
+ Second,
+ the contents of the &DEFAULT_TARGETS; list change
+ in response to calls to the &Default;: function,
+ as you can see from the following &SConstruct; file:
+
+ </para>
+
+ <programlisting>
+ prog1 = Program('prog1.c')
+ Default(prog1)
+ print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
+ prog2 = Program('prog2.c')
+ Default(prog2)
+ print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
+ </programlisting>
+
+ <para>
+
+ Which yields the output:
+
+ </para>
+
+ <literallayout>
+ % <userinput>scons</userinput>
+ scons: Reading SConscript files ...
+ DEFAULT_TARGETS is now ['prog1']
+ DEFAULT_TARGETS is now ['prog1', 'prog2']
+ scons: done reading SConscript files.
+ scons: Building targets ...
+ cc -c -o prog1.o prog1.c
+ cc -o prog1 prog1.o
+ cc -c -o prog2.o prog2.c
+ cc -o prog2 prog2.o
+ scons: done building targets.
+ </literallayout>
+
+ <para>
+
+ In practice, this simply means that you
+ need to pay attention to the order in
+ which you call the &Default; function
+ and refer to the &DEFAULT_TARGETS; list,
+ to make sure that you don't examine the
+ list before you've added the default targets
+ you expect to find in it.
+
+ </para>
+
+ </section>
+
+ </section>
<section>
- <title>Getting at Command-Line Targets</title>
+ <title>Getting at the List of Build Targets, Regardless of Origin</title>
<para>
- XXX
+ We've already been introduced to the
+ &COMMAND_LINE_TARGETS; variable,
+ which contains a list of targets specified on the command line,
+ and the &DEFAULT_TARGETS; variable,
+ which contains a list of targets specified
+ via calls to the &Default; method or function.
+ Sometimes, however,
+ you want a list of whatever targets
+ &SCons; will try to build,
+ regardless of whether the targets came from the
+ command line or a &Default; call.
+ You could code this up by hand, as follows:
</para>
- </section>
+ <programlisting>
+ if COMMAND_LINE_TARGETS:
+ targets = COMMAND_LINE_TARGETS
+ else:
+ targets = DEFAULT_TARGETS
+ </programlisting>
+
+ <para>
+
+ &SCons;, however, provides a convenient
+ &BUILD_TARGETS; variable
+ that eliminates the need for this by-hand manipulation.
+ Essentially, the &BUILD_TARGETS; variable
+ contains a list of the command-line targets,
+ if any were specified,
+ and if no command-line targets were specified,
+ it contains a list of the targets specified
+ via the &Default; method or function.
+
+ </para>
+
+ <para>
+
+ Because &BUILD_TARGETS; may contain a list of &SCons; nodes,
+ you must convert the list elements to strings
+ if you want to print them or look for a specific target name,
+ just like the &DEFAULT_TARGETS; list:
+
+ </para>
+
+ <programlisting>
+ prog1 = Program('prog1.c')
+ Program('prog2.c')
+ Default(prog1)
+ print "BUILD_TARGETS is", map(str, BUILD_TARGETS)
+ </programlisting>
+
+ <para>
+
+ Notice how the value of &BUILD_TARGETS;
+ changes depending on whether a target is
+ specified on the command line:
+
+ </para>
+
+ <literallayout>
+ % <userinput>scons -Q</userinput>
+ BUILD_TARGETS is ['prog1']
+ cc -c -o prog1.o prog1.c
+ cc -o prog1 prog1.o
+ % <userinput>scons -Q prog2</userinput>
+ BUILD_TARGETS is ['prog2']
+ cc -c -o prog2.o prog2.c
+ cc -o prog2 prog2.o
+ % <userinput>scons -Q -c .</userinput>
+ BUILD_TARGETS is ['.']
+ Removed prog1.o
+ Removed prog1
+ Removed prog2.o
+ Removed prog2
+ </literallayout>
- -->
+ </section>
<section>
<title>Command-Line <varname>variable</varname>=<varname>value</varname> Build Options</title>