diff options
Diffstat (limited to 'src/engine/SCons/Environment.xml')
| -rw-r--r-- | src/engine/SCons/Environment.xml | 468 |
1 files changed, 121 insertions, 347 deletions
diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml index 5baae24..344bc2e 100644 --- a/src/engine/SCons/Environment.xml +++ b/src/engine/SCons/Environment.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="UTF-8"?> +<?xml version="1.0"?> <!-- Copyright (c) 2001 - 2019 The SCons Foundation @@ -148,9 +148,9 @@ appending to this list, although the more flexible approach is to associate scanners with a specific Builder. -See the sections "Builder Objects" -and "Scanner Objects," -below, for more information. +See the manpage sections "Builder Objects" +and "Scanner Objects" +for more information. </para> </summary> </cvar> @@ -160,7 +160,8 @@ below, for more information. <para> A reserved variable name that may not be set or used in a construction environment. -(See "Variable Substitution," below.) +(See the manpage section "Variable Substitution" +for more information). </para> </summary> </cvar> @@ -170,7 +171,8 @@ that may not be set or used in a construction environment. <para> A reserved variable name that may not be set or used in a construction environment. -(See "Variable Substitution," below.) +(See the manpage section "Variable Substitution" +for more information). </para> </summary> </cvar> @@ -180,7 +182,8 @@ that may not be set or used in a construction environment. <para> A reserved variable name that may not be set or used in a construction environment. -(See "Variable Substitution," below.) +(See the manpage section "Variable Substitution" +for more information). </para> </summary> </cvar> @@ -190,7 +193,8 @@ that may not be set or used in a construction environment. <para> A reserved variable name that may not be set or used in a construction environment. -(See "Variable Substitution," below.) +(See the manpage section "Variable Substitution" +for more information). </para> </summary> </cvar> @@ -200,7 +204,8 @@ that may not be set or used in a construction environment. <para> A reserved variable name that may not be set or used in a construction environment. -(See "Variable Substitution," below.) +(See the manpage section "Variable Substitution" +for more information). </para> </summary> </cvar> @@ -210,7 +215,8 @@ that may not be set or used in a construction environment. <para> A reserved variable name that may not be set or used in a construction environment. -(See "Variable Substitution," below.) +(See the manpage section "Variable Substitution" +for more information). </para> </summary> </cvar> @@ -220,7 +226,8 @@ that may not be set or used in a construction environment. <para> A reserved variable name that may not be set or used in a construction environment. -(See "Variable Substitution," below.) +(See the manpage section "Variable Substitution" +for more information). </para> </summary> </cvar> @@ -230,7 +237,8 @@ that may not be set or used in a construction environment. <para> A reserved variable name that may not be set or used in a construction environment. -(See "Variable Substitution," below.) +(See the manpage section "Variable Substitution" +for more information). </para> </summary> </cvar> @@ -255,8 +263,8 @@ that are part of this construction environment. Creates an Action object for the specified <varname>action</varname>. -See the section "Action Objects," -below, for a complete explanation of the arguments and behavior. +See the manpage section "Action Objects" +for a complete explanation of the arguments and behavior. </para> <para> @@ -359,7 +367,8 @@ has been built. The specified action(s) may be an Action object, or anything that can be converted into an Action object -(see below). +See the manpage section "Action Objects" +for a complete explanation. </para> <para> @@ -386,7 +395,8 @@ is built. The specified action(s) may be an Action object, or anything that can be converted into an Action object -(see below). +See the manpage section "Action Objects" +for a complete explanation. </para> <para> @@ -512,7 +522,7 @@ Otherwise, the construction variable and the value of the keyword argument are both coerced to lists, and the lists are added together. -(See also the Prepend method, below.) +(See also the &Prepend; method). </para> <para> @@ -603,28 +613,6 @@ env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) </summary> </scons_function> -<scons_function name="BuildDir"> -<arguments> -(build_dir, src_dir, [duplicate]) -</arguments> -<summary> -<para> -Deprecated synonyms for -&f-VariantDir; -and -<function>env.VariantDir</function>(). -The -<varname>build_dir</varname> -argument becomes the -<varname>variant_dir</varname> -argument of -&f-VariantDir; -or -<function>env.VariantDir</function>(). -</para> -</summary> -</scons_function> - <scons_function name="Builder"> <arguments> (action, [arguments]) @@ -634,8 +622,8 @@ or Creates a Builder object for the specified <varname>action</varname>. -See the section "Builder Objects," -below, for a complete explanation of the arguments and behavior. +See the manpage section "Builder Objects" +for a complete explanation of the arguments and behavior. </para> <para> @@ -898,11 +886,15 @@ wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags') <builder name="Command"> <summary> <para> -The &b-Command; "Builder" is actually implemented -as a function that looks like a Builder, -but actually takes an additional argument of the action -from which the Builder should be made. -See the &f-link-Command; function description +The &b-Command; "Builder" is actually +a function that looks like a Builder, +but takes a required third argument, which is the +action to take to construct the target +from the source, used for "one-off" builds +where a full builder is not needed. +Thus it does not follow the builder +calling rules described at the start of this section. +See instead the &f-link-Command; function description for the calling syntax and details. </para> </summary> @@ -923,19 +915,29 @@ for a single special-case build. </para> <para> -As a special case, the -<varname>source_scanner</varname> -keyword argument can +&b-Command; builder accepts +<varname>source_scanner</varname>, +<varname>target_scanner</varname>, +<varname>source_factory</varname>, and +<varname>target_factory</varname> +keyword arguments. The *_scanner args can be used to specify a Scanner object -that will be used to scan the sources. -(The global +that will be used to apply a custom +scanner for a source or target. +For example, the global <literal>DirScanner</literal> object can be used if any of the sources will be directories that must be scanned on-disk for changes to files that aren't -already specified in other Builder of function calls.) +already specified in other Builder of function calls. +The *_factory args take a factory function that the +Command will use to turn any sources or targets +specified as strings into SCons Nodes. +See the sections "Builder Objects" +below, for more information about how these +args work in a Builder. </para> <para> @@ -947,7 +949,7 @@ same-named existing construction variables. An action can be an external command, specified as a string, or a callable Python object; -see "Action Objects," below, +see the manpage section "Action Objects" for more complete information. Also note that a string specifying an external command may be preceded by an @@ -971,7 +973,7 @@ env.Command('foo.out', 'foo.in', env.Command('bar.out', 'bar.in', ["rm -f $TARGET", "$BAR_BUILD < $SOURCES > $TARGET"], - ENV = {'PATH' : '/usr/local/bin/'}) + ENV={'PATH': '/usr/local/bin/'}) def rename(env, target, source): import os @@ -979,7 +981,7 @@ def rename(env, target, source): env.Command('baz.out', 'baz.in', ["$BAZ_BUILD < $SOURCES > .tmp", - rename ]) + rename]) </example_commands> <para> @@ -988,14 +990,14 @@ Note that the function will usually assume, by default, that the specified targets and/or sources are Files, if no other part of the configuration -identifies what type of entry it is. +identifies what type of entries they are. If necessary, you can explicitly specify that targets or source nodes should -be treated as directoriese +be treated as directories by using the &f-link-Dir; or -<function>env.Dir</function>() +<function>env.Dir</function> functions. </para> @@ -1011,9 +1013,9 @@ env.Command(env.Dir('$DISTDIR')), None, make_distdir) </example_commands> <para> -(Also note that SCons will usually +Also note that SCons will usually automatically create any directory necessary to hold a target file, -so you normally don't need to create directories by hand.) +so you normally don't need to create directories by hand. </para> </summary> </scons_function> @@ -1029,8 +1031,8 @@ so you normally don't need to create directories by hand.) <para> Creates a Configure object for integrated functionality similar to GNU autoconf. -See the section "Configure Contexts," -below, for a complete explanation of the arguments and behavior. +See the manpage section "Configure Contexts" +for a complete explanation of the arguments and behavior. </para> </summary> </scons_function> @@ -1325,11 +1327,11 @@ env.Depends(bar, installed_lib) <summary> <para> Returns a dictionary object -containing copies of all of the -construction variables in the environment. -If there are any variable names specified, -only the specified construction -variables are returned in the dictionary. +containing the &consvars; in the &consenv;. +If there are any arguments specified, +the values of the specified &consvars; +are returned as a string (if one +argument) or as a list of strings. </para> <para> @@ -1337,8 +1339,8 @@ Example: </para> <example_commands> -dict = env.Dictionary() -cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') +cvars = env.Dictionary() +cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') </example_commands> </summary> </scons_function> @@ -1375,7 +1377,8 @@ would supply a string as a directory name to a Builder method or function. Directory Nodes have attributes and methods that are useful in many situations; -see "File and Directory Nodes," below. +see manpage section "File and Directory Nodes" +for more information. </para> </summary> </scons_function> @@ -1399,7 +1402,7 @@ This SConstruct: <example_commands> env=Environment() -print env.Dump('CCCOM') +print(env.Dump('CCCOM')) </example_commands> <para> @@ -1416,7 +1419,7 @@ While this SConstruct: <example_commands> env=Environment() -print env.Dump() +print(env.Dump()) </example_commands> <para> @@ -1458,8 +1461,8 @@ Executes an Action object. The specified <varname>action</varname> may be an Action object -(see the section "Action Objects," -below, for a complete explanation of the arguments and behavior), +(see manpage section "Action Objects" +for a complete explanation of the arguments and behavior), or it may be a command-line string, list of commands, or executable Python function, @@ -1532,7 +1535,8 @@ would supply a string as a file name to a Builder method or function. File Nodes have attributes and methods that are useful in many situations; -see "File and Directory Nodes," below. +see manpage section "File and Directory Nodes" +for more information. </para> </summary> </scons_function> @@ -2190,7 +2194,7 @@ and the construction variables they affect are as specified for the &f-link-env-ParseFlags; method (which this method calls). -See that method's description, below, +See that method's description for a table of options and construction variables. </para> </summary> @@ -2308,6 +2312,7 @@ and added to the following construction variables: -fmerge-all-constants CCFLAGS, LINKFLAGS -fopenmp CCFLAGS, LINKFLAGS -include CCFLAGS +-imacros CCFLAGS -isysroot CCFLAGS, LINKFLAGS -isystem CCFLAGS -iquote CCFLAGS @@ -2658,8 +2663,8 @@ env.Requires('foo', 'file-that-must-be-built-before-foo') Creates a Scanner object for the specified <varname>function</varname>. -See the section "Scanner Objects," -below, for a complete explanation of the arguments and behavior. +See manpage section "Scanner Objects" +for a complete explanation of the arguments and behavior. </para> </summary> </scons_function> @@ -2971,105 +2976,6 @@ env.SourceCode('no_source.c', None) </summary> </scons_function> -<scons_function name="SourceSignatures"> -<arguments> -(type) -</arguments> -<summary> -<para> -Note: Although it is not yet officially deprecated, -use of this function is discouraged. -See the -&f-link-Decider; -function for a more flexible and straightforward way -to configure SCons' decision-making. -</para> - -<para> -The -&f-SourceSignatures; -function tells -&scons; -how to decide if a source file -(a file that is not built from any other files) -has changed since the last time it -was used to build a particular target file. -Legal values are -<literal>MD5</literal> -or -<literal>timestamp</literal>. -</para> - -<para> -If the environment method is used, -the specified type of source signature -is only used when deciding whether targets -built with that environment are up-to-date or must be rebuilt. -If the global function is used, -the specified type of source signature becomes the default -used for all decisions -about whether targets are up-to-date. -</para> - -<para> -<literal>MD5</literal> -means -&scons; -decides that a source file has changed -if the MD5 checksum of its contents has changed since -the last time it was used to rebuild a particular target file. -</para> - -<para> -<literal>timestamp</literal> -means -&scons; -decides that a source file has changed -if its timestamp (modification time) has changed since -the last time it was used to rebuild a particular target file. -(Note that although this is similar to the behavior of Make, -by default it will also rebuild if the dependency is -<emphasis>older</emphasis> -than the last time it was used to rebuild the target file.) -</para> - -<para> -There is no different between the two behaviors -for Python -&f-Value; -node objects. -</para> - -<para> -<literal>MD5</literal> -signatures take longer to compute, -but are more accurate than -<literal>timestamp</literal> -signatures. -The default value is -<literal>MD5</literal>. -</para> - -<para> -Note that the default -&f-link-TargetSignatures; -setting (see below) -is to use this -&f-SourceSignatures; -setting for any target files that are used -to build other target files. -Consequently, changing the value of -&f-SourceSignatures; -will, by default, -affect the up-to-date decision for all files in the build -(or all files built with a specific construction environment -when -&f-env-SourceSignatures; -is used). -</para> -</summary> -</scons_function> - <scons_function name="Split"> <arguments> (arg) @@ -3200,7 +3106,7 @@ Example: </para> <example_commands> -print env.subst("The C compiler is: $CC") +print(env.subst("The C compiler is: $CC")) def compile(target, source, env): sourceDir = env.subst("${SOURCE.srcdir}", @@ -3213,159 +3119,6 @@ source_nodes = env.subst('$EXPAND_TO_NODELIST', </summary> </scons_function> -<scons_function name="TargetSignatures"> -<arguments> -(type) -</arguments> -<summary> -<para> -Note: Although it is not yet officially deprecated, -use of this function is discouraged. -See the -&f-link-Decider; -function for a more flexible and straightforward way -to configure SCons' decision-making. -</para> - -<para> -The -&f-TargetSignatures; -function tells -&scons; -how to decide if a target file -(a file that -<emphasis>is</emphasis> -built from any other files) -has changed since the last time it -was used to build some other target file. -Legal values are -<literal>"build"</literal>; -<literal>"content"</literal> -(or its synonym -<literal>"MD5"</literal>); -<literal>"timestamp"</literal>; -or -<literal>"source"</literal>. -</para> - -<para> -If the environment method is used, -the specified type of target signature is only used -for targets built with that environment. -If the global function is used, -the specified type of signature becomes the default -used for all target files that -don't have an explicit target signature type -specified for their environments. -</para> - -<para> -<literal>"content"</literal> -(or its synonym -<literal>"MD5"</literal>) -means -&scons; -decides that a target file has changed -if the MD5 checksum of its contents has changed since -the last time it was used to rebuild some other target file. -This means -&scons; -will open up -MD5 sum the contents -of target files after they're built, -and may decide that it does not need to rebuild -"downstream" target files if a file was -rebuilt with exactly the same contents as the last time. -</para> - -<para> -<literal>"timestamp"</literal> -means -&scons; -decides that a target file has changed -if its timestamp (modification time) has changed since -the last time it was used to rebuild some other target file. -(Note that although this is similar to the behavior of Make, -by default it will also rebuild if the dependency is -<emphasis>older</emphasis> -than the last time it was used to rebuild the target file.) -</para> - -<para> -<literal>"source"</literal> -means -&scons; -decides that a target file has changed -as specified by the corresponding -&f-SourceSignatures; -setting -(<literal>"MD5"</literal> -or -<literal>"timestamp"</literal>). -This means that -&scons; -will treat all input files to a target the same way, -regardless of whether they are source files -or have been built from other files. -</para> - -<para> -<literal>"build"</literal> -means -&scons; -decides that a target file has changed -if it has been rebuilt in this invocation -or if its content or timestamp have changed -as specified by the corresponding -&f-SourceSignatures; -setting. -This "propagates" the status of a rebuilt file -so that other "downstream" target files -will always be rebuilt, -even if the contents or the timestamp -have not changed. -</para> - -<para> -<literal>"build"</literal> -signatures are fastest because -<literal>"content"</literal> -(or -<literal>"MD5"</literal>) -signatures take longer to compute, -but are more accurate than -<literal>"timestamp"</literal> -signatures, -and can prevent unnecessary "downstream" rebuilds -when a target file is rebuilt to the exact same contents -as the previous build. -The -<literal>"source"</literal> -setting provides the most consistent behavior -when other target files may be rebuilt from -both source and target input files. -The default value is -<literal>"source"</literal>. -</para> - -<para> -Because the default setting is -<literal>"source"</literal>, -using -&f-SourceSignatures; -is generally preferable to -&f-TargetSignatures;, -so that the up-to-date decision -will be consistent for all files -(or all files built with a specific construction environment). -Use of -&f-TargetSignatures; -provides specific control for how built target files -affect their "downstream" dependencies. -</para> -</summary> -</scons_function> - <scons_function name="Tool"> <arguments> (string, [toolpath, **kw]) @@ -3650,30 +3403,51 @@ SConscript(dirs='doc', variant_dir='build/doc', duplicate=0) Searches for the specified executable <varname>program</varname>, returning the full path name to the program -if it is found, -and returning None if not. -Searches the specified -<varname>path</varname>, -the value of the calling environment's PATH -(<literal>env['ENV']['PATH']</literal>), -or the user's current external PATH -(<literal>os.environ['PATH']</literal>) -by default. +if it is found, else <literal>None</literal>. +Searches the value of the +<varname>path</varname> keyword argument, +or if <literal>None</literal> (the default) +the value of the calling environment's <envar>PATH</envar> +(<literal>env['ENV']['PATH']</literal>). +If <varname>path</varname> is <literal>None</literal> and +the <literal>env['ENV']['PATH']</literal> key does not exist, +the user's current external <envar>PATH</envar> +(<literal>os.environ['PATH']</literal>) is used as fallback. +</para> +<para> On Windows systems, searches for executable -programs with any of the file extensions -listed in the specified -<varname>pathext</varname>, -the calling environment's PATHEXT -(<literal>env['ENV']['PATHEXT']</literal>) -or the user's current PATHEXT +programs with any of the file extensions listed in the +<varname>pathext</varname> keyword argument, +or if <literal>None</literal> (the default) +the calling environment's <envar>PATHEXT</envar> +(<literal>env['ENV']['PATHEXT']</literal>). +The user's current external <envar>PATHEXT</envar> (<literal>os.environ['PATHEXT']</literal>) -by default. +is used as a fallback if <varname>pathext</varname> is +<literal>None</literal> +and the key <literal>env['ENV']['PATHEXT']</literal> +does not exist. +</para> +<para> Will not select any path name or names in the specified <varname>reject</varname> list, if any. </para> +<note> +<para> +If you would prefer to search +the user's current external <envar>PATH</envar> +(<literal>os.environ['PATH']</literal>) +by default, +consider using the function <literal>SCons.Util.WhereIs</literal> instead. +Note that <literal>SCons.Util.WhereIs</literal> +does not expand environment variables automatically +(no implicit <literal>env.subst</literal> for its arguments). +</para> +</note> + </summary> </scons_function> |