From 365ca4a52fcde6ccfa0b58a1f3003df2f722ebdc Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 14 Feb 2024 09:17:38 -0700 Subject: Minor manpage updates. [skip appveyor] Consistent use of &Python; entity. Add something on Configure + variantdir. Also some docstrings. Signed-off-by: Mats Wichmann --- CHANGES.txt | 3 + SCons/Defaults.xml | 16 ++++ SCons/Environment.py | 11 +++ SCons/Environment.xml | 9 +- doc/man/scons.xml | 191 ++++++++++++++++++++++++----------------- doc/user/builders-built-in.xml | 14 +-- 6 files changed, 154 insertions(+), 90 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index a07fcbe..e78df95 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -99,6 +99,9 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER describe the Microsoft C++ compiler. Update the version table slightly. Amplified the usage of MSVC_VERSION. - Improve SharedLibrary docs a bit. + - More consistent use of &Python; in the manpage. A few links added. + A warning about overwriting env['ENV'] and one about Configure + checks possibly not running in in no-exec mode also added. RELEASE 4.6.0 - Sun, 19 Nov 2023 17:22:20 -0700 diff --git a/SCons/Defaults.xml b/SCons/Defaults.xml index f1ba386..c7b8643 100644 --- a/SCons/Defaults.xml +++ b/SCons/Defaults.xml @@ -57,6 +57,14 @@ containing the SConstruct file. + +If variant directories are in use, +and the configure check results should not be +shared between variants, +you can set &cv-CONFIGUREDIR; +and &cv-link-CONFIGURELOG; so they are +unique per variant directory. + @@ -71,6 +79,14 @@ containing the SConstruct file. + +If variant directories are in use, +and the configure check results should not be +shared between variants, +you can set &cv-link-CONFIGUREDIR; +and &cv-CONFIGURELOG; so they are +unique per variant directory. + diff --git a/SCons/Environment.py b/SCons/Environment.py index 121a47a..f5e1921 100644 --- a/SCons/Environment.py +++ b/SCons/Environment.py @@ -633,6 +633,17 @@ class SubstitutionEnvironment: return self._dict.setdefault(key, default) def arg2nodes(self, args, node_factory=_null, lookup_list=_null, **kw): + """Converts *args* to a list of nodes. + + Arguments: + args - filename strings or nodes to convert; nodes are just + added to the list without further processing. + node_factory - optional factory to create the nodes; if not + specified, will use this environment's ``fs.File method. + lookup_list - optional list of lookup functions to call to + attempt to find the file referenced by each *args*. + kw - keyword arguments that represent additional nodes to add. + """ if node_factory is _null: node_factory = self.fs.File if lookup_list is _null: diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 0014426..39a6529 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -2999,9 +2999,9 @@ method. Specifies an order-only relationship -between the specified target file(s) -and the specified prerequisite file(s). -The prerequisite file(s) +between target +and prerequisite. +The prerequisites will be (re)built, if necessary, before the target file(s), @@ -3012,6 +3012,9 @@ the prerequisite file(s) change. target and prerequisite may each be a string or Node, or a list of strings or Nodes. +If there are multiple +target values, +the prerequisite(s) are added to each one. Returns a list of the affected target nodes. diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 1ef6186..998115e 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -171,18 +171,31 @@ directories through the definition of When invoked, &scons; looks for a file named &SConstruct; +(other names are also accepted, +see ) in the current directory and reads the -build configuration from that file -(other names are allowed, -see -and the option -for more information). -The build may be structured in a hierarchical manner: -the &SConstruct; -file may specify subsidiary +build configuration from that file; +that directory is considered the project top directory. +Certain command-line options specify alternate +places to look for the &SConstruct; +(see +, +, + and +), +which will set the project top directory to the place found. +A path to the main build configuration file can also be +specified with the + option, +which leaves the current directory as the project top directory. + + +The build configuration may be split into multiple files: +the &SConstruct; file may specify additional configuration files by calling the &f-link-SConscript; function, -and these may, in turn, do the same. +and any file thus invoked may +include further files in the same way. By convention, these subsidiary files are named &SConscript;, @@ -206,10 +219,9 @@ SConscript files when needed. &scons; looks for a directory named site_scons -in various system directories and in the directory containing the -&SConstruct; file -or, if specified, the -directory from the +in various system directories and in the +project top directory, or, if specified, +the directory from the option instead, and prepends the ones it finds to the &Python; module search path (sys.path), @@ -339,16 +351,25 @@ env = Environment(ENV=os.environ.copy()) This comes at the expense of making your build dependent on the user's environment being set correctly, -but it may be more convenient for many configurations. +but it may be more convenient for some configurations. It should not cause problems if done in a build setup which tightly controls how the environment is set up before invoking &scons;, as in many continuous integration setups. + +The above fragments are intended to illustrate a concept. +It is normally not a good idea to wipe out the entire +default value of the execution environment +(env["ENV"]), +as it may carry important information for the +execution of build commands. + + &scons; is normally executed in a top-level directory containing an -&SConstruct; file. +&SConstruct; file (the project top directory). When &scons; is invoked, the command line (including the contents of the &SCONSFLAGS; @@ -530,9 +551,8 @@ should be built (on Windows systems): A subset of a hierarchical tree may be built by -remaining at the top-level directory (where the -&SConstruct; -file lives) and specifying the subdirectory as the target to +remaining at the project top directory +and specifying the subdirectory as the target to build: @@ -812,11 +832,6 @@ When multiple options are given, each subsequent non-absolute directory is interpreted relative to the preceding one. -This option is similar to using -, -but does not search for any of the -predefined &SConstruct; names -in the specified directory. See also options , @@ -1719,6 +1734,15 @@ that file is not available to scan for dependencies at all in an unbuilt tree, and may contain out of date information in a previously built tree. + +&SCons; cannot perform &f-link-Configure; checks in no-exec mode, +as they would make changes to the filesystem +(see &cv-link-CONFIGUREDIR; and &cv-link-CONFIGURELOG;). +It can use stored information from a previous build, +if it is not out of date, +so a "priming" build may make subsequent no-exec runs +more useful. + @@ -2082,7 +2106,7 @@ choices may be specified, separated by commas: &SConstruct;, &Sconstruct;, &sconstruct;, &SConstruct.py;, &Sconstruct.py; or &sconstruct.py; file is found, and uses that -as the top of the directory tree. +as the project top directory. If no targets are specified on the command line, only targets at or below the current directory will be built. @@ -2415,7 +2439,7 @@ though if necessary, also looks for alternative file names and &sconstruct.py; in that order. A different file name (which can include a pathname part) may be specified via the option. -Except for the SConstruct file, +Except for the &SConstruct; file, these files are not searched for automatically; you add additional configuration files to the build by calling the &f-link-SConscript; function. @@ -2832,8 +2856,7 @@ of the &SConscript; file currently being processed. path strings: if the string begins with the # character it is top-relative - it works like a relative path but the -search follows down from the directory containing the top-level -&SConstruct; rather than +search follows down from the project top directory rather than from the current directory. The # can optionally be followed by a pathname separator, which is ignored if found in that position. @@ -2999,7 +3022,7 @@ when using the chdir keyword argument--that is, the expanded file names will still be relative to -the top-level directory where the &SConstruct; was found, +the project top directory, and consequently incorrect relative to the chdir directory. If you use the chdir keyword argument, @@ -3309,9 +3332,8 @@ object. &scons; provides a number of other &consenv; methods and global functions to -manipulate the build configuration. - -Usually, a &consenv; method +manipulate the build configuration. +Usually, a &consenv; method and global function with the same name both exist for convenience. In the following list, the global function @@ -3335,12 +3357,15 @@ then both forms are listed. provide almost identical functionality, with a couple of exceptions. First, many of the &consenv; methods affect only that &consenv;, while the global function has a -global effect. Second, where appropriate, +global effect (or, alternatively, takes an additional +positional argument to specify the affected &consenv;). +Second, where appropriate, calling the functionality through a &consenv; will substitute &consvars; into -any supplied string arguments, while the global function doesn't have the -context of a &consenv; to pick variables from, -so it cannot perform the substitution. +any supplied string arguments, while the global function, +unless it takes a &consenv; parameter, +does not have the context of a &consenv; to pick variables from, +and thus cannot perform substitutions. For example: @@ -3362,12 +3387,18 @@ and add a target named foo to the list of default targets. For more on &consvar; expansion, -see the next section on -&consvars;. +see the +&Consvars; +section below. + -Global functions may be called from custom Python modules that you -import into an &SConscript; file by adding the following import -to the Python module: + +Global functions are automatically in scope inside +&SConscript; files. +If you have custom &Python; code that you import into an &SConscript; file, +such code will need to bring them into their own scope. +You can do that by adding the following import +to the &Python; module: from SCons.Script import * @@ -3488,7 +3519,7 @@ command line targets or &Default; calls are present. The elements of this list may be strings or -nodes, so you should run the list through the Python +nodes, so you should run the list through the &Python; str function to make sure any Node path names are converted to strings. @@ -3547,7 +3578,7 @@ function. If there are no command line targets, this list will have the same contents as &BUILD_TARGETS;. Since the elements of the list are nodes, -you need to call the Python +you need to call the &Python; str function on them to get the path name for each Node. @@ -3587,9 +3618,9 @@ default target before it's actually been added to the list. -These variables may be accessed from custom Python modules that you +These variables may be accessed from custom &Python; modules that you import into an &SConscript; file by adding the following -to the Python module: +to the &Python; module: from SCons.Script import * @@ -3620,10 +3651,12 @@ from SCons.Script import * &consvars; that are used by built-in or user-supplied build rules. &Consvar; naming must follow the same rules as -Python identifier naming: +&Python; identifier naming: the initial character must be an underscore or letter, followed by any number of underscores, letters, or digits. -A &consenv; is not a Python dictionary itself, +The convention is to use uppercase for all letters +for easier visual identification. +A &consenv; is not a &Python; dictionary itself, but it can be indexed like one to access a &consvar;: @@ -4379,7 +4412,7 @@ pass a dictionary to the &f-link-Configure; function as the custom_tests parameter. The dictionary maps the names of the checks to the custom check callables -(either a Python function or an instance of a class implementing a +(either a &Python; function or an instance of a class implementing a __call__ method). Each custom check will be called with a a CheckContext @@ -4566,8 +4599,8 @@ call the &Variables; 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 +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, or the @@ -4709,7 +4742,7 @@ The args are tuples (or lists) that contain the arguments for an individual call to the &Add; method. -Since tuples are not Python mappings, +Since tuples are not &Python; mappings, the arguments cannot use the keyword form, but rather are positional arguments as documented for Add: @@ -5205,10 +5238,8 @@ The following attributes provide information about a Node: node.path The build path -of the given -file or directory. -This path is relative to the top-level directory -(where the &SConstruct; file is found). +of the given file or directory. +This path is relative to the project top directory. The build path is the same as the source path if variant_dir is not being used. @@ -5225,7 +5256,8 @@ is not being used. node.relpath -The build path of the given file or directory relative to the root SConstruct file's directory. +The build path of the given file or directory relative to +the project top directory. @@ -5252,7 +5284,7 @@ Dir('.').path # Current dir's absolute path Dir('.').abspath -# Current dir's path relative to the root SConstruct file's directory +# Current dir's path relative to the project top directory Dir('.').relpath # Next line is always '.', because it is the top dir's path relative to itself. @@ -5512,7 +5544,7 @@ a dictionary mapping source file name suffixes to any combination of command line strings (if the builder should accept multiple source file extensions), -a Python function, +a &Python; function, an Action object (see Action Objects) or a list of any of the above. @@ -5999,8 +6031,7 @@ and when using the chdir keyword argument--that is, the expanded file names -will still be relative to -the top-level directory containing the &SConstruct; file, +will still be relative to the project top directory, and consequently incorrect relative to the chdir directory. Builders created using chdir keyword argument, @@ -6021,7 +6052,7 @@ env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in') -Python only keeps one current directory +&Python; only keeps one current directory location even if there are multiple threads. This means that use of the chdir @@ -6166,7 +6197,7 @@ arguments may be lists of Node objects if there is more than one target file or source file. The actual target and source file name(s) may be retrieved from their Node objects -via the built-in Python str function: +via the built-in &Python; str function: target_file_name = str(target) @@ -6303,7 +6334,7 @@ This is necessary whenever you want a target to be rebuilt when a specific &consvar; changes. This is not often needed for a string action, as the expanded variables will normally be part of the command line, -but may be needed if a Python function action uses +but may be needed if a &Python; function action uses the value of a &consvar; when generating the command line. @@ -6353,7 +6384,7 @@ when using the chdir parameter - that is, the expanded file names will still be relative to -the top-level directory containing the &SConstruct; file, +the project top directory, and consequently incorrect relative to the chdir directory. Builders created using chdir keyword argument, @@ -6465,7 +6496,7 @@ which will cause to batch-build targets with matching values of that &consvar;, or perhaps return the -Python id() +&Python; id() of the entire &consenv;, in which case &scons; @@ -6594,7 +6625,7 @@ env.Command( The behavior of Chmod is limited on Windows and on WebAssembly platforms, -see the notes in the Python documentation for +see the notes in the &Python; documentation for os.chmod, which is the underlying function. @@ -6638,7 +6669,7 @@ will be removed. If the must_exist flag is set to a true value, -then a Python error will be raised +then a &Python; error will be raised if the specified entry does not exist; the default is false, that is, the Action will silently do nothing @@ -7059,7 +7090,7 @@ These are known as special attributes. filebase - Like file but minus its suffix. suffix - Just the file suffix. abspath - The absolute path name of the file. - relpath - The path name of the file relative to the root SConstruct file's directory. + relpath - The path name of the file relative to the project top directory. posix - The path with directories separated by forward slashes (/). @@ -7145,8 +7176,8 @@ Some modifiers can be combined, like If a substitutable expression using the notation ${expression} does not appear to match one of the other substitution patterns, -it is evaluated as a Python expression. -This uses Python's eval function, +it is evaluated as a &Python; expression. +This uses &Python;'s eval function, with the globals parameter set to the current environment's set of &consvars;, and the result substituted in. @@ -7202,19 +7233,19 @@ echo foo1 foo2 > foo.out -In point of fact, Python expression evaluation is +In point of fact, &Python; expression evaluation is how the special attributes are substituted: -they are simply attributes of the Python objects +they are simply attributes of the &Python; objects that represent &cv-TARGET;, &cv-SOURCES;, etc., which &SCons; passes to eval which returns the value. -Use of the Python eval function +Use of the &Python; eval function is considered to have security implications, since, depending on input sources, -arbitrary unchecked strings of code can be executed by the Python interpreter. +arbitrary unchecked strings of code can be executed by the &Python; interpreter. Although &SCons; makes use of it in a somewhat restricted context, you should be aware of this issue when using the ${python-expression-for-subst} form. @@ -7456,7 +7487,7 @@ the default is to return File nodes. node_factory -A Python function that will take a string +A &Python; function that will take a string or other object and turn it into the appropriate class of Node to be returned by this Scanner object, @@ -7552,8 +7583,8 @@ placing them in a site_tools subdirectory of a site directory, or in a custom location specified to &scons; by giving the toolpath keyword argument to &f-link-Environment;. -A tool module is a form of Python module, invoked internally -using the Python import mechanism, so a tool can consist either +A tool module is a form of &Python; module, invoked internally +using the &Python; import mechanism, so a tool can consist either of a single source file taking the name of the tool (e.g. mytool.py) or a directory taking the name of the tool (e.g. mytool/) @@ -7726,7 +7757,7 @@ env.SomeTool(targets, sources) SYSTEM-SPECIFIC BEHAVIOR &scons; and its configuration files are very portable, -due largely to its implementation in Python. +due largely to its implementation in &Python;. There are, however, a few portability issues waiting to trap the unwary. @@ -7968,7 +7999,7 @@ directory must be in your PATH environment variable or the ['ENV']['PATH'] &consvar; for &scons; to detect and use the MinGW tools. When running under the native Windows -Python; interpreter, &scons; will prefer the MinGW tools over the Cygwin +&Python; interpreter, &scons; will prefer the MinGW tools over the Cygwin tools, if they are both installed, regardless of the order of the bin directories in the PATH variable. If you have both MSVC and MinGW @@ -8236,7 +8267,7 @@ env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET') The &f-link-FindPathDirs; function used in the previous example returns a function -(actually a callable Python object) +(actually a callable &Python; object) that will return a list of directories specified in the MYPATH @@ -8559,7 +8590,7 @@ However the following variables are imported by SCONS_LIB_DIR Specifies the directory that contains the &scons; -Python module directory. Normally &scons; can deduce this, +&Python; module directory. Normally &scons; can deduce this, but in some circumstances, such as working with a source release, it may be necessary to specify (for example, diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml index 7c243ed..be3eed7 100644 --- a/doc/user/builders-built-in.xml +++ b/doc/user/builders-built-in.xml @@ -24,6 +24,8 @@ SPDX-License-Identifier: MIT xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd"> + + Built-In Builders @@ -135,8 +137,7 @@ Program(['hello.c', 'goodbye.c']) -env = Environment(LIBS = ['foo1', 'foo2'], - LIBPATH = ['/usr/dir1', 'dir2']) +env = Environment(LIBS=['foo1', 'foo2'], LIBPATH=['/usr/dir1', 'dir2']) env.Program(['hello.c', 'goodbye.c']) @@ -786,8 +787,7 @@ directory/file -env = Environment(TARFLAGS = '-c -z', - TARSUFFIX = '.tgz') +env = Environment(TARFLAGS='-c -z', TARSUFFIX='.tgz') env.Tar('out', 'directory') @@ -873,7 +873,7 @@ file2 env = Environment() -env.Java(target = 'classes', source = 'src') +env.Java(target='classes', source='src') @@ -902,8 +902,8 @@ XXX Java() screen env = Environment() -env.Java(target = 'classes', source = 'src') -env.Jar(target = '', source = 'classes') +env.Java(target='classes', source='src') +env.Jar(target='', source='classes') -- cgit v0.12 From 186de05d47278d6b171741b06929ebaefe55511b Mon Sep 17 00:00:00 2001 From: William Deegan Date: Sun, 10 Mar 2024 17:06:01 -0700 Subject: update changes/release.txt --- CHANGES.txt | 1 + RELEASE.txt | 8 +++++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/CHANGES.txt b/CHANGES.txt index 51866a8..5de7f48 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -91,6 +91,7 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER harder to decode non-UTF-8 text. SCons.Util.to_Text now exists to convert a byte stream, such as "raw" file data. Fixes #3569, #4462. The Pseudo manpage entry was updated to provide more clarity. + - Clarify how SCons finds the project top directory, and what that is used for. - The internal routine which implements the PyPackageDir function would fail with an exception if called with a module which is not found. It will now return None. Updated manpage entry and diff --git a/RELEASE.txt b/RELEASE.txt index b339c44..f517530 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -90,12 +90,18 @@ DOCUMENTATION ------------- - Fixed the Scanner examples in the User Guide to be runnable and added - some more explantion. Clarified discussion of the scanner function in + some more explanation. Clarified discussion of the scanner function in the Scanner Objects section of the manpage. - The manpage entry for Pseudo was clarified. - The manpage entry for SharedLibrary was clarified. - Update API docs for Warnings framework; add two warns to manpage enable/disable control. +- More consistent use of &Python; in the manpage. A few links added. + A warning about overwriting env['ENV'] and one about Configure + checks possibly not running in in no-exec mode also added. +- Clarify how SCons finds the project top directory, and what that is used for. + + DEVELOPMENT ----------- -- cgit v0.12