<!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>">
<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:
%
</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>
</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
</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>
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;.
<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>
<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>
<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>
<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>
</chapter>
<chapter id="chap-command">
- <title>Avoiding Having to Write Builders</title>
+ <title>Not Writing a Builder (for One-Time Builds)</title>
&command;
</chapter>
<para>
- X
+ Use the &BuildDir; function to establish that target
+ files should be built in a separate directory
+ from the source files:
</para>
<para>
- X
+ Note that XXX
</para>
<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>
projects / scons.git / commitdiff