diff options
43 files changed, 625 insertions, 579 deletions
diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..089d31b --- /dev/null +++ b/.gitattributes @@ -0,0 +1,6 @@ +doc/* linguist-documentation +src/engine/SCons/Tool/docbook/docbook-xsl-1.76.1 linguist-vendored +*.xml linguist-documentation +*.xsl linguist-documentation +*.gen linguist-documentation + diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..9daae32 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,5 @@ +# These are supported funding model platforms + +github: bdbaddog +patreon: bdbaddog + diff --git a/bin/scons_dev_master.py b/bin/scons_dev_master.py index 4b1160f..cdbd68e 100644..100755 --- a/bin/scons_dev_master.py +++ b/bin/scons_dev_master.py @@ -1,4 +1,4 @@ -#!/bin/sh +#!/usr/bin/python # # A script for turning a generic Ubuntu system into a master for diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen index 54c7aaa..59d2dca 100644 --- a/doc/generated/builders.gen +++ b/doc/generated/builders.gen @@ -48,11 +48,15 @@ env.CFile(target = 'bar', source = 'bar.y') </term> <listitem> <para xmlns="http://www.scons.org/dbxsd/v1.0"> -The <function xmlns="http://www.scons.org/dbxsd/v1.0">Command</function> "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 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Command"><function>Command</function></link> function description +The <function xmlns="http://www.scons.org/dbxsd/v1.0">Command</function> "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 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Command"><function>Command</function></link> function description for the calling syntax and details. </para> </listitem> @@ -465,6 +469,22 @@ a builder. <example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> env.Install('/usr/local/bin', source = ['foo', 'bar']) </example_commands> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +If the <option>--install-sandbox</option> command line +option is given, the target directory will be prefixed +by the directory path specified. +This is useful to test installs without installing to +a "live" location in the system. +</para> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +See also <function xmlns="http://www.scons.org/dbxsd/v1.0">FindInstalledFiles</function>. +For more thoughts on installation, see the User Guide +(particularly the section on Command-Line Targets +and the chapters on Installing Files and on Alias Targets). +</para> + </listitem> </varlistentry> <varlistentry id="b-InstallAs"> diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index e55799c..66672b0 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -25,8 +25,8 @@ 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 xmlns="http://www.scons.org/dbxsd/v1.0"> @@ -221,6 +221,21 @@ AddOption('--prefix', help='installation prefix') env = Environment(PREFIX = GetOption('prefix')) </example_commands> + +<note xmlns="http://www.scons.org/dbxsd/v1.0"> +<para> +While <function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function> behaves like +<function>optparse.add_option</function>, +the behavior of options added by <function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function> +which take arguments is underfined in +<command>scons</command> if whitespace +(rather than <literal>=</literal> sign) is used as +the separator on the command line when +the option is invoked. +Such usage should be avoided. +</para> +</note> + </listitem> </varlistentry> <varlistentry id="f-AddPostAction"> @@ -241,7 +256,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 xmlns="http://www.scons.org/dbxsd/v1.0"> @@ -270,7 +286,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 xmlns="http://www.scons.org/dbxsd/v1.0"> @@ -444,7 +461,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 <function xmlns="http://www.scons.org/dbxsd/v1.0">Prepend</function> method). </para> <para xmlns="http://www.scons.org/dbxsd/v1.0"> @@ -568,8 +585,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 xmlns="http://www.scons.org/dbxsd/v1.0"> @@ -873,7 +890,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 @@ -897,7 +914,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 @@ -905,7 +922,7 @@ def rename(env, target, source): env.Command('baz.out', 'baz.in', ["$BAZ_BUILD < $SOURCES > .tmp", - rename ]) + rename]) </example_commands> <para xmlns="http://www.scons.org/dbxsd/v1.0"> @@ -914,14 +931,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 <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Dir"><function>Dir</function></link> or -<function>env.Dir</function>() +<function>env.Dir</function> functions. </para> @@ -937,9 +954,9 @@ env.Command(env.Dir('$DISTDIR')), None, make_distdir) </example_commands> <para xmlns="http://www.scons.org/dbxsd/v1.0"> -(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> </listitem> </varlistentry> @@ -954,8 +971,8 @@ so you normally don't need to create directories by hand.) <para xmlns="http://www.scons.org/dbxsd/v1.0"> 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> </listitem> </varlistentry> @@ -1385,7 +1402,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> </listitem> </varlistentry> @@ -1528,8 +1546,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, @@ -1686,7 +1704,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> </listitem> </varlistentry> @@ -2505,16 +2524,16 @@ This specifies help text to be printed if the <option>-h</option> argument is given to <filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename>. -If +If <function xmlns="http://www.scons.org/dbxsd/v1.0">Help</function> -is called multiple times, the text is appended together in the order that +is called multiple times, the text is appended together in the order that <function xmlns="http://www.scons.org/dbxsd/v1.0">Help</function> -is called. With append set to False, any +is called. With append set to False, any <function xmlns="http://www.scons.org/dbxsd/v1.0">Help</function> -text generated with +text generated with <function xmlns="http://www.scons.org/dbxsd/v1.0">AddOption</function> is clobbered. If append is True, the AddOption help is prepended to the help -string, thus preserving the +string, thus preserving the <option>-h</option> message. </para> @@ -2836,7 +2855,7 @@ and the construction variables they affect are as specified for the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-ParseFlags"><function>env.ParseFlags</function></link> 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> </listitem> @@ -2955,6 +2974,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 @@ -3539,8 +3559,8 @@ Return('val1 val2') 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> </listitem> </varlistentry> @@ -4229,107 +4249,6 @@ env.SourceCode('no_source.c', None) </para> </listitem> </varlistentry> - <varlistentry id="f-SourceSignatures"> - <term> - <literal>SourceSignatures(type)</literal> - </term> - <term> - <literal>env.SourceSignatures(type)</literal> - </term> - <listitem> -<para xmlns="http://www.scons.org/dbxsd/v1.0"> -Note: Although it is not yet officially deprecated, -use of this function is discouraged. -See the -<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Decider"><function>Decider</function></link> -function for a more flexible and straightforward way -to configure SCons' decision-making. -</para> - -<para xmlns="http://www.scons.org/dbxsd/v1.0"> -The -<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function> -function tells -<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> -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 xmlns="http://www.scons.org/dbxsd/v1.0"> -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 xmlns="http://www.scons.org/dbxsd/v1.0"> -<literal>MD5</literal> -means -<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> -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 xmlns="http://www.scons.org/dbxsd/v1.0"> -<literal>timestamp</literal> -means -<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> -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 xmlns="http://www.scons.org/dbxsd/v1.0"> -There is no different between the two behaviors -for Python -<function xmlns="http://www.scons.org/dbxsd/v1.0">Value</function> -node objects. -</para> - -<para xmlns="http://www.scons.org/dbxsd/v1.0"> -<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 xmlns="http://www.scons.org/dbxsd/v1.0"> -Note that the default -<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-TargetSignatures"><function>TargetSignatures</function></link> -setting (see below) -is to use this -<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function> -setting for any target files that are used -to build other target files. -Consequently, changing the value of -<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function> -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 -<function xmlns="http://www.scons.org/dbxsd/v1.0">env.SourceSignatures</function> -is used). -</para> -</listitem> - </varlistentry> <varlistentry id="f-Split"> <term> <literal>Split(arg)</literal> @@ -4501,161 +4420,6 @@ Tag( 'file2.txt', DOC ) </example_commands> </listitem> </varlistentry> - <varlistentry id="f-TargetSignatures"> - <term> - <literal>TargetSignatures(type)</literal> - </term> - <term> - <literal>env.TargetSignatures(type)</literal> - </term> - <listitem> -<para xmlns="http://www.scons.org/dbxsd/v1.0"> -Note: Although it is not yet officially deprecated, -use of this function is discouraged. -See the -<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="f-Decider"><function>Decider</function></link> -function for a more flexible and straightforward way -to configure SCons' decision-making. -</para> - -<para xmlns="http://www.scons.org/dbxsd/v1.0"> -The -<function xmlns="http://www.scons.org/dbxsd/v1.0">TargetSignatures</function> -function tells -<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> -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 xmlns="http://www.scons.org/dbxsd/v1.0"> -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 xmlns="http://www.scons.org/dbxsd/v1.0"> -<literal>"content"</literal> -(or its synonym -<literal>"MD5"</literal>) -means -<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> -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 -<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> -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 xmlns="http://www.scons.org/dbxsd/v1.0"> -<literal>"timestamp"</literal> -means -<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> -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 xmlns="http://www.scons.org/dbxsd/v1.0"> -<literal>"source"</literal> -means -<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> -decides that a target file has changed -as specified by the corresponding -<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function> -setting -(<literal>"MD5"</literal> -or -<literal>"timestamp"</literal>). -This means that -<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> -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 xmlns="http://www.scons.org/dbxsd/v1.0"> -<literal>"build"</literal> -means -<filename xmlns="http://www.scons.org/dbxsd/v1.0">scons</filename> -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 -<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function> -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 xmlns="http://www.scons.org/dbxsd/v1.0"> -<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 xmlns="http://www.scons.org/dbxsd/v1.0"> -Because the default setting is -<literal>"source"</literal>, -using -<function xmlns="http://www.scons.org/dbxsd/v1.0">SourceSignatures</function> -is generally preferable to -<function xmlns="http://www.scons.org/dbxsd/v1.0">TargetSignatures</function>, -so that the up-to-date decision -will be consistent for all files -(or all files built with a specific construction environment). -Use of -<function xmlns="http://www.scons.org/dbxsd/v1.0">TargetSignatures</function> -provides specific control for how built target files -affect their "downstream" dependencies. -</para> -</listitem> - </varlistentry> <varlistentry id="f-Tool"> <term> <literal>Tool(string, [toolpath, **kw])</literal> @@ -4949,30 +4713,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 xmlns="http://www.scons.org/dbxsd/v1.0"> 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 xmlns="http://www.scons.org/dbxsd/v1.0"> Will not select any path name or names in the specified <varname>reject</varname> list, if any. </para> +<note xmlns="http://www.scons.org/dbxsd/v1.0"> +<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> + </listitem> </varlistentry> </variablelist> diff --git a/doc/generated/functions.mod b/doc/generated/functions.mod index e460aaf..91710a3 100644 --- a/doc/generated/functions.mod +++ b/doc/generated/functions.mod @@ -82,11 +82,9 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY f-SetOption "<function xmlns='http://www.scons.org/dbxsd/v1.0'>SetOption</function>"> <!ENTITY f-SideEffect "<function xmlns='http://www.scons.org/dbxsd/v1.0'>SideEffect</function>"> <!ENTITY f-SourceCode "<function xmlns='http://www.scons.org/dbxsd/v1.0'>SourceCode</function>"> -<!ENTITY f-SourceSignatures "<function xmlns='http://www.scons.org/dbxsd/v1.0'>SourceSignatures</function>"> <!ENTITY f-Split "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Split</function>"> <!ENTITY f-subst "<function xmlns='http://www.scons.org/dbxsd/v1.0'>subst</function>"> <!ENTITY f-Tag "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Tag</function>"> -<!ENTITY f-TargetSignatures "<function xmlns='http://www.scons.org/dbxsd/v1.0'>TargetSignatures</function>"> <!ENTITY f-Tool "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Tool</function>"> <!ENTITY f-Value "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Value</function>"> <!ENTITY f-VariantDir "<function xmlns='http://www.scons.org/dbxsd/v1.0'>VariantDir</function>"> @@ -166,11 +164,9 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY f-env-SetOption "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.SetOption</function>"> <!ENTITY f-env-SideEffect "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.SideEffect</function>"> <!ENTITY f-env-SourceCode "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.SourceCode</function>"> -<!ENTITY f-env-SourceSignatures "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.SourceSignatures</function>"> <!ENTITY f-env-Split "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Split</function>"> <!ENTITY f-env-subst "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.subst</function>"> <!ENTITY f-env-Tag "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Tag</function>"> -<!ENTITY f-env-TargetSignatures "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.TargetSignatures</function>"> <!ENTITY f-env-Tool "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Tool</function>"> <!ENTITY f-env-Value "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Value</function>"> <!ENTITY f-env-VariantDir "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.VariantDir</function>"> @@ -260,11 +256,9 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY f-link-SetOption "<link linkend='f-SetOption' xmlns='http://www.scons.org/dbxsd/v1.0'><function>SetOption</function></link>"> <!ENTITY f-link-SideEffect "<link linkend='f-SideEffect' xmlns='http://www.scons.org/dbxsd/v1.0'><function>SideEffect</function></link>"> <!ENTITY f-link-SourceCode "<link linkend='f-SourceCode' xmlns='http://www.scons.org/dbxsd/v1.0'><function>SourceCode</function></link>"> -<!ENTITY f-link-SourceSignatures "<link linkend='f-SourceSignatures' xmlns='http://www.scons.org/dbxsd/v1.0'><function>SourceSignatures</function></link>"> <!ENTITY f-link-Split "<link linkend='f-Split' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Split</function></link>"> <!ENTITY f-link-subst "<link linkend='f-subst' xmlns='http://www.scons.org/dbxsd/v1.0'><function>subst</function></link>"> <!ENTITY f-link-Tag "<link linkend='f-Tag' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Tag</function></link>"> -<!ENTITY f-link-TargetSignatures "<link linkend='f-TargetSignatures' xmlns='http://www.scons.org/dbxsd/v1.0'><function>TargetSignatures</function></link>"> <!ENTITY f-link-Tool "<link linkend='f-Tool' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Tool</function></link>"> <!ENTITY f-link-Value "<link linkend='f-Value' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Value</function></link>"> <!ENTITY f-link-VariantDir "<link linkend='f-VariantDir' xmlns='http://www.scons.org/dbxsd/v1.0'><function>VariantDir</function></link>"> @@ -344,11 +338,9 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY f-link-env-SetOption "<link linkend='f-SetOption' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.SetOption</function></link>"> <!ENTITY f-link-env-SideEffect "<link linkend='f-SideEffect' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.SideEffect</function></link>"> <!ENTITY f-link-env-SourceCode "<link linkend='f-SourceCode' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.SourceCode</function></link>"> -<!ENTITY f-link-env-SourceSignatures "<link linkend='f-SourceSignatures' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.SourceSignatures</function></link>"> <!ENTITY f-link-env-Split "<link linkend='f-Split' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Split</function></link>"> <!ENTITY f-link-env-subst "<link linkend='f-subst' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.subst</function></link>"> <!ENTITY f-link-env-Tag "<link linkend='f-Tag' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Tag</function></link>"> -<!ENTITY f-link-env-TargetSignatures "<link linkend='f-TargetSignatures' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.TargetSignatures</function></link>"> <!ENTITY f-link-env-Tool "<link linkend='f-Tool' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Tool</function></link>"> <!ENTITY f-link-env-Value "<link linkend='f-Value' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Value</function></link>"> <!ENTITY f-link-env-VariantDir "<link linkend='f-VariantDir' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.VariantDir</function></link>"> diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen index 8f09512..cf54aab 100644 --- a/doc/generated/variables.gen +++ b/doc/generated/variables.gen @@ -488,7 +488,8 @@ after the SCons template for the file has been written. <para xmlns="http://www.scons.org/dbxsd/v1.0"> 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> </listitem> </varlistentry> @@ -498,7 +499,8 @@ that may not be set or used in a construction environment. <para xmlns="http://www.scons.org/dbxsd/v1.0"> 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> </listitem> </varlistentry> @@ -2804,15 +2806,6 @@ is <quote><literal>-dNOPAUSE -dBATCH -sDEVICE=pdfwrite</literal></quote> <term>HOST_ARCH</term> <listitem> <para xmlns="http://www.scons.org/dbxsd/v1.0"> - The name of the host hardware architecture used to create the Environment. - If a platform is specified when creating the Environment, then - that Platform's logic will handle setting this value. - This value is immutable, and should not be changed by the user after - the Environment is initialized. - Currently only set for Win32. -</para> - -<para xmlns="http://www.scons.org/dbxsd/v1.0"> Sets the host architecture for Visual Studio compiler. If not set, default to the detected host architecture: note that this may depend on the python you are using. @@ -2828,7 +2821,16 @@ Valid values are the same as for <envar xmlns="http://www.scons.org/dbxsd/v1.0"> This is currently only used on Windows, but in the future it will be used on other OSes as well. </para> -</listitem> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> + The name of the host hardware architecture used to create the Environment. + If a platform is specified when creating the Environment, then + that Platform's logic will handle setting this value. + This value is immutable, and should not be changed by the user after + the Environment is initialized. + Currently only set for Win32. +</para> + </listitem> </varlistentry> <varlistentry id="cv-HOST_OS"> <term>HOST_OS</term> @@ -2900,7 +2902,7 @@ to <literal>'.dll'</literal>. Used to override <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link>/<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LDMODULEVERSION"><envar>$LDMODULEVERSION</envar></link> when generating versioned import library for a shared library/loadable module. If undefined, the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link>/<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-LDMODULEVERSION"><envar>$LDMODULEVERSION</envar></link> is used to -determine the version of versioned import library. +determine the version of versioned import library. </para> </listitem> </varlistentry> @@ -3070,7 +3072,7 @@ The command line used to call the Java archive tool. <para xmlns="http://www.scons.org/dbxsd/v1.0"> The string displayed when the Java archive tool is called -If this is not set, then <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JARCOM"><envar>$JARCOM</envar></link> (the command line) is displayed. +If this is not set, then <envar xmlns="http://www.scons.org/dbxsd/v1.0">$JARCOM</envar> (the command line) is displayed. </para> <example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> @@ -3080,7 +3082,7 @@ env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET") <para xmlns="http://www.scons.org/dbxsd/v1.0"> The string displayed when the Java archive tool is called -If this is not set, then <envar xmlns="http://www.scons.org/dbxsd/v1.0">$JARCOM</envar> (the command line) is displayed. +If this is not set, then <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JARCOM"><envar>$JARCOM</envar></link> (the command line) is displayed. </para> <example_commands xmlns="http://www.scons.org/dbxsd/v1.0"> @@ -3446,6 +3448,17 @@ If this is not set, then <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend=" </para> </listitem> </varlistentry> + <varlistentry id="cv-LDMODULEEMITTER"> + <term>LDMODULEEMITTER</term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Contains the emitter specification for the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-LoadableModule"><function>LoadableModule</function></link> builder. +The manpage section "Builder Objects" contains +general information on specifying emitters. +</para> +</listitem> + </varlistentry> <varlistentry id="cv-LDMODULEFLAGS"> <term>LDMODULEFLAGS</term> <listitem> @@ -3618,7 +3631,10 @@ when the <envar xmlns="http://www.scons.org/dbxsd/v1.0">$_LIBDIRFLAGS</envar> va <term>LIBEMITTER</term> <listitem> <para xmlns="http://www.scons.org/dbxsd/v1.0"> -TODO +Contains the emitter specification for the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-StaticLibrary"><function>StaticLibrary</function></link> builder. +The manpage section "Builder Objects" contains +general information on specifying emitters. </para> </listitem> </varlistentry> @@ -5108,7 +5124,10 @@ for example. <term>PROGEMITTER</term> <listitem> <para xmlns="http://www.scons.org/dbxsd/v1.0"> -TODO +Contains the emitter specification for the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-Program"><function>Program</function></link> builder. +The manpage section "Builder Objects" contains +general information on specifying emitters. </para> </listitem> </varlistentry> @@ -5803,9 +5822,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> </listitem> </varlistentry> @@ -6465,7 +6484,10 @@ If this is not set, then <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend=" <term>SHLIBEMITTER</term> <listitem> <para xmlns="http://www.scons.org/dbxsd/v1.0"> -TODO +Contains the emitter specification for the +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-SharedLibrary"><function>SharedLibrary</function></link> builder. +The manpage section "Builder Objects" contains +general information on specifying emitters. </para> </listitem> </varlistentry> @@ -6509,7 +6531,7 @@ The suffix used for shared library file names. <listitem> <para xmlns="http://www.scons.org/dbxsd/v1.0"> When this construction variable is defined, a versioned shared library -is created by <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-SharedLibrary"><function>SharedLibrary</function></link> builder. This activates the +is created by the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-SharedLibrary"><function>SharedLibrary</function></link> builder. This activates the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-_SHLIBVERSIONFLAGS"><envar>$_SHLIBVERSIONFLAGS</envar></link> and thus modifies the <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLINKCOM"><envar>$SHLINKCOM</envar></link> as required, adds the version number to the library name, and creates the symlinks that are needed. <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> versions should exist as alpha-numeric, @@ -6518,6 +6540,16 @@ Example <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"> </para> </listitem> </varlistentry> + <varlistentry id="cv-SHLIBVERSIONFLAGS"> + <term>SHLIBVERSIONFLAGS</term> + <listitem> +<para xmlns="http://www.scons.org/dbxsd/v1.0"> +Extra flags added to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLINKCOM"><envar>$SHLINKCOM</envar></link> when building versioned +<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-SharedLibrary"><function>SharedLibrary</function></link>. These flags are only used when <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> is +set. +</para> +</listitem> + </varlistentry> <varlistentry id="cv-_SHLIBVERSIONFLAGS"> <term>_SHLIBVERSIONFLAGS</term> <listitem> @@ -6531,16 +6563,6 @@ and some extra dynamically generated options (such as </para> </listitem> </varlistentry> - <varlistentry id="cv-SHLIBVERSIONFLAGS"> - <term>SHLIBVERSIONFLAGS</term> - <listitem> -<para xmlns="http://www.scons.org/dbxsd/v1.0"> -Extra flags added to <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLINKCOM"><envar>$SHLINKCOM</envar></link> when building versioned -<link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="b-SharedLibrary"><function>SharedLibrary</function></link>. These flags are only used when <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-SHLIBVERSION"><envar>$SHLIBVERSION</envar></link> is -set. -</para> -</listitem> - </varlistentry> <varlistentry id="cv-SHLINK"> <term>SHLINK</term> <listitem> @@ -6629,7 +6651,8 @@ The variable is used, for example, by <link xmlns="http://www.scons.org/dbxsd/v1 <para xmlns="http://www.scons.org/dbxsd/v1.0"> 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> </listitem> </varlistentry> @@ -6652,7 +6675,8 @@ field in the controlling information for Ipkg and RPM packages. <para xmlns="http://www.scons.org/dbxsd/v1.0"> 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> </listitem> </varlistentry> @@ -6996,7 +7020,8 @@ General options passed to the tar archiver. <para xmlns="http://www.scons.org/dbxsd/v1.0"> 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> </listitem> </varlistentry> @@ -7004,13 +7029,6 @@ that may not be set or used in a construction environment. <term>TARGET_ARCH</term> <listitem> <para xmlns="http://www.scons.org/dbxsd/v1.0"> - The name of the target hardware architecture for the compiled objects - created by this Environment. - This defaults to the value of HOST_ARCH, and the user can override it. - Currently only set for Win32. -</para> - -<para xmlns="http://www.scons.org/dbxsd/v1.0"> Sets the target architecture for Visual Studio compiler (i.e. the arch of the binaries generated by the compiler). If not set, default to <envar xmlns="http://www.scons.org/dbxsd/v1.0">$HOST_ARCH</envar>, or, if that is unset, to the architecture of the @@ -7041,7 +7059,14 @@ and <literal>ia64</literal> (Itanium). For example, if you want to compile 64-bit binaries, you would set <literal>TARGET_ARCH='x86_64'</literal> in your SCons environment. </para> -</listitem> + +<para xmlns="http://www.scons.org/dbxsd/v1.0"> + The name of the target hardware architecture for the compiled objects + created by this Environment. + This defaults to the value of HOST_ARCH, and the user can override it. + Currently only set for Win32. +</para> + </listitem> </varlistentry> <varlistentry id="cv-TARGET_OS"> <term>TARGET_OS</term> @@ -7060,7 +7085,8 @@ For example, if you want to compile 64-bit binaries, you would set <para xmlns="http://www.scons.org/dbxsd/v1.0"> 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> </listitem> </varlistentry> @@ -7193,7 +7219,8 @@ that are part of this construction environment. <para xmlns="http://www.scons.org/dbxsd/v1.0"> 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> </listitem> </varlistentry> @@ -7203,7 +7230,8 @@ that may not be set or used in a construction environment. <para xmlns="http://www.scons.org/dbxsd/v1.0"> 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> </listitem> </varlistentry> diff --git a/doc/generated/variables.mod b/doc/generated/variables.mod index 372a15f..1a5bc97 100644 --- a/doc/generated/variables.mod +++ b/doc/generated/variables.mod @@ -251,6 +251,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY cv-LDMODULE "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LDMODULE</envar>"> <!ENTITY cv-LDMODULECOM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LDMODULECOM</envar>"> <!ENTITY cv-LDMODULECOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LDMODULECOMSTR</envar>"> +<!ENTITY cv-LDMODULEEMITTER "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LDMODULEEMITTER</envar>"> <!ENTITY cv-LDMODULEFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LDMODULEFLAGS</envar>"> <!ENTITY cv-LDMODULENOVERSIONSYMLINKS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LDMODULENOVERSIONSYMLINKS</envar>"> <!ENTITY cv-LDMODULEPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$LDMODULEPREFIX</envar>"> @@ -891,6 +892,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY cv-link-LDMODULE "<link linkend='cv-LDMODULE' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LDMODULE</envar></link>"> <!ENTITY cv-link-LDMODULECOM "<link linkend='cv-LDMODULECOM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LDMODULECOM</envar></link>"> <!ENTITY cv-link-LDMODULECOMSTR "<link linkend='cv-LDMODULECOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LDMODULECOMSTR</envar></link>"> +<!ENTITY cv-link-LDMODULEEMITTER "<link linkend='cv-LDMODULEEMITTER' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LDMODULEEMITTER</envar></link>"> <!ENTITY cv-link-LDMODULEFLAGS "<link linkend='cv-LDMODULEFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LDMODULEFLAGS</envar></link>"> <!ENTITY cv-link-LDMODULENOVERSIONSYMLINKS "<link linkend='cv-LDMODULENOVERSIONSYMLINKS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LDMODULENOVERSIONSYMLINKS</envar></link>"> <!ENTITY cv-link-LDMODULEPREFIX "<link linkend='cv-LDMODULEPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$LDMODULEPREFIX</envar></link>"> diff --git a/doc/man/scons.xml b/doc/man/scons.xml index a9e0dd7..e0f920d 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -686,19 +686,32 @@ option except for the way default targets are handled. When this option is used and no targets are specified on the command line, all default targets are built, whether or not they are below the current directory.</para> - </listitem> </varlistentry> + <varlistentry> - <term>--debug=<emphasis>type</emphasis></term> + <term>--debug=<replaceable>type</replaceable>[<replaceable>,type</replaceable>...]</term> <listitem> <para>Debug the build process. -<emphasis>type[,type...]</emphasis> -specifies what type of debugging. Multiple types may be specified, -separated by commas. The following types are valid:</para> +<emphasis>type</emphasis> +specifies the kind of debugging info to emit. +Multiple types may be specified, separated by commas. +The following entries show the recognized types:</para> + </listitem> + </varlistentry> + <varlistentry> + <term>--debug=action-timestamps</term> + <listitem> +<para>Prints additional time profiling information. For +each command, shows the absolute start and end times. +This may be useful in debugging parallel builds. +Implies the <option>--debug=time</option> option. +</para> +<para>Since &scons; 3.1.</para> </listitem> </varlistentry> + <varlistentry> <term>--debug=count</term> <listitem> @@ -893,40 +906,6 @@ should take place in parallel.) </listitem> </varlistentry> -<varlistentry> - <term>--debug=action_timestamps</term> - <listitem> - <para>Prints additional time profiling information:</para> - <itemizedlist> - <listitem> - <para>The time spent executing each individual build command</para> - </listitem> - <listitem> - <para>The total build time (time SCons ran from beginning to end)</para> - </listitem> - <listitem> - <para>The total time spent reading and executing SConscript files</para> - </listitem> - <listitem> - <para>The total time spent SCons itself spend running -(that is, not counting reading and executing SConscript files)</para> - </listitem> - <listitem> - <para>The total time spent executing all build commands</para> - </listitem> - <listitem> - <para>The elapsed wall-clock time spent executing those build commands</para> - </listitem> - <listitem> - <para>The absolute start and end wall-clock time spent executing those build commands</para> - </listitem> - <listitem> - <para>The time spent processing each file passed to the <emphasis>SConscript()</emphasis> function</para> - </listitem> - </itemizedlist> - </listitem> -</varlistentry> - <varlistentry> <term>--diskcheck=<emphasis>types</emphasis></term> <listitem> @@ -2278,10 +2257,10 @@ env.SomeTool(targets, sources) <refsect2 id='builder_methods'><title>Builder Methods</title> -<para>You tell <program>scons</program> what to build +<para>You tell <command>scons</command> what to build by calling Builders, functions which know to take a particular action when given files of a particular type -to produce a particular result type. <program>scons</program> +to produce a particular result type. <command>scons</command> defines a number of builders, and you can also write your own. Builders are attached to a &consenv; as methods, and the available builder methods are listed as @@ -4960,7 +4939,8 @@ the same target file(s). The default is 0, which means the builder can not be called multiple times for the same target file(s). Calling a builder multiple times for the same target simply adds additional source files to the target; it is not allowed to change the environment associated -with the target, specify addition environment overrides, or associate a different +with the target, specify additional environment overrides, +or associate a different builder with the target.</para> </listitem> diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index d129d2e..d8f9fff 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -2,7 +2,7 @@ <!DOCTYPE sconsdoc [ <!ENTITY % scons SYSTEM "../scons.mod"> %scons; - + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> %builders-mod; <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> @@ -89,7 +89,7 @@ all of the command-line variable settings, the ability to apply command-line variable settings to construction environments, - and functions for configuring + and functions for configuring specific types of variables (Boolean values, path names, etc.) with automatic validation of the user's specified values. @@ -599,24 +599,30 @@ foo.in &SCons; also allows you to define your own command-line options with the &AddOption; function. The &AddOption; function takes the same arguments - as the <function>optparse.add_option</function> function - from the standard Python library. + as the <function>add_option</function> method + from the standard Python library module <emphasis>optparse</emphasis>. <footnote> <para> The &AddOption; function is, in fact, implemented using a subclass - of the <classname>optparse.OptionParser</classname>. + of <classname>optparse.OptionParser</classname>. </para> </footnote> + </para> + + <para> Once you have added a custom command-line option with the &AddOption; function, the value of the option (if any) is immediately available using the standard &GetOption; function. + <!-- (The value can also be set using &SetOption;, although that's not very useful in practice because a default value can be specified in directly in the &AddOption; call.) - + --> + &SetOption; is not currently supported for + options added with &AddOption;. </para> <para> @@ -678,6 +684,47 @@ foo.in <scons_output_command>scons -Q -n --prefix=/tmp/install</scons_output_command> </scons_output> + <note> + <para> + Option-arguments separated from long options by whitespace, + rather than by an <literal>=</literal>, cannot be correctly + resolved by <command>scons</command>. + While <literal>--input=ARG</literal> + is clearly opt followed by arg, for <literal>--input ARG</literal> + it is not possible to tell without instructions whether + <parameter>ARG</parameter> is an argument belonging to the + <parameter>input</parameter> option or a positional argument. + <command>scons</command> treats positional arguments as either + command-line build options or command-line targets + which are made available for use in an &SConscript; + (see the immediately following sections for details). + Thus, they must be collected before &SConscript; processing + takes place. Since &AddOption; calls, which provide + the processing instructions to resolve any ambiguity, + happen in an &SConscript;, + <command>scons</command> does not know in time + for options added this way, and unexpected things will happen, + such as option-arguments assigned as targets and/or exceptions + due to missing option-arguments. + </para> + <para> + As a result, this usage style should be avoided when invoking + <command>scons</command>. For single-argument + options, use the <literal>--input=ARG</literal> form on the + command line. For multiple-argument options + (<parameter>nargs</parameter> greater than one), + set <parameter>nargs</parameter> to one in + &AddOption; calls and either: combine the option-arguments into one word + with a separator, and parse the result in your own code + (see the built-in <parameter>--debug</parameter> option, which + allows specifying multiple arguments as a single comma-separated + word, for an example of such usage); or allow the option to + be specified multiple times by setting + <literal>action='append'</literal>. Both methods can be + supported at the same time. + </para> + </note> + </section> </section> @@ -1132,12 +1179,12 @@ vars = Variables('custom.py', ARGUMENTS) </screen> <para> - + where values in the option file &custom_py; get overwritten by the ones specified on the command line. </para> - + </section> <section> diff --git a/doc/user/depends.xml b/doc/user/depends.xml index 5a78eb5..cd5094a 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -764,6 +764,7 @@ int main() { printf("Hello, world!\n"); } encounter them in older &SConscript; files. </para> + </section> <section> <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> diff --git a/src/CHANGES.txt b/src/CHANGES.txt index af448d5..47b63ee 100755 --- a/src/CHANGES.txt +++ b/src/CHANGES.txt @@ -4,10 +4,45 @@ Change Log +NOTE: Please add your name below (and your changes) alphabetically by last name. + RELEASE VERSION/DATE TO BE FILLED IN LATER - From Mathew Robinson: + From Edoardo Bezzeccheri + - Added debug option "action_timestamps" which outputs to stdout the absolute start and end time for each target. + + From Rob Boehne + - Fix suncxx tool (Oracle Studio compiler) when using Python 3. Previously would throw an exception. + Resolved by properly handling tool version string output as unicode. + + From Tim Gates + - Resolved a typo in engine.SCons.Tool + + From Adam Gross: + - Resolved a race condition in multithreaded Windows builds with Python 2 + in the case where a child process is spawned while a Python action has a + file open. Original author: Ryan Beasley. + + From Jason Kenny + - Update Command() function to accept target_scanner, source_factory, and target_factory arguments. + This makes Command act more like a one-off builder. + + From Ivan Kravets + - Added support for "-imacros" to ParseFlags + + From Jacek Kuczera: + - Fix CheckFunc detection code for Visual 2019. Some functions + (e.g. memmove) were incorrectly recognized as not available. + + From Jakub Kulik + - Fix subprocess result bytes not being decoded in SunOS/Solaris related tools. + From Philipp Maierhöfer: + - Avoid crash with UnicodeDecodeError on Python 3 when a Latex log file in + non-UTF-8 encoding (e.g. containing umlauts in Latin-1 encoding when + the fontenc package is included with \usepackage[T1]{fontenc}) is read. + + From Mathew Robinson: - Improved threading performance by ensuring NodeInfo is shared across threads. Results in ~13% improvement for parallel builds (-j# > 1) with many shared nodes. @@ -25,16 +60,8 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER On vs2019 saves 5+ seconds per SCons invocation, which really helps test suite runs. - Remove deprecated SourceSignatures, TargetSignatures + - Remove deprecated Builder keywords: overrides and scanner - From Jacek Kuczera: - - Fix CheckFunc detection code for Visual 2019. Some functions - (e.g. memmove) were incorrectly recognized as not available. - - From Jakub Kulik - - Fix subprocess result bytes not being decoded in SunOS/Solaris related tools. - - From Edoardo Bezzeccheri - - Added debug option "action_timestamps" which outputs to stdout the absolute start and end time for each target. RELEASE 3.1.1 - Mon, 07 Aug 2019 20:09:12 -0500 diff --git a/src/engine/SCons/Builder.py b/src/engine/SCons/Builder.py index 4352d7a..e3fb396 100644 --- a/src/engine/SCons/Builder.py +++ b/src/engine/SCons/Builder.py @@ -396,16 +396,13 @@ class BuilderBase(object): self.env = env self.single_source = single_source if 'overrides' in overrides: - SCons.Warnings.warn(SCons.Warnings.DeprecatedBuilderKeywordsWarning, - "The \"overrides\" keyword to Builder() creation has been deprecated;\n" +\ - "\tspecify the items as keyword arguments to the Builder() call instead.") - overrides.update(overrides['overrides']) - del overrides['overrides'] + msg = "The \"overrides\" keyword to Builder() creation has been removed;\n" +\ + "\tspecify the items as keyword arguments to the Builder() call instead." + raise TypeError(msg) if 'scanner' in overrides: - SCons.Warnings.warn(SCons.Warnings.DeprecatedBuilderKeywordsWarning, - "The \"scanner\" keyword to Builder() creation has been deprecated;\n" - "\tuse: source_scanner or target_scanner as appropriate.") - del overrides['scanner'] + msg = "The \"scanner\" keyword to Builder() creation has been removed;\n" +\ + "\tuse: source_scanner or target_scanner as appropriate." + raise TypeError(msg) self.overrides = overrides self.set_suffix(suffix) diff --git a/src/engine/SCons/Environment.py b/src/engine/SCons/Environment.py index 0e1102e..916ebc4 100644 --- a/src/engine/SCons/Environment.py +++ b/src/engine/SCons/Environment.py @@ -702,31 +702,34 @@ class SubstitutionEnvironment(object): append_next_arg_to = None # for multi-word args for arg in params: if append_next_arg_to: - if append_next_arg_to == 'CPPDEFINES': - append_define(arg) - elif append_next_arg_to == '-include': - t = ('-include', self.fs.File(arg)) - dict['CCFLAGS'].append(t) - elif append_next_arg_to == '-isysroot': - t = ('-isysroot', arg) - dict['CCFLAGS'].append(t) - dict['LINKFLAGS'].append(t) - elif append_next_arg_to == '-isystem': - t = ('-isystem', arg) - dict['CCFLAGS'].append(t) - elif append_next_arg_to == '-iquote': - t = ('-iquote', arg) - dict['CCFLAGS'].append(t) - elif append_next_arg_to == '-idirafter': - t = ('-idirafter', arg) - dict['CCFLAGS'].append(t) - elif append_next_arg_to == '-arch': - t = ('-arch', arg) - dict['CCFLAGS'].append(t) - dict['LINKFLAGS'].append(t) - else: - dict[append_next_arg_to].append(arg) - append_next_arg_to = None + if append_next_arg_to == 'CPPDEFINES': + append_define(arg) + elif append_next_arg_to == '-include': + t = ('-include', self.fs.File(arg)) + dict['CCFLAGS'].append(t) + elif append_next_arg_to == '-imacros': + t = ('-imacros', self.fs.File(arg)) + dict['CCFLAGS'].append(t) + elif append_next_arg_to == '-isysroot': + t = ('-isysroot', arg) + dict['CCFLAGS'].append(t) + dict['LINKFLAGS'].append(t) + elif append_next_arg_to == '-isystem': + t = ('-isystem', arg) + dict['CCFLAGS'].append(t) + elif append_next_arg_to == '-iquote': + t = ('-iquote', arg) + dict['CCFLAGS'].append(t) + elif append_next_arg_to == '-idirafter': + t = ('-idirafter', arg) + dict['CCFLAGS'].append(t) + elif append_next_arg_to == '-arch': + t = ('-arch', arg) + dict['CCFLAGS'].append(t) + dict['LINKFLAGS'].append(t) + else: + dict[append_next_arg_to].append(arg) + append_next_arg_to = None elif not arg[0] in ['-', '+']: dict['LIBS'].append(self.fs.File(arg)) elif arg == '-dylib_file': @@ -793,7 +796,7 @@ class SubstitutionEnvironment(object): elif arg[0] == '+': dict['CCFLAGS'].append(arg) dict['LINKFLAGS'].append(arg) - elif arg in ['-include', '-isysroot', '-isystem', '-iquote', '-idirafter', '-arch']: + elif arg in ['-include', '-imacros', '-isysroot', '-isystem', '-iquote', '-idirafter', '-arch']: append_next_arg_to = arg else: dict['CCFLAGS'].append(arg) @@ -1980,13 +1983,42 @@ class Base(SubstitutionEnvironment): be any type that the Builder constructor will accept for an action.""" bkw = { - 'action' : action, - 'target_factory' : self.fs.Entry, - 'source_factory' : self.fs.Entry, + 'action': action, + 'target_factory': self.fs.Entry, + 'source_factory': self.fs.Entry, } - try: bkw['source_scanner'] = kw['source_scanner'] - except KeyError: pass - else: del kw['source_scanner'] + # source scanner + try: + bkw['source_scanner'] = kw['source_scanner'] + except KeyError: + pass + else: + del kw['source_scanner'] + + # target scanner + try: + bkw['target_scanner'] = kw['target_scanner'] + except KeyError: + pass + else: + del kw['target_scanner'] + + # source factory + try: + bkw['source_factory'] = kw['source_factory'] + except KeyError: + pass + else: + del kw['source_factory'] + + # target factory + try: + bkw['target_factory'] = kw['target_factory'] + except KeyError: + pass + else: + del kw['target_factory'] + bld = SCons.Builder.Builder(**bkw) return bld(self, target, source, **kw) diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml index 829bf12..48cf3ae 100644 --- a/src/engine/SCons/Environment.xml +++ b/src/engine/SCons/Environment.xml @@ -937,19 +937,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> @@ -2324,6 +2334,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 diff --git a/src/engine/SCons/EnvironmentTests.py b/src/engine/SCons/EnvironmentTests.py index f016f22..0957361 100644 --- a/src/engine/SCons/EnvironmentTests.py +++ b/src/engine/SCons/EnvironmentTests.py @@ -804,6 +804,7 @@ sys.exit(0) "-iquote /usr/include/foo1 " + \ "-isystem /usr/include/foo2 " + \ "-idirafter /usr/include/foo3 " + \ + "-imacros /usr/include/foo4 " + \ "+DD64 " + \ "-DFOO -DBAR=value -D BAZ " @@ -818,6 +819,7 @@ sys.exit(0) ('-iquote', '/usr/include/foo1'), ('-isystem', '/usr/include/foo2'), ('-idirafter', '/usr/include/foo3'), + ('-imacros', env.fs.File('/usr/include/foo4')), '+DD64'], repr(d['CCFLAGS']) assert d['CXXFLAGS'] == ['-std=c++0x'], repr(d['CXXFLAGS']) assert d['CPPDEFINES'] == ['FOO', ['BAR', 'value'], 'BAZ'], d['CPPDEFINES'] diff --git a/src/engine/SCons/Platform/win32.py b/src/engine/SCons/Platform/win32.py index 0a3b199..77c048e 100644 --- a/src/engine/SCons/Platform/win32.py +++ b/src/engine/SCons/Platform/win32.py @@ -51,10 +51,6 @@ try: import msvcrt import win32api import win32con - - msvcrt.get_osfhandle - win32api.SetHandleInformation - win32con.HANDLE_FLAG_INHERIT except ImportError: parallel_msg = \ "you do not seem to have the pywin32 extensions installed;\n" + \ @@ -66,28 +62,44 @@ except AttributeError: else: parallel_msg = None - _builtin_open = open + if sys.version_info.major == 2: + import __builtin__ + + _builtin_file = __builtin__.file + _builtin_open = __builtin__.open + + def _scons_fixup_mode(mode): + """Adjust 'mode' to mark handle as non-inheritable. + + SCons is multithreaded, so allowing handles to be inherited by + children opens us up to races, where (e.g.) processes spawned by + the Taskmaster may inherit and retain references to files opened + by other threads. This may lead to sharing violations and, + ultimately, build failures. + + By including 'N' as part of fopen's 'mode' parameter, all file + handles returned from these functions are atomically marked as + non-inheritable. + """ + if not mode: + # Python's default is 'r'. + # https://docs.python.org/2/library/functions.html#open + mode = 'rN' + elif 'N' not in mode: + mode += 'N' + return mode - def _scons_open(*args, **kw): - fp = _builtin_open(*args, **kw) - win32api.SetHandleInformation(msvcrt.get_osfhandle(fp.fileno()), - win32con.HANDLE_FLAG_INHERIT, - 0) - return fp + class _scons_file(_builtin_file): + def __init__(self, name, mode=None, *args, **kwargs): + _builtin_file.__init__(self, name, _scons_fixup_mode(mode), + *args, **kwargs) - open = _scons_open + def _scons_open(name, mode=None, *args, **kwargs): + return _builtin_open(name, _scons_fixup_mode(mode), + *args, **kwargs) - if sys.version_info.major == 2: - _builtin_file = file - class _scons_file(_builtin_file): - def __init__(self, *args, **kw): - _builtin_file.__init__(self, *args, **kw) - win32api.SetHandleInformation(msvcrt.get_osfhandle(self.fileno()), - win32con.HANDLE_FLAG_INHERIT, 0) - file = _scons_file - else: - # No longer needed for python 3.4 and above. Files are opened non sharable - pass + __builtin__.file = _scons_file + __builtin__.open = _scons_open diff --git a/src/engine/SCons/SConfTests.py b/src/engine/SCons/SConfTests.py index f770450..787138e 100644 --- a/src/engine/SCons/SConfTests.py +++ b/src/engine/SCons/SConfTests.py @@ -56,6 +56,18 @@ class SConfTestCase(unittest.TestCase): os.chdir(self.save_cwd) def _resetSConfState(self): + if sys.platform in ['cygwin', 'win32'] and sys.version_info.major == 2: + # On Windows with Python2, SCons.Platform.win32 redefines the + # built-in file() and open() functions to disable handle + # inheritance. Because we are unloading all SCons modules other + # than SCons.Compat, SCons.Platform.win32 will lose the variables + # it needs. As a result, we should reset the file() and open() + # functions to their original built-in versions. + import __builtin__ + import SCons.Platform.win32 + __builtin__.file = SCons.Platform.win32._builtin_file + __builtin__.open = SCons.Platform.win32._builtin_open + # Ok, this is tricky, and i do not know, if everything is sane. # We try to reset scons' state (including all global variables) import SCons.SConsign @@ -90,22 +102,6 @@ class SConfTestCase(unittest.TestCase): global existing_lib existing_lib = 'm' - if sys.platform in ['cygwin', 'win32']: - # On Windows, SCons.Platform.win32 redefines the builtin - # file() and open() functions to close the file handles. - # This interferes with the unittest.py infrastructure in - # some way. Just sidestep the issue by restoring the - # original builtin functions whenever we have to reset - # all of our global state. - - import SCons.Platform.win32 - - try: - file = SCons.Platform.win32._builtin_file - open = SCons.Platform.win32._builtin_open - except AttributeError: - pass - def _baseTryXXX(self, TryFunc): # TryCompile and TryLink are much the same, so we can test them # in one method, we pass the function as a string ('TryCompile', diff --git a/src/engine/SCons/Script/Main.py b/src/engine/SCons/Script/Main.py index 58dbf64..238a828 100644 --- a/src/engine/SCons/Script/Main.py +++ b/src/engine/SCons/Script/Main.py @@ -211,10 +211,9 @@ class BuildTask(SCons.Taskmaster.OutOfDateTask): last_command_end = finish_time cumulative_command_time = cumulative_command_time+finish_time-start_time if print_action_timestamps: - sys.stdout.write("Command execution start time: %s: %f seconds\n"%(str(self.node), start_time)) + sys.stdout.write("Command execution start timestamp: %s: %f\n"%(str(self.node), start_time)) + sys.stdout.write("Command execution end timestamp: %s: %f\n"%(str(self.node), finish_time)) sys.stdout.write("Command execution time: %s: %f seconds\n"%(str(self.node), finish_time-start_time)) - if print_action_timestamps: - sys.stdout.write("Command execution stop time: %s: %f seconds\n"%(str(self.node), finish_time)) def do_failed(self, status=2): _BuildFailures.append(self.exception[1]) @@ -679,7 +678,7 @@ def _set_debug_values(options): options.tree_printers.append(TreePrinter(status=True)) if "time" in debug_values: print_time = 1 - if "action_timestamps" in debug_values: + if "action-timestamps" in debug_values: print_time = 1 print_action_timestamps = 1 if "tree" in debug_values: diff --git a/src/engine/SCons/Script/Main.xml b/src/engine/SCons/Script/Main.xml index e95afbc..f518422 100644 --- a/src/engine/SCons/Script/Main.xml +++ b/src/engine/SCons/Script/Main.xml @@ -33,11 +33,11 @@ See its __doc__ string for a discussion of the format. This function adds a new command-line option to be recognized. The specified <varname>arguments</varname> -are the same as supported by the standard Python -<function>optparse.add_option</function>() -method (with a few additional capabilities noted below); +are the same as supported by the <function>add_option</function> +method in the standard Python library module <emphasis>optparse</emphasis>, +with a few additional capabilities noted below; see the documentation for -<literal>optparse</literal> +<emphasis>optparse</emphasis> for a thorough discussion of its option-processing capabities. </para> @@ -78,12 +78,22 @@ the option will have a default value of </para> <para> +Unlike regular <emphasis>optparse</emphasis>, option names +added via <function>AddOption</function> must be matched +exactly, the automatic matching of abbreviations on the +command line for long options is not supported. +To allow specific abbreviations, +include them in the &f-AddOption; call. +</para> + +<para> Once a new command-line option has been added with &f-AddOption;, the option value may be accessed using &f-GetOption; or <function>env.GetOption</function>(). +<!-- The value may also be set, using &f-SetOption; or @@ -95,6 +105,9 @@ Note, however, that a value specified on the command line will <emphasis>always</emphasis> override a value set by any SConscript file. +--> +&f-SetOption; is not currently supported for +options added with &f-AddOption;. </para> <para> @@ -133,6 +146,22 @@ AddOption('--prefix', help='installation prefix') env = Environment(PREFIX = GetOption('prefix')) </example_commands> + +<note> +<para> +While &AddOption; behaves like +<function>add_option</function>, +from the <emphasis>optparse</emphasis> module, +the behavior of options added by &AddOption; +which take arguments is underfined in +<command>scons</command> if whitespace +(rather than an <literal>=</literal> sign) is used as +the separator on the command line when +the option is invoked. +Such usage should be avoided. +</para> +</note> + </summary> </scons_function> diff --git a/src/engine/SCons/Script/SConsOptions.py b/src/engine/SCons/Script/SConsOptions.py index 7b5d523..66c7239 100644 --- a/src/engine/SCons/Script/SConsOptions.py +++ b/src/engine/SCons/Script/SConsOptions.py @@ -622,7 +622,7 @@ def Parser(version): debug_options = ["count", "duplicate", "explain", "findlibs", "includes", "memoizer", "memory", "objects", "pdb", "prepare", "presub", "stacktrace", - "time", "action_timestamps"] + "time", "action-timestamps"] def opt_debug(option, opt, value__, parser, debug_options=debug_options, diff --git a/src/engine/SCons/Tool/__init__.py b/src/engine/SCons/Tool/__init__.py index c8fb389..f255b21 100644 --- a/src/engine/SCons/Tool/__init__.py +++ b/src/engine/SCons/Tool/__init__.py @@ -99,7 +99,7 @@ for suffix in LaTeXSuffixes: SourceFileScanner.add_scanner(suffix, LaTeXScanner) SourceFileScanner.add_scanner(suffix, PDFLaTeXScanner) -# Tool aliases are needed for those tools whos module names also +# Tool aliases are needed for those tools whose module names also # occur in the python standard library. This causes module shadowing and # can break using python library functions under python3 TOOL_ALIASES = { diff --git a/src/engine/SCons/Tool/intelc.py b/src/engine/SCons/Tool/intelc.py index 1f3fcea..7550c34 100644 --- a/src/engine/SCons/Tool/intelc.py +++ b/src/engine/SCons/Tool/intelc.py @@ -387,7 +387,7 @@ def get_intel_compiler_top(version, abi): def generate(env, version=None, abi=None, topdir=None, verbose=0): - """Add Builders and construction variables for Intel C/C++ compiler + r"""Add Builders and construction variables for Intel C/C++ compiler to an Environment. args: version: (string) compiler version to use, like "80" @@ -551,7 +551,7 @@ def generate(env, version=None, abi=None, topdir=None, verbose=0): # Look for license file dir # in system environment, registry, and default location. envlicdir = os.environ.get("INTEL_LICENSE_FILE", '') - K = ('SOFTWARE\Intel\Licenses') + K = r'SOFTWARE\Intel\Licenses' try: k = SCons.Util.RegOpenKeyEx(SCons.Util.HKEY_LOCAL_MACHINE, K) reglicdir = SCons.Util.RegQueryValueEx(k, "w_cpp")[0] diff --git a/src/engine/SCons/Tool/packaging/msi.py b/src/engine/SCons/Tool/packaging/msi.py index 0ef18ec..34e4f0f 100644 --- a/src/engine/SCons/Tool/packaging/msi.py +++ b/src/engine/SCons/Tool/packaging/msi.py @@ -224,7 +224,7 @@ def build_wxsfile(target, source, env): # setup function # def create_default_directory_layout(root, NAME, VERSION, VENDOR, filename_set): - """ Create the wix default target directory layout and return the innermost + r""" Create the wix default target directory layout and return the innermost directory. We assume that the XML tree delivered in the root argument already contains diff --git a/src/engine/SCons/Tool/suncxx.py b/src/engine/SCons/Tool/suncxx.py index 090df7d..c155484 100644 --- a/src/engine/SCons/Tool/suncxx.py +++ b/src/engine/SCons/Tool/suncxx.py @@ -39,12 +39,14 @@ import os import re import subprocess +from SCons.Util import PY3 import SCons.Tool.cxx cplusplus = SCons.Tool.cxx -#cplusplus = __import__('c++', globals(), locals(), []) +# cplusplus = __import__('c++', globals(), locals(), []) package_info = {} + def get_package_info(package_name, pkginfo, pkgchk): try: return package_info[package_name] @@ -52,7 +54,7 @@ def get_package_info(package_name, pkginfo, pkgchk): version = None pathname = None try: - from subprocess import DEVNULL # py3k + from subprocess import DEVNULL # py3k except ImportError: DEVNULL = open(os.devnull, 'wb') @@ -68,13 +70,18 @@ def get_package_info(package_name, pkginfo, pkgchk): pathname = os.path.dirname(sadm_match.group(1)) try: + popen_args = {'stdout': subprocess.PIPE, + 'stderr': DEVNULL} + if PY3: + popen_args['universal_newlines'] = True p = subprocess.Popen([pkginfo, '-l', package_name], - stdout=subprocess.PIPE, - stderr=DEVNULL) + **popen_args) except EnvironmentError: pass else: - pkginfo_contents = p.communicate()[0].decode() + pkginfo_contents = p.communicate()[0] + if not PY3: + pkginfo_contents.decode() version_re = re.compile(r'^ *VERSION:\s*(.*)$', re.M) version_match = version_re.search(pkginfo_contents) if version_match: @@ -82,13 +89,18 @@ def get_package_info(package_name, pkginfo, pkgchk): if pathname is None: try: + popen_args = {'stdout': subprocess.PIPE, + 'stderr': DEVNULL} + if PY3: + popen_args['universal_newlines'] = True p = subprocess.Popen([pkgchk, '-l', package_name], - stdout=subprocess.PIPE, - stderr=DEVNULL) + **popen_args) except EnvironmentError: pass else: - pkgchk_contents = p.communicate()[0].decode() + pkgchk_contents = p.communicate()[0] + if not PY3: + pkgchk_contents.decode() pathname_re = re.compile(r'^Pathname:\s*(.*/bin/CC)$', re.M) pathname_match = pathname_re.search(pkgchk_contents) if pathname_match: @@ -97,7 +109,8 @@ def get_package_info(package_name, pkginfo, pkgchk): package_info[package_name] = (pathname, version) return package_info[package_name] -# use the package installer tool lslpp to figure out where cppc and what + +# use the package installer tool "pkg" to figure out where cppc and what # version of it is installed def get_cppc(env): cxx = env.subst('$CXX') @@ -119,6 +132,7 @@ def get_cppc(env): return (cppcPath, 'CC', 'CC', cppcVersion) + def generate(env): """Add Builders and construction variables for SunPRO C++.""" path, cxx, shcxx, version = get_cppc(env) @@ -131,10 +145,11 @@ def generate(env): env['CXX'] = cxx env['SHCXX'] = shcxx env['CXXVERSION'] = version - env['SHCXXFLAGS'] = SCons.Util.CLVar('$CXXFLAGS -KPIC') - env['SHOBJPREFIX'] = 'so_' - env['SHOBJSUFFIX'] = '.o' - + env['SHCXXFLAGS'] = SCons.Util.CLVar('$CXXFLAGS -KPIC') + env['SHOBJPREFIX'] = 'so_' + env['SHOBJSUFFIX'] = '.o' + + def exists(env): path, cxx, shcxx, version = get_cppc(env) if path and cxx: diff --git a/src/engine/SCons/Tool/tex.py b/src/engine/SCons/Tool/tex.py index 64b9d3b..5cf7bca 100644 --- a/src/engine/SCons/Tool/tex.py +++ b/src/engine/SCons/Tool/tex.py @@ -297,8 +297,8 @@ def InternalLaTeXAuxAction(XXXLaTeXAction, target = None, source= None, env=None logfilename = targetbase + '.log' logContent = '' if os.path.isfile(logfilename): - with open(logfilename, "r") as f: - logContent = f.read() + with open(logfilename, "rb") as f: + logContent = f.read().decode(errors='replace') # Read the fls file to find all .aux files diff --git a/test/Command.py b/test/Command.py index 09a8daa..d8ca86d 100644 --- a/test/Command.py +++ b/test/Command.py @@ -21,7 +21,6 @@ # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # - __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" import TestSCons @@ -43,7 +42,9 @@ test.write('build.py', build_py) test.write(['expand_chdir_sub', 'subbuild.py'], build_py) test.write('SConstruct', """ +from __future__ import print_function import os +import sys def buildIt(env, target, source): with open(str(target[0]), 'w') as f, open(str(source[0]), 'r') as infp: @@ -62,6 +63,18 @@ def sub(env, target, source): t.write(s.read()) return 0 +def source_scanner(node, env, path, builder): + print("Source scanner node=", node, "builder =", builder,file=sys.stderr) + return [] + +def target_scanner(node, env, path, builder): + print("Target scanner node=", node, "builder =", builder,file=sys.stderr) + return [] + +def factory(node,*lst,**kw): + print("factory called on:",node,file=sys.stderr) + return env.File(node) + env = Environment(COPY_THROUGH_TEMP = r'%(_python_)s build.py .tmp $SOURCE' + '\\n' + r'%(_python_)s build.py $TARGET .tmp', EXPAND = '$COPY_THROUGH_TEMP') env.Command(target = 'f1.out', source = 'f1.in', @@ -82,6 +95,19 @@ env.Command(target = 'f7.out', source = 'f7.in', action = r'%(_python_)s build.py $TARGET $SOURCE') Command(target = 'f8.out', source = 'f8.in', action = r'%(_python_)s build.py $TARGET $SOURCE') +env.Command(target = 'f7s.out', source = 'f7.in', + action = r'%(_python_)s build.py $TARGET $SOURCE', + target_scanner=Scanner(lambda node, env, path: target_scanner(node, env, path, "w-env")), + source_scanner=Scanner(lambda node, env, path: source_scanner(node, env, path, "w-env"))) +Command(target = 'f8s.out', source = 'f8.in', + action = r'%(_python_)s build.py $TARGET $SOURCE', + target_scanner=Scanner(lambda node, env, path: target_scanner(node, env, path, "wo-env")), + source_scanner=Scanner(lambda node, env, path: source_scanner(node, env, path, "wo-env"))) +Command(target = 'f8f.out', source = 'f8.in', + action = r'%(_python_)s build.py $TARGET $SOURCE', + target_factory=factory, + source_factory=factory + ) env.Command(target = 'f9.out', source = 'f9.in', action = r'$EXPAND') env.Command(target = '${F10}.out', source = '${F10}.in', @@ -108,7 +134,18 @@ test.write('f9.in', "f9.in\n") test.write('f10.in', "f10.in\n") test.write(['expand_chdir_sub', 'f11.in'], "expand_chdir_sub/f11.in\n") -test.run(arguments = '.') +test_str = r'''factory called on: f8.in +factory called on: f8f.out +Source scanner node= f7.in builder = w-env +Target scanner node= f7s.out builder = w-env +Source scanner node= f8.in builder = wo-env +Target scanner node= f8s.out builder = wo-env +''' + +out = test.run(arguments='.', + stderr=test_str, + match=TestSCons.match_re_dotall) + test.must_match('f1.out', "f1.in\n", mode='r') test.must_match('f2.out', "f2.in\n", mode='r') @@ -118,9 +155,12 @@ test.must_match('f5.out', "XYZZY is set\nf5.in\n", mode='r') test.must_match('f6.out', "f6.in\n", mode='r') test.must_match('f7.out', "f7.in\n", mode='r') test.must_match('f8.out', "f8.in\n", mode='r') +test.must_match('f7s.out', "f7.in\n", mode='r') +test.must_match('f8s.out', "f8.in\n", mode='r') test.must_match('f9.out', "f9.in\n", mode='r') test.must_match('f10.out', "f10.in\n", mode='r') -test.must_match(['expand_chdir_sub', 'f11.out'], "expand_chdir_sub/f11.in\n", mode='r') +test.must_match(['expand_chdir_sub', 'f11.out'], + "expand_chdir_sub/f11.in\n", mode='r') test.pass_test() diff --git a/test/GetBuildFailures/option-k.py b/test/GetBuildFailures/option-k.py index 92a9db8..039ad50 100644 --- a/test/GetBuildFailures/option-k.py +++ b/test/GetBuildFailures/option-k.py @@ -45,11 +45,11 @@ test = TestSCons.TestSCons() contents = r"""\ import sys -if sys.argv[0] == 'mypass.py': +if 'mypass.py' in sys.argv[0]: with open(sys.argv[3], 'wb') as ofp, open(sys.argv[4], 'rb') as ifp: ofp.write(ifp.read()) exit_value = 0 -elif sys.argv[0] == 'myfail.py': +elif 'myfail.py' in sys.argv[0]: exit_value = 1 sys.exit(exit_value) """ diff --git a/test/GetBuildFailures/parallel.py b/test/GetBuildFailures/parallel.py index 5387e4a..63125ad 100644 --- a/test/GetBuildFailures/parallel.py +++ b/test/GetBuildFailures/parallel.py @@ -59,11 +59,11 @@ write_marker = sys.argv[2] + '.marker' if wait_marker != '-.marker': while not os.path.exists(wait_marker): time.sleep(1) -if sys.argv[0] == 'mypass.py': +if 'mypass.py' in sys.argv[0]: with open(sys.argv[3], 'wb') as ofp, open(sys.argv[4], 'rb') as ifp: ofp.write(ifp.read()) exit_value = 0 -elif sys.argv[0] == 'myfail.py': +elif 'myfail.py' in sys.argv[0]: exit_value = 1 if write_marker != '-.marker': os.mkdir(write_marker) diff --git a/test/GetBuildFailures/serial.py b/test/GetBuildFailures/serial.py index 7557dd5..4aecc12 100644 --- a/test/GetBuildFailures/serial.py +++ b/test/GetBuildFailures/serial.py @@ -48,11 +48,11 @@ test = TestSCons.TestSCons() contents = r"""\ import sys -if sys.argv[0] == 'mypass.py': +if 'mypass.py' in sys.argv[0]: with open(sys.argv[3], 'wb') as ofp, open(sys.argv[4], 'rb') as ifp: ofp.write(ifp.read()) exit_value = 0 -elif sys.argv[0] == 'myfail.py': +elif 'myfail.py' in sys.argv[0]: exit_value = 1 sys.exit(exit_value) """ diff --git a/test/Rpcgen/RPCGEN.py b/test/Rpcgen/RPCGEN.py index eaa4e16..86cdd71 100644 --- a/test/Rpcgen/RPCGEN.py +++ b/test/Rpcgen/RPCGEN.py @@ -69,10 +69,10 @@ expect_h = output % ('-h', test.workpath('rpcif.h')) expect_svc = output % ('-m', test.workpath('rpcif_svc.c')) expect_xdr = output % ('-c', test.workpath('rpcif_xdr.c')) -test.must_match('rpcif_clnt.c', expect_clnt, mode='r') -test.must_match('rpcif.h', expect_h, mode='r') -test.must_match('rpcif_svc.c', expect_svc, mode='r') -test.must_match('rpcif_xdr.c', expect_xdr, mode='r') +test.must_contain('rpcif_clnt.c', expect_clnt, mode='r') +test.must_contain('rpcif.h', expect_h, mode='r') +test.must_contain('rpcif_svc.c', expect_svc, mode='r') +test.must_contain('rpcif_xdr.c', expect_xdr, mode='r') diff --git a/test/Rpcgen/RPCGENCLIENTFLAGS.py b/test/Rpcgen/RPCGENCLIENTFLAGS.py index a298ebd..1143227 100644 --- a/test/Rpcgen/RPCGENCLIENTFLAGS.py +++ b/test/Rpcgen/RPCGENCLIENTFLAGS.py @@ -72,10 +72,10 @@ expect_h = output % ('-h', test.workpath('rpcif.h')) expect_svc = output % ('-m', test.workpath('rpcif_svc.c')) expect_xdr = output % ('-c', test.workpath('rpcif_xdr.c')) -test.must_match('rpcif_clnt.c', expect_clnt, mode='r') -test.must_match('rpcif.h', expect_h, mode='r') -test.must_match('rpcif_svc.c', expect_svc, mode='r') -test.must_match('rpcif_xdr.c', expect_xdr, mode='r') +test.must_contain('rpcif_clnt.c', expect_clnt, mode='r') +test.must_contain('rpcif.h', expect_h, mode='r') +test.must_contain('rpcif_svc.c', expect_svc, mode='r') +test.must_contain('rpcif_xdr.c', expect_xdr, mode='r') diff --git a/test/Rpcgen/RPCGENFLAGS.py b/test/Rpcgen/RPCGENFLAGS.py index c254ed0..3673a23 100644 --- a/test/Rpcgen/RPCGENFLAGS.py +++ b/test/Rpcgen/RPCGENFLAGS.py @@ -71,10 +71,10 @@ expect_h = output % ('-h', test.workpath('rpcif.h')) expect_svc = output % ('-m', test.workpath('rpcif_svc.c')) expect_xdr = output % ('-c', test.workpath('rpcif_xdr.c')) -test.must_match('rpcif_clnt.c', expect_clnt, mode='r') -test.must_match('rpcif.h', expect_h, mode='r') -test.must_match('rpcif_svc.c', expect_svc, mode='r') -test.must_match('rpcif_xdr.c', expect_xdr, mode='r') +test.must_contain('rpcif_clnt.c', expect_clnt, mode='r') +test.must_contain('rpcif.h', expect_h, mode='r') +test.must_contain('rpcif_svc.c', expect_svc, mode='r') +test.must_contain('rpcif_xdr.c', expect_xdr, mode='r') diff --git a/test/Rpcgen/RPCGENHEADERFLAGS.py b/test/Rpcgen/RPCGENHEADERFLAGS.py index 8e40ad7..6223ba3 100644 --- a/test/Rpcgen/RPCGENHEADERFLAGS.py +++ b/test/Rpcgen/RPCGENHEADERFLAGS.py @@ -72,10 +72,10 @@ expect_h = output_h % ('-h', test.workpath('rpcif.h')) expect_svc = output % ('-m', test.workpath('rpcif_svc.c')) expect_xdr = output % ('-c', test.workpath('rpcif_xdr.c')) -test.must_match('rpcif_clnt.c', expect_clnt, mode='r') -test.must_match('rpcif.h', expect_h, mode='r') -test.must_match('rpcif_svc.c', expect_svc, mode='r') -test.must_match('rpcif_xdr.c', expect_xdr, mode='r') +test.must_contain('rpcif_clnt.c', expect_clnt, mode='r') +test.must_contain('rpcif.h', expect_h, mode='r') +test.must_contain('rpcif_svc.c', expect_svc, mode='r') +test.must_contain('rpcif_xdr.c', expect_xdr, mode='r') diff --git a/test/Rpcgen/RPCGENSERVICEFLAGS.py b/test/Rpcgen/RPCGENSERVICEFLAGS.py index 2edc77c..7cdf430 100644 --- a/test/Rpcgen/RPCGENSERVICEFLAGS.py +++ b/test/Rpcgen/RPCGENSERVICEFLAGS.py @@ -72,10 +72,10 @@ expect_h = output % ('-h', test.workpath('rpcif.h')) expect_svc = output_svc % ('-m', test.workpath('rpcif_svc.c')) expect_xdr = output % ('-c', test.workpath('rpcif_xdr.c')) -test.must_match('rpcif_clnt.c', expect_clnt, mode='r') -test.must_match('rpcif.h', expect_h, mode='r') -test.must_match('rpcif_svc.c', expect_svc, mode='r') -test.must_match('rpcif_xdr.c', expect_xdr, mode='r') +test.must_contain('rpcif_clnt.c', expect_clnt, mode='r') +test.must_contain('rpcif.h', expect_h, mode='r') +test.must_contain('rpcif_svc.c', expect_svc, mode='r') +test.must_contain('rpcif_xdr.c', expect_xdr, mode='r') diff --git a/test/Rpcgen/RPCGENXDRFLAGS.py b/test/Rpcgen/RPCGENXDRFLAGS.py index 2d1ca96..2f6d8d9 100644 --- a/test/Rpcgen/RPCGENXDRFLAGS.py +++ b/test/Rpcgen/RPCGENXDRFLAGS.py @@ -72,10 +72,10 @@ expect_h = output % ('-h', test.workpath('rpcif.h')) expect_svc = output % ('-m', test.workpath('rpcif_svc.c')) expect_xdr = output_xdr % ('-c', test.workpath('rpcif_xdr.c')) -test.must_match('rpcif_clnt.c', expect_clnt, mode='r') -test.must_match('rpcif.h', expect_h, mode='r') -test.must_match('rpcif_svc.c', expect_svc, mode='r') -test.must_match('rpcif_xdr.c', expect_xdr, mode='r') +test.must_contain('rpcif_clnt.c', expect_clnt, mode='r') +test.must_contain('rpcif.h', expect_h, mode='r') +test.must_contain('rpcif_svc.c', expect_svc, mode='r') +test.must_contain('rpcif_xdr.c', expect_xdr, mode='r') diff --git a/test/TEX/LATEX.py b/test/TEX/LATEX.py index 553313e..dabe8b1 100644 --- a/test/TEX/LATEX.py +++ b/test/TEX/LATEX.py @@ -28,6 +28,8 @@ r""" Validate that we can set the LATEX string to our own utility, that the produced .dvi, .aux and .log files get removed by the -c option, and that we can use this to wrap calls to the real latex utility. +Check that a log file with a warning encoded in non-UTF-8 (here: Latin-1) +is read without throwing an error. """ import TestSCons @@ -193,6 +195,24 @@ This is the include file. mod %s test.must_not_exist('latexi.ilg') + test.write('SConstruct', """ +env = Environment() +env.DVI('latin1log.tex') +""") + + # This will trigger an overfull hbox warning in the log file, + # containing the umlaut "o in Latin-1 ("T1 fontenc") encoding. + test.write('latin1log.tex', r""" +\documentclass[12pt,a4paper]{article} +\usepackage[T1]{fontenc} +\begin{document} +\"oxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +\end{document} +""") + + test.run(arguments = 'latin1log.dvi', stderr = None) + test.must_exist('latin1log.dvi') + test.pass_test() # Local Variables: diff --git a/test/YACC/YACCHFILESUFFIX.py b/test/YACC/YACCHFILESUFFIX.py index 6c34db1..da3416c 100644 --- a/test/YACC/YACCHFILESUFFIX.py +++ b/test/YACC/YACCHFILESUFFIX.py @@ -71,9 +71,9 @@ test.write('bbb.yacc', "bbb.yacc\n/*yacc*/\n") test.run(arguments = '.') test.must_match('aaa.c', "aaa.y\n") -test.must_match('aaa.hsuffix', "myyacc.py -d -o aaa.c aaa.y\n") +test.must_contain('aaa.hsuffix', "myyacc.py -d -o aaa.c aaa.y\n") test.must_match('bbb.c', "bbb.yacc\n") -test.must_match('bbb.hsuffix', "myyacc.py -d -o bbb.c bbb.yacc\n") +test.must_contain('bbb.hsuffix', "myyacc.py -d -o bbb.c bbb.yacc\n") test.up_to_date(arguments = '.') diff --git a/test/YACC/YACCHXXFILESUFFIX.py b/test/YACC/YACCHXXFILESUFFIX.py index 63a5358..3ee70ee 100644 --- a/test/YACC/YACCHXXFILESUFFIX.py +++ b/test/YACC/YACCHXXFILESUFFIX.py @@ -69,7 +69,7 @@ test.write('aaa.yy', "aaa.yy\n/*yacc*/\n") test.run(arguments = '.') test.must_match('aaa.cc', "aaa.yy\n") -test.must_match('aaa.hxxsuffix', "myyacc.py -d -o aaa.cc aaa.yy\n") +test.must_contain('aaa.hxxsuffix', "myyacc.py -d -o aaa.cc aaa.yy\n") test.up_to_date(arguments = '.') diff --git a/test/YACC/YACCVCGFILESUFFIX.py b/test/YACC/YACCVCGFILESUFFIX.py index aee3265..32c3440 100644 --- a/test/YACC/YACCVCGFILESUFFIX.py +++ b/test/YACC/YACCVCGFILESUFFIX.py @@ -78,7 +78,7 @@ test.must_not_exist('aaa.vcgsuffix') test.must_match('bbb.cc', "bbb.yy\n") test.must_not_exist('bbb.vcg') -test.must_match('bbb.vcgsuffix', "myyacc.py -g -o bbb.cc bbb.yy\n") +test.must_contain('bbb.vcgsuffix', "myyacc.py -g -o bbb.cc bbb.yy\n") test.up_to_date(arguments = '.') diff --git a/test/option/debug-action-timestamps.py b/test/option/debug-action-timestamps.py index 0277516..059cfdf 100644 --- a/test/option/debug-action-timestamps.py +++ b/test/option/debug-action-timestamps.py @@ -34,13 +34,13 @@ def setup_fixtures(): test.file_fixture('../fixture/SConstruct_test_main.py', 'SConstruct') def test_help_function(): - # Before anything else, make sure we get valid --debug=action_timestamps results + # Before anything else, make sure we get valid --debug=action-timestamps results # when just running the help option. - test.run(arguments = "-h --debug=action_timestamps") + test.run(arguments = "-h --debug=action-timestamps") def build(): # Execute build - test.run(arguments='--debug=action_timestamps') + test.run(arguments='--debug=action-timestamps') build_output = test.stdout() return build_output @@ -84,8 +84,8 @@ def test_correctness_of_timestamps(build_output): debug_time_patterns = [ r'Command execution time: (.*): (\d+\.\d+) seconds', - r'Command execution start time: (.*): (\d+\.\d+) seconds', - r'Command execution stop time: (.*): (\d+\.\d+) seconds' + r'Command execution start timestamp: (.*): (\d+\.\d+)', + r'Command execution end timestamp: (.*): (\d+\.\d+)' ] test = TestSCons.TestSCons() diff --git a/testing/framework/TestCmd.py b/testing/framework/TestCmd.py index 81e03f3..9218f60 100644 --- a/testing/framework/TestCmd.py +++ b/testing/framework/TestCmd.py @@ -1528,7 +1528,7 @@ class TestCmd(object): # TODO: Run full tests on both platforms and see if this fixes failures # It seems that py3.6 still sets text mode if you set encoding. elif sys.version_info[0] == 3: # TODO and sys.version_info[1] < 6: - stream = stream.decode('utf-8') + stream = stream.decode('utf-8', errors='replace') stream = stream.replace('\r\n', '\n') elif sys.version_info[0] == 2: stream = stream.replace('\r\n', '\n') diff --git a/testing/framework/test-framework.rst b/testing/framework/test-framework.rst index cb6b8e1..24240ac 100644 --- a/testing/framework/test-framework.rst +++ b/testing/framework/test-framework.rst @@ -29,7 +29,7 @@ There are three types of SCons tests: ``src/engine/`` subdirectory and are the same base name as the module to be tests, with ``Tests`` appended before the ``.py``. For example, the unit tests for the ``Builder.py`` module are in the - ``BuilderTests.py`` script. Unit tests tend to be based on assertions. + ``BuilderTests.py`` script. Unit tests tend to be based on assertions. *External Tests* For the support of external Tools (in the form of packages, preferably), |