summaryrefslogtreecommitdiffstats
path: root/doc/user
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/default.sgml148
-rw-r--r--doc/user/depends.sgml76
-rw-r--r--doc/user/help.sgml11
-rw-r--r--doc/user/main.sgml4
-rw-r--r--doc/user/repositories.sgml24
-rw-r--r--doc/user/simple.sgml242
6 files changed, 418 insertions, 87 deletions
diff --git a/doc/user/default.sgml b/doc/user/default.sgml
index bb81a3a..eb2bdc1 100644
--- a/doc/user/default.sgml
+++ b/doc/user/default.sgml
@@ -60,19 +60,153 @@ default list.
-->
- <para>
+ <para>
+
+ As mentioned previously,
+ &SCons; will build every target
+ in or below the current directory
+ by default--that is, when you don't
+ explicitly specify one or more targets
+ on the command line.
+ Sometimes, however, you may want
+ to explicitly specify that only
+ certain programs should be built by default,
+ which you do using the &Default; function:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ hello = env.Program('hello.c')
+ env.Program('goodbye.c')
+ Default(hello)
+ </programlisting>
+
+ <para>
+
+ This &SConstruct; file builds two programs,
+ &hello; and &goodbye;,
+ but only builds the
+ &hello program by default:
+
+ </para>
+
+ <literallayout>
+ % <userinput>scons</userinput>
+ cc -c hello.c -o hello.o
+ cc -o hello hello.o
+ % <userinput>scons</userinput>
+ % <userinput>scons goodbye</userinput>
+ cc -c goodbye.c -o goodbye.o
+ cc -o goodbye goodbye.o
+ %
+ </literallayout>
+
+ <para>
+
+ Note that, even when you use the &Default;
+ function in your &SConstruct; file,
+ you can still explicitly specify the current directory
+ (<literal>.</literal>) on the command line
+ to tell &SCons; to build
+ everything in (or below) the current directory:
+
+ </para>
+
+ <literallayout>
+ % <userinput>scons .</userinput>
+ cc -c goodbye.c -o goodbye.o
+ cc -o goodbye goodbye.o
+ cc -c hello.c -o hello.o
+ cc -o hello hello.o
+ %
+ </literallayout>
+
+ <para>
- X
+ You can also call the &Default;
+ function more than once,
+ in which case each call
+ adds to the list of targets to be built by default:
- </para>
+ </para>
+
+ <programlisting>
+ env = Environment()
+ prog1 = env.Program('prog1.c')
+ Default(prog1)
+ prog2 = env.Program('prog2.c')
+ prog3 = env.Program('prog3.c')
+ Default(prog3)
+ </programlisting>
+
+ <para>
+
+ Or you can specify more than one target
+ in a single call to the &Default; function:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ prog1 = env.Program('prog1.c')
+ prog2 = env.Program('prog2.c')
+ prog3 = env.Program('prog3.c')
+ Default(prog1, prog3)
+ </programlisting>
+
+ <para>
+
+ Either of these last two examples
+ will build only the
+ <application>prog1</application>
+ and
+ <application>prog3</application>
+ programs:
+
+ </para>
+
+ <literallayout>
+ % <userinput>scons</userinput>
+ cc -c prog1.c -o prog1.o
+ cc -o prog1 prog1.o
+ cc -c prog3.c -o prog3.o
+ cc -o prog3 prog3.o
+ % <userinput>scons .</userinput>
+ cc -c prog2.c -o prog2.o
+ cc -o prog2 prog2.o
+ %
+ </literallayout>
+
+ <para>
+
+ Lastly, if for some reason you don't want
+ any targets built by default,
+ you can use the Python <literal>None</literal>
+ variable:
+
+ </para>
- <section>
- <title>The &Default; Method</title>
+ <programlisting>
+ env = Environment()
+ prog1 = env.Program('prog1.c')
+ prog2 = env.Program('prog2.c')
+ Default(None)
+ </programlisting>
<para>
- X
+ Which would produce build output like:
</para>
- </section>
+ <literallayout>
+ % <userinput>scons</userinput>
+ scons: *** No targets specified and no Default() targets found. Stop.
+ % <userinput>scons .</userinput>
+ cc -c prog1.c -o prog1.o
+ cc -o prog1 prog1.o
+ cc -c prog2.c -o prog2.o
+ cc -o prog2 prog2.o
+ %
+ </literallayout>
diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml
index c94ac0d..e8491e4 100644
--- a/doc/user/depends.sgml
+++ b/doc/user/depends.sgml
@@ -61,10 +61,10 @@ operating system on which the build is performed (as reported by C<uname
</para>
<literallayout>
- % <userinput>scons .</userinput>
+ % <userinput>scons</userinput>
cc -c hello.c -o hello.o
cc -o hello hello.o
- % <userinput>scons .</userinput>
+ % <userinput>scons</userinput>
%
</literallayout>
@@ -89,9 +89,9 @@ operating system on which the build is performed (as reported by C<uname
<para>
- (&SCons; only reports "...is up to date"
+ Note that &SCons; only reports "...is up to date"
for target files named explicitly on the command line,
- to avoid cluttering the output.)
+ to avoid cluttering the output.
</para>
@@ -172,15 +172,12 @@ included by included files will also be scanned.
<para>
- X
+ Now suppose that our "Hello, World!" program
+ actually looks like this:
</para>
<programlisting>
- #define string "world"
- </programlisting>
-
- <programlisting>
#include "hello.h"
int
main()
@@ -189,11 +186,44 @@ included by included files will also be scanned.
}
</programlisting>
+ <para>
+
+ That is, the first line
+ includes a &hello_h;
+ that looks like this:
+
+ </para>
+
+ <programlisting>
+ #define string "world"
+ </programlisting>
+
+ <para>
+
+ In this case, we want &SCons; to recognize that,
+ if the contents of the &hello_h; file change,
+ the &hello; program must be recompiled.
+ To do this, we need to modify the
+ &SConstruct; file like so:
+
+ </para>
+
<programlisting>
env = Environment(CPPPATH = '.') XXX IS CPPPATH NECESSARY?
hello = env.Program('hello.c')
</programlisting>
+ <para>
+
+ The &CPPPATH; assignment in the &Environment; call
+ tells &SCons; to look in the current directory
+ (<literal>'.'</literal>)
+ for any files included by C source files
+ (<filename>.c</filename> or <filename>.h</filename> files).
+ With this assignment in the &SConstruct file:
+
+ </para>
+
<literallayout>
% <userinput>scons hello</userinput>
cc -c hello.c -o hello.o
@@ -210,20 +240,20 @@ included by included files will also be scanned.
<para>
- &SCons; knows that the &hello;
- program must be rebuilt
- because it scans the contents of
- the &hello_c;
- for the #include lines that indicate
- another file is being included in the compilation.
- &SCons; records these as
- <emphasis>implicit dependencies</emphasis>
- of the target file,
- Consequently,
- when the &hello_h; file changes,
- &SCons; realizes that the &hello_c; file includes it,
- and rebuilds the resulting &hello; program
- that depends on both the &hello_c; and &hello_h; files.
+ &SCons; knows that the &hello;
+ program must be rebuilt
+ because it scans the contents of
+ the &hello_c; file
+ for the <literal>#include</literal> lines that indicate
+ another file is being included in the compilation.
+ &SCons; records these as
+ <emphasis>implicit dependencies</emphasis>
+ of the target file,
+ Consequently,
+ when the &hello_h; file changes,
+ &SCons; realizes that the &hello_c; file includes it,
+ and rebuilds the resulting &hello; program
+ that depends on both the &hello_c; and &hello_h; files.
</para>
diff --git a/doc/user/help.sgml b/doc/user/help.sgml
index 7c1732e..5e2ced3 100644
--- a/doc/user/help.sgml
+++ b/doc/user/help.sgml
@@ -23,15 +23,6 @@
-->
- <para>
-
- X
-
- </para>
-
- <section>
- <title>Providing build-specific help instructions</title>
-
<para>
It's often very useful to be able to give
@@ -84,5 +75,3 @@
the <literal>-H</literal> option is used.
</para>
-
- </section>
diff --git a/doc/user/main.sgml b/doc/user/main.sgml
index bb64b72..b285696 100644
--- a/doc/user/main.sgml
+++ b/doc/user/main.sgml
@@ -76,10 +76,10 @@
<edition>Revision &buildrevision; (&builddate;)</edition>
- <pubdate>2001</pubdate>
+ <pubdate>2003</pubdate>
<copyright>
- <year>2001</year>
+ <year>2003</year>
<holder>Steven Knight</holder>
</copyright>
diff --git a/doc/user/repositories.sgml b/doc/user/repositories.sgml
index 4acc943..2193a8f 100644
--- a/doc/user/repositories.sgml
+++ b/doc/user/repositories.sgml
@@ -142,7 +142,7 @@ subdirectories under the repository tree.
directory trees that contain
source code, or derived files, or both.
You can eliminate additional unnecessary
- rebuilds of files by having &SCons;,
+ rebuilds of files by having &SCons;
use files from one or more code repositories
to build files in your local build tree.
@@ -163,8 +163,8 @@ used to build any local derived files.
<para>
- You use the &Repository; method
- to tell &SCons; to search one or more
+ The &Repository; method
+ tells &SCons; to search one or more
central code repositories (in order)
for any source files and derived files
that are not present in the local build tree:
@@ -223,7 +223,7 @@ used to build any local derived files.
</para>
<literallayout>
- % <userinput>scons .</userinput>
+ % <userinput>scons</userinput>
gcc -c hello.c -o hello.o
gcc -o hello hello.o
</literallayout>
@@ -238,7 +238,7 @@ used to build any local derived files.
</para>
<literallayout>
- % <userinput>scons .</userinput>
+ % <userinput>scons</userinput>
gcc -c /usr/repository1/hello.c -o hello.o
gcc -o hello hello.o
</literallayout>
@@ -252,7 +252,7 @@ used to build any local derived files.
</para>
<literallayout>
- % <userinput>scons .</userinput>
+ % <userinput>scons</userinput>
gcc -c /usr/repository2/hello.c -o hello.o
gcc -o hello hello.o
</literallayout>
@@ -281,7 +281,7 @@ used to build any local derived files.
</para>
<literallayout>
- % <userinput>scons -Y /usr/repository1 -Y /usr/repository2 .</userinput>
+ % <userinput>scons -Y /usr/repository1 -Y /usr/repository2</userinput>
</literallayout>
<para>
@@ -303,7 +303,7 @@ used to build any local derived files.
If a repository contains not only source files,
but also derived files (such as object files,
- libraries, or exectuables), &SCons; will perform
+ libraries, or executables), &SCons; will perform
its normal MD5 signature calculation to
decide if a derived file in a repository is up-to-date,
or the derived file must be rebuilt in the local build directory.
@@ -325,7 +325,7 @@ used to build any local derived files.
<literallayout>
% <userinput>cd /usr/repository1</userinput>
- % <userinput>scons .</userinput>
+ % <userinput>scons</userinput>
gcc -c hello.c -o hello.o
gcc -o hello hello.o
</literallayout>
@@ -353,7 +353,7 @@ used to build any local derived files.
<literallayout>
% <userinput>cd $HOME/build</userinput>
% <userinput>edit hello.c</userinput>
- % <userinput>scons -Y /usr/repository1 .</userinput>
+ % <userinput>scons -Y /usr/repository1</userinput>
gcc -c hello.c -o hello.o
gcc -o hello hello.o
XXXXXXX
@@ -385,8 +385,8 @@ used to build any local derived files.
<literallayout>
% <userinput>mkdir $HOME/build2</userinput>
% <userinput>cd $HOME/build2</userinput>
- % <userinput>cons -Y /usr/all/repository hello</userinput>
- cons: "hello" is up-to-date.
+ % <userinput>scons -Y /usr/all/repository hello</userinput>
+ scons: `hello' is up-to-date.
</literallayout>
<para>
diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml
index 9071160..8cafe2d 100644
--- a/doc/user/simple.sgml
+++ b/doc/user/simple.sgml
@@ -44,7 +44,6 @@ requirements of a build.
<para>
Here's how to build the famous "Hello, World!" example using &SCons;.
- Enter the following into a file name &SConstruct;:
</para>
@@ -56,6 +55,12 @@ requirements of a build.
}
</programlisting>
+ <para>
+
+ Enter the following into a file name &SConstruct;:
+
+ </para>
+
<programlisting>
env = Environment()
env.Program('hello.c')
@@ -70,7 +75,7 @@ requirements of a build.
</para>
<literallayout>
- % <userinput>scons .</userinput>
+ % <userinput>scons</userinput>
cc -c hello.c -o hello.o
cc -o hello hello.o
</literallayout>
@@ -83,32 +88,42 @@ requirements of a build.
</para>
<literallayout>
- C:\><userinput>scons .</userinput>
+ C:\><userinput>scons</userinput>
cl /Fohello.obj hello.c
link /Fohello.exe hello.obj
</literallayout>
<para>
- First, notice that you need to supply a '.' on the command line.
- This tells &SCons; to build everything in the current directory
- or its subdirectories.
- We'll tell you later how to avoid having to use the '.'
+ First, notice that you only need
+ to specify the name of the source file,
+ and that &SCons; deduces the names of
+ the object and executable files
+ correctly from the source file.
</para>
<para>
- Next, notice that the same input &SConstruct; file
- without any special input,
- generates the right output file names on both systems:
+ 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>
on POSIX systems,
<filename>hello.obj</filename> and <filename>hello.exe</filename>
on Windows systems.
- (We won't provide side-by-side examples of POSIX
- and Windows runs for all future examples;
- just know that XXX.)
+ This is a simple example of how easy it is to
+ use &SCons; to write portable software builds.
+
+ </para>
+
+ <para>
+
+ (Note that we won't provide duplicate side-by-side
+ POSIX and Windows output for the
+ rest of the examples in this guide;
+ just keep in mind that, unless otherwise specified,
+ any of the examples should work equally well on both types of systems.)
</para>
@@ -132,19 +147,17 @@ requirements of a build.
an &SConstruct; file and a &Makefile:
the &SConstruct; file is actually a Python script.
If you're not already familiar with Python, don't worry;
- you don't really need to know Python to be able to use
- &SCons; effectively.
- But you'll see that being able to use the power of a
- real scripting language
- can greatly simplify the solutions
- to complex requirements of real-world builds.
+ Python is extremely easy to learn,
+ and this User's Guide will introduce you step-by-step
+ to the relatively small amount of Python you'll
+ neede to know to be able to use &SCons; effectively.
</para>
<para>
- For now, one ramification of using Python as the
- scripting language means that you can put comments
+ One aspect of using Python as the
+ scripting language is that you can put comments
in your &SConstruct; file using Python's commenting convention;
that is, everything between a '#' and the end of the line
will be ignored:
@@ -157,6 +170,16 @@ requirements of a build.
env.Program('hello.c')
</programlisting>
+ <para>
+
+ You'll see throughout the remainder of this Guide
+ that being able to use the power of a
+ real scripting language
+ can greatly simplify the solutions
+ to complex requirements of real-world builds.
+
+ </para>
+
</section>
<section>
@@ -164,7 +187,15 @@ requirements of a build.
<para>
- If you want
+ It's more common, of course,
+ that you'll need to build a program from
+ not just one, but many input source files.
+ To do this, you need to put the
+ source files in a Python list
+ (enclosed in square brackets),
+ and slide that list over to to the right
+ to make room for the output program file name.
+ For example:
</para>
@@ -173,19 +204,156 @@ requirements of a build.
env.Program('program', ['main.c', 'file1.c', 'file2.'])
</programlisting>
- <programlisting>
- env = Environment()
- env.Program('program', Split('main.c file1.c file2.'))
- </programlisting>
+ <para>
+
+ (&SCons; puts the output file name to the left
+ of the source file names
+ so that the order mimics that of an
+ assignment statement: "program = source files".)
+
+ </para>
+
+ <para>
+
+ A build of the above example would look:
+
+ </para>
<literallayout>
- % <userinput>scons .</userinput>
+ % <userinput>scons</userinput>
cc -c file1.c -o file1.o
cc -c file2.c -o file2.o
cc -c main.c -o main.o
cc -o program main.o file1.o file2.o
</literallayout>
+ <!--
+
+ XXX DO WE NEED WINDOWS EXAMPLE OUTPUT HERE?
+
+ </para>
+
+ Or on Windows:
+
+ </para>
+
+ <literallayout>
+ C:\><userinput>scons</userinput>
+ cl /Fofile1.obj file1.c
+ cl /Fofile2.obj file2.c
+ cl /Fomain.obj main.c
+ link /Foprogram.exe main.obj file1.obj file2.obj
+ </literallayout>
+
+ -->
+
+ </section>
+
+ <section>
+ <title>Keeping &SConstruct; Files Easy to Read</title>
+
+ <para>
+
+ One minor drawback to the use of a Python list
+ for source files is that
+ each file name must be enclosed in quotes
+ (either single quotes or double quotes).
+ This can get cumbersome and difficult to read
+ when the list of file names is long.
+ Fortunately, there are a number of things
+ we can do to make sure that
+ the &SConstruct; file stays easy to read.
+
+ </para>
+
+ <para>
+
+ To make long lists of file names
+ easier to deal with, &SCons; provides a
+ &Split; function
+ that takes a quoted list of file names,
+ with the names separated by spaces or other white-space characters,
+ and turns it into a list of separate file names.
+ Using the &Split; function turns the
+ previous example into:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ env.Program('program', Split('main.c file1.c file2.'))
+ </programlisting>
+
+ <para>
+
+ Putting the call to the &Split; function
+ inside the <function>env.Program</function> call
+ can also be a little unwieldy.
+ A more readable alternative is to
+ assign the output from the &Split; call
+ to a variable name,
+ and then use the variable when calling the
+ <function>env.Program</function> function:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ list = Split('main.c file1.c file2.')
+ env.Program('program', list)
+ </programlisting>
+
+ <para>
+
+ Lastly, the &Split; function
+ doesn't care how much white space separates
+ the file names in the quoted string.
+ This allows you to create lists of file
+ names that span multiple lines,
+ which often makes for easier editing:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ list = Split('main.c
+ file1.c
+ file2.c')
+ env.Program('program', list)
+ </programlisting>
+
+ </section>
+
+ <section>
+ <title>Keyword Arguments</title>
+
+ <para>
+
+ &SCons; also allows you to identify
+ the output file and input source files
+ by Python keyword arguments.
+ The output file is known as the
+ <emphasis>target</emphasis>,
+ and the source file(s) are known (logically enough) as the
+ <emphasis>source</emphasis>.
+ The Python syntax for this is:
+
+ </para>
+
+ <programlisting>
+ env = Environment()
+ list = Split('main.c file1.c file2.')
+ env.Program(target = 'program', source = list)
+ </programlisting>
+
+ <para>
+
+ Whether or not you choose to use keyword arguments
+ to identify the target and source files
+ is purely a personal choice.
+
+ </para>
+
</section>
<section>
@@ -193,7 +361,11 @@ requirements of a build.
<para>
- If you want
+ In order to compile multiple programs
+ within the same &SConstruct; file,
+ simply call <function>env.Program</function>
+ multiple times,
+ once for each program you need to build:
</para>
@@ -203,8 +375,14 @@ requirements of a build.
env.Program('bar', ['bar1.c', 'bar2.c'])
</programlisting>
+ <para>
+
+ &SCons; would then build the programs as follows:
+
+ </para>
+
<literallayout>
- % <userinput>scons .</userinput>
+ % <userinput>scons</userinput>
cc -c bar1.c -o bar1.o
cc -c bar2.c -o bar2.o
cc -o bar bar1.o bar2.o
@@ -215,11 +393,11 @@ requirements of a build.
</section>
<section>
- <title>Sharing Files Between Multiple Programs</title>
+ <title>Sharing Source Files Between Multiple Programs</title>
<para>
- If you want
+ XXX
</para>
@@ -231,7 +409,7 @@ requirements of a build.
</programlisting>
<literallayout>
- % <userinput>scons .</userinput>
+ % <userinput>scons</userinput>
cc -c bar1.c -o bar1.o
cc -c bar2.c -o bar2.o
cc -c common1.c -o common1.o
generated by cgit v0.12 at 2024-12-04 19:53:06 (GMT)