diff options
| -rwxr-xr-x | CHANGES.txt | 2 | ||||
| -rw-r--r-- | SCons/Defaults.py | 11 | ||||
| -rw-r--r-- | SCons/Environment.xml | 2 | ||||
| -rw-r--r-- | doc/man/scons.xml | 242 |
4 files changed, 133 insertions, 124 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index d907867..9ce5a8a 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -78,6 +78,8 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - Deprecate Python 3.5 as a supported version. - CPPDEFINES now expands construction variable references (issue 2363) - Restore behavior that Install()'d files are writable (issue 3927) + - Simplified Mkdir(), the internal mkdir_func no longer needs to handle + existing directories, it can now pass exist_ok=True to os.makedirs(). From Dillan Mills: - Add support for the (TARGET,SOURCE,TARGETS,SOURCES,CHANGED_TARGETS,CHANGED_SOURCES}.relpath property. diff --git a/SCons/Defaults.py b/SCons/Defaults.py index 6dabfb5..50c30c6 100644 --- a/SCons/Defaults.py +++ b/SCons/Defaults.py @@ -309,16 +309,7 @@ def mkdir_func(dest): if not SCons.Util.is_List(dest): dest = [dest] for entry in dest: - try: - os.makedirs(str(entry)) - except os.error as e: - p = str(entry) - if (e.args[0] == errno.EEXIST or - (sys.platform == 'win32' and e.args[0] == 183)) \ - and os.path.isdir(str(entry)): - pass # not an error if already exists - else: - raise + os.makedirs(str(entry), exist_ok=True) Mkdir = ActionFactory(mkdir_func, diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 945ed9c..27e7302 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -258,7 +258,7 @@ a subclass of the SCons.CacheDir.CacheDir class. <scons_function name="Action"> <arguments> -(action, [cmd/str/fun, [var, ...]] [option=value, ...]) +(action, [output, [var, ...]] [key=value, ...]) </arguments> <summary> <para> diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 3f7eef9..1ffc1a4 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2753,14 +2753,15 @@ Builder methods take two required arguments: and <parameter>source</parameter>. Either can be passed as a scalar or as a list. -The target and source arguments +The <parameter>target</parameter> and +<parameter>source</parameter> arguments can be specified either as positional arguments, in which case <parameter>target</parameter> comes first, or as keyword arguments, using <parameter>target=</parameter> and <parameter>source=</parameter>. -Although both arguments are required, -in one particular case the target argument can actually be omitted -because it can be inferred and &SCons; supplies it (see below). +Although both arguments are nominally required, +if there is a single source and the target can be inferred +the <parameter>target</parameter> argument can be omitted (see below). Builder methods also take a variety of keyword arguments, described below. </para> @@ -2830,7 +2831,8 @@ to a relative or absolute path first. </para> <para> -Target and source pathnames can be absolute, relative, or +<parameter>target</parameter> and <parameter>source</parameter> +can be absolute, relative, or top-relative. Relative pathnames are searched considering the directory of the SConscript file currently being processed as the "current directory". @@ -3098,9 +3100,10 @@ bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') print("The path to bar_obj is:", str(bar_obj_list[0])) </programlisting> -<para>Note again that because the Builder call returns a list, -you have to access the first element in the list -(<literal>(bar_obj_list[0])</literal>) +<para>Note that because the Builder call returns a +<classname>NodeList</classname>, +you have to access the first element in the list, +(<literal>bar_obj_list[0]</literal> in the example) to get at the Node that actually represents the object file.</para> @@ -3162,6 +3165,19 @@ and to use just the filename portion of the targets and source.</para> +<para> +When trying to handle errors that may occur in a builder method, +consider that the corresponding Action is executed at a different +time than the SConscript file statement calling the builder. +It is not useful to wrap a builder call in a +<systemitem>try</systemitem> block, +since success in the builder call is not the same as +the builder itself succeeding. +If necessary, a Builder's Action should be coded to exit with +a useful exception message indicating the problem in the SConscript files - +programmatically recovering from build errors is rarely useful. +</para> + <para>&scons; predefines the following builder methods. Depending on the setup of a particular @@ -5785,25 +5801,25 @@ you need to create the action object using &f-Action;. <para>The &Action; factory function returns an appropriate object for the action -represented by the type of the action argument +represented by the type of the +<parameter>action</parameter> argument (the first positional parmeter):</para> <itemizedlist> <listitem> -<para>If the action argument is already an Action object, +<para>If <parameter>action</parameter> is already an Action object, the object is simply returned.</para> </listitem> <listitem> -<para>If the action argument is a string, +<para>If <parameter>action</parameter> is a string, a command-line Action is returned. -If such a string begins with -<emphasis role="bold">@</emphasis>, -it indicates printing of the command line is to be suppressed. -If the string begins with -<emphasis role="bold">-</emphasis> (hyphen), -it indicates the exit status from the specified command -is to be ignored, allowing execution to continue +If such a string begins with <literal>@</literal>, +the command line is not printed. +If the string begins with hyphen +(<literal>-</literal>), +the exit status from the specified command +is ignored, allowing execution to continue even if the command reports failure:</para> <programlisting language="python"> @@ -5818,14 +5834,13 @@ Action('-build $TARGET $SOURCES') </listitem> <listitem> -<para>If the action argument is a list, +<para>If <parameter>action</parameter> is a list, then a list of Action objects is returned. An Action object is created as necessary for each element in the list. -If an element -<emphasis>within</emphasis> +If an element within the list is itself a list, -the internal list is taken as the +the embedded list is taken as the command and arguments to be executed via the command line. This allows white space to be enclosed @@ -5838,18 +5853,22 @@ Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) </listitem> <listitem> -<para>If the action argument is a Python function, -a function Action is returned. -The Python function must accept three keyword arguments:</para> +<para>If <parameter>action</parameter> is a Python callable +a Function Action is returned. +The callable must accept three keyword arguments: +<parameter>target</parameter>, +<parameter>source</parameter> and +<parameter>env</parameter>. +</para> - <simplelist type="vert"> - <member><parameter>target</parameter> - - a Node object representing the target file.</member> - <member><parameter>source</parameter> - - a Node object representing the source file.</member> - <member><parameter>env</parameter> - - the &consenv; used for building the target file.</member> - </simplelist> +<para> +<parameter>target</parameter> +is a Node object representing the target file, +<parameter>source</parameter> +is a Node object representing the source file and +<parameter>env</parameter> +is the &consenv; used for building the target file. +</para> <para> The @@ -5886,17 +5905,22 @@ a = Action(build_it) </listitem> <listitem> -<para>If the action argument is not one of the above types, -<constant>None</constant> is returned.</para> +<para>If +<parameter>action</parameter> +is not one of the above types, +no action object is generated and &f-Action; +returns <constant>None</constant>.</para> </listitem> </itemizedlist> -<para>As usual the environment method form &f-link-env-Action; +<para>The environment method form &f-link-env-Action; will expand &consvars; in any argument strings, -including the action argument, at the time it is called, +including +<parameter>action</parameter>, +at the time it is called, using the construction variables in the &consenv; through which it was called. The global function form &f-link-Action; -<emphasis>delays</emphasis> variable expansion until +delays variable expansion until the Action object is actually used. </para> @@ -5912,30 +5936,7 @@ The following argument types are accepted: <itemizedlist> <listitem> -<para>If the output argument is a function, -the function will be called to obtain a string -describing the action being executed. -The function -must accept these three keyword arguments:</para> - - <simplelist type="vert"> - <member><parameter>source</parameter> - - a Node object representing the source file.</member> - <member><parameter>target</parameter> - - a Node object representing the target file.</member> - <member><parameter>env</parameter> - the &consenv;.</member> - </simplelist> - -<para>The -<parameter>target</parameter> -and -<parameter>source</parameter> -arguments may be lists of Node objects if there is -more than one target file or source file.</para> - </listitem> - - <listitem> -<para>If the output argument is a string, +<para>If <parameter>output</parameter> is a string, substitution is performed on the string before it is printed. The string typically contains variables, notably <literal>$TARGET(S)</literal> and <literal>$SOURCE(S)</literal>, @@ -5945,7 +5946,21 @@ variable, which is optionally defined somewhere else. </listitem> <listitem> -<para>If the argument is <constant>None</constant>, +<para>If <parameter>output</parameter> is a function, +the function will be called to obtain a string +describing the action being executed. +The function +must accept three keyword arguments: +<parameter>target</parameter>, +<parameter>source</parameter> and +<parameter>env</parameter>, +with the same interpretation as for a callable +<parameter>action</parameter> argument above. +</para> + </listitem> + + <listitem> +<para>If <parameter>output</parameter>is <constant>None</constant>, output is suppressed entirely.</para> </listitem> </itemizedlist> @@ -6022,30 +6037,25 @@ to modify the Action object's behavior:</para> <term><parameter>chdir</parameter></term> <listitem> <para> -Specifies that -scons will execute the action -after changing to the specified directory. -If the -<parameter>chdir</parameter> -argument is -a string or a directory Node, -scons will change to the specified directory. -If the -<parameter>chdir</parameter> -argument -is not a string or Node -and is non-zero, -then scons will change to the +If <parameter>chdir</parameter> is true +(the default is <constant>False</constant>), +&SCons; will change directories before +executing the action. +If the value of <parameter>chdir</parameter> +is a string or a directory Node, +&SCons; will change to the specified directory. +Otherwise, if <parameter>chdir</parameter> evaluates true, +&SCons; will change to the target file's directory.</para> -<para>Note that scons will +<para>Note that &SCons; will <emphasis>not</emphasis> automatically modify its expansion of &consvars; like &cv-TARGET; and &cv-SOURCE; when using the <parameter>chdir</parameter> -keyword argument--that is, +parameter - that is, the expanded file names will still be relative to the top-level directory containing the &SConstruct; file, @@ -6061,8 +6071,7 @@ to use just the filename portion of the targets and source. Example:</para> <programlisting language="python"> -a = Action("build < ${SOURCE.file} > ${TARGET.file}", - chdir=1) +a = Action("build < ${SOURCE.file} > ${TARGET.file}", chdir=True) </programlisting> </listitem> </varlistentry> @@ -6070,11 +6079,10 @@ a = Action("build < ${SOURCE.file} > ${TARGET.file}", <term><parameter>exitstatfunc</parameter></term> <listitem> <para> -A function -that is passed the exit status -(or return value) -from the specified action -and can return an arbitrary +If provided, must be a callable which accepts a single parameter, +the exit status (or return value) +from the specified action, +and which returns an arbitrary or modified value. This can be used, for example, to specify that an Action object's @@ -6097,7 +6105,7 @@ a = Action("build < ${SOURCE.file} > ${TARGET.file}", <term><parameter>batch_key</parameter></term> <listitem> <para> -Specifies that the Action can create multiple target files +If provided, indicates that the Action can create multiple target files by processing multiple independent source files simultaneously. (The canonical example is "batch compilation" of multiple object files @@ -6134,33 +6142,33 @@ will be used to identify different for batch building. A <parameter>batch_key</parameter> -function must accept the following arguments:</para> - - <simplelist> - <member><parameter>action</parameter> - The action object.</member> - <member><parameter>env</parameter> - - The &consenv; configured for the target.</member> - <member><parameter>target</parameter> - - The list of targets for a particular configured action.</member> - <member><parameter>source</parameter> - - The list of source for a particular configured action.</member> - </simplelist> +function must accept four parameters: +<parameter>action</parameter>, +<parameter>env</parameter>, +<parameter>target</parameter> and +<parameter>source</parameter>. +The first parameter, <parameter>action</parameter>, +is the active action object. +The second parameter, <parameter>env</parameter>, +is the &consenv; configured for the target. +The <parameter>target</parameter> and <parameter>source</parameter> +parameters are the lists of targets and sources +for the configured action. +</para> <para>The returned key should typically be a tuple of values derived from the arguments, using any appropriate logic to decide how multiple invocations should be batched. For example, a -<function>batch_key</function> +<parameter>batch_key</parameter> function may decide to return -the value of a specific construction -variable from the -<parameter>env</parameter> -argument +the value of a specific &consvar; +from <parameter>env</parameter> which will cause &scons; to batch-build targets -with matching values of that variable, +with matching values of that &consvar;, or perhaps return the Python <function>id</function>() of the entire &consenv;, @@ -6197,8 +6205,8 @@ a = Action('build $CHANGED_SOURCES', batch_key=batch_key) <refsect2 id='miscellaneous_action_functions'> <title>Miscellaneous Action Functions</title> -<para>&scons; -supplies a number of functions +<para>&SCons; +supplies Action functions that arrange for various common file and directory manipulations to be performed. @@ -6213,8 +6221,8 @@ return an Action object that can be executed at the appropriate time.</para> -<para>In practice, -there are two natural ways +<para> +There are two natural ways that these Action Functions are intended to be used.</para> @@ -6226,7 +6234,7 @@ at the time the SConscript file is being read, you can use the &f-link-Execute; -global function to do so:</para> +global function:</para> <programlisting language="python"> Execute(Touch('file')) @@ -6284,6 +6292,12 @@ env.Command('foo.out', 'foo.in', Chmod('$TARGET', "ugo+w")]) </programlisting> +<para> +The behavior of <function>Chmod</function> is limited on Windows, +see the notes in the Python documentation for +<systemitem>os.chmod</systemitem>, which is the underlying function. +</para> + </listitem> </varlistentry> @@ -6346,12 +6360,14 @@ Execute(Delete('file_that_must_exist', must_exist=True)) </varlistentry> <varlistentry> - <term><function>Mkdir</function>(<parameter>dir</parameter>)</term> + <term><function>Mkdir</function>(<parameter>name</parameter>)</term> <listitem> <para>Returns an Action -that creates the specified -directory -<parameter>dir</parameter>. +that creates the directory +<parameter>name</parameter> +and all needed intermediate directories. +<parameter>name</parameter> may also be a list +of directories to create. Examples:</para> <programlisting language="python"> |