diff options
| -rw-r--r-- | README | 34 | ||||
| -rw-r--r-- | SConstruct | 2 | ||||
| -rw-r--r-- | debian/changelog | 7 | ||||
| -rw-r--r-- | doc/scons.mod | 18 | ||||
| -rw-r--r-- | doc/user/builders-writing.in | 158 | ||||
| -rw-r--r-- | doc/user/builders-writing.sgml | 107 | ||||
| -rw-r--r-- | doc/user/depends.in | 285 | ||||
| -rw-r--r-- | doc/user/depends.sgml | 258 | ||||
| -rw-r--r-- | doc/user/hierarchy.in | 146 | ||||
| -rw-r--r-- | doc/user/hierarchy.sgml | 172 | ||||
| -rw-r--r-- | doc/user/main.in | 30 | ||||
| -rw-r--r-- | doc/user/main.sgml | 30 | ||||
| -rw-r--r-- | doc/user/preface.in | 29 | ||||
| -rw-r--r-- | doc/user/preface.sgml | 33 | ||||
| -rw-r--r-- | doc/user/repositories.in | 52 | ||||
| -rw-r--r-- | doc/user/repositories.sgml | 56 | ||||
| -rw-r--r-- | doc/user/scanners.in | 210 | ||||
| -rw-r--r-- | doc/user/scanners.sgml | 196 | ||||
| -rw-r--r-- | doc/user/separate.in | 149 | ||||
| -rw-r--r-- | doc/user/separate.sgml | 144 | ||||
| -rw-r--r-- | doc/user/sourcecode.in | 35 | ||||
| -rw-r--r-- | doc/user/sourcecode.sgml | 61 | ||||
| -rw-r--r-- | doc/user/variants.in | 114 | ||||
| -rw-r--r-- | doc/user/variants.sgml | 123 | ||||
| -rw-r--r-- | rpm/scons.spec.in | 2 | ||||
| -rw-r--r-- | src/CHANGES.txt | 5 | ||||
| -rw-r--r-- | src/README.txt | 4 | ||||
| -rw-r--r-- | src/RELEASE.txt | 2 | ||||
| -rw-r--r-- | src/setupTests.py | 2 |
29 files changed, 1662 insertions, 802 deletions
@@ -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. @@ -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 fe292e1b..449c177c 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,10 @@ +scons (0.93-1) unstable; urgency=low + + * Fourth beta release. + + -- Steven Knight <knight@baldmt.com> 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 19190b23..958444d2 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -73,6 +73,7 @@ <!ENTITY implicit-cache "<literal>--implicit-cache</literal>"> <!ENTITY implicit-deps-changed "<literal>--implicit-deps-changed</literal>"> <!ENTITY implicit-deps-unchanged "<literal>--implicit-deps-unchanged</literal>"> +<!ENTITY Q "<literal>-Q</literal>"> <!-- @@ -127,6 +128,7 @@ <!ENTITY Export "<function>Export</function>"> <!ENTITY Help "<function>Help</function>"> <!ENTITY Ignore "<function>Ignore</function>"> +<!ENTITY Import "<function>Import</function>"> <!ENTITY Install "<function>Install</function>"> <!ENTITY InstallAs "<function>InstallAs</function>"> <!ENTITY Link "<function>Link</function>"> @@ -137,6 +139,7 @@ <!ENTITY Prepend "<function>Prepend</function>"> <!ENTITY Replace "<function>Replace</function>"> <!ENTITY Repository "<function>Repository</function>"> +<!ENTITY Return "<function>Return</function>"> <!ENTITY RuleSet "<function>RuleSet</function>"> <!ENTITY Salt "<function>Salt</function>"> <!ENTITY SetBuildSignatureType "<function>SetBuildSignatureType</function>"> @@ -163,6 +166,13 @@ <!ENTITY BUILDERMAP "<varname>BUILDERMAP</varname>"> <!ENTITY BUILDERS "<varname>BUILDERS</varname>"> +<!ENTITY LIBDIRPREFIX "<varname>LIBDIRPREFIX</varname>"> +<!ENTITY LIBDIRSUFFIX "<varname>LIBDIRSUFFIX</varname>"> +<!ENTITY LIBLINKPREFIX "<varname>LIBLINKPREFIX</varname>"> +<!ENTITY LIBLINKSUFFIX "<varname>LIBLINKSUFFIX</varname>"> +<!ENTITY LINK "<varname>LINK</varname>"> +<!ENTITY LINKCOM "<varname>LINKCOM</varname>"> +<!ENTITY LINKFLAGS "<varname>LINKFLAGS</varname>"> <!ENTITY SCANNERMAP "<varname>SCANNERMAP</varname>"> <!ENTITY SCANNERS "<varname>SCANNERS</varname>"> <!ENTITY TARFLAGS "<varname>TARFLAGS</varname>"> @@ -272,14 +282,22 @@ --> +<!ENTITY bar "<application>bar</application>"> <!ENTITY common1_c "<application>common1.c</application>"> <!ENTITY common2_c "<application>common2.c</application>"> <!ENTITY goodbye "<application>goodbye</application>"> +<!ENTITY file_dll "<application>file.dll</application>"> +<!ENTITY file_lib "<application>file.lib</application>"> +<!ENTITY file_o "<application>file.o</application>"> +<!ENTITY file_obj "<application>file.obj</application>"> +<!ENTITY foo "<application>foo</application>"> <!ENTITY hello "<application>hello</application>"> <!ENTITY hello_c "<filename>hello.c</filename>"> <!ENTITY hello_exe "<filename>hello.exe</filename>"> <!ENTITY hello_h "<filename>hello.h</filename>"> <!ENTITY hello_o "<filename>hello.o</filename>"> +<!ENTITY libfile_a "<filename>libfile_a</filename>"> +<!ENTITY libfile_so "<filename>libfile_so</filename>"> <!ENTITY prog "<filename>prog</filename>"> <!ENTITY prog1 "<filename>prog1</filename>"> <!ENTITY prog2 "<filename>prog2</filename>"> diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in index d911f6c2..50c91148 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: <file name="SConstruct"> 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> <file name="file.input"> file.input </file> + <file name="foobuild" chmod="0755"> + cat + </file> </scons_example> - <programlisting> + <sconstruct> bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) - </programlisting> + </sconstruct> <para> @@ -197,7 +202,7 @@ This functionality could be invoked as in the following example: </para> <scons_output example="ex1"> - <command>scons</command> + <command>scons -Q</command> </scons_output> <para> @@ -229,23 +234,8 @@ This functionality could be invoked as in the following example: </file> </scons_example> - <!-- - 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_output example="ex2"> - <command>scons</command> + <command>scons -Q</command> </scons_output> <para> @@ -260,6 +250,8 @@ This functionality could be invoked as in the following example: <scons_example name="ex3"> <file name="SConstruct"> 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: <file name="hello.c"> hello.c </file> + <file name="foobuild" chmod="0755"> + cat + </file> </scons_example> + <sconstruct> + env = Environment() + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + env.Append(BUILDERS = {'Foo' : bld}) + env.Foo('file.foo', 'file.input') + env.Program('hello.c') + </sconstruct> + <para> Or you can explicitly set the appropriately-named @@ -280,13 +283,13 @@ This functionality could be invoked as in the following example: </para> - <programlisting> + <sconstruct> env = Environment() bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env['BUILDERS']['Foo'] = bld env.Foo('file.foo', 'file.input') env.Program('hello.c') - </programlisting> + </sconstruct> <para> @@ -298,7 +301,7 @@ This functionality could be invoked as in the following example: </para> <scons_output example="ex3"> - <command>scons</command> + <command>scons -Q</command> </scons_output> </section> @@ -324,11 +327,13 @@ This functionality could be invoked as in the following example: </para> <scons_example name="ex4"> - <file name="SConstruct" printme="1"> - bld = Builder(action = 'foobuild < $TARGET > $SOURCE', + <file name="SConstruct"> + 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') </file> @@ -338,10 +343,22 @@ This functionality could be invoked as in the following example: <file name="file2.input"> file2.input </file> + <file name="foobuild" chmod="0755"> + cat + </file> </scons_example> + <sconstruct> + bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + suffix = '.foo', + src_suffix = '.input') + env = Environment(BUILDERS = {'Foo' : bld}) + env.Foo('file1') + env.Foo('file2') + </sconstruct> + <scons_output example="ex4"> - <command>scons</command> + <command>scons -Q</command> </scons_output> <para> @@ -370,7 +387,7 @@ This functionality could be invoked as in the following example: <programlisting> def build_function(target, source, env): - # XXX + # Code to build "target" from "source" return None </programlisting> @@ -459,7 +476,7 @@ This functionality could be invoked as in the following example: <scons_example name="ex5"> <file name="SConstruct" printme="1"> 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: </para> <scons_output example="ex5"> - <command>scons</command> + <command>scons -Q</command> </scons_output> </section> @@ -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: </para> <programlisting> def generate_actions(source, target, env, for_signature): - return XXX + return 'foobuild < %s > %s' % (target[0], source[0]) </programlisting> <para> @@ -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 + <!-- XXX NEED MORE HERE --> </para> </listitem> @@ -602,20 +621,37 @@ This functionality could be invoked as in the following example: </para> <scons_example name="ex6"> - <file name="SConstruct" printme="1"> + <file name="SConstruct"> + 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> <file name="file.input"> file.input </file> + <file name="foobuild" chmod="0755"> + cat + </file> </scons_example> + <sconstruct> + 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') + </sconstruct> + <scons_output example="ex6"> - <command>scons</command> + <command>scons -Q</command> </scons_output> <para> @@ -641,23 +677,46 @@ This functionality could be invoked as in the following example: </para> <scons_example name="ex7"> - <file name="SConstruct" printme="1"> - def modify_targets(XXX): - return XXX - bld = Builder(action = 'XXX', + <file name="SConstruct"> + 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> <file name="file.input"> file.input </file> - </programlisting> + <file name="new_source"> + new_source + </file> + <file name="foobuild" chmod="0755"> + cat + </file> + </scons_example> + + <sconstruct> + 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') + </sconstruct> <scons_output example="ex7"> - <command>scons</command> + <command>scons -Q</command> </scons_output> <programlisting> @@ -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: </section> + <!-- + <section> <title>Builders That Use Other Builders</title> @@ -691,13 +752,18 @@ This functionality could be invoked as in the following example: <scons_example name="ex8"> <file name="SConstruct" printme="1"> env = Environment() - env.SourceCode('.', env.BitKeeper('XXX')) + #env.SourceCode('.', env.BitKeeper('XXX')) env.Program('hello.c') </file> - </programlisting> + <file name="hello.c"> + hello.c + </file> + </scons_example> <scons_output example="ex8"> - <command>scons</command> + <command>scons -Q</command> </scons_output> </section> + + --> diff --git a/doc/user/builders-writing.sgml b/doc/user/builders-writing.sgml index 27a48b97..796e1994 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: </para> <programlisting> - bld = Builder(action = 'foobuild < $TARGET > $SOURCE') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') </programlisting> <para> @@ -163,8 +163,10 @@ This functionality could be invoked as in the following example: </para> + + <programlisting> - bld = Builder(action = 'foobuild < $TARGET > $SOURCE') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) </programlisting> @@ -186,7 +188,7 @@ This functionality could be invoked as in the following example: </para> <literallayout> - % <userinput>scons</userinput> + % <userinput>scons -Q</userinput> foobuild < file.input > file.foo </literallayout> @@ -205,26 +207,15 @@ This functionality could be invoked as in the following example: </para> <programlisting> - 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') </programlisting> <literallayout> - % <userinput>scons</userinput> - 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' + % <userinput>scons -Q</userinput> + AttributeError: SConsEnvironment instance has no attribute 'Program': </literallayout> <para> @@ -236,9 +227,11 @@ This functionality could be invoked as in the following example: </para> + + <programlisting> 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: <programlisting> 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: </para> <literallayout> - % <userinput>scons</userinput> + % <userinput>scons -Q</userinput> foobuild < file.input > file.foo - cc -c hello.c -o hello.o + cc -c -o hello.o hello.c cc -o hello hello.o </literallayout> @@ -297,8 +290,10 @@ This functionality could be invoked as in the following example: </para> + + <programlisting> - 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: </programlisting> <literallayout> - % <userinput>scons</userinput> + % <userinput>scons -Q</userinput> foobuild < file1.input > file1.foo foobuild < file2.input > file2.foo </literallayout> @@ -338,7 +333,7 @@ This functionality could be invoked as in the following example: <programlisting> def build_function(target, source, env): - # XXX + # Code to build "target" from "source" return None </programlisting> @@ -426,7 +421,7 @@ This functionality could be invoked as in the following example: <programlisting> 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: </para> <literallayout> - % <userinput>scons</userinput> + % <userinput>scons -Q</userinput> build_function("file.foo", "file.input") </literallayout> @@ -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: </para> <programlisting> def generate_actions(source, target, env, for_signature): - return XXX + return 'foobuild < %s > %s' % (target[0], source[0]) </programlisting> <para> @@ -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 + <!-- XXX NEED MORE HERE --> </para> </listitem> @@ -565,7 +562,11 @@ This functionality could be invoked as in the following example: </para> + + <programlisting> + def generate_actions(source, target, env, for_signature): + return 'foobuild < %s > %s' % (source[0], target[0]) bld = Builder(generator = generate_actions, suffix = '.foo', src_suffix = '.input') @@ -574,8 +575,8 @@ This functionality could be invoked as in the following example: </programlisting> <literallayout> - % <userinput>scons</userinput> - XXX + % <userinput>scons -Q</userinput> + foobuild < file.input > file.foo </literallayout> <para> @@ -600,10 +601,14 @@ This functionality could be invoked as in the following example: </para> + + <programlisting> - 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: </programlisting> <literallayout> - % <userinput>scons</userinput> - XXX + % <userinput>scons -Q</userinput> + foobuild file.foo new_target - file.input new_source </literallayout> <programlisting> @@ -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: </section> + <!-- + <section> <title>Builders That Use Other Builders</title> @@ -644,15 +651,21 @@ This functionality could be invoked as in the following example: </para> - <programlisting> + <scons_example name="ex8"> + <file name="SConstruct" printme="1"> env = Environment() - env.SourceCode('.', env.BitKeeper('XXX') + #env.SourceCode('.', env.BitKeeper('XXX')) env.Program('hello.c') - </programlisting> + </file> + <file name="hello.c"> + hello.c + </file> + </scons_example> - <literallayout> - % <userinput>scons</userinput> - XXX - </literallayout> + <scons_output example="ex8"> + <command>scons -Q</command> + </scons_output> </section> + + --> diff --git a/doc/user/depends.in b/doc/user/depends.in index aa69dc7c..bedc91d6 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<uname <scons_example name="ex1"> <file name="SConstruct"> - env = Environment() - env.Program('hello.c') + Program('hello.c') </file> <file name="hello.c"> int main() { printf("Hello, world!\n"); } @@ -68,8 +67,8 @@ operating system on which the build is performed (as reported by C<uname </scons_example> <scons_output example="ex1" os="posix"> - <command>scons</command> - <command>scons</command> + <command>scons -Q</command> + <command>scons -Q</command> </scons_output> <para> @@ -84,8 +83,8 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1" os="posix"> - <command>scons hello</command> - <command>scons hello</command> + <command>scons -Q hello</command> + <command>scons -Q hello</command> </scons_output> <para> @@ -133,9 +132,9 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1" os="posix"> - <command>scons hello</command> + <command>scons -Q hello</command> <command>touch hello.c</command> - <command>scons hello</command> + <command>scons -Q hello</command> </scons_output> <para> @@ -155,26 +154,10 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1" os="posix"> - <command>scons hello</command> - <command output="[CHANGE THE CONTENTS OF hello.c]">edit hello.c</command> - <command>scons hello</command> - </scons> - - <!-- - - <literallayout> - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o - cc -o hello hello.o - % <userinput>edit hello.c</userinput> - [CHANGE THE CONTENTS OF hello.c] - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o - cc -o hello hello.o - % - </literallayout> - - --> + <command>scons -Q hello</command> + <command output=" [CHANGE THE CONTENTS OF hello.c]">edit hello.c</command> + <command>scons -Q hello</command> + </scons_output> <para> @@ -186,8 +169,7 @@ operating system on which the build is performed (as reported by C<uname </para> <sconstruct> - env = Environment() - env.Program('hello.c') + Program('hello.c') SourceSignatures('MD5') </sconstruct> @@ -210,8 +192,7 @@ operating system on which the build is performed (as reported by C<uname <scons_example name="ex2"> <file name="SConstruct" printme="1"> - env = Environment() - env.Program('hello.c') + Program('hello.c') SourceSignatures('timestamp') </file> <file name="hello.c"> @@ -227,11 +208,11 @@ operating system on which the build is performed (as reported by C<uname </para> - <scons_output example="ex1" os="posix"> - <command>scons hello</command> + <scons_output example="ex2" os="posix"> + <command>scons -Q hello</command> <command>touch hello.c</command> - <command>scons hello</command> - </scons> + <command>scons -Q hello</command> + </scons_output> </section> @@ -247,8 +228,8 @@ operating system on which the build is performed (as reported by C<uname target file is up to date or must be rebuilt. When a target file depends on another target file, &SCons; allows you to separately configure - how the signatures of an "intermediate" target file - is used when deciding if a dependent target file + how the signatures of "intermediate" target files + are used when deciding if a dependent target file must be rebuilt. </para> @@ -271,26 +252,10 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1" os="posix"> - <command>scons hello</command> - <command output="[CHANGE THE CONTENTS OF hello.c]">edit hello.c</command> - <command>scons hello</command> - </scons> - - <!-- - - <literallayout> - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o - cc -o hello hello.o - % <userinput>edit hello.c</userinput> - [CHANGE THE CONTENTS OF hello.c] - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o - cc -o hello hello.o - % - </literallayout> - - --> + <command>scons -Q hello</command> + <command output=" [CHANGE THE CONTENTS OF hello.c]">edit hello.c</command> + <command>scons -Q hello</command> + </scons_output> <para> @@ -324,8 +289,7 @@ operating system on which the build is performed (as reported by C<uname </para> <sconstruct> - env = Environment() - env.Program('hello.c') + Program('hello.c') TargetSignatures('build') </sconstruct> @@ -344,17 +308,16 @@ operating system on which the build is performed (as reported by C<uname If so, then any other target files that depend on such a built-but-not-changed target file actually need not be rebuilt. - You can have &SCons; - realize that a dependent target file - need not be rebuilt in this situation + You can make &SCons; + realize that it does not need to rebuild + a dependent target file in this situation using the &TargetSignatures; function as follows: </para> <scons_example name="ex3"> <file name="SConstruct" printme="1"> - env = Environment() - env.Program('hello.c') + Program('hello.c') TargetSignatures('content') </file> <file name="hello.c"> @@ -376,10 +339,10 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex3" os="posix"> - <command>scons hello</command> - <command output="[CHANGE A COMMENT IN hello.c]">edit hello.c</command> - <command>scons hello</command> - </scons> + <command>scons -Q hello</command> + <command output=" [CHANGE A COMMENT IN hello.c]" edit="STRIP CCCOM line">edit hello.c</command> + <command>scons -Q hello</command> + </scons_output> <para> @@ -413,19 +376,18 @@ operating system on which the build is performed (as reported by C<uname <scons_example name="ex4"> <file name="SConstruct"> - env = Environment(CPPPATH = '.') - hello = env.Program('hello.c') + Program('hello.c', CPPPATH = '.') </file> <file name="hello.c" printme="1"> - #include "hello.h" - int - main() - { - printf("Hello, %s!\n", string); - } + #include "hello.h" + int + main() + { + printf("Hello, %s!\n", string); + } </file> <file name="hello.h"> - #define string "world" + #define string "world" </file> </scons_example> @@ -453,7 +415,7 @@ operating system on which the build is performed (as reported by C<uname <para> - The &CPPPATH; assignment in the &Environment; call + The &CPPPATH; value tells &SCons; to look in the current directory (<literal>'.'</literal>) for any files included by C source files @@ -463,11 +425,11 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex4" os="posix"> - <command>scons hello</command> - <command>scons hello</command> - <command output="[CHANGE THE CONTENTS IN hello.h]">edit hello.h</command> - <command>scons hello</command> - </scons> + <command>scons -Q hello</command> + <command>scons -Q hello</command> + <command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command> + <command>scons -Q hello</command> + </scons_output> <para> @@ -512,13 +474,9 @@ operating system on which the build is performed (as reported by C<uname </para> - <programlisting> - </programlisting> - <scons_example name="ex5"> - <file name="SConstruct"> - env = Environment(CPPPATH = ['include', '/home/project/inc']) - hello = env.Program('hello.c') + <file name="SConstruct" printme="1"> + Program('hello.c', CPPPATH = ['include', '/home/project/inc']) </file> <file name="hello.c"> int main() { printf("Hello, world!\n"); } @@ -531,8 +489,8 @@ operating system on which the build is performed (as reported by C<uname </para> - <scons_output example="ex4" os="posix"> - <command>scons hello</command> + <scons_output example="ex5" os="posix"> + <command>scons -Q hello</command> </scons_output> <para> @@ -541,8 +499,8 @@ operating system on which the build is performed (as reported by C<uname </para> - <scons_output example="ex4" os="win32"> - <command>scons hello</command> + <scons_output example="ex5" os="win32"> + <command>scons -Q hello.exe</command> </scons_output> </section> @@ -590,19 +548,22 @@ operating system on which the build is performed (as reported by C<uname the implicit dependencies that its scanners find, for use by later builds. - You do this either by specifying the + You can do this by specifying the &implicit-cache; option on the command line: </para> - <scons_output example="ex1" os="win32"> - <command>scons --implicit-cache hello</command> - <command>scons hello</command> + <scons_output example="ex1"> + <command>scons -Q --implicit-cache hello</command> + <command>scons -Q hello</command> </scons_output> <para> - 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: </para> @@ -611,25 +572,52 @@ operating system on which the build is performed (as reported by C<uname SetOption('implicit_cache', 1) </sconstruct> - <para> + <!-- - &SCons; does not cache implicit dependencies like this by default - because XXX + <para> + XXX + </para> <para> - - XXX + &SCons; does not cache implicit dependencies like this by default + because XXX + </para> + --> + <section> <title>The &implicit-deps-changed; Option</title> <para> - 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: + + </para> + + <scons_output example="ex1"> + <command>scons -Q --implicit-deps-changed hello</command> + <command>scons -Q hello</command> + </scons_output> + + <para> + + In this case, &SCons; will re-scan all of the implicit dependencies + and cache updated copies of the information. </para> @@ -640,7 +628,38 @@ operating system on which the build is performed (as reported by C<uname <para> - 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 <literal>#include</literal> lines. + In this case, + you can use the &implicit-deps-unchanged; option: + + </para> + + <scons_output example="ex1"> + <command>scons -Q --implicit-deps-unchanged hello</command> + <command>scons -Q hello</command> + </scons_output> + + <para> + + 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. </para> @@ -662,24 +681,42 @@ operating system on which the build is performed (as reported by C<uname </para> - <programlisting> - env = Environment() - hello = env.Program('hello.c') - env.Ignore(hello, 'hello.h') - </programlisting> + <scons_example name="ignore"> + <file name="SConstruct" printme="1"> + hello = Program('hello.c') + Ignore(hello, 'hello.h') + </file> + <file name="hello.c"> + #include "hello.h" + int main() { printf("Hello, %s!\n", string); } + </file> + <file name="hello.h"> + #define string "world" + </file> + </scons_example> <!-- XXX mention that you can use arrays for target and source? --> + <!-- + <scons_output example="ignore"> + <command>scons -Q hello</command> + <command>scons -Q hello</command> + <command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command> + <command>scons -Q hello</command> + XXX THIS EXAMPLE SHOULD BE UP-TO-DATE! XXX + </scons_output> + --> + <literallayout> - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o - cc -o hello hello.o - % <userinput>scons hello</userinput> - scons: `hello' is up to date. - % <userinput>edit hello.h</userinput> - [CHANGE THE CONTENTS OF hello.h] - % <userinput>scons hello</userinput> - scons: `hello' is up to date. + % <userinput>scons -Q hello</userinput> + cc -c -o hello.o hello.c + cc -o hello hello.o + % <userinput>scons -Q hello</userinput> + scons: `hello' is up to date. + % <userinput>edit hello.h</userinput> + [CHANGE THE CONTENTS OF hello.h] + % <userinput>scons -Q hello</userinput> + scons: `hello' is up to date. </literallayout> <para> @@ -718,7 +755,7 @@ operating system on which the build is performed (as reported by C<uname On the other hand, sometimes a file depends on another file - that has no &SCons; scanner will detect. + that is not detected by an &SCons; scanner. For this situation, &SCons; allows you to specific explicitly that one file depends on another file, @@ -736,14 +773,14 @@ operating system on which the build is performed (as reported by C<uname <!-- XXX mention that you can use arrays for target and source? --> <literallayout> - % <userinput>scons hello</userinput> + % <userinput>scons -Q hello</userinput> cc -c hello.c -o hello.o cc -o hello hello.o - % <userinput>scons hello</userinput> + % <userinput>scons -Q hello</userinput> scons: `hello' is up to date. % <userinput>edit other_file</userinput> [CHANGE THE CONTENTS OF other_file] - % <userinput>scons hello</userinput> + % <userinput>scons -Q hello</userinput> cc -c hello.c -o hello.o cc -o hello hello.o </literallayout> diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml index 2049caf3..f595e085 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<uname </para> + + <literallayout> - % <userinput>scons</userinput> - cc -c hello.c -o hello.o + % <userinput>scons -Q</userinput> + cc -c -o hello.o hello.c cc -o hello hello.o - % <userinput>scons</userinput> - % + % <userinput>scons -Q</userinput> + scons: `.' is up to date. </literallayout> <para> @@ -77,12 +79,11 @@ operating system on which the build is performed (as reported by C<uname </para> <literallayout> - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o + % <userinput>scons -Q hello</userinput> + cc -c -o hello.o hello.c cc -o hello hello.o - % <userinput>scons hello</userinput> + % <userinput>scons -Q hello</userinput> scons: `hello' is up to date. - % </literallayout> <para> @@ -130,13 +131,12 @@ operating system on which the build is performed (as reported by C<uname </para> <literallayout> - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o + % <userinput>scons -Q hello</userinput> + cc -c -o hello.o hello.c cc -o hello hello.o % <userinput>touch hello.c</userinput> - % <userinput>scons hello</userinput> + % <userinput>scons -Q hello</userinput> scons: `hello' is up to date. - % </literallayout> <para> @@ -156,15 +156,14 @@ operating system on which the build is performed (as reported by C<uname </para> <literallayout> - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o + % <userinput>scons -Q hello</userinput> + cc -c -o hello.o hello.c cc -o hello hello.o % <userinput>edit hello.c</userinput> [CHANGE THE CONTENTS OF hello.c] - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o + % <userinput>scons -Q hello</userinput> + cc -c -o hello.o hello.c cc -o hello hello.o - % </literallayout> <para> @@ -177,8 +176,7 @@ operating system on which the build is performed (as reported by C<uname </para> <programlisting> - env = Environment() - env.Program('hello.c') + Program('hello.c') SourceSignatures('MD5') </programlisting> @@ -200,8 +198,7 @@ operating system on which the build is performed (as reported by C<uname </para> <programlisting> - env = Environment() - env.Program('hello.c') + Program('hello.c') SourceSignatures('timestamp') </programlisting> @@ -214,14 +211,13 @@ operating system on which the build is performed (as reported by C<uname </para> <literallayout> - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o + % <userinput>scons -Q hello</userinput> + cc -c -o hello.o hello.c cc -o hello hello.o % <userinput>touch hello.c</userinput> - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o + % <userinput>scons -Q hello</userinput> + cc -c -o hello.o hello.c cc -o hello hello.o - % </literallayout> </section> @@ -238,8 +234,8 @@ operating system on which the build is performed (as reported by C<uname target file is up to date or must be rebuilt. When a target file depends on another target file, &SCons; allows you to separately configure - how the signatures of an "intermediate" target file - is used when deciding if a dependent target file + how the signatures of "intermediate" target files + are used when deciding if a dependent target file must be rebuilt. </para> @@ -262,15 +258,14 @@ operating system on which the build is performed (as reported by C<uname </para> <literallayout> - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o + % <userinput>scons -Q hello</userinput> + cc -c -o hello.o hello.c cc -o hello hello.o % <userinput>edit hello.c</userinput> - [CHANGE THE CONTENTS OF hello.c] - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o + [CHANGE THE CONTENTS OF hello.c] + % <userinput>scons -Q hello</userinput> + cc -c -o hello.o hello.c cc -o hello hello.o - % </literallayout> <para> @@ -305,8 +300,7 @@ operating system on which the build is performed (as reported by C<uname </para> <programlisting> - env = Environment() - env.Program('hello.c') + Program('hello.c') TargetSignatures('build') </programlisting> @@ -325,16 +319,15 @@ operating system on which the build is performed (as reported by C<uname If so, then any other target files that depend on such a built-but-not-changed target file actually need not be rebuilt. - You can have &SCons; - realize that a dependent target file - need not be rebuilt in this situation + You can make &SCons; + realize that it does not need to rebuild + a dependent target file in this situation using the &TargetSignatures; function as follows: </para> <programlisting> - env = Environment() - env.Program('hello.c') + Program('hello.c') TargetSignatures('content') </programlisting> @@ -352,14 +345,14 @@ operating system on which the build is performed (as reported by C<uname </para> <literallayout> - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o + % <userinput>scons -Q hello</userinput> + cc -c -o hello.o hello.c cc -o hello hello.o % <userinput>edit hello.c</userinput> [CHANGE A COMMENT IN hello.c] - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o - % + % <userinput>scons -Q hello</userinput> + cc -c -o hello.o hello.c + scons: `hello' is up to date. </literallayout> <para> @@ -407,9 +400,10 @@ operating system on which the build is performed (as reported by C<uname </para> + <programlisting> #define string "world" - </programlisting> + </programlisting> <para> @@ -421,14 +415,14 @@ operating system on which the build is performed (as reported by C<uname </para> + <programlisting> - env = Environment(CPPPATH = '.') - hello = env.Program('hello.c') - </programlisting> + Program('hello.c', CPPPATH = '.') + </programlisting> <para> - The &CPPPATH; assignment in the &Environment; call + The &CPPPATH; value tells &SCons; to look in the current directory (<literal>'.'</literal>) for any files included by C source files @@ -438,17 +432,16 @@ operating system on which the build is performed (as reported by C<uname </para> <literallayout> - % <userinput>scons hello</userinput> - cc -I. -c hello.c -o hello.o + % <userinput>scons -Q hello</userinput> + cc -I. -c -o hello.o hello.c cc -o hello hello.o - % <userinput>scons hello</userinput> + % <userinput>scons -Q hello</userinput> scons: `hello' is up to date. % <userinput>edit hello.h</userinput> [CHANGE THE CONTENTS OF hello.h] - % <userinput>scons hello</userinput> - cc -I. -c hello.c -o hello.o + % <userinput>scons -Q hello</userinput> + cc -I. -c -o hello.o hello.c cc -o hello hello.o - % </literallayout> <para> @@ -490,13 +483,12 @@ operating system on which the build is performed (as reported by C<uname (':' on POSIX/Linux, ';' on Windows). Either way, &SCons; creates the right command-line options - so that the followin example: + so that the following example: </para> <programlisting> - env = Environment(CPPPATH = ['include', '/home/project/inc']) - hello = env.Program('hello.c') + Program('hello.c', CPPPATH = ['include', '/home/project/inc']) </programlisting> <para> @@ -506,8 +498,8 @@ operating system on which the build is performed (as reported by C<uname </para> <literallayout> - % <userinput>scons hello</userinput> - cc -Iinclude -I/home/project/inc -c hello.c -o hello.o + % <userinput>scons -Q hello</userinput> + cc -Iinclude -I/home/project/inc -c -o hello.o hello.c cc -o hello hello.o </literallayout> @@ -518,9 +510,9 @@ operating system on which the build is performed (as reported by C<uname </para> <literallayout> - % <userinput>scons hello</userinput> - cl /Iinclude /I\home\project\inc /Fohello.obj hello.c - link /OUT:hello.exe hello.obj + C:\><userinput>scons -Q hello.exe</userinput> + cl /nologo /Iinclude /I\home\project\inc /c hello.c /Fohello.obj + link /nologo /OUT:hello.exe hello.obj </literallayout> </section> @@ -568,49 +560,82 @@ operating system on which the build is performed (as reported by C<uname the implicit dependencies that its scanners find, for use by later builds. - You do this either by specifying the + You can do this by specifying the &implicit-cache; option on the command line: </para> <literallayout> - % <userinput>scons --implicit-cache hello</userinput> - cc -c hello.c -o hello.o + % <userinput>scons -Q --implicit-cache hello</userinput> + cc -c -o hello.o hello.c cc -o hello hello.o - % <userinput>scons hello</userinput> + % <userinput>scons -Q hello</userinput> scons: `hello' is up to date. </literallayout> <para> - 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: </para> - <literallayout> + <programlisting> SetOption('implicit_cache', 1) - </literallayout> + </programlisting> - <para> + <!-- - &SCons; does not cache implicit dependencies like this by default - because XXX + <para> + XXX + </para> <para> - - XXX + &SCons; does not cache implicit dependencies like this by default + because XXX + </para> + --> + <section> <title>The &implicit-deps-changed; Option</title> <para> - 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: + + </para> + + <literallayout> + % <userinput>scons -Q --implicit-deps-changed hello</userinput> + cc -c -o hello.o hello.c + cc -o hello hello.o + % <userinput>scons -Q hello</userinput> + scons: `hello' is up to date. + </literallayout> + + <para> + + In this case, &SCons; will re-scan all of the implicit dependencies + and cache updated copies of the information. </para> @@ -621,7 +646,41 @@ operating system on which the build is performed (as reported by C<uname <para> - 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 <literal>#include</literal> lines. + In this case, + you can use the &implicit-deps-unchanged; option: + + </para> + + <literallayout> + % <userinput>scons -Q --implicit-deps-unchanged hello</userinput> + cc -c -o hello.o hello.c + cc -o hello hello.o + % <userinput>scons -Q hello</userinput> + scons: `hello' is up to date. + </literallayout> + + <para> + + 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. </para> @@ -644,23 +703,32 @@ operating system on which the build is performed (as reported by C<uname </para> <programlisting> - env = Environment() - hello = env.Program('hello.c') - env.Ignore(hello, 'hello.h') + hello = Program('hello.c') + Ignore(hello, 'hello.h') </programlisting> <!-- XXX mention that you can use arrays for target and source? --> + <!-- + <scons_output example="ignore"> + <command>scons -Q hello</command> + <command>scons -Q hello</command> + <command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command> + <command>scons -Q hello</command> + XXX THIS EXAMPLE SHOULD BE UP-TO-DATE! XXX + </scons_output> + --> + <literallayout> - % <userinput>scons hello</userinput> - cc -c hello.c -o hello.o - cc -o hello hello.o - % <userinput>scons hello</userinput> - scons: `hello' is up to date. - % <userinput>edit hello.h</userinput> - [CHANGE THE CONTENTS OF hello.h] - % <userinput>scons hello</userinput> - scons: `hello' is up to date. + % <userinput>scons -Q hello</userinput> + cc -c -o hello.o hello.c + cc -o hello hello.o + % <userinput>scons -Q hello</userinput> + scons: `hello' is up to date. + % <userinput>edit hello.h</userinput> + [CHANGE THE CONTENTS OF hello.h] + % <userinput>scons -Q hello</userinput> + scons: `hello' is up to date. </literallayout> <para> @@ -699,7 +767,7 @@ operating system on which the build is performed (as reported by C<uname On the other hand, sometimes a file depends on another file - that has no &SCons; scanner will detect. + that is not detected by an &SCons; scanner. For this situation, &SCons; allows you to specific explicitly that one file depends on another file, @@ -717,14 +785,14 @@ operating system on which the build is performed (as reported by C<uname <!-- XXX mention that you can use arrays for target and source? --> <literallayout> - % <userinput>scons hello</userinput> + % <userinput>scons -Q hello</userinput> cc -c hello.c -o hello.o cc -o hello hello.o - % <userinput>scons hello</userinput> + % <userinput>scons -Q hello</userinput> scons: `hello' is up to date. % <userinput>edit other_file</userinput> [CHANGE THE CONTENTS OF other_file] - % <userinput>scons hello</userinput> + % <userinput>scons -Q hello</userinput> cc -c hello.c -o hello.o cc -o hello hello.o </literallayout> diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in index 5a34be29..cc059ed8 100644 --- a/doc/user/hierarchy.in +++ b/doc/user/hierarchy.in @@ -340,7 +340,7 @@ make no difference to the build. </para> <scons_output example="ex1"> - <command>scons</command> + <command>scons -Q</command> </scons_output> <para> @@ -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. </para> @@ -375,7 +378,6 @@ make no difference to the build. by appending a &hash; (hash mark) to the beginning of the path name: - </para> <scons_example name="ex2"> @@ -409,7 +411,7 @@ make no difference to the build. </para> <scons_output example="ex2"> - <command>scons</command> + <command>scons -Q</command> </scons_output> <para> @@ -460,7 +462,7 @@ make no difference to the build. </para> <scons_output example="ex3"> - <command>scons</command> + <command>scons -Q</command> </scons_output> <para> @@ -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. <para> - XXX + You may export more than one variable name at a time: </para> @@ -543,7 +545,9 @@ make no difference to the build. <para> - 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: </para> @@ -603,7 +607,10 @@ make no difference to the build. <para> - 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: </para> @@ -614,7 +621,18 @@ make no difference to the build. <para> - XXX + The &Import; call makes the <literal>env</literal> construction + environment available to the &SConscript; file, + after which the variable can be used to build + programs, libraries, etc. + + </para> + + <para> + + Like the &Export; function, + the &Import; function can be used + with multiple variable names: </para> @@ -626,7 +644,9 @@ make no difference to the build. <para> - Which is exactly equivalent to: + And the &Import; function will similarly + split a string along white-space + into separate variable names: </para> @@ -638,7 +658,24 @@ make no difference to the build. <para> - 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: + + </para> + + <sconstruct> + Import('*') + env = env.Copy(DEBUG = debug) + env.Program('prog', ['prog.c']) + </sconstruct> + + <para> + + 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. </para> @@ -649,35 +686,90 @@ make no difference to the build. <para> - 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. </para> - <sconstruct> - obj = env.Object('foo.c') - Return('obj') - </sconstruct> + <para> + + 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: + + </para> + + <scons_example name="Return"> + <file name="SConstruct" printme="1"> + env = Environment() + Export('env') + objs = [] + for subdir in ['foo', 'bar']: + o = SConscript('%s/SConscript' % subdir) + objs.append(o) + env.Library('prog', objs) + </file> + <directory name="foo"></directory> + <directory name="bar"></directory> + <file name="foo/SConscript"> + Import('env') + obj = env.Object('foo.c') + Return('obj') + </file> + <file name="bar/SConscript"> + Import('env') + obj = env.Object('bar.c') + Return('obj') + </file> + <file name="foo/foo.c"> + void foo(void) { printf("foo/foo.c\n"); } + </file> + <file name="bar/bar.c"> + void bar(void) { printf("bar/bar.c\n"); } + </file> + </scons_example> <para> - XXX + We can do this by using the &Return; + function in the + <literal>foo/SConscript</literal> file like this: </para> - <sconstruct> - objs = [] - for subdir in ['foo', 'bar']: - o = SConscript('%s/SConscript' % subdir) - objs.append(o) - env.Library('prog', objs) - </sconstruct> + <scons_example_file example="Return" name="foo/SConscript"> + </scons_example_file> <para> - XXX + (The corresponding + <literal>bar/SConscript</literal> + 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: </para> + <scons_output example="Return"> + <command>scons -Q</command> + </scons_output> + </section> </section> diff --git a/doc/user/hierarchy.sgml b/doc/user/hierarchy.sgml index 24adb561..5db49a86 100644 --- a/doc/user/hierarchy.sgml +++ b/doc/user/hierarchy.sgml @@ -290,10 +290,11 @@ make no difference to the build. </para> + <programlisting> env = Environment() env.Program('prog1', ['main.c', 'foo1.c', 'foo2.c']) - </programlisting> + </programlisting> <para> @@ -301,10 +302,11 @@ make no difference to the build. </para> + <programlisting> env = Environment() env.Program('prog2', ['main.c', 'bar1.c', 'bar2.c']) - </programlisting> + </programlisting> <para> @@ -314,14 +316,14 @@ make no difference to the build. </para> <literallayout> - % <userinput>scons</userinput> - 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 + % <userinput>scons -Q</userinput> + 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 </literallayout> @@ -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. </para> @@ -357,13 +362,12 @@ make no difference to the build. by appending a &hash; (hash mark) to the beginning of the path name: - </para> - <literallayout> + <programlisting> env = Environment() env.Program('prog', ['main.c', '#lib/foo1.c', 'foo2.c']) - </literallayout> + </programlisting> <para> @@ -377,11 +381,11 @@ make no difference to the build. </para> <literallayout> - % <userinput>scons</userinput> - 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 + % <userinput>scons -Q</userinput> + 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 </literallayout> <para> @@ -406,10 +410,10 @@ make no difference to the build. </para> - <literallayout> + <programlisting> env = Environment() env.Program('prog', ['main.c', '/usr/joe/lib/foo1.c', 'foo2.c']) - </literallayout> + </programlisting> <para> @@ -418,11 +422,11 @@ make no difference to the build. </para> <literallayout> - % <userinput>scons</userinput> - 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 + % <userinput>scons -Q</userinput> + 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 </literallayout> <para> @@ -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. <para> - XXX + You may export more than one variable name at a time: </para> @@ -505,7 +509,9 @@ make no difference to the build. <para> - 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: </para> @@ -516,7 +522,7 @@ make no difference to the build. <para> 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: </para> @@ -565,7 +571,10 @@ make no difference to the build. <para> - 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: </para> @@ -576,7 +585,18 @@ make no difference to the build. <para> - XXX + The &Import; call makes the <literal>env</literal> construction + environment available to the &SConscript; file, + after which the variable can be used to build + programs, libraries, etc. + + </para> + + <para> + + Like the &Export; function, + the &Import; function can be used + with multiple variable names: </para> @@ -588,7 +608,9 @@ make no difference to the build. <para> - Which is exactly equivalent to: + And the &Import; function will similarly + split a string along white-space + into separate variable names: </para> @@ -600,7 +622,24 @@ make no difference to the build. <para> - 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: + + </para> + + <programlisting> + Import('*') + env = env.Copy(DEBUG = debug) + env.Program('prog', ['prog.c']) + </programlisting> + + <para> + + 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. </para> @@ -611,35 +650,78 @@ make no difference to the build. <para> - 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. + + </para> + + <para> + + 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: </para> <programlisting> - 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) </programlisting> <para> - XXX + We can do this by using the &Return; + function in the + <literal>foo/SConscript</literal> file like this: </para> + <programlisting> - objs = [] - for subdir in ['foo', 'bar']: - o = SConscript('%s/SConscript' % subdir) - objs.append(o) - env.Library('prog', objs) - </programlisting> + Import('env') + obj = env.Object('foo.c') + Return('obj') + </programlisting> <para> - XXX + (The corresponding + <literal>bar/SConscript</literal> + 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: </para> + <literallayout> + % <userinput>scons -Q</userinput> + 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 + </literallayout> + </section> </section> diff --git a/doc/user/main.in b/doc/user/main.in index 12b0480b..e0ae71d4 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -100,11 +100,6 @@ &simple; </chapter> - <chapter id="chap-environments"> - <title>Construction Environments</title> - &environments; - </chapter> - <chapter id="chap-libraries"> <title>Building and Linking with Libraries</title> &libraries; @@ -115,6 +110,11 @@ &depends; </chapter> + <chapter id="chap-environments"> + <title>Construction Environments</title> + &environments; + </chapter> + <chapter id="chap-default"> <title>Default Targets</title> &default; @@ -150,11 +150,15 @@ &variants; </chapter> + <!-- + <chapter id="chap-builders-built-in"> <title>Built-In Builders</title> &builders-built-in; </chapter> + --> + <chapter id="chap-builders-writing"> <title>Writing Your Own Builders</title> &builders-writing; @@ -165,11 +169,15 @@ &builders-commands; </chapter> + <!-- + <chapter id="chap-actions"> <title>SCons Actions</title> &actions; </chapter> + --> + <chapter id="chap-scanners"> <title>Writing Scanners</title> &scanners; @@ -180,11 +188,15 @@ &repositories; </chapter> + <!-- + <chapter id="chap-sourcecode"> <title>Fetching Files From Source Code Management Systems</title> &sourcecode; </chapter> + --> + <chapter id="chap-caching"> <title>Caching Built Files</title> &caching; @@ -195,6 +207,8 @@ &alias; </chapter> + <!-- + <chapter id="chap-run"> <title>How to Run &SCons;</title> &run; @@ -205,6 +219,8 @@ &troubleshoot; </chapter> + --> + <!-- AddPostAction() AddPreAction() @@ -220,6 +236,8 @@ Tools() --> + <!-- + <appendix id="app-example"> <title>Complex &SCons; Example</title> &example; @@ -240,4 +258,6 @@ &ant; </appendix> + --> + </book> diff --git a/doc/user/main.sgml b/doc/user/main.sgml index 12b0480b..e0ae71d4 100644 --- a/doc/user/main.sgml +++ b/doc/user/main.sgml @@ -100,11 +100,6 @@ &simple; </chapter> - <chapter id="chap-environments"> - <title>Construction Environments</title> - &environments; - </chapter> - <chapter id="chap-libraries"> <title>Building and Linking with Libraries</title> &libraries; @@ -115,6 +110,11 @@ &depends; </chapter> + <chapter id="chap-environments"> + <title>Construction Environments</title> + &environments; + </chapter> + <chapter id="chap-default"> <title>Default Targets</title> &default; @@ -150,11 +150,15 @@ &variants; </chapter> + <!-- + <chapter id="chap-builders-built-in"> <title>Built-In Builders</title> &builders-built-in; </chapter> + --> + <chapter id="chap-builders-writing"> <title>Writing Your Own Builders</title> &builders-writing; @@ -165,11 +169,15 @@ &builders-commands; </chapter> + <!-- + <chapter id="chap-actions"> <title>SCons Actions</title> &actions; </chapter> + --> + <chapter id="chap-scanners"> <title>Writing Scanners</title> &scanners; @@ -180,11 +188,15 @@ &repositories; </chapter> + <!-- + <chapter id="chap-sourcecode"> <title>Fetching Files From Source Code Management Systems</title> &sourcecode; </chapter> + --> + <chapter id="chap-caching"> <title>Caching Built Files</title> &caching; @@ -195,6 +207,8 @@ &alias; </chapter> + <!-- + <chapter id="chap-run"> <title>How to Run &SCons;</title> &run; @@ -205,6 +219,8 @@ &troubleshoot; </chapter> + --> + <!-- AddPostAction() AddPreAction() @@ -220,6 +236,8 @@ Tools() --> + <!-- + <appendix id="app-example"> <title>Complex &SCons; Example</title> &example; @@ -240,4 +258,6 @@ &ant; </appendix> + --> + </book> diff --git a/doc/user/preface.in b/doc/user/preface.in index 589399d6..5e46f0a6 100644 --- a/doc/user/preface.in +++ b/doc/user/preface.in @@ -60,8 +60,8 @@ <emphasis>easier</emphasis> 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 @@ </para> + <!-- + <section> <title>Why &SCons;?</title> @@ -94,6 +96,8 @@ </section> + --> + <section> <title>&SCons; Principles</title> @@ -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. </para> </listitem> @@ -169,6 +174,8 @@ </section> + <!-- + <section> <title>History</title> @@ -197,6 +204,8 @@ </section> + --> + <!-- <section> @@ -265,7 +274,7 @@ and time people have contributed over the past few years. The "core team" of Chad Austin, Anthony Roach, Charles Crain, - Steve Leblanc, Greg Spencer and Christoph Wiedemann + Steve Leblanc, Gary Oerbrunner, Greg Spencer and Christoph Wiedemann have been great about reviewing my (and other) changes and catching problems before they get in the code base. Of particular technical note: @@ -282,7 +291,7 @@ <para> Special thanks to David Snopek for contributing - his underlying "Autocons" code that formed + his underlying "Autoscons" code that formed the basis of Christoph's work with the Configure functionality. David was extremely generous in making this code available to &SCons;, @@ -291,6 +300,8 @@ </para> + <!-- + <para> &SCons; has received contributions @@ -308,12 +319,14 @@ Jeff Petkau (significant fixes for CacheDir and other areas), Stefan Reichor (Ghostscript support), Zed Shaw (Append() and Replace() environment methods), - Terrel Shumway (build and test fixes, as well as the SCons Wiki), - sam th (dynamic checks for utilities) - and Moshe Zadke (Debian packaging). + Terrel Shumway (build and test fixes, as well as the SCons Wiki) + and + sam th (dynamic checks for utilities). </para> + --> + <para> Thanks to Peter Miller diff --git a/doc/user/preface.sgml b/doc/user/preface.sgml index 589399d6..390d6a87 100644 --- a/doc/user/preface.sgml +++ b/doc/user/preface.sgml @@ -60,8 +60,8 @@ <emphasis>easier</emphasis> 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 @@ </para> + <!-- + <section> <title>Why &SCons;?</title> @@ -94,13 +96,15 @@ </section> + --> + <section> <title>&SCons; Principles</title> <para> 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;: </para> @@ -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. </para> </listitem> @@ -169,6 +174,8 @@ </section> + <!-- + <section> <title>History</title> @@ -197,6 +204,8 @@ </section> + --> + <!-- <section> @@ -265,7 +274,7 @@ and time people have contributed over the past few years. The "core team" of Chad Austin, Anthony Roach, Charles Crain, - Steve Leblanc, Greg Spencer and Christoph Wiedemann + Steve Leblanc, Gary Oerbrunner, Greg Spencer and Christoph Wiedemann have been great about reviewing my (and other) changes and catching problems before they get in the code base. Of particular technical note: @@ -282,7 +291,7 @@ <para> Special thanks to David Snopek for contributing - his underlying "Autocons" code that formed + his underlying "Autoscons" code that formed the basis of Christoph's work with the Configure functionality. David was extremely generous in making this code available to &SCons;, @@ -291,6 +300,8 @@ </para> + <!-- + <para> &SCons; has received contributions @@ -308,12 +319,14 @@ Jeff Petkau (significant fixes for CacheDir and other areas), Stefan Reichor (Ghostscript support), Zed Shaw (Append() and Replace() environment methods), - Terrel Shumway (build and test fixes, as well as the SCons Wiki), - sam th (dynamic checks for utilities) - and Moshe Zadke (Debian packaging). + Terrel Shumway (build and test fixes, as well as the SCons Wiki) + and + sam th (dynamic checks for utilities). </para> + --> + <para> Thanks to Peter Miller @@ -365,7 +378,7 @@ <para> - If you want to receive announcements about &SCons, + If you want to receive announcements about &SCons;, join the low-volume &scons-announce; mailing list. </para> diff --git a/doc/user/repositories.in b/doc/user/repositories.in index c1556178..480ea3ff 100644 --- a/doc/user/repositories.in +++ b/doc/user/repositories.in @@ -219,7 +219,7 @@ subdirectories under the repository tree. and next under the <filename>/usr/repository2</filename> 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. </para> <scons_output example="ex1"> - <command>scons</command> + <command>scons -Q</command> </scons_output> <para> @@ -264,7 +264,7 @@ subdirectories under the repository tree. </scons_example> <scons_output example="ex2"> - <command>scons</command> + <command>scons -Q</command> gcc -c /usr/repository1/hello.c -o hello.o gcc -o hello hello.o </scons_output> @@ -289,7 +289,7 @@ subdirectories under the repository tree. </scons_example> <scons_output example="ex3"> - <command>scons</command> + <command>scons -Q</command> </scons_output> <para> @@ -316,7 +316,7 @@ subdirectories under the repository tree. </para> <literallayout> - % <userinput>scons -Y /usr/repository1 -Y /usr/repository2</userinput> + % <userinput>scons -Q -Y /usr/repository1 -Y /usr/repository2</userinput> </literallayout> <para> @@ -361,20 +361,24 @@ subdirectories under the repository tree. <scons_example name="ex4"> <file name="SConstruct"> env = Environment() - env.Program('hello.c') + env.Program(['hello.c', 'file1.c', 'file2.c']) Repository('/usr/repository1', '/usr/repository2') </file> <file name="hello.c"> int main() { printf("Hello, world!\n"); } </file> + <file name="file1.c"> + int f1() { printf("file1\n"); } + </file> + <file name="file2.c"> + int f2() { printf("file2.c\n"); } + </file> </scons_example> - <literallayout> - % <userinput>cd /usr/repository1</userinput> - % <userinput>scons</userinput> - gcc -c hello.c -o hello.o - gcc -o hello hello.o - </literallayout> + <scons_output example="ex4"> + <command>cd /usr/repository1</command> + <command>scons -Q</command> + </scons_output> <para> @@ -396,20 +400,26 @@ subdirectories under the repository tree. </para> + <!-- + <scons_output example="ex4"> + <command>cd $HOME/build</command> + <command>edit hello.c</command> + <command>scons -Q -Y __ROOT__/usr/repository1</command> + </scons_output> + --> <literallayout> % <userinput>cd $HOME/build</userinput> % <userinput>edit hello.c</userinput> - % <userinput>scons -Y /usr/repository1</userinput> - gcc -c hello.c -o hello.o - gcc -o hello hello.o - XXXXXXX + % <userinput>scons -Q -Y /usr/repository1</userinput> + cc -c -o hello.o hello.c + cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o </literallayout> <para> 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. </para> @@ -431,7 +441,7 @@ subdirectories under the repository tree. <literallayout> % <userinput>mkdir $HOME/build2</userinput> % <userinput>cd $HOME/build2</userinput> - % <userinput>scons -Y /usr/all/repository hello</userinput> + % <userinput>scons -Q -Y /usr/all/repository hello</userinput> scons: `hello' is up-to-date. </literallayout> @@ -460,7 +470,7 @@ subdirectories under the repository tree. </para> - <scons_example name="ex1"> + <scons_example name="ex5"> <file name="SConstruct" printme="1"> 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? </literallayout> <para> @@ -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? </para> diff --git a/doc/user/repositories.sgml b/doc/user/repositories.sgml index 07af1156..fdb8b5bf 100644 --- a/doc/user/repositories.sgml +++ b/doc/user/repositories.sgml @@ -214,7 +214,7 @@ subdirectories under the repository tree. and next under the <filename>/usr/repository2</filename> 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. </para> <literallayout> - % <userinput>scons</userinput> - gcc -c hello.c -o hello.o - gcc -o hello hello.o + % <userinput>scons -Q</userinput> + cc -c -o hello.o hello.c + cc -o hello hello.o </literallayout> <para> @@ -249,8 +249,12 @@ subdirectories under the repository tree. </para> + + <literallayout> - % <userinput>scons</userinput> + % <userinput>scons -Q</userinput> + 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 </literallayout> @@ -263,10 +267,12 @@ subdirectories under the repository tree. </para> + + <literallayout> - % <userinput>scons</userinput> - gcc -c /usr/repository2/hello.c -o hello.o - gcc -o hello hello.o + % <userinput>scons -Q</userinput> + cc -c -o hello.o hello.c + cc -o hello hello.o </literallayout> <para> @@ -293,7 +299,7 @@ subdirectories under the repository tree. </para> <literallayout> - % <userinput>scons -Y /usr/repository1 -Y /usr/repository2</userinput> + % <userinput>scons -Q -Y /usr/repository1 -Y /usr/repository2</userinput> </literallayout> <para> @@ -335,11 +341,15 @@ subdirectories under the repository tree. </para> + + <literallayout> % <userinput>cd /usr/repository1</userinput> - % <userinput>scons</userinput> - gcc -c hello.c -o hello.o - gcc -o hello hello.o + % <userinput>scons -Q</userinput> + 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 </literallayout> <para> @@ -362,20 +372,26 @@ subdirectories under the repository tree. </para> + <!-- + <scons_output example="ex4"> + <command>cd $HOME/build</command> + <command>edit hello.c</command> + <command>scons -Q -Y __ROOT__/usr/repository1</command> + </scons_output> + --> <literallayout> % <userinput>cd $HOME/build</userinput> % <userinput>edit hello.c</userinput> - % <userinput>scons -Y /usr/repository1</userinput> - gcc -c hello.c -o hello.o - gcc -o hello hello.o - XXXXXXX + % <userinput>scons -Q -Y /usr/repository1</userinput> + cc -c -o hello.o hello.c + cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o </literallayout> <para> 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. </para> @@ -397,7 +413,7 @@ subdirectories under the repository tree. <literallayout> % <userinput>mkdir $HOME/build2</userinput> % <userinput>cd $HOME/build2</userinput> - % <userinput>scons -Y /usr/all/repository hello</userinput> + % <userinput>scons -Q -Y /usr/all/repository hello</userinput> scons: `hello' is up-to-date. </literallayout> @@ -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? </literallayout> <para> @@ -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? </para> diff --git a/doc/user/scanners.in b/doc/user/scanners.in index 76b2a1af..fe409ad2 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: --> - <para> + <para> - 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 <filename>.h</filename> files that are specified + using <literal>#include</literal> 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." + + </para> - </para> + <section> + <title>A Simple Scanner Example</title> - <section> - <title>XXX</title> + <para> - <para> + Suppose, for example, that we want to create a simple scanner + for <filename>.foo</filename> files. + A <filename>.foo</filename> file contains some text that + will be processed, + and can include other files on lines that begin + with <literal>include</literal> + followed by a file name: - XXX + </para> - </para> + <programlisting> + include filename.foo + </programlisting> - </section> + <para> + + Scanning a file will be handled by a Python function + that you must supply. + Here is a function that will use the Python + <filename>re</filename> module + to scan for the <literal>include</literal> lines in our example: + + </para> + + <programlisting> + 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) + </programlisting> + + <para> + + 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. + + </para> + + <variablelist> + + <varlistentry> + <term>node</term> + + <listitem> + <para> + + 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 <literal>str()</literal> function, + or an internal &SCons; <literal>get_contents()</literal> + object method can be used to fetch the contents. + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>env</term> + + <listitem> + <para> + + The construction environment in effect for this scan. + The scanner function may choose to use construction + variables from this environment to affect its behavior. + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>path</term> + + <listitem> + <para> + + 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. + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>arg</term> + + <listitem> + <para> + + An optional argument that you can choose to + have passed to this scanner function by + various scanner instances. + + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + + A Scanner object is created using the &Scanner; function, + which typically takes an <literal>skeys</literal> 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: + + </para> + + <programlisting> + kscan = Scanner(function = kfile_scan, + skeys = ['.k']) + env.Append(SCANNERS = kscan) + </programlisting> + + <para> + + When we put it all together, it looks like: + + </para> + + <scons_example name="scan"> + <file name="SConstruct" printme="1"> + 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') + </file> + <file name="foo.k"> + include other_file + </file> + <file name="other_file"> + other_file + </file> + <directory name="__ROOT__/usr"></directory> + <directory name="__ROOT__/usr/local"></directory> + <directory name="__ROOT__/usr/local/bin"></directory> + <file name="__ROOT_/usr/local/bin/kprocess" chmod="755"> + cat + </file> + </scons_example> + + <!-- + + <para> + + Now if we run &scons; + and then re-run it after changing the contents of + <filename>other_file</filename>, + the <filename>foo</filename> + target file will be automatically rebuilt: + + </para> + + <scons_output example="scan"> + <command>scons -Q</command> + <command output=" [CHANGE THE CONTENTS OF other_file]">edit other_file</command> + <command>scons -Q</command> + <command>scons -Q</command> + </scons_output> + + --> + + </section> diff --git a/doc/user/scanners.sgml b/doc/user/scanners.sgml index 76b2a1af..23cd0447 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: --> - <para> + <para> - 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 <filename>.h</filename> files that are specified + using <literal>#include</literal> 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." + + </para> - </para> + <section> + <title>A Simple Scanner Example</title> - <section> - <title>XXX</title> + <para> - <para> + Suppose, for example, that we want to create a simple scanner + for <filename>.foo</filename> files. + A <filename>.foo</filename> file contains some text that + will be processed, + and can include other files on lines that begin + with <literal>include</literal> + followed by a file name: - XXX + </para> - </para> + <programlisting> + include filename.foo + </programlisting> - </section> + <para> + + Scanning a file will be handled by a Python function + that you must supply. + Here is a function that will use the Python + <filename>re</filename> module + to scan for the <literal>include</literal> lines in our example: + + </para> + + <programlisting> + 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) + </programlisting> + + <para> + + 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. + + </para> + + <variablelist> + + <varlistentry> + <term>node</term> + + <listitem> + <para> + + 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 <literal>str()</literal> function, + or an internal &SCons; <literal>get_contents()</literal> + object method can be used to fetch the contents. + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>env</term> + + <listitem> + <para> + + The construction environment in effect for this scan. + The scanner function may choose to use construction + variables from this environment to affect its behavior. + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>path</term> + + <listitem> + <para> + + 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. + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>arg</term> + + <listitem> + <para> + + An optional argument that you can choose to + have passed to this scanner function by + various scanner instances. + + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + + A Scanner object is created using the &Scanner; function, + which typically takes an <literal>skeys</literal> 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: + + </para> + + <programlisting> + kscan = Scanner(function = kfile_scan, + skeys = ['.k']) + env.Append(SCANNERS = kscan) + </programlisting> + + <para> + + When we put it all together, it looks like: + + </para> + + <programlisting> + 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') + </programlisting> + + <!-- + + <para> + + Now if we run &scons; + and then re-run it after changing the contents of + <filename>other_file</filename>, + the <filename>foo</filename> + target file will be automatically rebuilt: + + </para> + + <scons_output example="scan"> + <command>scons -Q</command> + <command output=" [CHANGE THE CONTENTS OF other_file]">edit other_file</command> + <command>scons -Q</command> + <command>scons -Q</command> + </scons_output> + + --> + + </section> diff --git a/doc/user/separate.in b/doc/user/separate.in index c1b3c32e..1b24edfb 100644 --- a/doc/user/separate.in +++ b/doc/user/separate.in @@ -132,38 +132,37 @@ program using the F<build/foo.c> 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: </para> - <sconstruct> - SConscript('src/SConscript', build_dir='build') - </sconstruct> - - <para> - - &SCons; will then build all of the files in - the &build; subdirectory: - - </para> - <scons_example name="ex1"> <file name="SConstruct" printme="1"> + SConscript('src/SConscript', build_dir='build') + </file> + <file name="src/SConscript"> env = Environment() env.Program('hello.c') </file> - <file name="hello.c"> + <file name="src/hello.c"> int main() { printf("Hello, world!\n"); } </file> </scons_example> + <para> + + &SCons; will then build all of the files in + the &build; subdirectory: + + </para> + <scons_output example="ex1"> - <command>ls -1 src</command> - <command>scons</command> - <command>ls -1 build</command> + <command>ls src</command> + <command>scons -Q</command> + <command>ls build</command> </scons_output> <para> @@ -199,48 +198,88 @@ program using the F<build/foo.c> path name. &SCons; duplicates source files in build directories because it's the most straightforward way to guarantee a correct build - <emphasis>regardless of include-file directory paths</emphasis>, + <emphasis>regardless of include-file directory paths, + relative references between files, + or tool support for putting files in different locations</emphasis>, 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: </para> <para> - 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. + + </para> + + <para> + + 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 <literal>#include</literal> + mechanism with double quotes, not angle brackets: </para> <sconstruct> - env = Environmnet() + #include "file.h" </sconstruct> <para> - XXX + The <emphasis>de facto</emphasis> standard behavior + for most C compilers in this case + is to first look in the same directory + as the source file that contains the <literal>#include</literal> 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. </para> - <literallayout> - % <userinput>scons</userinput> - cc -c build/hello.c -o build/hello.o - cc -o build/hello build/hello.o - </literallayout> + <para> - </section> + Although source-file duplication guarantees a correct build + even in these end-cases, + it <emphasis>can</emphasis> usually be safely disabled. + The next section describes + how you can disable the duplication of source files + in the build directory. + + </para> + + </section> <section> <title>Telling &SCons; to Not Duplicate Source Files in the Build Directory</title> <para> - 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 <emphasis>without</emphasis> - 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 <literal>duplicate=0</literal> when you call the &SConscript; function: @@ -262,13 +301,13 @@ program using the F<build/foo.c> path name. </para> <literallayout> - % <userinput>ls -1 src</userinput> + % <userinput>ls src</userinput> SConscript hello.c - % <userinput>scons</userinput> + % <userinput>scons -Q</userinput> cc -c src/hello.c -o build/hello.o cc -o build/hello build/hello.o - % <userinput>ls -1 build</userinput> + % <userinput>ls build</userinput> hello hello.o </literallayout> @@ -311,12 +350,6 @@ program using the F<build/foo.c> path name. <para> - XXX - - </para> - - <para> - 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<build/foo.c> path name. <scons_output example="ex_builddir"> <command>ls src</command> - <command>scons</command> - <command>ls -1 build</command> + <command>scons -Q</command> + <command>ls build</command> </scons_output> <para> @@ -356,8 +389,8 @@ program using the F<build/foo.c> path name. <scons_output example="ex_duplicate_0"> <command>ls src</command> - <command>scons</command> - <command>ls -1 build</command> + <command>scons -Q</command> + <command>ls build</command> </scons_output> </section> @@ -377,22 +410,26 @@ program using the F<build/foo.c> path name. </para> <scons_example name="example_builddir_sconscript"> - <file name="SConstruct" printme="1"> + <file name="SConstruct"> + BuildDir('build', 'src') + SConscript('build/SConscript') + </file> + <file name="src/SConscript" printme="1"> env = Environment() env.Program('hello.c') </file> - <file name="SConscript"> - BuildDir('build', 'src') - SConscript('build/SConscript') + <file name="src/hello.c"> + int main() { printf("Hello, world!\n"); } + </file> </scons_example> <para> - Then our &SConscript; file could look like: + Then our &SConstruct; file could look like: </para> - <scons_example_file example="example_builddir_sconscript" name="SConscript"> + <scons_example_file example="example_builddir_sconscript" name="SConstruct"> </scons_example_file> <para> @@ -402,9 +439,9 @@ program using the F<build/foo.c> path name. </para> <scons_output example="example_builddir_sconscript"> - <command>ls -1 src</command> - <command>scons</command> - <command>ls -1 build</command> + <command>ls src</command> + <command>scons -Q</command> + <command>ls build</command> </scons_output> <para> @@ -417,6 +454,8 @@ program using the F<build/foo.c> path name. </section> + <!-- + <section> <title>Why You'd Want to Call &BuildDir; Instead of &SConscript;</title> @@ -427,3 +466,5 @@ program using the F<build/foo.c> path name. </para> </section> + + --> diff --git a/doc/user/separate.sgml b/doc/user/separate.sgml index ac3c0f33..b00be1a3 100644 --- a/doc/user/separate.sgml +++ b/doc/user/separate.sgml @@ -132,7 +132,7 @@ program using the F<build/foo.c> 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<build/foo.c> path name. </para> <literallayout> - % <userinput>ls -1 src</userinput> - SConscript - hello.c - % <userinput>scons</userinput> - cc -c build/hello.c -o build/hello.o + % <userinput>ls src</userinput> + SConscript hello.c + % <userinput>scons -Q</userinput> + cc -c -o build/hello.o build/hello.c cc -o build/hello build/hello.o - % <userinput>ls -1 build</userinput> - hello - hello.c - hello.o + % <userinput>ls build</userinput> + SConscript hello hello.c hello.o </literallayout> <para> @@ -196,48 +193,88 @@ program using the F<build/foo.c> path name. &SCons; duplicates source files in build directories because it's the most straightforward way to guarantee a correct build - <emphasis>regardless of include-file directory paths</emphasis>, + <emphasis>regardless of include-file directory paths, + relative references between files, + or tool support for putting files in different locations</emphasis>, 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: </para> <para> - 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. + + </para> + + <para> + + 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 <literal>#include</literal> + mechanism with double quotes, not angle brackets: </para> <programlisting> - env = Environmnet() + #include "file.h" </programlisting> <para> - XXX + The <emphasis>de facto</emphasis> standard behavior + for most C compilers in this case + is to first look in the same directory + as the source file that contains the <literal>#include</literal> 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. </para> - <literallayout> - % <userinput>scons</userinput> - cc -c build/hello.c -o build/hello.o - cc -o build/hello build/hello.o - </literallayout> + <para> - </section> + Although source-file duplication guarantees a correct build + even in these end-cases, + it <emphasis>can</emphasis> usually be safely disabled. + The next section describes + how you can disable the duplication of source files + in the build directory. + + </para> + + </section> <section> <title>Telling &SCons; to Not Duplicate Source Files in the Build Directory</title> <para> - 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 <emphasis>without</emphasis> - 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 <literal>duplicate=0</literal> when you call the &SConscript; function: @@ -259,13 +296,13 @@ program using the F<build/foo.c> path name. </para> <literallayout> - % <userinput>ls -1 src</userinput> + % <userinput>ls src</userinput> SConscript hello.c - % <userinput>scons</userinput> + % <userinput>scons -Q</userinput> cc -c src/hello.c -o build/hello.o cc -o build/hello build/hello.o - % <userinput>ls -1 build</userinput> + % <userinput>ls build</userinput> hello hello.o </literallayout> @@ -303,12 +340,6 @@ program using the F<build/foo.c> path name. <para> - XXX - - </para> - - <para> - 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<build/foo.c> path name. <literallayout> % <userinput>ls src</userinput> hello.c - % <userinput>scons</userinput> - cc -c build/hello.c -o build/hello.o + % <userinput>scons -Q</userinput> + cc -c -o build/hello.o build/hello.c cc -o build/hello build/hello.o - % <userinput>ls -1 build</userinput> - hello - hello.c - hello.o + % <userinput>ls build</userinput> + hello hello.c hello.o </literallayout> <para> @@ -350,12 +379,11 @@ program using the F<build/foo.c> path name. <literallayout> % <userinput>ls src</userinput> hello.c - % <userinput>scons</userinput> - cc -c src/hello.c -o build/hello.o + % <userinput>scons -Q</userinput> + cc -c -o build/hello.o src/hello.c cc -o build/hello build/hello.o - % <userinput>ls -1 build</userinput> - hello - hello.o + % <userinput>ls build</userinput> + hello hello.o </literallayout> </section> @@ -381,14 +409,15 @@ program using the F<build/foo.c> path name. <para> - Then our &SConscript; file could look like: + Then our &SConstruct; file could look like: </para> + <programlisting> BuildDir('build', 'src') SConscript('build/SConscript') - </programlisting> + </programlisting> <para> @@ -397,16 +426,13 @@ program using the F<build/foo.c> path name. </para> <literallayout> - % <userinput>ls -1 src</userinput> - SConscript - hello.c - % <userinput>scons</userinput> - cc -c build/hello.c -o build/hello.o + % <userinput>ls src</userinput> + SConscript hello.c + % <userinput>scons -Q</userinput> + cc -c -o build/hello.o build/hello.c cc -o build/hello build/hello.o - % <userinput>ls -1 build</userinput> - hello - hello.c - hello.o + % <userinput>ls build</userinput> + SConscript hello hello.c hello.o </literallayout> <para> @@ -419,6 +445,8 @@ program using the F<build/foo.c> path name. </section> + <!-- + <section> <title>Why You'd Want to Call &BuildDir; Instead of &SConscript;</title> @@ -429,3 +457,5 @@ program using the F<build/foo.c> path name. </para> </section> + + --> diff --git a/doc/user/sourcecode.in b/doc/user/sourcecode.in index b794c09f..30b6ecb8 100644 --- a/doc/user/sourcecode.in +++ b/doc/user/sourcecode.in @@ -29,7 +29,7 @@ <para> - X + XXX </para> @@ -38,20 +38,23 @@ <para> - X + XXX </para> <scons_example name="ex_bitkeeper"> <file name="SConstruct" printme="1"> env = Environment() - env.SourceCode('.', env.BitKeeper('XXX')) + env.SourceCode('.', env.BitKeeper()) env.Program('hello.c') </file> + <file name="s.hello.c"> + s.hello.c + </file> </scons_example> <scons_output example="ex_bitkeeper"> - <userinput>scons</userinput> + <command>scons -Q</command> </scons_output> </section> @@ -61,20 +64,20 @@ <para> - X + XXX </para> <scons_example name="ex_cvs"> <file name="SConstruct" printme="1"> env = Environment() - env.SourceCode('.', env.CVS('XXX')) + env.SourceCode('.', env.CVS('/usr/local/CVS')) env.Program('hello.c') </file> </scons_example> <scons_output example="ex_cvs"> - <userinput>scons</userinput> + <command>scons -Q</command> </scons_output> </section> @@ -84,7 +87,7 @@ <para> - X + XXX </para> @@ -94,10 +97,13 @@ env.SourceCode('.', env.RCS()) env.Program('hello.c') </file> + <file name="hello.c,v"> + hello.c,v + </file> </scons_example> <scons_output example="ex_rcs"> - <userinput>scons</userinput> + <command>scons -Q</command> </scons_output> </section> @@ -107,7 +113,7 @@ <para> - X + XXX </para> @@ -117,10 +123,13 @@ env.SourceCode('.', env.SCCS()) env.Program('hello.c') </file> + <file name="s.hello.c"> + s.hello.c + </file> </scons_example> <scons_output example="ex_sccs"> - <userinput>scons</userinput> + <command>scons -Q</command> </scons_output> </section> @@ -132,7 +141,7 @@ <para> - X + XXX </para> @@ -145,7 +154,7 @@ </scons_example> <scons_output example="ex_subversion"> - <userinput>scons</userinput> + <command>scons -Q</command> </scons_output> </section> diff --git a/doc/user/sourcecode.sgml b/doc/user/sourcecode.sgml index 6bbcceed..74b73470 100644 --- a/doc/user/sourcecode.sgml +++ b/doc/user/sourcecode.sgml @@ -29,7 +29,7 @@ <para> - X + XXX </para> @@ -38,19 +38,22 @@ <para> - X + XXX </para> <programlisting> env = Environment() - env.SourceCode('.', env.BitKeeper('XXX')) + env.SourceCode('.', env.BitKeeper()) env.Program('hello.c') </programlisting> <literallayout> - % <userinput>scons</userinput> - XXX + % <userinput>scons -Q</userinput> + bk get - + bk get hello.c + cc -c -o hello.o hello.c + cc -o hello hello.o </literallayout> </section> @@ -60,19 +63,22 @@ <para> - X + XXX </para> <programlisting> env = Environment() - env.SourceCode('.', env.CVS('XXX')) + env.SourceCode('.', env.CVS('/usr/local/CVS')) env.Program('hello.c') </programlisting> <literallayout> - % <userinput>scons</userinput> - XXX + % <userinput>scons -Q</userinput> + 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 </literallayout> </section> @@ -82,7 +88,7 @@ <para> - X + XXX </para> @@ -93,8 +99,11 @@ </programlisting> <literallayout> - % <userinput>scons</userinput> - XXX + % <userinput>scons -Q</userinput> + co - + co hello.c + cc -c -o hello.o hello.c + cc -o hello hello.o </literallayout> </section> @@ -104,7 +113,7 @@ <para> - X + XXX </para> @@ -115,30 +124,38 @@ </programlisting> <literallayout> - % <userinput>scons</userinput> - XXX + % <userinput>scons -Q</userinput> + sccs get - + sccs get hello.c + cc -c -o hello.o hello.c + cc -o hello hello.o </literallayout> </section> + <!-- + <section> <title>Fetching Source Code From Subversion</title> <para> - X + XXX </para> - <programlisting> + <scons_example name="ex_subversion"> + <file name="SConstruct" printme="1"> env = Environment() env.SourceCode('.', env.Subversion('XXX')) env.Program('hello.c') - </programlisting> + </file> + </scons_example> - <literallayout> - % <userinput>scons</userinput> - XXX - </literallayout> + <scons_output example="ex_subversion"> + <command>scons -Q</command> + </scons_output> </section> + + --> diff --git a/doc/user/variants.in b/doc/user/variants.in index 1fb461af..ceab8f6e 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<cons>. Here's -one way we could set up the F<Construct> file for our B<Hello, World!> -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<Hello, World!> -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. <scons_example name="ex_variants"> <file name="SConstruct" printme="1"> - 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") </file> + <directory name="src"></directory> + <directory name="src/hello"></directory> + <directory name="src/world"></directory> + <file name="src/SConscript"> + Import('env') + SConscript('hello/SConscript') + SConscript('world/SConscript') + </file> + <file name="src/hello/SConscript"> + Import('env') + hello = env.Program('hello.c') + env.Install('$BINDIR', hello) + </file> + <file name="src/hello/hello.c"> + #include "world.h" + int main(int argc, char *argv[]) { printf "hello.c\n"; world(); } + </file> + <file name="src/world/SConscript"> + Import('env') + world = env.Library('world.c') + env.Install('$LIBDIR', world) + env.Install('$INCDIR', 'world.h') + </file> + <file name="src/world/world.h"> + #define STRING "world.h" + extern int world(); + </file> + <file name="src/world/world.c"> + int world() { printf "world.c\n"; } + </file> </scons_example> <para> @@ -152,7 +125,7 @@ is pretty smart about rebuilding things when you change options. </para> <scons_output example="ex_variants" os="posix"> - <command>scons OS=linux</command> + <command>scons -Q OS=linux</command> </scons_output> <para> @@ -162,18 +135,21 @@ is pretty smart about rebuilding things when you change options. </para> <scons_output example="ex_variants" os="win32"> - <command>scons OS=windows</command> + <command>scons -Q OS=windows</command> </scons_output> + <!-- + <scons_example name="ex_var2"> - <programlisting> <file name="SConstruct" printme="1"> - env = Environment(OS = ) + env = Environment(OS = ARGUMENTS.get('OS')) for os in ['newell', 'post']: SConscript('src/SConscript', build_dir='build/' + os) </file> </scons_example> <scons_output example="ex_var2"> - % <userinput>scons</userinput> + <command>scons -Q</command> </scons_output> + + --> diff --git a/doc/user/variants.sgml b/doc/user/variants.sgml index 09dd16d1..4ddb40b7 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<cons>. Here's -one way we could set up the F<Construct> file for our B<Hello, World!> -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<Hello, World!> -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. </para> <programlisting> - 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. </para> <literallayout> - $ <userinput>scons OS=linux</userinput> - 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 + % <userinput>scons -Q OS=linux</userinput> + 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" </literallayout> <para> @@ -168,28 +110,29 @@ is pretty smart about rebuilding things when you change options. </para> - <!-- - cl /Fohello.obj hello.c - link /Fohello.exe hello.obj - --> <literallayout> - C:\test\><userinput>scons OS=linux</userinput> - 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:\><userinput>scons -Q OS=windows</userinput> + 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" </literallayout> - <programlisting> - env = Environment(OS = ) + <!-- + + <scons_example name="ex_var2"> + <file name="SConstruct" printme="1"> + env = Environment(OS = ARGUMENTS.get('OS')) for os in ['newell', 'post']: SConscript('src/SConscript', build_dir='build/' + os) - </programlisting> + </file> + </scons_example> - <literallayout> - % <userinput>scons</userinput> - </literallayout> + <scons_output example="ex_var2"> + <command>scons -Q</command> + </scons_output> + + --> diff --git a/rpm/scons.spec.in b/rpm/scons.spec.in index 53a245c1..2160041a 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 d7a4aecb..61dad1e6 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 0e2672d2..bccfb32c 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 f8839409..6e43f50e 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 950dbdbf..1397561d 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 |