From e2531c48893b00c776fd83b1ae8a74e9593854db Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 21 Jul 2020 09:07:58 -0600 Subject: Update docs on argument passing to Environment, etc. Adds a new uguide Ch 7 section on using the parse_flags method (with Ex.) Moves the section on overrides in calls to Builders to Chap 7 - it was using concepts not introduced yet where it was placed. Signed-off-by: Mats Wichmann --- doc/generated/examples/environments_ex6_1.xml | 1 + doc/generated/examples/parse_flags_ex1_1.xml | 7 ++ doc/overview.rst | 2 +- doc/user/MANIFEST | 1 + doc/user/environments.xml | 151 ++++++++++++++++++++------ doc/user/less-simple.xml | 75 ++----------- doc/user/main.xml | 8 +- doc/user/mergeflags.xml | 25 +++-- doc/user/parse_flags_arg.xml | 75 +++++++++++++ doc/user/parseflags.xml | 17 +-- 10 files changed, 238 insertions(+), 124 deletions(-) create mode 100644 doc/generated/examples/parse_flags_ex1_1.xml create mode 100644 doc/user/parse_flags_arg.xml diff --git a/doc/generated/examples/environments_ex6_1.xml b/doc/generated/examples/environments_ex6_1.xml index 03a5e7c..70fbb03 100644 --- a/doc/generated/examples/environments_ex6_1.xml +++ b/doc/generated/examples/environments_ex6_1.xml @@ -1,4 +1,5 @@ % scons -Q CC is: cc +LATEX is: None scons: `.' is up to date. diff --git a/doc/generated/examples/parse_flags_ex1_1.xml b/doc/generated/examples/parse_flags_ex1_1.xml new file mode 100644 index 0000000..1cead7d --- /dev/null +++ b/doc/generated/examples/parse_flags_ex1_1.xml @@ -0,0 +1,7 @@ +% scons -Q +CPPPATH: ['/opt/include'] +LIBPATH: ['/opt/lib'] +LIBS: ['foo'] +cc -o f1.o -c -I/opt/include f1.c +cc -o f1 f1.o -L/opt/lib -lfoo + diff --git a/doc/overview.rst b/doc/overview.rst index aed27af..9a2558a 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -125,7 +125,7 @@ method form, or both, exist. If all four exist you will get: *f-link-foobar* which is a link to the description of the global Function -*f-env-link-foobar* +*f-link-env-foobar* which is a link to the description of the environment method diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST index 10b79f6..d7237df 100644 --- a/doc/user/MANIFEST +++ b/doc/user/MANIFEST @@ -36,6 +36,7 @@ nodes.xml output.xml parseconfig.xml parseflags.xml +parse_flags_arg.xml preface.xml python.xml repositories.xml diff --git a/doc/user/environments.xml b/doc/user/environments.xml index 0a5722b..77c6972 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -367,11 +367,11 @@ environment, of directory names, suffixes, etc. - The external environment + The External Environment is the set of variables in the user's environment - at the time the user runs &SCons;. - These variables are available within the &SConscript; files - through the Python os.environ dictionary. + at the time the user runs &SCons;. These variables are not + automatically part of an &SCons; build + but are available to be examined if needed. See , below. @@ -384,7 +384,7 @@ environment, of directory names, suffixes, etc. - A &consenv; + A &ConsEnv; is a distinct object created within a &SConscript; file and which contains values that @@ -408,7 +408,7 @@ environment, of directory names, suffixes, etc. - An execution environment + An Execution Environment is the values that &SCons; sets when executing an external command (such as a compiler or linker) @@ -429,7 +429,7 @@ environment, of directory names, suffixes, etc. Unlike &Make;, &SCons; does not automatically copy or import values between different environments (with the exception of explicit clones of &consenvs;, - which inherit values from their parent). + which inherit the values from their parent). This is a deliberate design choice to make sure that builds are, by default, repeatable regardless of @@ -477,8 +477,8 @@ environment, of directory names, suffixes, etc. variable settings that the user has in force when executing &SCons; - are available through the normal Python - os.environ + are available in the Python + os.environ dictionary. This means that you must add an import os statement @@ -491,6 +491,8 @@ environment, of directory names, suffixes, etc. import os + +print("Shell is", os.environ['SHELL']) int main() { } @@ -500,7 +502,7 @@ int main() { } More usefully, you can use the - os.environ + os.environ dictionary in your &SConscript; files to initialize &consenvs; with values from the user's external environment. @@ -618,8 +620,9 @@ int main() { } - You can fetch individual &consvars; - using the normal syntax + You can fetch individual values, known as + Construction Variables, + using the same syntax used for accessing individual named items in a Python dictionary: @@ -628,14 +631,20 @@ int main() { } env = Environment() print("CC is: %s" % env['CC']) +print("LATEX is: %s" % env.get('LATEX', None)) - This example &SConstruct; file doesn't build anything, - but because it's actually a Python script, - it will print the value of &cv-link-CC; for us: + This example &SConstruct; file doesn't contain instructions + for building any targets, but because it's still a valid + &SConstruct; it will be evaulated and the Python + print calls will output the values + of &cv-link-CC; and &cv-link-LATEX; for us (using the + .get() method for fetching means + we get a default value back, rather than a failure, + if the variable is not set): @@ -650,7 +659,8 @@ print("CC is: %s" % env['CC']) attributes. If you want to have direct access to only the dictionary of &consvars; - you can fetch this using the &Dictionary; method: + you can fetch this using the &Dictionary; method + (although it's rarely necessary to use this method): @@ -1004,8 +1014,8 @@ env = DefaultEnvironment(tools=['gcc', 'gnulink'], -opt = Environment(CCFLAGS = '-O2') -dbg = Environment(CCFLAGS = '-g') +opt = Environment(CCFLAGS='-O2') +dbg = Environment(CCFLAGS='-g') opt.Program('foo', 'foo.c') @@ -1035,8 +1045,8 @@ int main() { } -opt = Environment(CCFLAGS = '-O2') -dbg = Environment(CCFLAGS = '-g') +opt = Environment(CCFLAGS='-O2') +dbg = Environment(CCFLAGS='-g') opt.Program('foo', 'foo.c') @@ -1133,7 +1143,7 @@ int main() { } Like the &Environment; call that creates a construction environment, - the &Clone; method takes &consvar; assignments, + the &Clone; method takes &consvar; assignment keyword arguments, which will override the values in the copied construction environment. For example, suppose we want to use &gcc; to create three versions of a program, @@ -1148,9 +1158,9 @@ int main() { } -env = Environment(CC = 'gcc') -opt = env.Clone(CCFLAGS = '-O2') -dbg = env.Clone(CCFLAGS = '-g') +env = Environment(CC='gcc') +opt = env.Clone(CCFLAGS='-O2') +dbg = env.Clone(CCFLAGS='-g') env.Program('foo', 'foo.c') @@ -1189,8 +1199,8 @@ int main() { } -env = Environment(CCFLAGS = '-DDEFINE1') -env.Replace(CCFLAGS = '-DDEFINE2') +env = Environment(CCFLAGS='-DDEFINE1') +env.Replace(CCFLAGS='-DDEFINE2') env.Program('foo.c') @@ -1222,8 +1232,8 @@ int main() { } env = Environment() -env.Replace(NEW_VARIABLE = 'xyzzy') -print("NEW_VARIABLE = %s"%env['NEW_VARIABLE']) +env.Replace(NEW_VARIABLE='xyzzy') +print("NEW_VARIABLE = %s" % env['NEW_VARIABLE']) @@ -1257,12 +1267,12 @@ print("NEW_VARIABLE = %s"%env['NEW_VARIABLE']) -env = Environment(CCFLAGS = '-DDEFINE1') -print("CCFLAGS = %s"%env['CCFLAGS']) +env = Environment(CCFLAGS='-DDEFINE1') +print("CCFLAGS = %s" % env['CCFLAGS']) env.Program('foo.c') -env.Replace(CCFLAGS = '-DDEFINE2') -print("CCFLAGS = %s"%env['CCFLAGS']) +env.Replace(CCFLAGS='-DDEFINE2') +print("CCFLAGS = %s" % env['CCFLAGS']) env.Program('bar.c') @@ -1320,7 +1330,7 @@ int main() { } -env.SetDefault(SPECIAL_FLAG = '-extra-option') +env.SetDefault(SPECIAL_FLAG='-extra-option') @@ -1538,6 +1548,79 @@ env.PrependUnique(CCFLAGS=['-g']) + + +
+ Overriding Construction Variable Settings + + + + Rather than creating a cloned environmant for specific tasks, + you can override or add construction variables + when calling a builder method by passing them as keyword arguments. + The values of these overridden or added variables will only be in + effect when building that target, and will not affect other parts + of the build. + For example, if you want to add additional libraries for just one program: + + + + +env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) + + + + + or generate a shared library with a non-standard suffix: + + + + +env.SharedLibrary( + target='word', + source='word.cpp', + SHLIBSUFFIX='.ocx', + LIBSUFFIXES=['.ocx'], +) + + + + + When overriding this way, the Python-style keyword arguments + mean "set to this value". If you want your override to augment + an existing value, you have to take some extra steps. XXX + + + + + + It is also possible to use the parse_flags + keyword argument in an override to merge command-line + style arguments into the appropriate construction + variables. This works like the &f-link-env-MergeFlags; method, + which will be described later. + + + + + + This example adds 'include' to &cv-link-CPPPATH;, + 'EBUG' to &cv-link-CPPDEFINES;, and 'm' to &cv-link-LIBS;: + + + + +env = Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm') + + + + + Using temporary overrides this way is lighter weight than making + a full construction environment, so it can help performance in + large projects which have lots of special case values to set. + + +
@@ -1737,7 +1820,7 @@ env = Environment(ENV = os.environ) One of the most common requirements for manipulating a variable in the execution environment is to add one or more custom directories to a search - like the $PATH variable on Linux or POSIX systems, + like the PATH variable on Linux or POSIX systems, or the %PATH% variable on Windows, so that a locally-installed compiler or other utility can be found when &SCons; tries to execute it to update a target. diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml index 10f0c1a..394a39f 100644 --- a/doc/user/less-simple.xml +++ b/doc/user/less-simple.xml @@ -463,30 +463,30 @@ Program('program', src_files) &SCons; also allows you to identify the output file and input source files using Python keyword arguments. - The output file is known as the - target, - and the source file(s) are known (logically enough) as the - source. + The output file keyword is + target, + and the source file(s) keyword is (logically enough) + source. The Python syntax for this is: src_files = Split('main.c file1.c file2.c') -Program(target = 'program', source = src_files) +Program(target='program', source=src_files) Because the keywords explicitly identify - what each argument is, - you can actually reverse the order if you prefer: + what each argument is, the order does + not matter and you can reverse it if you prefer: src_files = Split('main.c file1.c file2.c') -Program(source = src_files, target = 'program') +Program(source=src_files, target='program') @@ -646,63 +646,4 @@ Program('bar', bar_files) -
- Overriding construction variables when calling a Builder - - - - It is possible to override or add construction variables - when calling a builder method by passing additional keyword arguments. - These overridden or added variables will only be in effect when - building the target, so they will not affect other parts of the build. - For example, if you want to add additional libraries for just one program: - - - - -env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) - - - - - or generate a shared library with a non-standard suffix: - - - - -env.SharedLibrary('word', 'word.cpp', - SHLIBSUFFIX='.ocx', - LIBSUFFIXES=['.ocx']) - - - - - It is also possible to use the parse_flags - keyword argument in an override to merge command-line - style arguments into the appropriate construction - variables (see &f-link-env-MergeFlags;). - - - - - - This example adds 'include' to &cv-link-CPPPATH;, - 'EBUG' to &cv-link-CPPDEFINES;, and 'm' to &cv-link-LIBS;. - - - - -env = Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm') - - - - - Within the call to the builder action the environment is not cloned, - instead an OverrideEnvironment() is created which is more - light weight than a whole Environment() - - - -
- diff --git a/doc/user/main.xml b/doc/user/main.xml index 49fef75..6f516f9 100644 --- a/doc/user/main.xml +++ b/doc/user/main.xml @@ -87,14 +87,14 @@ (brief) overview of *what* these functions do to decide if this chapter is where they should read in more detail. --> - This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; methods of a &consenv;. + This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; + methods of a &consenv;, as well as the parse_flags + keyword argument to methods that construct environments. + - diff --git a/doc/user/mergeflags.xml b/doc/user/mergeflags.xml index 879a7b2..5a864b1 100644 --- a/doc/user/mergeflags.xml +++ b/doc/user/mergeflags.xml @@ -46,21 +46,26 @@ - &SCons; construction environments have a &MergeFlags; method - that merges a dictionary of values into the construction environment. + &SCons; &consenvs; have an &f-link-env-MergeFlags; method + that merges values from a passed-in argument into the &consenv; + If the argument is a dictionary, &MergeFlags; treats each value in the dictionary as a list of options such as one might pass to a command (such as a compiler or linker). &MergeFlags; will not duplicate an option if it already exists in the construction environment variable. + If the argument is a string, &MergeFlags; calls the + &f-link-env-ParseFlags; method to burst it out into a + dictionary first, then acts on the result. - &MergeFlags; tries to be intelligent about merging options. + &MergeFlags; tries to be intelligent about merging options, + knowing that different &consvars; may have different needs. When merging options to any variable - whose name ends in PATH, + whose name ends in PATH, &MergeFlags; keeps the leftmost occurrence of the option, because in typical lists of directory paths, the first occurrence "wins." @@ -74,8 +79,8 @@ env = Environment() -env.Append(CCFLAGS = '-option -O3 -O1') -flags = { 'CCFLAGS' : '-whatever -O3' } +env.Append(CCFLAGS='-option -O3 -O1') +flags = {'CCFLAGS': '-whatever -O3'} env.MergeFlags(flags) print(env['CCFLAGS']) @@ -101,8 +106,8 @@ print(env['CCFLAGS']) env = Environment() -env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include']) -flags = { 'CPPPATH' : ['/usr/opt/include', '/usr/local/include'] } +env.Append(CPPPATH=['/include', '/usr/local/include', '/usr/include']) +flags = {'CPPPATH': ['/usr/opt/include', '/usr/local/include']} env.MergeFlags(flags) print(env['CPPPATH']) @@ -135,8 +140,8 @@ print(env['CPPPATH']) env = Environment() -env.Append(CCFLAGS = '-option -O3 -O1') -env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include']) +env.Append(CCFLAGS='-option -O3 -O1') +env.Append(CPPPATH=['/include', '/usr/local/include', '/usr/include']) env.MergeFlags('-whatever -I/usr/opt/include -O3 -I/usr/local/include') print(env['CCFLAGS']) print(env['CPPPATH']) diff --git a/doc/user/parse_flags_arg.xml b/doc/user/parse_flags_arg.xml new file mode 100644 index 0000000..e7d6c42 --- /dev/null +++ b/doc/user/parse_flags_arg.xml @@ -0,0 +1,75 @@ + + + %scons; + + + %builders-mod; + + %functions-mod; + + %tools-mod; + + %variables-mod; +]> + +
+Merging Options the Environment: the <parameter>merge_flags</parameter> Parameter + + + + + + It is also possible to merge &consvar; values from arguments + given to the &f-link-Environment; call itself. + If the parse_flags keyword argument + is given, its value is distributed to &consvars; in the + new environment in the same way as + described for the &MergeFlags; method. + This also works when calling &f-link-env-Clone;. + + + + + +env = Environment(parse_flags="-I/opt/include -L/opt/lib -lfoo") +for k in ('CPPPATH', 'LIBPATH', 'LIBS'): + print("%s:" % k, env.get(k)) +env.Program("f1.c") + + +int main() { return 0; } + + + + + scons -Q + + +
diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml index 35c336e..1cd0bbf 100644 --- a/doc/user/parseflags.xml +++ b/doc/user/parseflags.xml @@ -46,7 +46,7 @@ - &SCons; has a bewildering array of construction variables + &SCons; has a bewildering array of &consvars; for different types of options when building programs. Sometimes you may not know exactly which variable should be used for a particular option. @@ -55,10 +55,10 @@ - &SCons; construction environments have a &ParseFlags; method + &SCons; &consenvs; have a &f-link-env-ParseFlags; method that takes a set of typical command-line options and distributes them into the appropriate construction variables. - Historically, it was created to support the &ParseConfig; method, + Historically, it was created to support the &f-link-env-ParseConfig; method, so it focuses on options used by the GNU Compiler Collection (GCC) for the C and C++ toolchains. @@ -68,7 +68,7 @@ &ParseFlags; returns a dictionary containing the options distributed into their respective construction variables. - Normally, this dictionary would be passed to &MergeFlags; + Normally, this dictionary would then be passed to &MergeFlags; to merge the options into a &consenv;, but the dictionary can be edited if desired to provide additional functionality. @@ -128,7 +128,7 @@ env.MergeFlags(d) env.Program("f1.c") - int main() { return 0; } +void main() { return 0; } @@ -154,7 +154,7 @@ env.MergeFlags(d) env.Program("f1.c") -int main() { return 0; } +void main() { return 0; } @@ -164,7 +164,8 @@ int main() { return 0; } - If a string begins with a "!" (an exclamation mark, often called a bang), + If a string begins with a an exclamation mark (!, + sometimes also called a bang), the string is passed to the shell for execution. The output of the command is then parsed: @@ -181,7 +182,7 @@ env.MergeFlags(d) env.Program("f1.c") -int main() { return 0; } +void main() { return 0; } -- cgit v0.12