diff options
Diffstat (limited to 'SCons/Environment.xml')
| -rw-r--r-- | SCons/Environment.xml | 147 |
1 files changed, 57 insertions, 90 deletions
diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 08df523..7d3927b 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -1,6 +1,6 @@ <?xml version="1.0"?> <!-- -__COPYRIGHT__ +Copyright The SCons Foundation This file is processed by the bin/SConsDoc.py module. See its __doc__ string for a discussion of the format. @@ -286,31 +286,22 @@ until the Action object is actually used. </arguments> <summary> <para> -When called with the -<function>AddMethod</function>() -form, -adds the specified -<parameter>function</parameter> -to the specified -<parameter>object</parameter> -as the specified method -<parameter>name</parameter>. -When called using the -&f-env-AddMethod; form, -adds the specified -<parameter>function</parameter> -to the construction environment -<replaceable>env</replaceable> -as the specified method -<parameter>name</parameter>. -In both cases, if -<parameter>name</parameter> -is omitted or -<constant>None</constant>, -the name of the -specified -<parameter>function</parameter> -itself is used for the method name. +Adds <parameter>function</parameter> to an object as a method. +<parameter>function</parameter> will be called with an instance +object as the first argument as for other methods. +If <parameter>name</parameter> is given, it is used as +the name of the new method, else the name of +<parameter>function</parameter> is used. +</para> +<para> +When the global function &f-AddMethod; is called, +the object to add the method to must be passed as the first argument; +typically this will be &Environment;, +in order to create a method which applies to all &consenvs; +subsequently constructed. +When called using the &f-env-AddMethod; form, +the method is added to the specified &consenv; only. +Added methods propagate through &f-env-Clone; calls. </para> <para> @@ -318,22 +309,17 @@ Examples: </para> <example_commands> -# Note that the first argument to the function to -# be attached as a method must be the object through -# which the method will be called; the Python -# convention is to call it 'self'. +# Function to add must accept an instance argument. +# The Python convention is to call this 'self'. def my_method(self, arg): print("my_method() got", arg) -# Use the global AddMethod() function to add a method -# to the Environment class. This +# Use the global function to add a method to the Environment class: AddMethod(Environment, my_method) env = Environment() env.my_method('arg') -# Add the function as a method, using the function -# name for the method call. -env = Environment() +# Use the optional name argument to set the name of the method: env.AddMethod(my_method, 'other_method_name') env.other_method_name('another arg') </example_commands> @@ -3174,8 +3160,8 @@ def create(target, source, env): # A function that will write a 'prefix=$SOURCE' # string into the file name specified as the # $TARGET. - f = open(str(target[0]), 'wb') - f.write('prefix=' + source[0].get_contents()) + with open(str(target[0]), 'wb') as f: + f.write('prefix=' + source[0].get_contents()) # Fetch the prefix= argument, if any, from the command # line, and use /usr/local as the default. @@ -3209,90 +3195,75 @@ env.UpdateValue(target = Value(output), source = Value(input)) </arguments> <summary> <para> -Use the -&f-VariantDir; -function to create a copy of your sources in another location: -if a name under -<parameter>variant_dir</parameter> -is not found but exists under -<parameter>src_dir</parameter>, -the file or directory is copied to -<parameter>variant_dir</parameter>. -Target files can be built in a different directory -than the original sources by simply refering to the sources (and targets) -within the variant tree. -</para> - -<para> +Sets up an alternate build location. +When building in the <parameter>variant_dir</parameter>, +&SCons; backfills as needed with files from <parameter>src_dir</parameter> +to create a complete build directory. &f-VariantDir; can be called multiple times with the same <parameter>src_dir</parameter> to set up multiple builds with different options -(<parameter>variants</parameter>). +(<emphasis>variants</emphasis>). +</para> + +<para> The -<parameter>src_dir</parameter> -location must be in or underneath the SConstruct file's directory, and -<parameter>variant_dir</parameter> +<parameter>variant</parameter> +location must be in or underneath the project top directory, +and <parameter>src_dir</parameter> may not be underneath -<parameter>src_dir</parameter>. -<!-- -TODO: Can the above restrictions be clarified or relaxed? -TODO: The latter restriction is clearly not completely right; -TODO: src_dir = '.' works fine with a build dir under it. ---> +<parameter>variant_dir</parameter>. </para> <para> -The default behavior is for -&scons; -to physically duplicate the source files in the variant tree. +By default, &SCons; +physically duplicates the source files and SConscript files +as needed into the variant tree. Thus, a build performed in the variant tree is guaranteed to be identical to a build performed in the source tree even if intermediate source files are generated during the build, -or preprocessors or other scanners search for included files +or if preprocessors or other scanners search for included files relative to the source file, -or individual compilers or other invoked tools are hard-coded +or if individual compilers or other invoked tools are hard-coded to put derived files in the same directory as source files. +Only the files &SCons; calculates are needed for the build are +duplicated into <parameter>variant_dir</parameter>. </para> <para> If possible on the platform, -the duplication is performed by linking rather than copying; -see also the +the duplication is performed by linking rather than copying. +This behavior is affected by the <option>--duplicate</option> command-line option. -Moreover, only the files needed for the build are duplicated; -files and directories that are not used are not present in -<parameter>variant_dir</parameter>. </para> <para> -Duplicating the source tree may be disabled by setting the -<literal>duplicate</literal> +Duplicating the source files may be disabled by setting the +<parameter>duplicate</parameter> argument to -<literal>0</literal> -(zero). +<constant>False</constant>. This will cause -&scons; +&SCons; to invoke Builders using the path names of source files in <parameter>src_dir</parameter> and the path names of derived files within <parameter>variant_dir</parameter>. -This is always more efficient than -<literal>duplicate=1</literal>, -and is usually safe for most builds -(but see above for cases that may cause problems). +This is more efficient than +<literal>duplicate=True</literal>, +and is safe for most builds; +revert to <constant>True</constant> +if it causes problems. </para> <para> -Note that &f-VariantDir; -works most naturally with a subsidiary SConscript file. -However, you would then call the subsidiary SConscript file -not in the source directory, but in the +works most naturally with used with a subsidiary SConscript file. +The subsidiary SConscript file is called as if it +were in <parameter>variant_dir</parameter>, regardless of the value of -<literal>duplicate</literal>. +<parameter>duplicate</parameter>. This is how you tell &scons; which variant of a source tree to build: @@ -3322,15 +3293,11 @@ Examples: # use names in the build directory, not the source directory VariantDir('build', 'src', duplicate=0) Program('build/prog', 'build/source.c') -</example_commands> -<example_commands> # this builds both the source and docs in a separate subtree VariantDir('build', '.', duplicate=0) SConscript(dirs=['build/src','build/doc']) -</example_commands> -<example_commands> # same as previous example, but only uses SConscript SConscript(dirs='src', variant_dir='build/src', duplicate=0) SConscript(dirs='doc', variant_dir='build/doc', duplicate=0) |