From 7d46ec3264caa9b1596b688c81739923bfab49df Mon Sep 17 00:00:00 2001 From: bdbaddog Date: Tue, 19 Jan 2010 07:06:10 +0000 Subject: [PATCH] rebuilt docs git-svn-id: http://scons.tigris.org/svn/scons/trunk@4636 fdb21ef1-2011-0410-befe-b5e4ea1792b1 --- doc/user/add-method.xml | 41 +- doc/user/alias.xml | 10 +- doc/user/builders-built-in.xml | 223 ++++++-- doc/user/builders-commands.xml | 59 ++ doc/user/builders-writing.xml | 957 +++++++++++++++++++++++++++++++++ doc/user/builders.xml | 57 ++ doc/user/caching.xml | 506 +++++++++++++++++ doc/user/command-line.xml | 145 +++-- doc/user/depends.xml | 13 +- doc/user/environments.xml | 23 +- doc/user/less-simple.xml | 12 - doc/user/libraries.xml | 24 - doc/user/nodes.xml | 12 - doc/user/output.xml | 12 - doc/user/parseconfig.xml | 26 +- doc/user/parseflags.xml | 12 - doc/user/simple.xml | 36 -- doc/user/troubleshoot.xml | 34 +- 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 8e078fd5..d4a484e9 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -56,7 +56,7 @@ % scons -Q / - [?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 @@ % scons -Q - [?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 @@ -110,40 +110,9 @@ C:\>scons -Q - 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 diff --git a/doc/user/alias.xml b/doc/user/alias.xml index 9c4a179d..f285d70d 100644 --- a/doc/user/alias.xml +++ b/doc/user/alias.xml @@ -46,7 +46,7 @@ % scons -Q install - [?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" @@ -86,23 +86,23 @@ % scons -Q install-bin - [?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" % scons -Q install-lib - [?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" % scons -Q -c / - [?1034hRemoved foo.o + Removed foo.o Removed foo Removed /usr/bin/foo Removed bar.o Removed libbar.a Removed /usr/lib/libbar.a % scons -Q install - [?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 cb7fb70e..738683bc 100644 --- a/doc/user/builders-built-in.xml +++ b/doc/user/builders-built-in.xml @@ -144,7 +144,7 @@ % scons -Q - [?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 @@ -157,40 +157,9 @@ C:\>scons -Q - 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 @@ -758,7 +727,7 @@ % scons -Q . - [?1034htar -c -f out1.tar file1 file2 + tar -c -f out1.tar file1 file2 tar -c -f out2.tar directory @@ -784,3 +753,185 @@ % scons -Q . + tar -c -z -f out.tar.gz directory + + + + + 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: + + + + + env = Environment(TARFLAGS = '-c -z', + TARSUFFIX = '.tgz') + env.Tar('out', 'directory') + + + + % scons -Q . + tar -c -z -f out.tgz directory + + + + +
+ The &Zip; Builder + + + + 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: + + + + + env = Environment() + env.Zip('out', ['file1', 'file2']) + + + + + Your output will reflect the fact + that an internal Python function + is being used to create the output ZIP archive: + + + + + % scons -Q . + zip(["out.zip"], ["file1", "file2"]) + + + + + If you're using Python version 1.5.2 to run &SCons;, + then &SCons; will try to use an external + &zip; program as follows: + + + + + % scons -Q . + zip /home/my/project/zip.out file1 file2 + + +
+ + + +
+ Java + + + + &SCons; provides Builder objects + for creating various types of Java output files. + + + +
+ Building Class Files: the &Java; Builder + + + + The &b-link-Java; builder takes one or more input + .java files + and turns them into one or more + .class files + Unlike most builders, however, + the &Java; builder takes + target and source directories, + not files, as input. + + + + + env = Environment() + env.Java(target = 'classes', source = 'src') + + + + + The &Java; builder will then + search the specified source directory + tree for all .java files, + and pass any out-of-date + + + + + XXX Java() screen + + +
+ +
+ The &Jar; Builder + + + + XXX The &Jar; builder object + + + + + env = Environment() + env.Java(target = 'classes', source = 'src') + env.Jar(target = '', source = 'classes') + + + + XXX Jar() screen + + +
+ +
+ Building C header and stub files: the &JavaH; Builder + + + + XXX JavaH() para + + + + + XXX JavaH() programlisting + + + + XXX JavaH() screen + + +
+ +
+ Building RMI stub and skeleton class files: the &RMIC; Builder + + + + XXX RMIC() para + + + + + XXX RMIC() programlisting + + + + XXX RMIC() screen + + +
+ +
diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml index 23fe4ce4..fcb2a96d 100644 --- a/doc/user/builders-commands.xml +++ b/doc/user/builders-commands.xml @@ -85,3 +85,62 @@ % scons -Q + sed 's/x/y/' < foo.in > foo.out + + + + + This is often more convenient than + creating a &Builder; object + and adding it to the &cv-link-BUILDERS; variable + of a &consenv; + + + + + + Note that the action you specify to the + &Command; &Builder; can be any legal &SCons; &Action;, + such as a Python function: + + + + + env = Environment() + def build(target, source, env): + # Whatever it takes to build + return None + env.Command('foo.out', 'foo.in', build) + + + + + Which executes as follows: + + + + + % scons -Q + build(["foo.out"], ["foo.in"]) + + + + + 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: + + + + + env.Command('${SOURCE.basename}.out', 'foo.in', build) + + + + + + which does the same thing as the previous example, but allows you + to avoid repeating yourself. + + + diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index e69de29b..3932181b 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -0,0 +1,957 @@ + + + + + + + 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.) + + + +
+ Writing Builders That Execute External Commands + + + + 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 + foobuild, + creating that &Builder; might look like: + + + + + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + + + + + All the above line does is create a free-standing + &Builder; object. + The next section will show us how to actually use it. + + + +
+ +
+ Attaching a Builder to a &ConsEnv; + + + + 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 + Foo, + our &SConstruct; file might look like: + + + + + + + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + env = Environment(BUILDERS = {'Foo' : bld}) + + + + + With the &Builder; attached to our &consenv; + with the name Foo, + we can now actually call it like so: + + + + + env.Foo('file.foo', 'file.input') + + + + + Then when we run &SCons; it looks like: + + + + + % scons -Q + foobuild < file.input > file.foo + + + + + 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: + + + + + + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + env = Environment(BUILDERS = {'Foo' : bld}) + env.Foo('file.foo', 'file.input') + env.Program('hello.c') + + + + % scons -Q + AttributeError: SConsEnvironment instance has no attribute 'Program': + File "/home/my/project/SConstruct", line 4: + env.Program('hello.c') + + + + + 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: + + + + + + + env = Environment() + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + env.Append(BUILDERS = {'Foo' : bld}) + env.Foo('file.foo', 'file.input') + env.Program('hello.c') + + + + + Or you can explicitly set the appropriately-named + key in the &cv-BUILDERS; dictionary: + + + + + env = Environment() + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + env['BUILDERS']['Foo'] = bld + env.Foo('file.foo', 'file.input') + env.Program('hello.c') + + + + + Either way, the same &consenv; + can then use both the newly-defined + Foo &Builder; + and the default &b-link-Program; &Builder;: + + + + + % scons -Q + foobuild < file.input > file.foo + cc -o hello.o -c hello.c + cc -o hello hello.o + + +
+ +
+ Letting &SCons; Handle The File Suffixes + + + + 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 Foo + &Builder; to build the file.foo + target file from the file.input source file, + you can give the .foo + and .input suffixes to the &Builder;, + making for more compact and readable calls to + the Foo &Builder;: + + + + + + + bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + suffix = '.foo', + src_suffix = '.input') + env = Environment(BUILDERS = {'Foo' : bld}) + env.Foo('file1') + env.Foo('file2') + + + + % scons -Q + foobuild < file1.input > file1.foo + foobuild < file2.input > file2.foo + + + + + You can also supply a prefix keyword argument + if it's appropriate to have &SCons; append a prefix + to the beginning of target file names. + + + +
+ +
+ Builders That Execute Python Functions + + + + 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: + + + + + def build_function(target, source, env): + # Code to build "target" from "source" + return None + + + + + The arguments of a &buildfunc; are: + + + + + + + target + + + + + 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. + + + + + + + source + + + + + 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. + + + + + + + env + + + + + 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. + + + + + + + + + + The builder function must + return a 0 or None 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, + + + + + + 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 + action + argument: + + + + + 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') + + + + + 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: + + + + + % scons -Q + build_function(["file.foo"], ["file.input"]) + + +
+ +
+ Builders That Create Actions Using a &Generator; + + + + &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: + + + + + def generate_actions(source, target, env, for_signature): + return 'foobuild < %s > %s' % (target[0], source[0]) + + + + + The arguments of a &generator; are: + + + + + + + source + + + + + 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. + + + + + + + + target + + + + + 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. + + + + + + + + env + + + + + 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. + + + + + + + + for_signature + + + + + A flag that specifies whether the + generator is being called to contribute to a build signature, + as opposed to actually executing the command. + + + + + + + + + + + + + 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). + + + + + + Once you've defined a &generator;, + you create a &Builder; to use it + by specifying the generator keyword argument + instead of action. + + + + + + + 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') + + + + % scons -Q + foobuild < file.input > file.foo + + + + + Note that it's illegal to specify both an + action + and a + generator + for a &Builder;. + + + +
+ +
+ Builders That Modify the Target or Source Lists Using an &Emitter; + + + + &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. + + + + + + For example, suppose you want to define a Builder + that always calls a foobuild program, + and you want to automatically add + a new target file named + new_target + and a new source file named + new_source + whenever it's called. + The &SConstruct; file might look like this: + + + + + + + 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') + + + + + And would yield the following output: + + + + + % scons -Q + foobuild file.foo new_target - file.input new_source + + + + + 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: + + + + + 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() + + + + + + 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') + + + + + + In this example, the modify1.in + and modify2.in files + get added to the source lists + of the different commands: + + + + + % scons -Q + my_command file1.input modify1.in > file1.foo + my_command file2.input modify2.in > file2.foo + + +
+ + + +
+ Where To Put Your Custom Builders and Tools + + + + The site_scons directory gives you a place to + put Python modules you can import into your &SConscript; files + (site_scons), + add-on tools that can integrate into &SCons; + (site_scons/site_tools), + and a site_scons/site_init.py file that + gets read before any &SConstruct; or &SConscript; file, + allowing you to change &SCons;'s default behavior. + + + + + + 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 + site_scons 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, + exists() and generate(). + + + + + + A single-function Tool can just be included in your + site_scons/site_init.py file where it will be + parsed and made available for use. For instance, you could have a + site_scons/site_init.py file like this: + + + + + 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 + + + + + and a &SConstruct; like this: + + + + + # Use TOOL_ADD_HEADER from site_scons/site_init.py + env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") + env.AddHeader('tgt', 'src') + + + + + The TOOL_ADD_HEADER tool method will be + called to add the AddHeader tool to the + environment. + + + + + + + Similarly, a more full-fledged tool with + exists() and generate() + methods can be installed in + site_scons/site_tools/toolname.py. Since + site_scons/site_tools 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. + + + + Many people have a library of utility Python functions they'd like + to include in &SConscript;s; just put that module in + site_scons/my_utils.py or any valid Python module name of your + choice. For instance you can do something like this in + site_scons/my_utils.py to add + build_id and MakeWorkDir + functions: + + + + 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)) + + + + + And then in your &SConscript; or any sub-&SConscript; anywhere in + your build, you can import my_utils and use it: + + + + + import my_utils + print "build_id=" + my_utils.build_id() + my_utils.MakeWorkDir('/tmp/work') + + + + Note that although you can put this library in + site_scons/site_init.py, + it is no better there than site_scons/my_utils.py + 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 + + + from SCons.Script import * + + + + This is true in modules in site_scons such as + site_scons/site_init.py as well. + + + + + If you have a machine-wide site dir you'd like to use instead of + ./site_scons, use the + --site-dir option to point to your dir. + site_init.py and + site_tools will be located under that dir. + To avoid using a site_scons dir at all, even + if it exists, use the --no-site-dir option. + + + +
+ + + diff --git a/doc/user/builders.xml b/doc/user/builders.xml index e69de29b..f3989ef3 100644 --- a/doc/user/builders.xml +++ b/doc/user/builders.xml @@ -0,0 +1,57 @@ + + + + + + +This appendix contains descriptions of all of the +Builders that are potentially +available "out of the box" in this version of SCons. + + + + + +&builders-gen; + + diff --git a/doc/user/caching.xml b/doc/user/caching.xml index e69de29b..2348d329 100644 --- a/doc/user/caching.xml +++ b/doc/user/caching.xml @@ -0,0 +1,506 @@ + + + + + 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. + + + +
+ Specifying the Shared Cache Directory + + + + To enable sharing of derived files, + use the &CacheDir; function + in any &SConscript; file: + + + + + CacheDir('/usr/local/build_cache') + + + + + 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. + + + + + + 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. + + + Actually, the MD5 signature is used as the name of the file + in the shared cache directory in which the contents are stored. + + + 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: + + + + + % scons -Q + cc -o hello.o -c hello.c + cc -o hello hello.o + % scons -Q -c + Removed hello.o + Removed hello + % scons -Q + Retrieved `hello.o' from cache + Retrieved `hello' from cache + + + + + 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 + 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. + + + +
+ +
+ Keeping Build Output Consistent + + + + 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. + + + + + + If, however, you use the --cache-show option, + &SCons; will print the command line that it + would 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: + + + + + % scons -Q + cc -o hello.o -c hello.c + cc -o hello hello.o + % scons -Q -c + Removed hello.o + Removed hello + % scons -Q --cache-show + cc -o hello.o -c hello.c + cc -o hello hello.o + + + + + 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. + + + +
+ +
+ Not Using the Shared Cache for Specific Files + + + + 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: + + + + + env = Environment() + obj = env.Object('hello.c') + env.Program('hello.c') + CacheDir('cache') + NoCache('hello.o') + + + + + 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: + + + + + + + % scons -Q + cc -o hello.o -c hello.c + cc -o hello hello.o + % scons -Q -c + Removed hello.o + Removed hello + % scons -Q + cc -o hello.o -c hello.c + Retrieved `hello' from cache + + +
+ +
+ Disabling the Shared Cache + + + + 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. + + + + + + In these cases, you can specify + the --cache-disable + command-line option to tell &SCons; + to not retrieve already-built files from the + shared cache directory: + + + + + % scons -Q + cc -o hello.o -c hello.c + cc -o hello hello.o + % scons -Q -c + Removed hello.o + Removed hello + % scons -Q + Retrieved `hello.o' from cache + Retrieved `hello' from cache + % scons -Q -c + Removed hello.o + Removed hello + % scons -Q --cache-disable + cc -o hello.o -c hello.c + cc -o hello hello.o + + +
+ +
+ Populating a Shared Cache With Already-Built Files + + + + 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. + + + + + + In this case, you can use the + the --cache-force 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: + + + + + % scons -Q --cache-disable + cc -o hello.o -c hello.c + cc -o hello hello.o + % scons -Q -c + Removed hello.o + Removed hello + % scons -Q --cache-disable + cc -o hello.o -c hello.c + cc -o hello hello.o + % scons -Q --cache-force + scons: `.' is up to date. + % scons -Q + scons: `.' is up to date. + + + + + Notice how the above sample run + demonstrates that the --cache-disable + option avoids putting the built + hello.o + and + hello files in the cache, + but after using the --cache-force option, + the files have been put in the cache + for the next invocation to retrieve. + + + +
+ +
+ Minimizing Cache Contention: the <literal>--random</literal> Option + + + + 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: + + + + + Program('prog', + ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c']) + + + + + &SCons; will normally build the input object files + on which the program depends in their normal, sorted order: + + + + + % scons -Q + 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 + + + + + But if two such builds take place simultaneously, + they may each look in the cache at nearly the same + time and both decide that f1.o + must be rebuilt and pushed into the shared cache directory, + then both decide that f2.o + must be rebuilt (and pushed into the shared cache directory), + then both decide that f3.o + 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. + + + + + + To alleviate such contention for the cache, + you can use the --random command-line option + to tell &SCons; to build dependencies + in a random order: + + + + + + + % scons -Q --random + 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 + + + + + Multiple builds using the --random 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. + + + + + + Note, of course, + the --random 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. + + + + + + If you want to make sure dependencies will be built + in a random order without having to specify + the --random on very command line, + you can use the &SetOption; function to + set the random option + within any &SConscript; file: + + + + + 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']) + + +
+ + + + diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index 3d48b2a7..148922eb 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -150,14 +150,14 @@ % scons - [?1034hscons: Reading SConscript files ... + scons: Reading SConscript files ... scons: done reading SConscript files. scons: Building targets ... ... [build output] ... scons: done building targets. % export SCONSFLAGS="-Q" % scons - [?1034h ... [build output] ... + ... [build output] ... @@ -309,7 +309,7 @@ % scons -Q - [?1034hrunning with -j 2 + running with -j 2 scons: `.' is up to date. @@ -324,7 +324,7 @@ % export NUM_CPU="4" % scons -Q - [?1034hrunning with -j 4 + running with -j 4 scons: `.' is up to date. @@ -341,11 +341,11 @@ % scons -Q -j 7 - [?1034hrunning with -j 7 + running with -j 7 scons: `.' is up to date. % export NUM_CPU="4" % scons -Q -j 3 - [?1034hrunning with -j 3 + running with -j 3 scons: `.' is up to date. @@ -630,7 +630,7 @@ % scons -Q -n - [?1034hInstall file: "foo.in" as "/usr/bin/foo.in" + Install file: "foo.in" as "/usr/bin/foo.in" @@ -643,7 +643,7 @@ % scons -Q -n --prefix=/tmp/install - [?1034hInstall file: "foo.in" as "/tmp/install/usr/bin/foo.in" + Install file: "foo.in" as "/tmp/install/usr/bin/foo.in" @@ -718,14 +718,15 @@ % scons -Q debug=0 - [?1034hcc -o prog.o -c prog.c + cc -o prog.o -c prog.c cc -o prog prog.o % scons -Q debug=0 - [?1034hscons: `.' is up to date. + scons: `.' is up to date. % scons -Q debug=1 - [?1034hscons: `.' is up to date. + cc -o prog.o -c -g prog.c + cc -o prog prog.o % scons -Q debug=1 - [?1034hscons: `.' is up to date. + scons: `.' is up to date. @@ -805,9 +806,9 @@ % scons -Q define=FOO - [?1034hcc -o prog.o -c -DFOO prog.c + cc -o prog.o -c -DFOO prog.c % scons -Q define=FOO define=BAR - [?1034hscons: `.' is up to date. + cc -o prog.o -c -DFOO -DBAR prog.c @@ -908,7 +909,7 @@ % scons -Q RELEASE=1 - [?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 @@ -971,7 +972,7 @@ % scons -Q -h - [?1034h + RELEASE: Set to 1 to build for release default: 0 actual: 0 @@ -1036,7 +1037,7 @@ % scons -Q - [?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 @@ -1060,7 +1061,7 @@ % scons -Q - [?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 @@ -1126,12 +1127,12 @@ % scons -Q RELEASE=yes foo.o - [?1034hcc -o foo.o -c -DRELEASE_BUILD=True foo.c + cc -o foo.o -c -DRELEASE_BUILD=True foo.c % scons -Q RELEASE=t foo.o - [?1034hcc -o foo.o -c -DRELEASE_BUILD=True foo.c + cc -o foo.o -c -DRELEASE_BUILD=True foo.c @@ -1157,12 +1158,12 @@ % scons -Q RELEASE=no foo.o - [?1034hcc -o foo.o -c -DRELEASE_BUILD=False foo.c + cc -o foo.o -c -DRELEASE_BUILD=False foo.c % scons -Q RELEASE=f foo.o - [?1034hcc -o foo.o -c -DRELEASE_BUILD=False foo.c + cc -o foo.o -c -DRELEASE_BUILD=False foo.c @@ -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> @@ -1233,11 +1233,11 @@ % scons -Q COLOR=red foo.o - [?1034hcc -o foo.o -c -DCOLOR="red" foo.c + cc -o foo.o -c -DCOLOR="red" foo.c % scons -Q COLOR=blue foo.o - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="blue" foo.c % scons -Q COLOR=green foo.o - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="green" foo.c @@ -1253,8 +1253,7 @@ % scons -Q COLOR=magenta foo.o 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> @@ -1293,7 +1292,7 @@ % scons -Q COLOR=navy foo.o - [?1034hcc -o foo.o -c -DCOLOR="blue" foo.c + cc -o foo.o -c -DCOLOR="blue" foo.c @@ -1310,18 +1309,15 @@ % scons -Q COLOR=Red foo.o 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> % scons -Q COLOR=BLUE foo.o 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> % scons -Q COLOR=nAvY foo.o 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> @@ -1353,13 +1349,13 @@ % scons -Q COLOR=Red foo.o - [?1034hcc -o foo.o -c -DCOLOR="Red" foo.c + cc -o foo.o -c -DCOLOR="Red" foo.c % scons -Q COLOR=BLUE foo.o - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="BLUE" foo.c % scons -Q COLOR=nAvY foo.o - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="blue" foo.c % scons -Q COLOR=green foo.o - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="green" foo.c @@ -1397,11 +1393,11 @@ % scons -Q COLOR=Red foo.o - [?1034hcc -o foo.o -c -DCOLOR="red" foo.c + cc -o foo.o -c -DCOLOR="red" foo.c % scons -Q COLOR=nAvY foo.o - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="blue" foo.c % scons -Q COLOR=GREEN foo.o - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLOR="green" foo.c @@ -1440,9 +1436,9 @@ % scons -Q COLORS=red,blue foo.o - [?1034hcc -o foo.o -c -DCOLORS="red blue" foo.c + cc -o foo.o -c -DCOLORS="red blue" foo.c % scons -Q COLORS=blue,green,red foo.o - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLORS="blue green red" foo.c @@ -1457,9 +1453,9 @@ % scons -Q COLORS=all foo.o - [?1034hcc -o foo.o -c -DCOLORS="red green blue" foo.c + cc -o foo.o -c -DCOLORS="red green blue" foo.c % scons -Q COLORS=none foo.o - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DCOLORS="" foo.c @@ -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> @@ -1515,9 +1510,9 @@ % scons -Q foo.o - [?1034hcc -o foo.o -c -DCONFIG_FILE="/etc/my_config" foo.c + cc -o foo.o -c -DCONFIG_FILE="/etc/my_config" foo.c % scons -Q CONFIG=/usr/local/etc/other_config foo.o - [?1034hscons: `foo.o' is up to date. + scons: `foo.o' is up to date. @@ -1532,8 +1527,7 @@ % scons -Q CONFIG=/does/not/exist foo.o 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> @@ -1661,13 +1655,13 @@ % scons -Q foo.o - [?1034hcc -o foo.o -c -DPACKAGE="/opt/location" foo.c + cc -o foo.o -c -DPACKAGE="/opt/location" foo.c % scons -Q PACKAGE=/usr/local/location foo.o - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DPACKAGE="/usr/local/location" foo.c % scons -Q PACKAGE=yes foo.o - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DPACKAGE="True" foo.c % scons -Q PACKAGE=no foo.o - [?1034hscons: `foo.o' is up to date. + cc -o foo.o -c -DPACKAGE="False" foo.c @@ -1787,7 +1781,7 @@ % scons -Q NOT_KNOWN=foo - [?1034hUnknown variables: ['NOT_KNOWN'] + Unknown variables: ['NOT_KNOWN'] @@ -1855,10 +1849,10 @@ % scons -Q - [?1034hcc -o foo.o -c foo.c + cc -o foo.o -c foo.c cc -o foo foo.o % scons -Q bar - [?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 @@ -1914,12 +1908,12 @@ % scons -Q - [?1034hcc -o hello.o -c hello.c + cc -o hello.o -c hello.c cc -o hello hello.o % scons -Q - [?1034hscons: `hello' is up to date. + scons: `hello' is up to date. % scons -Q goodbye - [?1034hcc -o goodbye.o -c goodbye.c + cc -o goodbye.o -c goodbye.c cc -o goodbye goodbye.o @@ -1936,7 +1930,7 @@ % scons -Q . - [?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 @@ % scons -Q - [?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 % scons -Q . - [?1034hcc -o prog2.o -c prog2.c + cc -o prog2.o -c prog2.c cc -o prog2 prog2.o @@ -2020,13 +2014,13 @@ % scons -Q - [?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 % scons -Q - [?1034hscons: `prog1' is up to date. + scons: `prog1' is up to date. % scons -Q . - [?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 @@ -2056,9 +2050,8 @@ % scons -Q scons: *** No targets specified and no Default() targets found. Stop. - [?1034h % scons -Q . - [?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 @@ % scons - [?1034hscons: Reading SConscript files ... + scons: Reading SConscript files ... DEFAULT_TARGETS is ['prog1'] scons: done reading SConscript files. scons: Building targets ... @@ -2136,7 +2129,7 @@ % scons - [?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 @@ % scons -Q - [?1034hBUILD_TARGETS is ['prog1'] + BUILD_TARGETS is ['prog1'] cc -o prog1.o -c prog1.c cc -o prog1 prog1.o % scons -Q prog2 - [?1034hBUILD_TARGETS is ['prog2'] + BUILD_TARGETS is ['prog2'] cc -o prog2.o -c prog2.c cc -o prog2 prog2.o % scons -Q -c . - [?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 873c5f17..c9207d56 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -347,7 +347,6 @@ % touch -t 198901010000 hello.c % scons -Q hello.o cc -o hello.o -c hello.c - cc -o hello hello.o @@ -987,12 +986,6 @@ C:\>scons -Q hello.exe - - 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 @@ -1657,15 +1650,17 @@ % scons -Q hello 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 + % sleep 1 + % scons -Q hello + cc -o version.o -c version.c scons: `hello' is up to date. % sleep 1 % edit hello.c [CHANGE THE CONTENTS OF hello.c] % scons -Q hello 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 % sleep 1 diff --git a/doc/user/environments.xml b/doc/user/environments.xml index f81dac7b..0746793b 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -656,18 +656,6 @@ environment, of directory names, suffixes, etc. C:\>scons -Q - - 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. % scons -Q - 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> diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml index e7db86da..0bc382ef 100644 --- a/doc/user/less-simple.xml +++ b/doc/user/less-simple.xml @@ -100,12 +100,6 @@ C:\>scons -Q - - 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 @@ -195,12 +189,6 @@ C:\>scons -Q - - 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 45ad16a7..1fa06af9 100644 --- a/doc/user/libraries.xml +++ b/doc/user/libraries.xml @@ -73,12 +73,6 @@ C:\>scons -Q - - 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 @@ C:\>scons -Q - - 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 @@ C:\>scons -Q - - 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 @@ C:\>scons -Q - - 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 diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml index 394ec372..8f3436a4 100644 --- a/doc/user/nodes.xml +++ b/doc/user/nodes.xml @@ -128,12 +128,6 @@ C:\>scons -Q - - 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 @@ C:\>scons -Q - - 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 8a9b67e4..ff39fca0 100644 --- a/doc/user/output.xml +++ b/doc/user/output.xml @@ -132,18 +132,6 @@ C:\>scons -h 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 4adf97d2..3613d77c 100644 --- a/doc/user/parseconfig.xml +++ b/doc/user/parseconfig.xml @@ -89,17 +89,8 @@ % scons -Q - 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. @@ -140,15 +131,6 @@ % scons -Q - 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. diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml index 1a169ac2..632077e5 100644 --- a/doc/user/parseflags.xml +++ b/doc/user/parseflags.xml @@ -88,18 +88,6 @@ C:\>scons -Q - - 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 30898546..6bd70b0b 100644 --- a/doc/user/simple.xml +++ b/doc/user/simple.xml @@ -106,12 +106,6 @@ C:\>scons 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 @@ C:\>scons 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 @@ C:\>scons 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:\>scons -c 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 @@ C:\>scons 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 @@ C:\>scons -Q - - 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 diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml index 2ac91ec2..a3339e03 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 @@ C:\>scons 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 @@ % scons 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 @@ C:\>scons 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]) diff --git a/doc/user/variants.xml b/doc/user/variants.xml index e60dd8c2..3ae3e4a8 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. C:\>scons -Q OS=windows - - 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 -- 2.26.2