diff options
Diffstat (limited to 'doc/man/scons.xml')
| -rw-r--r-- | doc/man/scons.xml | 138 |
1 files changed, 83 insertions, 55 deletions
diff --git a/doc/man/scons.xml b/doc/man/scons.xml index aabd957..dd9fbdd 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8"?> <!-- - Copyright (c) 2001 - 2017 The SCons Foundation + Copyright (c) 2001 - 2019 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -54,10 +54,10 @@ <corpauthor>Steven Knight and the SCons Development Team</corpauthor> - <pubdate>2004 - 2016</pubdate> + <pubdate>2004 - 2019</pubdate> <copyright> - <year>2004 - 2016</year> + <year>2004 - 2019</year> <holder>The SCons Foundation</holder> </copyright> @@ -75,8 +75,8 @@ <refmeta> <refentrytitle>SCONS</refentrytitle> <manvolnum>1</manvolnum> -<refmiscinfo class='source'>SCons 3.0.0</refmiscinfo> -<refmiscinfo class='manual'>SCons 3.0.0</refmiscinfo> +<refmiscinfo class='source'>SCons 3.1.0</refmiscinfo> +<refmiscinfo class='manual'>SCons 3.1.0</refmiscinfo> </refmeta> <refnamediv id='name'> <refname>scons</refname> @@ -105,8 +105,11 @@ rebuild them.</para> searches for a file named <emphasis>SConstruct</emphasis>, <emphasis>Sconstruct</emphasis>, +<emphasis>sconstruct</emphasis>, +<emphasis>SConstruct.py</emphasis> +<emphasis>Sconstruct.py</emphasis> or -<emphasis>sconstruct</emphasis> +<emphasis>sconstruct.py</emphasis> (in that order) in the current directory and reads its configuration from the first file found. An alternate file name may be @@ -271,7 +274,7 @@ scons <para>will build all target files in or below the current directory. Explicit default targets (to be built when no targets are specified on the command line) -may be defined the SConscript file(s) +may be defined in the SConscript file(s) using the <emphasis role="bold">Default()</emphasis> function, described below.</para> @@ -426,7 +429,7 @@ try to access a list member that does not exist.</para> <para><command>scons</command> -requires Python version 2.7 or later. +requires either Python 2.7 or Python 3.5 or higher. There should be no other dependencies or requirements to run <emphasis role="bold">scons.</emphasis></para> @@ -635,8 +638,11 @@ yet have any results in the cache.</para> before searching for the <emphasis>SConstruct</emphasis>, <emphasis>Sconstruct</emphasis>, +<emphasis>sconstruct</emphasis>, +<emphasis>SConstruct.py</emphasis> +<emphasis>Sconstruct.py</emphasis> or -<emphasis>sconstruct</emphasis> +<emphasis>sconstruct.py</emphasis> file, or doing anything else. Multiple <option>-C</option> @@ -649,8 +655,11 @@ equivalent to except that it will search for <emphasis>SConstruct</emphasis>, <emphasis>Sconstruct</emphasis>, +<emphasis>sconstruct</emphasis>, +<emphasis>SConstruct.py</emphasis> +<emphasis>Sconstruct.py</emphasis> or -<emphasis>sconstruct</emphasis> +<emphasis>sconstruct.py</emphasis> in the specified directory.)</para> <!-- .TP --> @@ -853,14 +862,31 @@ and ultimately removed.</para> <varlistentry> <term>--debug=time</term> <listitem> -<para>Prints various time profiling information: -the time spent executing each individual build command; -the total build time (time SCons ran from beginning to end); -the total time spent reading and executing SConscript files; -the total time spent SCons itself spend running -(that is, not counting reading and executing SConscript files); -and both the total time spent executing all build commands -and the elapsed wall-clock time spent executing those build commands. +<para>Prints various 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 time spent processing each file passed to the <emphasis>SConscript()</emphasis> function</para> + </listitem> + </itemizedlist> +<para> (When <command>scons</command> is executed without the @@ -884,7 +910,8 @@ be significantly smaller than the total time spent executing all the build commands, since multiple build commands and intervening SCons processing -should take place in parallel.)</para> +should take place in parallel.) +</para> </listitem> </varlistentry> @@ -970,6 +997,12 @@ the mechanisms in the specified order.</para> </listitem> </varlistentry> <varlistentry> + <term>--enable-virtualenv</term> + <listitem> +<para>Import virtualenv-related variables to SCons.</para> + </listitem> + </varlistentry> + <varlistentry> <term>-f<emphasis> file</emphasis>, --file=<emphasis>file</emphasis>, --makefile=<emphasis>file</emphasis>, --sconstruct=<emphasis>file</emphasis></term> <listitem> <para>Use @@ -1024,6 +1057,12 @@ are used, the directories are searched in the order specified.</para> </listitem> </varlistentry> + <varlistentry> + <term>--ignore-virtualenv</term> + <listitem> +<para>Suppress importing virtualenv-related variables to SCons.</para> + </listitem> + </varlistentry> <varlistentry> <term>--implicit-cache</term> <listitem> @@ -1640,9 +1679,12 @@ scons --tree=all,prune,status target <listitem> <para>Walks up the directory structure until an <emphasis>SConstruct ,</emphasis> -<emphasis>Sconstruct</emphasis> +<emphasis>Sconstruct ,</emphasis> +<emphasis>sconstruct ,</emphasis> +<emphasis>SConstruct.py</emphasis> +<emphasis>Sconstruct.py</emphasis> or -<emphasis>sconstruct</emphasis> +<emphasis>sconstruct.py</emphasis> file is found, and uses that as the top of the directory tree. If no targets are specified on the command line, @@ -1866,26 +1908,6 @@ These warnings are enabled by default.</para> </listitem> </varlistentry> <varlistentry> - <term>--warn=no-md5-module, --warn=no-no-md5-module</term> - <listitem> -<para>Enables or disables warnings about the version of Python -not having an MD5 checksum module available. -These warnings are enabled by default.</para> - - </listitem> - </varlistentry> - <varlistentry> - <term>--warn=no-metaclass-support, --warn=no-no-metaclass-support</term> - <listitem> -<para>Enables or disables warnings about the version of Python -not supporting metaclasses when the -<option>--debug=memoizer</option> -option is used. -These warnings are enabled by default.</para> - - </listitem> - </varlistentry> - <varlistentry> <term>--warn=no-object-count, --warn=no-no-object-count</term> <listitem> <para>Enables or disables warnings about the @@ -2021,7 +2043,7 @@ env['BAR'] = 'bar' construction variables may also be set or modified by the <emphasis>parse_flags</emphasis> keyword argument, which applies the -<emphasis role="bold">ParseFlags</emphasis> +&f-link-env-MergeFlags; method (described below) to the argument value after all other processing is completed. This is useful either if the exact content of the flags is unknown @@ -2029,7 +2051,7 @@ This is useful either if the exact content of the flags is unknown or if the flags are distributed to a number of construction variables.</para> <literallayout class="monospaced"> -env = Environment(parse_flags = '-Iinclude -DEBUG -lm') +env = Environment(parse_flags='-Iinclude -DEBUG -lm') </literallayout> <para>This example adds 'include' to @@ -2299,12 +2321,12 @@ that are not absolute path names <emphasis role="bold">/</emphasis> on POSIX systems or -<emphasis role="bold">\fR +<emphasis role="bold">\</emphasis> on Windows systems, with or without an optional drive letter) are interpreted relative to the directory containing the -SConscript</emphasis> +<emphasis role="bold">SConscript</emphasis> file being read. An initial <emphasis role="bold">#</emphasis> @@ -2417,10 +2439,14 @@ see the descriptions of these variables, below, for more information.)</para> <para>It is also possible to use the <emphasis>parse_flags</emphasis> -keyword argument in an override:</para> +keyword argument in an override, +to merge command-line style arguments +into the appropriate construction variables +(see &f-link-env-MergeFlags;). +</para> <literallayout class="monospaced"> -env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm') +env = Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm') </literallayout> <para>This example adds 'include' to @@ -2992,7 +3018,7 @@ function to get at the path name for each Node.</para> <literallayout class="monospaced"> print(str(DEFAULT_TARGETS[0])) -if 'foo' in map(str, DEFAULT_TARGETS): +if 'foo' in [str(t) for t in DEFAULT_TARGETS]: print("Don't forget to test the `foo' program!") </literallayout> </listitem> @@ -3006,13 +3032,13 @@ list change on on each successive call to the function:</para> <literallayout class="monospaced"> -print(map(str, DEFAULT_TARGETS)) # originally [] +print([str(t) for t in DEFAULT_TARGETS]) # originally [] Default('foo') -print(map(str, DEFAULT_TARGETS)) # now a node ['foo'] +print([str(t) for t in DEFAULT_TARGETS]) # now a node ['foo'] Default('bar') -print(map(str, DEFAULT_TARGETS)) # now a node ['foo', 'bar'] +print([str(t) for t in DEFAULT_TARGETS]) # now a node ['foo', 'bar'] Default(None) -print(map(str, DEFAULT_TARGETS)) # back to [] +print([str(t) for t in DEFAULT_TARGETS]) # back to [] </literallayout> <para>Consequently, be sure to use @@ -4056,7 +4082,9 @@ and return -1, 0 or 1 (like the standard Python <emphasis>cmp</emphasis> -function).</para> +function). + +Optionally a Boolean value of True for <emphasis>sort</emphasis> will cause a standard alphabetical sort to be performed</para> <literallayout class="monospaced"> Help(vars.GenerateHelpText(env)) @@ -5255,11 +5283,11 @@ arguments may be lists of Node objects if there is more than one target file or source file. The actual target and source file name(s) may be retrieved from their Node objects -via the built-in Python str() function:</para> +via the built-in Python <function>str</function> function:</para> <literallayout class="monospaced"> target_file_name = str(target) -source_file_names = map(lambda x: str(x), source) +source_file_names = [str(x) for x in source] </literallayout> <para>The function should return |