From 426885c8929b93944edcf8a0962331d36fbcdc73 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 21 Jan 2021 08:47:38 -0700 Subject: Some small doc fiddles [ci skip] * Use os.environ.copy() in examples - better not to get the Python proxy class that is os.environ, and instead a real dict. * Fix spelling on a python dict method: set_default -> setdefault * Update some wording on prepending in the user guide (where it still said "append to the beginning") * Change the rather oblique note in the recently modified section on Append of values to CPPDEFINES with something more explicit. * And, modify the sphinx config to get the version from SCons rather than hardcoding. Fixes #3867 Signed-off-by: Mats Wichmann --- SCons/Environment.xml | 6 +++--- doc/generated/variables.gen | 4 ++-- doc/man/scons.xml | 16 ++++++++-------- doc/sphinx/conf.py | 9 +++++---- doc/user/environments.xml | 21 +++++++++++---------- 5 files changed, 29 insertions(+), 27 deletions(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index a185815..cfa99db 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -87,7 +87,7 @@ Note that, by default, &scons; does not -propagate the environment in force when you +propagate the environment in effect when you execute &scons; to the commands used to build target files. @@ -108,7 +108,7 @@ you must do so explicitly: import os -env = Environment(ENV = os.environ) +env = Environment(ENV=os.environ.copy()) @@ -126,7 +126,7 @@ as the invoking shell (or other process): import os -env = Environment(ENV = {'PATH' : os.environ['PATH']}) +env = Environment(ENV={'PATH': os.environ['PATH']}) diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen index a16efae..1ac53fe 100644 --- a/doc/generated/variables.gen +++ b/doc/generated/variables.gen @@ -1636,7 +1636,7 @@ you must do so explicitly: import os -env = Environment(ENV = os.environ) +env = Environment(ENV=os.environ.copy()) @@ -1654,7 +1654,7 @@ as the invoking shell (or other process): import os -env = Environment(ENV = {'PATH' : os.environ['PATH']}) +env = Environment(ENV={'PATH': os.environ['PATH']}) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 8da4cc9..57bd209 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -269,7 +269,7 @@ complete external environment: import os -env = Environment(ENV=os.environ) +env = Environment(ENV=os.environ.copy()) This comes at the expense of making your build @@ -2574,7 +2574,7 @@ A nested tool name uses a dot to represent a directory separator # namespaced builder -env = Environment(ENV=os.environ, tools=['SubDir1.SubDir2.SomeTool']) +env = Environment(ENV=os.environ.copy(), tools=['SubDir1.SubDir2.SomeTool']) env.SomeTool(targets, sources) # Search Paths @@ -5060,7 +5060,7 @@ arguments must not both be used for the same Builder. prefix -The prefix that will be prepended to the target file name. +The prefix to prepend to the target file name. prefix may be: @@ -5098,13 +5098,13 @@ b = Builder("build_it < $SOURCE > $TARGET", suffix -The suffix that will be appended to the target file name. +The suffix to append to the target file name. This may be specified in the same manner as the prefix above. If the suffix is a string, then &scons; -will append a '.' to the beginning of the suffix if it's not already -there. The string returned by callable object (or obtained from the -dictionary) is untouched and must append its own '.' to the beginning +prepends a '.' to the suffix if it's not already there. +The string returned by the callable object (or obtained from the +dictionary) is untouched and you need to manually prepend a '.' if one is desired. @@ -6961,7 +6961,7 @@ such as Linux or UNIX, .F as a Fortran source file that is to be first run through -the standard C preprocessor, +the standard C preprocessor, while the lower-case version is not. This matches the convention of gfortran, which may also be followed by other Fortran compilers. diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index 27e18b7..517af50 100644 --- a/doc/sphinx/conf.py +++ b/doc/sphinx/conf.py @@ -76,11 +76,12 @@ author = 'SCons Project Team' # |version| and |release|, also used in various other places throughout the # built documents. # -# TODO: fill these in externally +from SCons import __version__ +# The full version, including alpha/beta/rc tags: +release = __version__ # The short X.Y version. -version = '4.1' -# The full version, including alpha/beta/rc tags. -release = '4.1.0' +major, minor, _ = __version__.split('.') +version = '.'.join([major, minor]) # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/doc/user/environments.xml b/doc/user/environments.xml index 2dae752..3c3eeae 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -1383,7 +1383,7 @@ int main() { } set to a value only if the construction environment does not already have that variable defined You can do this with the &f-link-env-SetDefault; method, - which behaves similarly to the set_default + which behaves similarly to the setdefault method of &Python; dictionary objects: @@ -1431,10 +1431,11 @@ int main() { } - &SCons; then generates the preprocessor define arguments from &CPPDEFINES; values with the correct - prefix/suffix. For example on Linux or POSIX, the following arguments would be generated: - -DMY_VALUE and - -DLAST + Note &cv-link-CPPDEFINES; is the preferred way to set preprocessor defines, + as &SCons; will generate the command line arguments using the correct + prefix/suffix for the platform, leaving the usage portable. + If you use &cv-link-CCFLAGS; and &cv-link-SHCCFLAGS;, + you need to include them in their final form, which is less portable. @@ -1487,7 +1488,7 @@ print("NEW_VARIABLE = %s"%env['NEW_VARIABLE']) - Some times it's useful to add a new value + Sometimes it's useful to add a new value only if the existing construction variable doesn't already contain the value. This can be done using the &f-link-env-AppendUnique; method: @@ -1510,11 +1511,11 @@ env.AppendUnique(CCFLAGS=['-g'])
- Appending to the Beginning of Values: the &Prepend; Method + Prepending to the Beginning of Values: the &Prepend; Method - You can append a value to the beginning of + You can prepend a value to the beginning of an existing construction variable using the &f-link-env-Prepend; method: @@ -1912,7 +1913,7 @@ env = Environment(ENV={'PATH': os.environ['PATH']}) import os -env = Environment(ENV=os.environ) +env = Environment(ENV=os.environ.copy()) @@ -1959,7 +1960,7 @@ env = Environment(ENV=os.environ) -env = Environment(ENV=os.environ) +env = Environment(ENV=os.environ.copy()) env.PrependENVPath('PATH', '/usr/local/bin') env.AppendENVPath('LIB', '/usr/local/lib') -- cgit v0.12