diff options
| -rw-r--r-- | doc/user/add-method.xml | 41 | ||||
| -rw-r--r-- | doc/user/alias.xml | 10 | ||||
| -rw-r--r-- | doc/user/builders-built-in.xml | 223 | ||||
| -rw-r--r-- | doc/user/builders-commands.xml | 59 | ||||
| -rw-r--r-- | doc/user/builders-writing.xml | 957 | ||||
| -rw-r--r-- | doc/user/builders.xml | 57 | ||||
| -rw-r--r-- | doc/user/caching.xml | 506 | ||||
| -rw-r--r-- | doc/user/command-line.xml | 145 | ||||
| -rw-r--r-- | doc/user/depends.xml | 13 | ||||
| -rw-r--r-- | doc/user/environments.xml | 23 | ||||
| -rw-r--r-- | doc/user/less-simple.xml | 12 | ||||
| -rw-r--r-- | doc/user/libraries.xml | 24 | ||||
| -rw-r--r-- | doc/user/nodes.xml | 12 | ||||
| -rw-r--r-- | doc/user/output.xml | 12 | ||||
| -rw-r--r-- | doc/user/parseconfig.xml | 26 | ||||
| -rw-r--r-- | doc/user/parseflags.xml | 12 | ||||
| -rw-r--r-- | doc/user/simple.xml | 36 | ||||
| -rw-r--r-- | doc/user/troubleshoot.xml | 34 | ||||
| -rw-r--r-- | doc/user/variants.xml | 12 |
19 files changed, 1862 insertions, 352 deletions
diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml index 8e078fd..d4a484e 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -56,7 +56,7 @@ <screen> % <userinput>scons -Q /</userinput> - [?1034hcc -o hello.o -c hello.c + cc -o hello.o -c hello.c cc -o hello hello.o Install file: "hello" as "/usr/bin/hello" Install file: "hello" as "install/bin/hello" @@ -100,7 +100,7 @@ <screen> % <userinput>scons -Q</userinput> - [?1034hcc -o test_stuff.o -c test_stuff.c + cc -o test_stuff.o -c test_stuff.c cc -o tests/test_stuff test_stuff.o </screen> @@ -110,40 +110,9 @@ <screen> C:\><userinput>scons -Q</userinput> - IndexError: list index out of range: - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\Main.py", line 1294: - _exec_main(parser, values) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\Main.py", line 1259: - _main(parser) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\Main.py", line 929: - SCons.Script._SConscript._SConscript(fs, script) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\SConscript.py", line 179: - exec sys.stdin in call_stack[-1].globals - File "<stdin>", line 219: - None - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\SConscript.py", line 614: - env = self.factory() - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\SConscript.py", line 594: - default_env = SCons.Defaults.DefaultEnvironment() - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Defaults.py", line 91: - _default_env = apply(SCons.Environment.Environment, args, kw) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Environment.py", line 1004: - apply_tools(self, tools, toolpath) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Environment.py", line 106: - env.Tool(tool) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Environment.py", line 1703: - tool(self) - File "<stdin>", line 67: - None - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\msvc.py", line 239: - mssdk.generate(env) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\mssdk.py", line 41: - mssdk_setup_env(env) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\MSCommon\sdk.py", line 298: - mssdk = get_default_sdk() - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\MSCommon\sdk.py", line 262: - return InstalledSDKList[0] - [?1034h + rc /fores.res res.rc + cl /Fotest_stuff.obj /c test_stuff.c /nologo + link /nologo /OUT:tests\test_stuff.exe test_stuff.obj res.res </screen> <para> diff --git a/doc/user/alias.xml b/doc/user/alias.xml index 9c4a179..f285d70 100644 --- a/doc/user/alias.xml +++ b/doc/user/alias.xml @@ -46,7 +46,7 @@ <screen> % <userinput>scons -Q install</userinput> - [?1034hcc -o hello.o -c hello.c + cc -o hello.o -c hello.c cc -o hello hello.o Install file: "hello" as "/usr/bin/hello" </screen> @@ -86,23 +86,23 @@ <screen> % <userinput>scons -Q install-bin</userinput> - [?1034hcc -o foo.o -c foo.c + cc -o foo.o -c foo.c cc -o foo foo.o Install file: "foo" as "/usr/bin/foo" % <userinput>scons -Q install-lib</userinput> - [?1034hcc -o bar.o -c bar.c + cc -o bar.o -c bar.c ar rc libbar.a bar.o ranlib libbar.a Install file: "libbar.a" as "/usr/lib/libbar.a" % <userinput>scons -Q -c /</userinput> - [?1034hRemoved foo.o + Removed foo.o Removed foo Removed /usr/bin/foo Removed bar.o Removed libbar.a Removed /usr/lib/libbar.a % <userinput>scons -Q install</userinput> - [?1034hcc -o foo.o -c foo.c + cc -o foo.o -c foo.c cc -o foo foo.o Install file: "foo" as "/usr/bin/foo" cc -o bar.o -c bar.c diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml index cb7fb70..738683b 100644 --- a/doc/user/builders-built-in.xml +++ b/doc/user/builders-built-in.xml @@ -144,7 +144,7 @@ <screen> % <userinput>scons -Q</userinput> - [?1034hcc -o goodbye.o -c goodbye.c + cc -o goodbye.o -c goodbye.c cc -o hello.o -c hello.c cc -o hello hello.o goodbye.o -L/usr/dir1 -Ldir2 -lfoo1 -lfoo2 </screen> @@ -157,40 +157,9 @@ <screen> C:\><userinput>scons -Q</userinput> - IndexError: list index out of range: - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\Main.py", line 1294: - _exec_main(parser, values) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\Main.py", line 1259: - _main(parser) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\Main.py", line 929: - SCons.Script._SConscript._SConscript(fs, script) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\SConscript.py", line 179: - exec sys.stdin in call_stack[-1].globals - File "<stdin>", line 219: - None - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\SConscript.py", line 614: - env = self.factory() - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Script\SConscript.py", line 594: - default_env = SCons.Defaults.DefaultEnvironment() - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Defaults.py", line 91: - _default_env = apply(SCons.Environment.Environment, args, kw) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Environment.py", line 1004: - apply_tools(self, tools, toolpath) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Environment.py", line 106: - env.Tool(tool) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Environment.py", line 1703: - tool(self) - File "<stdin>", line 67: - None - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\msvc.py", line 239: - mssdk.generate(env) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\mssdk.py", line 41: - mssdk_setup_env(env) - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\MSCommon\sdk.py", line 298: - mssdk = get_default_sdk() - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Tool\MSCommon\sdk.py", line 262: - return InstalledSDKList[0] - [?1034h + cl /Fogoodbye.obj /c goodbye.c /nologo + cl /Fohello.obj /c hello.c /nologo + link /nologo /OUT:hello.exe /LIBPATH:\usr\dir1 /LIBPATH:dir2 foo1.lib foo2.lib hello.obj goodbye.obj </screen> <para> @@ -758,7 +727,7 @@ <screen> % <userinput>scons -Q .</userinput> - [?1034htar -c -f out1.tar file1 file2 + tar -c -f out1.tar file1 file2 tar -c -f out2.tar directory </screen> @@ -784,3 +753,185 @@ <screen> % <userinput>scons -Q .</userinput> + tar -c -z -f out.tar.gz directory + </screen> + + <para> + + you may also wish to set the value of the + &cv-link-TARSUFFIX; construction variable + to your desired suffix for compress &tar; archives, + so that &SCons; can append it to the target file name + without your having to specify it explicitly: + + </para> + + <programlisting> + env = Environment(TARFLAGS = '-c -z', + TARSUFFIX = '.tgz') + env.Tar('out', 'directory') + </programlisting> + + <screen> + % <userinput>scons -Q .</userinput> + tar -c -z -f out.tgz directory + </screen> + + </section> + + <section> + <title>The &Zip; Builder</title> + + <para> + + The &b-link-Zip; Builder object creates archives of files + and/or directory trees in the ZIP file format. + Python versions 1.6 or later + contain an internal &zipfile; module + that &SCons; will use. + In this case, given the following + &SConstruct; file: + + </para> + + <programlisting> + env = Environment() + env.Zip('out', ['file1', 'file2']) + </programlisting> + + <para> + + Your output will reflect the fact + that an internal Python function + is being used to create the output ZIP archive: + + </para> + + <screen> + % <userinput>scons -Q .</userinput> + zip(["out.zip"], ["file1", "file2"]) + </screen> + + <para> + + If you're using Python version 1.5.2 to run &SCons;, + then &SCons; will try to use an external + &zip; program as follows: + + </para> + + <screen> + % <userinput>scons -Q .</userinput> + zip /home/my/project/zip.out file1 file2 + </screen> + + </section> + + </section> + + <section> + <title>Java</title> + + <para> + + &SCons; provides Builder objects + for creating various types of Java output files. + + </para> + + <section> + <title>Building Class Files: the &Java; Builder</title> + + <para> + + The &b-link-Java; builder takes one or more input + <filename>.java</filename> files + and turns them into one or more + <filename>.class</filename> files + Unlike most builders, however, + the &Java; builder takes + target and source <emphasis>directories</emphasis>, + not files, as input. + + </para> + + <programlisting> + env = Environment() + env.Java(target = 'classes', source = 'src') + </programlisting> + + <para> + + The &Java; builder will then + search the specified source directory + tree for all <filename>.java</filename> files, + and pass any out-of-date + + </para> + + <screen> + XXX Java() screen + </screen> + + </section> + + <section> + <title>The &Jar; Builder</title> + + <para> + + XXX The &Jar; builder object + + </para> + + <programlisting> + env = Environment() + env.Java(target = 'classes', source = 'src') + env.Jar(target = '', source = 'classes') + </programlisting> + + <screen> + XXX Jar() screen + </screen> + + </section> + + <section> + <title>Building C header and stub files: the &JavaH; Builder</title> + + <para> + + XXX JavaH() para + + </para> + + <programlisting> + XXX JavaH() programlisting + </programlisting> + + <screen> + XXX JavaH() screen + </screen> + + </section> + + <section> + <title>Building RMI stub and skeleton class files: the &RMIC; Builder</title> + + <para> + + XXX RMIC() para + + </para> + + <programlisting> + XXX RMIC() programlisting + </programlisting> + + <screen> + XXX RMIC() screen + </screen> + + </section> + + </section> diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml index 23fe4ce..fcb2a96 100644 --- a/doc/user/builders-commands.xml +++ b/doc/user/builders-commands.xml @@ -85,3 +85,62 @@ <screen> % <userinput>scons -Q</userinput> + sed 's/x/y/' < foo.in > foo.out + </screen> + + <para> + + This is often more convenient than + creating a &Builder; object + and adding it to the &cv-link-BUILDERS; variable + of a &consenv; + + </para> + + <para> + + Note that the action you specify to the + &Command; &Builder; can be any legal &SCons; &Action;, + such as a Python function: + + </para> + + <programlisting> + env = Environment() + def build(target, source, env): + # Whatever it takes to build + return None + env.Command('foo.out', 'foo.in', build) + </programlisting> + + <para> + + Which executes as follows: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + build(["foo.out"], ["foo.in"]) + </screen> + + <para> + + Note that &cv-link-SOURCE; and &cv-link-TARGET; are expanded + in the source and target as well as of SCons 1.1, + so you can write: + + </para> + + <programlisting> + env.Command('${SOURCE.basename}.out', 'foo.in', build) + </programlisting> + + + <para> + + which does the same thing as the previous example, but allows you + to avoid repeating yourself. + + </para> + diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index e69de29..3932181 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -0,0 +1,957 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<!-- + +=head2 Adding new methods + +For slightly more demanding changes, you may wish to add new methods to the +C<cons> package. Here's an example of a very simple extension, +C<InstallScript>, which installs a tcl script in a requested location, but +edits the script first to reflect a platform-dependent path that needs to be +installed in the script: + + # cons::InstallScript - Create a platform dependent version of a shell + # script by replacing string ``#!your-path-here'' with platform specific + # path $BIN_DIR. + + sub cons::InstallScript { + my ($env, $dst, $src) = @_; + Command $env $dst, $src, qq( + sed s+your-path-here+$BIN_DIR+ %< > %> + chmod oug+x %> + ); + } + +Notice that this method is defined directly in the C<cons> package (by +prefixing the name with C<cons::>). A change made in this manner will be +globally visible to all environments, and could be called as in the +following example: + + InstallScript $env "$BIN/foo", "foo.tcl"; + +For a small improvement in generality, the C<BINDIR> variable could be +passed in as an argument or taken from the construction environment-,-as +C<%BINDIR>. + + +=head2 Overriding methods + +Instead of adding the method to the C<cons> name space, you could define a +new package which inherits existing methods from the C<cons> package and +overrides or adds others. This can be done using Perl's inheritance +mechanisms. + +The following example defines a new package C<cons::switch> which +overrides the standard C<Library> method. The overridden method builds +linked library modules, rather than library archives. A new +constructor is provided. Environments created with this constructor +will have the new library method; others won't. + + package cons::switch; + BEGIN {@ISA = 'cons'} + + sub new { + shift; + bless new cons(@_); + } + + sub Library { + my($env) = shift; + my($lib) = shift; + my(@objs) = Objects $env @_; + Command $env $lib, @objs, q( + %LD -r %LDFLAGS %< -o %> + ); + } + +This functionality could be invoked as in the following example: + + $env = new cons::switch(@overrides); + ... + Library $env 'lib.o', 'foo.c', 'bar.c'; + +--> + + <para> + + Although &SCons; provides many useful methods + for building common software products: + programs, libraries, documents. + you frequently want to be + able to build some other type of file + not supported directly by &SCons;. + Fortunately, &SCons; makes it very easy + to define your own &Builder; objects + for any custom file types you want to build. + (In fact, the &SCons; interfaces for creating + &Builder; objects are flexible enough and easy enough to use + that all of the the &SCons; built-in &Builder; objects + are created the mechanisms described in this section.) + + </para> + + <section> + <title>Writing Builders That Execute External Commands</title> + + <para> + + The simplest &Builder; to create is + one that executes an external command. + For example, if we want to build + an output file by running the contents + of the input file through a command named + <literal>foobuild</literal>, + creating that &Builder; might look like: + + </para> + + <programlisting> + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + </programlisting> + + <para> + + All the above line does is create a free-standing + &Builder; object. + The next section will show us how to actually use it. + + </para> + + </section> + + <section> + <title>Attaching a Builder to a &ConsEnv;</title> + + <para> + + A &Builder; object isn't useful + until it's attached to a &consenv; + so that we can call it to arrange + for files to be built. + This is done through the &cv-link-BUILDERS; + &consvar; in an environment. + The &cv-BUILDERS; variable is a Python dictionary + that maps the names by which you want to call + various &Builder; objects to the objects themselves. + For example, if we want to call the + &Builder; we just defined by the name + <function>Foo</function>, + our &SConstruct; file might look like: + + </para> + + + + <programlisting> + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + env = Environment(BUILDERS = {'Foo' : bld}) + </programlisting> + + <para> + + With the &Builder; attached to our &consenv; + with the name <function>Foo</function>, + we can now actually call it like so: + + </para> + + <programlisting> + env.Foo('file.foo', 'file.input') + </programlisting> + + <para> + + Then when we run &SCons; it looks like: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + foobuild < file.input > file.foo + </screen> + + <para> + + Note, however, that the default &cv-BUILDERS; + variable in a &consenv; + comes with a default set of &Builder; objects + already defined: + &b-link-Program;, &b-link-Library;, etc. + And when we explicitly set the &cv-BUILDERS; variable + when we create the &consenv;, + the default &Builder;s are no longer part of + the environment: + + </para> + + <!-- + The ToolSurrogate stuff that's used to capture output initializes + SCons.Defaults.ConstructionEnvironment with its own list of TOOLS. + In this next example, we want to show the user that when they + set the BUILDERS explicitly, the call to env.Program() generates + an AttributeError. This won't happen with all of the default + ToolSurrogates in the default construction environment. To make the + AttributeError show up, we have to overwite the default construction + environment's TOOLS variable so Program() builder doesn't show up. + + We do this by executing a slightly different SConstruct file than the + one we print in the guide, with two extra statements at the front + that overwrite the TOOLS variable as described. Note that we have + to jam those statements on to the first line to keep the line number + in the generated error consistent with what the user will see in the + User's Guide. + --> + <programlisting> + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + env = Environment(BUILDERS = {'Foo' : bld}) + env.Foo('file.foo', 'file.input') + env.Program('hello.c') + </programlisting> + + <screen> + % <userinput>scons -Q</userinput> + AttributeError: SConsEnvironment instance has no attribute 'Program': + File "/home/my/project/SConstruct", line 4: + env.Program('hello.c') + </screen> + + <para> + + To be able to use both our own defined &Builder; objects + and the default &Builder; objects in the same &consenv;, + you can either add to the &cv-BUILDERS; variable + using the &Append; function: + + </para> + + + + <programlisting> + env = Environment() + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + env.Append(BUILDERS = {'Foo' : bld}) + env.Foo('file.foo', 'file.input') + env.Program('hello.c') + </programlisting> + + <para> + + Or you can explicitly set the appropriately-named + key in the &cv-BUILDERS; dictionary: + + </para> + + <programlisting> + env = Environment() + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + env['BUILDERS']['Foo'] = bld + env.Foo('file.foo', 'file.input') + env.Program('hello.c') + </programlisting> + + <para> + + Either way, the same &consenv; + can then use both the newly-defined + <function>Foo</function> &Builder; + and the default &b-link-Program; &Builder;: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + foobuild < file.input > file.foo + cc -o hello.o -c hello.c + cc -o hello hello.o + </screen> + + </section> + + <section> + <title>Letting &SCons; Handle The File Suffixes</title> + + <para> + + By supplying additional information + when you create a &Builder;, + you can let &SCons; add appropriate file + suffixes to the target and/or the source file. + For example, rather than having to specify + explicitly that you want the <literal>Foo</literal> + &Builder; to build the <literal>file.foo</literal> + target file from the <literal>file.input</literal> source file, + you can give the <literal>.foo</literal> + and <literal>.input</literal> suffixes to the &Builder;, + making for more compact and readable calls to + the <literal>Foo</literal> &Builder;: + + </para> + + + + <programlisting> + bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + suffix = '.foo', + src_suffix = '.input') + env = Environment(BUILDERS = {'Foo' : bld}) + env.Foo('file1') + env.Foo('file2') + </programlisting> + + <screen> + % <userinput>scons -Q</userinput> + foobuild < file1.input > file1.foo + foobuild < file2.input > file2.foo + </screen> + + <para> + + You can also supply a <literal>prefix</literal> keyword argument + if it's appropriate to have &SCons; append a prefix + to the beginning of target file names. + + </para> + + </section> + + <section> + <title>Builders That Execute Python Functions</title> + + <para> + + In &SCons;, you don't have to call an external command + to build a file. + You can, instead, define a Python function + that a &Builder; object can invoke + to build your target file (or files). + Such a &buildfunc; definition looks like: + + </para> + + <programlisting> + def build_function(target, source, env): + # Code to build "target" from "source" + return None + </programlisting> + + <para> + + The arguments of a &buildfunc; are: + + </para> + + <variablelist> + + <varlistentry> + <term>target</term> + + <listitem> + <para> + + A list of Node objects representing + the target or targets to be + built by this builder function. + The file names of these target(s) + may be extracted using the Python &str; function. + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>source</term> + + <listitem> + <para> + + A list of Node objects representing + the sources to be + used by this builder function to build the targets. + The file names of these source(s) + may be extracted using the Python &str; function. + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>env</term> + + <listitem> + <para> + + The &consenv; used for building the target(s). + The builder function may use any of the + environment's construction variables + in any way to affect how it builds the targets. + + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + + The builder function must + return a <literal>0</literal> or <literal>None</literal> value + if the target(s) are built successfully. + The builder function + may raise an exception + or return any non-zero value + to indicate that the build is unsuccessful, + + </para> + + <para> + + Once you've defined the Python function + that will build your target file, + defining a &Builder; object for it is as + simple as specifying the name of the function, + instead of an external command, + as the &Builder;'s + <literal>action</literal> + argument: + + </para> + + <programlisting> + def build_function(target, source, env): + # Code to build "target" from "source" + return None + bld = Builder(action = build_function, + suffix = '.foo', + src_suffix = '.input') + env = Environment(BUILDERS = {'Foo' : bld}) + env.Foo('file') + </programlisting> + + <para> + + And notice that the output changes slightly, + reflecting the fact that a Python function, + not an external command, + is now called to build the target file: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + build_function(["file.foo"], ["file.input"]) + </screen> + + </section> + + <section> + <title>Builders That Create Actions Using a &Generator;</title> + + <para> + + &SCons; Builder objects can create an action "on the fly" + by using a function called a &generator;. + This provides a great deal of flexibility to + construct just the right list of commands + to build your target. + A &generator; looks like: + + </para> + + <programlisting> + def generate_actions(source, target, env, for_signature): + return 'foobuild < %s > %s' % (target[0], source[0]) + </programlisting> + + <para> + + The arguments of a &generator; are: + + </para> + + <variablelist> + + <varlistentry> + <term>source</term> + + <listitem> + <para> + + A list of Node objects representing + the sources to be built + by the command or other action + generated by this function. + The file names of these source(s) + may be extracted using the Python &str; function. + + </para> + </listitem> + + </varlistentry> + + <varlistentry> + <term>target</term> + + <listitem> + <para> + + A list of Node objects representing + the target or targets to be built + by the command or other action + generated by this function. + The file names of these target(s) + may be extracted using the Python &str; function. + + </para> + </listitem> + + </varlistentry> + + <varlistentry> + <term>env</term> + + <listitem> + <para> + + The &consenv; used for building the target(s). + The generator may use any of the + environment's construction variables + in any way to determine what command + or other action to return. + + </para> + </listitem> + + </varlistentry> + + <varlistentry> + <term>for_signature</term> + + <listitem> + <para> + + A flag that specifies whether the + generator is being called to contribute to a build signature, + as opposed to actually executing the command. + + <!-- XXX NEED MORE HERE, describe generators use in signatures --> + + </para> + </listitem> + + </varlistentry> + + </variablelist> + + <para> + + The &generator; must return a + command string or other action that will be used to + build the specified target(s) from the specified source(s). + + </para> + + <para> + + Once you've defined a &generator;, + you create a &Builder; to use it + by specifying the generator keyword argument + instead of <literal>action</literal>. + + </para> + + + + <programlisting> + def generate_actions(source, target, env, for_signature): + return 'foobuild < %s > %s' % (source[0], target[0]) + bld = Builder(generator = generate_actions, + suffix = '.foo', + src_suffix = '.input') + env = Environment(BUILDERS = {'Foo' : bld}) + env.Foo('file') + </programlisting> + + <screen> + % <userinput>scons -Q</userinput> + foobuild < file.input > file.foo + </screen> + + <para> + + Note that it's illegal to specify both an + <literal>action</literal> + and a + <literal>generator</literal> + for a &Builder;. + + </para> + + </section> + + <section> + <title>Builders That Modify the Target or Source Lists Using an &Emitter;</title> + + <para> + + &SCons; supports the ability for a Builder to modify the + lists of target(s) from the specified source(s). + You do this by defining an &emitter; function + that takes as its arguments + the list of the targets passed to the builder, + the list of the sources passed to the builder, + and the construction environment. + The emitter function should return the modified + lists of targets that should be built + and sources from which the targets will be built. + + </para> + + <para> + + For example, suppose you want to define a Builder + that always calls a <filename>foobuild</filename> program, + and you want to automatically add + a new target file named + <filename>new_target</filename> + and a new source file named + <filename>new_source</filename> + whenever it's called. + The &SConstruct; file might look like this: + + </para> + + + + <programlisting> + def modify_targets(target, source, env): + target.append('new_target') + source.append('new_source') + return target, source + bld = Builder(action = 'foobuild $TARGETS - $SOURCES', + suffix = '.foo', + src_suffix = '.input', + emitter = modify_targets) + env = Environment(BUILDERS = {'Foo' : bld}) + env.Foo('file') + </programlisting> + + <para> + + And would yield the following output: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + foobuild file.foo new_target - file.input new_source + </screen> + + <para> + + One very flexible thing that you can do is + use a construction variable to specify + different emitter functions for different + construction variable. + To do this, specify a string + containing a construction variable + expansion as the emitter when you call + the &Builder; function, + and set that construction variable to + the desired emitter function + in different construction environments: + + </para> + + <programlisting> + bld = Builder(action = 'my_command $SOURCES > $TARGET', + suffix = '.foo', + src_suffix = '.input', + emitter = '$MY_EMITTER') + def modify1(target, source, env): + return target, source + ['modify1.in'] + def modify2(target, source, env): + return target, source + ['modify2.in'] + env1 = Environment(BUILDERS = {'Foo' : bld}, + MY_EMITTER = modify1) + env2 = Environment(BUILDERS = {'Foo' : bld}, + MY_EMITTER = modify2) + env1.Foo('file1') + env2.Foo('file2') + import os + env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() + env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() + + + </programlisting> + + <programlisting> + bld = Builder(action = 'my_command $SOURCES > $TARGET', + suffix = '.foo', + src_suffix = '.input', + emitter = '$MY_EMITTER') + def modify1(target, source, env): + return target, source + ['modify1.in'] + def modify2(target, source, env): + return target, source + ['modify2.in'] + env1 = Environment(BUILDERS = {'Foo' : bld}, + MY_EMITTER = modify1) + env2 = Environment(BUILDERS = {'Foo' : bld}, + MY_EMITTER = modify2) + env1.Foo('file1') + env2.Foo('file2') + + </programlisting> + + <para> + + In this example, the <filename>modify1.in</filename> + and <filename>modify2.in</filename> files + get added to the source lists + of the different commands: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + my_command file1.input modify1.in > file1.foo + my_command file2.input modify2.in > file2.foo + </screen> + + </section> + + <!-- + + <section> + <title>target_factor=, source_factory=</title> + + </section> + + <section> + <title>target_scanner=, source_scanner=</title> + + </section> + + <section> + <title>multi=</title> + + </section> + + <section> + <title>single_source=</title> + + </section> + + <section> + <title>src_builder=</title> + + </section> + + <section> + <title>ensure_suffix=</title> + + </section> + + --> + + <section> + <title>Where To Put Your Custom Builders and Tools</title> + + <para> + + The <filename>site_scons</filename> directory gives you a place to + put Python modules you can import into your &SConscript; files + (<filename>site_scons</filename>), + add-on tools that can integrate into &SCons; + (<filename>site_scons/site_tools</filename>), + and a <filename>site_scons/site_init.py</filename> file that + gets read before any &SConstruct; or &SConscript; file, + allowing you to change &SCons;'s default behavior. + + </para> + + <para> + + If you get a tool from somewhere (the &SCons; wiki or a third party, + for instance) and you'd like to use it in your project, the + <filename>site_scons</filename> dir is the simplest place to put it. + Tools come in two flavors; either a Python function that operates on + an &Environment; or a Python file containing two functions, + <function>exists()</function> and <function>generate()</function>. + + </para> + + <para> + + A single-function Tool can just be included in your + <filename>site_scons/site_init.py</filename> file where it will be + parsed and made available for use. For instance, you could have a + <filename>site_scons/site_init.py</filename> file like this: + + </para> + + <programlisting> + def TOOL_ADD_HEADER(env): + """A Tool to add a header from $HEADER to the source file""" + add_header = Builder(action=['echo "$HEADER" > $TARGET', + 'cat $SOURCE >> $TARGET']) + env.Append(BUILDERS = {'AddHeader' : add_header}) + env['HEADER'] = '' # set default value + </programlisting> + + <para> + + and a &SConstruct; like this: + + </para> + + <programlisting> + # Use TOOL_ADD_HEADER from site_scons/site_init.py + env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") + env.AddHeader('tgt', 'src') + </programlisting> + + <para> + + The <function>TOOL_ADD_HEADER</function> tool method will be + called to add the <function>AddHeader</function> tool to the + environment. + + </para> + + <!-- + <scons_output example="site1" os="posix"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + --> + + <para> + Similarly, a more full-fledged tool with + <function>exists()</function> and <function>generate()</function> + methods can be installed in + <filename>site_scons/site_tools/toolname.py</filename>. Since + <filename>site_scons/site_tools</filename> is automatically added + to the head of the tool search path, any tool found there will be + available to all environments. Furthermore, a tool found there + will override a built-in tool of the same name, so if you need to + change the behavior of a built-in tool, site_scons gives you the + hook you need. + </para> + + <para> + Many people have a library of utility Python functions they'd like + to include in &SConscript;s; just put that module in + <filename>site_scons/my_utils.py</filename> or any valid Python module name of your + choice. For instance you can do something like this in + <filename>site_scons/my_utils.py</filename> to add + <function>build_id</function> and <function>MakeWorkDir</function> + functions: + </para> + + <programlisting> + from SCons.Script import * # for Execute and Mkdir + def build_id(): + """Return a build ID (stub version)""" + return "100" + def MakeWorkDir(workdir): + """Create the specified dir immediately""" + Execute(Mkdir(workdir)) + </programlisting> + + <para> + + And then in your &SConscript; or any sub-&SConscript; anywhere in + your build, you can import <filename>my_utils</filename> and use it: + + </para> + + <programlisting> + import my_utils + print "build_id=" + my_utils.build_id() + my_utils.MakeWorkDir('/tmp/work') + </programlisting> + + <para> + Note that although you can put this library in + <filename>site_scons/site_init.py</filename>, + it is no better there than <filename>site_scons/my_utils.py</filename> + since you still have to import that module into your &SConscript;. + Also note that in order to refer to objects in the SCons namespace + such as &Environment; or &Mkdir; or &Execute; in any file other + than a &SConstruct; or &SConscript; you always need to do + </para> + <programlisting> + from SCons.Script import * + </programlisting> + + <para> + This is true in modules in <filename>site_scons</filename> such as + <filename>site_scons/site_init.py</filename> as well. + </para> + + <para> + + If you have a machine-wide site dir you'd like to use instead of + <filename>./site_scons</filename>, use the + <literal>--site-dir</literal> option to point to your dir. + <filename>site_init.py</filename> and + <filename>site_tools</filename> will be located under that dir. + To avoid using a <filename>site_scons</filename> dir at all, even + if it exists, use the <literal>--no-site-dir</literal> option. + + </para> + + </section> + + + <!-- + + <section> + <title>Builders That Use Other Builders</title> + + <para> + + XXX para + + </para> + + <scons_example name="ex8"> + <file name="SConstruct" printme="1"> + env = Environment() + #env.SourceCode('.', env.BitKeeper('my_command')) + env.Program('hello.c') + </file> + <file name="hello.c"> + hello.c + </file> + </scons_example> + + <scons_output example="ex8"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + </section> + + --> diff --git a/doc/user/builders.xml b/doc/user/builders.xml index e69de29..f3989ef 100644 --- a/doc/user/builders.xml +++ b/doc/user/builders.xml @@ -0,0 +1,57 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<!-- +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> + +<refentry id="Command"> + +<refmeta> +<refentrytitle>Command</refentrytitle> +</refmeta> + +<methodsynopsis> + <methodname>env.Command</methodname> + <methodparam>foo</methodparam> + <methodparam>bar</methodparam> +</methodsynopsis> + +</refentry> +--> + +<para> + +This appendix contains descriptions of all of the +Builders that are <emphasis>potentially</emphasis> +available "out of the box" in this version of SCons. + +</para> + +<variablelist> + +&builders-gen; + +</variablelist> diff --git a/doc/user/caching.xml b/doc/user/caching.xml index e69de29..2348d32 100644 --- a/doc/user/caching.xml +++ b/doc/user/caching.xml @@ -0,0 +1,506 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + + On multi-developer software projects, + you can sometimes speed up every developer's builds a lot by + allowing them to share the derived files that they build. + &SCons; makes this easy, as well as reliable. + + </para> + + <section> + <title>Specifying the Shared Cache Directory</title> + + <para> + + To enable sharing of derived files, + use the &CacheDir; function + in any &SConscript; file: + + </para> + + <programlisting> + CacheDir('/usr/local/build_cache') + </programlisting> + + <para> + + Note that the directory you specify must already exist + and be readable and writable by all developers + who will be sharing derived files. + It should also be in some central location + that all builds will be able to access. + In environments where developers are using separate systems + (like individual workstations) for builds, + this directory would typically be + on a shared or NFS-mounted file system. + + </para> + + <para> + + Here's what happens: + When a build has a &CacheDir; specified, + every time a file is built, + it is stored in the shared cache directory + along with its MD5 build signature. + <footnote> + <para> + Actually, the MD5 signature is used as the name of the file + in the shared cache directory in which the contents are stored. + </para> + </footnote> + On subsequent builds, + before an action is invoked to build a file, + &SCons; will check the shared cache directory + to see if a file with the exact same build + signature already exists. + If so, the derived file will not be built locally, + but will be copied into the local build directory + from the shared cache directory, + like so: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + cc -o hello.o -c hello.c + cc -o hello hello.o + % <userinput>scons -Q -c</userinput> + Removed hello.o + Removed hello + % <userinput>scons -Q</userinput> + Retrieved `hello.o' from cache + Retrieved `hello' from cache + </screen> + + <para> + + Note that the &CacheDir; feature still calculates + MD5 build sigantures for the shared cache file names + even if you configure &SCons; to use timestamps + to decide if files are up to date. + (See the <xref linkend="chap-depends"></xref> + chapter for information about the &Decider; function.) + Consequently, using &CacheDir; may reduce or eliminate any + potential performance improvements + from using timestamps for up-to-date decisions. + + </para> + + </section> + + <section> + <title>Keeping Build Output Consistent</title> + + <para> + + One potential drawback to using a shared cache + is that the output printed by &SCons; + can be inconsistent from invocation to invocation, + because any given file may be rebuilt one time + and retrieved from the shared cache the next time. + This can make analyzing build output more difficult, + especially for automated scripts that + expect consistent output each time. + + </para> + + <para> + + If, however, you use the <literal>--cache-show</literal> option, + &SCons; will print the command line that it + <emphasis>would</emphasis> have executed + to build the file, + even when it is retrieving the file from the shared cache. + This makes the build output consistent + every time the build is run: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + cc -o hello.o -c hello.c + cc -o hello hello.o + % <userinput>scons -Q -c</userinput> + Removed hello.o + Removed hello + % <userinput>scons -Q --cache-show</userinput> + cc -o hello.o -c hello.c + cc -o hello hello.o + </screen> + + <para> + + The trade-off, of course, is that you no longer + know whether or not &SCons; + has retrieved a derived file from cache + or has rebuilt it locally. + + </para> + + </section> + + <section> + <title>Not Using the Shared Cache for Specific Files</title> + + <para> + + You may want to disable caching for certain + specific files in your configuration. + For example, if you only want to put + executable files in a central cache, + but not the intermediate object files, + you can use the &NoCache; + function to specify that the + object files should not be cached: + + </para> + + <programlisting> + env = Environment() + obj = env.Object('hello.c') + env.Program('hello.c') + CacheDir('cache') + NoCache('hello.o') + </programlisting> + + <para> + + Then when you run &scons; after cleaning + the built targets, + it will recompile the object file locally + (since it doesn't exist in the shared cache directory), + but still realize that the shared cache directory + contains an up-to-date executable program + that can be retrieved instead of re-linking: + + </para> + + <!-- + + <scons_output example="ex1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + --> + + <screen> + % <userinput>scons -Q</userinput> + cc -o hello.o -c hello.c + cc -o hello hello.o + % <userinput>scons -Q -c</userinput> + Removed hello.o + Removed hello + % <userinput>scons -Q</userinput> + cc -o hello.o -c hello.c + Retrieved `hello' from cache + </screen> + + </section> + + <section> + <title>Disabling the Shared Cache</title> + + <para> + + Retrieving an already-built file + from the shared cache + is usually a significant time-savings + over rebuilding the file, + but how much of a savings + (or even whether it saves time at all) + can depend a great deal on your + system or network configuration. + For example, retrieving cached files + from a busy server over a busy network + might end up being slower than + rebuilding the files locally. + + </para> + + <para> + + In these cases, you can specify + the <literal>--cache-disable</literal> + command-line option to tell &SCons; + to not retrieve already-built files from the + shared cache directory: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + cc -o hello.o -c hello.c + cc -o hello hello.o + % <userinput>scons -Q -c</userinput> + Removed hello.o + Removed hello + % <userinput>scons -Q</userinput> + Retrieved `hello.o' from cache + Retrieved `hello' from cache + % <userinput>scons -Q -c</userinput> + Removed hello.o + Removed hello + % <userinput>scons -Q --cache-disable</userinput> + cc -o hello.o -c hello.c + cc -o hello hello.o + </screen> + + </section> + + <section> + <title>Populating a Shared Cache With Already-Built Files</title> + + <para> + + Sometimes, you may have one or more derived files + already built in your local build tree + that you wish to make available to other people doing builds. + For example, you may find it more effective to perform + integration builds with the cache disabled + (per the previous section) + and only populate the shared cache directory + with the built files after the integration build + has completed successfully. + This way, the cache will only get filled up + with derived files that are part of a complete, successful build + not with files that might be later overwritten + while you debug integration problems. + + </para> + + <para> + + In this case, you can use the + the <literal>--cache-force</literal> option + to tell &SCons; to put all derived files in the cache, + even if the files already exist in your local tree + from having been built by a previous invocation: + + </para> + + <screen> + % <userinput>scons -Q --cache-disable</userinput> + cc -o hello.o -c hello.c + cc -o hello hello.o + % <userinput>scons -Q -c</userinput> + Removed hello.o + Removed hello + % <userinput>scons -Q --cache-disable</userinput> + cc -o hello.o -c hello.c + cc -o hello hello.o + % <userinput>scons -Q --cache-force</userinput> + scons: `.' is up to date. + % <userinput>scons -Q</userinput> + scons: `.' is up to date. + </screen> + + <para> + + Notice how the above sample run + demonstrates that the <literal>--cache-disable</literal> + option avoids putting the built + <filename>hello.o</filename> + and + <filename>hello</filename> files in the cache, + but after using the <literal>--cache-force</literal> option, + the files have been put in the cache + for the next invocation to retrieve. + + </para> + + </section> + + <section> + <title>Minimizing Cache Contention: the <literal>--random</literal> Option</title> + + <para> + + If you allow multiple builds to update the + shared cache directory simultaneously, + two builds that occur at the same time + can sometimes start "racing" + with one another to build the same files + in the same order. + If, for example, + you are linking multiple files into an executable program: + + </para> + + <programlisting> + Program('prog', + ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c']) + </programlisting> + + <para> + + &SCons; will normally build the input object files + on which the program depends in their normal, sorted order: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + cc -o f1.o -c f1.c + cc -o f2.o -c f2.c + cc -o f3.o -c f3.c + cc -o f4.o -c f4.c + cc -o f5.o -c f5.c + cc -o prog f1.o f2.o f3.o f4.o f5.o + </screen> + + <para> + + But if two such builds take place simultaneously, + they may each look in the cache at nearly the same + time and both decide that <filename>f1.o</filename> + must be rebuilt and pushed into the shared cache directory, + then both decide that <filename>f2.o</filename> + must be rebuilt (and pushed into the shared cache directory), + then both decide that <filename>f3.o</filename> + must be rebuilt... + This won't cause any actual build problems--both + builds will succeed, + generate correct output files, + and populate the cache--but + it does represent wasted effort. + + </para> + + <para> + + To alleviate such contention for the cache, + you can use the <literal>--random</literal> command-line option + to tell &SCons; to build dependencies + in a random order: + + </para> + + <!-- + + The following <screen> output was generated by this: + + <scons_output example="ex-random"> + <scons_output_command>scons -Q - -random</scons_output_command> + </scons_output> + + We captured it directly here to guarantee a "random" order, + guarding against the potential for - -random to happen + to return things in the original sorted order. + + --> + + <screen> + % <userinput>scons -Q --random</userinput> + cc -o f3.o -c f3.c + cc -o f1.o -c f1.c + cc -o f5.o -c f5.c + cc -o f2.o -c f2.c + cc -o f4.o -c f4.c + cc -o prog f1.o f2.o f3.o f4.o f5.o + </screen> + + <para> + + Multiple builds using the <literal>--random</literal> option + will usually build their dependencies in different, + random orders, + which minimizes the chances for a lot of + contention for same-named files + in the shared cache directory. + Multiple simultaneous builds might still race to try to build + the same target file on occasion, + but long sequences of inefficient contention + should be rare. + + </para> + + <para> + + Note, of course, + the <literal>--random</literal> option + will cause the output that &SCons; prints + to be inconsistent from invocation to invocation, + which may be an issue when + trying to compare output from different build runs. + + </para> + + <para> + + If you want to make sure dependencies will be built + in a random order without having to specify + the <literal>--random</literal> on very command line, + you can use the &SetOption; function to + set the <literal>random</literal> option + within any &SConscript; file: + + </para> + + <programlisting> + Program('prog', + ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c']) + + SetOption('random', 1) + Program('prog', + ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c']) + </programlisting> + + </section> + + <!-- + + <section> + <title>Troubleshooting Shared Caching: the &cache-debug; Option</title> + + <para> + + XXX describe the - - cache-debug option + XXX maybe point to the troubleshooting appendix? + + </para> + + </section> + + --> + + <!-- + + <section> + + <para> + + XXX describe CacheDir management: monitoring, deleting, etc. + + </para> + + </section> + + --> diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index 3d48b2a..148922e 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -150,14 +150,14 @@ <screen> % <userinput>scons</userinput> - [?1034hscons: Reading SConscript files ... + scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... ... [build output] ... scons: done building targets. % <userinput>export SCONSFLAGS="-Q"</userinput> % <userinput>scons</userinput> - [?1034h ... [build output] ... + ... [build output] ... </screen> <para> @@ -309,7 +309,7 @@ <screen> % <userinput>scons -Q</userinput> - [?1034hrunning with -j 2 + running with -j 2 scons: `.' is up to date. </screen> @@ -324,7 +324,7 @@ <screen> % <userinput>export NUM_CPU="4"</userinput> % <userinput>scons -Q</userinput> - [?1034hrunning with -j 4 + running with -j 4 scons: `.' is up to date. </screen> @@ -341,11 +341,11 @@ <screen> % <userinput>scons -Q -j 7</userinput> - [?1034hrunning with -j 7 + running with -j 7 scons: `.' is up to date. % <userinput>export NUM_CPU="4"</userinput> % <userinput>scons -Q -j 3</userinput> - [?1034hrunning with -j 3 + running with -j 3 scons: `.' is up to date. </screen> @@ -630,7 +630,7 @@ <screen> % <userinput>scons -Q -n</userinput> - [?1034hInstall file: "foo.in" as "/usr/bin/foo.in" + Install file: "foo.in" as "/usr/bin/foo.in" </screen> <para> @@ -643,7 +643,7 @@ <screen> % <userinput>scons -Q -n --prefix=/tmp/install</userinput> - [?1034hInstall file: "foo.in" as "/tmp/install/usr/bin/foo.in" + Install file: "foo.in" as "/tmp/install/usr/bin/foo.in" </screen> </section> @@ -718,14 +718,15 @@ <screen> % <userinput>scons -Q debug=0</userinput> - [?1034hcc -o prog.o -c prog.c + cc -o prog.o -c prog.c cc -o prog prog.o % <userinput>scons -Q debug=0</userinput> - [?1034hscons: `.' is up to date. + scons: `.' is up to date. % <userinput>scons -Q debug=1</userinput> - [?1034hscons: `.' is up to date. + cc -o prog.o -c -g prog.c + cc -o prog prog.o % <userinput>scons -Q debug=1</userinput> - [?1034hscons: `.' is up to date. + scons: `.' is up to date. </screen> <para> @@ -805,9 +806,9 @@ <screen> % <userinput>scons -Q define=FOO</userinput> - [?1034hcc -o prog.o -c -DFOO prog.c + cc -o prog.o -c -DFOO prog.c % <userinput>scons -Q define=FOO define=BAR</userinput> - [?1034hscons: `.' is up to date. + cc -o prog.o -c -DFOO -DBAR prog.c </screen> <para> @@ -908,7 +909,7 @@ <screen> % <userinput>scons -Q RELEASE=1</userinput> - [?1034hcc -o bar.o -c -DRELEASE_BUILD=1 bar.c + cc -o bar.o -c -DRELEASE_BUILD=1 bar.c cc -o foo.o -c -DRELEASE_BUILD=1 foo.c cc -o foo foo.o bar.o </screen> @@ -971,7 +972,7 @@ <screen> % <userinput>scons -Q -h</userinput> - [?1034h + RELEASE: Set to 1 to build for release default: 0 actual: 0 @@ -1036,7 +1037,7 @@ <screen> % <userinput>scons -Q</userinput> - [?1034hcc -o bar.o -c -DRELEASE_BUILD=1 bar.c + cc -o bar.o -c -DRELEASE_BUILD=1 bar.c cc -o foo.o -c -DRELEASE_BUILD=1 foo.c cc -o foo foo.o bar.o </screen> @@ -1060,7 +1061,7 @@ <screen> % <userinput>scons -Q</userinput> - [?1034hcc -o bar.o -c -DRELEASE_BUILD=0 bar.c + cc -o bar.o -c -DRELEASE_BUILD=0 bar.c cc -o foo.o -c -DRELEASE_BUILD=0 foo.c cc -o foo foo.o bar.o </screen> @@ -1126,12 +1127,12 @@ <screen> % <userinput>scons -Q RELEASE=yes foo.o</userinput> - [?1034hcc -o foo.o -c -DRELEASE_BUILD=True foo.c + cc -o foo.o -c -DRELEASE_BUILD=True foo.c </screen> <screen> % <userinput>scons -Q RELEASE=t foo.o</userinput> - [?1034hcc -o foo.o -c -DRELEASE_BUILD=True foo.c + cc -o foo.o -c -DRELEASE_BUILD=True foo.c </screen> <para> @@ -1157,12 +1158,12 @@ <screen> % <userinput>scons -Q RELEASE=no foo.o</userinput> - [?1034hcc -o foo.o -c -DRELEASE_BUILD=False foo.c + cc -o foo.o -c -DRELEASE_BUILD=False foo.c </screen> <screen> % <userinput>scons -Q RELEASE=f foo.o</userinput> - [?1034hcc -o foo.o -c -DRELEASE_BUILD=False foo.c + cc -o foo.o -c -DRELEASE_BUILD=False foo.c </screen> <para> @@ -1189,8 +1190,7 @@ scons: *** Error converting option: RELEASE Invalid value for boolean option: bad_value - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\__init__.py", line 214, in Update - [?1034h + File "/home/my/project/SConstruct", line 4, in <module> </screen> </section> @@ -1233,11 +1233,11 @@ <screen> % <userinput>scons -Q COLOR=red foo.o</userinput> - [?1034hcc -o foo.o -c -DCOLOR="red" foo.c + cc -o foo.o -c -DCOLOR="red" foo.c % <userinput>scons -Q COLOR=blue foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="blue" foo.c % <userinput>scons -Q COLOR=green foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="green" foo.c </screen> <para> @@ -1253,8 +1253,7 @@ % <userinput>scons -Q COLOR=magenta foo.o</userinput> scons: *** Invalid value for option COLOR: magenta - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\EnumVariable.py", line 51, in _validator - [?1034h + File "/home/my/project/SConstruct", line 5, in <module> </screen> <para> @@ -1293,7 +1292,7 @@ <screen> % <userinput>scons -Q COLOR=navy foo.o</userinput> - [?1034hcc -o foo.o -c -DCOLOR="blue" foo.c + cc -o foo.o -c -DCOLOR="blue" foo.c </screen> <para> @@ -1310,18 +1309,15 @@ % <userinput>scons -Q COLOR=Red foo.o</userinput> scons: *** Invalid value for option COLOR: Red - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\EnumVariable.py", line 51, in _validator - [?1034h + File "/home/my/project/SConstruct", line 5, in <module> % <userinput>scons -Q COLOR=BLUE foo.o</userinput> scons: *** Invalid value for option COLOR: BLUE - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\EnumVariable.py", line 51, in _validator - [?1034h + File "/home/my/project/SConstruct", line 5, in <module> % <userinput>scons -Q COLOR=nAvY foo.o</userinput> scons: *** Invalid value for option COLOR: nAvY - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\EnumVariable.py", line 51, in _validator - [?1034h + File "/home/my/project/SConstruct", line 5, in <module> </screen> <para> @@ -1353,13 +1349,13 @@ <screen> % <userinput>scons -Q COLOR=Red foo.o</userinput> - [?1034hcc -o foo.o -c -DCOLOR="Red" foo.c + cc -o foo.o -c -DCOLOR="Red" foo.c % <userinput>scons -Q COLOR=BLUE foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="BLUE" foo.c % <userinput>scons -Q COLOR=nAvY foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="blue" foo.c % <userinput>scons -Q COLOR=green foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="green" foo.c </screen> <para> @@ -1397,11 +1393,11 @@ <screen> % <userinput>scons -Q COLOR=Red foo.o</userinput> - [?1034hcc -o foo.o -c -DCOLOR="red" foo.c + cc -o foo.o -c -DCOLOR="red" foo.c % <userinput>scons -Q COLOR=nAvY foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="blue" foo.c % <userinput>scons -Q COLOR=GREEN foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="green" foo.c </screen> </section> @@ -1440,9 +1436,9 @@ <screen> % <userinput>scons -Q COLORS=red,blue foo.o</userinput> - [?1034hcc -o foo.o -c -DCOLORS="red blue" foo.c + cc -o foo.o -c -DCOLORS="red blue" foo.c % <userinput>scons -Q COLORS=blue,green,red foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLORS="blue green red" foo.c </screen> <para> @@ -1457,9 +1453,9 @@ <screen> % <userinput>scons -Q COLORS=all foo.o</userinput> - [?1034hcc -o foo.o -c -DCOLORS="red green blue" foo.c + cc -o foo.o -c -DCOLORS="red green blue" foo.c % <userinput>scons -Q COLORS=none foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLORS="" foo.c </screen> <para> @@ -1474,8 +1470,7 @@ scons: *** Error converting option: COLORS Invalid value(s) for option: magenta - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\__init__.py", line 214, in Update - [?1034h + File "/home/my/project/SConstruct", line 5, in <module> </screen> </section> @@ -1515,9 +1510,9 @@ <screen> % <userinput>scons -Q foo.o</userinput> - [?1034hcc -o foo.o -c -DCONFIG_FILE="/etc/my_config" foo.c + cc -o foo.o -c -DCONFIG_FILE="/etc/my_config" foo.c % <userinput>scons -Q CONFIG=/usr/local/etc/other_config foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + scons: `foo.o' is up to date. </screen> <para> @@ -1532,8 +1527,7 @@ % <userinput>scons -Q CONFIG=/does/not/exist foo.o</userinput> scons: *** Path for option CONFIG does not exist: /does/not/exist - File "p:\cyghome\bdeegan\scons\trunk\bootstrap\src\engine\SCons\Variables\PathVariable.py", line 117, in PathExists - [?1034h + File "/home/my/project/SConstruct", line 6, in <module> </screen> <para> @@ -1661,13 +1655,13 @@ <screen> % <userinput>scons -Q foo.o</userinput> - [?1034hcc -o foo.o -c -DPACKAGE="/opt/location" foo.c + cc -o foo.o -c -DPACKAGE="/opt/location" foo.c % <userinput>scons -Q PACKAGE=/usr/local/location foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DPACKAGE="/usr/local/location" foo.c % <userinput>scons -Q PACKAGE=yes foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DPACKAGE="True" foo.c % <userinput>scons -Q PACKAGE=no foo.o</userinput> - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DPACKAGE="False" foo.c </screen> </section> @@ -1787,7 +1781,7 @@ <screen> % <userinput>scons -Q NOT_KNOWN=foo</userinput> - [?1034hUnknown variables: ['NOT_KNOWN'] + Unknown variables: ['NOT_KNOWN'] </screen> <para> @@ -1855,10 +1849,10 @@ <screen> % <userinput>scons -Q</userinput> - [?1034hcc -o foo.o -c foo.c + cc -o foo.o -c foo.c cc -o foo foo.o % <userinput>scons -Q bar</userinput> - [?1034hDon't forget to copy `bar' to the archive! + Don't forget to copy `bar' to the archive! cc -o bar.o -c bar.c cc -o bar bar.o </screen> @@ -1914,12 +1908,12 @@ <screen> % <userinput>scons -Q</userinput> - [?1034hcc -o hello.o -c hello.c + cc -o hello.o -c hello.c cc -o hello hello.o % <userinput>scons -Q</userinput> - [?1034hscons: `hello' is up to date. + scons: `hello' is up to date. % <userinput>scons -Q goodbye</userinput> - [?1034hcc -o goodbye.o -c goodbye.c + cc -o goodbye.o -c goodbye.c cc -o goodbye goodbye.o </screen> @@ -1936,7 +1930,7 @@ <screen> % <userinput>scons -Q .</userinput> - [?1034hcc -o goodbye.o -c goodbye.c + cc -o goodbye.o -c goodbye.c cc -o goodbye goodbye.o cc -o hello.o -c hello.c cc -o hello hello.o @@ -1988,12 +1982,12 @@ <screen> % <userinput>scons -Q</userinput> - [?1034hcc -o prog1.o -c prog1.c + cc -o prog1.o -c prog1.c cc -o prog1 prog1.o cc -o prog3.o -c prog3.c cc -o prog3 prog3.o % <userinput>scons -Q .</userinput> - [?1034hcc -o prog2.o -c prog2.c + cc -o prog2.o -c prog2.c cc -o prog2 prog2.o </screen> @@ -2020,13 +2014,13 @@ <screen> % <userinput>scons -Q</userinput> - [?1034hcc -o prog1/foo.o -c prog1/foo.c + cc -o prog1/foo.o -c prog1/foo.c cc -o prog1/main.o -c prog1/main.c cc -o prog1/main prog1/main.o prog1/foo.o % <userinput>scons -Q</userinput> - [?1034hscons: `prog1' is up to date. + scons: `prog1' is up to date. % <userinput>scons -Q .</userinput> - [?1034hcc -o prog2/bar.o -c prog2/bar.c + cc -o prog2/bar.o -c prog2/bar.c cc -o prog2/main.o -c prog2/main.c cc -o prog2/main prog2/main.o prog2/bar.o </screen> @@ -2056,9 +2050,8 @@ <screen> % <userinput>scons -Q</userinput> scons: *** No targets specified and no Default() targets found. Stop. - [?1034h % <userinput>scons -Q .</userinput> - [?1034hcc -o prog1.o -c prog1.c + cc -o prog1.o -c prog1.c cc -o prog1 prog1.o cc -o prog2.o -c prog2.c cc -o prog2 prog2.o @@ -2101,7 +2094,7 @@ <screen> % <userinput>scons</userinput> - [?1034hscons: Reading SConscript files ... + scons: Reading SConscript files ... DEFAULT_TARGETS is ['prog1'] scons: done reading SConscript files. scons: Building targets ... @@ -2136,7 +2129,7 @@ <screen> % <userinput>scons</userinput> - [?1034hscons: Reading SConscript files ... + scons: Reading SConscript files ... DEFAULT_TARGETS is now ['prog1'] DEFAULT_TARGETS is now ['prog1', 'prog2'] scons: done reading SConscript files. @@ -2231,15 +2224,15 @@ <screen> % <userinput>scons -Q</userinput> - [?1034hBUILD_TARGETS is ['prog1'] + BUILD_TARGETS is ['prog1'] cc -o prog1.o -c prog1.c cc -o prog1 prog1.o % <userinput>scons -Q prog2</userinput> - [?1034hBUILD_TARGETS is ['prog2'] + BUILD_TARGETS is ['prog2'] cc -o prog2.o -c prog2.c cc -o prog2 prog2.o % <userinput>scons -Q -c .</userinput> - [?1034hBUILD_TARGETS is ['.'] + BUILD_TARGETS is ['.'] Removed prog1.o Removed prog1 Removed prog2.o diff --git a/doc/user/depends.xml b/doc/user/depends.xml index 873c5f1..c9207d5 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -347,7 +347,6 @@ % <userinput>touch -t 198901010000 hello.c</userinput> % <userinput>scons -Q hello.o</userinput> cc -o hello.o -c hello.c - cc -o hello hello.o </screen> <para> @@ -987,12 +986,6 @@ <screen> C:\><userinput>scons -Q hello.exe</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ cl /Fohello.obj /c hello.c /nologo /Iinclude /I\home\project\inc link /nologo /OUT:hello.exe hello.obj </screen> @@ -1657,15 +1650,17 @@ <screen> % <userinput>scons -Q hello</userinput> cc -o version.o -c version.c - cc -o version.o -c version.c cc -o hello.o -c hello.c + cc -o hello version.o hello.o + % <userinput>sleep 1</userinput> + % <userinput>scons -Q hello</userinput> + cc -o version.o -c version.c scons: `hello' is up to date. % <userinput>sleep 1</userinput> % <userinput>edit hello.c</userinput> [CHANGE THE CONTENTS OF hello.c] % <userinput>scons -Q hello</userinput> cc -o version.o -c version.c - cc -o version.o -c version.c cc -o hello.o -c hello.c cc -o hello version.o hello.o % <userinput>sleep 1</userinput> diff --git a/doc/user/environments.xml b/doc/user/environments.xml index f81dac7..0746793 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -656,18 +656,6 @@ environment, of directory names, suffixes, etc. <screen> C:\><userinput>scons -Q</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ key = OBJSUFFIX, value = .obj key = LIBSUFFIX, value = .lib key = PROGSUFFIX, value = .exe @@ -963,15 +951,8 @@ environment, of directory names, suffixes, etc. <screen> % <userinput>scons -Q</userinput> - scons: warning: Two different environments were specified for target foo.o, - but they appear to have the same action: CCCom(target, source, env) - File "/home/my/project/SConstruct", line 6, in ? - - scons: warning: Two different environments were specified for target foo, - but they appear to have the same action: Cat(target, source, env) - File "/home/my/project/SConstruct", line 6, in ? - cc -o foo.o -c -g foo.c - cc -o foo foo.o + scons: *** Two environments with different actions were specified for the same target: foo.o + File "/home/my/project/SConstruct", line 6, in <module> </screen> <para> diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml index e7db86d..0bc382e 100644 --- a/doc/user/less-simple.xml +++ b/doc/user/less-simple.xml @@ -100,12 +100,6 @@ <screen> C:\><userinput>scons -Q</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ cl /Fohello.obj /c hello.c /nologo link /nologo /OUT:new_hello.exe hello.obj </screen> @@ -195,12 +189,6 @@ <screen> C:\><userinput>scons -Q</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ cl /Fofile1.obj /c file1.c /nologo cl /Fofile2.obj /c file2.c /nologo cl /Foprog.obj /c prog.c /nologo diff --git a/doc/user/libraries.xml b/doc/user/libraries.xml index 45ad16a..1fa06af 100644 --- a/doc/user/libraries.xml +++ b/doc/user/libraries.xml @@ -73,12 +73,6 @@ <screen> C:\><userinput>scons -Q</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ cl /Fof1.obj /c f1.c /nologo cl /Fof2.obj /c f2.c /nologo cl /Fof3.obj /c f3.c /nologo @@ -207,12 +201,6 @@ <screen> C:\><userinput>scons -Q</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ cl /Fof1.obj /c f1.c /nologo cl /Fof2.obj /c f2.c /nologo cl /Fof3.obj /c f3.c /nologo @@ -294,12 +282,6 @@ <screen> C:\><userinput>scons -Q</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ cl /Fof1.obj /c f1.c /nologo cl /Fof2.obj /c f2.c /nologo cl /Fof3.obj /c f3.c /nologo @@ -428,12 +410,6 @@ <screen> C:\><userinput>scons -Q</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ cl /Foprog.obj /c prog.c /nologo link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj </screen> diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml index 394ec37..8f3436a 100644 --- a/doc/user/nodes.xml +++ b/doc/user/nodes.xml @@ -128,12 +128,6 @@ <screen> C:\><userinput>scons -Q</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ cl /Fogoodbye.obj /c goodbye.c -DGOODBYE cl /Fohello.obj /c hello.c -DHELLO link /nologo /OUT:hello.exe hello.obj goodbye.obj @@ -277,12 +271,6 @@ <screen> C:\><userinput>scons -Q</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ The object file is: hello.obj The program file is: hello.exe cl /Fohello.obj /c hello.c /nologo diff --git a/doc/user/output.xml b/doc/user/output.xml index 8a9b67e..ff39fca 100644 --- a/doc/user/output.xml +++ b/doc/user/output.xml @@ -132,18 +132,6 @@ <screen> C:\><userinput>scons -h</userinput> scons: Reading SConscript files ... - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ scons: done reading SConscript files. Type: 'scons program' to build the production program. diff --git a/doc/user/parseconfig.xml b/doc/user/parseconfig.xml index 4adf97d..3613d77 100644 --- a/doc/user/parseconfig.xml +++ b/doc/user/parseconfig.xml @@ -89,17 +89,8 @@ <screen> % <userinput>scons -Q</userinput> - Package x11 was not found in the pkg-config search path. - Perhaps you should add the directory containing `x11.pc' - to the PKG_CONFIG_PATH environment variable - No package 'x11' found - OSError: 'pkg-config x11 --cflags --libs' exited 1: - File "/home/my/project/SConstruct", line 3: - env.ParseConfig("pkg-config x11 --cflags --libs") - File "bootstrap/src/engine/SCons/Environment.py", line 1474: - None - File "bootstrap/src/engine/SCons/Environment.py", line 593: - None + ['/lib/compat', '/usr/X11/include'] + scons: `.' is up to date. </screen> <para> @@ -140,15 +131,6 @@ <screen> % <userinput>scons -Q</userinput> - Package x11 was not found in the pkg-config search path. - Perhaps you should add the directory containing `x11.pc' - to the PKG_CONFIG_PATH environment variable - No package 'x11' found - OSError: 'pkg-config x11 --cflags --libs' exited 1: - File "/home/my/project/SConstruct", line 2: - env.ParseConfig("pkg-config x11 --cflags --libs") - File "bootstrap/src/engine/SCons/Environment.py", line 1474: - None - File "bootstrap/src/engine/SCons/Environment.py", line 593: - None + ['/usr/X11/include'] + scons: `.' is up to date. </screen> diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml index 1a169ac..632077e 100644 --- a/doc/user/parseflags.xml +++ b/doc/user/parseflags.xml @@ -88,18 +88,6 @@ <screen> C:\><userinput>scons -Q</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ CPPPATH ['/opt/include'] LIBPATH ['/opt/lib'] LIBS ['foo'] diff --git a/doc/user/simple.xml b/doc/user/simple.xml index 3089854..6bd70b0 100644 --- a/doc/user/simple.xml +++ b/doc/user/simple.xml @@ -106,12 +106,6 @@ <screen> C:\><userinput>scons</userinput> scons: Reading SConscript files ... - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ scons: done reading SConscript files. scons: Building targets ... cl /Fohello.obj /c hello.c /nologo @@ -199,12 +193,6 @@ <screen> C:\><userinput>scons</userinput> scons: Reading SConscript files ... - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ scons: done reading SConscript files. scons: Building targets ... cl /Fohello.obj /c hello.c /nologo @@ -308,12 +296,6 @@ <screen> C:\><userinput>scons</userinput> scons: Reading SConscript files ... - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ scons: done reading SConscript files. scons: Building targets ... cl /Fohello.obj /c hello.c /nologo @@ -321,12 +303,6 @@ scons: done building targets. C:\><userinput>scons -c</userinput> scons: Reading SConscript files ... - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ scons: done reading SConscript files. scons: Cleaning targets ... Removed hello.obj @@ -527,12 +503,6 @@ <screen> C:\><userinput>scons</userinput> scons: Reading SConscript files ... - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ scons: done reading SConscript files. scons: Building targets ... cl /Fohello.obj /c hello.c /nologo @@ -564,12 +534,6 @@ <screen> C:\><userinput>scons -Q</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ cl /Fohello.obj /c hello.c /nologo link /nologo /OUT:hello.exe hello.obj </screen> diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml index 2ac91ec..a3339e0 100644 --- a/doc/user/troubleshoot.xml +++ b/doc/user/troubleshoot.xml @@ -286,7 +286,7 @@ 'DSUFFIXES': ['.d'], 'Dir': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, 'Dirs': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, - 'ENV': {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'}, + 'ENV': { 'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'}, 'ESCAPE': <function escape at 0x700000>, 'File': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, 'HOST_ARCH': None, @@ -341,18 +341,6 @@ <screen> C:\><userinput>scons</userinput> scons: Reading SConscript files ... - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ { 'BUILDERS': {'_InternalInstall': <function InstallBuilderWrapper at 0x700000>, 'Object': <SCons.Builder.CompositeBuilder instance at 0x700000>, 'PCH': <SCons.Builder.BuilderBase instance at 0x700000>, 'RES': <SCons.Builder.BuilderBase instance at 0x700000>, 'SharedObject': <SCons.Builder.CompositeBuilder instance at 0x700000>, 'StaticObject': <SCons.Builder.CompositeBuilder instance at 0x700000>, '_InternalInstallAs': <function InstallAsBuilderWrapper at 0x700000>}, 'CC': 'cl', 'CCCOM': <SCons.Action.FunctionAction instance at 0x700000>, @@ -391,7 +379,7 @@ 'DSUFFIXES': ['.d'], 'Dir': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, 'Dirs': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, - 'ENV': { 'PATH': 'C:/WINDOWS\\System32', + 'ENV': { 'PATH': 'C:\\WINDOWS\\System32', 'PATHEXT': '.COM;.EXE;.BAT;.CMD', 'SystemRoot': 'C:\\WINDOWS'}, 'ESCAPE': <function escape at 0x700000>, @@ -501,7 +489,7 @@ <screen> % <userinput>scons</userinput> scons: Reading SConscript files ... - {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'} + { 'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'} scons: done reading SConscript files. scons: Building targets ... scons: `.' is up to date. @@ -517,18 +505,7 @@ <screen> C:\><userinput>scons</userinput> scons: Reading SConscript files ... - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ - { 'PATH': 'C:/WINDOWS\\System32', + { 'PATH': 'C:\\WINDOWS\\System32', 'PATHEXT': '.COM;.EXE;.BAT;.CMD', 'SystemRoot': 'C:\\WINDOWS'} scons: done reading SConscript files. @@ -1144,8 +1121,11 @@ File "bootstrap/src/engine/SCons/Job.py", line 197, in start task.prepare() File "bootstrap/src/engine/SCons/Script/Main.py", line 167, in prepare + return SCons.Taskmaster.OutOfDateTask.prepare(self) File "bootstrap/src/engine/SCons/Taskmaster.py", line 190, in prepare + executor.prepare() File "bootstrap/src/engine/SCons/Executor.py", line 397, in prepare + raise SCons.Errors.StopError, msg % (s, self.batches[0].targets[0]) </screen> <para> diff --git a/doc/user/variants.xml b/doc/user/variants.xml index e60dd8c..3ae3e4a 100644 --- a/doc/user/variants.xml +++ b/doc/user/variants.xml @@ -108,18 +108,6 @@ is pretty smart about rebuilding things when you change options. <screen> C:\><userinput>scons -Q OS=windows</userinput> - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ - - scons: warning: No installed VCs - File "<stdin>", line 67, in __call__ - - scons: warning: No version of Visual Studio compiler found - C/C++ compilers most likely not set correctly - File "<stdin>", line 67, in __call__ Install file: "build/windows/world/world.h" as "export/windows/include/world.h" cl /Fobuild\windows\hello\hello.obj /c build\windows\hello\hello.c /nologo /Iexport\windows\include cl /Fobuild\windows\world\world.obj /c build\windows\world\world.c /nologo /Iexport\windows\include |