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 examind
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:
149 <scons_example name="SCONSFLAGS">
150 <file name="SConstruct">
151 def b(target, source, env):
153 def s(target, source, env):
154 return " ... [build output] ..."
155 a = Action(b, strfunction = s)
156 env = Environment(BUILDERS = {'A' : Builder(action=a)})
157 env.A('foo.out', 'foo.in')
164 <scons_output example="SCONSFLAGS">
165 <scons_output_command>scons</scons_output_command>
166 <scons_output_command>export SCONSFLAGS="-Q"</scons_output_command>
167 <scons_output_command environment="SCONSFLAGS=-Q">scons</scons_output_command>
172 Users of &csh;-style shells on POSIX systems
173 can set the &SCONSFLAGS; environment as follows:
178 $ <userinput>setenv SCONSFLAGS "-Q"</userinput>
183 Windows users may typically want to set the
184 &SCONSFLAGS; in the appropriate tab of the
185 <literal>System Properties</literal> window.
192 <title>Getting Values Set by Command-Line Options: the &GetOption; Function</title>
196 &SCons; provides the &GetOption; function
197 to get the values set by the various command-line options.
198 One common use of this is to check whether or not
199 the <literal>-h</literal> or <literal>--help</literal> option
201 Normally, &SCons; does not print its help text
202 until after it has read all of the &SConscript; files,
203 because it's possible that help text has been added
204 by some subsidiary &SConscript; file deep in the
205 source tree hierarchy.
206 Of course, reading all of the &SConscript; files
213 If you know that your configuration does not define
214 any additional help text in subsidiary &SConscript; files,
215 you can speed up the command-line help available to users
216 by using the &GetOption; function to load the
217 subsidiary &SConscript; files only if the
218 the user has <emphasis>not</emphasis> specified
219 the <literal>-h</literal> or <literal>--help</literal> option,
225 if not GetOption('help'):
226 SConscript('src/SConscript', export='env')
231 In general, the string that you pass to the
232 &GetOption; function to fetch the value of a command-line
233 option setting is the same as the "most common" long option name
234 (beginning with two hyphen characters),
235 although there are some exceptions.
236 The list of &SCons; command-line options
237 and the &GetOption; strings for fetching them,
239 <xref linkend="sect-command-line-option-strings"></xref> section,
247 <title>Setting Values of Command-Line Options: the &SetOption; Function</title>
251 You can also set the values of &SCons;
252 command-line options from within the &SConscript; files
253 by using the &SetOption; function.
254 The strings that you use to set the values of &SCons;
255 command-line options are available in the
256 <xref linkend="sect-command-line-option-strings"></xref> section,
263 One use of the &SetOption; function is to
264 specify a value for the <literal>-j</literal>
265 or <literal>--jobs</literal> option,
266 so that users get the improved performance
267 of a parallel build without having to specify the option by hand.
268 A complicating factor is that a good value
269 for the <literal>-j</literal> option is
270 somewhat system-dependent.
271 One rough guideline is that the more processors
273 the higher you want to set the
274 <literal>-j</literal> value,
275 in order to take advantage of the number of CPUs.
281 For example, suppose the administrators
282 of your development systems
283 have standardized on setting a
284 <varname>NUM_CPU</varname> environment variable
285 to the number of processors on each system.
286 A little bit of Python code
287 to access the environment variable
288 and the &SetOption; function
289 provide the right level of flexibility:
293 <scons_example name="SetOption">
294 <file name="SConstruct" printme="1">
296 num_cpu = int(os.environ.get('NUM_CPU', 2))
297 SetOption('num_jobs', num_cpu)
298 print "running with -j", GetOption('num_jobs')
307 The above snippet of code
308 sets the value of the <literal>--jobs</literal> option
309 to the value specified in the
310 <varname>$NUM_CPU</varname> environment variable.
311 (This is one of the exception cases
312 where the string is spelled differently from
313 the from command-line option.
314 The string for fetching or setting the <literal>--jobs</literal>
315 value is <literal>num_jobs</literal>
316 for historical reasons.)
317 The code in this example prints the <literal>num_jobs</literal>
318 value for illustrative purposes.
319 It uses a default value of <literal>2</literal>
320 to provide some minimal parallelism even on
321 single-processor systems:
325 <scons_output example="SetOption">
326 <scons_output_command>scons -Q</scons_output_command>
331 But if the <varname>$NUM_CPU</varname>
332 environment variable is set,
333 then we use that for the default number of jobs:
337 <scons_output example="SetOption">
338 <scons_output_command>export NUM_CPU="4"</scons_output_command>
339 <scons_output_command environment="NUM_CPU=4">scons -Q</scons_output_command>
345 <literal>-j</literal> or <literal>--jobs</literal>
346 value the user specifies an the command line is used first,
347 regardless of whether or not
348 the <varname>$NUM_CPU</varname> environment
353 <scons_output example="SetOption">
354 <scons_output_command>scons -Q -j 7</scons_output_command>
355 <scons_output_command>export NUM_CPU="4"</scons_output_command>
356 <scons_output_command environment="NUM_CPU=4">scons -Q -j 3</scons_output_command>
361 <section id="sect-command-line-option-strings">
362 <title>Strings for Getting or Setting Values of &SCons; Command-Line Options</title>
366 The strings that you can pass to the &GetOption;
367 and &SetOption; functions usually correspond to the
368 first long-form option name
369 (beginning with two hyphen characters: <literal>--</literal>),
370 after replacing any remaining hyphen characters
377 The full list of strings and the variables they
378 correspond to is as follows:
383 <tgroup cols="2" align="left">
388 <entry>String for &GetOption; and &SetOption;</entry>
389 <entry>Command-Line Option(s)</entry>
397 <entry><literal>cache_debug</literal></entry>
398 <entry><option>--cache-debug</option></entry>
402 <entry><literal>cache_disable</literal></entry>
403 <entry><option>--cache-disable</option></entry>
407 <entry><literal>cache_force</literal></entry>
408 <entry><option>--cache-force</option></entry>
412 <entry><literal>cache_show</literal></entry>
413 <entry><option>--cache-show</option></entry>
417 <entry><literal>clean</literal></entry>
418 <entry><option>-c</option>,
419 <option>--clean</option>,
420 <option>--remove</option></entry>
424 <entry><literal>config</literal></entry>
425 <entry><option>--config</option></entry>
429 <entry><literal>directory</literal></entry>
430 <entry><option>-C</option>,
431 <option>--directory</option></entry>
435 <entry><literal>diskcheck</literal></entry>
436 <entry><option>--diskcheck</option></entry>
440 <entry><literal>duplicate</literal></entry>
441 <entry><option>--duplicate</option></entry>
445 <entry><literal>file</literal></entry>
446 <entry><option>-f</option>,
447 <option>--file</option>,
448 <option>--makefile </option>,
449 <option>--sconstruct</option></entry>
453 <entry><literal>help</literal></entry>
454 <entry><option>-h</option>,
455 <option>--help</option></entry>
459 <entry><literal>ignore_errors</literal></entry>
460 <entry><option>--ignore-errors</option></entry>
464 <entry><literal>implicit_cache</literal></entry>
465 <entry><option>--implicit-cache</option></entry>
469 <entry><literal>implicit_deps_changed</literal></entry>
470 <entry><option>--implicit-deps-changed</option></entry>
474 <entry><literal>implicit_deps_unchanged</literal></entry>
475 <entry><option>--implicit-deps-unchanged</option></entry>
479 <entry><literal>interactive</literal></entry>
480 <entry><option>--interact</option>,
481 <option>--interactive</option></entry>
485 <entry><literal>keep_going</literal></entry>
486 <entry><option>-k</option>,
487 <option>--keep-going</option></entry>
491 <entry><literal>max_drift</literal></entry>
492 <entry><option>--max-drift</option></entry>
496 <entry><literal>no_exec</literal></entry>
497 <entry><option>-n</option>,
498 <option>--no-exec</option>,
499 <option>--just-print</option>,
500 <option>--dry-run</option>,
501 <option>--recon</option></entry>
505 <entry><literal>no_site_dir</literal></entry>
506 <entry><option>--no-site-dir</option></entry>
510 <entry><literal>num_jobs</literal></entry>
511 <entry><option>-j</option>,
512 <option>--jobs</option></entry>
516 <entry><literal>profile_file</literal></entry>
517 <entry><option>--profile</option></entry>
521 <entry><literal>question</literal></entry>
522 <entry><option>-q</option>,
523 <option>--question</option></entry>
527 <entry><literal>random</literal></entry>
528 <entry><option>--random</option></entry>
532 <entry><literal>repository</literal></entry>
533 <entry><option>-Y</option>,
534 <option>--repository</option>,
535 <option>--srcdir</option></entry>
539 <entry><literal>silent</literal></entry>
540 <entry><option>-s</option>,
541 <option>--silent</option>,
542 <option>--quiet</option></entry>
546 <entry><literal>site_dir</literal></entry>
547 <entry><option>--site-dir</option></entry>
551 <entry><literal>stack_size</literal></entry>
552 <entry><option>--stack-size</option></entry>
556 <entry><literal>taskmastertrace_file</literal></entry>
557 <entry><option>--taskmastertrace</option></entry>
561 <entry><literal>warn</literal></entry>
562 <entry><option>--warn</option> <option>--warning</option></entry>
573 <title>Adding Custom Command-Line Options: the &AddOption; Function</title>
577 &SCons; also allows you to define your own
578 command-line options with the &AddOption; function.
579 The &AddOption; function takes the same arguments
580 as the <function>optparse.add_option</function> function
581 from the standard Python library.
584 The &AddOption; function is,
585 in fact, implemented using a subclass
586 of the <classname>optparse.OptionParser</classname>.
589 Once you have added a custom command-line option
590 with the &AddOption; function,
591 the value of the option (if any) is immediately available
592 using the standard &GetOption; function.
593 (The value can also be set using &SetOption;,
594 although that's not very useful in practice
595 because a default value can be specified in
596 directly in the &AddOption; call.)
602 One useful example of using this functionality
603 is to provide a <option>--prefix</option> for users:
607 <scons_example name="AddOption">
608 <file name="SConstruct" printme="1">
609 AddOption('--prefix',
615 help='installation prefix')
617 env = Environment(PREFIX = GetOption('prefix'))
619 installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in')
620 Default(installed_foo)
629 The above code uses the &GetOption; function
630 to set the <varname>$PREFIX</varname>
631 construction variable to any
632 value that the user specifies with a command-line
633 option of <literal>--prefix</literal>.
634 Because <varname>$PREFIX</varname>
635 will expand to a null string if it's not initialized,
636 running &SCons; without the
637 option of <literal>--prefix</literal>
638 will install the file in the
639 <filename>/usr/bin/</filename> directory:
643 <scons_output example="AddOption">
644 <scons_output_command>scons -Q -n</scons_output_command>
649 But specifying <literal>--prefix=/tmp/install</literal>
650 on the command line causes the file to be installed in the
651 <filename>/tmp/install/usr/bin/</filename> directory:
655 <scons_output example="AddOption">
656 <scons_output_command>scons -Q -n --prefix=/tmp/install</scons_output_command>
663 <section id="sect-command-line-variables">
664 <title>Command-Line <varname>variable</varname>=<varname>value</varname> Build Variables</title>
668 You may want to control various aspects
669 of your build by allowing the user
670 to specify <varname>variable</varname>=<varname>value</varname>
671 values on the command line.
672 For example, suppose you
673 want users to be able to
674 build a debug version of a program
675 by running &SCons; as follows:
680 % <userinput>scons -Q debug=1</userinput>
685 &SCons; provides an &ARGUMENTS; dictionary
686 that stores all of the
687 <varname>variable</varname>=<varname>value</varname>
688 assignments from the command line.
689 This allows you to modify
690 aspects of your build in response
691 to specifications on the command line.
692 (Note that unless you want to require
693 that users <emphasis>always</emphasis>
695 you probably want to use
697 <literal>ARGUMENTS.get()</literal> function,
698 which allows you to specify a default value
699 to be used if there is no specification
700 on the command line.)
706 The following code sets the &cv-link-CCFLAGS; construction
707 variable in response to the <varname>debug</varname>
708 flag being set in the &ARGUMENTS; dictionary:
712 <scons_example name="ARGUMENTS">
713 <file name="SConstruct" printme="1">
715 debug = ARGUMENTS.get('debug', 0)
717 env.Append(CCFLAGS = '-g')
718 env.Program('prog.c')
727 This results in the <varname>-g</varname>
728 compiler option being used when
729 <literal>debug=1</literal>
730 is used on the command line:
734 <scons_output example="ARGUMENTS">
735 <scons_output_command>scons -Q debug=0</scons_output_command>
736 <scons_output_command>scons -Q debug=0</scons_output_command>
737 <scons_output_command>scons -Q debug=1</scons_output_command>
738 <scons_output_command>scons -Q debug=1</scons_output_command>
743 Notice that &SCons; keeps track of
744 the last values used to build the object files,
745 and as a result correctly rebuilds
746 the object and executable files
747 only when the value of the <literal>debug</literal>
748 argument has changed.
754 The &ARGUMENTS; dictionary has two minor drawbacks.
755 First, because it is a dictionary,
756 it can only store one value for each specified keyword,
757 and thus only "remembers" the last setting
758 for each keyword on the command line.
759 This makes the &ARGUMENTS; dictionary
760 inappropriate if users should be able to
761 specify multiple values
762 on the command line for a given keyword.
763 Second, it does not preserve
764 the order in which the variable settings
766 which is a problem if
767 you want the configuration to
768 behave differently in response
769 to the order in which the build
770 variable settings were specified on the command line.
776 To accomodate these requirements,
777 &SCons; provides an &ARGLIST; variable
778 that gives you direct access to
779 <varname>variable</varname>=<varname>value</varname>
780 settings on the command line,
781 in the exact order they were specified,
782 and without removing any duplicate settings.
783 Each element in the &ARGLIST; variable
784 is itself a two-element list
785 containing the keyword and the value
787 and you must loop through,
788 or otherwise select from,
789 the elements of &ARGLIST; to
790 process the specific settings you want
791 in whatever way is appropriate for your configuration.
793 the following code to let the user
794 add to the &CPPDEFINES; construction variable
795 by specifying multiple
796 <varname>define=</varname>
797 settings on the command line:
801 <scons_example name="ARGLIST">
802 <file name="SConstruct" printme="1">
804 for key, value in ARGLIST:
806 cppdefines.append(value)
807 env = Environment(CPPDEFINES = cppdefines)
817 Yields the followig output:
821 <scons_output example="ARGLIST">
822 <scons_output_command>scons -Q define=FOO</scons_output_command>
823 <scons_output_command>scons -Q define=FOO define=BAR</scons_output_command>
828 Note that the &ARGLIST; and &ARGUMENTS;
829 variables do not interfere with each other,
830 but merely provide slightly different views
831 into how the user specified
832 <varname>variable</varname>=<varname>value</varname>
833 settings on the command line.
834 You can use both variables in the same
835 &SCons; configuration.
836 In general, the &ARGUMENTS; dictionary
837 is more convenient to use,
838 (since you can just fetch variable
839 settings through a dictionary access),
840 and the &ARGLIST; list
842 (since you can examine the
843 specific order in which
844 the user's command-line variabe settings).
849 <title>Controlling Command-Line Build Variables</title>
853 Being able to use a command-line build variable like
854 <literal>debug=1</literal> is handy,
855 but it can be a chore to write specific Python code
856 to recognize each such variable,
857 check for errors and provide appropriate messages,
858 and apply the values to a construction variable.
860 &SCons; supports a class to
861 define such build variables easily,
862 and a mechanism to apply the
863 build variables to a construction environment.
864 This allows you to control how the build variables affect
865 construction environments.
871 For example, suppose that you want users to set
872 a &RELEASE; construction variable on the
873 command line whenever the time comes to build
874 a program for release,
875 and that the value of this variable
876 should be added to the command line
877 with the appropriate <literal>-D</literal> option
878 (or other command line option)
879 to pass the value to the C compiler.
880 Here's how you might do that by setting
881 the appropriate value in a dictionary for the
882 &cv-link-CPPDEFINES; construction variable:
886 <scons_example name="Variables1">
887 <file name="SConstruct" printme="1">
889 vars.Add('RELEASE', 'Set to 1 to build for release', 0)
890 env = Environment(variables = vars,
891 CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
892 env.Program(['foo.c', 'bar.c'])
904 This &SConstruct; file first creates a &Variables; object
905 (the <literal>vars = Variables()</literal> call),
906 and then uses the object's &Add;
907 method to indicate that the &RELEASE;
908 variable can be set on the command line,
909 and that its default value will be <literal>0</literal>
910 (the third argument to the &Add; method).
911 The second argument is a line of help text;
912 we'll learn how to use it in the next section.
918 We then pass the created &Variables;
919 object as a &variables; keyword argument
920 to the &Environment; call
921 used to create the construction environment.
922 This then allows a user to set the
923 &RELEASE; build variable on the command line
924 and have the variable show up in
925 the command line used to build each object from
930 <scons_output example="Variables1">
931 <scons_output_command>scons -Q RELEASE=1</scons_output_command>
936 NOTE: Before &SCons; release 0.98.1, these build variables
937 were known as "command-line build options."
938 The class was actually named the &Options; class,
939 and in the sections below,
940 the various functions were named
941 &BoolOption;, &EnumOption;, &ListOption;,
942 &PathOption;, &PackageOption; and &AddOptions;.
943 These older names still work,
944 and you may encounter them in older
946 but their use is discouraged
947 and will be officially deprecated some day.
954 <title>Providing Help for Command-Line Build Variables</title>
958 To make command-line build variables most useful,
959 you ideally want to provide
960 some help text that will describe
961 the available variables
962 when the user runs <literal>scons -h</literal>.
963 You could write this text by hand,
964 but &SCons; provides an easier way.
965 &Variables; objects support a
966 &GenerateHelpText; method
967 that will, as its name suggests,
968 generate text that describes
969 the various variables that
970 have been added to it.
971 You then pass the output from this method to
976 <scons_example name="Variables_Help">
977 <file name="SConstruct" printme="1">
978 vars = Variables('custom.py')
979 vars.Add('RELEASE', 'Set to 1 to build for release', 0)
980 env = Environment(variables = vars)
981 Help(vars.GenerateHelpText(env))
987 &SCons; will now display some useful text
988 when the <literal>-h</literal> option is used:
992 <scons_output example="Variables_Help">
993 <scons_output_command>scons -Q -h</scons_output_command>
998 Notice that the help output shows the default value,
999 and the current actual value of the build variable.
1006 <title>Reading Build Variables From a File</title>
1010 Giving the user a way to specify the
1011 value of a build variable on the command line
1013 but can still be tedious
1014 if users must specify the variable
1015 every time they run &SCons;.
1016 We can let users provide customized build variable settings
1017 in a local file by providing a
1018 file name when we create the
1023 <scons_example name="Variables_custom_py_1">
1024 <file name="SConstruct" printme="1">
1025 vars = Variables('custom.py')
1026 vars.Add('RELEASE', 'Set to 1 to build for release', 0)
1027 env = Environment(variables = vars,
1028 CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
1029 env.Program(['foo.c', 'bar.c'])
1030 Help(vars.GenerateHelpText(env))
1038 <file name="custom.py">
1045 This then allows the user to control the &RELEASE;
1046 variable by setting it in the &custom_py; file:
1050 <scons_example_file example="Variables_custom_py_1" name="custom.py"></scons_example_file>
1054 Note that this file is actually executed
1055 like a Python script.
1056 Now when we run &SCons;:
1060 <scons_output example="Variables_custom_py_1">
1061 <scons_output_command>scons -Q</scons_output_command>
1066 And if we change the contents of &custom_py; to:
1070 <scons_example name="Variables_custom_py_2">
1071 <file name="SConstruct">
1072 vars = Variables('custom.py')
1073 vars.Add('RELEASE', 'Set to 1 to build for release', 0)
1074 env = Environment(variables = vars,
1075 CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
1076 env.Program(['foo.c', 'bar.c'])
1077 Help(vars.GenerateHelpText(env))
1085 <file name="custom.py" printme="1">
1092 The object files are rebuilt appropriately
1093 with the new variable:
1097 <scons_output example="Variables_custom_py_2">
1098 <scons_output_command>scons -Q</scons_output_command>
1104 <title>Pre-Defined Build Variable Functions</title>
1108 &SCons; provides a number of functions
1109 that provide ready-made behaviors
1110 for various types of command-line build variables.
1115 <title>True/False Values: the &BoolVariable; Build Variable Function</title>
1119 It's often handy to be able to specify a
1120 variable that controls a simple Boolean variable
1121 with a &true; or &false; value.
1122 It would be even more handy to accomodate
1123 users who have different preferences for how to represent
1124 &true; or &false; values.
1125 The &BoolVariable; function
1126 makes it easy to accomodate these
1127 common representations of
1134 The &BoolVariable; function takes three arguments:
1135 the name of the build variable,
1136 the default value of the build variable,
1137 and the help string for the variable.
1138 It then returns appropriate information for
1139 passing to the &Add; method of a &Variables; object, like so:
1143 <scons_example name="BoolVariable">
1144 <file name="SConstruct" printme="1">
1145 vars = Variables('custom.py')
1146 vars.Add(BoolVariable('RELEASE', 'Set to build for release', 0))
1147 env = Environment(variables = vars,
1148 CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
1149 env.Program('foo.c')
1158 With this build variable,
1159 the &RELEASE; variable can now be enabled by
1160 setting it to the value <literal>yes</literal>
1161 or <literal>t</literal>:
1165 <scons_output example="BoolVariable">
1166 <scons_output_command>scons -Q RELEASE=yes foo.o</scons_output_command>
1169 <scons_output example="BoolVariable">
1170 <scons_output_command>scons -Q RELEASE=t foo.o</scons_output_command>
1175 Other values that equate to &true; include
1176 <literal>y</literal>,
1177 <literal>1</literal>,
1178 <literal>on</literal>
1180 <literal>all</literal>.
1186 Conversely, &RELEASE; may now be given a &false;
1187 value by setting it to
1188 <literal>no</literal>
1190 <literal>f</literal>:
1194 <scons_output example="BoolVariable">
1195 <scons_output_command>scons -Q RELEASE=no foo.o</scons_output_command>
1198 <scons_output example="BoolVariable">
1199 <scons_output_command>scons -Q RELEASE=f foo.o</scons_output_command>
1204 Other values that equate to &false; include
1205 <literal>n</literal>,
1206 <literal>0</literal>,
1207 <literal>off</literal>
1209 <literal>none</literal>.
1215 Lastly, if a user tries to specify
1217 &SCons; supplies an appropriate error message:
1221 <scons_output example="BoolVariable">
1222 <scons_output_command>scons -Q RELEASE=bad_value foo.o</scons_output_command>
1228 <title>Single Value From a List: the &EnumVariable; Build Variable Function</title>
1232 Suppose that we want a user to be able to
1233 set a &COLOR; variable
1234 that selects a background color to be
1235 displayed by an application,
1236 but that we want to restrict the
1237 choices to a specific set of allowed colors.
1238 This can be set up quite easily
1239 using the &EnumVariable;,
1240 which takes a list of &allowed_values
1241 in addition to the variable name,
1243 and help text arguments:
1247 <scons_example name="EnumVariable">
1248 <file name="SConstruct" printme="1">
1249 vars = Variables('custom.py')
1250 vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
1251 allowed_values=('red', 'green', 'blue')))
1252 env = Environment(variables = vars,
1253 CPPDEFINES={'COLOR' : '"${COLOR}"'})
1254 env.Program('foo.c')
1263 The user can now explicity set the &COLOR; build variable
1264 to any of the specified allowed values:
1268 <scons_output example="EnumVariable">
1269 <scons_output_command>scons -Q COLOR=red foo.o</scons_output_command>
1270 <scons_output_command>scons -Q COLOR=blue foo.o</scons_output_command>
1271 <scons_output_command>scons -Q COLOR=green foo.o</scons_output_command>
1276 But, almost more importantly,
1277 an attempt to set &COLOR;
1278 to a value that's not in the list
1279 generates an error message:
1283 <scons_output example="EnumVariable">
1284 <scons_output_command>scons -Q COLOR=magenta foo.o</scons_output_command>
1289 The &EnumVariable; function also supports a way
1290 to map alternate names to allowed values.
1291 Suppose, for example,
1292 that we want to allow the user
1293 to use the word <literal>navy</literal> as a synonym for
1294 <literal>blue</literal>.
1295 We do this by adding a ↦ dictionary
1296 that will map its key values
1297 to the desired legal value:
1301 <scons_example name="EnumVariable_map">
1302 <file name="SConstruct" printme="1">
1303 vars = Variables('custom.py')
1304 vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
1305 allowed_values=('red', 'green', 'blue'),
1306 map={'navy':'blue'}))
1307 env = Environment(variables = vars,
1308 CPPDEFINES={'COLOR' : '"${COLOR}"'})
1309 env.Program('foo.c')
1318 As desired, the user can then use
1319 <literal>navy</literal> on the command line,
1320 and &SCons; will translate it into <literal>blue</literal>
1321 when it comes time to use the &COLOR;
1322 variable to build a target:
1326 <scons_output example="EnumVariable_map">
1327 <scons_output_command>scons -Q COLOR=navy foo.o</scons_output_command>
1332 By default, when using the &EnumVariable; function,
1333 arguments that differ
1334 from the legal values
1336 are treated as illegal values:
1340 <scons_output example="EnumVariable">
1341 <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command>
1342 <scons_output_command>scons -Q COLOR=BLUE foo.o</scons_output_command>
1343 <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command>
1348 The &EnumVariable; function can take an additional
1349 &ignorecase; keyword argument that,
1350 when set to <literal>1</literal>,
1351 tells &SCons; to allow case differences
1352 when the values are specified:
1356 <scons_example name="EnumVariable_ic1">
1357 <file name="SConstruct" printme="1">
1358 vars = Variables('custom.py')
1359 vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
1360 allowed_values=('red', 'green', 'blue'),
1361 map={'navy':'blue'},
1363 env = Environment(variables = vars,
1364 CPPDEFINES={'COLOR' : '"${COLOR}"'})
1365 env.Program('foo.c')
1374 Which yields the output:
1378 <scons_output example="EnumVariable_ic1">
1379 <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command>
1380 <scons_output_command>scons -Q COLOR=BLUE foo.o</scons_output_command>
1381 <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command>
1382 <scons_output_command>scons -Q COLOR=green foo.o</scons_output_command>
1387 Notice that an &ignorecase; value of <literal>1</literal>
1388 preserves the case-spelling that the user supplied.
1389 If you want &SCons; to translate the names
1391 regardless of the case used by the user,
1392 specify an &ignorecase; value of <literal>2</literal>:
1396 <scons_example name="EnumVariable_ic2">
1397 <file name="SConstruct" printme="1">
1398 vars = Variables('custom.py')
1399 vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
1400 allowed_values=('red', 'green', 'blue'),
1401 map={'navy':'blue'},
1403 env = Environment(variables = vars,
1404 CPPDEFINES={'COLOR' : '"${COLOR}"'})
1405 env.Program('foo.c')
1414 Now &SCons; will use values of
1415 <literal>red</literal>,
1416 <literal>green</literal> or
1417 <literal>blue</literal>
1418 regardless of how the user spells
1419 those values on the command line:
1423 <scons_output example="EnumVariable_ic2">
1424 <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command>
1425 <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command>
1426 <scons_output_command>scons -Q COLOR=GREEN foo.o</scons_output_command>
1432 <title>Multiple Values From a List: the &ListVariable; Build Variable Function</title>
1436 Another way in which you might want to allow users
1437 to control a build variable is to
1438 specify a list of one or more legal values.
1439 &SCons; supports this through the &ListVariable; function.
1440 If, for example, we want a user to be able to set a
1441 &COLORS; variable to one or more of the legal list of values:
1445 <scons_example name="ListVariable">
1446 <file name="SConstruct" printme="1">
1447 vars = Variables('custom.py')
1448 vars.Add(ListVariable('COLORS', 'List of colors', 0,
1449 ['red', 'green', 'blue']))
1450 env = Environment(variables = vars,
1451 CPPDEFINES={'COLORS' : '"${COLORS}"'})
1452 env.Program('foo.c')
1461 A user can now specify a comma-separated list
1463 which will get translated into a space-separated
1464 list for passing to the any build commands:
1468 <scons_output example="ListVariable">
1469 <scons_output_command>scons -Q COLORS=red,blue foo.o</scons_output_command>
1470 <scons_output_command>scons -Q COLORS=blue,green,red foo.o</scons_output_command>
1475 In addition, the &ListVariable; function
1476 allows the user to specify explicit keywords of
1478 to select all of the legal values,
1479 or none of them, respectively:
1483 <scons_output example="ListVariable">
1484 <scons_output_command>scons -Q COLORS=all foo.o</scons_output_command>
1485 <scons_output_command>scons -Q COLORS=none foo.o</scons_output_command>
1490 And, of course, an illegal value
1491 still generates an error message:
1495 <scons_output example="ListVariable">
1496 <scons_output_command>scons -Q COLORS=magenta foo.o</scons_output_command>
1502 <title>Path Names: the &PathVariable; Build Variable Function</title>
1506 &SCons; supports a &PathVariable; function
1507 to make it easy to create a build variable
1508 to control an expected path name.
1509 If, for example, you need to
1510 define a variable in the preprocessor
1511 that controls the location of a
1516 <scons_example name="PathVariable">
1517 <file name="SConstruct" printme="1">
1518 vars = Variables('custom.py')
1519 vars.Add(PathVariable('CONFIG',
1520 'Path to configuration file',
1521 '__ROOT__/etc/my_config'))
1522 env = Environment(variables = vars,
1523 CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
1524 env.Program('foo.c')
1529 <file name="__ROOT__/etc/my_config">
1532 <file name="__ROOT__/usr/local/etc/other_config">
1539 This then allows the user to
1540 override the &CONFIG; build variable
1541 on the command line as necessary:
1545 <scons_output example="PathVariable">
1546 <scons_output_command>scons -Q foo.o</scons_output_command>
1547 <scons_output_command>scons -Q CONFIG=__ROOT__/usr/local/etc/other_config foo.o</scons_output_command>
1552 By default, &PathVariable; checks to make sure
1553 that the specified path exists and generates an error if it
1558 <scons_output example="PathVariable">
1559 <scons_output_command>scons -Q CONFIG=__ROOT__/does/not/exist foo.o</scons_output_command>
1564 &PathVariable; provides a number of methods
1565 that you can use to change this behavior.
1566 If you want to ensure that any specified paths are,
1567 in fact, files and not directories,
1568 use the &PathVariable_PathIsFile; method:
1572 <scons_example name="PathIsFile">
1573 <file name="SConstruct" printme="1">
1574 vars = Variables('custom.py')
1575 vars.Add(PathVariable('CONFIG',
1576 'Path to configuration file',
1577 '__ROOT__/etc/my_config',
1578 PathVariable.PathIsFile))
1579 env = Environment(variables = vars,
1580 CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
1581 env.Program('foo.c')
1586 <file name="__ROOT__/etc/my_config">
1593 Conversely, to ensure that any specified paths are
1594 directories and not files,
1595 use the &PathVariable_PathIsDir; method:
1599 <scons_example name="PathIsDir">
1600 <file name="SConstruct" printme="1">
1601 vars = Variables('custom.py')
1602 vars.Add(PathVariable('DBDIR',
1603 'Path to database directory',
1604 '__ROOT__/var/my_dbdir',
1605 PathVariable.PathIsDir))
1606 env = Environment(variables = vars,
1607 CPPDEFINES={'DBDIR' : '"$DBDIR"'})
1608 env.Program('foo.c')
1613 <file name="__ROOT__/var/my_dbdir">
1620 If you want to make sure that any specified paths
1622 and you would like the directory created
1623 if it doesn't already exist,
1624 use the &PathVariable_PathIsDirCreate; method:
1628 <scons_example name="PathIsDirCreate">
1629 <file name="SConstruct" printme="1">
1630 vars = Variables('custom.py')
1631 vars.Add(PathVariable('DBDIR',
1632 'Path to database directory',
1633 '__ROOT__/var/my_dbdir',
1634 PathVariable.PathIsDirCreate))
1635 env = Environment(variables = vars,
1636 CPPDEFINES={'DBDIR' : '"$DBDIR"'})
1637 env.Program('foo.c')
1642 <file name="__ROOT__/var/my_dbdir">
1649 Lastly, if you don't care whether the path exists,
1650 is a file, or a directory,
1651 use the &PathVariable_PathAccept; method
1652 to accept any path that the user supplies:
1656 <scons_example name="PathAccept">
1657 <file name="SConstruct" printme="1">
1658 vars = Variables('custom.py')
1659 vars.Add(PathVariable('OUTPUT',
1660 'Path to output file or directory',
1662 PathVariable.PathAccept))
1663 env = Environment(variables = vars,
1664 CPPDEFINES={'OUTPUT' : '"$OUTPUT"'})
1665 env.Program('foo.c')
1675 <title>Enabled/Disabled Path Names: the &PackageVariable; Build Variable Function</title>
1679 Sometimes you want to give users
1680 even more control over a path name variable,
1681 allowing them to explicitly enable or
1682 disable the path name
1683 by using <literal>yes</literal> or <literal>no</literal> keywords,
1684 in addition to allow them
1685 to supply an explicit path name.
1686 &SCons; supports the &PackageVariable;
1687 function to support this:
1691 <scons_example name="PackageVariable">
1692 <file name="SConstruct" printme="1">
1693 vars = Variables('custom.py')
1694 vars.Add(PackageVariable('PACKAGE',
1696 '__ROOT__/opt/location'))
1697 env = Environment(variables = vars,
1698 CPPDEFINES={'PACKAGE' : '"$PACKAGE"'})
1699 env.Program('foo.c')
1704 <file name="__ROOT__/opt/location">
1707 <file name="__ROOT__/usr/local/location">
1714 When the &SConscript; file uses the &PackageVariable; funciton,
1715 user can now still use the default
1716 or supply an overriding path name,
1717 but can now explicitly set the
1718 specified variable to a value
1719 that indicates the package should be enabled
1720 (in which case the default should be used)
1725 <scons_output example="PackageVariable">
1726 <scons_output_command>scons -Q foo.o</scons_output_command>
1727 <scons_output_command>scons -Q PACKAGE=__ROOT__/usr/local/location foo.o</scons_output_command>
1728 <scons_output_command>scons -Q PACKAGE=yes foo.o</scons_output_command>
1729 <scons_output_command>scons -Q PACKAGE=no foo.o</scons_output_command>
1737 <title>Adding Multiple Command-Line Build Variables at Once</title>
1741 Lastly, &SCons; provides a way to add
1742 multiple build variables to a &Variables; object at once.
1743 Instead of having to call the &Add; method
1745 you can call the &AddVariables;
1746 method with a list of build variables
1747 to be added to the object.
1748 Each build variable is specified
1749 as either a tuple of arguments,
1750 just like you'd pass to the &Add; method itself,
1751 or as a call to one of the pre-defined
1752 functions for pre-packaged command-line build variables.
1757 <scons_example name="AddVariables_1">
1758 <file name="SConstruct" printme="1">
1761 ('RELEASE', 'Set to 1 to build for release', 0),
1762 ('CONFIG', 'Configuration file', '/etc/my_config'),
1763 BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
1764 EnumVariable('debug', 'debug output and symbols', 'no',
1765 allowed_values=('yes', 'no', 'full'),
1766 map={}, ignorecase=0), # case sensitive
1767 ListVariable('shared',
1768 'libraries to build as shared libraries',
1770 names = list_of_libs),
1771 PackageVariable('x11',
1772 'use X11 installed here (yes = search some places)',
1774 PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
1785 <title>Handling Unknown Command-Line Build Variables: the &UnknownVariables; Function</title>
1789 Users may, of course,
1790 occasionally misspell variable names in their command-line settings.
1791 &SCons; does not generate an error or warning
1792 for any unknown variables the users specifies on the command line.
1793 (This is in no small part because you may be
1794 processing the arguments directly using the &ARGUMENTS; dictionary,
1795 and therefore &SCons; can't know in the general case
1796 whether a given "misspelled" variable is
1797 really unknown and a potential problem,
1798 or something that your &SConscript; file
1799 will handle directly with some Python code.)
1805 If, however, you're using a &Variables; object to
1806 define a specific set of command-line build variables
1807 that you expect users to be able to set,
1808 you may want to provide an error
1809 message or warning of your own
1810 if the user supplies a variable setting
1811 that is <emphasis>not</emphasis> among
1812 the defined list of variable names known to the &Variables; object.
1813 You can do this by calling the &UnknownVariables;
1814 method of the &Variables; object:
1818 <scons_example name="UnknownVariables">
1819 <file name="SConstruct" printme="1">
1820 vars = Variables(None)
1821 vars.Add('RELEASE', 'Set to 1 to build for release', 0)
1822 env = Environment(variables = vars,
1823 CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
1824 unknown = vars.UnknownVariables()
1826 print "Unknown variables:", unknown.keys()
1828 env.Program('foo.c')
1837 The &UnknownVariables; method returns a dictionary
1838 containing the keywords and values
1839 of any variables the user specified on the command line
1840 that are <emphasis>not</emphasis>
1841 among the variables known to the &Variables; object
1842 (from having been specified using
1843 the &Variables; object's&Add; method).
1844 In the examble above,
1845 we check for whether the dictionary
1846 returned by the &UnknownVariables; is non-empty,
1847 and if so print the Python list
1848 containing the names of the unknwown variables
1849 and then call the &Exit; function
1850 to terminate &SCons;:
1854 <scons_output example="UnknownVariables">
1855 <scons_output_command>scons -Q NOT_KNOWN=foo</scons_output_command>
1860 Of course, you can process the items in the
1861 dictionary returned by the &UnknownVariables; function
1862 in any way appropriate to your bulid configuration,
1863 including just printing a warning message
1865 logging an error somewhere,
1872 Note that you must delay the call of &UnknownVariables;
1873 until after you have applied the &Variables; object
1874 to a construction environment
1875 with the <literal>variables=</literal>
1876 keyword argument of an &Environment; call.
1884 <section id="sect-command-line-targets">
1885 <title>Command-Line Targets</title>
1888 <title>Fetching Command-Line Targets: the &COMMAND_LINE_TARGETS; Variable</title>
1892 &SCons; supports a &COMMAND_LINE_TARGETS; variable
1893 that lets you fetch the list of targets that the
1894 user specified on the command line.
1895 You can use the targets to manipulate the
1896 build in any way you wish.
1897 As a simple example,
1898 suppose that you want to print a reminder
1899 to the user whenever a specific program is built.
1900 You can do this by checking for the
1901 target in the &COMMAND_LINE_TARGETS; list:
1905 <scons_example name="COMMAND_LINE_TARGETS">
1906 <file name="SConstruct" printme="1">
1907 if 'bar' in COMMAND_LINE_TARGETS:
1908 print "Don't forget to copy `bar' to the archive!"
1909 Default(Program('foo.c'))
1922 Then, running &SCons; with the default target
1923 works as it always does,
1924 but explicity specifying the &bar; target
1925 on the command line generates the warning message:
1929 <scons_output example="COMMAND_LINE_TARGETS">
1930 <scons_output_command>scons -Q</scons_output_command>
1931 <scons_output_command>scons -Q bar</scons_output_command>
1936 Another practical use for the &COMMAND_LINE_TARGETS; variable
1937 might be to speed up a build
1938 by only reading certain subsidiary &SConscript;
1939 files if a specific target is requested.
1946 <title>Controlling the Default Targets: the &Default; Function</title>
1950 One of the most basic things you can control
1951 is which targets &SCons; will build by default--that is,
1952 when there are no targets specified on the command line.
1953 As mentioned previously,
1954 &SCons; will normally build every target
1955 in or below the current directory
1956 by default--that is, when you don't
1957 explicitly specify one or more targets
1958 on the command line.
1959 Sometimes, however, you may want
1960 to specify explicitly that only
1961 certain programs, or programs in certain directories,
1962 should be built by default.
1963 You do this with the &Default; function:
1967 <scons_example name="Default1">
1968 <file name="SConstruct" printme="1">
1970 hello = env.Program('hello.c')
1971 env.Program('goodbye.c')
1974 <file name="hello.c">
1977 <file name="goodbye.c">
1984 This &SConstruct; file knows how to build two programs,
1985 &hello; and &goodbye;,
1987 &hello; program by default:
1991 <scons_output example="Default1">
1992 <scons_output_command>scons -Q</scons_output_command>
1993 <scons_output_command>scons -Q</scons_output_command>
1994 <scons_output_command>scons -Q goodbye</scons_output_command>
1999 Note that, even when you use the &Default;
2000 function in your &SConstruct; file,
2001 you can still explicitly specify the current directory
2002 (<literal>.</literal>) on the command line
2003 to tell &SCons; to build
2004 everything in (or below) the current directory:
2008 <scons_output example="Default1">
2009 <scons_output_command>scons -Q .</scons_output_command>
2014 You can also call the &Default;
2015 function more than once,
2016 in which case each call
2017 adds to the list of targets to be built by default:
2021 <scons_example name="Default2">
2022 <file name="SConstruct" printme="1">
2024 prog1 = env.Program('prog1.c')
2026 prog2 = env.Program('prog2.c')
2027 prog3 = env.Program('prog3.c')
2030 <file name="prog1.c">
2033 <file name="prog2.c">
2036 <file name="prog3.c">
2043 Or you can specify more than one target
2044 in a single call to the &Default; function:
2050 prog1 = env.Program('prog1.c')
2051 prog2 = env.Program('prog2.c')
2052 prog3 = env.Program('prog3.c')
2053 Default(prog1, prog3)
2058 Either of these last two examples
2060 <application>prog1</application>
2062 <application>prog3</application>
2063 programs by default:
2067 <scons_output example="Default2">
2068 <scons_output_command>scons -Q</scons_output_command>
2069 <scons_output_command>scons -Q .</scons_output_command>
2074 You can list a directory as
2075 an argument to &Default;:
2079 <scons_example name="Default3">
2080 <file name="SConstruct" printme="1">
2082 env.Program(['prog1/main.c', 'prog1/foo.c'])
2083 env.Program(['prog2/main.c', 'prog2/bar.c'])
2086 <directory name="prog1"></directory>
2087 <directory name="prog2"></directory>
2088 <file name="prog1/main.c">
2089 int main() { printf("prog1/main.c\n"); }
2091 <file name="prog1/foo.c">
2092 int foo() { printf("prog1/foo.c\n"); }
2094 <file name="prog2/main.c">
2095 int main() { printf("prog2/main.c\n"); }
2097 <file name="prog2/bar.c">
2098 int bar() { printf("prog2/bar.c\n"); }
2104 In which case only the target(s) in that
2105 directory will be built by default:
2109 <scons_output example="Default3">
2110 <scons_output_command>scons -Q</scons_output_command>
2111 <scons_output_command>scons -Q</scons_output_command>
2112 <scons_output_command>scons -Q .</scons_output_command>
2117 Lastly, if for some reason you don't want
2118 any targets built by default,
2119 you can use the Python <literal>None</literal>
2124 <scons_example name="Default4">
2125 <file name="SConstruct" printme="1">
2127 prog1 = env.Program('prog1.c')
2128 prog2 = env.Program('prog2.c')
2131 <file name="prog1.c">
2134 <file name="prog2.c">
2141 Which would produce build output like:
2145 <scons_output example="Default4">
2146 <scons_output_command>scons -Q</scons_output_command>
2147 <scons_output_command>scons -Q .</scons_output_command>
2151 <title>Fetching the List of Default Targets: the &DEFAULT_TARGETS; Variable</title>
2155 &SCons; supports a &DEFAULT_TARGETS; variable
2156 that lets you get at the current list of default targets.
2157 The &DEFAULT_TARGETS variable has
2158 two important differences from the &COMMAND_LINE_TARGETS; variable.
2159 First, the &DEFAULT_TARGETS; variable is a list of
2160 internal &SCons; nodes,
2161 so you need to convert the list elements to strings
2162 if you want to print them or look for a specific target name.
2163 Fortunately, you can do this easily
2164 by using the Python <function>map</function> function
2165 to run the list through <function>str</function>:
2169 <scons_example name="DEFAULT_TARGETS_1">
2170 <file name="SConstruct" printme="1">
2171 prog1 = Program('prog1.c')
2173 print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS)
2175 <file name="prog1.c">
2182 (Keep in mind that all of the manipulation of the
2183 &DEFAULT_TARGETS; list takes place during the
2184 first phase when &SCons; is reading up the &SConscript; files,
2186 we leave off the <literal>-Q</literal> flag when we run &SCons;:)
2190 <scons_output example="DEFAULT_TARGETS_1">
2191 <scons_output_command>scons</scons_output_command>
2197 the contents of the &DEFAULT_TARGETS; list change
2198 in response to calls to the &Default: function,
2199 as you can see from the following &SConstruct; file:
2203 <scons_example name="DEFAULT_TARGETS_2">
2204 <file name="SConstruct" printme="1">
2205 prog1 = Program('prog1.c')
2207 print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
2208 prog2 = Program('prog2.c')
2210 print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
2212 <file name="prog1.c">
2215 <file name="prog2.c">
2222 Which yields the output:
2226 <scons_output example="DEFAULT_TARGETS_2">
2227 <scons_output_command>scons</scons_output_command>
2232 In practice, this simply means that you
2233 need to pay attention to the order in
2234 which you call the &Default; function
2235 and refer to the &DEFAULT_TARGETS; list,
2236 to make sure that you don't examine the
2237 list before you've added the default targets
2238 you expect to find in it.
2247 <title>Fetching the List of Build Targets, Regardless of Origin: the &BUILD_TARGETS; Variable</title>
2251 We've already been introduced to the
2252 &COMMAND_LINE_TARGETS; variable,
2253 which contains a list of targets specified on the command line,
2254 and the &DEFAULT_TARGETS; variable,
2255 which contains a list of targets specified
2256 via calls to the &Default; method or function.
2258 you want a list of whatever targets
2259 &SCons; will try to build,
2260 regardless of whether the targets came from the
2261 command line or a &Default; call.
2262 You could code this up by hand, as follows:
2267 if COMMAND_LINE_TARGETS:
2268 targets = COMMAND_LINE_TARGETS
2270 targets = DEFAULT_TARGETS
2275 &SCons;, however, provides a convenient
2276 &BUILD_TARGETS; variable
2277 that eliminates the need for this by-hand manipulation.
2278 Essentially, the &BUILD_TARGETS; variable
2279 contains a list of the command-line targets,
2280 if any were specified,
2281 and if no command-line targets were specified,
2282 it contains a list of the targets specified
2283 via the &Default; method or function.
2289 Because &BUILD_TARGETS; may contain a list of &SCons; nodes,
2290 you must convert the list elements to strings
2291 if you want to print them or look for a specific target name,
2292 just like the &DEFAULT_TARGETS; list:
2296 <scons_example name="BUILD_TARGETS_1">
2297 <file name="SConstruct" printme="1">
2298 prog1 = Program('prog1.c')
2301 print "BUILD_TARGETS is", map(str, BUILD_TARGETS)
2303 <file name="prog1.c">
2306 <file name="prog2.c">
2313 Notice how the value of &BUILD_TARGETS;
2314 changes depending on whether a target is
2315 specified on the command line:
2319 <scons_output example="BUILD_TARGETS_1">
2320 <scons_output_command>scons -Q</scons_output_command>
2321 <scons_output_command>scons -Q prog2</scons_output_command>
2322 <scons_output_command>scons -Q -c .</scons_output_command>