From 4abe243870f36da0f53f055e587610e0f7104ef7 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 18 Apr 2024 06:52:33 -0600 Subject: Update docs for Variables Signed-off-by: Mats Wichmann --- CHANGES.txt | 1 + RELEASE.txt | 1 + doc/man/scons.xml | 432 ++++++++++++++++++++++++++++------------------ doc/scons.mod | 1 + doc/user/command-line.xml | 309 ++++++++++++++++++++------------- doc/user/output.xml | 6 +- 6 files changed, 456 insertions(+), 294 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index e938a74..45a195d 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -40,6 +40,7 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER build pdf versions which are then ignored. - Add the ability to print a Variables object for debugging purposes (provides a __str__ method in the class). + - Update manpage and user guide for Variables usage. RELEASE 4.7.0 - Sun, 17 Mar 2024 17:22:20 -0700 diff --git a/RELEASE.txt b/RELEASE.txt index 12d4b07..661cddf 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -63,6 +63,7 @@ DOCUMENTATION - Updated Value Node docs. - Update manpage for Tools, and for the TOOL variable. +- Update manpage and user guide for Variables usage. diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 0ac9916..e62e734 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -108,7 +108,7 @@ 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, -unless the experimental Ninja tool is used. +unless the experimental Ninja tool is used (requires the ninja package). Changed in version 4.3.0: @@ -4654,63 +4654,94 @@ env = conf.Finish() Command-Line Construction Variables Often when building software, -some variables need to 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; -provides a &Variables; -object to support overriding &consvars; with values obtained -from various sources, often from the command line: +specialized information needs to be conveyed at build time +to override the defaults in the build scripts. +Commandline arguments (like --implcit-cache) +and giving names of build targets are two ways to do that. +Another is to provide variable-assignment arguments +on the command line. +For the particular case where you want to specify new +values for &consvars;, +&SCons; provides a &Variables; +object to simplify collecting those +and updating a &consenv; with the values. +The typical calling style looks like: + scons VARIABLE=foo -The variable values can also be specified in a configuration file -or an &SConscript; file. + +Variables specified in the above way +can be manually processed by accessing the +&ARGUMENTS; dictionary +(or &ARGLIST; list), +but using a &Variables; object allows you to describe anticipated +variables and structure them into types with validation, +value conversion, defaults, help messages and aliases, +conceptually similar to the structure of options +(see &f-link-AddOption;). +It also allows pulling variables from a saved +configuration file or a custom dictionary in an &SConscript; file. +The processed variables can then be applied to the desired &consenv;. + + + +Conceptually, arguments are used to convey information to the +&SCons; program about how it should behave; +variables are used to convey information to the build +(though the line between the two is certainly not absolute). + -To obtain the object for manipulating values, -call the &Variables; function: +To obtain an object for manipulating variables, +call the &Variables; factory function: Variables([files, [args]]) -If files is a file or -list of files, they are executed as &Python; scripts, -and the values of (global) &Python; variables set in -those files are added as &consvars; in the &DefEnv;. -If no files are specified, +If files is a file or list of files, +they are considered to be &Python; scripts which will +be executed when the +Update +method is called - +this allows the use of &Python; syntax in the assignments. +If files is not specified, or the files argument is None, then no files will be read -(supplying None is necessary +(supplying None is required if there are no files but you want to specify -args as a positional argument). +args as a positional argument; +this can be omitted if using the keyword argument style). -The following example file +Either of the following example file contents could be used to set an alternative C compiler: CC = 'my_cc' +CC = os.environ.get('CC') If args -is specified, it is a dictionary of -values that will override anything read from -files. -The primary use is to pass the +is specified, it must be a dictionary. +The key-value pairs will be added to those +obtained from +files, if any. +Keys from args +take precendence over same-named keys from files. +The most common usage is to pass the &ARGUMENTS; dictionary that holds variables specified on the command line, allowing you to indicate that if a setting appears on both the command line and in the file(s), -the command line setting takes precedence. +the command line setting is preferred. However, any dictionary can be passed. Examples: @@ -4718,6 +4749,7 @@ Examples: vars = Variables('custom.py') vars = Variables('overrides.py', ARGUMENTS) vars = Variables(None, {FOO:'expansion', BAR:7}) +vars = Variables(args={FOO:'expansion', BAR:7}) @@ -4727,24 +4759,57 @@ Calling &Variables; with no arguments is equivalent to: vars = Variables(files=None, args=ARGUMENTS) + + + + + +A &Variables; object serves as a container for +descriptions of variables, +which are added by calling methods of the object. +Each variable consists of a name (which will +become a &consvar;), aliases for the name, +a help message, a default value, +and functions to validate and convert values. +Once the object is asked to process variables, +it matches up data from the input +sources it was given with the definitions, +and generates key-value pairs which are added +to the specified &consenv;, +except that if any variable was described +to have a default of None, +it is not added to +the construction environment unless it +appears in the input sources. +Otherwise, a variable not in the +input sources is added using its default value. + + Note that since the variables are eventually added as &consvars;, you should choose variable names which do not unintentionally change pre-defined &consvars; that your project will make use of -(see ). +(see for a reference), +since variables obtained have values overridden, not merged. - - - + +Also note there is currently no way to use the &Variables; +mechanism to define a variable which the user is +required to supply; +if necessary this can be implemented by accessing +&ARGUMENTS; directly, +although that only applies to the command-line, +not to any stored-values files. + -Variables objects have the following methods: +A Variables object has the following methods: - + vars.Add(key, [help, default, validator, converter]) -Add a customizable &consvar; to the Variables object. +Add a customizable &consvar; to the &Variables; object. key is either the name of the variable, or a tuple (or list), in which case @@ -4756,45 +4821,48 @@ is the help text for the variable default is the default value of the variable (default None). -If default is -None -and a value is not specified, -the &consvar; will not -be added to the &consenv;. + + +If the optional validator argument is supplied, +it is a callback function to validate the value of the variable. +A validator function must accept three arguments: +key, +value +and env, +and should raise an exception (with a helpful error message) +if value is invalid. +No return value is expected from the validator. + + + +If the optional converter argument is supplied, +it is a callback function to convert the value into +one suitable for adding to the environment, +and should accept either a value +or a value and &consenv; as parameters. +The converter is called before the validator; +it must return a value, which is then passed to the +validator (if any) +and finally added to the &consenv; - +it is recommended to avoid performing validation +checks in the converter. + + As a special case, if key is a tuple (or list) and is the only argument, the tuple is unpacked into the five parameters listed above left to right, with any missing members filled with -the respecitive default values. This form allows Add +the respective default values. This form allows &Add; to consume a tuple emitted by the convenience functions -BoolVariable, -EnumVariable, -ListVariable, -PackageVariable +&BoolVariable;, +&EnumVariable;, +&ListVariable;, +&PackageVariable; and -PathVariable. +&PathVariable;. - -If the optional validator is supplied, -it is called to validate the value of the variable. -A function supplied as a validator must accept -three arguments: key, -value and env, -and should raise an exception with a helpful error message -if value is invalid. -No return value is expected from the validator. - - -If the optional converter is supplied, -it is called to convert the value before putting it in the environment, -and should take either a value -or a value and environment as parameters. -The converter function must return a value, -which will be converted into a string and be passed to the -validator (if any) -and then added to the &consenv;. Examples: @@ -4815,7 +4883,7 @@ vars.Add('COLOR', validator=valid_color) A convenience method that adds one or more customizable &consvars; -to a Variables object in one call; +to a &Variables; object in one call; equivalent to calling &Add; multiple times. The args are tuples (or lists) @@ -4843,24 +4911,30 @@ opt.AddVariables( vars.Update(env, [args]) -Update a &consenv; +Process the arguments given as +files and/or +args +when the &Variables; object was created, +and update env with the customized &consvars;. Any specified variables that are not -configured for the Variables object -will be saved and may be -retrieved using the +configured in the &Variables; object +will be saved and may be retrieved using the &UnknownVariables; method. -Normally this method is not called directly, -but rather invoked indirectly by passing the Variables object to +Normally, &Update; is not called directly, +but rather invoked indirectly by passing the &Variables; object to the &f-link-Environment; function: -env = Environment(variables=vars) +env = Environment(..., variables=vars) + + + @@ -4868,11 +4942,15 @@ env = Environment(variables=vars) vars.UnknownVariables() Returns a dictionary containing any -variables that were specified -either in the files or the dictionary -with which the Variables object was initialized, -but for which the Variables object was -not configured. +variables that were specified in the +files and/or +args parameters +when &Variables; +was called, but the object was not actually configured for. +This information is not available until the +Update +method has run. + env = Environment(variables=vars) @@ -4886,13 +4964,14 @@ for key, value in vars.UnknownVariables(): vars.Save(filename, env) -Save the currently set variables into a script file named -by filename. Only variables that are -set to non-default values are saved. -You can load these saved settings on a subsequent run +Saves the currently set variables into a script file named +by filename. +This provides a way to cache particular variable settings for reuse. +Only variables that are set to non-default values are saved. +You can load these saved variables on a subsequent run by passing filename to the &Variables; function, -providing a way to cache particular settings for reuse. + @@ -4909,22 +4988,28 @@ vars.Save('variables.cache', env) vars.GenerateHelpText(env, [sort]) -Generate help text documenting the customizable construction -variables, suitable for passing in to the &f-link-Help; function. -env -is the &consenv; that will be used to get the actual values -of the customizable variables. If the (optional) -value of sort -is callable, it is used as a comparison function to + +Return a formatted string with the help text collected +from all the variables configured in this &Variables; object. +This string is suitable for passing in to the &f-link-Help; function. +The generated string include an indication of the +actual value in the environment given by env. + + + +If the optional +sort parameter is set to +a callable value, it is used as a comparison function to determine how to sort the added variables. This function must accept two arguments, compare them, and return a negative integer if the first is -less-than the second, zero for equality, or a positive integer -for greater-than. - -Optionally a Boolean value of True -for sort will cause a standard -alphabetical sort to be performed. +less-than the second, zero if equal, or a positive integer +if greater-than. +If sort is not callable, +but is set to True, +an alphabetical sort is performed. +The default is False (unsorted). + Help(vars.GenerateHelpText(env)) @@ -4943,7 +5028,7 @@ Help(vars.GenerateHelpText(env, sort=cmp)) Returns a formatted string containing the printable help text -for one option. +for the single option opt. It is normally not called directly, but is called by the &GenerateHelpText; method to create the returned help text. @@ -4965,31 +5050,30 @@ vars.FormatVariableHelpText = my_format - + -To make it more convenient to work with customizable Variables, -&scons; -provides a number of functions -that make it easy to set up -various types of Variables. -Each of these return a tuple ready to be passed to + +To make it more convenient to describe custom variables, +&SCons; provides some pre-defined variable types, +acessible through factory functions that generate +a tuple appropriate for directly passing to the &Add; or &AddVariables; method: - + BoolVariable(key, help, default) -Return a tuple of arguments -to set up a Boolean option. -The option will use + +Set up a Boolean variable. +The variable will use the specified name key, have a default value of default, and help will form the descriptive part of the help text. -The option will interpret the command-line values +The variable will interpret the command-line values y, yes, t, @@ -5015,30 +5099,26 @@ as false. EnumVariable(key, help, default, allowed_values, [map, ignorecase]) -Returns a tuple of arguments -to set up an option -whose value may be one -of a specified list of legal enumerated values. -The option will use -the specified name + +Set up a variable +whose value may only be from +a specified list ("enumeration") of values. +The variable will have the name key, have a default value of -default, +default and help will form the descriptive part of the help text. -The option will only support those -values in the +Any value that is not in allowed_values -list. -The optional +will raise an error, +except that the optional map argument is a dictionary -that can be used to convert -input values into specific legal values -in the -allowed_values -list. -If the value of +that can be used to map additional names into +a particular name in the +allowed_values list. +If the value of optional ignore_case is 0 @@ -5064,23 +5144,21 @@ converted to lower case. ListVariable(key, help, default, names, [map]) -Returns a tuple of arguments -to set up an option + +Set up a variable whose value may be one or more -of a specified list of legal enumerated values. -The option will use -the specified name +from a specified list of values. +The variable will have the name key, have a default value of default, and help will form the descriptive part of the help text. -The option will only accept the values -all, -none, -or the values in the -names -list. +Any value that is not in +names or the special values +all or +none +will raise an error. More than one value may be specified, separated by commas. The default may be a string of @@ -5103,60 +5181,72 @@ reflected in the generated help message). PackageVariable(key, help, default) -Returns a tuple of arguments -to set up an option -whose value is a path name -of a package that may be -enabled, disabled or -given an explicit path name. -The option will use -the specified name -key, -have a default value of + +Set up a variable for a package, +where if the variable is specified, +the &consvar; named by key +will end with a value of True, +False, or a user-specified value. +For example, +a package could be a third-party software component, +the build could use the information to +exclude the package, include the package in the standard way, +or include the package using a specified +directory path to find the package files. + + +The variable will have a default value default, and help will form the descriptive part of the help text. -The option will support the values +The variable supports (case-insensitive) truthy values +1, yes, true, on, enable -or -search, -in which case the specified -default -will be used, -or the option may be set to an -arbitrary string -(typically the path name to a package -that is being enabled). -The option will also support the values +and +search +to indicate the package is "enabled", +and the (case-insensitive) falsy values +0, no, false, off -or +and disable -to disable use of the specified option. +to indicate the package is "disabled". + + +The value +of the variable may also be set to an +arbitrary string, +which is taken to be the path name to the package +that is being enabled. +The validator will raise an exception +if this path does not exist in the filesystem. + PathVariable(key, help, default, [validator]) -Returns a tuple of arguments -to set up an option + +Set up a variable whose value is expected to be a path name. -The option will use -the specified name -key, -have a default value of +The &consvar; named by key +will have have a default value of default, and help will form the descriptive part of the help text. -An additional -validator -may be specified -that will be called to + + + +An optional +validator argument +may be specified. +The validator will be called to verify that the specified path is acceptable. SCons supplies the @@ -5209,14 +5299,14 @@ created as part of the build process, for example. You may supply your own validator function, -which must accept three arguments -(key, +which must accept three arguments: +key, the name of the variable to be set; val, the specified value being checked; and env, -the &consenv;) +the &consenv;, and should raise an exception if the specified value is not acceptable. diff --git a/doc/scons.mod b/doc/scons.mod index 2288879..e954916 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -291,6 +291,7 @@ Touch"> UnknownOptions"> UnknownVariables"> +Update"> diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index d8f9389..ede4825 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -26,11 +26,10 @@ SPDX-License-Identifier: MIT xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd"> Controlling a Build From the Command Line - + &SCons; provides a number of ways - for you as the writer of the &SConscript; files - to give you (and your users) + for you as the build system writer to grant the ability to control the build execution. The arguments that can be specified on the command line are broken down into three types: @@ -45,12 +44,13 @@ SPDX-License-Identifier: MIT - Command-line options always begin with - one or two - (hyphen) characters. + Command-line arguments that begin with a + - (hyphen) characters + are called options. &SCons; provides ways for you to examine - and set options values from within your &SConscript; files, - as well as the ability to define your own - custom options. + and act on options and their values, + as well as the ability to define custom options + for your project. See , below. @@ -63,17 +63,16 @@ SPDX-License-Identifier: MIT - Any command-line argument containing an = - (equal sign) is considered a variable setting with the form - variable=value. + Command-line arguments containing an = + (equal sign) character are called build variables + (or just variables). &SCons; provides direct access to - all of the command-line variable settings, - the ability to apply command-line variable settings - to &consenvs;, - and functions for configuring - specific types of variables - (Boolean values, path names, etc.) - with automatic validation of the specified values. + all of the build variable settings from the command line, + as well as a higher-level interface that lets you + define known build variables, + including defining types, default vaules, help text, + and automatic validation, + as well as applying those to a &consenv;. See , below. @@ -86,12 +85,12 @@ SPDX-License-Identifier: MIT - Any command-line argument that is not an option - or a variable setting - (does not begin with a hyphen - and does not contain an equal sign) - is considered a target that the you - are telling &SCons; to build. + Command-line arguments that are neither options + nor build variables + (that is, do not begin with a hyphen + and do not contain an equal sign) + are considered targets + that you are telling &SCons; to build. &SCons; provides access to the list of specified targets, as well as ways to set the default list of targets from within the &SConscript; files. @@ -108,21 +107,22 @@ SPDX-License-Identifier: MIT - &SCons; has many command-line options - that control its behavior. - An &SCons; command-line option - always begins with one or two hyphen (-) - characters. + &SCons; has many command-line options that control its behavior. + A command-line option always begins with one + or two hyphen (-) characters. + The &SCons; manual page contains the description of + the current options + (see ). -
+
Not Having to Specify Command-Line Options Each Time: the &SCONSFLAGS; Environment Variable You may find yourself using - the same command-line options every time + certain command-line options every time you run &SCons;. For example, you might find it saves time to specify -j 2 @@ -209,35 +209,33 @@ C:\Users\foo> set SCONSFLAGS="-Q"
-
+
Getting Values Set by Command-Line Options: the &GetOption; Function &SCons; provides the &f-link-GetOption; function - to get the values set by the various command-line options. + to query the values set by the various command-line options. - One use case for &GetOption; is to check whether or not - the or option - has been specified. + One use case for &GetOption; is to check the operation + mode in order to bypass some steps, + for example, checking whether + the (or ) + option was given. Normally, &SCons; does not print its help text until after it has read all of the SConscript files, - because it's possible that help text has been added - by some subsidiary SConscript file deep in the - source tree hierarchy. + since any SConscript can make additions to the help text. Of course, reading all of the SConscript files takes extra time. If you know that your configuration does not define any additional help text in subsidiary SConscript files, you can speed up displaying the command-line help - by using the &GetOption; function to load the - subsidiary SConscript files only if - the or option - has not been specified like this: + by using a &GetOption; query as a guard for whether + to load the subsidiary SConscript files: @@ -248,6 +246,15 @@ if not GetOption('help'): + The same technique can be used to special-case the + clean (GetOption('clean')) + and no-execute (GetOption('no_exec')) + modes. + + + + + In general, the string that you pass to the &f-GetOption; function to fetch the value of a command-line option setting is the same as the "most common" long option name @@ -265,7 +272,9 @@ if not GetOption('help'): &f-GetOption; can be used to retrieve the values of options defined by calls to &f-link-AddOption;. A &f-GetOption; call - must appear after the &f-AddOption; call for that option. + must appear after the &f-AddOption; call for that option + (unlike the defining of build targets, + this is a case where "order matters" in &SCons;). If the &f-AddOption; call supplied a dest keyword argument, a string with that name is what to pass as the argument to &f-GetOption;, otherwise it is a @@ -276,12 +285,12 @@ if not GetOption('help'):
-
+
Setting Values of Command-Line Options: the &SetOption; Function - You can also set the values of &SCons; + You can also set the values of certain (but not all) &SCons; command-line options from within the &SConscript; files by using the &f-link-SetOption; function. The strings that you use to set the values of &SCons; @@ -610,16 +619,17 @@ foo.in
-
+
Adding Custom Command-Line Options: the &AddOption; Function - &SCons; also allows you to define your own - command-line options with the &f-link-AddOption; function. + &SCons; lets you define your own command-line options + for the project with the &f-link-AddOption; function. The &AddOption; function takes the same arguments as the add_option method - from the standard Python library module optparse. + from the &Python; standard library module + optparse The &AddOption; function is, @@ -627,13 +637,14 @@ foo.in of optparse.OptionParser. + (see ). Once you add a custom command-line option with the &AddOption; function, the value of the option (if any) is immediately available - using the standard &f-link-GetOption; function. + using the &f-link-GetOption; function. The argument to &f-GetOption; must be the name of the variable which holds the option. If the dest @@ -723,35 +734,42 @@ foo.in - Option-arguments separated from long options by whitespace, - rather than by an =, cannot be correctly - resolved by &SCons;. - While - is clearly opt followed by arg, for + The optparse parser which &SCons; uses + allows option-arguments to follow their options after either + an = or space separator, + however the latter form does not work well in &SCons; for + added options and should be avoided. + &SCons; does not place an ordering constraint on the + types of command-line arguments, + so while is unambiguous, + for it is not possible to tell without instructions whether ARG is an argument belonging to the - input option or a positional argument. - &SCons; treats positional arguments as either - command-line build options or command-line targets - which are made available for use in an &SConscript; + input option or a standalone word. + &SCons; considers words on the command line which do not + begin with hyphen as either command-line build variables + or command-line targets, + both of which are made available for use in an &SConscript; (see the immediately following sections for details). Thus, they must be collected before &SConscript; processing - takes place. Since &AddOption; calls, which provide - the processing instructions to resolve any ambiguity, - happen in an &SConscript;, - &SCons; does not know in time - for options added this way, and unexpected things happen, - such as option-arguments assigned as targets and/or exceptions - due to missing option-arguments. - - - As a result, this usage style should be avoided when invoking - &scons;. For single-argument - options, use the form on the - command line. For multiple-argument options - (nargs greater than one), - set nargs to one in - &AddOption; calls and either: combine the option-arguments into one word + takes place. &AddOption; calls do provide the + the necessary instructions to resolve the ambiguity, + but as they appear in &SConscript; files, + &SCons; does not have the information early enough, + and unexpected things may happen, + such as option-arguments appearing in the list of targets, + and processing exceptions due to missing option-arguments. + + + As a result, + this usage style should be avoided when invoking &scons;. + For single-argument options, + tell your users to use the + form on the command line. + For multiple-argument options + (nargs value greater than one), + set nargs to one in the + &AddOption; call and either: combine the option-arguments into one word with a separator, and parse the result in your own code (see the built-in option, which allows specifying multiple arguments as a single comma-separated @@ -795,7 +813,7 @@ foo.in aspects of your build in response to specifications on the command line. (Note that unless you want to require - a variable always + a variable to always be specified you probably want to use the Python dictionary get method, which allows you to designate a default value @@ -841,9 +859,38 @@ prog.c scons -Q debug=1 + + + Two usage notes (both shown in the example above): + + + + + No matter how you intend to use them, the values read from + a command line (i.e., external to the program) are + always strings. You may need to do type conversion. + + + + + When you retrieve from the &ARGUMENTS; dictionary, + it is useful to use the &Python; dictionary + get method, + so you can supply a default value if there is not + one given on the command line. Otherwise, the build + will fail with a KeyError + if the user does not supply the build option. + + + + + + + + - &SCons; keeps track of the precise command line used to build each object file, + &SCons; keeps track of the precise build command used to build each object file, and as a result can determine that the object and executable files need rebuilding when the value of the debug argument has changed. @@ -854,7 +901,7 @@ prog.c The &ARGUMENTS; dictionary has two minor drawbacks. First, because it is a dictionary, - it can only store one value for each specified keyword, + it can only map each keyword to one value, and thus only "remembers" the last setting for each keyword on the command line. This makes the &ARGUMENTS; dictionary @@ -868,17 +915,18 @@ prog.c you want the configuration to behave differently in response to the order in which the build - variable settings were specified on the command line. + variable settings were specified on the command line + (&Python; versions since 3.6 now maintain dictionaries in + insertion order, so this problem is mitigated). To accomodate these requirements, - &SCons; provides an &ARGLIST; variable - that gives you direct access to - variable=value - settings on the command line, + &SCons; also provides an &ARGLIST; variable + that gives you direct access to build variable + settings from the command line, in the exact order they were specified, and without removing any duplicate settings. Each element in the &ARGLIST; variable @@ -946,7 +994,7 @@ prog.c -
+
Controlling Command-Line Build Variables @@ -958,8 +1006,8 @@ prog.c check for errors and provide appropriate messages, and apply the values to a &consvar;. To help with this, - &SCons; provides a &Variables; class to - define such build variables easily, + &SCons; provides a &Variables; container class to + hold defintions of such build variables, and a mechanism to apply the build variables to a &consenv;. This allows you to control how the build variables affect @@ -974,7 +1022,7 @@ prog.c command line whenever the time comes to build a program for release, and that the value of this variable - should be added to the command line + should be added to the build command with the appropriate define to pass the value to the C compiler. Here's how you might do that by setting @@ -1000,9 +1048,8 @@ bar.c - This &SConstruct; file first creates a &Variables; object - which uses the values from the command-line options dictionary &ARGUMENTS; - (the vars=Variables(None, ARGUMENTS) call). + This &SConstruct; snippet first creates a &Variables; object which + uses the values from the command-line variables dictionary &ARGUMENTS;. It then uses the object's &Add; method to indicate that the &RELEASE; variable can be set on the command line, and that @@ -1025,15 +1072,32 @@ bar.c - Historical note: In old &SCons; (prior to 0.98.1), + The Variables() call in this example looks + a little awkward. The function takes two optional arguments: + a script name and a dictionary. In order to specify the + dictionary as the second argument, you must provide the + script argument as the first; since there's actually no script, + use None as a sentinel value. + However, if you omit all the arguments, + the default behavior is to read from the &ARGUMENTS; dictionary anyway, + which is what we want. The example shows it this way because the arguments + were introduced in this order, but you should feel free to just + leave off the arguments if the default behavior is what you want. + + + + + + Historical note: In old &SCons; (prior to 0.98.1 from 2008), these build variables were known as "command-line build options." - At that time, class was named &Options; + At that time, the class was named &Options; and the predefined functions to construct options were named &BoolOption;, &EnumOption;, &ListOption;, &PathOption;, &PackageOption; and &AddOptions; (contrast with the current names in , below). - You may encounter these names in older + Because the Internet has a very long memory, + you may encounter these names in older &SConscript; files, wiki pages, blog entries, StackExchange articles, etc. These old names no longer work, but a mental substitution @@ -1044,19 +1108,19 @@ bar.c
-
+
Providing Help for Command-Line Build Variables - To make command-line build variables most useful, - you ideally want to provide + To make command-line build variables more useful, + you may want to provide some help text to describe the available variables - when the you ask for help (run scons -h). + when you ask for help (run scons -h). You can write this text by hand, but &SCons; provides some assistance. Variables objects provide a - &GenerateHelpText; method the + &GenerateHelpText; method to generate text that describes the various variables that have been added to it. The default text includes @@ -1072,7 +1136,7 @@ bar.c -vars = Variables(None, ARGUMENTS) +vars = Variables() vars.Add('RELEASE', help='Set to 1 to build for release', default=0) env = Environment(variables=vars) Help(vars.GenerateHelpText(env)) @@ -1081,7 +1145,7 @@ Help(vars.GenerateHelpText(env)) - &SCons; now displays some useful text + &scons; now displays some useful text when the option is used: @@ -1099,7 +1163,7 @@ Help(vars.GenerateHelpText(env))
-
+
Reading Build Variables From a File @@ -1112,8 +1176,7 @@ Help(vars.GenerateHelpText(env)) every time you run &SCons;. To make this easier, you can provide customized build variable settings - in a local file by providing a - file name when the + in a &Python; script by providing a file name when the &Variables; object is created: @@ -1140,7 +1203,7 @@ RELEASE = 1 This then allows you to control the &RELEASE; - variable by setting it in the &custom_py; file: + variable by setting it in the &custom_py; script: @@ -1149,7 +1212,7 @@ RELEASE = 1 Note that this file is actually executed - like a Python script. + like a &Python; script. Now when you run &SCons;: @@ -1206,11 +1269,17 @@ vars = Variables('custom.py', ARGUMENTS) - where values in the option file &custom_py; get overwritten - by the ones specified on the command line. + If both a variables script and a dictionary are supplied, + the dictionary is evaluated last, so values from the + command line "win" if there are any duplicate keys. + This rule allows you to move some common settings + to a variables script, but still be able to override those + for a given build without changing the script. + +
@@ -1219,7 +1288,7 @@ vars = Variables('custom.py', ARGUMENTS) &SCons; provides a number of convenience functions - that provide ready-made behaviors + that provide pre-made behavior definitions for various types of command-line build variables. These functions all return a tuple which is ready to be passed to the &Add; or &AddVariables; method call. @@ -1228,7 +1297,7 @@ vars = Variables('custom.py', ARGUMENTS) -
+
True/False Values: the &BoolVariable; Build Variable Function @@ -1340,7 +1409,7 @@ foo.c
-
+
Single Value From a Selection: the &EnumVariable; Build Variable Function @@ -1576,7 +1645,7 @@ foo.c
-
+
Multiple Values From a List: the &ListVariable; Build Variable Function @@ -1670,7 +1739,7 @@ foo.c
-
+
Path Names: the &PathVariable; Build Variable Function @@ -1856,7 +1925,7 @@ foo.c
-
+
Enabled/Disabled Path Names: the &PackageVariable; Build Variable Function @@ -1915,7 +1984,7 @@ foo.c
-
+
Adding Multiple Command-Line Build Variables at Once @@ -1971,7 +2040,7 @@ vars.AddVariables(
-
+
Handling Unknown Command-Line Build Variables: the &UnknownVariables; Function @@ -2074,7 +2143,7 @@ foo.c
Command-Line Targets -
+
Fetching Command-Line Targets: the &COMMAND_LINE_TARGETS; Variable @@ -2132,7 +2201,7 @@ foo.c
-
+
Controlling the Default Targets: the &Default; Function @@ -2336,7 +2405,7 @@ prog2.c scons -Q . -
+
Fetching the List of Default Targets: the &DEFAULT_TARGETS; Variable @@ -2432,7 +2501,7 @@ prog2.c
-
+
Fetching the List of Build Targets, Regardless of Origin: the &BUILD_TARGETS; Variable diff --git a/doc/user/output.xml b/doc/user/output.xml index ebcf06e..9fc00aa 100644 --- a/doc/user/output.xml +++ b/doc/user/output.xml @@ -39,7 +39,7 @@ SPDX-License-Identifier: MIT -
+
Providing Build Help: the &Help; Function @@ -360,7 +360,7 @@ cc -o foo foo.o
-
+
Providing Build Progress Output: the &Progress; Function @@ -593,7 +593,7 @@ Progress(progress_function)
-
+
Printing Detailed Build Status: the &GetBuildFailures; Function -- cgit v0.12 From edab5fe44446ddf1c6aef23c737d161c80785342 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sat, 20 Apr 2024 10:11:00 -0600 Subject: More manpage tweaking of Variables and ARGUMENTS Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 102 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 59 insertions(+), 43 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index e62e734..14a3003 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -391,8 +391,8 @@ and can be used in the &SConscript; files to modify the build in any way: -if ARGUMENTS.get('debug', 0): - env = Environment(CCFLAGS='-g') +if ARGUMENTS.get("debug", ""): + env = Environment(CCFLAGS="-g") else: env = Environment() @@ -401,8 +401,8 @@ else: 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). +if necessary. Each &ARGLIST; entry is a tuple consisting +of the name and the value. @@ -3478,7 +3478,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 for run-time queries in &SConscript; files to affect how you want the build to be performed. @@ -3486,12 +3486,12 @@ to affect how you want the build to be performed. &ARGLIST; A list of the -keyword=value -arguments specified on the command line. +variable=value +build variable arguments specified on the command line. Each element in the list is a tuple -containing the argument. +consisting of the variable and its value. The separate -keyword +variable and value elements of the tuple @@ -3501,16 +3501,25 @@ subscripting for elements and [1] of the tuple, or, more readably, by using tuple unpacking. -Example: +Examples: -print("first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]) -print("second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]) -key, value = ARGLIST[2] -print("third keyword, value =", key, value) -for key, value in ARGLIST: - # process key and value +print("first variable, value =", ARGLIST[0][0], ARGLIST[0][1]) +print("second variable, value =", ARGLIST[1][0], ARGLIST[1][1]) +var, value = ARGLIST[2] +print("third variable, value =", var, value) +for var, value in ARGLIST: + # process variable and value + + +The values obtained from &ARGLIST; +(or from &ARGUMENTS;) +are always strings since they originate from outside the &SCons; process. +As "untrusted data", +they should be validated before usage, +and may need conversion to an appropriate type. + @@ -3518,24 +3527,28 @@ for key, value in ARGLIST: &ARGUMENTS; A dictionary of all the -keyword=value -arguments specified on the command line. -The dictionary is not in order, -and if a given keyword has +variable=value +build variable arguments specified on the command line. +The dictionary is in command-line order, +so if a given variable has more than one value assigned to it on the command line, the last (right-most) value is -the one in the &ARGUMENTS; +the one saved in the &ARGUMENTS; dictionary. Example: -if ARGUMENTS.get('debug', 0): - env = Environment(CCFLAGS='-g') +if ARGUMENTS.get("debug", ""): + env = Environment(CCFLAGS="-g") else: env = Environment() + + +See also &ARGLIST;. + @@ -3570,8 +3583,7 @@ list of targets specified using the &Default; function, the contents of the list may change on each successive call to &Default;. -See the -&DEFAULT_TARGETS; list, below, +See &DEFAULT_TARGETS; for additional information. Example: @@ -3590,12 +3602,13 @@ if 'special/program' in BUILD_TARGETS: A list of the targets explicitly specified on the command line. If there are command line targets, -this list will have the same contents as &BUILD_TARGETS;. +this list has the same contents as +&BUILD_TARGETS;. If there are no targets specified on the command line, the list is empty. The elements of this list are strings. This can be used, for example, to take specific actions only -when certain targets are explicitly being built. +when a certain targets is explicitly requested for building. Example: @@ -3617,7 +3630,7 @@ that have been specified using the &f-link-Default; function. If there are no command line targets, this list will have the same contents as -&BUILD_TARGETS;. +&BUILD_TARGETS;. Since the elements of the list are nodes, you need to call the &Python; str @@ -4656,7 +4669,7 @@ env = conf.Finish() Often when building software, specialized information needs to be conveyed at build time to override the defaults in the build scripts. -Commandline arguments (like --implcit-cache) +Command-line arguments (like --implcit-cache) and giving names of build targets are two ways to do that. Another is to provide variable-assignment arguments on the command line. @@ -4677,21 +4690,23 @@ Variables specified in the above way can be manually processed by accessing the &ARGUMENTS; dictionary (or &ARGLIST; list), -but using a &Variables; object allows you to describe anticipated -variables and structure them into types with validation, -value conversion, defaults, help messages and aliases, -conceptually similar to the structure of options +but using a &Variables; object allows you to describe +anticipated variables, +convert them to a suitable type if necessary, +validate the values are within defined constraints, +and define defaults, help messages and aliases. +This is conceptually similar to the structure of options (see &f-link-AddOption;). -It also allows pulling variables from a saved -configuration file or a custom dictionary in an &SConscript; file. +It also allows obtaining values from a saved variables file, +or from a custom dictionary in an &SConscript; file. The processed variables can then be applied to the desired &consenv;. -Conceptually, arguments are used to convey information to the +Roughly speaking, arguments are used to convey information to the &SCons; program about how it should behave; variables are used to convey information to the build -(though the line between the two is certainly not absolute). +(although &SCons; does not enforce any such constraint). To obtain an object for manipulating variables, @@ -4731,8 +4746,8 @@ CC = os.environ.get('CC') If args is specified, it must be a dictionary. -The key-value pairs will be added to those -obtained from +The key-value pairs from args +will be added to those obtained from files, if any. Keys from args take precendence over same-named keys from files. @@ -4799,7 +4814,7 @@ mechanism to define a variable which the user is required to supply; if necessary this can be implemented by accessing &ARGUMENTS; directly, -although that only applies to the command-line, +although that only applies to the command line, not to any stored-values files. @@ -4884,15 +4899,16 @@ vars.Add('COLOR', validator=valid_color) A convenience method that adds one or more customizable &consvars; to a &Variables; object in one call; -equivalent to calling &Add; multiple times. +equivalent to calling +Add +multiple times. The args are tuples (or lists) that contain the arguments for an individual call to the &Add; method. Since tuples are not &Python; mappings, the arguments cannot use the keyword form, -but rather are positional arguments as documented for -Add: +but rather are positional arguments as documented for &Add;: a required name, the other four optional, but must be in the specified order if used. -- cgit v0.12 From cfb272b86f8faef32cb1011c9a79255b20a168f9 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 23 Apr 2024 08:07:49 -0600 Subject: A few more Variables doc tweaks Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 111 +++++++++++++++++++++++++++++++++--------------------- doc/scons.mod | 1 + 2 files changed, 69 insertions(+), 43 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 14a3003..a747c4c 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -4716,22 +4716,26 @@ call the &Variables; factory function: Variables([files, [args]]) -If files is a file or list of files, +If files is a filename or list of filenames, they are considered to be &Python; scripts which will -be executed when the +be executed to set variables when the Update method is called - this allows the use of &Python; syntax in the assignments. +A file can be the result of an earlier call to the +&Save; method. If files is not specified, or the files argument is None, -then no files will be read -(supplying None is required +then no files will be read. +Supplying None is required if there are no files but you want to specify args as a positional argument; -this can be omitted if using the keyword argument style). +this can be omitted if using the keyword argument style. +If any of files is missing, +it is silently skipped. @@ -4751,10 +4755,11 @@ will be added to those obtained from files, if any. Keys from args take precendence over same-named keys from files. -The most common usage is to pass the -&ARGUMENTS; dictionary that holds variables -specified on the command line, -allowing you to indicate that if a setting appears +If omittted, the default is the +&ARGUMENTS; +dictionary that holds build variables +specified on the command line. +Using &ARGUMENTS; allows you to indicate that if a setting appears on both the command line and in the file(s), the command line setting is preferred. However, any dictionary can be passed. @@ -4827,20 +4832,25 @@ not to any stored-values files. Add a customizable &consvar; to the &Variables; object. key is either the name of the variable, -or a tuple (or list), in which case -the first item in the tuple is taken as the variable name, +or a sequence of strings, in which case +the first item in the sequence is taken as the variable name, and any remaining values are considered aliases for the variable. +key is mandatory, +there is no default. help is the help text for the variable -(default empty string). +(defaults to an empty string). default is the default value of the variable -(default None). +(defaults to None). If the optional validator argument is supplied, -it is a callback function to validate the value of the variable. +it is a callback function to validate the value of the variable +when the variables are processed +(that is, when the &Update; +method runs). A validator function must accept three arguments: key, value @@ -4853,23 +4863,34 @@ No return value is expected from the validator. If the optional converter argument is supplied, it is a callback function to convert the value into -one suitable for adding to the environment, -and should accept either a value -or a value and &consenv; as parameters. +one suitable for adding to the &consenv;. +A converter function must accept the +value argument, +and may declare env +as a second argument if it needs access to the +&consenv; while validating - the function will be called appropriately. The converter is called before the validator; it must return a value, which is then passed to the -validator (if any) -and finally added to the &consenv; - -it is recommended to avoid performing validation -checks in the converter. +validator (if any) for checking. +In general, the converter should not fail, +leaving validation checks to the validator, +although if an operation is impossible to complete +or there is no separate validator +it can raise a ValueError. As a special case, if key -is a tuple (or list) and is the only -argument, the tuple is unpacked into the five parameters -listed above left to right, with any missing members filled with -the respective default values. This form allows &Add; +is a sequence and is the only +argument to &Add;, it is unpacked into the five parameters +key, +help, +default, +validator and +converter, +with any missing members from the right filled in with +the respective default values. +This form allows it to consume a tuple emitted by the convenience functions &BoolVariable;, &EnumVariable;, @@ -4902,15 +4923,12 @@ to a &Variables; object in one call; equivalent to calling Add multiple times. -The args -are tuples (or lists) -that contain the arguments -for an individual call to the &Add; method. -Since tuples are not &Python; mappings, -the arguments cannot use the keyword form, -but rather are positional arguments as documented for &Add;: -a required name, the other four optional, -but must be in the specified order if used. +Each args member +must be a tuple that contains the arguments +for an individual call to the &Add; method +using the "special case" form; +the other calling styles (individual positional +arguments and/or keyword arguments) are not supported. @@ -4927,19 +4945,26 @@ opt.AddVariables( vars.Update(env, [args]) -Process the arguments given as -files and/or -args -when the &Variables; object was created, +Process the input sources recorded +when the &Variables; object was initialized and update env with the customized &consvars;. -Any specified variables that are not +The names of any variables in the input sources that are not configured in the &Variables; object -will be saved and may be retrieved using the +are recorded and may be retrieved using the &UnknownVariables; method. + +If the optional +args +argument is provided, it is a dictionary of variables +to use in place of the one saved when +&Variables; +was called. + + Normally, &Update; is not called directly, but rather invoked indirectly by passing the &Variables; object to the &f-link-Environment; function: @@ -5177,9 +5202,9 @@ Any value that is not in will raise an error. More than one value may be specified, separated by commas. -The default may be a string of -comma-separated default values, -or a list of the default values. +default may be specified +either as a string of comma-separated value, +or as a list of values. The optional map argument is a dictionary diff --git a/doc/scons.mod b/doc/scons.mod index e954916..d44cfbd 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -279,6 +279,7 @@ Return"> RuleSet"> Salt"> +Save"> SetBuildSignatureType"> SetContentSignatureType"> SetDefault"> -- cgit v0.12 From cf259b4e01eab803a159975b9b14cc21a1fd1cb5 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 25 Apr 2024 06:48:29 -0600 Subject: Variables docs: fix some review comments Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 3 --- doc/user/command-line.xml | 31 ++++++++++++------------------- 2 files changed, 12 insertions(+), 22 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index a747c4c..22d3d00 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -4973,9 +4973,6 @@ the &f-link-Environment; function: env = Environment(..., variables=vars) - - - diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index ede4825..63fd0eb 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -28,9 +28,9 @@ SPDX-License-Identifier: MIT - &SCons; provides a number of ways - for you as the build system writer to grant - the ability to control the build execution. + Software builds are rarely completely static, + so &SCons; gives you a number of ways to help control + build execution via instructions on the command line. The arguments that can be specified on the command line are broken down into three types: @@ -70,7 +70,7 @@ SPDX-License-Identifier: MIT all of the build variable settings from the command line, as well as a higher-level interface that lets you define known build variables, - including defining types, default vaules, help text, + including defining types, default values, help text, and automatic validation, as well as applying those to a &consenv;. See , below. @@ -117,7 +117,7 @@ SPDX-License-Identifier: MIT
- Not Having to Specify Command-Line Options Each Time: the &SCONSFLAGS; Environment Variable + Not Having to Type Command-Line Options Each Time: the &SCONSFLAGS; Environment Variable @@ -214,8 +214,8 @@ C:\Users\foo> set SCONSFLAGS="-Q" - &SCons; provides the &f-link-GetOption; function - to query the values set by the various command-line options. + The &f-link-GetOption; function + lets you query the values set by the various command-line options. @@ -624,7 +624,7 @@ foo.in - &SCons; lets you define your own command-line options + You can also define your own command-line options for the project with the &f-link-AddOption; function. The &AddOption; function takes the same arguments as the add_option method @@ -812,13 +812,6 @@ foo.in This allows you to modify aspects of your build in response to specifications on the command line. - (Note that unless you want to require - a variable to always - be specified you probably want to use - the Python dictionary get method, - which allows you to designate a default value - to be used if there is no specification - on the command line.) @@ -876,10 +869,10 @@ prog.c When you retrieve from the &ARGUMENTS; dictionary, it is useful to use the &Python; dictionary get method, - so you can supply a default value if there is not - one given on the command line. Otherwise, the build + so you can supply a default value if the variable is + not given on the command line. Otherwise, the build will fail with a KeyError - if the user does not supply the build option. + if the variable is not set. @@ -1288,7 +1281,7 @@ vars = Variables('custom.py', ARGUMENTS) &SCons; provides a number of convenience functions - that provide pre-made behavior definitions + that provide behavior definitions for various types of command-line build variables. These functions all return a tuple which is ready to be passed to the &Add; or &AddVariables; method call. -- cgit v0.12 From 5c6c15b55776a9cfe34691679e55cd8bed683700 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Sat, 4 May 2024 12:53:45 -0700 Subject: More spelling/typo fixes --- doc/user/command-line.xml | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index 63fd0eb..c8d5e12 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -353,7 +353,7 @@ foo.in NUM_CPU environment variable. (This is one of the exception cases where the string is spelled differently from - the from command-line option. + the command-line option. The string for fetching or setting the value is num_jobs for historical reasons.) @@ -387,9 +387,9 @@ foo.in But any explicit or value you specify on the command line is used first, - regardless of whether or not + whether the NUM_CPU environment - variable is set: + variable is set or not: @@ -753,7 +753,7 @@ foo.in (see the immediately following sections for details). Thus, they must be collected before &SConscript; processing takes place. &AddOption; calls do provide the - the necessary instructions to resolve the ambiguity, + necessary instructions to resolve the ambiguity, but as they appear in &SConscript; files, &SCons; does not have the information early enough, and unexpected things may happen, @@ -916,7 +916,7 @@ prog.c - To accomodate these requirements, + To accommodate these requirements, &SCons; also provides an &ARGLIST; variable that gives you direct access to build variable settings from the command line, @@ -1000,7 +1000,7 @@ prog.c and apply the values to a &consvar;. To help with this, &SCons; provides a &Variables; container class to - hold defintions of such build variables, + hold definitions of such build variables, and a mechanism to apply the build variables to a &consenv;. This allows you to control how the build variables affect @@ -1101,7 +1101,7 @@ bar.c
-
+
Providing Help for Command-Line Build Variables @@ -1161,7 +1161,7 @@ Help(vars.GenerateHelpText(env)) - Being able to to specify the + Being able to specify the value of a build variable on the command line is useful, but can still become tedious @@ -1271,7 +1271,7 @@ vars = Variables('custom.py', ARGUMENTS) - +
@@ -1298,11 +1298,11 @@ vars = Variables('custom.py', ARGUMENTS) It is often handy to be able to specify a variable that controls a simple Boolean variable with a &true; or &false; value. - It would be even more handy to accomodate + It would be even more handy to accommodate different preferences for how to represent &true; or &false; values. The &BoolVariable; function - makes it easy to accomodate these + makes it easy to accommodate these common representations of &true; or &false;. @@ -2005,7 +2005,7 @@ vars = Variables() vars.AddVariables( ('RELEASE', 'Set to 1 to build for release', 0), ('CONFIG', 'Configuration file', '/etc/my_config'), - BoolVariable('warnings', help='compilation with -Wall and similiar', default=True), + BoolVariable('warnings', help='compilation with -Wall and similar', default=True), EnumVariable( 'debug', help='debug output and symbols', @@ -2173,7 +2173,7 @@ foo.c Now, running &SCons; with the default target works as usual, - but explicity specifying the &bar; target + but explicitly specifying the &bar; target on the command line generates the warning message: @@ -2430,7 +2430,7 @@ prog1.c - (Keep in mind that all of the manipulation of the + (Keep in mind that the manipulation of the &DEFAULT_TARGETS; list takes place during the first phase when &SCons; is reading up the &SConscript; files, which is obvious if -- cgit v0.12 From f644fc6a18f32018746a2f0546fadc2449e9e0db Mon Sep 17 00:00:00 2001 From: William Deegan Date: Sat, 4 May 2024 13:11:00 -0700 Subject: Reword one title, and fix id's --- doc/user/command-line.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index c8d5e12..fea1af1 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -117,7 +117,7 @@ SPDX-License-Identifier: MIT
- Not Having to Type Command-Line Options Each Time: the &SCONSFLAGS; Environment Variable + How To Avoid Typing Command-Line Options Each Time: the &SCONSFLAGS; Environment Variable @@ -619,7 +619,7 @@ foo.in
-
+
Adding Custom Command-Line Options: the &AddOption; Function @@ -1101,7 +1101,7 @@ bar.c
-
+
Providing Help for Command-Line Build Variables -- cgit v0.12