From 9b809a71fe4babb7766d31e1c19ef0a9545ef2b5 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 13 Apr 2020 12:16:52 -0600 Subject: docs: update Variables content [ci skip] * Apply current formatting styles for funcs/methods (that is, func/method name is marked up, instance name is marked up, params are marked up, each with the appropriate docbook tag. * Word around the obsolete reference to built-in cmp function, which no longer exists in Python 3. We should probably transtion the API towards taking a key function instead, since that conversion is already done internally. * Clarify the way AddVariables is described - it takes a list of tuples, but that "list" isn't a Python list object, but rather one or more tuples, varargs-style. Also describe the content of the tuples. * Tweak some other wordings on variable helpers and validators. * Rework userguide chapter examples to use keyword arguments for calls to Add and for the *Variable functions. * Add a User Guide example of a help message that is more than a simple one (reuses an EnumVariable example) to illustrate that the generated help text is more than the help=helpstring. * Word differently the back-reference to Options in the User Guide. Signed-off-by: Mats Wichmann --- .../examples/commandline_EnumVariable_3.xml | 16 +- .../examples/commandline_EnumVariable_4.xml | 13 + doc/man/scons.xml | 360 +++++++++++---------- doc/user/command-line.xml | 263 ++++++++------- 4 files changed, 343 insertions(+), 309 deletions(-) create mode 100644 doc/generated/examples/commandline_EnumVariable_4.xml diff --git a/doc/generated/examples/commandline_EnumVariable_3.xml b/doc/generated/examples/commandline_EnumVariable_3.xml index bb9a6d5..eb5d3c1 100644 --- a/doc/generated/examples/commandline_EnumVariable_3.xml +++ b/doc/generated/examples/commandline_EnumVariable_3.xml @@ -1,14 +1,8 @@ - -% scons -Q COLOR=Red foo.o +% scons -Q -h -scons: *** Invalid value for option COLOR: Red. Valid values are: ('red', 'green', 'blue') -File "/home/my/project/SConstruct", line 5, in <module> -% scons -Q COLOR=BLUE foo.o +COLOR: Set background color (red|green|blue) + default: red + actual: red -scons: *** Invalid value for option COLOR: BLUE. Valid values are: ('red', 'green', 'blue') -File "/home/my/project/SConstruct", line 5, in <module> -% scons -Q COLOR=nAvY foo.o - -scons: *** Invalid value for option COLOR: nAvY. Valid values are: ('red', 'green', 'blue') -File "/home/my/project/SConstruct", line 5, in <module> +Use scons -H for help about command-line options. diff --git a/doc/generated/examples/commandline_EnumVariable_4.xml b/doc/generated/examples/commandline_EnumVariable_4.xml new file mode 100644 index 0000000..7c37f72 --- /dev/null +++ b/doc/generated/examples/commandline_EnumVariable_4.xml @@ -0,0 +1,13 @@ +% scons -Q COLOR=Red foo.o + +scons: *** Invalid value for option COLOR: Red. Valid values are: ('red', 'green', 'blue') +File "/home/my/project/SConstruct", line 6, in <module> +% scons -Q COLOR=BLUE foo.o + +scons: *** Invalid value for option COLOR: BLUE. Valid values are: ('red', 'green', 'blue') +File "/home/my/project/SConstruct", line 6, in <module> +% scons -Q COLOR=nAvY foo.o + +scons: *** Invalid value for option COLOR: nAvY. Valid values are: ('red', 'green', 'blue') +File "/home/my/project/SConstruct", line 6, in <module> + diff --git a/doc/man/scons.xml b/doc/man/scons.xml index c52a4b8..b1eea06 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -3952,12 +3952,12 @@ env = conf.Finish() Command-Line Construction Variables Often when building software, -some variables must be specified at build time. +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; +&SCons; +provides a Variables object to support overriding &consvars; on the command line: @@ -3965,37 +3965,38 @@ on the command line: scons VARIABLE=foo -The variable values can also be specified in an SConscript file. -To obtain the object for manipulating values, +The variable values can also be specified in an SConscript file. + +To obtain the object for manipulating values, call the &Variables; function: - Variables([files[, args]]) + Variables([files, [args]]) -If files is a file or +If files is a file or list of files, those are executed as Python scripts, and the values of (global) Python variables set in -those files are added as &consvars; in the -default &consenv;. +those files are added as &consvars; in the &DefEnv;. If no files are specified, or the -files +files argument is -None, -then no files will be read. Example file content: +None, +then no files will be read. The following example file +contents could be used to set an alternative C compiler: CC = 'my_cc' -The optional argument -args -is a dictionary of -values that will override anything read from the specified files; +If +args +is specified, it is a dictionary of +values that will override anything read from +files. it is primarily intended to be passed the -ARGUMENTS -dictionary that holds variables +&ARGUMENTS; dictionary that holds variables specified on the command line. Example: @@ -4013,93 +4014,97 @@ vars = Variables(None, {FOO:'expansion', BAR:7}) - Add(key, [help, default, validator, converter]) + vars.Add(key, [help, default, validator, converter]) -This adds a customizable &consvar; to the Variables object. -key +Add a customizable &consvar; to the Variables object. +key is the name of the variable. -help +help is the help text for the variable. -default +default is the default value of the variable; if the default value is -None +None and there is no explicit value specified, -the &consvar; will -not +the &consvar; will not be added to the &consenv;. -validator -is called to validate the value of the variable, and should take three -arguments: key, value, and environment. +If set, validator +is called to validate the value of the variable. +A function supplied as a validator shall accept +arguments: key, +value, and env. The recommended way to handle an invalid value is to raise an exception (see example below). -converter +If set, converter is called to convert the value before putting it in the environment, and should take either a value, or the value and environment, as parameters. -The -converter -must return a value, +The converter function must return a value, which will be converted into a string before being validated by the -validator +validator (if any) -and then added to the environment. +and then added to the &consenv;. Examples: vars.Add('CC', help='The C compiler') -def validate_color(key, val, env): +def valid_color(key, val, env): if not val in ['red', 'blue', 'yellow']: raise Exception("Invalid color value '%s'" % val) + vars.Add('COLOR', validator=valid_color) - vars.AddVariables(list) + vars.AddVariables(args) -A wrapper script that adds +A convenience method that adds multiple customizable &consvars; -to a Variables object. -list -is a list of tuple or list objects +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. +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 rest optional +but must be in the specified in order if used. + + opt.AddVariables( - ('debug', '', 0), - ('CC', 'The C compiler'), - ('VALIDATE', 'An option for testing validation', - 'notset', validator, None), - ) + ("debug", "", 0), + ("CC", "The C compiler"), + ("VALIDATE", "An option for testing validation", "notset", validator, None), +) - vars.Update(env, [args]) + vars.Update(env, [args]) -This updates a &consenv; -env -with the customized &consvars;. -Any specified variables that are -not +Update a &consenv; +env +with the customized &consvars; . +Any specified variables that are not configured for the Variables object will be saved and may be -retrieved with the -UnknownVariables() +retrieved using the +&UnknownVariables; method, below. Normally this method is not called directly, -but is called indirectly by passing the Variables object to -the Environment() function: +but rather invoked indirectly by passing the Variables object to +the &f-link-Environment; function: env = Environment(variables=vars) @@ -4109,9 +4114,9 @@ env = Environment(variables=vars) - vars.UnknownVariables() + vars.UnknownVariables() -Returns a dictionary containing any +Return a dictionary containing any variables that were specified either in the files or the dictionary with which the Variables object was initialized, @@ -4128,10 +4133,10 @@ for key, value in vars.UnknownVariables(): - vars.Save(filename, env) + vars.Save(filename, env) -This saves the currently set variables into a script file named -filename +Save the currently set variables into a script file named +by filename that can be used on the next invocation to automatically load the current settings. This method combined with the Variables method can be used to support caching of variables between runs. @@ -4148,32 +4153,31 @@ vars.Save('variables.cache', env) - vars.GenerateHelpText(env, [sort]) + vars.GenerateHelpText(env, [sort]) -This generates help text documenting the customizable construction -variables suitable to passing in to the Help() function. -env +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 customizable variables. Calling with -an optional -sort -function -will cause the output to be sorted -by the specified argument. -The specific -sort -function -should take two arguments -and return --1, 0 or 1 -(like the standard Python -cmp -function). +of the customizable variables. If the (optional) +value of sort +is callable, 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 +Optionally a Boolean value of True +for sort will cause a standard +alphabetical sort to be performed. Help(vars.GenerateHelpText(env)) + +def cmp(a, b): + return (a > b) - (a < b) + Help(vars.GenerateHelpText(env, sort=cmp)) @@ -4181,20 +4185,18 @@ Help(vars.GenerateHelpText(env, sort=cmp)) - FormatVariableHelpText(env, opt, help, default, actual) + vars.FormatVariableHelpText(env, opt, help, default, actual) -This method returns a formatted string +Return a formatted string containing the printable help text for one option. It is normally not called directly, -but is called by the -GenerateHelpText() +but is called by the &GenerateHelpText; method to create the returned help text. It may be overridden with your own function that takes the arguments specified above and returns a string of help text formatted to your liking. -Note that -GenerateHelpText() +Note that &GenerateHelpText; will not put any blank lines or extra characters in between the entries, so you must add those characters to the returned @@ -4203,7 +4205,7 @@ string if you want the entries separated. def my_format(env, opt, help, default, actual): fmt = "\n%s: default=%s actual=%s (%s)\n" - return fmt % (opt, default. actual, help) + return fmt % (opt, default, actual, help) vars.FormatVariableHelpText = my_format @@ -4215,47 +4217,48 @@ vars.FormatVariableHelpText = my_format &scons; provides a number of functions that make it easy to set up -various types of Variables: +various types of Variables. +Each of these return a tuple ready to be passed to +the &Add; or &AddVariables; method: - BoolVariable(key, help, default) + BoolVariable(key, help, default) Return a tuple of arguments to set up a Boolean option. The option will use the specified name -key, +key, have a default value of -default, -and display the specified -help -text. +default, +and help +will form the descriptive part of the help text. The option will interpret the values -y, -yes, -t, -true, -1, -on +y, +yes, +t, +true, +1, +on and -all +all as true, and the values -n, -no, -f, -false, -0, -off +n, +no, +f, +false, +0, +off and -none +none as false. - EnumVariable(key, help, default, allowed_values, [map, ignorecase]) + EnumVariable(key, help, default, allowed_values, [map, ignorecase]) Return a tuple of arguments to set up an option @@ -4263,49 +4266,48 @@ whose value may be one of a specified list of legal enumerated values. The option will use the specified name -key, +key, have a default value of -default, -and display the specified -help -text. +default, +and help +will form the descriptive part of the help text. The option will only support those values in the -allowed_values +allowed_values list. The optional -map +map argument is a dictionary that can be used to convert input values into specific legal values in the -allowed_values +allowed_values list. If the value of -ignore_case +ignore_case is 0 (the default), then the values are case-sensitive. If the value of -ignore_case +ignore_case is 1, then values will be matched -case-insensitive. +case-insensitively. If the value of -ignore_case +ignore_case is 2, then values will be matched -case-insensitive, +case-insensitively, and all input values will be converted to lower case. - ListVariable(key, help, default, names, [,map]) + ListVariable(key, help, default, names, [map]) Return a tuple of arguments to set up an option @@ -4313,36 +4315,38 @@ whose value may be one or more of a specified list of legal enumerated values. The option will use the specified name -key, +key, have a default value of -default, -and display the specified -help -text. -The option will only support the values -all, -none, +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 +names list. More than one value may be specified, -with all values separated by commas. +separated by commas. The default may be a string of comma-separated default values, or a list of the default values. The optional -map +map argument is a dictionary that can be used to convert input values into specific legal values in the -names -list. +names +list. +(Note that the additional values accepted through +the use of a map are not +reflected in the generated help message). - PackageVariable(key, help, default) + PackageVariable(key, help, default) Return a tuple of arguments to set up an option @@ -4352,52 +4356,50 @@ enabled, disabled or given an explicit path name. The option will use the specified name -key, +key, have a default value of -default, -and display the specified -help -text. +default, +and help +will form the descriptive part of the help text. The option will support the values -yes, -true, -on, -enable +yes, +true, +on, +enable or -search, +search, in which case the specified -default +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 -no, -false, -off +no, +false, +off or -disable +disable to disable use of the specified option. - PathVariable(key, help, default, [validator]) + PathVariable(key, help, default, [validator]) Return a tuple of arguments to set up an option whose value is expected to be a path name. The option will use the specified name -key, +key, have a default value of -default, -and display the specified -help -text. +default, +and help +will form the descriptive part of the help text. An additional -validator +validator may be specified that will be called to verify that the specified path @@ -4407,38 +4409,40 @@ following ready-made validators: - PathVariable.PathExists + PathVariable.PathExists -Verify that the specified path exists (the default). +Verify that the specified path exists +(this the default behavior if no +validator is supplied). - PathVariable.PathIsFile + PathVariable.PathIsFile -Verify that the specified path is an existing file. +Verify that the specified path exists and is a regular file. - PathVariable.PathIsDir + PathVariable.PathIsDir -Verify that the specified path is an existing directory. +Verify that the specified path exists and is a directory. - PathVariable.PathIsDirCreate + PathVariable.PathIsDirCreate -Verify that the specified path is a directory -and will create the specified directory if the path does not exist. +Verify that the specified path exists and is a directory; +if it does not exist, create the directory. - PathVariable.PathAccept + PathVariable.PathAccept -Simply accept the specific path name argument without validation, +Accept the specific path name argument without validation, suitable for when you want your users to be able to specify a directory path that will be created as part of the build process, for example. @@ -4451,12 +4455,12 @@ You may supply your own validator function, which must accept three arguments -(key, +(key, the name of the variable to be set; -val, +val, the specified value being checked; and -env, +env, the &consenv;) and should raise an exception if the specified value is not acceptable. @@ -7220,7 +7224,7 @@ line or in the file custom.py. vars = Variables('custom.py') -vars.Add('CC', 'The C compiler.') +vars.Add('CC', help='The C compiler.') env = Environment(variables=vars) Help(vars.GenerateHelpText(env)) diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index d8f9fff..4033372 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -873,7 +873,7 @@ cppdefines = [] for key, value in ARGLIST: if key == 'define': cppdefines.append(value) -env = Environment(CPPDEFINES = cppdefines) +env = Environment(CPPDEFINES=cppdefines) env.Object('prog.c') @@ -943,8 +943,7 @@ prog.c a program for release, and that the value of this variable should be added to the command line - with the appropriate -D option - (or other command line option) + with the appropriate define to pass the value to the C compiler. Here's how you might do that by setting the appropriate value in a dictionary for the @@ -955,9 +954,8 @@ prog.c vars = Variables(None, ARGUMENTS) -vars.Add('RELEASE', 'Set to 1 to build for release', 0) -env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) +vars.Add('RELEASE', default=0) +env = Environment(variables=vars, CPPDEFINES={'RELEASE_BUILD': '${RELEASE}'}) env.Program(['foo.c', 'bar.c']) @@ -975,11 +973,8 @@ bar.c (the vars = Variables(None, ARGUMENTS) call). It then uses the object's &Add; method to indicate that the &RELEASE; - variable can be set on the command line, - and that its default value will be 0 - (the third argument to the &Add; method). - The second argument is a line of help text; - we'll learn how to use it in the next section. + variable can be set on the command line, and that + if not set the default value will be 0. @@ -1003,18 +998,19 @@ bar.c - NOTE: Before &SCons; release 0.98.1, these build variables - were known as "command-line build options." - The class was actually named the &Options; class, - and in the sections below, - the various functions were named + Historical note: In old &SCons; (prior to 1.0), + these build variables were known as "command-line build options." + The class was named the &Options; class, + and the predefined functions to construct options were named &BoolOption;, &EnumOption;, &ListOption;, - &PathOption;, &PackageOption; and &AddOptions;. - These older names still work, - and you may encounter them in older - &SConscript; files, - but they have been officially deprecated - as of &SCons; version 2.0. + &PathOption;, &PackageOption; and &AddOptions; (contrast + with the current names in "Pre-Defined Build Variable Functions" + below. 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 + of Variable" for Option + will let the concepts transfer to current usage models. @@ -1032,12 +1028,17 @@ bar.c when the user runs scons -h. You could write this text by hand, but &SCons; provides an easier way. - &Variables; objects support a + Variables objects support a &GenerateHelpText; method that will, as its name suggests, generate text that describes the various variables that - have been added to it. + have been added to it. The default text includes + the help string itself plus other information + such as allowed values. + (The generated text can also be customized by + replacing the FormatVariableHelpText + method). You then pass the output from this method to the &Help; function: @@ -1046,8 +1047,8 @@ bar.c vars = Variables(None, ARGUMENTS) -vars.Add('RELEASE', 'Set to 1 to build for release', 0) -env = Environment(variables = vars) +vars.Add('RELEASE', help='Set to 1 to build for release', default=0) +env = Environment(variables=vars) Help(vars.GenerateHelpText(env)) @@ -1093,9 +1094,8 @@ Help(vars.GenerateHelpText(env)) vars = Variables('custom.py') -vars.Add('RELEASE', 'Set to 1 to build for release', 0) -env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) +vars.Add('RELEASE', help='Set to 1 to build for release', default=0) +env = Environment(variables=vars, CPPDEFINES={'RELEASE_BUILD': '${RELEASE}'}) env.Program(['foo.c', 'bar.c']) Help(vars.GenerateHelpText(env)) @@ -1139,12 +1139,11 @@ RELEASE = 1 - vars = Variables('custom.py') - vars.Add('RELEASE', 'Set to 1 to build for release', 0) - env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) - env.Program(['foo.c', 'bar.c']) - Help(vars.GenerateHelpText(env)) +vars = Variables('custom.py') +vars.Add('RELEASE', help='Set to 1 to build for release', default=0) +env = Environment(variables=vars, CPPDEFINES={'RELEASE_BUILD': '${RELEASE}'}) +env.Program(['foo.c', 'bar.c']) +Help(vars.GenerateHelpText(env)) foo.c @@ -1195,6 +1194,8 @@ vars = Variables('custom.py', ARGUMENTS) &SCons; provides a number of functions that provide ready-made behaviors for various types of command-line build variables. + These functions all return a tuple which is ready + to be passed to an &Add; call. @@ -1230,9 +1231,10 @@ vars = Variables('custom.py', ARGUMENTS) vars = Variables('custom.py') -vars.Add(BoolVariable('RELEASE', 'Set to build for release', 0)) -env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) +vars.Add(BoolVariable('RELEASE', + help='Set to build for release', + default=0)) +env = Environment(variables=vars, CPPDEFINES={'RELEASE_BUILD': '${RELEASE}'}) env.Program('foo.c') @@ -1334,11 +1336,13 @@ foo.c vars = Variables('custom.py') -vars.Add(EnumVariable('COLOR', 'Set background color', 'red', - allowed_values=('red', 'green', 'blue'))) -env = Environment(variables = vars, - CPPDEFINES={'COLOR' : '"${COLOR}"'}) +vars.Add(EnumVariable('COLOR', + help='Set background color', + default='red', + allowed_values=('red', 'green', 'blue'))) +env = Environment(variables=vars, CPPDEFINES={'COLOR': '"${COLOR}"'}) env.Program('foo.c') +Help(vars.GenerateHelpText(env)) foo.c @@ -1373,6 +1377,20 @@ foo.c + This example can also serve to further illustrate help + generation: the help message here picks up not only the + help text, but augments it with + information gathered from allowed_values + and default: + + + + + scons -Q -h + + + + The &EnumVariable; function also supports a way to map alternate names to allowed values. Suppose, for example, @@ -1388,11 +1406,12 @@ foo.c vars = Variables('custom.py') -vars.Add(EnumVariable('COLOR', 'Set background color', 'red', - allowed_values=('red', 'green', 'blue'), - map={'navy':'blue'})) -env = Environment(variables = vars, - CPPDEFINES={'COLOR' : '"${COLOR}"'}) +vars.Add(EnumVariable('COLOR', + help='Set background color', + default='red', + allowed_values=('red', 'green', 'blue'), + map={'navy':'blue'})) +env = Environment(variables=vars, CPPDEFINES={'COLOR': '"${COLOR}"'}) env.Program('foo.c') @@ -1424,7 +1443,7 @@ foo.c - + scons -Q COLOR=Red foo.o scons -Q COLOR=BLUE foo.o scons -Q COLOR=nAvY foo.o @@ -1443,12 +1462,13 @@ foo.c vars = Variables('custom.py') -vars.Add(EnumVariable('COLOR', 'Set background color', 'red', - allowed_values=('red', 'green', 'blue'), - map={'navy':'blue'}, - ignorecase=1)) -env = Environment(variables = vars, - CPPDEFINES={'COLOR' : '"${COLOR}"'}) +vars.Add(EnumVariable('COLOR', + help='Set background color', + default='red', + allowed_values=('red', 'green', 'blue'), + map={'navy':'blue'}, + ignorecase=1)) +env = Environment(variables=vars, CPPDEFINES={'COLOR':'"${COLOR}"'}) env.Program('foo.c') @@ -1483,12 +1503,13 @@ foo.c vars = Variables('custom.py') -vars.Add(EnumVariable('COLOR', 'Set background color', 'red', - allowed_values=('red', 'green', 'blue'), - map={'navy':'blue'}, - ignorecase=2)) -env = Environment(variables = vars, - CPPDEFINES={'COLOR' : '"${COLOR}"'}) +vars.Add(EnumVariable('COLOR', + help='Set background color', + default='red', + allowed_values=('red', 'green', 'blue'), + map={'navy':'blue'}, + ignorecase=2)) +env = Environment(variables=vars, CPPDEFINES={'COLOR': '"${COLOR}"'}) env.Program('foo.c') @@ -1532,10 +1553,11 @@ foo.c vars = Variables('custom.py') -vars.Add(ListVariable('COLORS', 'List of colors', 0, - ['red', 'green', 'blue'])) -env = Environment(variables = vars, - CPPDEFINES={'COLORS' : '"${COLORS}"'}) +vars.Add(ListVariable('COLORS', + help='List of colors', + default=0, + names=['red', 'green', 'blue'])) +env = Environment(variables=vars, CPPDEFINES={'COLORS': '"${COLORS}"'}) env.Program('foo.c') @@ -1604,10 +1626,9 @@ foo.c vars = Variables('custom.py') vars.Add(PathVariable('CONFIG', - 'Path to configuration file', - '__ROOT__/etc/my_config')) -env = Environment(variables = vars, - CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'}) + help='Path to configuration file', + default='__ROOT__/etc/my_config')) +env = Environment(variables=vars, CPPDEFINES={'CONFIG_FILE': '"$CONFIG"'}) env.Program('foo.c') @@ -1652,7 +1673,7 @@ foo.c that you can use to change this behavior. If you want to ensure that any specified paths are, in fact, files and not directories, - use the &PathVariable_PathIsFile; method: + use the &PathVariable_PathIsFile; method as the validation function: @@ -1660,11 +1681,10 @@ foo.c vars = Variables('custom.py') vars.Add(PathVariable('CONFIG', - 'Path to configuration file', - '__ROOT__/etc/my_config', - PathVariable.PathIsFile)) -env = Environment(variables = vars, - CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'}) + help='Path to configuration file', + default='__ROOT__/etc/my_config', + validator=PathVariable.PathIsFile)) +env = Environment(variables=vars, CPPDEFINES={'CONFIG_FILE': '"$CONFIG"'}) env.Program('foo.c') @@ -1679,7 +1699,7 @@ foo.c Conversely, to ensure that any specified paths are directories and not files, - use the &PathVariable_PathIsDir; method: + use the &PathVariable_PathIsDir; method as the validation function: @@ -1687,11 +1707,10 @@ foo.c vars = Variables('custom.py') vars.Add(PathVariable('DBDIR', - 'Path to database directory', - '__ROOT__/var/my_dbdir', - PathVariable.PathIsDir)) -env = Environment(variables = vars, - CPPDEFINES={'DBDIR' : '"$DBDIR"'}) + help='Path to database directory', + default='__ROOT__/var/my_dbdir', + validator=PathVariable.PathIsDir)) +env = Environment(variables=vars, CPPDEFINES={'DBDIR': '"$DBDIR"'}) env.Program('foo.c') @@ -1708,7 +1727,7 @@ foo.c are directories, and you would like the directory created if it doesn't already exist, - use the &PathVariable_PathIsDirCreate; method: + use the &PathVariable_PathIsDirCreate; method as the validation function: @@ -1716,11 +1735,10 @@ foo.c vars = Variables('custom.py') vars.Add(PathVariable('DBDIR', - 'Path to database directory', - '__ROOT__/var/my_dbdir', - PathVariable.PathIsDirCreate)) -env = Environment(variables = vars, - CPPDEFINES={'DBDIR' : '"$DBDIR"'}) + help='Path to database directory', + default='__ROOT__/var/my_dbdir', + validator=PathVariable.PathIsDirCreate)) +env = Environment(variables=vars, CPPDEFINES={'DBDIR': '"$DBDIR"'}) env.Program('foo.c') @@ -1744,11 +1762,10 @@ foo.c vars = Variables('custom.py') vars.Add(PathVariable('OUTPUT', - 'Path to output file or directory', - None, - PathVariable.PathAccept)) -env = Environment(variables = vars, - CPPDEFINES={'OUTPUT' : '"$OUTPUT"'}) + help='Path to output file or directory', + default=None, + validator=PathVariable.PathAccept)) +env = Environment(variables=vars, CPPDEFINES={'OUTPUT': '"$OUTPUT"'}) env.Program('foo.c') @@ -1777,13 +1794,12 @@ foo.c -vars = Variables('custom.py') -vars.Add(PackageVariable('PACKAGE', - 'Location package', - '__ROOT__/opt/location')) -env = Environment(variables = vars, - CPPDEFINES={'PACKAGE' : '"$PACKAGE"'}) -env.Program('foo.c') +vars = Variables("custom.py") +vars.Add(PackageVariable("PACKAGE", + help="Location package", + default="__ROOT__/opt/location")) +env = Environment(variables=vars, CPPDEFINES={"PACKAGE": '"$PACKAGE"'}) +env.Program("foo.c") foo.c @@ -1798,8 +1814,8 @@ foo.c - When the &SConscript; file uses the &PackageVariable; funciton, - user can now still use the default + When the &SConscript; file uses the &PackageVariable; function, + the user can still use the default or supply an overriding path name, but can now explicitly set the specified variable to a value @@ -1828,16 +1844,17 @@ foo.c Lastly, &SCons; provides a way to add multiple build variables to a &Variables; object at once. Instead of having to call the &Add; method - multiple times, - you can call the &AddVariables; - method with a list of build variables - to be added to the object. + multiple times, you can call the &AddVariables; + method with the build variables to be added to the object. Each build variable is specified as either a tuple of arguments, - just like you'd pass to the &Add; method itself, or as a call to one of the pre-defined - functions for pre-packaged command-line build variables. - in any order: + functions for pre-packaged command-line build variables, + which returns such a tuple. Note that an individual tuple + cannot take keyword arguments in the way that a call to + &Add; or one of the build variable functions can. + The order of variables given to &AddVariables; does not + matter. @@ -1847,18 +1864,25 @@ vars = Variables() vars.AddVariables( ('RELEASE', 'Set to 1 to build for release', 0), ('CONFIG', 'Configuration file', '/etc/my_config'), - BoolVariable('warnings', 'compilation with -Wall and similiar', 1), - EnumVariable('debug', 'debug output and symbols', 'no', - allowed_values=('yes', 'no', 'full'), - map={}, ignorecase=0), # case sensitive + BoolVariable('warnings', + help='compilation with -Wall and similiar', + default=1), + EnumVariable('debug', + help='debug output and symbols', + default='no', + allowed_values=('yes', 'no', 'full'), + map={}, + ignorecase=0), ListVariable('shared', - 'libraries to build as shared libraries', - 'all', - names = list_of_libs), + help='libraries to build as shared libraries', + default='all', + names = list_of_libs), PackageVariable('x11', - 'use X11 installed here (yes = search some places)', - 'yes'), - PathVariable('qtdir', 'where the root of Qt is installed', qtdir), + help='use X11 installed here (yes = search some places)', + default='yes'), + PathVariable('qtdir', + help='where the root of Qt is installed', + default=qtdir), ) @@ -1905,9 +1929,8 @@ vars.AddVariables( vars = Variables(None) -vars.Add('RELEASE', 'Set to 1 to build for release', 0) -env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) +vars.Add('RELEASE', help='Set to 1 to build for release', default=0) +env = Environment(variables=vars, CPPDEFINES={'RELEASE_BUILD': '${RELEASE}'}) unknown = vars.UnknownVariables() if unknown: print("Unknown variables: %s"%unknown.keys()) -- cgit v0.12 From d270eb25f5cca3224c89498c79b8a39f9a69241a Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 20 Apr 2020 09:02:59 -0600 Subject: [PR #3615] address some review comments on Variables [ci skip] Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 16 ++++++++-------- doc/user/command-line.xml | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index b1eea06..54065dc 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -3957,7 +3957,7 @@ 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 +provides a &Variables; object to support overriding &consvars; on the command line: @@ -4116,7 +4116,7 @@ env = Environment(variables=vars) vars.UnknownVariables() -Return a dictionary containing any +Returns a dictionary containing any variables that were specified either in the files or the dictionary with which the Variables object was initialized, @@ -4187,7 +4187,7 @@ Help(vars.GenerateHelpText(env, sort=cmp)) vars.FormatVariableHelpText(env, opt, help, default, actual) -Return a formatted string +Returns a formatted string containing the printable help text for one option. It is normally not called directly, @@ -4225,7 +4225,7 @@ the &Add; or &AddVariables; method: BoolVariable(key, help, default) -Return a tuple of arguments +Returns a tuple of arguments to set up a Boolean option. The option will use the specified name @@ -4260,7 +4260,7 @@ as false. EnumVariable(key, help, default, allowed_values, [map, ignorecase]) -Return a tuple of arguments +Returns a tuple of arguments to set up an option whose value may be one of a specified list of legal enumerated values. @@ -4309,7 +4309,7 @@ converted to lower case. ListVariable(key, help, default, names, [map]) -Return a tuple of arguments +Returns a tuple of arguments to set up an option whose value may be one or more of a specified list of legal enumerated values. @@ -4348,7 +4348,7 @@ reflected in the generated help message). PackageVariable(key, help, default) -Return a tuple of arguments +Returns a tuple of arguments to set up an option whose value is a path name of a package that may be @@ -4388,7 +4388,7 @@ to disable use of the specified option. PathVariable(key, help, default, [validator]) -Return a tuple of arguments +Returns a tuple of arguments to set up an option whose value is expected to be a path name. The option will use diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index 4033372..903fe56 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -998,7 +998,7 @@ bar.c - Historical note: In old &SCons; (prior to 1.0), + Historical note: In old &SCons; (prior to 0.98.1), these build variables were known as "command-line build options." The class was named the &Options; class, and the predefined functions to construct options were named -- cgit v0.12