diff options
| -rw-r--r-- | doc/generated/functions.gen | 14 | ||||
| -rw-r--r-- | doc/man/scons.xml | 59 | ||||
| -rw-r--r-- | doc/user/environments.xml | 19 | ||||
| -rw-r--r-- | src/engine/SCons/Environment.py | 43 | ||||
| -rw-r--r-- | src/engine/SCons/Environment.xml | 14 |
5 files changed, 94 insertions, 55 deletions
diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index 9bed358..c446a44 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -1333,11 +1333,11 @@ env.Depends(bar, installed_lib) <listitem> <para xmlns="http://www.scons.org/dbxsd/v1.0"> 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 construction variables in the environment. +If there are any arguments specified, +only the values of the specified construction +variables are returned as a string (if one +argument) or as a list of strings. </para> <para xmlns="http://www.scons.org/dbxsd/v1.0"> @@ -1345,8 +1345,8 @@ Example: </para> <example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> -dict = env.Dictionary() -cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') +cvars = env.Dictionary() +cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') </example_commands> </listitem> </varlistentry> diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 542ac9d..e610386 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2577,8 +2577,8 @@ object_files.extend(Object('bar.c')) </literallayout> <para>The path name for a Node's file may be used -by passing the Node to the Python-builtin -<function>str()</function> +by passing the Node to Python's builtin +<function>str</function> function:</para> <literallayout class="monospaced"> @@ -3119,11 +3119,12 @@ defined construction variables:</para> method of the construction environment:</para> <literallayout class="monospaced"> -dict = env.Dictionary() -dict["CC"] = "cc" +cvars = env.Dictionary() +cvars["CC"] = "cc" </literallayout> -<para>or using the [] operator:</para> +<para>or using the key lookup operator <literal>[]</literal> +directly on the construction environment:</para> <literallayout class="monospaced"> env["CC"] = "cc" @@ -6315,7 +6316,8 @@ might not exist argument is the construction environment for the scan. Fetch values from it using the <emphasis role="bold">env.Dictionary()</emphasis> -method.</para> +method or using the key lookup operator +directly on the construction environment.</para> <para>The <emphasis role="bold">path</emphasis> @@ -6771,7 +6773,7 @@ env['BUILDERS]['PDFBuilder'] = bld <refsect2 id='defining_your_own_scanner_object'><title>Defining Your Own Scanner Object</title> -<para>The following example shows an extremely simple scanner (the +<para>The following example shows adding an extremely simple scanner (the <emphasis role="bold">kfile_scan</emphasis>() function) that doesn't use a search path at all @@ -6796,8 +6798,10 @@ kscan = Scanner(name = 'kfile', function = kfile_scan, argument = None, skeys = ['.k']) -scanners = Environment().Dictionary('SCANNERS') -env = Environment(SCANNERS = scanners + [kscan]) + +scanners = DefaultEnvironment()['SCANNERS'] +scanners.append(kscan) +env = Environment(SCANNERS=scanners) env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') @@ -6814,7 +6818,8 @@ you can use the function of your current Environment in order to create nodes on the fly from a sequence of file names with relative paths.</para> -<para>Here is a similar but more complete example that searches +<para>Here is a similar but more complete example that adds +a scanner which searches a path of directories (specified as the <emphasis role="bold">MYPATH</emphasis> @@ -6840,15 +6845,16 @@ def my_scan(node, env, path, arg): break return env.File(results) -scanner = Scanner(name = 'myscanner', - function = my_scan, - argument = None, - skeys = ['.x'], - path_function = FindPathDirs('MYPATH') +scanner = Scanner(name='myscanner', + function=my_scan, + argument=None, + skeys=['.x'], + path_function=FindPathDirs('MYPATH') ) -scanners = Environment().Dictionary('SCANNERS') -env = Environment(SCANNERS = scanners + [scanner], - MYPATH = ['incs']) + +scanners = DefaultEnvironment()['SCANNERS'] +scanners.append(scanner) +env = Environment(SCANNERS=scanners, MYPATH=['incs']) env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET') </programlisting> @@ -6861,8 +6867,8 @@ that will return a list of directories specified in the <emphasis role="bold">$MYPATH</emphasis> construction variable. It lets SCons detect the file -<emphasis role="bold">incs/foo.inc</emphasis> -, even if +<emphasis role="bold">incs/foo.inc</emphasis>, +even if <emphasis role="bold">foo.x</emphasis> contains the line <emphasis role="bold">include foo.inc</emphasis> @@ -6883,17 +6889,18 @@ def pf(env, dir, target, source, arg): results.append(top_dir + os.sep + p) return results -scanner = Scanner(name = 'myscanner', - function = my_scan, - argument = None, - skeys = ['.x'], - path_function = pf +scanner = Scanner(name='myscanner', + function=my_scan, + argument=None, + skeys=['.x'], + path_function=pf ) </programlisting> </refsect2> -<refsect2 id='creating_a_hierarchical_build'><title>Creating a Hierarchical Build</title> +<refsect2 id='creating_a_hierarchical_build'> +<title>Creating a Hierarchical Build</title> <para>Notice that the file names specified in a subdirectory's SConscript diff --git a/doc/user/environments.xml b/doc/user/environments.xml index 65eed72..3f1f142 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -645,8 +645,9 @@ print("CC is: %s"%env['CC']) <para> - A construction environment, however, - is actually an object with associated methods, etc. + A construction environment + is actually an object with associated methods and + attributes. If you want to have direct access to only the dictionary of construction variables, you can fetch this using the &Dictionary; method: @@ -656,9 +657,9 @@ print("CC is: %s"%env['CC']) <scons_example name="environments_ex6b"> <file name="SConstruct" printme="1"> env = Environment(FOO = 'foo', BAR = 'bar') -dict = env.Dictionary() +cvars = env.Dictionary() for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']: - print("key = %s, value = %s" % (key, dict[key])) + print("key = %s, value = %s" % (key, cvars[key])) </file> </scons_example> @@ -698,6 +699,16 @@ for item in sorted(env.Dictionary().items()): print("construction variable = '%s', value = '%s'" % item) </sconstruct> + <para> + It should be noted that for the previous example, there is actually + an environment method that does the same thing more simply, + and tries to format it nicely as well: + </para> + <sconstruct> +env = Environment() +print(env.Dump()) + </sconstruct> + </section> <section> diff --git a/src/engine/SCons/Environment.py b/src/engine/SCons/Environment.py index 5faa2d0..2e1e742 100644 --- a/src/engine/SCons/Environment.py +++ b/src/engine/SCons/Environment.py @@ -1493,8 +1493,14 @@ class Base(SubstitutionEnvironment): self.copy_from_cache = copy_function + def Detect(self, progs): """Return the first available program in progs. + + :param progs: one or more command names to check for + :type progs: str or list + :returns str: first name from progs that can be found. + """ if not SCons.Util.is_List(progs): progs = [ progs ] @@ -1503,7 +1509,17 @@ class Base(SubstitutionEnvironment): if path: return prog return None + def Dictionary(self, *args): + """Return construction variables from an environment. + + :param *args: (optional) variable names to look up + :returns: if args omitted, the dictionary of all constr. vars. + If one arg, the corresponding value is returned. + If more than one arg, a list of values is returned. + :raises KeyError: if any of *args is not in the construction env. + + """ if not args: return self._dict dlist = [self._dict[x] for x in args] @@ -1511,23 +1527,28 @@ class Base(SubstitutionEnvironment): dlist = dlist[0] return dlist - def Dump(self, key = None): - """ - Using the standard Python pretty printer, return the contents of the - scons build environment as a string. - If the key passed in is anything other than None, then that will - be used as an index into the build environment dictionary and - whatever is found there will be fed into the pretty printer. Note - that this key is case sensitive. + def Dump(self, key=None): + """ Return pretty-printed string of construction variables. + + :param key: if None, format the whole dict of variables. + Else look up and format just the value for key. + """ import pprint pp = pprint.PrettyPrinter(indent=2) if key: - dict = self.Dictionary(key) + cvars = self.Dictionary(key) else: - dict = self.Dictionary() - return pp.pformat(dict) + cvars = self.Dictionary() + + # TODO: pprint doesn't do a nice job on path-style values + # if the paths contain spaces (i.e. Windows), because the + # algorithm tries to break lines on spaces, while breaking + # on the path-separator would be more "natural". Is there + # a better way to format those? + return pp.pformat(cvars) + def FindIxes(self, paths, prefix, suffix): """ diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml index 46a00d2..3f12b4f 100644 --- a/src/engine/SCons/Environment.xml +++ b/src/engine/SCons/Environment.xml @@ -1325,11 +1325,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 construction variables in the environment. +If there are any arguments specified, +only the values of the specified construction +variables are returned as a string (if one +argument) or as a list of strings. </para> <para> @@ -1337,8 +1337,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> |