From dd8e3d92024d02b4e133b0e0624886ce4cd8fe11 Mon Sep 17 00:00:00 2001 From: Steven Knight Date: Thu, 23 Oct 2003 16:14:15 +0000 Subject: Initialize the new branch. --- README | 34 ++--- SConstruct | 2 +- debian/changelog | 7 + doc/scons.mod | 18 +++ doc/user/builders-writing.in | 158 ++++++++++++++++------- doc/user/builders-writing.sgml | 107 +++++++++------- doc/user/depends.in | 285 +++++++++++++++++++++++------------------ doc/user/depends.sgml | 258 +++++++++++++++++++++++-------------- doc/user/hierarchy.in | 146 +++++++++++++++++---- doc/user/hierarchy.sgml | 172 ++++++++++++++++++------- doc/user/main.in | 30 ++++- doc/user/main.sgml | 30 ++++- doc/user/preface.in | 29 +++-- doc/user/preface.sgml | 33 +++-- doc/user/repositories.in | 52 ++++---- doc/user/repositories.sgml | 56 +++++--- doc/user/scanners.in | 210 ++++++++++++++++++++++++++++-- doc/user/scanners.sgml | 196 ++++++++++++++++++++++++++-- doc/user/separate.in | 149 +++++++++++++-------- doc/user/separate.sgml | 144 ++++++++++++--------- doc/user/sourcecode.in | 35 +++-- doc/user/sourcecode.sgml | 61 +++++---- doc/user/variants.in | 114 +++++++---------- doc/user/variants.sgml | 123 +++++------------- rpm/scons.spec.in | 2 +- src/CHANGES.txt | 5 +- src/README.txt | 4 +- src/RELEASE.txt | 2 +- src/setupTests.py | 2 +- 29 files changed, 1662 insertions(+), 802 deletions(-) diff --git a/README b/README index 3e0d33a..6c921f1 100644 --- a/README +++ b/README @@ -56,8 +56,8 @@ part of Python until Python version 1.6, so if your system is running Python 1.5.2, you may not have distutils installed. If you are running Python version 1.6 or later, you should be fine. -NOTE TO RED HAT USERS: All Red Hat Linux versions up to 7.3 still ship -Python 1.5.2 as the default, so you probably do *not* have distutils +NOTE TO RED HAT USERS: Red Hat shipped Python 1.5.2 as the default all +the way up to Red Hat Linux 7.3, so you probably do *not* have distutils installed, unless you have already done so manually or are running Red Hat 8.0 or later. @@ -66,12 +66,12 @@ In this case, your options are: -- (Optional.) Install from a pre-packaged SCons package that does not require distutils: - Red Hat Linux scons-0.92-1.noarch.rpm + Red Hat Linux scons-0.93-1.noarch.rpm - Debian GNU/Linux scons_0.92-1_all.deb + Debian GNU/Linux scons_0.93-1_all.deb (or use apt-get) - Windows scons-0.92.win32.exe + Windows scons-0.93.win32.exe -- (Recommended.) Download the latest distutils package from the following URL: @@ -218,18 +218,18 @@ more typing: Depending on the utilities installed on your system, any or all of the following packages will be built: - build/dist/scons-0.92-1.noarch.rpm - build/dist/scons-0.92-1.src.rpm - build/dist/scons-0.92.linux-i686.tar.gz - build/dist/scons-0.92.tar.gz - build/dist/scons-0.92.win32.exe - build/dist/scons-0.92.zip - build/dist/scons-doc-0.92.tar.gz - build/dist/scons-local-0.92.tar.gz - build/dist/scons-local-0.92.zip - build/dist/scons-src-0.92.tar.gz - build/dist/scons-src-0.92.zip - build/dist/scons_0.92-1_all.deb + build/dist/scons-0.93-1.noarch.rpm + build/dist/scons-0.93-1.src.rpm + build/dist/scons-0.93.linux-i686.tar.gz + build/dist/scons-0.93.tar.gz + build/dist/scons-0.93.win32.exe + build/dist/scons-0.93.zip + build/dist/scons-doc-0.93.tar.gz + build/dist/scons-local-0.93.tar.gz + build/dist/scons-local-0.93.zip + build/dist/scons-src-0.93.tar.gz + build/dist/scons-src-0.93.zip + build/dist/scons_0.93-1_all.deb The SConstruct file is supposed to be smart enough to avoid trying to build packages for which you don't have the proper utilities installed. diff --git a/SConstruct b/SConstruct index e1cb341..ec03578 100644 --- a/SConstruct +++ b/SConstruct @@ -39,7 +39,7 @@ import sys import time project = 'scons' -default_version = '0.92' +default_version = '0.93' copyright = "Copyright (c) %s Steven Knight" % copyright_years Default('.') diff --git a/debian/changelog b/debian/changelog index fe292e1..449c177 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,10 @@ +scons (0.93-1) unstable; urgency=low + + * Fourth beta release. + + -- Steven Knight Thu, 23 Oct 2003 07:26:55 -0500 + + scons (0.92-1) unstable; urgency=low * Third beta release. diff --git a/doc/scons.mod b/doc/scons.mod index 19190b2..958444d 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -73,6 +73,7 @@ --implicit-cache"> --implicit-deps-changed"> --implicit-deps-unchanged"> +-Q"> +bar"> common1.c"> common2.c"> goodbye"> +file.dll"> +file.lib"> +file.o"> +file.obj"> +foo"> hello"> hello.c"> hello.exe"> hello.h"> hello.o"> +libfile_a"> +libfile_so"> prog"> prog1"> prog2"> diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in index d911f6c..50c9114 100644 --- a/doc/user/builders-writing.in +++ b/doc/user/builders-writing.in @@ -167,17 +167,22 @@ This functionality could be invoked as in the following example: bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() env.Foo('file.foo', 'file.input') file.input + + cat + - + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) - + @@ -197,7 +202,7 @@ This functionality could be invoked as in the following example: - scons + scons -Q @@ -229,23 +234,8 @@ This functionality could be invoked as in the following example: - - - scons + scons -Q @@ -260,6 +250,8 @@ This functionality could be invoked as in the following example: env = Environment() + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env.Append(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') @@ -271,8 +263,19 @@ This functionality could be invoked as in the following example: hello.c + + cat + + + 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 @@ -280,13 +283,13 @@ This functionality could be invoked as in the following example: - + env = Environment() bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env['BUILDERS']['Foo'] = bld env.Foo('file.foo', 'file.input') env.Program('hello.c') - + @@ -298,7 +301,7 @@ This functionality could be invoked as in the following example: - scons + scons -Q @@ -324,11 +327,13 @@ This functionality could be invoked as in the following example: - - bld = Builder(action = 'foobuild < $TARGET > $SOURCE', + + bld = Builder(action = 'foobuild < $SOURCE > $TARGET', suffix = '.foo', src_suffix = '.input') env = Environment(BUILDERS = {'Foo' : bld}) + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() env.Foo('file1') env.Foo('file2') @@ -338,10 +343,22 @@ This functionality could be invoked as in the following example: file2.input + + cat + + + bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + suffix = '.foo', + src_suffix = '.input') + env = Environment(BUILDERS = {'Foo' : bld}) + env.Foo('file1') + env.Foo('file2') + + - scons + scons -Q @@ -370,7 +387,7 @@ This functionality could be invoked as in the following example: def build_function(target, source, env): - # XXX + # Code to build "target" from "source" return None @@ -459,7 +476,7 @@ This functionality could be invoked as in the following example: def build_function(target, source, env): - # XXX + # Code to build "target" from "source" return None bld = Builder(action = build_function, suffix = '.foo', @@ -482,7 +499,7 @@ This functionality could be invoked as in the following example: - scons + scons -Q @@ -494,14 +511,16 @@ This functionality could be invoked as in the following example: &SCons; Builder objects can create an action "on the fly" by using a function called a &generator;. - This provides a great deal of flexibility XXX + 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 XXX + return 'foobuild < %s > %s' % (target[0], source[0]) @@ -575,7 +594,7 @@ This functionality could be invoked as in the following example: generator is being called to contribute to a build signature, as opposed to actually executing the command. - XXX + @@ -602,20 +621,37 @@ This functionality could be invoked as in the following example: - + + 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}) + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() env.Foo('file') file.input + + cat + + + 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 + scons -Q @@ -641,23 +677,46 @@ This functionality could be invoked as in the following example: - - def modify_targets(XXX): - return XXX - bld = Builder(action = 'XXX', + + 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}) + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() env.Foo('file') file.input - + + new_source + + + cat + + + + + 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') + - scons + scons -Q @@ -665,10 +724,10 @@ This functionality could be invoked as in the following example: suffix = '.foo', src_suffix = '.input', emitter = 'MY_EMITTER') - def modify1(XXX): - return XXX - def modify2(XXX): - return XXX + def modify1(target, source, env): + return target, source + def modify2(target, source, env): + return target, source env1 = Environment(BUILDERS = {'Foo' : bld}, MY_EMITTER = modify1) env2 = Environment(BUILDERS = {'Foo' : bld}, @@ -679,6 +738,8 @@ This functionality could be invoked as in the following example: + diff --git a/doc/user/builders-writing.sgml b/doc/user/builders-writing.sgml index 27a48b9..796e199 100644 --- a/doc/user/builders-writing.sgml +++ b/doc/user/builders-writing.sgml @@ -129,7 +129,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $TARGET > $SOURCE') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') @@ -163,8 +163,10 @@ This functionality could be invoked as in the following example: + + - bld = Builder(action = 'foobuild < $TARGET > $SOURCE') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) @@ -186,7 +188,7 @@ This functionality could be invoked as in the following example: - % scons + % scons -Q foobuild < file.input > file.foo @@ -205,26 +207,15 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $TARGET > $SOURCE') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') env.Program('hello.c') - % scons - scons: Reading SConscript files ... - other errors - Traceback (most recent call last): - File "/usr/lib/scons/SCons/Script/__init__.py", line 901, in main - _main() - File "/usr/lib/scons/SCons/Script/__init__.py", line 762, in _main - SCons.Script.SConscript.SConscript(script) - File "/usr/lib/scons/SCons/Script/SConscript.py", line 207, in SConscript - exec _file_ in stack[-1].globals - File "SConstruct", line 4, in ? - env.Program('hello.c') - scons: Environment instance has no attribute 'Program' + % scons -Q + AttributeError: SConsEnvironment instance has no attribute 'Program': @@ -236,9 +227,11 @@ This functionality could be invoked as in the following example: + + env = Environment() - bld = Builder(action = 'foobuild < $TARGET > $SOURCE') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env.Append(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') env.Program('hello.c') @@ -253,7 +246,7 @@ This functionality could be invoked as in the following example: env = Environment() - bld = Builder(action = 'foobuild < $TARGET > $SOURCE') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env['BUILDERS']['Foo'] = bld env.Foo('file.foo', 'file.input') env.Program('hello.c') @@ -269,9 +262,9 @@ This functionality could be invoked as in the following example: - % scons + % scons -Q foobuild < file.input > file.foo - cc -c hello.c -o hello.o + cc -c -o hello.o hello.c cc -o hello hello.o @@ -297,8 +290,10 @@ This functionality could be invoked as in the following example: + + - bld = Builder(action = 'foobuild < $TARGET > $SOURCE', + bld = Builder(action = 'foobuild < $SOURCE > $TARGET', suffix = '.foo', src_suffix = '.input') env = Environment(BUILDERS = {'Foo' : bld}) @@ -307,7 +302,7 @@ This functionality could be invoked as in the following example: - % scons + % scons -Q foobuild < file1.input > file1.foo foobuild < file2.input > file2.foo @@ -338,7 +333,7 @@ This functionality could be invoked as in the following example: def build_function(target, source, env): - # XXX + # Code to build "target" from "source" return None @@ -426,7 +421,7 @@ This functionality could be invoked as in the following example: def build_function(target, source, env): - # XXX + # Code to build "target" from "source" return None bld = Builder(action = build_function, suffix = '.foo', @@ -445,7 +440,7 @@ This functionality could be invoked as in the following example: - % scons + % scons -Q build_function("file.foo", "file.input") @@ -458,14 +453,16 @@ This functionality could be invoked as in the following example: &SCons; Builder objects can create an action "on the fly" by using a function called a &generator;. - This provides a great deal of flexibility XXX + 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 XXX + return 'foobuild < %s > %s' % (target[0], source[0]) @@ -539,7 +536,7 @@ This functionality could be invoked as in the following example: generator is being called to contribute to a build signature, as opposed to actually executing the command. - XXX + @@ -565,7 +562,11 @@ This functionality could be invoked as in the following example: + + + 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') @@ -574,8 +575,8 @@ This functionality could be invoked as in the following example: - % scons - XXX + % scons -Q + foobuild < file.input > file.foo @@ -600,10 +601,14 @@ This functionality could be invoked as in the following example: + + - def modify_targets(XXX): - return XXX - bld = Builder(action = 'XXX', + 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) @@ -612,8 +617,8 @@ This functionality could be invoked as in the following example: - % scons - XXX + % scons -Q + foobuild file.foo new_target - file.input new_source @@ -621,10 +626,10 @@ This functionality could be invoked as in the following example: suffix = '.foo', src_suffix = '.input', emitter = 'MY_EMITTER') - def modify1(XXX): - return XXX - def modify2(XXX): - return XXX + def modify1(target, source, env): + return target, source + def modify2(target, source, env): + return target, source env1 = Environment(BUILDERS = {'Foo' : bld}, MY_EMITTER = modify1) env2 = Environment(BUILDERS = {'Foo' : bld}, @@ -635,6 +640,8 @@ This functionality could be invoked as in the following example: + diff --git a/doc/user/depends.in b/doc/user/depends.in index aa69dc7..bedc91d 100644 --- a/doc/user/depends.in +++ b/doc/user/depends.in @@ -59,8 +59,7 @@ operating system on which the build is performed (as reported by C - env = Environment() - env.Program('hello.c') + Program('hello.c') int main() { printf("Hello, world!\n"); } @@ -68,8 +67,8 @@ operating system on which the build is performed (as reported by C - scons - scons + scons -Q + scons -Q @@ -84,8 +83,8 @@ operating system on which the build is performed (as reported by C - scons hello - scons hello + scons -Q hello + scons -Q hello @@ -133,9 +132,9 @@ operating system on which the build is performed (as reported by C - scons hello + scons -Q hello touch hello.c - scons hello + scons -Q hello @@ -155,26 +154,10 @@ operating system on which the build is performed (as reported by C - scons hello - edit hello.c - scons hello - - - + scons -Q hello + edit hello.c + scons -Q hello + @@ -186,8 +169,7 @@ operating system on which the build is performed (as reported by C - env = Environment() - env.Program('hello.c') + Program('hello.c') SourceSignatures('MD5') @@ -210,8 +192,7 @@ operating system on which the build is performed (as reported by C - env = Environment() - env.Program('hello.c') + Program('hello.c') SourceSignatures('timestamp') @@ -227,11 +208,11 @@ operating system on which the build is performed (as reported by C - - scons hello + + scons -Q hello touch hello.c - scons hello - + scons -Q hello + @@ -247,8 +228,8 @@ operating system on which the build is performed (as reported by C @@ -271,26 +252,10 @@ operating system on which the build is performed (as reported by C - scons hello - edit hello.c - scons hello - - - + scons -Q hello + edit hello.c + scons -Q hello + @@ -324,8 +289,7 @@ operating system on which the build is performed (as reported by C - env = Environment() - env.Program('hello.c') + Program('hello.c') TargetSignatures('build') @@ -344,17 +308,16 @@ operating system on which the build is performed (as reported by C - env = Environment() - env.Program('hello.c') + Program('hello.c') TargetSignatures('content') @@ -376,10 +339,10 @@ operating system on which the build is performed (as reported by C - scons hello - edit hello.c - scons hello - + scons -Q hello + edit hello.c + scons -Q hello + @@ -413,19 +376,18 @@ operating system on which the build is performed (as reported by C - env = Environment(CPPPATH = '.') - hello = env.Program('hello.c') + Program('hello.c', CPPPATH = '.') - #include "hello.h" - int - main() - { - printf("Hello, %s!\n", string); - } + #include "hello.h" + int + main() + { + printf("Hello, %s!\n", string); + } - #define string "world" + #define string "world" @@ -453,7 +415,7 @@ operating system on which the build is performed (as reported by C - The &CPPPATH; assignment in the &Environment; call + The &CPPPATH; value tells &SCons; to look in the current directory ('.') for any files included by C source files @@ -463,11 +425,11 @@ operating system on which the build is performed (as reported by C - scons hello - scons hello - edit hello.h - scons hello - + scons -Q hello + scons -Q hello + edit hello.h + scons -Q hello + @@ -512,13 +474,9 @@ operating system on which the build is performed (as reported by C - - - - - env = Environment(CPPPATH = ['include', '/home/project/inc']) - hello = env.Program('hello.c') + + Program('hello.c', CPPPATH = ['include', '/home/project/inc']) int main() { printf("Hello, world!\n"); } @@ -531,8 +489,8 @@ operating system on which the build is performed (as reported by C - - scons hello + + scons -Q hello @@ -541,8 +499,8 @@ operating system on which the build is performed (as reported by C - - scons hello + + scons -Q hello.exe @@ -590,19 +548,22 @@ operating system on which the build is performed (as reported by C - - scons --implicit-cache hello - scons hello + + scons -Q --implicit-cache hello + scons -Q hello - Or by setting the &implicit_cache; option + If you don't want to specify &implicit-cache; + on the command line each time, + you can make it the default behavior for your build + by setting the &implicit_cache; option in an &SConscript; file: @@ -611,25 +572,52 @@ operating system on which the build is performed (as reported by C - + +
The &implicit-deps-changed; Option - XXX + When using cached implicit dependencies, + sometimes you want to "start fresh" + and have &SCons; re-scan the files + for which it previously cached the dependencies. + For example, + if you have recently installed a new version of + external code that you use for compilation, + the external header files will have changed + and the previously-cached implicit dependencies + will be out of date. + You can update them by + running &SCons; with the &implicit-deps-changed; option: + + + + + scons -Q --implicit-deps-changed hello + scons -Q hello + + + + + In this case, &SCons; will re-scan all of the implicit dependencies + and cache updated copies of the information. @@ -640,7 +628,38 @@ operating system on which the build is performed (as reported by C - XXX + By default when caching dependencies, + &SCons; notices when a file has been modified + and re-scans the file for any updated + implicit dependency information. + Sometimes, however, you may want + to force &SCons; to use the cached implicit dependencies, + even if the source files changed. + This can speed up a build for example, + when you have changed your source files + but know that you haven't changed + any #include lines. + In this case, + you can use the &implicit-deps-unchanged; option: + + + + + scons -Q --implicit-deps-unchanged hello + scons -Q hello + + + + + In this case, + &SCons; will assume that the cached implicit + dependencies are correct and + will not bother to re-scan changed files. + For typical builds after small, + incremental changes to source files, + the savings may not be very big, + but sometimes every bit of + improved performance counts. @@ -662,24 +681,42 @@ operating system on which the build is performed (as reported by C - - env = Environment() - hello = env.Program('hello.c') - env.Ignore(hello, 'hello.h') - + + + hello = Program('hello.c') + Ignore(hello, 'hello.h') + + + #include "hello.h" + int main() { printf("Hello, %s!\n", string); } + + + #define string "world" + + + + - % scons hello - cc -c hello.c -o hello.o - cc -o hello hello.o - % scons hello - scons: `hello' is up to date. - % edit hello.h - [CHANGE THE CONTENTS OF hello.h] - % scons hello - scons: `hello' is up to date. + % scons -Q hello + cc -c -o hello.o hello.c + cc -o hello hello.o + % scons -Q hello + scons: `hello' is up to date. + % edit hello.h + [CHANGE THE CONTENTS OF hello.h] + % scons -Q hello + scons: `hello' is up to date. @@ -718,7 +755,7 @@ operating system on which the build is performed (as reported by C - % scons hello + % scons -Q hello cc -c hello.c -o hello.o cc -o hello hello.o - % scons hello + % scons -Q hello scons: `hello' is up to date. % edit other_file [CHANGE THE CONTENTS OF other_file] - % scons hello + % scons -Q hello cc -c hello.c -o hello.o cc -o hello hello.o diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml index 2049caf..f595e08 100644 --- a/doc/user/depends.sgml +++ b/doc/user/depends.sgml @@ -57,12 +57,14 @@ operating system on which the build is performed (as reported by C + + - % scons - cc -c hello.c -o hello.o + % scons -Q + cc -c -o hello.o hello.c cc -o hello hello.o - % scons - % + % scons -Q + scons: `.' is up to date. @@ -77,12 +79,11 @@ operating system on which the build is performed (as reported by C - % scons hello - cc -c hello.c -o hello.o + % scons -Q hello + cc -c -o hello.o hello.c cc -o hello hello.o - % scons hello + % scons -Q hello scons: `hello' is up to date. - % @@ -130,13 +131,12 @@ operating system on which the build is performed (as reported by C - % scons hello - cc -c hello.c -o hello.o + % scons -Q hello + cc -c -o hello.o hello.c cc -o hello hello.o % touch hello.c - % scons hello + % scons -Q hello scons: `hello' is up to date. - % @@ -156,15 +156,14 @@ operating system on which the build is performed (as reported by C - % scons hello - cc -c hello.c -o hello.o + % scons -Q hello + cc -c -o hello.o hello.c cc -o hello hello.o % edit hello.c [CHANGE THE CONTENTS OF hello.c] - % scons hello - cc -c hello.c -o hello.o + % scons -Q hello + cc -c -o hello.o hello.c cc -o hello hello.o - % @@ -177,8 +176,7 @@ operating system on which the build is performed (as reported by C - env = Environment() - env.Program('hello.c') + Program('hello.c') SourceSignatures('MD5') @@ -200,8 +198,7 @@ operating system on which the build is performed (as reported by C - env = Environment() - env.Program('hello.c') + Program('hello.c') SourceSignatures('timestamp') @@ -214,14 +211,13 @@ operating system on which the build is performed (as reported by C - % scons hello - cc -c hello.c -o hello.o + % scons -Q hello + cc -c -o hello.o hello.c cc -o hello hello.o % touch hello.c - % scons hello - cc -c hello.c -o hello.o + % scons -Q hello + cc -c -o hello.o hello.c cc -o hello hello.o - %
@@ -238,8 +234,8 @@ operating system on which the build is performed (as reported by C @@ -262,15 +258,14 @@ operating system on which the build is performed (as reported by C - % scons hello - cc -c hello.c -o hello.o + % scons -Q hello + cc -c -o hello.o hello.c cc -o hello hello.o % edit hello.c - [CHANGE THE CONTENTS OF hello.c] - % scons hello - cc -c hello.c -o hello.o + [CHANGE THE CONTENTS OF hello.c] + % scons -Q hello + cc -c -o hello.o hello.c cc -o hello hello.o - % @@ -305,8 +300,7 @@ operating system on which the build is performed (as reported by C - env = Environment() - env.Program('hello.c') + Program('hello.c') TargetSignatures('build') @@ -325,16 +319,15 @@ operating system on which the build is performed (as reported by C - env = Environment() - env.Program('hello.c') + Program('hello.c') TargetSignatures('content') @@ -352,14 +345,14 @@ operating system on which the build is performed (as reported by C - % scons hello - cc -c hello.c -o hello.o + % scons -Q hello + cc -c -o hello.o hello.c cc -o hello hello.o % edit hello.c [CHANGE A COMMENT IN hello.c] - % scons hello - cc -c hello.c -o hello.o - % + % scons -Q hello + cc -c -o hello.o hello.c + scons: `hello' is up to date. @@ -407,9 +400,10 @@ operating system on which the build is performed (as reported by C + #define string "world" - + @@ -421,14 +415,14 @@ operating system on which the build is performed (as reported by C + - env = Environment(CPPPATH = '.') - hello = env.Program('hello.c') - + Program('hello.c', CPPPATH = '.') + - The &CPPPATH; assignment in the &Environment; call + The &CPPPATH; value tells &SCons; to look in the current directory ('.') for any files included by C source files @@ -438,17 +432,16 @@ operating system on which the build is performed (as reported by C - % scons hello - cc -I. -c hello.c -o hello.o + % scons -Q hello + cc -I. -c -o hello.o hello.c cc -o hello hello.o - % scons hello + % scons -Q hello scons: `hello' is up to date. % edit hello.h [CHANGE THE CONTENTS OF hello.h] - % scons hello - cc -I. -c hello.c -o hello.o + % scons -Q hello + cc -I. -c -o hello.o hello.c cc -o hello hello.o - % @@ -490,13 +483,12 @@ operating system on which the build is performed (as reported by C - env = Environment(CPPPATH = ['include', '/home/project/inc']) - hello = env.Program('hello.c') + Program('hello.c', CPPPATH = ['include', '/home/project/inc']) @@ -506,8 +498,8 @@ operating system on which the build is performed (as reported by C - % scons hello - cc -Iinclude -I/home/project/inc -c hello.c -o hello.o + % scons -Q hello + cc -Iinclude -I/home/project/inc -c -o hello.o hello.c cc -o hello hello.o @@ -518,9 +510,9 @@ operating system on which the build is performed (as reported by C - % scons hello - cl /Iinclude /I\home\project\inc /Fohello.obj hello.c - link /OUT:hello.exe hello.obj + C:\>scons -Q hello.exe + cl /nologo /Iinclude /I\home\project\inc /c hello.c /Fohello.obj + link /nologo /OUT:hello.exe hello.obj @@ -568,49 +560,82 @@ operating system on which the build is performed (as reported by C - % scons --implicit-cache hello - cc -c hello.c -o hello.o + % scons -Q --implicit-cache hello + cc -c -o hello.o hello.c cc -o hello hello.o - % scons hello + % scons -Q hello scons: `hello' is up to date. - Or by setting the &implicit_cache; option + If you don't want to specify &implicit-cache; + on the command line each time, + you can make it the default behavior for your build + by setting the &implicit_cache; option in an &SConscript; file: - + SetOption('implicit_cache', 1) - + - + +
The &implicit-deps-changed; Option - XXX + When using cached implicit dependencies, + sometimes you want to "start fresh" + and have &SCons; re-scan the files + for which it previously cached the dependencies. + For example, + if you have recently installed a new version of + external code that you use for compilation, + the external header files will have changed + and the previously-cached implicit dependencies + will be out of date. + You can update them by + running &SCons; with the &implicit-deps-changed; option: + + + + + % scons -Q --implicit-deps-changed hello + cc -c -o hello.o hello.c + cc -o hello hello.o + % scons -Q hello + scons: `hello' is up to date. + + + + + In this case, &SCons; will re-scan all of the implicit dependencies + and cache updated copies of the information. @@ -621,7 +646,41 @@ operating system on which the build is performed (as reported by C - XXX + By default when caching dependencies, + &SCons; notices when a file has been modified + and re-scans the file for any updated + implicit dependency information. + Sometimes, however, you may want + to force &SCons; to use the cached implicit dependencies, + even if the source files changed. + This can speed up a build for example, + when you have changed your source files + but know that you haven't changed + any #include lines. + In this case, + you can use the &implicit-deps-unchanged; option: + + + + + % scons -Q --implicit-deps-unchanged hello + cc -c -o hello.o hello.c + cc -o hello hello.o + % scons -Q hello + scons: `hello' is up to date. + + + + + In this case, + &SCons; will assume that the cached implicit + dependencies are correct and + will not bother to re-scan changed files. + For typical builds after small, + incremental changes to source files, + the savings may not be very big, + but sometimes every bit of + improved performance counts. @@ -644,23 +703,32 @@ operating system on which the build is performed (as reported by C - env = Environment() - hello = env.Program('hello.c') - env.Ignore(hello, 'hello.h') + hello = Program('hello.c') + Ignore(hello, 'hello.h') + + - % scons hello - cc -c hello.c -o hello.o - cc -o hello hello.o - % scons hello - scons: `hello' is up to date. - % edit hello.h - [CHANGE THE CONTENTS OF hello.h] - % scons hello - scons: `hello' is up to date. + % scons -Q hello + cc -c -o hello.o hello.c + cc -o hello hello.o + % scons -Q hello + scons: `hello' is up to date. + % edit hello.h + [CHANGE THE CONTENTS OF hello.h] + % scons -Q hello + scons: `hello' is up to date. @@ -699,7 +767,7 @@ operating system on which the build is performed (as reported by C - % scons hello + % scons -Q hello cc -c hello.c -o hello.o cc -o hello hello.o - % scons hello + % scons -Q hello scons: `hello' is up to date. % edit other_file [CHANGE THE CONTENTS OF other_file] - % scons hello + % scons -Q hello cc -c hello.c -o hello.o cc -o hello hello.o diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in index 5a34be2..cc059ed 100644 --- a/doc/user/hierarchy.in +++ b/doc/user/hierarchy.in @@ -340,7 +340,7 @@ make no difference to the build. - scons + scons -Q @@ -351,8 +351,11 @@ make no difference to the build. in multiple directories, like main.c in the above example. Second, unlike standard recursive use of &Make;, - &SCons; stays in the top-level directory and - issues commands + &SCons; stays in the top-level directory + (where the &SConstruct; file lives) + and issues commands that use the path names + from the top-level directory to the + target and source files within the hierarchy. @@ -375,7 +378,6 @@ make no difference to the build. by appending a &hash; (hash mark) to the beginning of the path name: - @@ -409,7 +411,7 @@ make no difference to the build. - scons + scons -Q @@ -460,7 +462,7 @@ make no difference to the build. - scons + scons -Q @@ -512,7 +514,7 @@ make no difference to the build. There are two ways to export a variable, such as a construction environment, - from one &SConscript; file, + from an &SConscript; file, so that it may be used by other &SConscript; files. First, you can call the &Export; function with a list of variables, @@ -531,7 +533,7 @@ make no difference to the build. - XXX + You may export more than one variable name at a time: @@ -543,7 +545,9 @@ make no difference to the build. - XXX + Because white space is not legal in Python variable names, + the &Export; function will even automatically split + a string into separate names for you: @@ -603,7 +607,10 @@ make no difference to the build. - XXX + Once a variable has been exported from a calling + &SConscript; file, + it may be used in other &SConscript; files + by calling the &Import; function: @@ -614,7 +621,18 @@ make no difference to the build. - XXX + The &Import; call makes the env construction + environment available to the &SConscript; file, + after which the variable can be used to build + programs, libraries, etc. + + + + + + Like the &Export; function, + the &Import; function can be used + with multiple variable names: @@ -626,7 +644,9 @@ make no difference to the build. - Which is exactly equivalent to: + And the &Import; function will similarly + split a string along white-space + into separate variable names: @@ -638,7 +658,24 @@ make no difference to the build. - XXX + Lastly, as a special case, + you may import all of the variables that + have been exported by supplying an asterisk + to the &Import; function: + + + + + Import('*') + env = env.Copy(DEBUG = debug) + env.Program('prog', ['prog.c']) + + + + + If you're dealing with a lot of &SConscript; files, + this can be a lot simpler than keeping + arbitrary lists of imported variables in each file. @@ -649,35 +686,90 @@ make no difference to the build. - XXX + Sometimes, you would like to be able to + use information from a subsidiary + &SConscript file in some way. + For example, + suppose that you want to create one + library from source files + scattered throughout a number + of subsidiary &SConscript; files. + You can do this by using the &Return; + function to return values + from the subsidiary &SConscript; files + to the calling file. - - obj = env.Object('foo.c') - Return('obj') - + + + If, for example, we have two subdirectories + &foo; and &bar; + that should each contribute a source + file to a Library, + what we'd like to be able to do is + collect the object files + from the subsidiary &SConscript; calls + like this: + + + + + + env = Environment() + Export('env') + objs = [] + for subdir in ['foo', 'bar']: + o = SConscript('%s/SConscript' % subdir) + objs.append(o) + env.Library('prog', objs) + + + + + Import('env') + obj = env.Object('foo.c') + Return('obj') + + + Import('env') + obj = env.Object('bar.c') + Return('obj') + + + void foo(void) { printf("foo/foo.c\n"); } + + + void bar(void) { printf("bar/bar.c\n"); } + + - XXX + We can do this by using the &Return; + function in the + foo/SConscript file like this: - - objs = [] - for subdir in ['foo', 'bar']: - o = SConscript('%s/SConscript' % subdir) - objs.append(o) - env.Library('prog', objs) - + + - XXX + (The corresponding + bar/SConscript + file should be pretty obvious.) + Then when we run &SCons;, + the object files from the subsidiary subdirectories + are all correctly archived in the desired library: + + scons -Q + +
diff --git a/doc/user/hierarchy.sgml b/doc/user/hierarchy.sgml index 24adb56..5db49a8 100644 --- a/doc/user/hierarchy.sgml +++ b/doc/user/hierarchy.sgml @@ -290,10 +290,11 @@ make no difference to the build. + env = Environment() env.Program('prog1', ['main.c', 'foo1.c', 'foo2.c']) - + @@ -301,10 +302,11 @@ make no difference to the build. + env = Environment() env.Program('prog2', ['main.c', 'bar1.c', 'bar2.c']) - + @@ -314,14 +316,14 @@ make no difference to the build. - % scons - cc -c prog1/foo1.c -o prog1/foo1.o - cc -c prog1/foo2.c -o prog1/foo2.o - cc -c prog1/main.c -o prog1/main.o + % scons -Q + cc -c -o prog1/foo1.o prog1/foo1.c + cc -c -o prog1/foo2.o prog1/foo2.c + cc -c -o prog1/main.o prog1/main.c cc -o prog1/prog1 prog1/main.o prog1/foo1.o prog1/foo2.o - cc -c prog2/bar1.c -o prog2/bar1.o - cc -c prog2/bar2.c -o prog2/bar2.o - cc -c prog2/main.c -o prog2/main.o + cc -c -o prog2/bar1.o prog2/bar1.c + cc -c -o prog2/bar2.o prog2/bar2.c + cc -c -o prog2/main.o prog2/main.c cc -o prog2/prog2 prog2/main.o prog2/bar1.o prog2/bar2.o @@ -333,8 +335,11 @@ make no difference to the build. in multiple directories, like main.c in the above example. Second, unlike standard recursive use of &Make;, - &SCons; stays in the top-level directory and - issues commands + &SCons; stays in the top-level directory + (where the &SConstruct; file lives) + and issues commands that use the path names + from the top-level directory to the + target and source files within the hierarchy. @@ -357,13 +362,12 @@ make no difference to the build. by appending a &hash; (hash mark) to the beginning of the path name: - - + env = Environment() env.Program('prog', ['main.c', '#lib/foo1.c', 'foo2.c']) - + @@ -377,11 +381,11 @@ make no difference to the build. - % scons - cc -c lib/foo1.c -o lib/foo1.o - cc -c src/prog/foo2.c -o src/prog/foo2.o - cc -c src/prog/main.c -o src/prog/main.o - cc -o src/prog/prog prog/main.o lib/foo1.o prog/foo2.o + % scons -Q + cc -c -o lib/foo1.o lib/foo1.c + cc -c -o src/prog/foo2.o src/prog/foo2.c + cc -c -o src/prog/main.o src/prog/main.c + cc -o src/prog/prog src/prog/main.o lib/foo1.o src/prog/foo2.o @@ -406,10 +410,10 @@ make no difference to the build. - + env = Environment() env.Program('prog', ['main.c', '/usr/joe/lib/foo1.c', 'foo2.c']) - + @@ -418,11 +422,11 @@ make no difference to the build. - % scons - cc -c /usr/joe/lib/foo1.c -o /usr/joe/lib/foo1.o - cc -c src/prog/foo2.c -o src/prog/foo2.o - cc -c src/prog/main.c -o src/prog/main.o - cc -o src/prog/prog prog/main.o /usr/joe/lib/foo1.o prog/foo2.o + % scons -Q + cc -c -o src/prog/foo2.o src/prog/foo2.c + cc -c -o src/prog/main.o src/prog/main.c + cc -c -o /usr/joe/lib/foo1.o /usr/joe/lib/foo1.c + cc -o src/prog/prog src/prog/main.o /usr/joe/lib/foo1.o src/prog/foo2.o @@ -474,7 +478,7 @@ make no difference to the build. There are two ways to export a variable, such as a construction environment, - from one &SConscript; file, + from an &SConscript; file, so that it may be used by other &SConscript; files. First, you can call the &Export; function with a list of variables, @@ -493,7 +497,7 @@ make no difference to the build. - XXX + You may export more than one variable name at a time: @@ -505,7 +509,9 @@ make no difference to the build. - XXX + Because white space is not legal in Python variable names, + the &Export; function will even automatically split + a string into separate names for you: @@ -516,7 +522,7 @@ make no difference to the build. Second, you can specify a list of - variables to exported as a second argument + variables to export as a second argument to the &SConscript; function call: @@ -565,7 +571,10 @@ make no difference to the build. - XXX + Once a variable has been exported from a calling + &SConscript; file, + it may be used in other &SConscript; files + by calling the &Import; function: @@ -576,7 +585,18 @@ make no difference to the build. - XXX + The &Import; call makes the env construction + environment available to the &SConscript; file, + after which the variable can be used to build + programs, libraries, etc. + + + + + + Like the &Export; function, + the &Import; function can be used + with multiple variable names: @@ -588,7 +608,9 @@ make no difference to the build. - Which is exactly equivalent to: + And the &Import; function will similarly + split a string along white-space + into separate variable names: @@ -600,7 +622,24 @@ make no difference to the build. - XXX + Lastly, as a special case, + you may import all of the variables that + have been exported by supplying an asterisk + to the &Import; function: + + + + + Import('*') + env = env.Copy(DEBUG = debug) + env.Program('prog', ['prog.c']) + + + + + If you're dealing with a lot of &SConscript; files, + this can be a lot simpler than keeping + arbitrary lists of imported variables in each file. @@ -611,35 +650,78 @@ make no difference to the build. - XXX + Sometimes, you would like to be able to + use information from a subsidiary + &SConscript; file in some way. + For example, + suppose that you want to create one + library from source files + scattered throughout a number + of subsidiary &SConscript; files. + You can do this by using the &Return; + function to return values + from the subsidiary &SConscript; files + to the calling file. + + + + + + If, for example, we have two subdirectories + &foo; and &bar; + that should each contribute a source + file to a Library, + what we'd like to be able to do is + collect the object files + from the subsidiary &SConscript; calls + like this: - obj = env.Object('foo.c') - Return('obj') + env = Environment() + Export('env') + objs = [] + for subdir in ['foo', 'bar']: + o = SConscript('%s/SConscript' % subdir) + objs.append(o) + env.Library('prog', objs) - XXX + We can do this by using the &Return; + function in the + foo/SConscript file like this: + - objs = [] - for subdir in ['foo', 'bar']: - o = SConscript('%s/SConscript' % subdir) - objs.append(o) - env.Library('prog', objs) - + Import('env') + obj = env.Object('foo.c') + Return('obj') + - XXX + (The corresponding + bar/SConscript + file should be pretty obvious.) + Then when we run &SCons;, + the object files from the subsidiary subdirectories + are all correctly archived in the desired library: + + % scons -Q + cc -c -o bar/bar.o bar/bar.c + cc -c -o foo/foo.o foo/foo.c + ar r libprog.a foo/foo.o bar/bar.o + ranlib libprog.a + + diff --git a/doc/user/main.in b/doc/user/main.in index 12b0480..e0ae71d 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -100,11 +100,6 @@ &simple; - - Construction Environments - &environments; - - Building and Linking with Libraries &libraries; @@ -115,6 +110,11 @@ &depends; + + Construction Environments + &environments; + + Default Targets &default; @@ -150,11 +150,15 @@ &variants; + + Writing Your Own Builders &builders-writing; @@ -165,11 +169,15 @@ &builders-commands; + + Writing Scanners &scanners; @@ -180,11 +188,15 @@ &repositories; + + Caching Built Files &caching; @@ -195,6 +207,8 @@ &alias; + + + + diff --git a/doc/user/main.sgml b/doc/user/main.sgml index 12b0480..e0ae71d 100644 --- a/doc/user/main.sgml +++ b/doc/user/main.sgml @@ -100,11 +100,6 @@ &simple; - - Construction Environments - &environments; - - Building and Linking with Libraries &libraries; @@ -115,6 +110,11 @@ &depends; + + Construction Environments + &environments; + + Default Targets &default; @@ -150,11 +150,15 @@ &variants; + + Writing Your Own Builders &builders-writing; @@ -165,11 +169,15 @@ &builders-commands; + + Writing Scanners &scanners; @@ -180,11 +188,15 @@ &repositories; + + Caching Built Files &caching; @@ -195,6 +207,8 @@ &alias; + + + + diff --git a/doc/user/preface.in b/doc/user/preface.in index 589399d..5e46f0a 100644 --- a/doc/user/preface.in +++ b/doc/user/preface.in @@ -60,8 +60,8 @@ easier for non-programmers to learn than the cryptic languages of other build tools, - which are usally invented by programmers for other programmers. - This is in no small part to the + which are usually invented by programmers for other programmers. + This is in no small part due to the consistency and readability that are built in to Python. It just so happens that making a real, live scripting language the basis for the @@ -72,6 +72,8 @@ + +
&SCons; Principles @@ -137,7 +141,8 @@ down the default &SCons; behavior to guarantee a correct build, we also try to make it easy to speed up &SCons; through optimization options that let you trade off - guaranteed correctness for speed. + guaranteed correctness in all end cases for + a speedier build in the usual cases. @@ -169,6 +174,8 @@
+ + + Thanks to Peter Miller diff --git a/doc/user/preface.sgml b/doc/user/preface.sgml index 589399d..390d6a8 100644 --- a/doc/user/preface.sgml +++ b/doc/user/preface.sgml @@ -60,8 +60,8 @@ easier for non-programmers to learn than the cryptic languages of other build tools, - which are usally invented by programmers for other programmers. - This is in no small part to the + which are usually invented by programmers for other programmers. + This is in no small part due to the consistency and readability that are built in to Python. It just so happens that making a real, live scripting language the basis for the @@ -72,6 +72,8 @@ + +
&SCons; Principles There are a few overriding principles - we try to live up to in designing and implementing &SCons: + we try to live up to in designing and implementing &SCons;: @@ -137,7 +141,8 @@ down the default &SCons; behavior to guarantee a correct build, we also try to make it easy to speed up &SCons; through optimization options that let you trade off - guaranteed correctness for speed. + guaranteed correctness in all end cases for + a speedier build in the usual cases. @@ -169,6 +174,8 @@
+ + + Thanks to Peter Miller @@ -365,7 +378,7 @@ - If you want to receive announcements about &SCons, + If you want to receive announcements about &SCons;, join the low-volume &scons-announce; mailing list. diff --git a/doc/user/repositories.in b/doc/user/repositories.in index c155617..480ea3f 100644 --- a/doc/user/repositories.in +++ b/doc/user/repositories.in @@ -219,7 +219,7 @@ subdirectories under the repository tree. and next under the /usr/repository2 tree. &SCons; expects that any files it searches for will be found in the same position - relative to the top-level directory XXX + relative to the top-level directory. In the above example, if the &hello_c; file is not found in the local build tree, &SCons; will search first for @@ -240,7 +240,7 @@ subdirectories under the repository tree. - scons + scons -Q @@ -264,7 +264,7 @@ subdirectories under the repository tree. - scons + scons -Q gcc -c /usr/repository1/hello.c -o hello.o gcc -o hello hello.o @@ -289,7 +289,7 @@ subdirectories under the repository tree. - scons + scons -Q @@ -316,7 +316,7 @@ subdirectories under the repository tree. - % scons -Y /usr/repository1 -Y /usr/repository2 + % scons -Q -Y /usr/repository1 -Y /usr/repository2 @@ -361,20 +361,24 @@ subdirectories under the repository tree. env = Environment() - env.Program('hello.c') + env.Program(['hello.c', 'file1.c', 'file2.c']) Repository('/usr/repository1', '/usr/repository2') int main() { printf("Hello, world!\n"); } + + int f1() { printf("file1\n"); } + + + int f2() { printf("file2.c\n"); } + - - % cd /usr/repository1 - % scons - gcc -c hello.c -o hello.o - gcc -o hello hello.o - + + cd /usr/repository1 + scons -Q + @@ -396,20 +400,26 @@ subdirectories under the repository tree. + % cd $HOME/build % edit hello.c - % scons -Y /usr/repository1 - gcc -c hello.c -o hello.o - gcc -o hello hello.o - XXXXXXX + % scons -Q -Y /usr/repository1 + cc -c -o hello.o hello.c + cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o Notice that &SCons; realizes that it does not need to - rebuild a local XXX.o file, - but instead uses the already-compiled XXX.o file + rebuild local copies file1.o and file2.o files, + but instead uses the already-compiled files from the repository. @@ -431,7 +441,7 @@ subdirectories under the repository tree. % mkdir $HOME/build2 % cd $HOME/build2 - % scons -Y /usr/all/repository hello + % scons -Q -Y /usr/all/repository hello scons: `hello' is up-to-date. @@ -460,7 +470,7 @@ subdirectories under the repository tree. - + env = Environment() hello = env.Program('hello.c') @@ -484,7 +494,6 @@ subdirectories under the repository tree. % scons -Y /usr/all/repository hello Local copy of hello from /usr/all/repository/hello scons: `hello' is up-to-date. - XXXXXX DO WE REALLY REPORT up-to-date, TOO? @@ -492,7 +501,6 @@ subdirectories under the repository tree. (Notice that, because the act of making the local copy is not considered a "build" of the &hello; file, &SCons; still reports that it is up-to-date.) - XXXXXX DO WE REALLY REPORT up-to-date, TOO? diff --git a/doc/user/repositories.sgml b/doc/user/repositories.sgml index 07af115..fdb8b5b 100644 --- a/doc/user/repositories.sgml +++ b/doc/user/repositories.sgml @@ -214,7 +214,7 @@ subdirectories under the repository tree. and next under the /usr/repository2 tree. &SCons; expects that any files it searches for will be found in the same position - relative to the top-level directory XXX + relative to the top-level directory. In the above example, if the &hello_c; file is not found in the local build tree, &SCons; will search first for @@ -235,9 +235,9 @@ subdirectories under the repository tree. - % scons - gcc -c hello.c -o hello.o - gcc -o hello hello.o + % scons -Q + cc -c -o hello.o hello.c + cc -o hello hello.o @@ -249,8 +249,12 @@ subdirectories under the repository tree. + + - % scons + % scons -Q + cc -c -o hello.o hello.c + cc -o hello hello.o gcc -c /usr/repository1/hello.c -o hello.o gcc -o hello hello.o @@ -263,10 +267,12 @@ subdirectories under the repository tree. + + - % scons - gcc -c /usr/repository2/hello.c -o hello.o - gcc -o hello hello.o + % scons -Q + cc -c -o hello.o hello.c + cc -o hello hello.o @@ -293,7 +299,7 @@ subdirectories under the repository tree. - % scons -Y /usr/repository1 -Y /usr/repository2 + % scons -Q -Y /usr/repository1 -Y /usr/repository2 @@ -335,11 +341,15 @@ subdirectories under the repository tree. + + % cd /usr/repository1 - % scons - gcc -c hello.c -o hello.o - gcc -o hello hello.o + % scons -Q + cc -c -o file1.o file1.c + cc -c -o file2.o file2.c + cc -c -o hello.o hello.c + cc -o hello hello.o file1.o file2.o @@ -362,20 +372,26 @@ subdirectories under the repository tree. + % cd $HOME/build % edit hello.c - % scons -Y /usr/repository1 - gcc -c hello.c -o hello.o - gcc -o hello hello.o - XXXXXXX + % scons -Q -Y /usr/repository1 + cc -c -o hello.o hello.c + cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o Notice that &SCons; realizes that it does not need to - rebuild a local XXX.o file, - but instead uses the already-compiled XXX.o file + rebuild local copies file1.o and file2.o files, + but instead uses the already-compiled files from the repository. @@ -397,7 +413,7 @@ subdirectories under the repository tree. % mkdir $HOME/build2 % cd $HOME/build2 - % scons -Y /usr/all/repository hello + % scons -Q -Y /usr/all/repository hello scons: `hello' is up-to-date. @@ -445,7 +461,6 @@ subdirectories under the repository tree. % scons -Y /usr/all/repository hello Local copy of hello from /usr/all/repository/hello scons: `hello' is up-to-date. - XXXXXX DO WE REALLY REPORT up-to-date, TOO? @@ -453,7 +468,6 @@ subdirectories under the repository tree. (Notice that, because the act of making the local copy is not considered a "build" of the &hello; file, &SCons; still reports that it is up-to-date.) - XXXXXX DO WE REALLY REPORT up-to-date, TOO? diff --git a/doc/user/scanners.in b/doc/user/scanners.in index 76b2a1a..fe409ad 100644 --- a/doc/user/scanners.in +++ b/doc/user/scanners.in @@ -121,19 +121,211 @@ over the file scanning rather than being called for each input line: --> - + - XXX + &SCons; has built-in scanners that know how to look in + C, Fortran and IDL source files for information about + other files that targets built from those files depend on--for example, + in the case of files that use the C preprocessor, + the .h files that are specified + using #include lines in the source. + You can use the same mechanisms that &SCons; uses to create + its built-in scanners to write scanners of your own for file types + that &SCons; does not know how to scan "out of the box." + + - +
+ A Simple Scanner Example -
- XXX + - + Suppose, for example, that we want to create a simple scanner + for .foo files. + A .foo file contains some text that + will be processed, + and can include other files on lines that begin + with include + followed by a file name: - XXX + - + + include filename.foo + -
+ + + Scanning a file will be handled by a Python function + that you must supply. + Here is a function that will use the Python + re module + to scan for the include lines in our example: + + + + + import re + + include_re = re.compile(r'^include\\s+(\\S+)$', re.M) + + def kfile_scan(node, env, path, arg): + contents = node.get_contents() + return include_re.findall(contents) + + + + + The scanner function must + accept the four specified arguments + and return a list of implicit dependencies. + Presumably, these would be dependencies found + from examining the contents of the file, + although the function can perform any + manipulation at all to generate the list of + dependencies. + + + + + + + node + + + + + An &SCons; node object representing the file being scanned. + The path name to the file can be + used by converting the node to a string + using the str() function, + or an internal &SCons; get_contents() + object method can be used to fetch the contents. + + + + + + + env + + + + + The construction environment in effect for this scan. + The scanner function may choose to use construction + variables from this environment to affect its behavior. + + + + + + + path + + + + + A list of directories that form the search path for included files + for this scanner. + This is how &SCons; handles the &CPPPATH; and &LIBPATH; + variables. + + + + + + + arg + + + + + An optional argument that you can choose to + have passed to this scanner function by + various scanner instances. + + + + + + + + + + A Scanner object is created using the &Scanner; function, + which typically takes an skeys argument + to associate the type of file suffix with this scanner. + The Scanner object must then be associated with the + &SCANNERS; construction variable of a construction environment, + typically by using the &Append; method: + + + + + kscan = Scanner(function = kfile_scan, + skeys = ['.k']) + env.Append(SCANNERS = kscan) + + + + + When we put it all together, it looks like: + + + + + + import re + + include_re = re.compile(r'^include\\s+(\\S+)$', re.M) + + def kfile_scan(node, env, path): + contents = node.get_contents() + includes = include_re.findall(contents) + return includes + + kscan = Scanner(function = kfile_scan, + skeys = ['.k']) + + env = Environment(ENV = {'PATH' : '__ROOT__/usr/local/bin'}) + env.Append(SCANNERS = kscan) + + env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') + + + include other_file + + + other_file + + + + + + cat + + + + + +
diff --git a/doc/user/scanners.sgml b/doc/user/scanners.sgml index 76b2a1a..23cd044 100644 --- a/doc/user/scanners.sgml +++ b/doc/user/scanners.sgml @@ -121,19 +121,197 @@ over the file scanning rather than being called for each input line: --> - + - XXX + &SCons; has built-in scanners that know how to look in + C, Fortran and IDL source files for information about + other files that targets built from those files depend on--for example, + in the case of files that use the C preprocessor, + the .h files that are specified + using #include lines in the source. + You can use the same mechanisms that &SCons; uses to create + its built-in scanners to write scanners of your own for file types + that &SCons; does not know how to scan "out of the box." + + - +
+ A Simple Scanner Example -
- XXX + - + Suppose, for example, that we want to create a simple scanner + for .foo files. + A .foo file contains some text that + will be processed, + and can include other files on lines that begin + with include + followed by a file name: - XXX + - + + include filename.foo + -
+ + + Scanning a file will be handled by a Python function + that you must supply. + Here is a function that will use the Python + re module + to scan for the include lines in our example: + + + + + import re + + include_re = re.compile(r'^include\\s+(\\S+)$', re.M) + + def kfile_scan(node, env, path, arg): + contents = node.get_contents() + return include_re.findall(contents) + + + + + The scanner function must + accept the four specified arguments + and return a list of implicit dependencies. + Presumably, these would be dependencies found + from examining the contents of the file, + although the function can perform any + manipulation at all to generate the list of + dependencies. + + + + + + + node + + + + + An &SCons; node object representing the file being scanned. + The path name to the file can be + used by converting the node to a string + using the str() function, + or an internal &SCons; get_contents() + object method can be used to fetch the contents. + + + + + + + env + + + + + The construction environment in effect for this scan. + The scanner function may choose to use construction + variables from this environment to affect its behavior. + + + + + + + path + + + + + A list of directories that form the search path for included files + for this scanner. + This is how &SCons; handles the &CPPPATH; and &LIBPATH; + variables. + + + + + + + arg + + + + + An optional argument that you can choose to + have passed to this scanner function by + various scanner instances. + + + + + + + + + + A Scanner object is created using the &Scanner; function, + which typically takes an skeys argument + to associate the type of file suffix with this scanner. + The Scanner object must then be associated with the + &SCANNERS; construction variable of a construction environment, + typically by using the &Append; method: + + + + + kscan = Scanner(function = kfile_scan, + skeys = ['.k']) + env.Append(SCANNERS = kscan) + + + + + When we put it all together, it looks like: + + + + + import re + + include_re = re.compile(r'^include\\s+(\\S+)$', re.M) + + def kfile_scan(node, env, path): + contents = node.get_contents() + includes = include_re.findall(contents) + return includes + + kscan = Scanner(function = kfile_scan, + skeys = ['.k']) + + env = Environment(ENV = {'PATH' : '/usr/local/bin'}) + env.Append(SCANNERS = kscan) + + env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') + + + + +
diff --git a/doc/user/separate.in b/doc/user/separate.in index c1b3c32..1b24edf 100644 --- a/doc/user/separate.in +++ b/doc/user/separate.in @@ -132,38 +132,37 @@ program using the F path name. The most straightforward way to establish a build directory uses the fact that the usual way to - set up a build hierarcy is to have an + set up a build hierarchy is to have an &SConscript; file in the source subdirectory. If you then pass a &build_dir; argument to the &SConscript; function call: - - SConscript('src/SConscript', build_dir='build') - - - - - &SCons; will then build all of the files in - the &build; subdirectory: - - - + SConscript('src/SConscript', build_dir='build') + + env = Environment() env.Program('hello.c') - + int main() { printf("Hello, world!\n"); } + + + &SCons; will then build all of the files in + the &build; subdirectory: + + + - ls -1 src - scons - ls -1 build + ls src + scons -Q + ls build @@ -199,48 +198,88 @@ program using the F path name. &SCons; duplicates source files in build directories because it's the most straightforward way to guarantee a correct build - regardless of include-file directory paths, + regardless of include-file directory paths, + relative references between files, + or tool support for putting files in different locations, and the &SCons; philosophy is to, by default, guarantee a correct build in all cases. - Here is an example of an end case where duplicating - source files in a build directory - is necessary for a correct build: - XXX + The most direct reason to duplicate source files + in build directories + is simply that some tools (mostly older vesions) + are written to only build their output files + in the same directory as the source files. + In this case, the choices are either + to build the output file in the source directory + and move it to the build directory, + or to duplicate the source files in the build directory. + + + + + + Additionally, + relative references between files + can cause problems if we don't + just duplicate the hierarchy of source files + in the build directory. + You can see this at work in + use of the C preprocessor #include + mechanism with double quotes, not angle brackets: - env = Environmnet() + #include "file.h" - XXX + The de facto standard behavior + for most C compilers in this case + is to first look in the same directory + as the source file that contains the #include line, + then to look in the directories in the preprocessor search path. + Add to this that the &SCons; implementation of + support for code repositories + (described below) + means not all of the files + will be found in the same directory hierarchy, + and the simplest way to make sure + that the right include file is found + is to duplicate the source files into the build directory, + which provides a correct build + regardless of the original location(s) of the source files. - - % scons - cc -c build/hello.c -o build/hello.o - cc -o build/hello build/hello.o - + - + Although source-file duplication guarantees a correct build + even in these end-cases, + it can usually be safely disabled. + The next section describes + how you can disable the duplication of source files + in the build directory. + + + +
Telling &SCons; to Not Duplicate Source Files in the Build Directory - In most cases, however, - having &SCons; place its target files in a build subdirectory + In most cases and with most tool sets, + &SCons; can place its target files in a build subdirectory without - duplicating the source files works just fine. + duplicating the source files + and everything will work just fine. You can disable the default &SCons; behavior by specifying duplicate=0 when you call the &SConscript; function: @@ -262,13 +301,13 @@ program using the F path name. - % ls -1 src + % ls src SConscript hello.c - % scons + % scons -Q cc -c src/hello.c -o build/hello.o cc -o build/hello build/hello.o - % ls -1 build + % ls build hello hello.o @@ -311,12 +350,6 @@ program using the F path name. - XXX - - - - - When using the &BuildDir; function directly, &SCons; still duplicates the source files in the build directory by default: @@ -325,8 +358,8 @@ program using the F path name. ls src - scons - ls -1 build + scons -Q + ls build @@ -356,8 +389,8 @@ program using the F path name. ls src - scons - ls -1 build + scons -Q + ls build
@@ -377,22 +410,26 @@ program using the F path name. - + + BuildDir('build', 'src') + SConscript('build/SConscript') + + env = Environment() env.Program('hello.c') - - BuildDir('build', 'src') - SConscript('build/SConscript') + + int main() { printf("Hello, world!\n"); } + - Then our &SConscript; file could look like: + Then our &SConstruct; file could look like: - + @@ -402,9 +439,9 @@ program using the F path name. - ls -1 src - scons - ls -1 build + ls src + scons -Q + ls build @@ -417,6 +454,8 @@ program using the F path name. + diff --git a/doc/user/separate.sgml b/doc/user/separate.sgml index ac3c0f3..b00be1a 100644 --- a/doc/user/separate.sgml +++ b/doc/user/separate.sgml @@ -132,7 +132,7 @@ program using the F path name. The most straightforward way to establish a build directory uses the fact that the usual way to - set up a build hierarcy is to have an + set up a build hierarchy is to have an &SConscript; file in the source subdirectory. If you then pass a &build_dir; argument to the &SConscript; function call: @@ -151,16 +151,13 @@ program using the F path name. - % ls -1 src - SConscript - hello.c - % scons - cc -c build/hello.c -o build/hello.o + % ls src + SConscript hello.c + % scons -Q + cc -c -o build/hello.o build/hello.c cc -o build/hello build/hello.o - % ls -1 build - hello - hello.c - hello.o + % ls build + SConscript hello hello.c hello.o @@ -196,48 +193,88 @@ program using the F path name. &SCons; duplicates source files in build directories because it's the most straightforward way to guarantee a correct build - regardless of include-file directory paths, + regardless of include-file directory paths, + relative references between files, + or tool support for putting files in different locations, and the &SCons; philosophy is to, by default, guarantee a correct build in all cases. - Here is an example of an end case where duplicating - source files in a build directory - is necessary for a correct build: - XXX + The most direct reason to duplicate source files + in build directories + is simply that some tools (mostly older vesions) + are written to only build their output files + in the same directory as the source files. + In this case, the choices are either + to build the output file in the source directory + and move it to the build directory, + or to duplicate the source files in the build directory. + + + + + + Additionally, + relative references between files + can cause problems if we don't + just duplicate the hierarchy of source files + in the build directory. + You can see this at work in + use of the C preprocessor #include + mechanism with double quotes, not angle brackets: - env = Environmnet() + #include "file.h" - XXX + The de facto standard behavior + for most C compilers in this case + is to first look in the same directory + as the source file that contains the #include line, + then to look in the directories in the preprocessor search path. + Add to this that the &SCons; implementation of + support for code repositories + (described below) + means not all of the files + will be found in the same directory hierarchy, + and the simplest way to make sure + that the right include file is found + is to duplicate the source files into the build directory, + which provides a correct build + regardless of the original location(s) of the source files. - - % scons - cc -c build/hello.c -o build/hello.o - cc -o build/hello build/hello.o - + - + Although source-file duplication guarantees a correct build + even in these end-cases, + it can usually be safely disabled. + The next section describes + how you can disable the duplication of source files + in the build directory. + + + +
Telling &SCons; to Not Duplicate Source Files in the Build Directory - In most cases, however, - having &SCons; place its target files in a build subdirectory + In most cases and with most tool sets, + &SCons; can place its target files in a build subdirectory without - duplicating the source files works just fine. + duplicating the source files + and everything will work just fine. You can disable the default &SCons; behavior by specifying duplicate=0 when you call the &SConscript; function: @@ -259,13 +296,13 @@ program using the F path name. - % ls -1 src + % ls src SConscript hello.c - % scons + % scons -Q cc -c src/hello.c -o build/hello.o cc -o build/hello build/hello.o - % ls -1 build + % ls build hello hello.o @@ -303,12 +340,6 @@ program using the F path name. - XXX - - - - - When using the &BuildDir; function directly, &SCons; still duplicates the source files in the build directory by default: @@ -318,13 +349,11 @@ program using the F path name. % ls src hello.c - % scons - cc -c build/hello.c -o build/hello.o + % scons -Q + cc -c -o build/hello.o build/hello.c cc -o build/hello build/hello.o - % ls -1 build - hello - hello.c - hello.o + % ls build + hello hello.c hello.o @@ -350,12 +379,11 @@ program using the F path name. % ls src hello.c - % scons - cc -c src/hello.c -o build/hello.o + % scons -Q + cc -c -o build/hello.o src/hello.c cc -o build/hello build/hello.o - % ls -1 build - hello - hello.o + % ls build + hello hello.o
@@ -381,14 +409,15 @@ program using the F path name. - Then our &SConscript; file could look like: + Then our &SConstruct; file could look like: + BuildDir('build', 'src') SConscript('build/SConscript') - + @@ -397,16 +426,13 @@ program using the F path name. - % ls -1 src - SConscript - hello.c - % scons - cc -c build/hello.c -o build/hello.o + % ls src + SConscript hello.c + % scons -Q + cc -c -o build/hello.o build/hello.c cc -o build/hello build/hello.o - % ls -1 build - hello - hello.c - hello.o + % ls build + SConscript hello hello.c hello.o @@ -419,6 +445,8 @@ program using the F path name. + diff --git a/doc/user/sourcecode.in b/doc/user/sourcecode.in index b794c09..30b6ecb 100644 --- a/doc/user/sourcecode.in +++ b/doc/user/sourcecode.in @@ -29,7 +29,7 @@ - X + XXX @@ -38,20 +38,23 @@ - X + XXX env = Environment() - env.SourceCode('.', env.BitKeeper('XXX')) + env.SourceCode('.', env.BitKeeper()) env.Program('hello.c') + + s.hello.c + - scons + scons -Q @@ -61,20 +64,20 @@ - X + XXX env = Environment() - env.SourceCode('.', env.CVS('XXX')) + env.SourceCode('.', env.CVS('/usr/local/CVS')) env.Program('hello.c') - scons + scons -Q @@ -84,7 +87,7 @@ - X + XXX @@ -94,10 +97,13 @@ env.SourceCode('.', env.RCS()) env.Program('hello.c') + + hello.c,v + - scons + scons -Q @@ -107,7 +113,7 @@ - X + XXX @@ -117,10 +123,13 @@ env.SourceCode('.', env.SCCS()) env.Program('hello.c') + + s.hello.c + - scons + scons -Q @@ -132,7 +141,7 @@ - X + XXX @@ -145,7 +154,7 @@ - scons + scons -Q diff --git a/doc/user/sourcecode.sgml b/doc/user/sourcecode.sgml index 6bbccee..74b7347 100644 --- a/doc/user/sourcecode.sgml +++ b/doc/user/sourcecode.sgml @@ -29,7 +29,7 @@ - X + XXX @@ -38,19 +38,22 @@ - X + XXX env = Environment() - env.SourceCode('.', env.BitKeeper('XXX')) + env.SourceCode('.', env.BitKeeper()) env.Program('hello.c') - % scons - XXX + % scons -Q + bk get - + bk get hello.c + cc -c -o hello.o hello.c + cc -o hello hello.o @@ -60,19 +63,22 @@ - X + XXX env = Environment() - env.SourceCode('.', env.CVS('XXX')) + env.SourceCode('.', env.CVS('/usr/local/CVS')) env.Program('hello.c') - % scons - XXX + % scons -Q + cvs -d /usr/local/CVS co - + cvs -d /usr/local/CVS co hello.c + cc -c -o hello.o hello.c + cc -o hello hello.o @@ -82,7 +88,7 @@ - X + XXX @@ -93,8 +99,11 @@ - % scons - XXX + % scons -Q + co - + co hello.c + cc -c -o hello.o hello.c + cc -o hello hello.o @@ -104,7 +113,7 @@ - X + XXX @@ -115,30 +124,38 @@ - % scons - XXX + % scons -Q + sccs get - + sccs get hello.c + cc -c -o hello.o hello.c + cc -o hello hello.o + diff --git a/doc/user/variants.in b/doc/user/variants.in index 1fb461a..ceab8f6 100644 --- a/doc/user/variants.in +++ b/doc/user/variants.in @@ -27,66 +27,6 @@ =head1 Variant builds - -=head2 Hello, World! for baNaNa and peAcH OS's - -Variant builds require just another simple extension. Let's take as an -example a requirement to allow builds for both the baNaNa and peAcH -operating systems. In this case, we are using a distributed file system, -such as NFS to access the particular system, and only one or the other of -the systems has to be compiled for any given invocation of C. Here's -one way we could set up the F file for our B -application: - - # Construct file for Hello, World! - - die qq(OS must be specified) unless $OS = $ARG{OS}; - die qq(OS must be "peach" or "banana") - if $OS ne "peach" && $OS ne "banana"; - - # Where to put all our shared products. - $EXPORT = "#export/$OS"; - - Export qw( CONS INCLUDE LIB BIN ); - - # Standard directories for sharing products. - $INCLUDE = "$EXPORT/include"; - $LIB = "$EXPORT/lib"; - $BIN = "$EXPORT/bin"; - - # A standard construction environment. - $CONS = new cons ( - CPPPATH => $INCLUDE, # Include path for C Compilations - LIBPATH => $LIB, # Library path for linking programs - LIBS => '-lworld', # List of standard libraries - ); - - # $BUILD is where we will derive everything. - $BUILD = "#build/$OS"; - - # Tell cons where the source files for $BUILD are. - Link $BUILD => 'src'; - - Build ( - "$BUILD/hello/Conscript", - "$BUILD/world/Conscript", - ); - -Now if we login to a peAcH system, we can build our B -application for that platform: - - % cons export OS=peach - Install build/peach/world/world.h as export/peach/include/world.h - cc -Iexport/peach/include -c build/peach/hello/hello.c -o build/peach/hello/hello.o - cc -Iexport/peach/include -c build/peach/world/world.c -o build/peach/world/world.o - ar r build/peach/world/libworld.a build/peach/world/world.o - ar: creating build/peach/world/libworld.a - ranlib build/peach/world/libworld.a - Install build/peach/world/libworld.a as export/peach/lib/libworld.a - cc -o build/peach/hello/hello build/peach/hello/hello.o -Lexport/peach/lib -lworld - Install build/peach/hello/hello as export/peach/bin/hello - - =head2 Variations on a theme Other variations of this model are possible. For example, you might decide @@ -122,26 +62,59 @@ is pretty smart about rebuilding things when you change options. - platform = ARGUMENT.get('OS', Platform()) + platform = ARGUMENTS.get('OS', Platform()) include = "#export/$PLATFORM/include" lib = "#export/$PLATFORM/lib" bin = "#export/$PLATFORM/bin" env = Environment(PLATFORM = platform, + BINDIR = bin, + INCDIR = include, + LIBDIR = lib, CPPPATH = [include], - LIB = lib, - LIBS = '-lworld') + LIBPATH = [lib], + LIBS = 'world') Export('env') - SConscript('src/SConscript', build_dir='build/$PLATFORM') + env.SConscript('src/SConscript', build_dir='build/$PLATFORM') # #BuildDir("#build/$PLATFORM", 'src') #SConscript("build/$PLATFORM/hello/SConscript") #SConscript("build/$PLATFORM/world/SConscript") + + + + + Import('env') + SConscript('hello/SConscript') + SConscript('world/SConscript') + + + Import('env') + hello = env.Program('hello.c') + env.Install('$BINDIR', hello) + + + #include "world.h" + int main(int argc, char *argv[]) { printf "hello.c\n"; world(); } + + + Import('env') + world = env.Library('world.c') + env.Install('$LIBDIR', world) + env.Install('$INCDIR', 'world.h') + + + #define STRING "world.h" + extern int world(); + + + int world() { printf "world.c\n"; } + @@ -152,7 +125,7 @@ is pretty smart about rebuilding things when you change options. - scons OS=linux + scons -Q OS=linux @@ -162,18 +135,21 @@ is pretty smart about rebuilding things when you change options. - scons OS=windows + scons -Q OS=windows + diff --git a/doc/user/variants.sgml b/doc/user/variants.sgml index 09dd16d..4ddb40b 100644 --- a/doc/user/variants.sgml +++ b/doc/user/variants.sgml @@ -27,66 +27,6 @@ =head1 Variant builds - -=head2 Hello, World! for baNaNa and peAcH OS's - -Variant builds require just another simple extension. Let's take as an -example a requirement to allow builds for both the baNaNa and peAcH -operating systems. In this case, we are using a distributed file system, -such as NFS to access the particular system, and only one or the other of -the systems has to be compiled for any given invocation of C. Here's -one way we could set up the F file for our B -application: - - # Construct file for Hello, World! - - die qq(OS must be specified) unless $OS = $ARG{OS}; - die qq(OS must be "peach" or "banana") - if $OS ne "peach" && $OS ne "banana"; - - # Where to put all our shared products. - $EXPORT = "#export/$OS"; - - Export qw( CONS INCLUDE LIB BIN ); - - # Standard directories for sharing products. - $INCLUDE = "$EXPORT/include"; - $LIB = "$EXPORT/lib"; - $BIN = "$EXPORT/bin"; - - # A standard construction environment. - $CONS = new cons ( - CPPPATH => $INCLUDE, # Include path for C Compilations - LIBPATH => $LIB, # Library path for linking programs - LIBS => '-lworld', # List of standard libraries - ); - - # $BUILD is where we will derive everything. - $BUILD = "#build/$OS"; - - # Tell cons where the source files for $BUILD are. - Link $BUILD => 'src'; - - Build ( - "$BUILD/hello/Conscript", - "$BUILD/world/Conscript", - ); - -Now if we login to a peAcH system, we can build our B -application for that platform: - - % cons export OS=peach - Install build/peach/world/world.h as export/peach/include/world.h - cc -Iexport/peach/include -c build/peach/hello/hello.c -o build/peach/hello/hello.o - cc -Iexport/peach/include -c build/peach/world/world.c -o build/peach/world/world.o - ar r build/peach/world/libworld.a build/peach/world/world.o - ar: creating build/peach/world/libworld.a - ranlib build/peach/world/libworld.a - Install build/peach/world/libworld.a as export/peach/lib/libworld.a - cc -o build/peach/hello/hello build/peach/hello/hello.o -Lexport/peach/lib -lworld - Install build/peach/hello/hello as export/peach/bin/hello - - =head2 Variations on a theme Other variations of this model are possible. For example, you might decide @@ -121,20 +61,23 @@ is pretty smart about rebuilding things when you change options. - platform = ARGUMENT.get('OS', Platform()) + platform = ARGUMENTS.get('OS', Platform()) include = "#export/$PLATFORM/include" lib = "#export/$PLATFORM/lib" bin = "#export/$PLATFORM/bin" env = Environment(PLATFORM = platform, + BINDIR = bin, + INCDIR = include, + LIBDIR = lib, CPPPATH = [include], - LIB = lib, - LIBS = '-lworld') + LIBPATH = [lib], + LIBS = 'world') Export('env') - SConscript('src/SConscript', build_dir='build/$PLATFORM') + env.SConscript('src/SConscript', build_dir='build/$PLATFORM') # #BuildDir("#build/$PLATFORM", 'src') @@ -150,16 +93,15 @@ is pretty smart about rebuilding things when you change options. - $ scons OS=linux - Install build/linux/world/world.h as export/linux/include/world.h - cc -Iexport/linux/include -c build/linux/hello/hello.c -o build/linux/hello/hello.o - cc -Iexport/linux/include -c build/linux/world/world.c -o build/linux/world/world.o + % scons -Q OS=linux + Install file: "build/linux/world/world.h" as "export/linux/include/world.h" + cc -Iexport/linux/include -c -o build/linux/hello/hello.o build/linux/hello/hello.c + cc -Iexport/linux/include -c -o build/linux/world/world.o build/linux/world/world.c ar r build/linux/world/libworld.a build/linux/world/world.o - ar: creating build/linux/world/libworld.a ranlib build/linux/world/libworld.a - Install build/linux/world/libworld.a as export/linux/lib/libworld.a + Install file: "build/linux/world/libworld.a" as "export/linux/lib/libworld.a" cc -o build/linux/hello/hello build/linux/hello/hello.o -Lexport/linux/lib -lworld - Install build/linux/hello/hello as export/linux/bin/hello + Install file: "build/linux/hello/hello" as "export/linux/bin/hello" @@ -168,28 +110,29 @@ is pretty smart about rebuilding things when you change options. - - C:\test\>scons OS=linux - Install build\linux\world\world.h as export\linux\include\world.h - cl /Iexport\linux\include /Fobuild\linux\hello\hello.obj build\linux\hello\hello.c - cl /Iexport\linux\include /Fobuild\linux\world\world.obj build\linux\world\world.c - XXX - ar r build\linux\world\world.lib build\linux\world\world.obj - Install build\linux\world\world.lib as export\linux\lib\libworld.a - link /Fobuild\linux\hello\hello.exe build\linux\hello\hello.obj -Lexport\linux\lib world.lib - Install build\linux\hello\hello.exe as export\linux\bin\hello.exe + C:\>scons -Q OS=windows + Install file: "build/windows/world/world.h" as "export/windows/include/world.h" + cl /nologo /Iexport\windows\include /c build\windows\hello\hello.c /Fobuild\windows\hello\hello.obj + cl /nologo /Iexport\windows\include /c build\windows\world\world.c /Fobuild\windows\world\world.obj + lib /nologo /OUT:build\windows\world\world.lib build\windows\world\world.obj + Install file: "build/windows/world/world.lib" as "export/windows/lib/world.lib" + link /nologo /OUT:build\windows\hello\hello.exe /LIBPATH:export\windows\lib world.lib build\windows\hello\hello.obj + Install file: "build/windows/hello/hello.exe" as "export/windows/bin/hello.exe" - - env = Environment(OS = ) + diff --git a/rpm/scons.spec.in b/rpm/scons.spec.in index 53a245c..2160041 100644 --- a/rpm/scons.spec.in +++ b/rpm/scons.spec.in @@ -1,5 +1,5 @@ %define name scons -%define version 0.92 +%define version 0.93 %define release 1 Summary: an Open Source software construction tool diff --git a/src/CHANGES.txt b/src/CHANGES.txt index d7a4aec..61dad1e 100644 --- a/src/CHANGES.txt +++ b/src/CHANGES.txt @@ -8,7 +8,7 @@ -RELEASE X.XX - XXX +RELEASE 0.93 - Thu, 23 Oct 2003 07:26:55 -0500 From J.T. Conklin: @@ -135,6 +135,9 @@ RELEASE X.XX - XXX - Supply a warning when -j is used and threading isn't built in to the current version of Python. + - First release of the User's Guide (finally, and despite a lot + of things still missing from it...). + From Clark McGrew: - Generalize the action for .tex files so that it will decide whether diff --git a/src/README.txt b/src/README.txt index 0e2672d..bccfb32 100644 --- a/src/README.txt +++ b/src/README.txt @@ -50,8 +50,8 @@ Python until Python version 1.6, so if your system is running Python 1.5.2, you may not have distutils installed. If you are running Python version 1.6 or later, you should be fine. -NOTE TO RED HAT USERS: All Red Hat Linux versions up to 7.3 still ship -Python 1.5.2 as the default, so you probably do *not* have distutils +NOTE TO RED HAT USERS: Red Hat shipped Python 1.5.2 as the default all +the way up to Red Hat Linux 7.3, so you probably do *not* have distutils installed, unless you have already done so manually or are running Red Hat 8.0 or later. diff --git a/src/RELEASE.txt b/src/RELEASE.txt index f883940..6e43f50 100644 --- a/src/RELEASE.txt +++ b/src/RELEASE.txt @@ -20,7 +20,7 @@ more effectively, please sign up for the scons-users mailing list at: -RELEASE X.XX - XXX +RELEASE 0.93 - Thu, 23 Oct 2003 07:26:55 -0500 This is the fourth beta release of SCons. Please consult the CHANGES.txt file for a list of specific changes since last release. diff --git a/src/setupTests.py b/src/setupTests.py index 950dbdb..1397561 100644 --- a/src/setupTests.py +++ b/src/setupTests.py @@ -52,7 +52,7 @@ except KeyError: # version = os.environ['SCONS_VERSION'] #except KeyError: # version = '__VERSION__' -version = '0.92' +version = '0.93' scons_version = 'scons-%s' % version -- cgit v0.12