5 Permission is hereby granted, free of charge, to any person obtaining
6 a copy of this software and associated documentation files (the
7 "Software"), to deal in the Software without restriction, including
8 without limitation the rights to use, copy, modify, merge, publish,
9 distribute, sublicense, and/or sell copies of the Software, and to
10 permit persons to whom the Software is furnished to do so, subject to
11 the following conditions:
13 The above copyright notice and this permission notice shall be included
14 in all copies or substantial portions of the Software.
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
17 KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
18 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
28 &SCons; provides a number of ways
29 for the writer of the &SConscript; files
30 to give the users who will run &SCons;
31 a great deal of control over the build execution.
32 The arguments that the user can specify on
33 the command line are broken down into three types:
45 Command-line options always begin with
46 one or two <literal>-</literal> (hyphen) characters.
47 &SCons; provides ways for you to examine
48 and set options values from within your &SConscript; files,
49 as well as the ability to define your own
51 See <xref linkend="sect-command-line-options"></xref>, below.
58 <term>Variables</term>
63 Any command-line argument containing an <literal>=</literal>
64 (equal sign) is considered a variable setting with the form
65 <varname>variable</varname>=<varname>value</varname>
66 &SCons; provides direct access to
67 all of the command-line variable settings,
68 the ability to apply command-line variable settings
69 to construction environments,
70 and functions for configuring
71 specific types of variables
72 (Boolean values, path names, etc.)
73 with automatic validation of the user's specified values.
74 See <xref linkend="sect-command-line-variables"></xref>, below.
86 Any command-line argument that is not an option
88 (does not begin with a hyphen
89 and does not contain an equal sign)
90 is considered a target that the user
91 (presumably) wants &SCons; to build.
92 A list of Node objects representing
93 the target or targets to build.
94 &SCons; provides access to the list of specified targets,
95 as well as ways to set the default list of targets
96 from within the &SConscript; files.
97 See <xref linkend="sect-command-line-targets"></xref>, below.
105 <section id="sect-command-line-options">
106 <title>Command-Line Options</title>
110 &SCons; has many <emphasis>command-line options</emphasis>
111 that control its behavior.
112 A &SCons; <emphasis>command-line option</emphasis>
113 always begins with one or two <literal>-</literal> (hyphen)
119 <title>Not Having to Specify Command-Line Options Each Time: the &SCONSFLAGS; Environment Variable</title>
123 Users may find themselves supplying
124 the same command-line options every time
126 For example, you might find it saves time
127 to specify a value of <literal>-j 2</literal>
128 to have &SCons; run up to two build commands in parallel.
129 To avoid having to type <literal>-j 2</literal> by hand
131 you can set the external environment variable
132 &SCONSFLAGS; to a string containing
133 command-line options that you want &SCons; to use.
140 you're using a POSIX shell that's
141 compatible with the Bourne shell,
142 and you always want &SCons; to use the
143 <literal>-Q</literal> option,
144 you can set the &SCONSFLAGS;
145 environment as follows:
152 % <userinput>scons</userinput>
153 scons: Reading SConscript files ...
154 scons: done reading SConscript files.
155 scons: Building targets ...
156 ... [build output] ...
157 scons: done building targets.
158 % <userinput>export SCONSFLAGS="-Q"</userinput>
159 % <userinput>scons</userinput>
160 ... [build output] ...
165 Users of &csh;-style shells on POSIX systems
166 can set the &SCONSFLAGS; environment as follows:
171 $ <userinput>setenv SCONSFLAGS "-Q"</userinput>
176 Windows users may typically want to set the
177 &SCONSFLAGS; in the appropriate tab of the
178 <literal>System Properties</literal> window.
185 <title>Getting Values Set by Command-Line Options: the &GetOption; Function</title>
189 &SCons; provides the &GetOption; function
190 to get the values set by the various command-line options.
191 One common use of this is to check whether or not
192 the <literal>-h</literal> or <literal>--help</literal> option
194 Normally, &SCons; does not print its help text
195 until after it has read all of the &SConscript; files,
196 because it's possible that help text has been added
197 by some subsidiary &SConscript; file deep in the
198 source tree hierarchy.
199 Of course, reading all of the &SConscript; files
206 If you know that your configuration does not define
207 any additional help text in subsidiary &SConscript; files,
208 you can speed up the command-line help available to users
209 by using the &GetOption; function to load the
210 subsidiary &SConscript; files only if the
211 the user has <emphasis>not</emphasis> specified
212 the <literal>-h</literal> or <literal>--help</literal> option,
217 <programlisting></programlisting>
221 In general, the string that you pass to the
222 &GetOption; function to fetch the value of a command-line
223 option setting is the same as the "most common" long option name
224 (beginning with two hyphen characters),
225 although there are some exceptions.
226 The list of &SCons; command-line options
227 and the &GetOption; strings for fetching them,
229 <xref linkend="sect-command-line-option-strings"></xref> section,
237 <title>Setting Values of Command-Line Options: the &SetOption; Function</title>
241 You can also set the values of &SCons;
242 command-line options from within the &SConscript; files
243 by using the &SetOption; function.
244 The strings that you use to set the values of &SCons;
245 command-line options are available in the
246 <xref linkend="sect-command-line-option-strings"></xref> section,
253 One use of the &SetOption; function is to
254 specify a value for the <literal>-j</literal>
255 or <literal>--jobs</literal> option,
256 so that users get the improved performance
257 of a parallel build without having to specify the option by hand.
258 A complicating factor is that a good value
259 for the <literal>-j</literal> option is
260 somewhat system-dependent.
261 One rough guideline is that the more processors
263 the higher you want to set the
264 <literal>-j</literal> value,
265 in order to take advantage of the number of CPUs.
271 For example, suppose the administrators
272 of your development systems
273 have standardized on setting a
274 <varname>NUM_CPU</varname> environment variable
275 to the number of processors on each system.
276 A little bit of Python code
277 to access the environment variable
278 and the &SetOption; function
279 provide the right level of flexibility:
285 num_cpu = int(os.environ.get('NUM_CPU', 2))
286 SetOption('num_jobs', num_cpu)
287 print "running with -j", GetOption('num_jobs')
292 The above snippet of code
293 sets the value of the <literal>--jobs</literal> option
294 to the value specified in the
295 <varname>$NUM_CPU</varname> environment variable.
296 (This is one of the exception cases
297 where the string is spelled differently from
298 the from command-line option.
299 The string for fetching or setting the <literal>--jobs</literal>
300 value is <literal>num_jobs</literal>
301 for historical reasons.)
302 The code in this example prints the <literal>num_jobs</literal>
303 value for illustrative purposes.
304 It uses a default value of <literal>2</literal>
305 to provide some minimal parallelism even on
306 single-processor systems:
311 % <userinput>scons -Q</userinput>
313 scons: `.' is up to date.
318 But if the <varname>$NUM_CPU</varname>
319 environment variable is set,
320 then we use that for the default number of jobs:
325 % <userinput>export NUM_CPU="4"</userinput>
326 % <userinput>scons -Q</userinput>
328 scons: `.' is up to date.
334 <literal>-j</literal> or <literal>--jobs</literal>
335 value the user specifies an the command line is used first,
336 regardless of whether or not
337 the <varname>$NUM_CPU</varname> environment
343 % <userinput>scons -Q -j 7</userinput>
345 scons: `.' is up to date.
346 % <userinput>export NUM_CPU="4"</userinput>
347 % <userinput>scons -Q -j 3</userinput>
349 scons: `.' is up to date.
354 <section id="sect-command-line-option-strings">
355 <title>Strings for Getting or Setting Values of &SCons; Command-Line Options</title>
359 The strings that you can pass to the &GetOption;
360 and &SetOption; functions usually correspond to the
361 first long-form option name
362 (beginning with two hyphen characters: <literal>--</literal>),
363 after replacing any remaining hyphen characters
370 The full list of strings and the variables they
371 correspond to is as follows:
376 <tgroup cols="2" align="left">
381 <entry>String for &GetOption; and &SetOption;</entry>
382 <entry>Command-Line Option(s)</entry>
390 <entry><literal>cache_debug</literal></entry>
391 <entry><option>--cache-debug</option></entry>
395 <entry><literal>cache_disable</literal></entry>
396 <entry><option>--cache-disable</option></entry>
400 <entry><literal>cache_force</literal></entry>
401 <entry><option>--cache-force</option></entry>
405 <entry><literal>cache_show</literal></entry>
406 <entry><option>--cache-show</option></entry>
410 <entry><literal>clean</literal></entry>
411 <entry><option>-c</option>,
412 <option>--clean</option>,
413 <option>--remove</option></entry>
417 <entry><literal>config</literal></entry>
418 <entry><option>--config</option></entry>
422 <entry><literal>directory</literal></entry>
423 <entry><option>-C</option>,
424 <option>--directory</option></entry>
428 <entry><literal>diskcheck</literal></entry>
429 <entry><option>--diskcheck</option></entry>
433 <entry><literal>duplicate</literal></entry>
434 <entry><option>--duplicate</option></entry>
438 <entry><literal>file</literal></entry>
439 <entry><option>-f</option>,
440 <option>--file</option>,
441 <option>--makefile </option>,
442 <option>--sconstruct</option></entry>
446 <entry><literal>help</literal></entry>
447 <entry><option>-h</option>,
448 <option>--help</option></entry>
452 <entry><literal>ignore_errors</literal></entry>
453 <entry><option>--ignore-errors</option></entry>
457 <entry><literal>implicit_cache</literal></entry>
458 <entry><option>--implicit-cache</option></entry>
462 <entry><literal>implicit_deps_changed</literal></entry>
463 <entry><option>--implicit-deps-changed</option></entry>
467 <entry><literal>implicit_deps_unchanged</literal></entry>
468 <entry><option>--implicit-deps-unchanged</option></entry>
472 <entry><literal>interactive</literal></entry>
473 <entry><option>--interact</option>,
474 <option>--interactive</option></entry>
478 <entry><literal>keep_going</literal></entry>
479 <entry><option>-k</option>,
480 <option>--keep-going</option></entry>
484 <entry><literal>max_drift</literal></entry>
485 <entry><option>--max-drift</option></entry>
489 <entry><literal>no_exec</literal></entry>
490 <entry><option>-n</option>,
491 <option>--no-exec</option>,
492 <option>--just-print</option>,
493 <option>--dry-run</option>,
494 <option>--recon</option></entry>
498 <entry><literal>no_site_dir</literal></entry>
499 <entry><option>--no-site-dir</option></entry>
503 <entry><literal>num_jobs</literal></entry>
504 <entry><option>-j</option>,
505 <option>--jobs</option></entry>
509 <entry><literal>profile_file</literal></entry>
510 <entry><option>--profile</option></entry>
514 <entry><literal>question</literal></entry>
515 <entry><option>-q</option>,
516 <option>--question</option></entry>
520 <entry><literal>random</literal></entry>
521 <entry><option>--random</option></entry>
525 <entry><literal>repository</literal></entry>
526 <entry><option>-Y</option>,
527 <option>--repository</option>,
528 <option>--srcdir</option></entry>
532 <entry><literal>silent</literal></entry>
533 <entry><option>-s</option>,
534 <option>--silent</option>,
535 <option>--quiet</option></entry>
539 <entry><literal>site_dir</literal></entry>
540 <entry><option>--site-dir</option></entry>
544 <entry><literal>stack_size</literal></entry>
545 <entry><option>--stack-size</option></entry>
549 <entry><literal>taskmastertrace_file</literal></entry>
550 <entry><option>--taskmastertrace</option></entry>
554 <entry><literal>warn</literal></entry>
555 <entry><option>--warn</option> <option>--warning</option></entry>
566 <title>Adding Custom Command-Line Options: the &AddOption; Function</title>
570 &SCons; also allows you to define your own
571 command-line options with the &AddOption; function.
572 The &AddOption; function takes the same arguments
573 as the <function>optparse.add_option</function> function
574 from the standard Python library.
577 The &AddOption; function is,
578 in fact, implemented using a subclass
579 of the <classname>optparse.OptionParser</classname>.
582 Once you have added a custom command-line option
583 with the &AddOption; function,
584 the value of the option (if any) is immediately available
585 using the standard &GetOption; function.
586 (The value can also be set using &SetOption;,
587 although that's not very useful in practice
588 because a default value can be specified in
589 directly in the &AddOption; call.)
595 One useful example of using this functionality
596 is to provide a <option>--prefix</option> for users:
601 AddOption('--prefix',
607 help='installation prefix')
609 env = Environment(PREFIX = GetOption('prefix'))
611 installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in')
612 Default(installed_foo)
617 The above code uses the &GetOption; function
618 to set the <varname>$PREFIX</varname>
619 construction variable to any
620 value that the user specifies with a command-line
621 option of <literal>--prefix</literal>.
622 Because <varname>$PREFIX</varname>
623 will expand to a null string if it's not initialized,
624 running &SCons; without the
625 option of <literal>--prefix</literal>
626 will install the file in the
627 <filename>/usr/bin/</filename> directory:
632 % <userinput>scons -Q -n</userinput>
633 Install file: "foo.in" as "/usr/bin/foo.in"
638 But specifying <literal>--prefix=/tmp/install</literal>
639 on the command line causes the file to be installed in the
640 <filename>/tmp/install/usr/bin/</filename> directory:
645 % <userinput>scons -Q -n --prefix=/tmp/install</userinput>
646 Install file: "foo.in" as "/tmp/install/usr/bin/foo.in"
653 <section id="sect-command-line-variables">
654 <title>Command-Line <varname>variable</varname>=<varname>value</varname> Build Variables</title>
658 You may want to control various aspects
659 of your build by allowing the user
660 to specify <varname>variable</varname>=<varname>value</varname>
661 values on the command line.
662 For example, suppose you
663 want users to be able to
664 build a debug version of a program
665 by running &SCons; as follows:
670 % <userinput>scons -Q debug=1</userinput>
675 &SCons; provides an &ARGUMENTS; dictionary
676 that stores all of the
677 <varname>variable</varname>=<varname>value</varname>
678 assignments from the command line.
679 This allows you to modify
680 aspects of your build in response
681 to specifications on the command line.
682 (Note that unless you want to require
683 that users <emphasis>always</emphasis>
685 you probably want to use
687 <literal>ARGUMENTS.get()</literal> function,
688 which allows you to specify a default value
689 to be used if there is no specification
690 on the command line.)
696 The following code sets the &cv-link-CCFLAGS; construction
697 variable in response to the <varname>debug</varname>
698 flag being set in the &ARGUMENTS; dictionary:
704 debug = ARGUMENTS.get('debug', 0)
706 env.Append(CCFLAGS = '-g')
707 env.Program('prog.c')
712 This results in the <varname>-g</varname>
713 compiler option being used when
714 <literal>debug=1</literal>
715 is used on the command line:
720 % <userinput>scons -Q debug=0</userinput>
721 cc -o prog.o -c prog.c
723 % <userinput>scons -Q debug=0</userinput>
724 scons: `.' is up to date.
725 % <userinput>scons -Q debug=1</userinput>
726 cc -o prog.o -c -g prog.c
728 % <userinput>scons -Q debug=1</userinput>
729 scons: `.' is up to date.
734 Notice that &SCons; keeps track of
735 the last values used to build the object files,
736 and as a result correctly rebuilds
737 the object and executable files
738 only when the value of the <literal>debug</literal>
739 argument has changed.
745 The &ARGUMENTS; dictionary has two minor drawbacks.
746 First, because it is a dictionary,
747 it can only store one value for each specified keyword,
748 and thus only "remembers" the last setting
749 for each keyword on the command line.
750 This makes the &ARGUMENTS; dictionary
751 inappropriate if users should be able to
752 specify multiple values
753 on the command line for a given keyword.
754 Second, it does not preserve
755 the order in which the variable settings
757 which is a problem if
758 you want the configuration to
759 behave differently in response
760 to the order in which the build
761 variable settings were specified on the command line.
767 To accomodate these requirements,
768 &SCons; provides an &ARGLIST; variable
769 that gives you direct access to
770 <varname>variable</varname>=<varname>value</varname>
771 settings on the command line,
772 in the exact order they were specified,
773 and without removing any duplicate settings.
774 Each element in the &ARGLIST; variable
775 is itself a two-element list
776 containing the keyword and the value
778 and you must loop through,
779 or otherwise select from,
780 the elements of &ARGLIST; to
781 process the specific settings you want
782 in whatever way is appropriate for your configuration.
784 the following code to let the user
785 add to the &CPPDEFINES; construction variable
786 by specifying multiple
787 <varname>define=</varname>
788 settings on the command line:
794 for key, value in ARGLIST:
796 cppdefines.append(value)
797 env = Environment(CPPDEFINES = cppdefines)
803 Yields the following output:
808 % <userinput>scons -Q define=FOO</userinput>
809 cc -o prog.o -c -DFOO prog.c
810 % <userinput>scons -Q define=FOO define=BAR</userinput>
811 cc -o prog.o -c -DFOO -DBAR prog.c
816 Note that the &ARGLIST; and &ARGUMENTS;
817 variables do not interfere with each other,
818 but merely provide slightly different views
819 into how the user specified
820 <varname>variable</varname>=<varname>value</varname>
821 settings on the command line.
822 You can use both variables in the same
823 &SCons; configuration.
824 In general, the &ARGUMENTS; dictionary
825 is more convenient to use,
826 (since you can just fetch variable
827 settings through a dictionary access),
828 and the &ARGLIST; list
830 (since you can examine the
831 specific order in which
832 the user's command-line variabe settings).
837 <title>Controlling Command-Line Build Variables</title>
841 Being able to use a command-line build variable like
842 <literal>debug=1</literal> is handy,
843 but it can be a chore to write specific Python code
844 to recognize each such variable,
845 check for errors and provide appropriate messages,
846 and apply the values to a construction variable.
848 &SCons; supports a class to
849 define such build variables easily,
850 and a mechanism to apply the
851 build variables to a construction environment.
852 This allows you to control how the build variables affect
853 construction environments.
859 For example, suppose that you want users to set
860 a &RELEASE; construction variable on the
861 command line whenever the time comes to build
862 a program for release,
863 and that the value of this variable
864 should be added to the command line
865 with the appropriate <literal>-D</literal> option
866 (or other command line option)
867 to pass the value to the C compiler.
868 Here's how you might do that by setting
869 the appropriate value in a dictionary for the
870 &cv-link-CPPDEFINES; construction variable:
876 vars.Add('RELEASE', 'Set to 1 to build for release', 0)
877 env = Environment(variables = vars,
878 CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
879 env.Program(['foo.c', 'bar.c'])
884 This &SConstruct; file first creates a &Variables; object
885 (the <literal>vars = Variables()</literal> call),
886 and then uses the object's &Add;
887 method to indicate that the &RELEASE;
888 variable can be set on the command line,
889 and that its default value will be <literal>0</literal>
890 (the third argument to the &Add; method).
891 The second argument is a line of help text;
892 we'll learn how to use it in the next section.
898 We then pass the created &Variables;
899 object as a &variables; keyword argument
900 to the &Environment; call
901 used to create the construction environment.
902 This then allows a user to set the
903 &RELEASE; build variable on the command line
904 and have the variable show up in
905 the command line used to build each object from
911 % <userinput>scons -Q RELEASE=1</userinput>
912 cc -o bar.o -c -DRELEASE_BUILD=1 bar.c
913 cc -o foo.o -c -DRELEASE_BUILD=1 foo.c
914 cc -o foo foo.o bar.o
919 NOTE: Before &SCons; release 0.98.1, these build variables
920 were known as "command-line build options."
921 The class was actually named the &Options; class,
922 and in the sections below,
923 the various functions were named
924 &BoolOption;, &EnumOption;, &ListOption;,
925 &PathOption;, &PackageOption; and &AddOptions;.
926 These older names still work,
927 and you may encounter them in older
929 but their use is discouraged
930 and will be officially deprecated some day.
937 <title>Providing Help for Command-Line Build Variables</title>
941 To make command-line build variables most useful,
942 you ideally want to provide
943 some help text that will describe
944 the available variables
945 when the user runs <literal>scons -h</literal>.
946 You could write this text by hand,
947 but &SCons; provides an easier way.
948 &Variables; objects support a
949 &GenerateHelpText; method
950 that will, as its name suggests,
951 generate text that describes
952 the various variables that
953 have been added to it.
954 You then pass the output from this method to
960 vars = Variables('custom.py')
961 vars.Add('RELEASE', 'Set to 1 to build for release', 0)
962 env = Environment(variables = vars)
963 Help(vars.GenerateHelpText(env))
968 &SCons; will now display some useful text
969 when the <literal>-h</literal> option is used:
974 % <userinput>scons -Q -h</userinput>
976 RELEASE: Set to 1 to build for release
980 Use scons -H for help about command-line options.
985 Notice that the help output shows the default value,
986 and the current actual value of the build variable.
993 <title>Reading Build Variables From a File</title>
997 Giving the user a way to specify the
998 value of a build variable on the command line
1000 but can still be tedious
1001 if users must specify the variable
1002 every time they run &SCons;.
1003 We can let users provide customized build variable settings
1004 in a local file by providing a
1005 file name when we create the
1011 vars = Variables('custom.py')
1012 vars.Add('RELEASE', 'Set to 1 to build for release', 0)
1013 env = Environment(variables = vars,
1014 CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
1015 env.Program(['foo.c', 'bar.c'])
1016 Help(vars.GenerateHelpText(env))
1021 This then allows the user to control the &RELEASE;
1022 variable by setting it in the &custom_py; file:
1032 Note that this file is actually executed
1033 like a Python script.
1034 Now when we run &SCons;:
1039 % <userinput>scons -Q</userinput>
1040 cc -o bar.o -c -DRELEASE_BUILD=1 bar.c
1041 cc -o foo.o -c -DRELEASE_BUILD=1 foo.c
1042 cc -o foo foo.o bar.o
1047 And if we change the contents of &custom_py; to:
1057 The object files are rebuilt appropriately
1058 with the new variable:
1063 % <userinput>scons -Q</userinput>
1064 cc -o bar.o -c -DRELEASE_BUILD=0 bar.c
1065 cc -o foo.o -c -DRELEASE_BUILD=0 foo.c
1066 cc -o foo foo.o bar.o
1072 <title>Pre-Defined Build Variable Functions</title>
1076 &SCons; provides a number of functions
1077 that provide ready-made behaviors
1078 for various types of command-line build variables.
1083 <title>True/False Values: the &BoolVariable; Build Variable Function</title>
1087 It's often handy to be able to specify a
1088 variable that controls a simple Boolean variable
1089 with a &true; or &false; value.
1090 It would be even more handy to accomodate
1091 users who have different preferences for how to represent
1092 &true; or &false; values.
1093 The &BoolVariable; function
1094 makes it easy to accomodate these
1095 common representations of
1102 The &BoolVariable; function takes three arguments:
1103 the name of the build variable,
1104 the default value of the build variable,
1105 and the help string for the variable.
1106 It then returns appropriate information for
1107 passing to the &Add; method of a &Variables; object, like so:
1112 vars = Variables('custom.py')
1113 vars.Add(BoolVariable('RELEASE', 'Set to build for release', 0))
1114 env = Environment(variables = vars,
1115 CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
1116 env.Program('foo.c')
1121 With this build variable,
1122 the &RELEASE; variable can now be enabled by
1123 setting it to the value <literal>yes</literal>
1124 or <literal>t</literal>:
1129 % <userinput>scons -Q RELEASE=yes foo.o</userinput>
1130 cc -o foo.o -c -DRELEASE_BUILD=True foo.c
1134 % <userinput>scons -Q RELEASE=t foo.o</userinput>
1135 cc -o foo.o -c -DRELEASE_BUILD=True foo.c
1140 Other values that equate to &true; include
1141 <literal>y</literal>,
1142 <literal>1</literal>,
1143 <literal>on</literal>
1145 <literal>all</literal>.
1151 Conversely, &RELEASE; may now be given a &false;
1152 value by setting it to
1153 <literal>no</literal>
1155 <literal>f</literal>:
1160 % <userinput>scons -Q RELEASE=no foo.o</userinput>
1161 cc -o foo.o -c -DRELEASE_BUILD=False foo.c
1165 % <userinput>scons -Q RELEASE=f foo.o</userinput>
1166 cc -o foo.o -c -DRELEASE_BUILD=False foo.c
1171 Other values that equate to &false; include
1172 <literal>n</literal>,
1173 <literal>0</literal>,
1174 <literal>off</literal>
1176 <literal>none</literal>.
1182 Lastly, if a user tries to specify
1184 &SCons; supplies an appropriate error message:
1189 % <userinput>scons -Q RELEASE=bad_value foo.o</userinput>
1191 scons: *** Error converting option: RELEASE
1192 Invalid value for boolean option: bad_value
1193 File "/home/my/project/SConstruct", line 4, in <module>
1199 <title>Single Value From a List: the &EnumVariable; Build Variable Function</title>
1203 Suppose that we want a user to be able to
1204 set a &COLOR; variable
1205 that selects a background color to be
1206 displayed by an application,
1207 but that we want to restrict the
1208 choices to a specific set of allowed colors.
1209 This can be set up quite easily
1210 using the &EnumVariable;,
1211 which takes a list of &allowed_values;
1212 in addition to the variable name,
1214 and help text arguments:
1219 vars = Variables('custom.py')
1220 vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
1221 allowed_values=('red', 'green', 'blue')))
1222 env = Environment(variables = vars,
1223 CPPDEFINES={'COLOR' : '"${COLOR}"'})
1224 env.Program('foo.c')
1229 The user can now explicity set the &COLOR; build variable
1230 to any of the specified allowed values:
1235 % <userinput>scons -Q COLOR=red foo.o</userinput>
1236 cc -o foo.o -c -DCOLOR="red" foo.c
1237 % <userinput>scons -Q COLOR=blue foo.o</userinput>
1238 cc -o foo.o -c -DCOLOR="blue" foo.c
1239 % <userinput>scons -Q COLOR=green foo.o</userinput>
1240 cc -o foo.o -c -DCOLOR="green" foo.c
1245 But, almost more importantly,
1246 an attempt to set &COLOR;
1247 to a value that's not in the list
1248 generates an error message:
1253 % <userinput>scons -Q COLOR=magenta foo.o</userinput>
1255 scons: *** Invalid value for option COLOR: magenta
1256 File "/home/my/project/SConstruct", line 5, in <module>
1261 The &EnumVariable; function also supports a way
1262 to map alternate names to allowed values.
1263 Suppose, for example,
1264 that we want to allow the user
1265 to use the word <literal>navy</literal> as a synonym for
1266 <literal>blue</literal>.
1267 We do this by adding a ↦ dictionary
1268 that will map its key values
1269 to the desired legal value:
1274 vars = Variables('custom.py')
1275 vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
1276 allowed_values=('red', 'green', 'blue'),
1277 map={'navy':'blue'}))
1278 env = Environment(variables = vars,
1279 CPPDEFINES={'COLOR' : '"${COLOR}"'})
1280 env.Program('foo.c')
1285 As desired, the user can then use
1286 <literal>navy</literal> on the command line,
1287 and &SCons; will translate it into <literal>blue</literal>
1288 when it comes time to use the &COLOR;
1289 variable to build a target:
1294 % <userinput>scons -Q COLOR=navy foo.o</userinput>
1295 cc -o foo.o -c -DCOLOR="blue" foo.c
1300 By default, when using the &EnumVariable; function,
1301 arguments that differ
1302 from the legal values
1304 are treated as illegal values:
1309 % <userinput>scons -Q COLOR=Red foo.o</userinput>
1311 scons: *** Invalid value for option COLOR: Red
1312 File "/home/my/project/SConstruct", line 5, in <module>
1313 % <userinput>scons -Q COLOR=BLUE foo.o</userinput>
1315 scons: *** Invalid value for option COLOR: BLUE
1316 File "/home/my/project/SConstruct", line 5, in <module>
1317 % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
1319 scons: *** Invalid value for option COLOR: nAvY
1320 File "/home/my/project/SConstruct", line 5, in <module>
1325 The &EnumVariable; function can take an additional
1326 &ignorecase; keyword argument that,
1327 when set to <literal>1</literal>,
1328 tells &SCons; to allow case differences
1329 when the values are specified:
1334 vars = Variables('custom.py')
1335 vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
1336 allowed_values=('red', 'green', 'blue'),
1337 map={'navy':'blue'},
1339 env = Environment(variables = vars,
1340 CPPDEFINES={'COLOR' : '"${COLOR}"'})
1341 env.Program('foo.c')
1346 Which yields the output:
1351 % <userinput>scons -Q COLOR=Red foo.o</userinput>
1352 cc -o foo.o -c -DCOLOR="Red" foo.c
1353 % <userinput>scons -Q COLOR=BLUE foo.o</userinput>
1354 cc -o foo.o -c -DCOLOR="BLUE" foo.c
1355 % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
1356 cc -o foo.o -c -DCOLOR="blue" foo.c
1357 % <userinput>scons -Q COLOR=green foo.o</userinput>
1358 cc -o foo.o -c -DCOLOR="green" foo.c
1363 Notice that an &ignorecase; value of <literal>1</literal>
1364 preserves the case-spelling that the user supplied.
1365 If you want &SCons; to translate the names
1367 regardless of the case used by the user,
1368 specify an &ignorecase; value of <literal>2</literal>:
1373 vars = Variables('custom.py')
1374 vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
1375 allowed_values=('red', 'green', 'blue'),
1376 map={'navy':'blue'},
1378 env = Environment(variables = vars,
1379 CPPDEFINES={'COLOR' : '"${COLOR}"'})
1380 env.Program('foo.c')
1385 Now &SCons; will use values of
1386 <literal>red</literal>,
1387 <literal>green</literal> or
1388 <literal>blue</literal>
1389 regardless of how the user spells
1390 those values on the command line:
1395 % <userinput>scons -Q COLOR=Red foo.o</userinput>
1396 cc -o foo.o -c -DCOLOR="red" foo.c
1397 % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
1398 cc -o foo.o -c -DCOLOR="blue" foo.c
1399 % <userinput>scons -Q COLOR=GREEN foo.o</userinput>
1400 cc -o foo.o -c -DCOLOR="green" foo.c
1406 <title>Multiple Values From a List: the &ListVariable; Build Variable Function</title>
1410 Another way in which you might want to allow users
1411 to control a build variable is to
1412 specify a list of one or more legal values.
1413 &SCons; supports this through the &ListVariable; function.
1414 If, for example, we want a user to be able to set a
1415 &COLORS; variable to one or more of the legal list of values:
1420 vars = Variables('custom.py')
1421 vars.Add(ListVariable('COLORS', 'List of colors', 0,
1422 ['red', 'green', 'blue']))
1423 env = Environment(variables = vars,
1424 CPPDEFINES={'COLORS' : '"${COLORS}"'})
1425 env.Program('foo.c')
1430 A user can now specify a comma-separated list
1432 which will get translated into a space-separated
1433 list for passing to the any build commands:
1438 % <userinput>scons -Q COLORS=red,blue foo.o</userinput>
1439 cc -o foo.o -c -DCOLORS="red blue" foo.c
1440 % <userinput>scons -Q COLORS=blue,green,red foo.o</userinput>
1441 cc -o foo.o -c -DCOLORS="blue green red" foo.c
1446 In addition, the &ListVariable; function
1447 allows the user to specify explicit keywords of
1449 to select all of the legal values,
1450 or none of them, respectively:
1455 % <userinput>scons -Q COLORS=all foo.o</userinput>
1456 cc -o foo.o -c -DCOLORS="red green blue" foo.c
1457 % <userinput>scons -Q COLORS=none foo.o</userinput>
1458 cc -o foo.o -c -DCOLORS="" foo.c
1463 And, of course, an illegal value
1464 still generates an error message:
1469 % <userinput>scons -Q COLORS=magenta foo.o</userinput>
1471 scons: *** Error converting option: COLORS
1472 Invalid value(s) for option: magenta
1473 File "/home/my/project/SConstruct", line 5, in <module>
1479 <title>Path Names: the &PathVariable; Build Variable Function</title>
1483 &SCons; supports a &PathVariable; function
1484 to make it easy to create a build variable
1485 to control an expected path name.
1486 If, for example, you need to
1487 define a variable in the preprocessor
1488 that controls the location of a
1494 vars = Variables('custom.py')
1495 vars.Add(PathVariable('CONFIG',
1496 'Path to configuration file',
1498 env = Environment(variables = vars,
1499 CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
1500 env.Program('foo.c')
1505 This then allows the user to
1506 override the &CONFIG; build variable
1507 on the command line as necessary:
1512 % <userinput>scons -Q foo.o</userinput>
1513 cc -o foo.o -c -DCONFIG_FILE="/etc/my_config" foo.c
1514 % <userinput>scons -Q CONFIG=/usr/local/etc/other_config foo.o</userinput>
1515 scons: `foo.o' is up to date.
1520 By default, &PathVariable; checks to make sure
1521 that the specified path exists and generates an error if it
1527 % <userinput>scons -Q CONFIG=/does/not/exist foo.o</userinput>
1529 scons: *** Path for option CONFIG does not exist: /does/not/exist
1530 File "/home/my/project/SConstruct", line 6, in <module>
1535 &PathVariable; provides a number of methods
1536 that you can use to change this behavior.
1537 If you want to ensure that any specified paths are,
1538 in fact, files and not directories,
1539 use the &PathVariable_PathIsFile; method:
1544 vars = Variables('custom.py')
1545 vars.Add(PathVariable('CONFIG',
1546 'Path to configuration file',
1548 PathVariable.PathIsFile))
1549 env = Environment(variables = vars,
1550 CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
1551 env.Program('foo.c')
1556 Conversely, to ensure that any specified paths are
1557 directories and not files,
1558 use the &PathVariable_PathIsDir; method:
1563 vars = Variables('custom.py')
1564 vars.Add(PathVariable('DBDIR',
1565 'Path to database directory',
1567 PathVariable.PathIsDir))
1568 env = Environment(variables = vars,
1569 CPPDEFINES={'DBDIR' : '"$DBDIR"'})
1570 env.Program('foo.c')
1575 If you want to make sure that any specified paths
1577 and you would like the directory created
1578 if it doesn't already exist,
1579 use the &PathVariable_PathIsDirCreate; method:
1584 vars = Variables('custom.py')
1585 vars.Add(PathVariable('DBDIR',
1586 'Path to database directory',
1588 PathVariable.PathIsDirCreate))
1589 env = Environment(variables = vars,
1590 CPPDEFINES={'DBDIR' : '"$DBDIR"'})
1591 env.Program('foo.c')
1596 Lastly, if you don't care whether the path exists,
1597 is a file, or a directory,
1598 use the &PathVariable_PathAccept; method
1599 to accept any path that the user supplies:
1604 vars = Variables('custom.py')
1605 vars.Add(PathVariable('OUTPUT',
1606 'Path to output file or directory',
1608 PathVariable.PathAccept))
1609 env = Environment(variables = vars,
1610 CPPDEFINES={'OUTPUT' : '"$OUTPUT"'})
1611 env.Program('foo.c')
1617 <title>Enabled/Disabled Path Names: the &PackageVariable; Build Variable Function</title>
1621 Sometimes you want to give users
1622 even more control over a path name variable,
1623 allowing them to explicitly enable or
1624 disable the path name
1625 by using <literal>yes</literal> or <literal>no</literal> keywords,
1626 in addition to allow them
1627 to supply an explicit path name.
1628 &SCons; supports the &PackageVariable;
1629 function to support this:
1634 vars = Variables('custom.py')
1635 vars.Add(PackageVariable('PACKAGE',
1638 env = Environment(variables = vars,
1639 CPPDEFINES={'PACKAGE' : '"$PACKAGE"'})
1640 env.Program('foo.c')
1645 When the &SConscript; file uses the &PackageVariable; funciton,
1646 user can now still use the default
1647 or supply an overriding path name,
1648 but can now explicitly set the
1649 specified variable to a value
1650 that indicates the package should be enabled
1651 (in which case the default should be used)
1657 % <userinput>scons -Q foo.o</userinput>
1658 cc -o foo.o -c -DPACKAGE="/opt/location" foo.c
1659 % <userinput>scons -Q PACKAGE=/usr/local/location foo.o</userinput>
1660 cc -o foo.o -c -DPACKAGE="/usr/local/location" foo.c
1661 % <userinput>scons -Q PACKAGE=yes foo.o</userinput>
1662 cc -o foo.o -c -DPACKAGE="True" foo.c
1663 % <userinput>scons -Q PACKAGE=no foo.o</userinput>
1664 cc -o foo.o -c -DPACKAGE="False" foo.c
1672 <title>Adding Multiple Command-Line Build Variables at Once</title>
1676 Lastly, &SCons; provides a way to add
1677 multiple build variables to a &Variables; object at once.
1678 Instead of having to call the &Add; method
1680 you can call the &AddVariables;
1681 method with a list of build variables
1682 to be added to the object.
1683 Each build variable is specified
1684 as either a tuple of arguments,
1685 just like you'd pass to the &Add; method itself,
1686 or as a call to one of the pre-defined
1687 functions for pre-packaged command-line build variables.
1695 ('RELEASE', 'Set to 1 to build for release', 0),
1696 ('CONFIG', 'Configuration file', '/etc/my_config'),
1697 BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
1698 EnumVariable('debug', 'debug output and symbols', 'no',
1699 allowed_values=('yes', 'no', 'full'),
1700 map={}, ignorecase=0), # case sensitive
1701 ListVariable('shared',
1702 'libraries to build as shared libraries',
1704 names = list_of_libs),
1705 PackageVariable('x11',
1706 'use X11 installed here (yes = search some places)',
1708 PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
1718 <title>Handling Unknown Command-Line Build Variables: the &UnknownVariables; Function</title>
1722 Users may, of course,
1723 occasionally misspell variable names in their command-line settings.
1724 &SCons; does not generate an error or warning
1725 for any unknown variables the users specifies on the command line.
1726 (This is in no small part because you may be
1727 processing the arguments directly using the &ARGUMENTS; dictionary,
1728 and therefore &SCons; can't know in the general case
1729 whether a given "misspelled" variable is
1730 really unknown and a potential problem,
1731 or something that your &SConscript; file
1732 will handle directly with some Python code.)
1738 If, however, you're using a &Variables; object to
1739 define a specific set of command-line build variables
1740 that you expect users to be able to set,
1741 you may want to provide an error
1742 message or warning of your own
1743 if the user supplies a variable setting
1744 that is <emphasis>not</emphasis> among
1745 the defined list of variable names known to the &Variables; object.
1746 You can do this by calling the &UnknownVariables;
1747 method of the &Variables; object:
1752 vars = Variables(None)
1753 vars.Add('RELEASE', 'Set to 1 to build for release', 0)
1754 env = Environment(variables = vars,
1755 CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
1756 unknown = vars.UnknownVariables()
1758 print "Unknown variables:", unknown.keys()
1760 env.Program('foo.c')
1765 The &UnknownVariables; method returns a dictionary
1766 containing the keywords and values
1767 of any variables the user specified on the command line
1768 that are <emphasis>not</emphasis>
1769 among the variables known to the &Variables; object
1770 (from having been specified using
1771 the &Variables; object's&Add; method).
1772 In the examble above,
1773 we check for whether the dictionary
1774 returned by the &UnknownVariables; is non-empty,
1775 and if so print the Python list
1776 containing the names of the unknwown variables
1777 and then call the &Exit; function
1778 to terminate &SCons;:
1783 % <userinput>scons -Q NOT_KNOWN=foo</userinput>
1784 Unknown variables: ['NOT_KNOWN']
1789 Of course, you can process the items in the
1790 dictionary returned by the &UnknownVariables; function
1791 in any way appropriate to your build configuration,
1792 including just printing a warning message
1794 logging an error somewhere,
1801 Note that you must delay the call of &UnknownVariables;
1802 until after you have applied the &Variables; object
1803 to a construction environment
1804 with the <literal>variables=</literal>
1805 keyword argument of an &Environment; call.
1813 <section id="sect-command-line-targets">
1814 <title>Command-Line Targets</title>
1817 <title>Fetching Command-Line Targets: the &COMMAND_LINE_TARGETS; Variable</title>
1821 &SCons; supports a &COMMAND_LINE_TARGETS; variable
1822 that lets you fetch the list of targets that the
1823 user specified on the command line.
1824 You can use the targets to manipulate the
1825 build in any way you wish.
1826 As a simple example,
1827 suppose that you want to print a reminder
1828 to the user whenever a specific program is built.
1829 You can do this by checking for the
1830 target in the &COMMAND_LINE_TARGETS; list:
1835 if 'bar' in COMMAND_LINE_TARGETS:
1836 print "Don't forget to copy `bar' to the archive!"
1837 Default(Program('foo.c'))
1843 Then, running &SCons; with the default target
1844 works as it always does,
1845 but explicity specifying the &bar; target
1846 on the command line generates the warning message:
1851 % <userinput>scons -Q</userinput>
1852 cc -o foo.o -c foo.c
1854 % <userinput>scons -Q bar</userinput>
1855 Don't forget to copy `bar' to the archive!
1856 cc -o bar.o -c bar.c
1862 Another practical use for the &COMMAND_LINE_TARGETS; variable
1863 might be to speed up a build
1864 by only reading certain subsidiary &SConscript;
1865 files if a specific target is requested.
1872 <title>Controlling the Default Targets: the &Default; Function</title>
1876 One of the most basic things you can control
1877 is which targets &SCons; will build by default--that is,
1878 when there are no targets specified on the command line.
1879 As mentioned previously,
1880 &SCons; will normally build every target
1881 in or below the current directory
1882 by default--that is, when you don't
1883 explicitly specify one or more targets
1884 on the command line.
1885 Sometimes, however, you may want
1886 to specify explicitly that only
1887 certain programs, or programs in certain directories,
1888 should be built by default.
1889 You do this with the &Default; function:
1895 hello = env.Program('hello.c')
1896 env.Program('goodbye.c')
1902 This &SConstruct; file knows how to build two programs,
1903 &hello; and &goodbye;,
1905 &hello; program by default:
1910 % <userinput>scons -Q</userinput>
1911 cc -o hello.o -c hello.c
1913 % <userinput>scons -Q</userinput>
1914 scons: `hello' is up to date.
1915 % <userinput>scons -Q goodbye</userinput>
1916 cc -o goodbye.o -c goodbye.c
1917 cc -o goodbye goodbye.o
1922 Note that, even when you use the &Default;
1923 function in your &SConstruct; file,
1924 you can still explicitly specify the current directory
1925 (<literal>.</literal>) on the command line
1926 to tell &SCons; to build
1927 everything in (or below) the current directory:
1932 % <userinput>scons -Q .</userinput>
1933 cc -o goodbye.o -c goodbye.c
1934 cc -o goodbye goodbye.o
1935 cc -o hello.o -c hello.c
1941 You can also call the &Default;
1942 function more than once,
1943 in which case each call
1944 adds to the list of targets to be built by default:
1950 prog1 = env.Program('prog1.c')
1952 prog2 = env.Program('prog2.c')
1953 prog3 = env.Program('prog3.c')
1959 Or you can specify more than one target
1960 in a single call to the &Default; function:
1966 prog1 = env.Program('prog1.c')
1967 prog2 = env.Program('prog2.c')
1968 prog3 = env.Program('prog3.c')
1969 Default(prog1, prog3)
1974 Either of these last two examples
1976 <application>prog1</application>
1978 <application>prog3</application>
1979 programs by default:
1984 % <userinput>scons -Q</userinput>
1985 cc -o prog1.o -c prog1.c
1987 cc -o prog3.o -c prog3.c
1989 % <userinput>scons -Q .</userinput>
1990 cc -o prog2.o -c prog2.c
1996 You can list a directory as
1997 an argument to &Default;:
2003 env.Program(['prog1/main.c', 'prog1/foo.c'])
2004 env.Program(['prog2/main.c', 'prog2/bar.c'])
2010 In which case only the target(s) in that
2011 directory will be built by default:
2016 % <userinput>scons -Q</userinput>
2017 cc -o prog1/foo.o -c prog1/foo.c
2018 cc -o prog1/main.o -c prog1/main.c
2019 cc -o prog1/main prog1/main.o prog1/foo.o
2020 % <userinput>scons -Q</userinput>
2021 scons: `prog1' is up to date.
2022 % <userinput>scons -Q .</userinput>
2023 cc -o prog2/bar.o -c prog2/bar.c
2024 cc -o prog2/main.o -c prog2/main.c
2025 cc -o prog2/main prog2/main.o prog2/bar.o
2030 Lastly, if for some reason you don't want
2031 any targets built by default,
2032 you can use the Python <literal>None</literal>
2039 prog1 = env.Program('prog1.c')
2040 prog2 = env.Program('prog2.c')
2046 Which would produce build output like:
2051 % <userinput>scons -Q</userinput>
2052 scons: *** No targets specified and no Default() targets found. Stop.
2053 % <userinput>scons -Q .</userinput>
2054 cc -o prog1.o -c prog1.c
2056 cc -o prog2.o -c prog2.c
2061 <title>Fetching the List of Default Targets: the &DEFAULT_TARGETS; Variable</title>
2065 &SCons; supports a &DEFAULT_TARGETS; variable
2066 that lets you get at the current list of default targets.
2067 The &DEFAULT_TARGETS; variable has
2068 two important differences from the &COMMAND_LINE_TARGETS; variable.
2069 First, the &DEFAULT_TARGETS; variable is a list of
2070 internal &SCons; nodes,
2071 so you need to convert the list elements to strings
2072 if you want to print them or look for a specific target name.
2073 Fortunately, you can do this easily
2074 by using the Python <function>map</function> function
2075 to run the list through <function>str</function>:
2080 prog1 = Program('prog1.c')
2082 print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS)
2087 (Keep in mind that all of the manipulation of the
2088 &DEFAULT_TARGETS; list takes place during the
2089 first phase when &SCons; is reading up the &SConscript; files,
2091 we leave off the <literal>-Q</literal> flag when we run &SCons;:)
2096 % <userinput>scons</userinput>
2097 scons: Reading SConscript files ...
2098 DEFAULT_TARGETS is ['prog1']
2099 scons: done reading SConscript files.
2100 scons: Building targets ...
2101 cc -o prog1.o -c prog1.c
2103 scons: done building targets.
2109 the contents of the &DEFAULT_TARGETS; list change
2110 in response to calls to the &Default;: function,
2111 as you can see from the following &SConstruct; file:
2116 prog1 = Program('prog1.c')
2118 print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
2119 prog2 = Program('prog2.c')
2121 print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
2126 Which yields the output:
2131 % <userinput>scons</userinput>
2132 scons: Reading SConscript files ...
2133 DEFAULT_TARGETS is now ['prog1']
2134 DEFAULT_TARGETS is now ['prog1', 'prog2']
2135 scons: done reading SConscript files.
2136 scons: Building targets ...
2137 cc -o prog1.o -c prog1.c
2139 cc -o prog2.o -c prog2.c
2141 scons: done building targets.
2146 In practice, this simply means that you
2147 need to pay attention to the order in
2148 which you call the &Default; function
2149 and refer to the &DEFAULT_TARGETS; list,
2150 to make sure that you don't examine the
2151 list before you've added the default targets
2152 you expect to find in it.
2161 <title>Fetching the List of Build Targets, Regardless of Origin: the &BUILD_TARGETS; Variable</title>
2165 We've already been introduced to the
2166 &COMMAND_LINE_TARGETS; variable,
2167 which contains a list of targets specified on the command line,
2168 and the &DEFAULT_TARGETS; variable,
2169 which contains a list of targets specified
2170 via calls to the &Default; method or function.
2172 you want a list of whatever targets
2173 &SCons; will try to build,
2174 regardless of whether the targets came from the
2175 command line or a &Default; call.
2176 You could code this up by hand, as follows:
2181 if COMMAND_LINE_TARGETS:
2182 targets = COMMAND_LINE_TARGETS
2184 targets = DEFAULT_TARGETS
2189 &SCons;, however, provides a convenient
2190 &BUILD_TARGETS; variable
2191 that eliminates the need for this by-hand manipulation.
2192 Essentially, the &BUILD_TARGETS; variable
2193 contains a list of the command-line targets,
2194 if any were specified,
2195 and if no command-line targets were specified,
2196 it contains a list of the targets specified
2197 via the &Default; method or function.
2203 Because &BUILD_TARGETS; may contain a list of &SCons; nodes,
2204 you must convert the list elements to strings
2205 if you want to print them or look for a specific target name,
2206 just like the &DEFAULT_TARGETS; list:
2211 prog1 = Program('prog1.c')
2214 print "BUILD_TARGETS is", map(str, BUILD_TARGETS)
2219 Notice how the value of &BUILD_TARGETS;
2220 changes depending on whether a target is
2221 specified on the command line:
2226 % <userinput>scons -Q</userinput>
2227 BUILD_TARGETS is ['prog1']
2228 cc -o prog1.o -c prog1.c
2230 % <userinput>scons -Q prog2</userinput>
2231 BUILD_TARGETS is ['prog2']
2232 cc -o prog2.o -c prog2.c
2234 % <userinput>scons -Q -c .</userinput>
2235 BUILD_TARGETS is ['.']