From a655ffe484a23e7abaf7585832e43204399f0b6f Mon Sep 17 00:00:00 2001 From: stevenknight Date: Sat, 8 Feb 2003 13:51:02 +0000 Subject: [PATCH] More User's Guide edits. git-svn-id: http://scons.tigris.org/svn/scons/trunk@578 fdb21ef1-2011-0410-befe-b5e4ea1792b1 --- doc/SConscript | 4 + doc/scons.mod | 4 + doc/user/default.sgml | 148 +++++++++++++++++++++-- doc/user/depends.sgml | 76 ++++++++---- doc/user/help.sgml | 11 -- doc/user/main.sgml | 4 +- doc/user/repositories.sgml | 24 ++-- doc/user/simple.sgml | 242 ++++++++++++++++++++++++++++++++----- 8 files changed, 426 insertions(+), 87 deletions(-) diff --git a/doc/SConscript b/doc/SConscript index 7073246d..feb8a753 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -183,6 +183,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. if tidy: cmds.append("tidy -m -q $TARGET || true") env.Command(htmlindex, main, cmds) + Local(htmlindex) cmds = [ "rm -f ${TARGET.dir}/main.html", @@ -192,6 +193,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. if tidy: cmds.append("tidy -m -q $TARGET || true") env.Command(html, main, cmds) + Local(html) env.Ignore([html, htmlindex], "version.sgml") @@ -214,6 +216,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. "mv ${TARGET.dir}/main.ps $TARGET", "rm -f ${TARGET.dir}/%s" % out, ]) + Local(ps) env.Ignore(ps, "version.sgml") @@ -235,6 +238,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. "mv ${TARGET.dir}/main.pdf $TARGET", "rm -f ${TARGET.dir}/out", ]) + Local(pdf) env.Ignore(pdf, "version.sgml") diff --git a/doc/scons.mod b/doc/scons.mod index 642f979a..9f1832c4 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -103,6 +103,7 @@ RuleSet"> Salt"> SourceSignature"> +Split"> Task"> @@ -169,6 +170,8 @@ construction variable"> construction variables"> +CPPPATH"> + Dictionary"> +goodbye"> hello"> hello.c"> hello.h"> diff --git a/doc/user/default.sgml b/doc/user/default.sgml index bb81a3a8..eb2bdc1a 100644 --- a/doc/user/default.sgml +++ b/doc/user/default.sgml @@ -60,19 +60,153 @@ default list. --> - + + + 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: + + + + + env = Environment() + hello = env.Program('hello.c') + env.Program('goodbye.c') + Default(hello) + + + + + This &SConstruct; file builds two programs, + &hello; and &goodbye;, + but only builds the + &hello program by default: + + + + + % scons + cc -c hello.c -o hello.o + cc -o hello hello.o + % scons + % scons goodbye + cc -c goodbye.c -o goodbye.o + cc -o goodbye goodbye.o + % + + + + + Note that, even when you use the &Default; + function in your &SConstruct; file, + you can still explicitly specify the current directory + (.) on the command line + to tell &SCons; to build + everything in (or below) the current directory: + + + + + % scons . + cc -c goodbye.c -o goodbye.o + cc -o goodbye goodbye.o + cc -c hello.c -o hello.o + cc -o hello hello.o + % + + + - 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: - + + + + env = Environment() + prog1 = env.Program('prog1.c') + Default(prog1) + prog2 = env.Program('prog2.c') + prog3 = env.Program('prog3.c') + Default(prog3) + + + + + Or you can specify more than one target + in a single call to the &Default; function: + + + + + env = Environment() + prog1 = env.Program('prog1.c') + prog2 = env.Program('prog2.c') + prog3 = env.Program('prog3.c') + Default(prog1, prog3) + + + + + Either of these last two examples + will build only the + prog1 + and + prog3 + programs: + + + + + % scons + cc -c prog1.c -o prog1.o + cc -o prog1 prog1.o + cc -c prog3.c -o prog3.o + cc -o prog3 prog3.o + % scons . + cc -c prog2.c -o prog2.o + cc -o prog2 prog2.o + % + + + + + Lastly, if for some reason you don't want + any targets built by default, + you can use the Python None + variable: + + -
- The &Default; Method + + env = Environment() + prog1 = env.Program('prog1.c') + prog2 = env.Program('prog2.c') + Default(None) + - X + Which would produce build output like: -
+ + % scons + scons: *** No targets specified and no Default() targets found. Stop. + % scons . + cc -c prog1.c -o prog1.o + cc -o prog1 prog1.o + cc -c prog2.c -o prog2.o + cc -o prog2 prog2.o + % + diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml index c94ac0d1..e8491e4e 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 - % scons . + % scons cc -c hello.c -o hello.o cc -o hello hello.o - % scons . + % scons % @@ -89,9 +89,9 @@ operating system on which the build is performed (as reported by C - (&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. @@ -172,14 +172,11 @@ included by included files will also be scanned. - X + Now suppose that our "Hello, World!" program + actually looks like this: - - #define string "world" - - #include "hello.h" int @@ -189,11 +186,44 @@ included by included files will also be scanned. } + + + That is, the first line + includes a &hello_h; + that looks like this: + + + + + #define string "world" + + + + + 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: + + + env = Environment(CPPPATH = '.') XXX IS CPPPATH NECESSARY? hello = env.Program('hello.c') + + + The &CPPPATH; assignment in the &Environment; call + tells &SCons; to look in the current directory + ('.') + for any files included by C source files + (.c or .h files). + With this assignment in the &SConstruct file: + + + % scons hello cc -c hello.c -o hello.o @@ -210,20 +240,20 @@ included by included files will also be scanned. - &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 - implicit dependencies - 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 #include lines that indicate + another file is being included in the compilation. + &SCons; records these as + implicit dependencies + 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. diff --git a/doc/user/help.sgml b/doc/user/help.sgml index 7c1732e7..5e2ced38 100644 --- a/doc/user/help.sgml +++ b/doc/user/help.sgml @@ -23,15 +23,6 @@ --> - - - X - - - -
- Providing build-specific help instructions - It's often very useful to be able to give @@ -84,5 +75,3 @@ the -H option is used. - -
diff --git a/doc/user/main.sgml b/doc/user/main.sgml index bb64b725..b285696d 100644 --- a/doc/user/main.sgml +++ b/doc/user/main.sgml @@ -76,10 +76,10 @@ Revision &buildrevision; (&builddate;) - 2001 + 2003 - 2001 + 2003 Steven Knight diff --git a/doc/user/repositories.sgml b/doc/user/repositories.sgml index 4acc9432..2193a8fd 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. - 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. - % scons . + % scons gcc -c hello.c -o hello.o gcc -o hello hello.o @@ -238,7 +238,7 @@ used to build any local derived files. - % scons . + % scons gcc -c /usr/repository1/hello.c -o hello.o gcc -o hello hello.o @@ -252,7 +252,7 @@ used to build any local derived files. - % scons . + % scons gcc -c /usr/repository2/hello.c -o hello.o gcc -o hello hello.o @@ -281,7 +281,7 @@ used to build any local derived files. - % scons -Y /usr/repository1 -Y /usr/repository2 . + % scons -Y /usr/repository1 -Y /usr/repository2 @@ -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. % cd /usr/repository1 - % scons . + % scons gcc -c hello.c -o hello.o gcc -o hello hello.o @@ -353,7 +353,7 @@ used to build any local derived files. % cd $HOME/build % edit hello.c - % scons -Y /usr/repository1 . + % scons -Y /usr/repository1 gcc -c hello.c -o hello.o gcc -o hello hello.o XXXXXXX @@ -385,8 +385,8 @@ used to build any local derived files. % mkdir $HOME/build2 % cd $HOME/build2 - % cons -Y /usr/all/repository hello - cons: "hello" is up-to-date. + % scons -Y /usr/all/repository hello + scons: `hello' is up-to-date. diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml index 90711608..8cafe2d8 100644 --- a/doc/user/simple.sgml +++ b/doc/user/simple.sgml @@ -44,7 +44,6 @@ requirements of a build. Here's how to build the famous "Hello, World!" example using &SCons;. - Enter the following into a file name &SConstruct;: @@ -56,6 +55,12 @@ requirements of a build. } + + + Enter the following into a file name &SConstruct;: + + + env = Environment() env.Program('hello.c') @@ -70,7 +75,7 @@ requirements of a build. - % scons . + % scons cc -c hello.c -o hello.o cc -o hello hello.o @@ -83,32 +88,42 @@ requirements of a build. - C:\>scons . + C:\>scons cl /Fohello.obj hello.c link /Fohello.exe hello.obj - 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. - 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: hello.o and hello on POSIX systems, hello.obj and hello.exe 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. + + + + + + (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.) @@ -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. - 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') + + + 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. + + +
@@ -164,7 +187,15 @@ requirements of a build. - 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: @@ -173,19 +204,156 @@ requirements of a build. env.Program('program', ['main.c', 'file1.c', 'file2.']) - - env = Environment() - env.Program('program', Split('main.c file1.c file2.')) - + + + (&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".) + + + + + + A build of the above example would look: + + - % scons . + % scons 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 + + +
+ +
+ Keeping &SConstruct; Files Easy to Read + + + + 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. + + + + + + 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: + + + + + env = Environment() + env.Program('program', Split('main.c file1.c file2.')) + + + + + Putting the call to the &Split; function + inside the env.Program 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 + env.Program function: + + + + + env = Environment() + list = Split('main.c file1.c file2.') + env.Program('program', list) + + + + + 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: + + + + + env = Environment() + list = Split('main.c + file1.c + file2.c') + env.Program('program', list) + + +
+ +
+ Keyword Arguments + + + + &SCons; also allows you to identify + the output file and input source files + by Python keyword arguments. + The output file is known as the + target, + and the source file(s) are known (logically enough) as the + source. + The Python syntax for this is: + + + + + env = Environment() + list = Split('main.c file1.c file2.') + env.Program(target = 'program', source = list) + + + + + Whether or not you choose to use keyword arguments + to identify the target and source files + is purely a personal choice. + + +
@@ -193,7 +361,11 @@ requirements of a build. - If you want + In order to compile multiple programs + within the same &SConstruct; file, + simply call env.Program + multiple times, + once for each program you need to build: @@ -203,8 +375,14 @@ requirements of a build. env.Program('bar', ['bar1.c', 'bar2.c']) + + + &SCons; would then build the programs as follows: + + + - % scons . + % scons 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.
- Sharing Files Between Multiple Programs + Sharing Source Files Between Multiple Programs - If you want + XXX @@ -231,7 +409,7 @@ requirements of a build. - % scons . + % scons cc -c bar1.c -o bar1.o cc -c bar2.c -o bar2.o cc -c common1.c -o common1.o -- 2.26.2