diff options
| -rw-r--r-- | doc/scons.mod | 2 | ||||
| -rw-r--r-- | doc/user/depends.sgml | 71 | ||||
| -rw-r--r-- | doc/user/environments.sgml | 83 | ||||
| -rw-r--r-- | doc/user/main.sgml | 2 | ||||
| -rw-r--r-- | doc/user/separate.sgml | 6 | ||||
| -rw-r--r-- | doc/user/simple.sgml | 2 |
6 files changed, 131 insertions, 35 deletions
diff --git a/doc/scons.mod b/doc/scons.mod index 1c2653e..32283c3 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -101,6 +101,8 @@ <!ENTITY Module "<function>Module</function>"> <!ENTITY Objects "<function>Objects</function>"> <!ENTITY Precious "<function>Precious</function>"> +<!ENTITY Prepend "<function>Prepend</function>"> +<!ENTITY Replace "<function>Replace</function>"> <!ENTITY Repository "<function>Repository</function>"> <!ENTITY RuleSet "<function>RuleSet</function>"> <!ENTITY Salt "<function>Salt</function>"> diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml index 8669c72..bc46618 100644 --- a/doc/user/depends.sgml +++ b/doc/user/depends.sgml @@ -124,10 +124,10 @@ operating system on which the build is performed (as reported by C<uname <para> - This saves time by avoiding unnecessary rebuilds when, + This avoids unnecessary rebuilds when, for example, someone rewrites the contents of a file without making a change. - But if the contents of the file change, + But if the contents of the file really change, then &SCons; detects the change and rebuilds the program as required: @@ -145,29 +145,8 @@ operating system on which the build is performed (as reported by C<uname % </literallayout> - <para> - - X - - </para> - </section> - <!-- - - Now it turns out that F<hello.c> also includes the interface definition - file, F<world.h>: - - How does Cons know that F<hello.c> includes F<world.h>, and that F<hello.o> - must therefore be recompiled? For now, suffice it to say that when - considering whether or not F<hello.o> is up-to-date, Cons invokes a scanner - for its dependency, F<hello.c>. This scanner enumerates the files included - by F<hello.c> to come up with a list of further dependencies, beyond those - made explicit by the Cons script. This process is recursive: any files - included by included files will also be scanned. - - --> - <section> <title>Implicit Dependencies</title> @@ -257,9 +236,24 @@ operating system on which the build is performed (as reported by C<uname </para> + </section> + + <section> + <title>Caching Implicit Dependencies</title> + <para> - X + Scanning each file for <literal>#include</literal> lines + does take some extra processing time. + When you're doing a full build of a large system, + the scanning time is a small percentage + of the overall time spent on the build. + You're most likely to notice the scanning time, + however, when you rebuild all or part of a large system: + &SCons; will take some extra time to "think about" + what must be built before it issues the + first build command, + or decides that nothing must be rebuilt. <!-- Isn't this expensive? The answer is, it depends. If you do a full build of a @@ -272,6 +266,35 @@ operating system on which the build is performed (as reported by C<uname </para> + <para> + + In practice, having &SCons; scan files saves time + relative to the amount of potential time + lost to tracking down subtle problems + introduced by incorrect dependencies. + Nevertheless, the "waiting time" + while &SCons; scans files can annoy + individual developers waiting for their builds. + Consequently, &SCons; lets you cache + the implicit dependencies + + </para> + + <literallayout> + % <userinput>scons --implicit-cache hello</userinput> + cc -c hello.c -o hello.o + cc -o hello hello.o + % <userinput>scons hello</userinput> + scons: `hello' is up to date. + </literallayout> + + <para> + + &SCons; does not cache implicit dependencies like this by default + because XXX + + </para> + </section> <section> diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml index 8117cf0..77d9c6b 100644 --- a/doc/user/environments.sgml +++ b/doc/user/environments.sgml @@ -592,6 +592,11 @@ environment undisturbed. variables when you create each &consenv;, you can use the &Copy; method to create a copy of a &consenv;. + + </para> + + <para> + Like the &Environment; call that creates a &consenv;, the &Copy; method takes &consvar; assignments, which will override the values in the copied &consenv;. @@ -643,16 +648,47 @@ environment undisturbed. <para> - X + You can fetch individual construction variables + using the normal Python syntax + for accessing individual named items in a dictionary: + + </para> + + <programlisting> + env = Environment() + print "CCCOM is:", env['CCCOM'] + </programlisting> + + <literallayout> + % <userinput>scons</userinput> + CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES + </literallayout> + + <para> + + Note, however, that a &consenv; + is actually a Python object with + associated methods, etc. + If you want to have direct access to only the + dictionary of construction variables, + you can fetch this using the &Dictionary; method. + This provides the </para> <programlisting> env = Environment() + dict = env.Dictionary() + # XXX SOMETHING WHERE A DICT IS NEEDED </programlisting> + <para> + + </para> + <literallayout> % <userinput>scons</userinput> + # XXX </literallayout> </section> @@ -660,21 +696,42 @@ environment undisturbed. <section> <title>Modifying a &ConsEnv;</title> + <para> + + &SCons; provides various methods that + support modifying existing values in a &consenv;. + + </para> + <section> <title>Replacing Values in a &ConsEnv;</title> <para> - X + You can replace existing construction variable values + using the &Replace; method: </para> <programlisting> - env = Environment() + env = Environment(CCFLAGS = '-DDEFINE1) + env.Program('foo.c') + env.Replace(CCFLAGS = '-DDEFINE2') + env.Program('bar.c') </programlisting> + <para> + + The replaced value completely overwrites + + </para> + <literallayout> % <userinput>scons</userinput> + gcc -DDEFINE2 -c bar.c -o bar.o + gcc -o bar bar.o + gcc -DDEFINE2 -c foo.c -o foo.o + gcc -o foo foo.o </literallayout> </section> @@ -684,16 +741,22 @@ environment undisturbed. <para> - X + You can append a value to + an existing construction variable + using the &Append; method: </para> <programlisting> - env = Environment() + env = Environment(CCFLAGS = '-DMY_VALUE') + env.Append(CCFLAGS = ' -DLAST') + env.Program('foo.c') </programlisting> <literallayout> % <userinput>scons</userinput> + gcc -DMY_VALUE -DLAST -c foo.c -o foo.o + gcc -o foo foo.o </literallayout> </section> @@ -703,16 +766,22 @@ environment undisturbed. <para> - X + You can append a value to the beginning + an existing construction variable + using the &Prepend; method: </para> <programlisting> - env = Environment() + env = Environment(CCFLAGS = '-DMY_VALUE') + env.Prepend(CCFLAGS = '-DFIRST ') + env.Program('foo.c') </programlisting> <literallayout> % <userinput>scons</userinput> + gcc -DFIRST -DMY_VALUE -c foo.c -o foo.o + gcc -o foo foo.o </literallayout> </section> diff --git a/doc/user/main.sgml b/doc/user/main.sgml index 68bc59c..9ea4dd5 100644 --- a/doc/user/main.sgml +++ b/doc/user/main.sgml @@ -148,7 +148,7 @@ </chapter> <chapter id="chap-command"> - <title>Avoiding Having to Write Builders</title> + <title>Not Writing a Builder (for One-Time Builds)</title> &command; </chapter> diff --git a/doc/user/separate.sgml b/doc/user/separate.sgml index 9050eb7..21fcabc 100644 --- a/doc/user/separate.sgml +++ b/doc/user/separate.sgml @@ -129,7 +129,9 @@ program using the F<build/foo.c> path name. <para> - X + Use the &BuildDir; function to establish that target + files should be built in a separate directory + from the source files: </para> @@ -141,7 +143,7 @@ program using the F<build/foo.c> path name. <para> - X + Note that XXX </para> diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml index a86fd34..2acd669 100644 --- a/doc/user/simple.sgml +++ b/doc/user/simple.sgml @@ -105,7 +105,7 @@ requirements of a build. <para> - Second, notice that the same input &SConstruct; file + Second, notice that the same input &SConstruct; file, without any changes, generates the correct output file names on both systems: <filename>hello.o</filename> and <filename>hello</filename> |