From 9677b9fa57f09540fb7087d8874b5aa38b9fc21e Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 28 Feb 2020 11:39:12 -0700 Subject: Continue manpage cleanups [ci skip] Eliminate some "note" wording in manpage. This is a "tone" thing, trying to avoid so many "asides", like "Note that blah blah", by trying to reword into a more regular flow, and occasionally dropping the aside if it doesn't seem quite suited to the manpage. More harmonization of docbook entity usage, cleanup of comments around generated sections, and other fiddling. around a code fragment was changed to around output was changed to If a section contained use input, that was marked with the entity. These changes ought to also facilitate better conversion to other document markup formats, something which has been discussed. In the Description section, the remaining command-line discussion at the end was merged into the earlier wording about command-line processing, to improve the flow a bit. Some options entries were adjusted for appearance - indents, etc. Mention of Python 2.7 as a requirement is dropped. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 2059 ++++++++++++++++++++++----------------------- doc/python10/design.xml | 2 +- doc/scons.mod | 19 +- doc/user/repositories.xml | 4 +- 4 files changed, 1032 insertions(+), 1052 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 6aa42a3..7336c4f 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -86,9 +86,9 @@ scons - options - name=val - targets + options + name=val + targets @@ -96,7 +96,7 @@ DESCRIPTION -scons +&scons; orchestrates the construction of software (and other tangible products such as documentation files) by determining which @@ -104,19 +104,19 @@ component pieces must be built or rebuilt and invoking the necessary commands to build them. You instruct -scons by writing a configuration file +&scons; by writing a configuration file which specifies the files to be built (targets), and, if necessary, the rules to build those files. Premade rules exist for building many common software components -(such as executable programs, object files, libraries), -so that for most software projects, +such as executable programs, object files, libraries, +so that for many software projects, only the target and input files need be specified. -When invoked, scons +When invoked, &scons; searches for a file named &SConstruct; -(going on to check alternative names +(it also checks alternate spellings &Sconstruct;, &sconstruct;, &SConstruct.py; &Sconstruct.py; and &sconstruct.py; in that order) in the current directory and reads its @@ -127,7 +127,7 @@ specified via the option. The &SConstruct; file can specify subsidiary -configuration files using the +configuration files by calling the &SConscriptFunc; function. By convention, these subsidiary files are named @@ -137,12 +137,12 @@ As a result of this naming convention, the term SConscript files is often used to refer generically to the complete set of -configuration files for a project, -including the &SConstruct; file, -regardless of the actual file names or number of files. +configuration files for a project +(including the &SConstruct; file), +regardless of the actual file names or number of such files. Before reading the SConscript files, -scons +&scons; looks for a directory named site_scons in various system directories and in the directory containing the @@ -150,7 +150,7 @@ in various system directories and in the directory containing the finds to the Python module search path (sys.path), thus allowing modules in such directories to be imported in the normal Python way in SConscript files. -For each found site directory, +For each found site directory, if it contains a file site_init.py it is evaluated, and if it contains a directory site_tools the path to it @@ -163,30 +163,34 @@ options for details on default paths and controlling the site directories. -scons -reads and executes the SConscript files as Python scripts, -so you may use normal Python scripting capabilities -(such as flow control, data manipulation, and imported Python libraries) -to handle complicated build situations. + +&scons; configuration files are written in the +Python programming language, +although it is normally not necessary to be a Python +programmer to use &scons; effectively. +Standard Python scripting capabilities +such as flow control, data manipulation, and imported Python libraries +are available to use to handle complicated build situations. + -scons +&scons; reads and executes all of the SConscript files before it begins building any targets. To make this clear, -scons +&scons; prints the following messages about what it is doing: - -$ scons foo.out + +$ scons foo.out scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... cp foo.in foo.out scons: done building targets. $ - + The status messages (lines beginning with the scons: tag) @@ -194,97 +198,123 @@ may be suppressed using the option. -scons +&scons; does not automatically propagate the external environment used to execute -scons +&scons; to the commands used to build target files. This is so that builds will be guaranteed repeatable regardless of the environment variables set at the time -scons +&scons; is invoked. This also means that if the compiler or other commands that you want to use to build your target files are not in standard system locations, -scons +&scons; will not find them unless -you explicitly set the scons +you explicitly set the &scons; PATH in the internal environment to include those locations. Whenever you create a &consenv;, you can propagate the value of PATH from your external environment as follows: - + import os env = Environment(ENV={'PATH': os.environ['PATH']}) - + Similarly, if the commands use specific -external environment variables that scons +external environment variables that &scons; does not recognize, they can be propagated into the internal environment: - + import os env = Environment(ENV={'PATH': os.environ['PATH'], 'ANDROID_HOME': os.environ['ANDROID_HOME'], 'ANDROID_NDK_HOME': os.environ['ANDROID_NDK_HOME']}) - + Or you may explicitly propagate the invoking user's complete external environment: - + import os env = Environment(ENV=os.environ) - + This comes at the expense of making your build dependent on the user's environment being set correctly, but it may be more convenient for many configurations. It should not cause problems if done in a build setup which tightly controls how the environment is set up before invoking -scons, as in many continuous +&scons;, as in many continuous integration setups. -scons +&scons; can scan known input files automatically for dependency information (for example, #include preprocessor directives in C or C++ files) and will rebuild dependent files appropriately whenever any "included" input file changes. -scons +&scons; supports the ability to define new scanners for unknown input file types. -scons +&scons; knows how to fetch files automatically from SCCS or RCS subdirectories using SCCS, RCS or BitKeeper. -scons +&scons; is normally executed in a top-level directory containing an &SConstruct; file. -When scons is invoked, +When &scons; is invoked, the command line (including the contents of the &SCONSFLAGS; environment variable, if set) is processed. -The options are consumed (see ; -and also note that SConscript files may define additional options -for the project using the &AddOption; function). -Any variable argument assignments (see below) are also consumed. -Any remaining arguments are taken as the targets to build. -Targets on the command line may be files, directories, +Command-line options (see ;) are consumed. +Any variable argument assignments are collected, and +remaining arguments are taken as the targets to build. + +Values of variables to be passed to the SConscript files +may be specified on the command line: + + +scons debug=1 + + +These variables are made available +through the &ARGUMENTS; dictionary, +and can be used in the SConscript files to modify +the build in any way: + + +if ARGUMENTS.get('debug', 0): + env = Environment(CCFLAGS = '-g') +else: + env = Environment() + + +The command-line variable arguments are also available +in the &ARGLIST; list, +indexed by their order on the command line. +This allows you to process them in order rather than by name, +if necessary. Each &ARGLIST; entry is a tuple containing +(argname, argvalue). + + +Targets on the command line may be files, directories, or phony targets defined using the &Alias; function. -The command line targets are available in the +The command line targets are made available in the &COMMAND_LINE_TARGETS; list. If no targets are specified on the command line, -scons +&scons; will build the default targets. The default targets are those specified in the SConscript files via calls to the &Default; function; if none, the default targets are @@ -299,25 +329,25 @@ target files in or below the current directory specify the current directory (.) as a command-line target: - -scons . - + +scons . + To build all target files, including any files outside of the current directory, supply a command-line target of the root directory (on POSIX systems): - -scons / - + +scons / + or the path name(s) of the volume(s) in which all the targets should be built (on Windows systems): - -scons C:\ D:\ - + +scons C:\ D:\ + A subset of a hierarchical tree may be built by remaining at the top-level directory (where the @@ -325,9 +355,9 @@ remaining at the top-level directory (where the file lives) and specifying the subdirectory as the target to build: - -scons src/subdir - + +scons src/subdir + or by changing directory and invoking scons with the @@ -338,13 +368,13 @@ file, and then builds targets relatively to the current subdirectory (see also the related and options): - -cd src/subdir -scons -u . - + +cd src/subdir +scons -u . + In all cases, more files may be built than are -requested, as scons needs to make +requested, as &scons; needs to make sure any dependent files are built. Specifying "cleanup" targets in SConscript files is not usually necessary. @@ -353,15 +383,15 @@ The flag removes all files necessary to build the specified target: - -scons -c . - + +scons -c . + to remove all target files in or under the current directory, or: - -scons -c build export - + +scons -c build export + to remove target files under build and export. @@ -374,23 +404,23 @@ Conversely, targets that would normally be removed by the invocation can be retained by calling the &NoClean; function with those targets. -scons +&scons; supports building multiple targets in parallel via a option that takes, as its argument, the number of simultaneous tasks that may be spawned: - -scons -j 4 - + +scons -j 4 + builds four targets in parallel, for example. -scons +&scons; can maintain a cache of target (derived) files that can be shared between multiple builds. When caching is enabled in a SConscript file, any target files built by -scons +&scons; will be copied to the cache. If an up-to-date target file is found in the cache, it will be retrieved from the cache instead of being rebuilt locally. @@ -405,88 +435,57 @@ command-line options. The option is useful to prevent multiple builds from trying to update the cache simultaneously. -Values of variables to be passed to the SConscript files -may be specified on the command line: - - -scons debug=1 . - - -These variables are available -through the &ARGUMENTS; dictionary, -and can be used in the SConscript files to modify -the build in any way: - - -if ARGUMENTS.get('debug', 0): - env = Environment(CCFLAGS = '-g') -else: - env = Environment() - - -The command-line variable arguments are also available -in the &ARGLIST; list, -indexed by their order on the command line. -This allows you to process them in order rather than by name, -if necessary. Each &ARGLIST; entry is a tuple -containing (argname, argvalue). -A Python IndexError exception is raised if you -try to access a list member that -does not exist. - -scons -requires either Python 2.7 or Python 3.5 or higher. -There should be no other dependencies or requirements to run -scons. +&scons; +requires Python 3.5 or higher. +There should be no other dependencies or requirements to run &scons;. + By default, -scons +&scons; searches for known programming tools on various systems and initializes itself based on what is found. On Windows systems which identify as win32, -scons +&scons; searches in order for the Microsoft Visual C++ tools, the MinGW tool chain, the Intel compiler tools, and the PharLap ETS compiler. On Windows system which identify as cygwin -(that is, if scons is invoked from a cygwin shell), +(that is, if &scons; is invoked from a cygwin shell), the order changes to prefer the GCC toolchain over the MSVC tools. On OS/2 systems, -scons +&scons; searches in order for the OS/2 compiler, the GCC tool chain, and the Microsoft Visual C++ tools, On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Oracle Solaris systems, -scons +&scons; searches for the native compiler tools (MIPSpro, Visual Age, aCC, and Forte tools respectively) and the GCC tool chain. On all other platforms, including POSIX (Linux and UNIX) platforms, -scons +&scons; searches in order for the GCC tool chain, and the Intel compiler tools. -You may, of course, override these default values -by appropriate configuration of -Environment construction variables. +These default values may be overridden +by appropriate setting of &consvars;. OPTIONS In general, -scons -supports the same command-line options as GNU -make, -and many of those supported by -cons. +&scons; +supports the same command-line options as GNU &Make; +and many of those supported by cons. + @@ -511,13 +510,13 @@ Will not remove any targets specified by the &NoClean; function. - --cache-debug=file + --cache-debug=file Print debug information about the &CacheDir; derived-file caching to the specified -file. +file. If -file +file is - (a hyphen), @@ -533,7 +532,7 @@ are being looked for in, retrieved from, or written to the Disable the derived-file caching specified by &CacheDir;. -scons +&scons; will neither retrieve files from the cache nor copy files to the cache. @@ -580,7 +579,7 @@ file was rebuilt or retrieved from the cache. - --config=mode + --config=mode This specifies how the &Configure; call should use or generate the @@ -624,10 +623,10 @@ in a system header file or compiler. If this option is specified, no configuration tests will be rerun and all results will be taken from cache. -Note that scons will still consider it an error -if --config=cache is specified +&scons; will report an error +if is specified and a necessary test does not -yet have any results in the cache. +have any results in the cache. @@ -688,7 +687,7 @@ directory. --debug=type[,type...] Debug the build process. -type +type specifies the kind of debugging info to emit. Multiple types may be specified, separated by commas. The following entries show the recognized types: @@ -737,13 +736,10 @@ files, as well as unlinking old targets before building them. --debug=explain -Print an explanation of precisely why -scons -is deciding to (re-)build any targets. -(Note: this does not print anything -for targets that are -not -rebuilt.) +Print an explanation of why &scons; +is deciding to (re-)build the targets +it selects for building. + @@ -764,9 +760,9 @@ and about the actual libraries it finds. This is generally used to find out what files are included by the sources of a given derived file: - -$ scons --debug=includes foo.o - + +$ scons --debug=includes foo.o + @@ -801,7 +797,7 @@ of the various classes used internally by SCons. --debug=pdb -Re-run SCons under the control of the +Re-run &scons; under the control of the pdb Python debugger. @@ -812,12 +808,12 @@ Python debugger. Print a line each time any target (internal or external) is prepared for building. -scons +&scons; prints this for each target it considers, even if that target is up to date (see also --debug=explain). This can help debug problems with targets that aren't being built; it shows whether -scons +&scons; is at least considering them or not. @@ -826,16 +822,16 @@ is at least considering them or not. --debug=presub Print the raw command line used to build each target -before the construction environment variables are substituted. +before the &consenv; variables are substituted. Also shows which targets are being built by this command. Output looks something like this: - -$ scons --debug=presub + +$ scons --debug=presub Building myprog.o with action(s): $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES ... - + @@ -871,12 +867,12 @@ when encountering an otherwise unexplained error. The elapsed wall-clock time spent executing those build commands -The time spent processing each file passed to the SConscript() function +The time spent processing each file passed to the &SConscriptFunc; function (When -scons +&scons; is executed without the option, @@ -886,7 +882,7 @@ executing all the build commands, due to the SCons processing that takes place in between executing each command. When -scons +&scons; is executed with the @@ -904,7 +900,7 @@ should take place in parallel.) - --diskcheck=types + --diskcheck=types Enable specific checks for whether or not there is a file on disk @@ -913,7 +909,7 @@ where the SCons configuration expects a directory and whether or not RCS or SCCS sources exist when searching for source and include files. The -types +types argument can be set to: all, to enable all checks explicitly @@ -948,13 +944,13 @@ where the SCons configuration expects a directory). - --duplicate=ORDER + --duplicate=ORDER There are three ways to duplicate files in a build tree: hard links, soft (symbolic) links and copies. The default behaviour of SCons is to prefer hard links to soft links to copies. You can specify different behaviours with this option. -ORDER +ORDER must be one of hard-soft-copy (the default), @@ -981,16 +977,16 @@ the mechanisms in the specified order. - -f file, --file=file, --makefile=file, --sconstruct=file + -f file, --file=file, --makefile=file, --sconstruct=file Use -file +file as the initial SConscript file. Multiple options may be specified, in which case -scons +&scons; will read all of the specified files. @@ -1024,10 +1020,10 @@ exit. - -I directory, --include-dir=directory + -I directory, --include-dir=directory Specifies a -directory +directory to search for imported Python modules. If several @@ -1048,26 +1044,26 @@ are used, the directories are searched in the order specified. Cache implicit dependencies. This causes -scons +&scons; to use the implicit (scanned) dependencies from the last time it was run instead of scanning the files for implicit dependencies. This can significantly speed up SCons, but with the following limitations: -scons +&scons; will not detect changes to implicit dependency search paths (e.g. -CPPPATH, LIBPATH) +CPPPATH, LIBPATH) that would ordinarily cause different versions of same-named files to be used. -scons +&scons; will miss changes in the implicit dependencies in cases where a new implicit dependency is added earlier in the implicit dependency search path (e.g. -CPPPATH, LIBPATH) +CPPPATH, LIBPATH) than a current implicit dependency with the same name. @@ -1128,8 +1124,10 @@ SCons command-line OPTIONS. b and -scons -are synonyms. +scons +are synonyms for +build. + The following SCons command-line options affect the build @@ -1235,30 +1233,28 @@ are synonyms. - + - - - An empty line repeats the last typed command. Command-line editing can be used if the readline module is available. - -$ scons --interactive + +$ scons --interactive scons: Reading SConscript files ... scons: done reading SConscript files. scons>>> build -n prog scons>>> exit - + + + - -j N, --jobs=N -Specifies the number of jobs (commands) to run simultaneously. +Specifies the maximum number of comcurrent jobs (commands) to run. If there is more than one option, the last one is effective. @@ -1318,10 +1314,10 @@ targets specified on the command line will still be processed. - --max-drift=SECONDS + --max-drift=SECONDS Set the maximum expected drift in the modification time of files to -SECONDS. +SECONDS. This value determines how long a file must be unmodified before its cached content signature will be used instead of @@ -1338,10 +1334,10 @@ no matter how old the file is. - --md5-chunksize=KILOBYTES + --md5-chunksize=KILOBYTES Set the block size used to compute MD5 signatures to -KILOBYTES. +KILOBYTES. This value determines the size of the chunks which are read in at once when computing MD5 signatures. Files below that size are fully stored in memory before performing the signature computation while bigger files are read in @@ -1408,11 +1404,11 @@ dirs to the toolpath. - --profile=file + --profile=file Run SCons under the Python profiler and save the results in the specified -file. +file. The results may be analyzed using the Python pstats module. @@ -1466,34 +1462,34 @@ Also suppresses SCons status messages. -S, --no-keep-going, --stop -Ignored for compatibility with GNU -make. +Ignored for compatibility with GNU &Make; --site-dir=dir -Uses the named dir as the site dir rather than the default +Uses the named dir as the site directory +rather than the default site_scons -dirs. This dir will get prepended to +directories. This directory will be prepended to sys.path, the module dir/site_init.py -will get loaded if it exists, and +will be loaded if it exists, and dir/site_tools -will get added to the default toolpath. +will be added to the default toolpath. The default set of site_scons -dirs used when +directories used when -is not specified depends on the system platform, as follows. Note -that the directories are examined in the order given, from most +is not specified depends on the system platform, as follows. +Directories are examined in the order given, from most generic to most specific, so the last-executed site_init.py file is the most specific one (which gives it the chance to override -everything else), and the dirs are prepended to the paths, again so -the last dir examined comes first in the resulting path. +everything else), and the directories are prepended to the paths, again so +the last directory examined comes first in the resulting path. @@ -1551,23 +1547,24 @@ $HOME/.scons/site_scons - --stack-size=KILOBYTES + --stack-size=KILOBYTES Set the size stack used to run threads to -KILOBYTES. +KILOBYTES. This value determines the stack size of the threads used to run jobs. -These are the threads that execute the actions of the builders for the +These threads execute the actions of the builders for the nodes that are out-of-date. -Note that this option has no effect unless the -num_jobs -option, which corresponds to -j and --jobs, is larger than one. Using -a stack size that is too small may cause stack overflow errors. This -usually shows up as segmentation faults that cause scons to abort +This option has no effect unless the number of concurrent +build jobs is larger than one (as set by or + on the command line or &SetOption; in a script). + + +Using a stack size that is too small may cause stack overflow errors. +This usually shows up as segmentation faults that cause scons to abort before building anything. Using a stack size that is too large will cause scons to use more memory than required and may slow down the entire -build process. - -The default value is to use a stack size of 256 kilobytes, which should +build process. +The default value is to use a stack size of 256 kilobytes, which should be appropriate for most uses. You should not need to increase this value unless you encounter stack overflow errors. @@ -1576,19 +1573,17 @@ unless you encounter stack overflow errors. -t, --touch -Ignored for compatibility with GNU -make. +Ignored for compatibility with GNU &Make;. (Touching a file to make it -appear up-to-date is unnecessary when using -scons.) +appear up-to-date is unnecessary when using &scons;.) - --taskmastertrace=file + --taskmastertrace=file Prints trace information to the specified -file +file about how the internal Taskmaster object evaluates and controls the order in which Nodes are built. A file name of @@ -1598,18 +1593,18 @@ may be used to specify the standard output. - -tree=options + --tree=options Prints a tree of the dependencies after each top-level target is built. This prints out some or all of the tree, in various formats, depending on the -options +options specified: - - + + --tree=all @@ -1648,21 +1643,22 @@ for that node can be found by searching for the relevant output higher up in the tree. - + -Multiple options may be specified, +Multiple options may be specified, separated by commas: - + # Prints only derived files, with status information: -scons --tree=derived,status +scons --tree=derived,status # Prints all dependencies of target, with status information # and pruning dependencies of already-visited Nodes: -scons --tree=all,prune,status target - +scons --tree=all,prune,status target + + + - -u, --up, --search-up @@ -1694,7 +1690,7 @@ up in. -v, --version Print the -scons +&scons; version, copyright information, list of authors, and any other relevant information. Then exit. @@ -1717,10 +1713,10 @@ after other processing. - --warn=type, --warn=no-type + --warn=type, --warn=no-type Enable or disable warnings. -type +type specifies the type of warnings to be enabled or disabled: @@ -1773,18 +1769,16 @@ These warnings are disabled by default. --warn=deprecated, --warn=no-deprecated -Enables or disables all warnings about use of +Enables or disables warnings about use of currently deprecated features. These warnings are enabled by default. -Note that the - -option does not disable warnings about absolutely all deprecated features. -Warnings for some deprecated features that have already been through -several releases with deprecation warnings -may be mandatory for a release or two -before they are officially no longer supported by SCons. -Warnings for some specific deprecated features -may be enabled or disabled individually; +Not all deprecation warnings can be disabled with the + option as some +deprecated features which are late in the deprecation +cycle may have been designated as mandatory warnings, +and these will still display. +Warnings for certain deprecated features +may also be enabled or disabled individually; see below. @@ -1793,7 +1787,7 @@ see below. --warn=duplicate-environment, --warn=no-duplicate-environment Enables or disables warnings about attempts to specify a build -of a target with two different construction environments +of a target with two different &consenvs; that use the same action. These warnings are enabled by default. @@ -1813,8 +1807,8 @@ which can yield unpredictable behavior with some compilers. Enables or disables warnings about features that will be deprecated in the future. -These warnings are disabled by default. -Enabling this warning is especially +Such warnings are disabled by default. +Enabling future deprecation warnings is recommended for projects that redistribute SCons configurations for other users to build, so that the project can be warned as soon as possible @@ -1833,18 +1827,17 @@ that may require changes to the configuration. --warn=misleading-keywords, --warn=no-misleading-keywords -Enables or disables warnings about use of the misspelled keywords +Enables or disables warnings about the use of two commonly +misspelled keywords targets and sources -when calling Builders. -(Note the last -s -characters, the correct spellings are +to &Builder; calls. The correct spelling is the +singular form, even though target and -source.) -These warnings are enabled by default. +source +can themselves refer to lists of names or nodes. @@ -1862,7 +1855,7 @@ These warnings are enabled by default. Enables or disables warnings about the feature not working when -scons +&scons; is run with the Python option or from optimized Python (.pyo) modules. @@ -1893,16 +1886,16 @@ These warnings are enabled by default. --warn=reserved-variable, --warn=no-reserved-variable Enables or disables warnings about attempts to set the -reserved construction variable names -CHANGED_SOURCES, -CHANGED_TARGETS, -TARGET, -TARGETS, -SOURCE, -SOURCES, -UNCHANGED_SOURCES +reserved &consvar; names +CHANGED_SOURCES, +CHANGED_TARGETS, +TARGET, +TARGETS, +SOURCE, +SOURCES, +UNCHANGED_SOURCES or -UNCHANGED_TARGETS. +UNCHANGED_TARGETS. These warnings are disabled by default. @@ -1920,7 +1913,7 @@ These warnings are enabled by default. --warn=target_not_build, --warn=no-target_not_built Enables or disables warnings about a build rule not building the - expected targets. These warnings are not currently enabled by default. + expected targets. These warnings are disabled by default. @@ -1947,9 +1940,10 @@ These warnings are enabled by default. - -Y repository, --repository=repository, --srcdir=repository + -Y repository, --repository=repository, --srcdir=repository -Search the specified repository for any input and target +Search the specified repository +for any input and target files not found in the local directory hierarchy. Multiple options may be specified, in which case the @@ -1967,14 +1961,14 @@ repositories are searched in the order specified. Construction Environments A &ConsEnv; is the basic means by which the SConscript files communicate build information to -scons. +&scons;. A new &consenv; is created using the -Environment +&Environment; function: - + env = Environment() - + Variables, called &ConsVars; @@ -1982,10 +1976,10 @@ may be set in a &consenv; either by specifying them as keywords when the object is created or by assigning them a value after the object is created: - + env = Environment(FOO='foo') env['BAR'] = 'bar' - + As a convenience, &consvars; may also be set or modified by the @@ -1998,16 +1992,16 @@ This is useful either if the exact content of the flags is unknown (for example, read from a control file) or if the flags are distributed to a number of &consvars;. - + env = Environment(parse_flags='-Iinclude -DEBUG -lm') - + This example adds 'include' to -CPPPATH, +CPPPATH, 'EBUG' to -CPPDEFINES, +CPPDEFINES, and 'm' to -LIBS. +LIBS. By default, a new &consenv; is initialized with a set of builder methods @@ -2017,17 +2011,17 @@ An optional platform keyword argument may be used to specify that an environment should be initialized for a different platform: - + env = Environment(platform = 'cygwin') env = Environment(platform = 'os2') env = Environment(platform = 'posix') env = Environment(platform = 'win32') - + Specifying a platform initializes the appropriate &consvars; in the environment to use and generate file names with prefixes -and suffixes appropriate for the platform. +and suffixes appropriate for that platform. Note that the win32 @@ -2036,7 +2030,7 @@ platform adds the and SystemRoot variables from the user's external environment -to the construction environment's +to the &consenv;'s ENV dictionary. This is so that any executed commands @@ -2046,16 +2040,16 @@ external CVS repository specifications like :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons) will work on Windows systems. -The platform argument may be function or callable object, -in which case the Environment() method -will call the specified argument to update -the new construction environment: +The platform argument may be a function or callable object. +in which case the &Environment; method +will call it to update +the new &consenv;: - + def my_platform(env): env['VAR'] = 'xyzzy' -env = Environment(platform = my_platform) +env = Environment(platform=my_platform) Additionally, a specific set of tools @@ -2063,9 +2057,9 @@ with which to initialize the environment may be specified using the optional keyword argument tools: - + env = Environment(tools=['msvc', 'lex']) - + The tools argument overrides @@ -2081,9 +2075,9 @@ be used to retain the default list. Non-built-in tools may be specified using the optional toolpath keyword argument: - + env = Environment(tools=['default', 'foo'], toolpath=['tools']) - + This looks for a tool specification in tools/foo.py @@ -2114,32 +2108,29 @@ Tools in the toolpath are used before any of the built-in ones. For example, adding gcc.py to the toolpath would override the built-in gcc tool. -Also note that the toolpath is -stored in the environment for use -by later calls to -Clone() -and -Tool() -methods: +The toolpath is +stored in the environment and will be +picked up by subsequent calls to the +&Clone; and &Tool; methods: - + base = Environment(toolpath=['custom_path']) derived = base.Clone(tools=['custom_tool']) derived.CustomBuilder() - + The elements of the tools list may also be functions or callable objects, in which case the Environment() method will call the specified elements -to update the new construction environment: +to update the new &consenv;: - + def my_tool(env): env['XYZZY'] = 'xyzzy' -env = Environment(tools = [my_tool]) +env = Environment(tools=[my_tool]) The individual elements of the tools list @@ -2159,7 +2150,7 @@ function can use the arguments to modify the tool's behavior by setting up the environment in different ways or otherwise changing its initialization. - + # in tools/my_tool.py: def generate(env, **kw): # Sets MY_TOOL to the value of keyword argument 'arg1' or 1. @@ -2177,7 +2168,7 @@ env = Environment(tools=['default', ('my_tool', {'arg1': 'abc'})], the environment it receives to customize the tool for different platforms. If no tool list is specified, then SCons will auto-detect the installed -tools using the PATH variable in the ENV construction variable and the +tools using the PATH variable in the ENV &consvar; and the platform name when the Environment is constructed. Changing the PATH variable after the Environment is constructed will not cause the tools to be redetected. @@ -2186,7 +2177,7 @@ be redetected. Tools which can be located within a subdirectory in the toolpath. With a nested tool name the dot represents a directory seperator - + # namespaced builder env = Environment(ENV=os.environ, tools=['SubDir1.SubDir2.SomeTool']) env.SomeTool(targets, sources) @@ -2204,13 +2195,8 @@ env.SomeTool(targets, sources) - - - - - - - + + @@ -2219,13 +2205,8 @@ env.SomeTool(targets, sources) - - - - - - - + + @@ -2234,10 +2215,10 @@ env.SomeTool(targets, sources) Builder Methods -You tell scons what to build +You tell &scons; what to build by calling Builders, functions which know to take a particular action when given files of a particular type -to produce a particular result type. scons +to produce a particular result type. &scons; defines a number of builders, and you can also write your own. Builders are attached to a &consenv; as methods, and the available builder methods are listed as @@ -2247,9 +2228,9 @@ The available builders can be displayed like this for debugging purposes: - + print("Builders:", list(env['BUILDERS'])) - + Builder methods always take two arguments: @@ -2267,7 +2248,7 @@ keyword arguments, described below. Because long lists of file names can lead to a lot of quoting, -scons +&scons; supplies a &Split; global function and a same-named environment method @@ -2287,7 +2268,7 @@ The following are equivalent examples of calling the &Program; builder method: - + env.Program('bar', ['bar.c', 'foo.c']) env.Program('bar', Split('bar.c foo.c')) env.Program('bar', env.Split('bar.c foo.c')) @@ -2295,7 +2276,7 @@ env.Program(source=['bar.c', 'foo.c'], target='bar') env.Program(target='bar', source=Split('bar.c foo.c')) env.Program(target='bar', source=env.Split('bar.c foo.c')) env.Program('bar', source='bar.c foo.c'.split()) - + Python follows the POSIX pathname convention for path @@ -2311,15 +2292,15 @@ from the starting point, which is the top of the directory tree for an absolute path and the current directory for a relative path. -scons recognizes a third way to specify +&scons; recognizes a third way to specify path strings: if the string begins with the # character it is -top-relative - it works like a relative path but the +top-relative - it works like a relative path but the search follows down from the directory containing the top-level &SConstruct; rather than -from the current directory (the # is allowed +from the current directory. The # is allowed to be followed by a pathname separator, which is ignored if -found in that position). +found in that position. Top-relative paths only work in places where &scons; will interpret the path (see some examples below). To be used in other contexts the string will need to be converted @@ -2335,7 +2316,7 @@ file currently being processed as the "current directory". Examples: - + # The comments describing the targets that will be built # assume these calls are in a SConscript file in the # a subdirectory named "subdir". @@ -2356,6 +2337,11 @@ env.Program('#/bar', 'bar.c') # Builds the program "other/foo" (relative to the top-level # SConstruct directory) from "subdir/foo.c": env.Program('#other/foo', 'foo.c') + +# This will not work, only SCons interfaces understand '#', +# os.path.exists is pure Python: +if os.path.exists('#inc/foo.h'): + env.Append(CPPPATH='#inc') When the target shares the same base name @@ -2363,7 +2349,7 @@ as the source and only the suffix varies, and if the builder method has a suffix defined for the target file type, then the target argument may be omitted completely, and -scons +&scons; will deduce the target file name from the source file name. The following examples all build the @@ -2375,12 +2361,12 @@ or (on Windows systems) from the bar.c source file: - + env.Program(target='bar', source='bar.c') env.Program('bar', source='bar.c') env.Program(source='bar.c') env.Program('bar.c') - + As a convenience, a srcdir @@ -2402,46 +2388,46 @@ and src/f2.c: - + env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src') - + It is possible to override (replace or add) -construction variables when calling a +&consvars; when calling a builder method by passing them as keyword arguments. These overrides will only be in effect when building that target, and will not affect other parts of the build. For example, if you want to specify some libraries needed by just one program: - + env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) - + or generate a shared library with a non-standard suffix: - + env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx', LIBSUFFIXES=['.ocx']) - + -(Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set -if you want SCons to search automatically +Note that both the $SHLIBSUFFIX and $LIBSUFFIXES +variables must be set if you want SCons to search automatically for dependencies on the non-standard library names; -see the descriptions of these variables, below, for more information.) +see the descriptions of these variables, below, for more information. It is also possible to use the parse_flags keyword argument in an override, to merge command-line style arguments -into the appropriate construction variables +into the appropriate &consvars; (see &f-link-env-MergeFlags;). - + env = Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm') - + This example adds 'include' to CPPPATH, @@ -2451,20 +2437,20 @@ and 'm' to LIBS. Although the builder methods defined by -scons +&scons; are, in fact, -methods of a construction environment object, +methods of a &consenv; object, they may also be called without an explicit environment: - + Program('hello', 'hello.c') SharedLibrary('word', 'word.cpp') - + In this case, the methods are called internally using a default construction environment that consists of the tools and values that -scons +&scons; has determined are appropriate for the local system. Builder methods that can be called without an explicit @@ -2472,9 +2458,9 @@ environment may be called from custom Python modules that you import into an SConscript file by adding the following to the Python module: - + from SCons.Script import * - + All builder methods return a list-like object containing Nodes that will be built. @@ -2492,10 +2478,10 @@ For example, if it were necessary to add a specific preprocessor define when compiling one specific object file: - + bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') -env.Program(source = ['foo.c', bar_obj_list, 'main.c']) - +env.Program(source=['foo.c', bar_obj_list, 'main.c']) + Using a Node in this way makes for a more portable build @@ -2503,41 +2489,39 @@ by avoiding having to specify a platform-specific object suffix when calling the &Program; builder method. -Note that builder calls will automatically "flatten" -the source and target file lists, -so it's all right to have the bar_obj_list -returned by the &StaticObject; call -in the middle of the source file list. +Builder calls will automatically "flatten" +lists passed as source and target, so they are free to +contain elements which are themselves lists, such as +bar_obj_list +returned by the &StaticObject; call above. If you need to manipulate a list of lists returned by builders -directly using Python, -you can either build the list by hand: +directly in Python code, +you can either build a new list by hand: - + foo = Object('foo.c') bar = Object('bar.c') objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o'] for object in objects: print(str(object)) - + Or you can use the &Flatten; -function supplied by scons +function supplied by &scons; to create a list containing just the Nodes, which may be more convenient: - + foo = Object('foo.c') bar = Object('bar.c') objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o']) for object in objects: print(str(object)) - + -Note also that because builder calls return +SCons builder calls return a list-like object, not an actual Python list, -you should -not -use the Python add +so it is not appropriate to use the Python add operator (+ or +=) to append builder results to a Python list. Because the list and the object are different types, @@ -2553,29 +2537,27 @@ Instead, use the Python list method to make sure the list is updated in-place. Example: - + object_files = [] -# Do NOT use += as follows: -# +# Do NOT use += here: # object_files += Object('bar.c') # # It will not update the object_files list in place. # # Instead, use the list extend method: object_files.extend(Object('bar.c')) - - + The path name for a Node's file may be used by passing the Node to Python's builtin str function: - + bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') print("The path to bar_obj is:", str(bar_obj_list[0])) - + Note again that because the Builder call returns a list, we have to access the first element in the list @@ -2601,7 +2583,7 @@ and is non-zero, then scons will change to the target file's directory. - + # scons will change to the "sub" subdirectory # before executing the "cp" command. env.Command('sub/dir/foo.out', 'sub/dir/foo.in', @@ -2614,13 +2596,13 @@ env.Command('sub/dir/foo.out', 'sub/dir/foo.in', env.Command('sub/dir/foo.out', 'sub/dir/foo.in', "cp foo.in foo.out", chdir=1) - + Note that scons will not automatically modify its expansion of -construction variables like +&consvars; like $TARGET and $SOURCE @@ -2641,7 +2623,7 @@ and to use just the filename portion of the targets and source. -scons +&scons; predefines the following builder methods. Depending on the setup of a particular &consenv; and on the type and software @@ -2653,13 +2635,8 @@ not all builders may be available to that - - - - - - - + + @@ -2667,14 +2644,9 @@ not all builders may be available to that - - - - - - - - + + + @@ -2685,10 +2657,10 @@ targets of builder methods automatically depend on their sources. An explicit dependency can be specified using the Depends -method of a construction environment (see below). +method of a &consenv; (see below). In addition, -scons +&scons; automatically scans source files for various programming languages, so the dependencies do not need to be specified explicitly. @@ -2736,44 +2708,48 @@ object. Methods and Functions To Do Things In addition to Builder methods, -scons -provides a number of other construction environment methods +&scons; +provides a number of other &consenv; methods and global functions to manipulate the build configuration. -Usually, a construction environment method +Usually, a &consenv; method and global function with the same name both exist for convenience. In the following list, the global function is documented like: - + + Function(arguments) - -and the construction environment method looks like: - + + +and the &consenv; method looks like: + + env.Function(arguments) - + + If you can call the function in both ways, then both forms are listed. The global function and same-named -construction environment method +&consenv; method provide almost identical functionality, with a couple of exceptions. -First, many of the construction environment methods affect only that -construction environment, while the global function has a +First, many of the &consenv; methods affect only that +&consenv;, while the global function has a global effect. Second, where appropriate, -calling the functionality through a construction environment will -substitute construction variables into +calling the functionality through a &consenv; will +substitute &consvars; into any supplied strings, while the global function doesn't have the -context of a construction environment to pick variables from, +context of a &consenv; to pick variables from, so it cannot perform the substitution. For example: - + env = Environment(FOO = 'foo') Default('$FOO') env.Default('$FOO') - + In the above example, the first call to the global @@ -2783,39 +2759,34 @@ function will actually add a target named to the list of default targets, while the second call to the env.Default() -construction environment method +&consenv; method will expand the value and add a target named foo to the list of default targets. -For more on construction variable expansion, +For more on &consvar; expansion, see the next section on -construction variables. +&consvars;. Global functions may be called from custom Python modules that you import into an SConscript file by adding the following import to the Python module: - + from SCons.Script import * - + -Construction environment methods +&Consenv; methods and global functions supported by -scons +&scons; include: - - - - - - - - + + + @@ -2823,14 +2794,9 @@ include: - - - - - - - - + + + @@ -2839,7 +2805,7 @@ include: SConscript Variables In addition to the global functions and methods, -scons +&scons; supports a number of Python variables that can be used in SConscript files to affect how you want the build to be performed. @@ -2847,11 +2813,10 @@ These variables may be accessed from custom Python modules that you import into an SConscript file by adding the following to the Python module: - + from SCons.Script import * - + - ARGLIST @@ -2877,18 +2842,17 @@ of the tuple, respectively. Example: - + print("first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]) print("second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]) third_tuple = ARGLIST[2] print("third keyword, value =", third_tuple[0], third_tuple[1]) for key, value in ARGLIST: # process key and value - - - + + ARGUMENTS @@ -2906,27 +2870,33 @@ dictionary. Example: - + if ARGUMENTS.get('debug', 0): env = Environment(CCFLAGS = '-g') else: env = Environment() - - - + + BUILD_TARGETS A list of the targets which -scons -will actually try to build, -regardless of whether they were specified on -the command line or via the &Default; -function or method -(but empty if neither -command line targets or &Default; calls are present). +&scons; +has been asked to build. +The contents will be either those targets listed +on the command line, or, if none, those targets set +via calls to the &Default; function or method. +It does +not +contain any not-specified dependent targets that &scons; +selects for building as a result of making the sure the +specified targets are up to date. +The list is empty if neither +command line targets or &Default; calls are present. + + The elements of this list may be strings or nodes, so you should run the list through the Python @@ -2941,60 +2911,45 @@ the contents of the list may change on each successive call to Default(). See the -DEFAULT_TARGETS -list, below, +&DEFAULT_TARGETS; list, below, for additional information. Example: - + if 'foo' in BUILD_TARGETS: print("Don't forget to test the `foo' program!") if 'special/program' in BUILD_TARGETS: SConscript('special') - + -Note that the -BUILD_TARGETS -list only contains targets listed -on the command line or via calls to the -Default() -function or method. -It does -not -contain all dependent targets that will be built as -a result of making the sure the explicitly-specified -targets are up to date. - - COMMAND_LINE_TARGETS A list of the targets explicitly specified on -the command line. +the command line. If there are command line targets, +this list will have the same contents as &BUILD_TARGETS;. If there are no targets specified on the command line, -the list is empty. +the list is empty. The elemnts of this list are strings. This can be used, for example, to take specific actions only -when a certain target or targets -is explicitly being built. +when certain targets is explicitly being built. Example: - + if 'foo' in COMMAND_LINE_TARGETS: print("Don't forget to test the `foo' program!") if 'special/program' in COMMAND_LINE_TARGETS: SConscript('special') - - - + + DEFAULT_TARGETS @@ -3002,7 +2957,9 @@ if 'special/program' in COMMAND_LINE_TARGETS: nodes that have been specified using the Default() -function or method. +function or method. If there are no command line +targets, this list will have the same contents as +&BUILD_TARGETS;. The elements of the list are nodes, so you need to run them through the Python str @@ -3010,14 +2967,11 @@ function to get at the path name for each Node. Example: - + print(str(DEFAULT_TARGETS[0])) if 'foo' in [str(t) for t in DEFAULT_TARGETS]: print("Don't forget to test the `foo' program!") - - - - + The contents of the DEFAULT_TARGETS @@ -3025,7 +2979,7 @@ list change on on each successive call to the Default() function: - + print([str(t) for t in DEFAULT_TARGETS]) # originally [] Default('foo') print([str(t) for t in DEFAULT_TARGETS]) # now a node ['foo'] @@ -3033,7 +2987,7 @@ Default('bar') print([str(t) for t in DEFAULT_TARGETS]) # now a node ['foo', 'bar'] Default(None) print([str(t) for t in DEFAULT_TARGETS]) # back to [] - + Consequently, be sure to use DEFAULT_TARGETS @@ -3044,6 +2998,9 @@ or else simply be careful of the order of these statements in your SConscript files so that you don't look for a specific default target before it's actually been added to the list. + + + @@ -3064,30 +3021,25 @@ default target before it's actually been added to the list. -A construction environment has an associated dictionary of -construction variables +A &consenv; has an associated dictionary of +&consvars; that are used by built-in or user-supplied build rules. -Construction variables must follow the same rules for +&Consvars; must follow the same rules for Python identifiers: the initial character must be an underscore or letter, followed by any number of underscores, letters, or digits. -A number of useful construction variables are automatically defined by -scons for each supported platform, and additional construction variables +A number of useful &consvars; are automatically defined by +scons for each supported platform, and additional &consvars; can be defined by the user. The following is a list of the automatically -defined construction variables: +defined &consvars;: - - - - - - - + + @@ -3096,54 +3048,49 @@ defined construction variables: - - - - - - - + + -Construction variables can be retrieved and set using the +&Consvars; can be retrieved and set using the Dictionary -method of the construction environment: +method of the &consenv;: - + cvars = env.Dictionary() cvars["CC"] = "cc" - + or using the key lookup operator [] -directly on the construction environment: +directly on the &consenv;: - + env["CC"] = "cc" - + -Construction variables can also be passed to the construction environment +&Consvars; can also be passed to the &consenv; constructor: - + env = Environment(CC="cc") - + -or when copying a construction environment using the +or when copying a &consenv; using the Clone method: - + env2 = env.Clone(CC="cl.exe") - + Configure Contexts -scons +&scons; supports configure contexts, an integrated mechanism similar to the @@ -3151,7 +3098,7 @@ various AC_CHECK macros in GNU autoconf for testing for the existence of C header files, libraries, etc. In contrast to autoconf, -scons +&scons; does not maintain an explicit cache of the tested values, but uses its normal dependency tracking to keep the checked values up to date. However, users may override this behaviour with the @@ -3196,10 +3143,9 @@ file. You can specify the same config.h file in multiple calls to Configure, -in which case -scons +in which case &SCons; will concatenate all results in the specified file. -Note that SCons +Note that &SCons; uses its normal dependency checking to decide if it's necessary to rebuild the specified @@ -3235,10 +3181,10 @@ or arguments (or both) to avoid unnecessary test execution. - + A created Configure instance has the following associated methods: @@ -3261,9 +3207,9 @@ Only one context should be active at a time. The following Checks are predefined. (This list will likely grow larger as time goes by and developers contribute new useful tests.) - + SConf.CheckHeader(context, header, [include_quotes, language]) sconf.CheckHeader(header, [include_quotes, language]) @@ -3294,9 +3240,9 @@ or C++ and selects the compiler to be used for the check. Returns 1 on success and 0 on failure. - + SConf.CheckCHeader(context, header, [include_quotes]) sconf.CheckCHeader(header, [include_quotes]) @@ -3322,9 +3268,9 @@ a two character string, where the first character denotes the opening quote and the second character denotes the closing quote (both default to \N'34'). Returns 1 on success and 0 on failure. - + SConf.CheckCXXHeader(context, header, [include_quotes]) sconf.CheckCXXHeader(header, [include_quotes]) @@ -3350,9 +3296,9 @@ a two character string, where the first character denotes the opening quote and the second character denotes the closing quote (both default to \N'34'). Returns 1 on success and 0 on failure. - + SConf.CheckFunc(context,, function_name, [header, language]) sconf.CheckFunc(function_name, [header, language]) @@ -3370,12 +3316,14 @@ of the test file that will be compiled to check if the function exists; the default is: - + + #ifdef __cplusplus extern "C" #endif char function_name(); - + + The optional language argument should be @@ -3384,9 +3332,9 @@ or C++ and selects the compiler to be used for the check; the default is "C". - + SConf.CheckLib(context, [library, symbol, header, language, autoadd=1]) sconf.CheckLib([library, symbol, header, language, autoadd=1]) @@ -3399,7 +3347,7 @@ If the value of autoadd is 1 and the library provides the specified symbol, -appends the library to the LIBS construction environment variable. +appends the library to the LIBS &consvar; library may also be None (the default), in which case @@ -3430,9 +3378,9 @@ The default value for autoadd is 1. This method returns 1 on success and 0 on error. - + SConf.CheckLibWithHeader(context, library, header, language, [call, autoadd]) sconf.CheckLibWithHeader(library, header, language, [call, autoadd]) @@ -3468,9 +3416,9 @@ can link against the specified autoadd specifies whether to add the library to the environment (only if the check succeeds). This method returns 1 on success and 0 on error. - + SConf.CheckType(context, type_name, [includes, language]) sconf.CheckType(type_name, [includes, language]) @@ -3493,16 +3441,18 @@ or and selects the compiler to be used for the check; the default is "C". Example: - + + sconf.CheckType('foo_type', '#include "my_types.h"', 'C++') - + + Configure.CheckCC(self) -Checks whether the C compiler (as defined by the CC construction variable) works +Checks whether the C compiler (as defined by the CC &consvar;) works by trying to compile a small source file. By default, SCons only detects if there is a program with the correct name, not @@ -3511,26 +3461,26 @@ if it is a functioning compiler. This uses the exact same command than the one used by the object builder for C source file, so it can be used to detect if a particular compiler flag works or not. - + Configure.CheckCXX(self) -Checks whether the C++ compiler (as defined by the CXX construction variable) +Checks whether the C++ compiler (as defined by the CXX &consvar;) works by trying to compile a small source file. By default, SCons only detects if there is a program with the correct name, not if it is a functioning compiler. This uses the exact same command than the one used by the object builder for CXX source files, so it can be used to detect if a particular compiler flag works or not. - + Configure.CheckSHCC(self) -Checks whether the C compiler (as defined by the SHCC construction variable) works +Checks whether the C compiler (as defined by the SHCC &consvar;) works by trying to compile a small source file. By default, SCons only detects if there is a program with the correct name, not if it is a functioning compiler. @@ -3538,13 +3488,13 @@ there is a program with the correct name, not if it is a functioning compiler. - + Configure.CheckSHCXX(self) -Checks whether the C++ compiler (as defined by the SHCXX construction variable) +Checks whether the C++ compiler (as defined by the SHCXX &consvar;) works by trying to compile a small source file. By default, SCons only detects if there is a program with the correct name, not if it is a functioning compiler. @@ -3552,13 +3502,12 @@ if there is a program with the correct name, not if it is a functioning compiler CXX source files, so it can be used to detect if a particular compiler flag works or not. This does not check whether the object code can be used to build a shared library, only that the compilation (not link) succeeds. - Example of a typical Configure usage: - + env = Environment() conf = Configure( env ) if not conf.CheckCHeader( 'math.h' ): @@ -3569,7 +3518,7 @@ if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', # do stuff for qt - usage, e.g. conf.env.Append( CPPFLAGS = '-DWITH_QT' ) env = conf.Finish() - + @@ -3603,15 +3552,16 @@ argument should be an integer. If this argument is used, the function will only check whether the type given in type_name has the expected size (in bytes). -For example, -CheckTypeSize('short', expect = 2) -will return success only if short is two bytes. +For example, - - + +CheckTypeSize('short', expect = 2) + +will return success only if short is two bytes. + SConf.CheckDeclaration(context, symbol, [includes, language]) sconf.CheckDeclaration(symbol, [includes, language]) @@ -3632,9 +3582,9 @@ or C++ and selects the compiler to be used for the check; the default is "C". - + SConf.Define(context, symbol, [value, comment]) sconf.Define(symbol, [value, comment]) @@ -3648,14 +3598,13 @@ with the optional value and the optional comment comment. - Examples: - + env = Environment() conf = Configure( env ) @@ -3671,7 +3620,7 @@ conf.Define('A_SYMBOL', 1) Be careful about quoting string values, though: - + env = Environment() conf = Configure( env ) @@ -3687,7 +3636,7 @@ conf.Define('A_SYMBOL', '"YA"') For comment: - + env = Environment() conf = Configure( env ) @@ -3719,9 +3668,9 @@ These CheckContext instances define the following methods: Usually called before the check is started. text will be displayed to the user, e.g. 'Checking for library X...' - + CheckContext.Result(self,, res) @@ -3731,9 +3680,9 @@ will be displayed to the user, e.g. 'Checking for library X...' can be either an integer or a string. In the former case, 'yes' (res != 0) or 'no' (res == 0) is displayed to the user, in the latter case the given string is displayed. - + CheckContext.TryCompile(self, text, extension) @@ -3744,9 +3693,9 @@ given string is displayed. can be compiled using the environment's Object builder. Returns 1 on success and 0 on failure. - + CheckContext.TryLink(self, text, extension) @@ -3757,9 +3706,9 @@ builder. Returns 1 on success and 0 on failure. can be compiled using the environment's Program builder. Returns 1 on success and 0 on failure. - + CheckContext.TryRun(self, text, extension) @@ -3781,9 +3730,9 @@ program. If the program fails execution (its return status is non-zero), then (0, '') is returned. - + CheckContext.TryAction(self, action, [text, extension]) @@ -3797,7 +3746,7 @@ with an optional source file (contents ) can be executed. action may be anything which can be converted to a -scons +&scons; Action. On success, (1, outputStr) @@ -3807,9 +3756,9 @@ is the content of the target file. On failure (0, '') is returned. - + CheckContext.TryBuild(self, builder, [text, extension]) @@ -3824,13 +3773,12 @@ of a source file with optional this method returns 1 on success and 0 on failure. In addition, self.lastTarget is set to the build target node, if the build was successful. - Example for implementing and using custom tests: - + def CheckQt(context, qtdir): context.Message( 'Checking for qt ...' ) lastLIBS = context.env['LIBS'] @@ -3866,14 +3814,16 @@ some variables must be specified at build time. For example, libraries needed for the build may be in non-standard locations, or site-specific compiler options may need to be passed to the compiler. -scons +&scons; provides a Variables -object to support overriding construction variables +object to support overriding &consvars; on the command line: - -$ scons VARIABLE=foo - + + +scons VARIABLE=foo + + The variable values can also be specified in a text-based SConscript file. To create a Variables object, call the Variables() function: @@ -3881,7 +3831,7 @@ To create a Variables object, call the Variables() function: Variables([files], [args]) -This creates a Variables object that will read construction variables from +This creates a Variables object that will read &consvars; from the file or list of filenames specified in files. If no files are specified, @@ -3900,11 +3850,11 @@ dictionary that holds variables specified on the command line. Example: - + vars = Variables('custom.py') vars = Variables('overrides.py', ARGUMENTS) vars = Variables(None, {FOO:'expansion', BAR:7}) - + Variables objects have the following methods: @@ -3913,7 +3863,7 @@ vars = Variables(None, {FOO:'expansion', BAR:7}) Add(key, [help, default, validator, converter]) -This adds a customizable construction variable to the Variables object. +This adds a customizable &consvar; to the Variables object. key is the name of the variable. help @@ -3923,9 +3873,9 @@ is the default value of the variable; if the default value is None and there is no explicit value specified, -the construction variable will +the &consvar; will not -be added to the construction environment. +be added to the &consenv;. validator is called to validate the value of the variable, and should take three arguments: key, value, and environment. @@ -3945,7 +3895,7 @@ and then added to the environment. Examples: - + vars.Add('CC', 'The C compiler') def validate_color(key, val, env): @@ -3953,14 +3903,14 @@ def validate_color(key, val, env): raise Exception("Invalid color value '%s'" % val) vars.Add('COLOR', validator=valid_color) - + AddVariables(list) A wrapper script that adds -multiple customizable construction variables +multiple customizable &consvars; to a Variables object. list is a list of tuple or list objects @@ -3969,23 +3919,24 @@ for an individual call to the Add method. - + opt.AddVariables( ('debug', '', 0), ('CC', 'The C compiler'), ('VALIDATE', 'An option for testing validation', 'notset', validator, None), ) - + + Update(env, [args]) -This updates a construction environment +This updates a &consenv; env -with the customized construction variables. +with the customized &consvars;. Any specified variables that are not configured for the Variables object @@ -3998,9 +3949,10 @@ method, below. but is called indirectly by passing the Variables object to the Environment() function: - + env = Environment(variables=vars) - + + @@ -4009,13 +3961,13 @@ env = Environment(variables=vars) when the &Variables; object was created are executed as Python scripts, and the values of (global) Python variables set in the file -are added to the construction environment. +are added to the &consenv;. Example: - + CC = 'my_cc' - + @@ -4028,14 +3980,15 @@ with which the Variables object was initialized, but for which the Variables object was not configured. - + env = Environment(variables=vars) for key, value in vars.UnknownVariables(): print("unknown variable: %s=%s" % (key, value)) - + + Save(filename, env) @@ -4045,23 +3998,24 @@ that can be used on the next invocation to automatically load the current settings. This method combined with the Variables method can be used to support caching of variables between runs. - + env = Environment() vars = Variables(['variables.cache', 'custom.py']) vars.Add(...) vars.Update(env) vars.Save('variables.cache', env) - + + GenerateHelpText(env, [sort]) This generates help text documenting the customizable construction variables suitable to passing in to the Help() function. env -is the construction environment that will be used to get the actual values +is the &consenv; that will be used to get the actual values of customizable variables. Calling with an optional sort @@ -4080,13 +4034,14 @@ function). Optionally a Boolean value of True for sort will cause a standard alphabetical sort to be performed - + Help(vars.GenerateHelpText(env)) Help(vars.GenerateHelpText(env, sort=cmp)) - + + FormatVariableHelpText(env, opt, help, default, actual) @@ -4100,14 +4055,14 @@ method to create the returned help text. It may be overridden with your own function that takes the arguments specified above and returns a string of help text formatted to your liking. -Note that the +Note that GenerateHelpText() will not put any blank lines or extra characters in between the entries, so you must add those characters to the returned string if you want the entries separated. - + def my_format(env, opt, help, default, actual): fmt = "\n%s: default=%s actual=%s (%s)\n" return fmt % (opt, default. actual, help) @@ -4115,13 +4070,13 @@ vars.FormatVariableHelpText = my_format To make it more convenient to work with customizable Variables, -scons +&scons; provides a number of functions that make it easy to set up various types of Variables: - + BoolVariable(key, help, default) @@ -4155,9 +4110,9 @@ and the values and none as false. - + EnumVariable(key, help, default, allowed_values, [map, ignorecase]) @@ -4205,9 +4160,9 @@ then values will be matched case-insensitive, and all input values will be converted to lower case. - + ListVariable(key, help, default, names, [,map]) @@ -4242,9 +4197,9 @@ input values into specific legal values in the names list. - + PackageVariable(key, help, default) @@ -4283,9 +4238,9 @@ The option will also support the values or disable to disable use of the specified option. - + PathVariable(key, help, default, [validator]) @@ -4334,10 +4289,9 @@ the name of the variable to be set; the specified value being checked; and env, -the construction environment) +the &consenv;) and should raise an exception if the specified value is not acceptable. - @@ -4348,25 +4302,27 @@ in a single call to the AddVariables method: - + vars.AddVariables( - BoolVariable('warnings', 'compilation with -Wall and similiar', 1), - EnumVariable('debug', 'debug output and symbols', 'no' - allowed_values=('yes', 'no', 'full'), - map={}, ignorecase=0), # case sensitive - ListVariable('shared', - 'libraries to build as shared libraries', - 'all', - names = list_of_libs), - PackageVariable('x11', - 'use X11 installed here (yes = search some places)', - 'yes'), - PathVariable('qtdir', 'where the root of Qt is installed', qtdir), - PathVariable('foopath', 'where the foo library is installed', foopath, - PathVariable.PathIsDir), - + BoolVariable("warnings", "compilation with -Wall and similiar", 1), + EnumVariable( + "debug", + "debug output and symbols", + "no", + allowed_values=("yes", "no", "full"), + map={}, + ignorecase=0, # case sensitive + ), + ListVariable( + "shared", "libraries to build as shared libraries", "all", names=list_of_libs + ), + PackageVariable("x11", "use X11 installed here (yes = search some places)", "yes"), + PathVariable("qtdir", "where the root of Qt is installed", qtdir), + PathVariable( + "foopath", "where the foo library is installed", foopath, PathVariable.PathIsDir + ), ) - + @@ -4420,7 +4376,7 @@ File or Directory Node. For example: - + # Get the current build dir's path, relative to top. Dir('.').path # Current dir's absolute path @@ -4432,7 +4388,7 @@ File('foo.c').srcnode().path # source path of the given source file. # Builders also return File objects: foo = env.Program('foo.c') print("foo will be built in", foo.path) - + File and Directory Node objects have methods to create @@ -4517,7 +4473,7 @@ within the parent directory of For example: - + # Get a Node for a file within a directory incl = Dir('include') f = incl.File('header.h') @@ -4535,7 +4491,7 @@ docs = Dir('docs') html = docs.Dir('html') index = html.File('index.html') css = index.File('app.css') - + @@ -4543,22 +4499,22 @@ css = index.File('app.css') EXTENDING SCONS Builder Objects -scons +&scons; can be extended to build different types of targets by adding new Builder objects -to a construction environment. +to a &consenv;. In general, you should only need to add a new Builder object when you want to build a new type of file or other external target. If you just want to invoke a different compiler or other tool to build a Program, Object, Library, or any other type of output file for which -scons +&scons; already has an existing Builder, it is generally much easier to use those existing Builders -in a construction environment -that sets the appropriate construction variables +in a &consenv; +that sets the appropriate &consvars; (CC, LINK, etc.). Builder objects are created @@ -4567,7 +4523,7 @@ using the function. The Builder -function accepts the following arguments: +function accepts the following keyword arguments: @@ -4595,44 +4551,39 @@ takes three arguments: target - a list of target nodes, env -- the construction environment. +- the &consenv;. +The +action +and +generator +arguments must not both be used for the same Builder. + prefix The prefix that will be prepended to the target file name. -This may be specified as a: - -
- -* -string, - - -* -callable object -- a function or other callable that takes -two arguments (a construction environment and a list of sources) -and returns a prefix, - - -* -dictionary -- specifies a mapping from a specific source suffix (of the first +This may be specified as: + + + a string + a callable object - +a function or other callable that takes +two arguments (a &consenv; and a list of sources) +and returns a prefix + a dictionary - +specifies a mapping from a specific source suffix (of the first source specified) to a corresponding target prefix. Both the source suffix and target prefix specifications may use environment variable substitution, and the target prefix (the 'value' entries in the dictionary) may also be a callable object. The default target prefix -may be indicated by a dictionary entry with a key value of None. -
+may be indicated by a dictionary entry with a key value of None. - - + - - + b = Builder("build_it < $SOURCE > $TARGET", prefix = "file-") @@ -4645,21 +4596,22 @@ b = Builder("build_it < $SOURCE > $TARGET", suffix = { None: "file-", "$SRC_SFX_A": gen_prefix }) + + - suffix The suffix that will be appended to the target file name. This may be specified in the same manner as the prefix above. If the suffix is a string, then -scons +&scons; will append a '.' to the beginning of the suffix if it's not already there. The string returned by callable object (or obtained from the dictionary) is untouched and must append its own '.' to the beginning if one is desired. - + b = Builder("build_it < $SOURCE > $TARGET" suffix = "-file") @@ -4672,14 +4624,14 @@ b = Builder("build_it < $SOURCE > $TARGET", suffix = { None: ".sfx1", "$SRC_SFX_A": gen_suffix }) - + ensure_suffix When set to any true value, causes -scons +&scons; to add the target suffix specified by the suffix keyword to any target strings @@ -4687,7 +4639,7 @@ that have a different suffix. (The default behavior is to leave untouched any target file name that looks like it already has any suffix.) - + b1 = Builder("build_it < $SOURCE > $TARGET" suffix = ".out") b2 = Builder("build_it < $SOURCE > $TARGET" @@ -4702,18 +4654,19 @@ env.B1('foo.txt', 'foo.in') # Builds "bar.txt.out" because ensure_suffix is set. env.B2('bar.txt', 'bar.in') - + + src_suffix The expected source file name suffix. This may be a string or a list of strings. - + target_scanner @@ -4724,14 +4677,14 @@ This keyword argument should be used for Scanner objects that find implicit dependencies based only on the target file -and the construction environment, +and the &consenv;, not for implicit dependencies based on source files. (See the section "Scanner Objects" below, for information about creating Scanner objects.) - + source_scanner @@ -4752,13 +4705,13 @@ indicate that this Builder should scan directory trees for on-disk changes to files that -scons +&scons; does not know about from other Builder or function calls. (See the section "Scanner Objects" below, for information about creating your own Scanner objects.) - + target_factory @@ -4777,13 +4730,12 @@ or directory target. Example: - + MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir) env = Environment() env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder}) env.MakeDirectory('new_directory', []) - - + Note that the call to the MakeDirectory Builder needs to specify an empty source list @@ -4793,9 +4745,9 @@ and would try to deduce the target name from it, which in the absence of an automatically-added prefix or suffix would lead to a matching target and source name and a circular dependency. - + source_factory @@ -4814,15 +4766,15 @@ or directories (or both) as sources. Example: - + CollectBuilder = Builder(action=my_mkdir, source_factory=Entry) env = Environment() env.Append(BUILDERS = {'Collect':CollectBuilder}) env.Collect('archive', ['directory_name', 'file_name']) - + emitter @@ -4830,7 +4782,7 @@ env.Collect('archive', ['directory_name', 'file_name']) lists before dependencies are established and the target(s) are actually built. emitter -can also be a string containing a construction variable to expand +can also be a string containing a &consvar; to expand to an emitter function or list of functions, or a dictionary mapping source file suffixes to emitter functions. @@ -4845,14 +4797,14 @@ takes three arguments: target - a list of target nodes, env -- the construction environment. +- the &consenv;. An emitter must return a tuple containing two lists, the list of targets to be built by this builder, and the list of sources for this builder. Example: - + def e(target, source, env): return (target + ['foo.foo'], source + ['foo.src']) @@ -4867,12 +4819,12 @@ def e2(target, source, env): b = Builder("my_build < $TARGET > $SOURCE", emitter = [e, e2]) -# Calling an emitter function through a construction variable. +# Calling an emitter function through a &consvar;. env = Environment(MY_EMITTER = e) b = Builder("my_build < $TARGET > $SOURCE", emitter = '$MY_EMITTER') -# Calling a list of emitter functions through a construction variable. +# Calling a list of emitter functions through a &consvar;. env = Environment(EMITTER_LIST = [e, e2]) b = Builder("my_build < $TARGET > $SOURCE", emitter = '$EMITTER_LIST') @@ -4887,9 +4839,9 @@ b = Builder("my_build < $TARGET > $SOURCE", emitter = {'.suf1' : e_suf1, '.suf2' : e_suf2}) - + multi @@ -4901,22 +4853,22 @@ files to the target; it is not allowed to change the environment associated with the target, specify additional environment overrides, or associate a different builder with the target. - + env -A construction environment that can be used +A &consenv; that can be used to fetch source code using this Builder. (Note that this environment is not used for normal builds of normal target files, which use the environment that was used to call the Builder for the target file.) - + generator @@ -4934,7 +4886,7 @@ takes four arguments: target - a list of target nodes, env -- the construction environment, +- the &consenv;, for_signature - a Boolean value that specifies whether the generator is being called @@ -4942,7 +4894,7 @@ for generating a build signature (as opposed to actually executing the command). Example: - + def g(source, target, env, for_signature): return [["gcc", "-c", "-o"] + target + source] @@ -4955,18 +4907,18 @@ b = Builder(generator=g) and action arguments must not both be used for the same Builder. - + src_builder Specifies a builder to use when a source file name suffix does not match any of the suffixes of the builder. Using this argument produces a multi-stage builder. - + single_source @@ -4974,18 +4926,9 @@ multi-stage builder. more than one source file without target files results in implicitly calling the builder multiple times (once for each source given). Giving multiple source files together with target files results in a UserError exception. - - -The -generator -and -action -arguments must not both be used for the same Builder. - - source_ext_match @@ -5005,7 +4948,7 @@ or some other non-true value. When source_ext_match is disable, -scons +&scons; will use the suffix of the first specified source file to select the appropriate action from the action @@ -5015,27 +4958,28 @@ dictionary. the setting of source_ext_match prevents -scons +&scons; from exiting with an error due to the mismatched suffixes of foo.in and foo.extra. - + b = Builder(action={'.in' : 'build $SOURCES > $TARGET'}, source_ext_match = None) env = Environment(BUILDERS = {'MyBuild':b}) env.MyBuild('foo.out', ['foo.in', 'foo.extra']) - + + env -A construction environment that can be used +A &consenv; that can be used to fetch source code using this Builder. (Note that this environment is not @@ -5043,14 +4987,15 @@ used for normal builds of normal target files, which use the environment that was used to call the Builder for the target file.) - + b = Builder(action="build < $SOURCE > $TARGET") env = Environment(BUILDERS = {'MyBuild' : b}) env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy') - + + chdir @@ -5074,7 +5019,7 @@ target file's directory. not automatically modify its expansion of -construction variables like +&consvars; like $TARGET and $SOURCE @@ -5086,7 +5031,7 @@ the top-level directory containing the &SConstruct; file, and consequently incorrect relative to the chdir directory. Builders created using chdir keyword argument, -will need to use construction variable +will need to use &consvar; expansions like ${TARGET.file} and @@ -5094,12 +5039,12 @@ and to use just the filename portion of the targets and source. - + b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}", chdir=1) env = Environment(BUILDERS = {'MyBuild' : b}) env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in') - + WARNING: Python only keeps one current directory @@ -5115,17 +5060,17 @@ option, because individual worker threads spawned by SCons interfere with each other when they start changing directory. - + Any additional keyword arguments supplied when a Builder object is created (that is, when the Builder() function is called) will be set in the executing construction environment when the Builder object is called. The canonical example here would be -to set a construction variable to +to set a &consvar; to the repository of a source code system. Any additional keyword arguments supplied @@ -5180,25 +5125,24 @@ represented by the type of the first argument: If the first argument is already an Action object, the object is simply returned. - + String If the first argument is a string, a command-line Action is returned. -Note that the command-line string -may be preceded by an -@ -(at-sign) -to suppress printing of the specified command line, -or by a -- -(hyphen) -to ignore the exit status from the specified command: - - +If such a string begins with +@, +it indicates printing of the command line is to be suppressed. +If the string begins with +- (hyphen), +it indicated the exit status from the specified command +is to be ignored, allowing execution to continue +even if the command reports failure: + + Action('$CC -c -o $TARGET $SOURCES') # Doesn't print the line being executed. @@ -5206,7 +5150,8 @@ Action('@build $TARGET $SOURCES') # Ignores return value Action('-build $TARGET $SOURCES') - + + @@ -5215,9 +5160,9 @@ Action('-build $TARGET $SOURCES') - + List @@ -5235,12 +5180,13 @@ This allows white space to be enclosed in an argument by defining a command in a list within a list: - + Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) - + + Function @@ -5253,7 +5199,7 @@ The Python function must take three keyword arguments, (a Node object representing the source file) and env -(the construction environment +(the &consenv; used for building the target file). The target @@ -5265,10 +5211,10 @@ The actual target and source file name(s) may be retrieved from their Node objects via the built-in Python str function: - + target_file_name = str(target) source_file_names = [str(x) for x in source] - + The function should return 0 @@ -5279,7 +5225,7 @@ The function may raise an exception or return a non-zero exit status to indicate an unsuccessful build. - + def build_it(target = None, source = None, env = None): # build the target from the source return 0 @@ -5316,7 +5262,7 @@ this function must take three keyword arguments: (a Node object representing the source file) and env -(a construction environment). +(a &consenv;). The target and @@ -5335,7 +5281,7 @@ SCons itself heavily uses the latter variant. Examples: - + def build_it(target, source, env): # build the target from the source return 0 @@ -5356,7 +5302,7 @@ l = Action(build_it, '$STRINGIT') The third and succeeding arguments, if present, -may either be a construction variable or a list of construction variables +may either be a &consvar; or a list of &consvars; whose values will be included in the signature of the Action when deciding whether a target should be rebuilt because the action changed. The variables may also be specified by a @@ -5364,13 +5310,13 @@ The variables may also be specified by a keyword parameter; if both are present, they are combined. This is necessary whenever you want a target to be rebuilt -when a specific construction variable changes. +when a specific &consvar; changes. This is not often needed for a string action, as the expanded variables will normally be part of the command line, but may be needed if a Python function action uses -the value of a construction variable when generating the command line. +the value of a &consvar; when generating the command line. - + def build_it(target, source, env): # build the target from the 'XXX' construction variable open(target[0], 'w').write(env['XXX']) @@ -5412,7 +5358,7 @@ target file's directory. not automatically modify its expansion of -construction variables like +&consvars; like $TARGET and $SOURCE @@ -5424,7 +5370,7 @@ the top-level directory containing the &SConstruct; file, and consequently incorrect relative to the chdir directory. Builders created using chdir keyword argument, -will need to use construction variable +will need to use &consvar; expansions like ${TARGET.file} and @@ -5432,10 +5378,10 @@ and to use just the filename portion of the targets and source. - + a = Action("build < ${SOURCE.file} > ${TARGET.file}", chdir=1) - + exitstatfunc @@ -5452,7 +5398,7 @@ under special conditions and SCons should, therefore, consider that the action always suceeds: - + def always_succeed(s): # Always return 0, which indicates success. return 0 @@ -5474,14 +5420,14 @@ If the batch_key argument evaluates True and is not a callable object, the configured Action object will cause -scons +&scons; to collect all targets built with the Action object -and configured with the same construction environment +and configured with the same &consenv; into single invocations of the Action object's command line or function. Command lines will typically want to use the CHANGED_SOURCES -construction variable +&consvar; (and possibly CHANGED_TARGETS as well) @@ -5490,9 +5436,9 @@ have actually changed since their targets were built. Example: - + a = Action('build $CHANGED_SOURCES', batch_key=True) - + The batch_key @@ -5511,24 +5457,24 @@ function must accept the following arguments: action The action object. - + env -The construction environment +The &consenv; configured for the target. - + target The list of targets for a particular configured action. - + source @@ -5546,16 +5492,16 @@ variable from the env argument which will cause -scons +&scons; to batch-build targets with matching values of that variable, or perhaps return the id() -of the entire construction environment, +of the entire &consenv;, in which case -scons +&scons; will batch-build -all targets configured with the same construction environment. +all targets configured with the same &consenv;. Returning None indicates that @@ -5567,7 +5513,7 @@ by a separate invocation of action's command or function. Example: - + def batch_key(action, env, target, source): tdir = target[0].dir if tdir.name == 'special': @@ -5577,7 +5523,6 @@ def batch_key(action, env, target, source): return (id(action), id(env), tdir) a = Action('build $CHANGED_SOURCES', batch_key=batch_key) - @@ -5585,13 +5530,13 @@ a = Action('build $CHANGED_SOURCES', batch_key=batch_key) Miscellaneous Action Functions -scons +&scons; supplies a number of functions that arrange for various common file and directory manipulations to be performed. These are similar in concept to "tasks" in the -Ant build tool, +&Ant; build tool, although the implementation is slightly different. These functions do not actually perform the specified action @@ -5620,9 +5565,10 @@ file is being read, you can use the Execute global function to do so: - + + Execute(Touch('file')) - + Second, you can use these functions @@ -5637,14 +5583,15 @@ without relying on platform-specific external commands: - + + env = Environment(TMPBUILD = '/tmp/builddir') env.Command('foo.out', 'foo.in', [Mkdir('$TMPBUILD'), Copy('$TMPBUILD', '${SOURCE.dir}'), "cd $TMPBUILD && make", Delete('$TMPBUILD')]) - + @@ -5658,7 +5605,7 @@ file or directory to the specified which can be octal or string, similar to the bash command. Examples: - + Execute(Chmod('file', 0o755)) env.Command('foo.out', 'foo.in', @@ -5670,10 +5617,11 @@ Execute(Chmod('file', "ugo+w")) env.Command('foo.out', 'foo.in', [Copy('$TARGET', '$SOURCE'), Chmod('$TARGET', "ugo+w")]) - + + Copy(dest, src) @@ -5685,15 +5633,16 @@ source file or directory to the destination file or directory. Examples: - + Execute(Copy('foo.output', 'foo.input')) env.Command('bar.out', 'bar.in', Copy('$TARGET', '$SOURCE')) - + + Delete(entry, [must_exist]) @@ -5715,7 +5664,7 @@ that is, the Action will silently do nothing if the entry does not exist. Examples: - + Execute(Delete('/tmp/buildroot')) env.Command('foo.out', 'foo.in', @@ -5723,10 +5672,11 @@ env.Command('foo.out', 'foo.in', MyBuildAction]) Execute(Delete('file_that_must_exist', must_exist=1)) - + + Mkdir(dir) @@ -5736,7 +5686,7 @@ directory dir . Examples: - + Execute(Mkdir('/tmp/outputdir')) env.Command('foo.out', 'foo.in', @@ -5744,10 +5694,11 @@ env.Command('foo.out', 'foo.in', Copy('/tmp/builddir/foo.in', '$SOURCE'), "cd /tmp/builddir && make", Copy('$TARGET', '/tmp/builddir/foo.out')]) - + + Move(dest, src) @@ -5760,16 +5711,17 @@ the specified file or directory. Examples: - + Execute(Move('file.destination', 'file.source')) env.Command('output_file', 'input_file', [MyBuildAction, Move('$TARGET', 'file_created_by_MyBuildAction')]) - + + Touch(file) @@ -5779,13 +5731,13 @@ on the specified file. Examples: - + Execute(Touch('file_to_be_touched')) env.Command('marker', 'input_file', [MyBuildAction, Touch('$TARGET')]) - + @@ -5795,13 +5747,13 @@ env.Command('marker', 'input_file', Variable Substitution Before executing a command, -scons -performs construction variable interpolation on the string that makes up +&scons; +performs &consvar; interpolation on the string that makes up the command line of the builder. Variables are introduced in such strings by a $ prefix. -Besides regular construction variables, scons provides the following +Besides regular &consvars;, scons provides the following special variables for each command execution: @@ -5810,49 +5762,49 @@ special variables for each command execution: The file names of all sources of the build command that have changed since the target was last built. - + CHANGED_TARGETS The file names of all targets that would be built from sources that have changed since the target was last built. - + SOURCE The file name of the source of the build command, or the file name of the first source if multiple sources are being built. - + SOURCES The file names of the sources of the build command. - + TARGET The file name of the target being built, or the file name of the first target if multiple targets are being built. - + TARGETS The file names of all targets being built. - + UNCHANGED_SOURCES @@ -5860,9 +5812,9 @@ if multiple targets are being built. that have not changed since the target was last built. - + UNCHANGED_TARGETS @@ -5870,30 +5822,29 @@ changed since the target was last built. from sources that have not changed since the target was last built. - -Note that the above variables are reserved -and may not be set in a construction environment. +The above variables are reserved +and may not be set in a &consenv;. -For example, given the construction variables +For example, given the &consvars; CC='cc', targets=['foo'] and sources=['foo.c', 'bar.c']: - + action='$CC -c -o $TARGET $SOURCES' - + would produce the command line: - + cc -c -o foo foo.c bar.c - + Variable names may be surrounded by curly braces { } @@ -5902,17 +5853,13 @@ are not part of the name. Within the curly braces, a variable name may have a Python slice subscript appended to select one or more items from a list. -In the previous example, the string: - - -${SOURCES[1]} - - -would produce: +In the previous example, the string: +${SOURCES[1]} +would produce: - + bar.c - + Additionally, a variable name may have the following special @@ -5926,47 +5873,47 @@ to modify the interpolated string: The base path of the file name, including the directory path but excluding any suffix. - + dir The name of the directory in which the file exists. - + file The file name, minus any directory portion. - + filebase Just the basename of the file, minus any suffix and minus the directory. - + suffix Just the file suffix. - + abspath The absolute path name of the file. - + posix @@ -5977,9 +5924,9 @@ with directories separated by not backslashes. This is sometimes necessary on Windows systems when a path references a file on other (POSIX) systems. - + srcpath @@ -5987,9 +5934,9 @@ when a path references a file on other (POSIX) systems. VariantDir(). If this file isn't linked, it just returns the directory and filename unchanged. - + srcdir @@ -5997,9 +5944,9 @@ it just returns the directory and filename unchanged. VariantDir(). If this file isn't linked, it just returns the directory part of the filename. - + rsrcpath @@ -6009,9 +5956,9 @@ If the file does not exist locally but exists in a Repository, the path in the Repository is returned. If this file isn't linked, it just returns the directory and filename unchanged. - + rsrcdir @@ -6019,7 +5966,6 @@ directory and filename unchanged. VariantDir(). If this file isn't linked, it just returns the directory part of the filename. - @@ -6059,7 +6005,7 @@ how this can be used. Lastly, a variable name may be a callable Python function associated with a -construction variable in the environment. +&consvar; in the environment. The function should accept four arguments: @@ -6070,18 +6016,21 @@ accept four arguments: a list of target nodes + source a list of source nodes + env -the construction environment +the &consenv; + for_signature @@ -6098,7 +6047,7 @@ the called function returns into the expanded string: - + def foo(target, source, env, for_signature): return "bar" @@ -6119,7 +6068,7 @@ so that the arguments will be associated with the instantiation of the class: - + class foo(object): def __init__(self, arg): self.arg = arg @@ -6129,7 +6078,7 @@ class foo(object): # Will expand $BAR to "my argument bar baz" env=Environment(FOO=foo, BAR="${FOO('my argument')} baz") - + The special pseudo-variables @@ -6155,23 +6104,21 @@ and will be removed before the command is executed. For example, the command line: - + echo Last build occurred $( $TODAY $). > $TARGET - - + would execute the command: - + echo Last build occurred $TODAY. > $TARGET - - + but the command signature added to any target files would be: - + echo Last build occurred . > $TARGET - + @@ -6179,25 +6126,32 @@ echo Last build occurred . > $TARGET Any Python code within curly braces -{ } -and introduced by the variable prefix $ -gets evaluated by the Python eval statement, +{} +and introduced by the variable prefix $ +will be evaluated using the Python eval statement, with the Python globals set to -the current environment's set of construction variables. +the current environment's set of &consvars;, and the result +substituted in. So in the following case: - + + env['COND'] = 0 env.Command('foo.out', 'foo.in', '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''') - + + the command executed will be either - + + echo FOO > foo.out - + + or - + + echo BAR > foo.out - + + according to the current value of env['COND'] when the command is executed. The evaluation takes place when the target is being @@ -6209,12 +6163,12 @@ later in the SConscript, the final value will be used. COND, FOO, and -BAR are construction variables, +BAR are &consvars;, and their values are substituted into the final command. FOO is a list, so its elements are interpolated separated by spaces. - + env=Environment() env['COND'] = 0 env['FOO'] = ['foo1', 'foo2'] @@ -6224,9 +6178,9 @@ env.Command('foo.out', 'foo.in', # Will execute this: # echo foo1 foo2 > foo.out - + -SCons uses the following rules when converting construction variables into +SCons uses the following rules when converting &consvars; into command lines: @@ -6235,25 +6189,25 @@ command lines: When the value is a string it is interpreted as a space delimited list of command line arguments. - + List When the value is a list it is interpreted as a list of command line arguments. Each element of the list is converted to a string. - + Other Anything that is not a list or string is converted to a string and interpreted as a single command line argument. - + Newline @@ -6261,7 +6215,6 @@ interpreted as a single command line argument. all other parsing, so it is not possible for arguments (e.g. file names) to contain embedded newline characters. This limitation will likely go away in a future version of SCons. - @@ -6282,16 +6235,22 @@ function accepts the following arguments: function -This can be either: -1) a Python function that will process +This can be either: + + +a Python function that will process the Node (file) and return a list of File Nodes representing the implicit dependencies (file names) found in the contents; or: -2) a dictionary that maps keys + + +a dictionary that maps keys (typically the file suffix, but see below for more discussion) -to other Scanners that should be called. +to other Scanners that should be called. + + If the argument is actually a Python function, the function must take three or four arguments: @@ -6303,7 +6262,7 @@ the function must take three or four arguments: The node argument is the internal -SCons node representing the file. +&SCons; node representing the file. Use str(node) to fetch the name of the file, and @@ -6319,11 +6278,11 @@ might not exist The env -argument is the construction environment for the scan. +argument is the &consenv; for the scan. Fetch values from it using the env.Dictionary() method or using the key lookup operator -directly on the construction environment. +directly on the &consenv;. The path @@ -6338,18 +6297,18 @@ argument (see below). arg argument is the argument supplied when the scanner was created, if any. - + name The name of the Scanner. This is mainly used to identify the Scanner internally. - + argument @@ -6358,9 +6317,9 @@ will be passed to the scanner function (described above) and the path function (specified below). - + skeys @@ -6374,14 +6333,14 @@ Scanner knows how to scan. If the argument is a string, then it will be expanded into a list by the current environment. - + path_function A Python function that takes four or five arguments: -a construction environment, +a &consenv;, a Node for the directory containing the SConscript file in which the first target was defined, @@ -6398,11 +6357,11 @@ by this Scanner object. FindPathDirs() function can be used to return a ready-made path_function -for a given construction variable name, +for a given &consvar; name, instead of having to write your own function from scratch.) - + node_class @@ -6414,9 +6373,9 @@ that are not of this class will be run through the node_factory function. - + node_factory @@ -6424,14 +6383,14 @@ function. or other object and turn it into the appropriate class of Node to be returned by this Scanner object. - + scan_check An optional Python function that takes two arguments, -a Node (file) and a construction environment, +a Node (file) and a &consenv;, and returns whether the Node should, in fact, be scanned for dependencies. @@ -6439,9 +6398,9 @@ This check can be used to eliminate unnecessary calls to the scanner function when, for example, the underlying file represented by a Node does not yet exist. - + recursive @@ -6462,34 +6421,29 @@ should return a list of Nodes that should be scanned recursively; this can be used to select a specific subset of Nodes for additional scanning. - Note that -scons +&scons; has a global SourceFileScanner object that is used by -the -Object(), -SharedObject(), -and -StaticObject() +the &Object;, &SharedObject; and &StaticObject; builders to decide which scanner should be used for different file extensions. -You can using the +You can use the SourceFileScanner.add_scanner() method to add your own Scanner object to the -scons +&SCons; infrastructure that builds target programs or libraries from a list of source files of different types: - + def xyz_scan(node, env, path): contents = node.get_text_contents() # Scan the contents and return the included files. @@ -6505,45 +6459,45 @@ env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz']) SYSTEM-SPECIFIC BEHAVIOR -SCons and its configuration files are very portable, +&scons; and its configuration files are very portable, due largely to its implementation in Python. There are, however, a few portability issues waiting to trap the unwary. .C file suffix -SCons handles the upper-case +&scons; handles the upper-case .C file suffix differently, depending on the capabilities of the underlying system. On a case-sensitive system such as Linux or UNIX, -SCons treats a file with a +&scons; treats a file with a .C suffix as a C++ source file. On a case-insensitive system such as Windows, -SCons treats a file with a +&scons; treats a file with a .C suffix as a C source file. .F file suffix -SCons handles the upper-case +&scons; handles the upper-case .F file suffix differently, depending on the capabilities of the underlying system. On a case-sensitive system such as Linux or UNIX, -SCons treats a file with a +&scons; treats a file with a .F suffix as a Fortran source file that is to be first run through the standard C preprocessor. On a case-insensitive system such as Windows, -SCons treats a file with a +&scons; treats a file with a .F suffix as a Fortran source file that should not @@ -6570,8 +6524,7 @@ such as the python.org and ActiveState versions, do not have the Cygwin path name semantics. This means that using a native Windows version of Python to build compiled programs using Cygwin tools -(such as gcc, bison, -and flex) +(such as &gcc;, &bison; and flex) may yield unpredictable results. "Mixing and matching" in this way can be made to work, @@ -6580,18 +6533,18 @@ in your SConscript files. In practice, users can sidestep the issue by adopting the following rules: -When using gcc, +When using &gcc;, use the Cygwin-supplied Python interpreter -to run SCons; +to run &scons;; when using Microsoft Visual C/C++ (or some other Windows compiler) -use the python.org or ActiveState version of Python -to run SCons. +use the python.org or Microsoft Store or ActiveState version of Python +to run &scons;. Windows: scons.bat file On Windows systems, -SCons is executed via a wrapper +&scons; is executed via a wrapper scons.bat file. This has (at least) two ramifications: @@ -6602,14 +6555,13 @@ on the command line may have to put double quotes around the assignments: - -scons "FOO=BAR" "BAZ=BLEH" - + +scons "FOO=BAR" "BAZ=BLEH" + Second, the Cygwin shell does not recognize this file as being the same -as an -scons +as an &scons; command issued at the command-line prompt. You can work around this either by executing @@ -6617,42 +6569,38 @@ executing from the Cygwin command line, or by creating a wrapper shell script named -scons . +scons. MinGW The MinGW bin directory must be in your PATH environment variable or the -PATH variable under the ENV construction variable for SCons +PATH variable under the ENV &consvar; for &scons; to detect and use the MinGW tools. When running under the native Windows -Python interpreter, SCons will prefer the MinGW tools over the Cygwin +Python interpreter, &scons; will prefer the MinGW tools over the Cygwin tools, if they are both installed, regardless of the order of the bin directories in the PATH variable. If you have both MSVC and MinGW installed and you want to use MinGW instead of MSVC, -then you must explicitly tell SCons to use MinGW by passing - - -tools=['mingw'] - - -to the Environment() function, because SCons will prefer the MSVC tools +then you must explicitly tell &scons; to use MinGW by passing +tools=['mingw'] +to the &Environment; function, because &scons; will prefer the MSVC tools over the MinGW tools. EXAMPLES -To help you get started using SCons, +To help you get started using &scons;, this section contains a brief overview of some common tasks. Basic Compilation From a Single Source File - + env = Environment() env.Program(target = 'foo', source = 'foo.c') - + Note: Build the file by specifying the target as an argument @@ -6663,19 +6611,19 @@ or by specifying a dot ("scons ."). Basic Compilation From Multiple Source Files - + env = Environment() env.Program(target = 'foo', source = Split('f1.c f2.c f3.c')) - + Setting a Compilation Flag - + env = Environment(CCFLAGS = '-g') env.Program(target = 'foo', source = 'foo.c') - + @@ -6684,51 +6632,51 @@ env.Program(target = 'foo', source = 'foo.c') Note: You do not need to set CCFLAGS to specify -I options by hand. -SCons will construct the right -I options from CPPPATH. +&scons; will construct the right options from CPPPATH. - + env = Environment(CPPPATH = ['.']) env.Program(target = 'foo', source = 'foo.c') - + Search Multiple Directories For .h Files - + env = Environment(CPPPATH = ['include1', 'include2']) env.Program(target = 'foo', source = 'foo.c') - + Building a Static Library - + env = Environment() env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c')) env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c']) - + Building a Shared Library - + env = Environment() env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c']) env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c')) - + Linking a Local Library Into a Program - + env = Environment(LIBS = 'mylib', LIBPATH = ['.']) env.Library(target = 'mylib', source = Split('l1.c l2.c')) env.Program(target = 'prog', source = ['p1.c', 'p2.c']) - + @@ -6736,9 +6684,9 @@ env.Program(target = 'prog', source = ['p1.c', 'p2.c']) Notice that when you invoke the Builder, you can leave off the target file suffix, -and SCons will add it automatically. +and &scons; will add it automatically. - + bld = Builder(action = 'pdftex < $SOURCES > $TARGET' suffix = '.pdf', src_suffix = '.tex') @@ -6747,19 +6695,21 @@ env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') # The following creates "bar.pdf" from "bar.tex" env.PDFBuilder(target = 'bar', source = 'bar') - + Note also that the above initialization overwrites the default Builder objects, so the Environment created above -can not be used call Builders like env.Program(), -env.Object(), env.StaticLibrary(), etc. +can not be used call Builders like +env.Program, +env.Object, +env.StaticLibrary etc. Adding Your Own Builder Object to an Environment - + bld = Builder(action = 'pdftex < $SOURCES > $TARGET' suffix = '.pdf', src_suffix = '.tex') @@ -6767,15 +6717,15 @@ env = Environment() env.Append(BUILDERS = {'PDFBuilder' : bld}) env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') env.Program(target = 'bar', source = 'bar.c') - + You also can use other Pythonic techniques to add -to the BUILDERS construction variable, such as: +to the BUILDERS &consvar;, such as: - + env = Environment() env['BUILDERS]['PDFBuilder'] = bld - + @@ -6792,7 +6742,7 @@ lines in the scanned file. This would implicitly assume that all included files live in the top-level directory: - + import re include_re = re.compile(r'^include\s+(\S+)$', re.M) @@ -6816,7 +6766,7 @@ env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') bar_in = File('bar.in') env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET') bar_in.target_scanner = kscan - + It is important to note that you have to return a list of File nodes from the scan function, simple @@ -6831,10 +6781,10 @@ a scanner which searches a path of directories (specified as the MYPATH -construction variable) +&consvar;) for files that actually exist: - + import re import os include_re = re.compile(r'^include\s+(\S+)$', re.M) @@ -6874,12 +6824,12 @@ function used in the previous example returns a function that will return a list of directories specified in the $MYPATH -construction variable. It lets SCons detect the file -incs/foo.inc, +&consvar;. It lets &scons; detect the file +incs/foo.inc, even if -foo.x +foo.x contains the line -include foo.inc +include foo.inc only. If you need to customize how the search path is derived, you would provide your own @@ -6887,7 +6837,7 @@ you would provide your own argument when creating the Scanner object, as follows: - + # MYPATH is a list of directories to search for files in def pf(env, dir, target, source, arg): top_dir = Dir('#').abspath @@ -6914,49 +6864,55 @@ scanner = Scanner(name='myscanner', SConscript file are relative to that subdirectory. - -SConstruct: +SConstruct: - env = Environment() - env.Program(target = 'foo', source = 'foo.c') + +env = Environment() +env.Program(target = 'foo', source = 'foo.c') - SConscript('sub/SConscript') +SConscript('sub/SConscript') + -sub/SConscript: +sub/SConscript: - env = Environment() - # Builds sub/foo from sub/foo.c - env.Program(target = 'foo', source = 'foo.c') + +env = Environment() +# Builds sub/foo from sub/foo.c +env.Program(target = 'foo', source = 'foo.c') - SConscript('dir/SConscript') +SConscript('dir/SConscript') + -sub/dir/SConscript: +sub/dir/SConscript: - env = Environment() - # Builds sub/dir/foo from sub/dir/foo.c - env.Program(target = 'foo', source = 'foo.c') + +env = Environment() +# Builds sub/dir/foo from sub/dir/foo.c +env.Program(target = 'foo', source = 'foo.c') Sharing Variables Between SConscript Files -You must explicitly Export() and Import() variables that +You must explicitly call &Export; and &Import; for variables that you want to share between SConscript files. - -SConstruct: +SConstruct: - env = Environment() - env.Program(target = 'foo', source = 'foo.c') + +env = Environment() +env.Program(target = 'foo', source = 'foo.c') - Export("env") - SConscript('subdirectory/SConscript') +Export("env") +SConscript('subdirectory/SConscript') + -subdirectory/SConscript: +subdirectory/SConscript: - Import("env") - env.Program(target = 'foo', source = 'foo.c') + +Import("env") +env.Program(target = 'foo', source = 'foo.c') @@ -6964,108 +6920,117 @@ subdirectory/SConscript: Building Multiple Variants From the Same Source Use the variant_dir keyword argument to -the SConscript function to establish +the &SConscriptFunc; function to establish one or more separate variant build directory trees for a given source directory: - -SConstruct: +SConstruct: - cppdefines = ['FOO'] - Export("cppdefines") - SConscript('src/SConscript', variant_dir='foo') + +cppdefines = ['FOO'] +Export("cppdefines") +SConscript('src/SConscript', variant_dir='foo') - cppdefines = ['BAR'] - Export("cppdefines") - SConscript('src/SConscript', variant_dir='bar') +cppdefines = ['BAR'] +Export("cppdefines") +SConscript('src/SConscript', variant_dir='bar') + -src/SConscript: +src/SConscript: - Import("cppdefines") - env = Environment(CPPDEFINES = cppdefines) - env.Program(target = 'src', source = 'src.c') + +Import("cppdefines") +env = Environment(CPPDEFINES = cppdefines) +env.Program(target = 'src', source = 'src.c') -Note the use of the Export() method +Note the use of the &Export; method to set the "cppdefines" variable to a different -value each time we call the SConscript function. +value each time we call the &SConscriptFunc; function. Hierarchical Build of Two Libraries Linked With a Program - -SConstruct: +SConstruct: - env = Environment(LIBPATH=['#libA', '#libB']) - Export('env') - SConscript('libA/SConscript') - SConscript('libB/SConscript') - SConscript('Main/SConscript') + +env = Environment(LIBPATH=['#libA', '#libB']) +Export('env') +SConscript('libA/SConscript') +SConscript('libB/SConscript') +SConscript('Main/SConscript') + -libA/SConscript: +libA/SConscript: - Import('env') - env.Library('a', Split('a1.c a2.c a3.c')) + +Import('env') +env.Library('a', Split('a1.c a2.c a3.c')) + -libB/SConscript: +libB/SConscript: - Import('env') - env.Library('b', Split('b1.c b2.c b3.c')) + +Import('env') +env.Library('b', Split('b1.c b2.c b3.c')) + -Main/SConscript: +Main/SConscript: - Import('env') - e = env.Clone(LIBS=['a', 'b']) - e.Program('foo', Split('m1.c m2.c m3.c')) + +Import('env') +e = env.Clone(LIBS=['a', 'b']) +e.Program('foo', Split('m1.c m2.c m3.c')) -The '#' in the LIBPATH directories specify that they're relative to the -top-level directory, so they don't turn into "Main/libA" when they're -used in Main/SConscript. +The # in the LIBPATH +directories specify that they're relative to the +top-level directory, so they don't turn into +Main/libA when they're +used in Main/SConscript Specifying only 'a' and 'b' for the library names -allows SCons to append the appropriate library +allows &scons; to append the appropriate library prefix and suffix for the current platform -(for example, 'liba.a' on POSIX systems, -'a.lib' on Windows). +(for example, liba.a on POSIX systems, +a.lib on Windows). -Customizing construction variables from the command line. +Customizing &consvars; from the command line. The following would allow the C compiler to be specified on the command line or in the file custom.py. - + vars = Variables('custom.py') vars.Add('CC', 'The C compiler.') env = Environment(variables=vars) Help(vars.GenerateHelpText(env)) - + The user could specify the C compiler on the command line: - -scons "CC=my_cc" - + +scons "CC=my_cc" + or in the custom.py file: - + CC = 'my_cc' - + or get documentation on the options: - -$ scons -h + +$ scons -h CC: The C compiler. default: None actual: cc - - + @@ -7081,41 +7046,46 @@ then include every header you want to precompile in "StdAfx.h", and finally include "StdAfx.h" as the first header in all the source files you are compiling to object files. For example: -StdAfx.h: - +StdAfx.h: + + #include <windows.h> #include <my_big_header.h> - + -StdAfx.cpp: - +StdAfx.cpp: + + #include <StdAfx.h> - + -Foo.cpp: - +Foo.cpp: + + #include <StdAfx.h> /* do some stuff */ - + -Bar.cpp: - +Bar.cpp: + + #include <StdAfx.h> /* do some other stuff */ - + -SConstruct: - +SConstruct: + + env=Environment() env['PCHSTOP'] = 'StdAfx.h' env['PCH'] = env.PCH('StdAfx.cpp')[0] env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) - + For more information see the document for the PCH builder, and the PCH and -PCHSTOP construction variables. To learn about the details of precompiled +PCHSTOP &consvars;. To learn about the details of precompiled headers consult the MSDN documentation for /Yc, /Yu, and /Yp. @@ -7125,17 +7095,18 @@ headers consult the MSDN documentation for /Yc, /Yu, and /Yp. Since including debugging information in programs and shared libraries can cause their size to increase significantly, Microsoft provides a mechanism for including the debugging information in an external file called a PDB -file. SCons supports PDB files through the PDB construction +file. &scons; supports PDB files through the PDB construction variable. -SConstruct: - +SConstruct: + + env=Environment() env['PDB'] = 'MyApp.pdb' env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) - + -For more information see the document for the PDB construction variable. +For more information see the document for the PDB &consvar;. @@ -7151,7 +7122,7 @@ However the following variables are imported by - SCONS_LIB_DIR + SCONS_LIB_DIR Specifies the directory that contains the &scons; Python module directory. Normally &scons; can deduce this, @@ -7163,7 +7134,7 @@ release, it may be necessary to specify - SCONSFLAGS + SCONSFLAGS A string of options that will be used by &scons; in addition to those passed on the command line. @@ -7171,7 +7142,7 @@ in addition to those passed on the command line. - SCONS_CACHE_MSVC_CONFIG + SCONS_CACHE_MSVC_CONFIG (Windows only). If set, save the shell environment variables generated when setting up the Microsoft Visual C++ compiler @@ -7198,19 +7169,15 @@ Remove the cache file in case of problems with this. and will silently revert to non-cached behavior in such cases. Since &scons; 3.1 (experimental). - SEE ALSO -scons -User Manual, -scons -Design Document, -scons -source code. +&SCons; User Manual, +&SCons; Design Document, +&SCons; source code. diff --git a/doc/python10/design.xml b/doc/python10/design.xml index bd571ba..bbbe887 100644 --- a/doc/python10/design.xml +++ b/doc/python10/design.xml @@ -320,7 +320,7 @@ (or other object). The signature of a derived file consists of the aggregate of the signatures of all the source files plus the command-line string used to - build the file. These signatures are stored in a &sconsign; file + build the file. These signatures are stored in a &sconsigndb; file in each directory. diff --git a/doc/scons.mod b/doc/scons.mod index 024afab..f279f47 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -8,6 +8,20 @@ --> + + +SCons"> +scons"> +scons-file"> +sconsign"> +