From a0d9e457e835ecb4f975d8b9e130726b7a9f06bd Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 6 Dec 2022 12:02:15 -0700 Subject: Manpage tweaking [skip appveyor] * Reworded the section on --experimental - separate when the two current features were made available, and when --experimental itself was added. * Reworded in GetOption * Changed tags on a few options * Use entity forms in more places (Python -> &Python;, SConscript -> &SConscript; etc.) * Make changed/added notifications more consistent with what Sphinx produces for the API docs (:versionadded: and :versionchanged: markup) Signed-off-by: Mats Wichmann --- SCons/Script/Main.xml | 20 ++-- doc/man/scons.xml | 280 +++++++++++++++++++++++++------------------------- 2 files changed, 151 insertions(+), 149 deletions(-) diff --git a/SCons/Script/Main.xml b/SCons/Script/Main.xml index cd4cc1a..fbb90fd 100644 --- a/SCons/Script/Main.xml +++ b/SCons/Script/Main.xml @@ -316,18 +316,22 @@ atexit.register(print_build_failures) -This function provides a way to query the value of -options which can be set via the command line or using the -&f-link-SetOption; function. +Query the value of settable options which may have been set +on the command line, or by using the &f-link-SetOption; function. +The value of the option is returned in a type matching how the +option was declared - see the documentation for the +corresponding command line option for information about each specific +option. + name can be an entry from the following table, which shows the corresponding command line arguments that could affect the value. name can be also be the destination variable name from a project-specific option added using the -&f-link-AddOption; function, as long as the addition -happens prior to the &f-GetOption; call in the SConscript files. +&f-link-AddOption; function, as long as that addition has been +processed prior to the &f-GetOption; call in the &SConscript; files. @@ -552,12 +556,6 @@ happens prior to the &f-GetOption; call in the SConscript files. - - -See the documentation for the -corresponding command line option for information about each specific -option. - diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 2bdf2b9..4d72180 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -106,15 +106,16 @@ and a database of information about previous builds so details do not have to be recalculated each run. -&scons; requires Python 3.6 or later to run; -there should be no other dependencies or requirements. +&scons; requires &Python; 3.6 or later to run; +there should be no other dependencies or requirements, unless the experimental Ninja tool is used. - -Support for Python 3.5 is removed since -&SCons; 4.3.0. -The CPython project has retired 3.5: + + +Changed in version 4.3.0: +support for &Python; 3.5 is removed; +the CPython project has retired 3.5: . - + You set up an &SCons; build system by writing a script @@ -176,14 +177,14 @@ these subsidiary files are named &SConscript;, although any name may be used. As a result of this naming convention, -the term SConscript files +the term &SConscript; files is 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 such files. -Before reading the SConscript files, +Before reading the &SConscript; files, &scons; looks for a directory named site_scons @@ -193,9 +194,9 @@ or, if specified, the directory from the option instead, and prepends the ones it -finds to the Python module search path (sys.path), +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. +the normal &Python; way in &SConscript; files. For each found site directory, (1) if it contains a file site_init.py that file is evaluated, @@ -211,24 +212,24 @@ controlling the site directories. -SConscript files are written in the -Python programming language, -although it is normally not necessary to be a Python +&SConscript; files are written in the +&Python; programming language, +although it is normally not necessary to be a &Python; programmer to use &scons; effectively. -SConscript files are invoked in a context that makes +&SConscript; files are invoked in a context that makes the facilities described in this manual page available in their local namespace without any special steps. -Standard Python scripting capabilities -such as flow control, data manipulation, and imported Python libraries +Standard &Python; scripting capabilities +such as flow control, data manipulation, and imported &Python; libraries are available to use to handle complicated build situations. -Other Python files can be made a part of the build system, +Other &Python; files can be made a part of the build system, but they do not automatically have the &SCons; context and need to import it if they need access (described later). &scons; -reads and executes all of the included SConscript files +reads and executes all of the included &SConscript; files before it begins building any targets. To make this clear, @@ -338,7 +339,7 @@ Command-line options (see ) are consumed. Any variable argument assignments are collected, and remaining arguments are taken as targets to build. -Values of variables to be passed to the SConscript files +Values of variables to be passed to the &SConscript; files may be specified on the command line: @@ -347,7 +348,7 @@ may be specified on the command line: These variables are available through the &ARGUMENTS; dictionary, -and can be used in the SConscript files to modify +and can be used in the &SConscript; files to modify the build in any way: @@ -373,7 +374,7 @@ for more information. &scons; can maintain a cache of target (derived) files that can be shared between multiple builds. When derived-file caching is enabled in an -SConscript file, any target files built by +&SConscript; file, any target files built by &scons; will be copied to the cache. If an up-to-date target file is found in the cache, it @@ -449,7 +450,7 @@ The targets listed on the command line are made available in the If no targets are specified on the command line, &scons; will select those targets -specified in the SConscript files via calls +specified in the &SConscript; files via calls to the &f-link-Default; function. These are known as the default targets, and are made available in the @@ -460,11 +461,11 @@ and are made available in the If no targets are selected by the previous steps, &scons; selects the current directory for scanning, -unless command-line options which affect the target -scan are detected -(, +unless command-line options which affect the directory +for target scanning are present +(, , -, +, ). Since targets thus selected were not the result of user instructions, this target list is not made available @@ -521,7 +522,7 @@ build: or by changing directory and invoking scons with the - + option, which traverses up the directory hierarchy until it finds the &SConstruct; @@ -542,7 +543,7 @@ options): requested, as &scons; needs to make sure any dependent files are built. -Specifying "cleanup" targets in SConscript files is +Specifying "cleanup" targets in &SConscript; files is usually not necessary. The @@ -564,7 +565,7 @@ and export. Additional files or directories to remove can be specified using the -&f-link-Clean; function in the SConscript files. +&f-link-Clean; function in the &SConscript; files. Conversely, targets that would normally be removed by the invocation can be retained by calling the @@ -572,7 +573,7 @@ invocation can be retained by calling the &scons; supports building multiple targets in parallel via a - + option that takes, as its argument, the number of simultaneous tasks that may be spawned: @@ -627,10 +628,10 @@ preservation through calls to the &f-link-NoClean; function. While clean mode removes targets rather than building them, -work which is done directly in Python code in SConscript files +work which is done directly in &Python; code in &SConscript; files will still be carried out. If it is important to avoid some such work from taking place in clean mode, it should be protected. -An SConscript file can determine which mode +An &SConscript; file can determine which mode is active by querying &f-link-GetOption;, as in the call if GetOption("clean"): @@ -638,7 +639,7 @@ is active by querying &f-link-GetOption;, as in the call - - + Write debug information about derived-file caching to the specified @@ -699,7 +700,7 @@ built during this invocation. - + When using a derived-file cache show the command @@ -770,7 +771,7 @@ have any results in the cache. - + , @@ -794,12 +795,12 @@ options are given, each subsequent non-absolute directory is interpreted relative to the preceding one. This option is similar to using -, +, but does not search for any of the predefined &SConstruct; names in the specified directory. See also options -, +, and @@ -818,7 +819,7 @@ to change the &SConstruct; search behavior when this option is used. Works exactly the same way as the - + option except for the way default targets are handled. When this option is used and no targets are specified on the command line, all default targets are built, whether or not they are below the current @@ -844,7 +845,7 @@ each command, shows the absolute start and end times. This may be useful in debugging parallel builds. Implies the option. -Available since &scons; 3.1. +New in version 3.1. @@ -853,9 +854,9 @@ Implies the option. Print how many objects are created of the various classes used internally by SCons -before and after reading the SConscript files +before and after reading the &SConscript; files and before and after building targets. -This is not supported when SCons is executed with the Python +This is not supported when SCons is executed with the &Python; (optimized) option or when the SCons modules @@ -923,7 +924,7 @@ instead of recomputing them each time they're needed. memory Prints how much memory SCons uses -before and after reading the SConscript files +before and after reading the &SConscript; files and before and after building targets. @@ -940,8 +941,8 @@ of the various classes used internally by SCons. pdb Re-run &scons; under the control of the -pdb -Python debugger. +pdb +&Python; debugger. @@ -980,7 +981,7 @@ Building myprog.o with action(s): stacktrace -Prints an internal Python stack trace +Prints an internal &Python; stack trace when encountering an otherwise unexplained error. @@ -997,11 +998,11 @@ when encountering an otherwise unexplained error. The total build time (time SCons ran from beginning to end) -The total time spent reading and executing SConscript files +The total time spent reading and executing &SConscript; files The total time SCons itself spent running -(that is, not counting reading and executing SConscript files) +(that is, not counting reading and executing &SConscript; files) The total time spent executing all build commands @@ -1009,7 +1010,7 @@ 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 &SConscriptFunc; function +The time spent processing each file passed to the &f-link-SConscript; function @@ -1125,16 +1126,18 @@ the mechanisms in the specified order. the special tokens all or none. A comma-separated string can be used to select multiple features. The default setting is none. - Current available features are: ninja, tm_v2. + Current available features are: + ninja (added in version 4.2), + tm_v2 (added in version 4.4.1). + No Support offered for any features or tools enabled by this flag. - ninja Available since &scons; 4.2. - tm_v2 Available since &scons; 4.4.1 + New in version 4.2 (experimental). - + , , @@ -1144,7 +1147,7 @@ the mechanisms in the specified order. Use file - as the initial SConscript file. + as the initial &SConscript; file. Multiple options may be specified, @@ -1155,14 +1158,14 @@ the mechanisms in the specified order. - + , Print a local help message for this project, -if one is defined in the SConscript files +if one is defined in the &SConscript; files (see the &f-link-Help; function), plus a line that refers to the standard &SCons; help message. If no local help message is defined, @@ -1172,7 +1175,7 @@ plus help for any local options defined through &f-link-AddOption;. Exits after displaying the appropriate message. Note that use of this option requires &SCons; to process -the SConscript files, so syntax errors may cause +the &SConscript; files, so syntax errors may cause the help message not to be displayed. @@ -1194,7 +1197,7 @@ small block-size slows down the build considerably. The default value is to use a chunk size of 64 kilobytes, which should be appropriate for most uses. -Available since &scons; 4.2. +New in version 4.2. @@ -1212,16 +1215,16 @@ This value determines the hashing algorithm used in generating md5, sha1 and sha256. -However, the Python interpreter used to run SCons must have the corresponding +However, the &Python; interpreter used to run &scons; must have the corresponding support available in the hashlib module to use the specified algorithm. If this option is omitted, the first supported hash format found is selected. Typically this is MD5, however, on a FIPS-compliant system -using a version of Python older than 3.9, +using a version of &Python; older than 3.9, SHA1 or SHA256 is chosen as the default. -Python 3.9 and onwards clients always default to MD5, even in FIPS mode. +&Python; 3.9 and onwards clients always default to MD5, even in FIPS mode. Specifying this option changes the name of the SConsign database. @@ -1234,7 +1237,7 @@ For example, uses a SConsign database named .sconsign_sha256.dblite. -Available since &scons; 4.2. +New in version 4.2. @@ -1249,7 +1252,7 @@ command-line options and exit. - + , @@ -1260,7 +1263,7 @@ command-line options and exit. - + , @@ -1269,7 +1272,7 @@ command-line options and exit. Specifies a directory to search for -imported Python modules. If several +imported &Python; modules. If several options are used, the directories are searched in the order specified. @@ -1329,7 +1332,7 @@ This implies - + @@ -1338,7 +1341,7 @@ When using the &Install; builders, prepend to the installation paths such that all installed files will be placed under that directory. This option is unavailable if one of &b-link-Install;, &b-link-InstallAs; or -&b-link-InstallVersionedLib; is not used in the SConscript files. +&b-link-InstallVersionedLib; is not used in the &SConscript; files. @@ -1347,11 +1350,11 @@ one of &b-link-Install;, &b-link-InstallAs; or Starts SCons in interactive mode. -The SConscript files are read once and a +The &SConscript; files are read once and a scons>>> prompt is printed. Targets may now be rebuilt by typing commands at interactive prompt -without having to re-read the SConscript files +without having to re-read the &SConscript; files and re-initialize the dependency graph from scratch. SCons interactive mode supports the following commands: @@ -1399,7 +1402,7 @@ do not cause errors but have no effect on the build command -(mainly because they affect how the SConscript files are read, +(mainly because they affect how the &SConscript; files are read, which only happens once at the beginning of interactive mode). @@ -1500,7 +1503,7 @@ scons>>> exit - + , @@ -1520,7 +1523,7 @@ option, the last one is effective. - + , @@ -1595,11 +1598,11 @@ no matter how old the file is. . -Deprecated since &scons; 4.2. +Changed in version 4.2: deprecated. - + , , @@ -1619,11 +1622,11 @@ that file is not available to scan for dependencies on an unbuilt tree, or may contain out of date information in a built tree. -Work which is done directly in Python code in SConscript files, +Work which is done directly in &Python; code in &SConscript; files, as opposed to work done by builder actions during the build phase, will still be carried out. If it is important to avoid some such work from taking place in no execute mode, it should be protected. -An SConscript file can determine which mode +An &SConscript; file can determine which mode is active by querying &f-link-GetOption;, as in the call if GetOption("no_exec"): @@ -1635,13 +1638,13 @@ is active by querying &f-link-GetOption;, as in the call Prevents the automatic addition of the standard site_scons -dirs to +directories to sys.path. Also prevents loading the site_scons/site_init.py modules if they exist, and prevents adding their site_scons/site_tools -dirs to the toolpath. +directories to the toolpath. @@ -1679,11 +1682,10 @@ dirs to the toolpath. -The type or types +The type of package to create when using the &b-link-Package; builder. -In the case of multiple types, type -should be a comma-separated string; &SCons; will try to build -for all of those packages. +Multiple types can be specified by using a comma-separated string, +in which case &SCons; will try to build for all of those package types. Note this option is only available if the &t-link-packaging; tool has been enabled. @@ -1693,15 +1695,14 @@ has been enabled. -Run SCons under the Python profiler -and save the results in the specified -file. -The results may be analyzed using the Python -pstats module. +Run &SCons; under the &Python; profiler +and save the results to file. +The results may be analyzed using the &Python; +pstats module. - + , @@ -1715,8 +1716,8 @@ date, non-zero otherwise. -Quiets SCons status messages about -reading SConscript files, +Suppress status messages about +reading &SConscript; files, building targets and entering directories. Commands that are executed @@ -1739,7 +1740,7 @@ or retrieve the same target files. - + , , @@ -1752,7 +1753,7 @@ Also suppresses SCons status messages. - + , , @@ -1876,7 +1877,7 @@ unless you encounter stack overflow errors. - + , @@ -1941,7 +1942,7 @@ specified alone, without any type, it behaves as if all had been specified. -Available since &scons; 4.0. +New in version 4.0. @@ -1981,7 +1982,7 @@ choices may be specified, separated by commas: - + , , @@ -2006,13 +2007,13 @@ current directory will be built. option except for the way default targets are handled. When this option is used and no targets are specified on the command line, -all default targets that are defined in the SConscript(s) in the current +all default targets that are defined in the &SConscript; file(s) in the current directory are built, regardless of what directory the resultant targets end up in. - + , @@ -2183,7 +2184,7 @@ can themselves refer to lists of names or nodes. These warnings are disabled by default for the first phase of deprecation. Enable to be reminded about use of this tool module. -Available since &SCons; 4.3. +New in version 4.3. @@ -2191,7 +2192,7 @@ of this tool module. missing-sconscript -Warnings about missing SConscript files. +Warnings about missing &SConscript; files. These warnings are enabled by default. @@ -2203,16 +2204,16 @@ These warnings are enabled by default. feature not working when &scons; -is run with the Python +is run with the &Python; -option or from optimized Python (.pyo) modules. +option or from optimized &Python; (.pyo) modules. no-parallel-support -Warnings about the version of Python +Warnings about the version of &Python; not being able to support parallel builds when the option is used. @@ -2224,7 +2225,7 @@ These warnings are enabled by default. python-version Warnings about running -SCons with a deprecated version of Python. +&SCons; using a version of &Python; that has been deprecated. These warnings are enabled by default. @@ -2289,7 +2290,7 @@ These warnings are enabled by default. - + , , @@ -2314,7 +2315,7 @@ repositories are searched in the order specified. SConscript Files The build configuration is described by one or more files, -known as SConscript files. +known as &SConscript; files. There must be at least one file for a valid build (&scons; will quit if it does not find one). &scons; by default looks for this file by the name @@ -2334,20 +2335,20 @@ included or excluded at run-time depending on how &scons; is invoked. -Each SConscript file in a build configuration is invoked +Each &SConscript; file in a build configuration is invoked independently in a separate context. This provides necessary isolation so that different parts of the build don't accidentally step on each other. You have to be explicit about sharing information, by using the &f-link-Export; function or the &exports; argument -to the &SConscript; function, as well as the &f-link-Return; function -in a called SConscript file, and comsume shared information by using the +to the &f-link-SConscript; function, as well as the &f-link-Return; function +in a called &SConscript; file, and comsume shared information by using the &f-link-Import; function. The following sections describe the various &SCons; facilities -that can be used in SConscript files. Quick links: +that can be used in &SConscript; files. Quick links: @@ -2546,7 +2547,7 @@ See for details. (more properly, tool specification modules) which are used to help initialize the &consenv;. An &SCons; tool is only responsible for setup. -For example, if an SConscript file declares +For example, if an &SConscript; file declares the need to construct an object file from a C-language source file by calling the &b-link-Object; builder, then a tool representing @@ -2734,7 +2735,7 @@ contains separator characters, the search follows down from the starting point, which is the top of the directory tree for an absolute path and the current directory for a relative path. The "current directory" in this context is the directory -of the SConscript file currently being processed. +of the &SConscript; file currently being processed. @@ -2868,7 +2869,7 @@ target file's directory. -Python only keeps one current directory +&Python; only keeps one current directory location even if there are multiple threads. This means that use of the chdir @@ -2879,7 +2880,7 @@ work with the SCons option, because individual worker threads spawned -by SCons interfere with each other +by &SCons; interfere with each other when they start changing directory. @@ -2973,7 +2974,7 @@ has determined are appropriate for the local system. environment (indicated in the listing of builders below without a leading env.) may be called from custom &Python; modules that you -import into an SConscript file by adding the following +import into an &SConscript; file by adding the following to the &Python; module: @@ -3114,13 +3115,13 @@ the object file. When trying to handle errors that may occur in a builder method, consider that the corresponding Action is executed at a different -time than the SConscript file statement calling the builder. +time than the &SConscript; file statement calling the builder. It is not useful to wrap a builder call in a try block, since success in the builder call is not the same as the builder itself succeeding. If necessary, a Builder's Action should be coded to exit with -a useful exception message indicating the problem in the SConscript files - +a useful exception message indicating the problem in the &SConscript; files - programmatically recovering from build errors is rarely useful. @@ -3276,7 +3277,7 @@ see the next section on &consvars;. Global functions may be called from custom Python modules that you -import into an SConscript file by adding the following import +import into an &SConscript; file by adding the following import to the Python module: @@ -3316,7 +3317,7 @@ include: In addition to the global functions and methods, &scons; supports a number of variables -that can be used in SConscript files +that can be used in &SConscript; files to affect how you want the build to be performed. @@ -3489,7 +3490,7 @@ print([str(t) for t in DEFAULT_TARGETS]) # back to [] only after you've made all of your &Default;() calls, or else simply be careful of the order -of these statements in your SConscript files +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. @@ -3498,7 +3499,7 @@ default target before it's actually been added to the list. These variables may be accessed from custom Python modules that you -import into an SConscript file by adding the following +import into an &SConscript; file by adding the following to the Python module: @@ -3654,14 +3655,16 @@ discovered while running tests. The context includes a local &consenv; which is used when running the tests and which can be updated with the check results. Only one context may be active -at a time (since 4.0, &scons; will raise an exception -on an attempt to create a new context when there is -an active context), but a new context can be created +at a time, but a new context can be created after the active one is completed. For the global function form, the required env describes the initial values for the context's local &consenv;; for the &consenv; method form the instance provides the values. + +Changed in version 4.0: raises an exception +on an attempt to create a new context when there is an active context. + custom_tests specifies a dictionary containing custom tests (see the section on custom tests below). @@ -4426,7 +4429,8 @@ from various sources, often from the command line: scons VARIABLE=foo -The variable values can also be specified in a configuration file or an SConscript file. +The variable values can also be specified in a configuration file +or an &SConscript; file. To obtain the object for manipulating values, call the &Variables; function: @@ -5062,7 +5066,7 @@ Builders return the target Node(s) in the form of a list, which you can then make use of. However, since filesystem Nodes have some useful public attributes and methods -that you can use in SConscript files, +that you can use in &SConscript; files, it is sometimes appropriate to create them manually, outside the regular context of a Builder call. @@ -6394,7 +6398,7 @@ are intended to be used. First, if you need to perform the action -at the time the SConscript +at the time the &SConscript; file is being read, you can use the &f-link-Execute; @@ -6763,8 +6767,8 @@ builder action. The value of env['BAR'] will be exactly as it was set: "$FOO baz". This can make debugging tricky, as the substituted result is not available at the time -the SConscript files are being interpreted and -thus not available to print(). +the &SConscript; files are being interpreted and +thus not available to the print function. However, you can perform the substitution on demand by calling the &f-link-env-subst; method for this purpose. @@ -7041,9 +7045,9 @@ 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 -built, not when the SConscript is being read. So if +built, not when the &SConscript; is being read. So if env['COND'] is changed -later in the SConscript, the final value will be used. +later in the &SConscript;, the final value will be used. Here's a more complete example. Note that all of COND, @@ -7078,7 +7082,7 @@ which &SCons; passes to eval which returns the value. - + Use of the Python eval function is considered to have security implications, since, depending on input sources, @@ -7086,7 +7090,7 @@ arbitrary unchecked strings of code can be executed by the Python interpreter. Although &SCons; makes use of it in a somewhat restricted context, you should be aware of this issue when using the ${python-expression-for-subst} form. - + @@ -7229,7 +7233,7 @@ it will be expanded into a list by the current environment. A Python function that takes four or five arguments: a &consenv;, a Node for the directory containing -the SConscript file in which +the &SConscript; file in which the first target was defined, a list of target nodes, a list of source nodes, @@ -7713,7 +7717,7 @@ may yield unpredictable results. "Mixing and matching" in this way can be made to work, but it requires careful attention to the use of path names -in your SConscript files. +in your &SConscript; files. In practice, users can sidestep the issue by adopting the following guidelines: @@ -8092,7 +8096,7 @@ scanner = Scanner( Creating a Hierarchical Build Notice that the file names specified in a subdirectory's -SConscript file are relative to that subdirectory. +&SConscript; file are relative to that subdirectory. SConstruct: @@ -8128,7 +8132,7 @@ env.Program(target='foo', source='foo.c') You must explicitly call &f-link-Export; and &f-link-Import; for variables that -you want to share between SConscript files. +you want to share between &SConscript; files. SConstruct: @@ -8179,7 +8183,7 @@ env.Program(target='src', source='src.c') Note the use of the &f-link-Export; method to set the cppdefines variable to a different -value each time we call the &SConscriptFunc; function. +value each time we call the &f-link-SConscript; function. @@ -8362,7 +8366,7 @@ env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) In general, &scons; is not controlled by environment variables set in the shell used to invoke it, leaving it -up to the SConscript file author to import those if desired. +up to the &SConscript; file author to import those if desired. However the following variables are imported by &scons; itself if set: -- cgit v0.12 From b6acf5ee664d1d4440bc02be33d4cf0f155e349f Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 8 Dec 2022 09:10:06 -0700 Subject: Tweak no-exec manpage wording [skip appveyor] Minor change - this was one of the options where the xml id was changed, and the previous wording just didn't seem to be that smooth. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 4d72180..8dda049 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -1611,24 +1611,29 @@ no matter how old the file is. -Set no execute mode. +Set no-exec mode. Print the commands that would be executed to build -any out-of-date target files, but do not execute the commands. - -The output is a best effort, as &SCons; cannot always precisely -determine what would be built. For example, if a file is generated -by a builder action that is later used in the build, -that file is not available to scan for dependencies on an unbuilt tree, -or may contain out of date information in a built tree. +any out-of-date targets, but do not execute those commands. + -Work which is done directly in &Python; code in &SConscript; files, -as opposed to work done by builder actions during the build phase, -will still be carried out. If it is important to avoid some -such work from taking place in no execute mode, it should be protected. -An &SConscript; file can determine which mode -is active by querying &f-link-GetOption;, as in the call -if GetOption("no_exec"): +Only target building is suppressed - any work in the build +system that is done directly (in regular &Python; code) +will still be carried out. You can add guards around +code which should not be executed in no-exec mode by +checking the value of the option at run time with &f-link-GetOption;: + + +if not GetOption("no_exec"): + # run regular instructions + + +The output is a best effort, as &SCons; cannot always precisely +determine what would be built. For example, if a file generated +by a builder action is also used as a source in the build, +that file is not available to scan for dependencies at all +in an unbuilt tree, and may contain out of date information in a +previously built tree. @@ -1682,7 +1687,7 @@ directories to the toolpath. -The type +The type of package to create when using the &b-link-Package; builder. Multiple types can be specified by using a comma-separated string, in which case &SCons; will try to build for all of those package types. -- cgit v0.12 From a8d1ef73713371da16300fd3bbd53cd993aa9e5d Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 8 Dec 2022 10:18:47 -0700 Subject: uguide: variant dir tweaking [skip appveyor] Try to clarify some more about variant dirs (people are still getting confused), without getting too technical about it, in the spirit of the User Guide. Also some stuff about hierarchical builds - both manpage and user guide. User guide chunks that were modified anyway had section IDs added. This is part of a plan to gradually get rid of horrible-looking autogenerated links which are not constant (problem when Google archives something and then maybe it doesn't work). May look like this in a browser: https://scons.org/doc/production/HTML/scons-user.html#idp105548893220944 With assigned IDs, looks more like: .../HTML/scons-user.html#sect-variant-sconscript So far only three userguide files changed. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 51 +++++++--- doc/user/hierarchy.xml | 90 ++++++++--------- doc/user/separate.xml | 267 ++++++++++++++++++++++++++++++------------------- doc/user/variants.xml | 34 ++----- 4 files changed, 249 insertions(+), 193 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 8dda049..824cd41 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -145,33 +145,44 @@ to support additional input file types. Information about files involved in the build, -including a cryptographic hash of the contents, +including a cryptographic hash of the contents of source files, is cached for later reuse. By default this hash (the &contentsig;) is used to determine if a file has changed since the last build, -but this can be controlled by selecting an appropriate +although this can be controlled by selecting an appropriate &f-link-Decider; function. Implicit dependency files are also part of out-of-date computation. The scanned implicit dependency information can optionally be cached and used to speed up future builds. -A hash of each executed build action (the &buildsig; +A hash of each executed build action (the &buildsig;) is cached, so that changes to build instructions (changing flags, etc.) or to the build tools themselves (new version) can also trigger a rebuild. +&SCons; supports the concept of separated source and build +directories through the definition of +variant directories +(see the &f-link-VariantDir; function). + + + When invoked, &scons; looks for a file named &SConstruct; in the current directory and reads the build configuration from that file (other names are allowed, -see for more information). -The &SConstruct; +see +and the option +for more information). +The build may be structured in a hierarchical manner: +the &SConstruct; file may specify subsidiary configuration files by calling the -&f-link-SConscript; function. +&f-link-SConscript; function, +and these may, in turn, do the same. By convention, these subsidiary files are named &SConscript;, @@ -182,7 +193,14 @@ is 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 such files. +regardless of the actual file names or number of such files. +A hierarchical build is not recursive - all of +the SConscript files are processed in a single pass, +although each is processed in a separate context so +as not to interfere with one another. &SCons; provides +mechanisms for information to be shared between +SConscript files when needed. + Before reading the &SConscript; files, &scons; @@ -870,9 +888,10 @@ files). duplicate -Print a line for each unlink/relink (or copy) of a variant file from -its source file. Includes debugging info for unlinking stale variant -files, as well as unlinking old targets before building them. +Print a line for each unlink/relink (or copy) of a file in +a variant directory from its source file. +Includes debugging info for unlinking stale variant directory files, +as well as unlinking old targets before building them. @@ -3686,9 +3705,9 @@ The default value is specifies a file which collects the output from commands that are executed to check for the existence of header files, libraries, etc. The default is #/config.log. -If you are using the -&VariantDir; function, -you may want to specify a subdirectory under your variant directory. +If you are using variant directories, +you may want to place the log file for a given build +under that build's variant directory. config_h specifies a C header file where the results of tests @@ -6720,7 +6739,7 @@ For example, the command line string: echo Last build occurred $TODAY. > $TARGET -but the build signature added to any target files would be computed from: +but the &buildsig; added to any target files would be computed from: echo Last build occurred . > $TARGET @@ -6741,8 +6760,8 @@ The callable must accept four arguments: env is the &consenv; to use for context, and for_signature is a boolean value that tells the callable -if it is being called for the purpose of generating a build signature. -Since the build signature is used for rebuild determination, +if it is being called for the purpose of generating a &buildsig;. +Since the &buildsig; is used for rebuild determination, variable elements that do not affect whether a rebuild should be triggered should be omitted from the returned string diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml index e63d230..17874d0 100644 --- a/doc/user/hierarchy.xml +++ b/doc/user/hierarchy.xml @@ -1,4 +1,10 @@ + + %scons; @@ -18,32 +24,8 @@ xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd"> -Hierarchical Builds - - +Hierarchical Builds + %scons; @@ -17,98 +23,111 @@ xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd"> -Separating Source and Build Trees: Variant Directories - + - It's often useful to keep any built files completely - separate from the source files. Consider if you have a - project to build software for a variety of different - controller hardware. The boards are able to share a - lot of code, so it makes sense to keep them in the same - source tree, but certain build options in the source code - and header files differ. If you build "Controller A" first, - then "Controller B", on the "Controller B" build everything would - have to be rebuilt, because &SCons; recognizes that the build - instructions are different from those used in the "Controller A" - build for each target - the build instructions are part of - &SCons;'s out-of-date calculation. - Now when you go back and build for "Controller A", - things have to be rebuilt from scratch again for the same reason. - However, if you can separate the locations of the output files, - this problem can be avoided. - You can even set up to do both builds in one invocation of &SCons;. + Having a separated build also helps you keep your source tree clean - + there is less chance of accidentally checking in build products + to version control that were not intended to be checked in. + You can add a separated build directory to your + version control system's list of items not to track. + You can even remove the whole build tree with a single command without + risking removing any of the source code. - You can enable this separation by establishing one or more - variant directory trees - that are used to perform the build in, and thus provide a unique - home for object files, libraries, and executable programs, etc. - for a specific flavor, or variant, of build. &SCons; tracks - targets by their path, so when the variant directory is included, - objects belonging to "Controller A" can have different - build instructions than those belonging to "Controller B" without - triggering ping-ponging rebuilds. + The key to making this separation work is the ability to + do out-of-tree builds: building under a separate root + than the sources being built. + You set up out of tree builds by establishing what &SCons; + calls a variant directory, + a place where you can build a single variant of your software + (of course you can define more than one of these if you need to). + Since &SCons; tracks targets by their path, it is able to distinguish + build products like build/A/network.obj + of the Controller A build + from build/B/network.obj + of the Controller B build, + thus avoiding conflicts. - &SCons; provides two ways to do this, - one through the &f-link-SConscript; function that we've already seen, + &SCons; provides two ways to establish variant directories, + one through the &f-link-SConscript; function that we have already seen, and the second through a more flexible &f-link-VariantDir; function. + + The variant directory mechanism does support doing multiple builds + in one invocation of &SCons;, but the remainder of this chapter + will focus on setting up a single build. You can combine these + techniques with ones from the previous chapter and elsewhere + in this Guide to set up more complex scenarios. + + + + - Historical note: the &VariantDir; function - used to be called &BuildDir;, a name which was - removed because the &SCons; functionality + The &VariantDir; function used to be called &BuildDir;, + a name which was changed because it turned out to be confusing: + the &SCons; functionality differs from a familiar model of a "build directory" - implemented by other build systems like GNU Autotools. + implemented by certain other build systems like GNU Autotools. You might still find references to the old name on the Internet in postings about &SCons;, but it no longer works. - + -
+
Specifying a Variant Directory Tree as Part of an &SConscript; Call The most straightforward way to establish a variant directory tree - relies the fact that the usual way to + relies on the fact that the usual way to set up a build hierarchy is to have an - SConscript file in the source subdirectory. + &SConscript; file in the source directory. If you pass a &variant_dir; argument to the &f-link-SConscript; function call: @@ -130,7 +149,7 @@ int main() { printf("Hello, world!\n"); } &SCons; will then build all of the files in - the &build; subdirectory: + the &build; directory: @@ -143,46 +162,73 @@ int main() { printf("Hello, world!\n"); } - No files were built in &src;, they went to &build;. - The build output might show a bit of a surprise: + No files were built in &src;: the object file build/hello.o and the executable file build/hello - were built in the &build; subdirectory, - as expected. - But even though our &hello_c; file lives in the &src; subdirectory, - &SCons; has actually compiled a + were built in the &build; directory, as expected. + But notice that even though our &hello_c; file actually + lives in the &src; directory, &SCons; has compiled a build/hello.c file to create the object file, and that file is now seen in &build;. + + + + + + You can ask &SCons; to show the dependency tree to illustrate + a bit more: + + scons -Q --tree=prune + + What's happened is that &SCons; has duplicated - the &hello_c; file from the &src; subdirectory - to the &build; subdirectory, + the &hello_c; file from the &src; directory + to the &build; directory, and built the program from there (it also duplicated &SConscript;). The next section explains why &SCons; does this. + + + The nice thing about the &SConscript; approach is it is almost + invisible to you: + this build looks just like an ordinary in-place build + except for the extra &variant_dir; argument in the + &f-link-SConscript; call. + &SCons; handles all the path adjustments for the + out of tree &build; directory while it processes that SConscript file. + + +
-
+
Why &SCons; Duplicates Source Files in a Variant Directory Tree - The important thing to understand is that when you set up a variant directory, - &SCons; performs the build in that directory. - It turns out it's easiest to ensure where build products end up - by just building in place. - Since the build is happening in a place different from where the - sources are, the most straightforward way to guarantee a correct build - is for &SCons; to copy them there. + When you set up a variant directory &SCons; conceptually behaves as + if you requested a build in that directory. + As noted in the previous chapter, + all builds actually happen from the top level directory, + but as an aid to understanding how &SCons; operates, think + of it as build in place in the variant directory, + not build in source but send build artifacts + to the variant directory. + It turns out in place builds are easier to get right than out + of tree builds - so by default &SCons; simulates an in place build + by making the variant directory look just like the source directory. + The most straightforward way to do that is by making copies + of the files needed for the build. @@ -192,7 +238,11 @@ int main() { printf("Hello, world!\n"); } in variant directories is simply that some tools (mostly older versions) are written to only build their output files - in the same directory as the source files. + in the same directory as the source files - such tools often don't + have any option to specify the output file, and the tool just + uses a predefined output file name, + or uses a derived variant of the source file name, + dropping the result in the same directory. In this case, the choices are either to build the output file in the source directory and move it to the variant directory, @@ -204,9 +254,9 @@ int main() { printf("Hello, world!\n"); } Additionally, relative references between files - can cause problems if we don't - just duplicate the hierarchy of source files - in the variant directory. + can cause problems which are resolved by + just duplicating the hierarchy of source files + into the variant directory. You can see this at work in use of the C preprocessor #include mechanism with double quotes, not angle brackets: @@ -240,8 +290,8 @@ int main() { printf("Hello, world!\n"); } Although source-file duplication guarantees a correct build - even in these end-cases, - it can usually be safely disabled. + even in these edge cases, + it can usually be safely disabled. The next section describes how you can disable the duplication of source files in the variant directory. @@ -250,19 +300,19 @@ int main() { printf("Hello, world!\n"); }
-
+
Telling &SCons; to Not Duplicate Source Files in the Variant Directory Tree In most cases and with most tool sets, - &SCons; can place its target files in a build subdirectory + &SCons; can use sources directly from the source directory without - duplicating the source files + duplicating them into the variant directory before building, and everything will work just fine. - You can disable the default &SCons; behavior + You can disable the default &SCons; duplication behavior by specifying duplicate=False - when you call the &SConscript; function: + when you call the &f-link-SConscript; function: @@ -272,11 +322,11 @@ SConscript('src/SConscript', variant_dir='build', duplicate=False) - When this flag is specified, - &SCons; uses the variant directory - like most people expect--that is, - the output files are placed in the variant directory - while the source files stay in the source directory: + When this flag is specified, the results of a build + look more like the mental model people may have from other + build systems - that is, + the output files end up in the variant directory + while the source files do not. @@ -292,14 +342,22 @@ hello hello.o + + + If disabling duplication causes any problems, + just return to the more cautious approach by letting + &SCons; go back to duplicating files. + + +
-
+
The &VariantDir; Function - Use the &VariantDir; function to establish that target + Use the &f-link-VariantDir; function to establish that target files should be built in a separate directory from the source files: @@ -318,8 +376,8 @@ int main() { printf("Hello, world!\n"); } - Note that when you're not using - an &SConscript; file in the &src; subdirectory, + Note that when you are not using + an &SConscript; file in the &src; directory, you must actually specify that the program must be built from the build/hello.c @@ -345,7 +403,7 @@ int main() { printf("Hello, world!\n"); } You can specify the same duplicate=False argument - that you can specify for an &SConscript; call: + that you can specify for an &f-link-SConscript; call: @@ -375,12 +433,12 @@ int main() { printf("Hello, world!\n"); }
-
+
Using &VariantDir; With an &SConscript; File - Even when using the &VariantDir; function, + Even when using the &f-link-VariantDir; function, it's more natural to use it with a subsidiary &SConscript; file, because then you don't have to adjust your individual @@ -428,21 +486,26 @@ int main() { printf("Hello, world!\n"); } - Notice that this is completely equivalent - to the use of &SConscript; that we - learned about in the previous section. + This is completely equivalent + to the use of &f-link-SConscript; with the + variant_dir argument + from earlier in this chapter, + but did require callng the SConscript using the already established + variant directory path to trigger that behavior. + If you use SConscript('src/SConscript') + you would get a normal in-place build in &src;.
-
+
Using &Glob; with &VariantDir; The &f-link-Glob; file name pattern matching function - works just as usual when using &VariantDir;. + works just as usual when using &f-link-VariantDir;. For example, if the src/SConscript looks like this: @@ -496,7 +559,7 @@ const char * f2(); + %scons; @@ -13,36 +19,12 @@ %variables-mod; ]> -
-Variant Build Examples - - +Variant Build Examples -- cgit v0.12 From c544c4c2dc2c4fe7c04703479f088377ac7cb0cf Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 14 Dec 2022 14:59:48 -0700 Subject: Clarify build tree separation wording [skip appveyor] Review pointed out that a use of the term "build" wasn't that clear, "build tree" would be more descriptive. Signed-off-by: Mats Wichmann --- doc/user/separate.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/separate.xml b/doc/user/separate.xml index f0636cc..4955d0e 100644 --- a/doc/user/separate.xml +++ b/doc/user/separate.xml @@ -61,7 +61,7 @@ Copyright The SCons Foundation - Having a separated build also helps you keep your source tree clean - + Having a separated build tree also helps you keep your source tree clean - there is less chance of accidentally checking in build products to version control that were not intended to be checked in. You can add a separated build directory to your -- cgit v0.12 From 889ce62c4c053a09bf9c8a029b848cc574297729 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 16 Dec 2022 07:49:43 -0700 Subject: uguide: clarify VariantDir example [skip appvyor] A little more tweaking to show all references have to be to the variant dir (the "implied target" form of the example might let readers miss it applies to targets too). Signed-off-by: Mats Wichmann --- doc/user/separate.xml | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/doc/user/separate.xml b/doc/user/separate.xml index 4955d0e..0485a55 100644 --- a/doc/user/separate.xml +++ b/doc/user/separate.xml @@ -35,7 +35,7 @@ Copyright The SCons Foundation - + Consider if you have a project to build an embedded software system for a variety of different controller hardware. @@ -78,7 +78,7 @@ Copyright The SCons Foundation than the sources being built. You set up out of tree builds by establishing what &SCons; calls a variant directory, - a place where you can build a single variant of your software + a place where you can build a single variant of your software (of course you can define more than one of these if you need to). Since &SCons; tracks targets by their path, it is able to distinguish build products like build/A/network.obj @@ -98,7 +98,7 @@ Copyright The SCons Foundation - + The variant directory mechanism does support doing multiple builds in one invocation of &SCons;, but the remainder of this chapter will focus on setting up a single build. You can combine these @@ -173,7 +173,7 @@ int main() { printf("Hello, world!\n"); } build/hello.c file to create the object file, and that file is now seen in &build;. - + @@ -217,7 +217,7 @@ int main() { printf("Hello, world!\n"); } When you set up a variant directory &SCons; conceptually behaves as - if you requested a build in that directory. + if you requested a build in that directory. As noted in the previous chapter, all builds actually happen from the top level directory, but as an aid to understanding how &SCons; operates, think @@ -357,8 +357,8 @@ hello.o - Use the &f-link-VariantDir; function to establish that target - files should be built in a separate directory + You can also use the &f-link-VariantDir; function to establish + that target files should be built in a separate directory tree from the source files: @@ -376,13 +376,18 @@ int main() { printf("Hello, world!\n"); } - Note that when you are not using - an &SConscript; file in the &src; directory, - you must actually specify that - the program must be built from - the build/hello.c - file that &SCons; will duplicate in the - &build; subdirectory. + When using this form, you have to tell &SCons; that + sources and targets are in the variant directory, + and those references will trigger the remapping, + necessary file copying, etc. for an already established + variant directory. Here is the same example in a more + spelled out form to show this more clearly: + + +VariantDir('build', 'src') +env = Environment() +env.Program(target='build/hello', source=['build/hello.c']) + @@ -439,7 +444,7 @@ int main() { printf("Hello, world!\n"); } Even when using the &f-link-VariantDir; function, - it's more natural to use it with + it is more natural to use it with a subsidiary &SConscript; file, because then you don't have to adjust your individual build instructions to use the variant directory path. @@ -492,7 +497,7 @@ int main() { printf("Hello, world!\n"); } from earlier in this chapter, but did require callng the SConscript using the already established variant directory path to trigger that behavior. - If you use SConscript('src/SConscript') + If you call SConscript('src/SConscript') you would get a normal in-place build in &src;. -- cgit v0.12 From 755ab60ef33cf62e2f887cfddb1b084b7f44ba21 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 16 Dec 2022 08:30:40 -0700 Subject: Updated RELEASE to show VariantDir updated [ci skip] Signed-off-by: Mats Wichmann --- RELEASE.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/RELEASE.txt b/RELEASE.txt index 2a32831..c158efb 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -105,6 +105,9 @@ DOCUMENTATION - Updated the User Guide chapter on installation: modernized the notes on Python installs, SCons installs, and having multiple SCons versions present on a single system. +- Updated the User Guide chapter on variant directories with more + explanation, and the introduction of terms like "out of tree" that + may help in forming a mental model. DEVELOPMENT ----------- -- cgit v0.12