From 4e233ae6eee0d731bb80405054e587ea665ac48c Mon Sep 17 00:00:00 2001 From: stevenknight Date: Thu, 29 Jan 2009 17:06:51 +0000 Subject: [PATCH] User's Guide updates: fix typos, clarify various things. (Robert P. J. Day) git-svn-id: http://scons.tigris.org/svn/scons/trunk@3931 fdb21ef1-2011-0410-befe-b5e4ea1792b1 --- doc/scons.mod | 14 +++++++------- doc/user/build-install.in | 24 +++++++++++++++++++----- doc/user/build-install.xml | 24 +++++++++++++++++++----- doc/user/depends.in | 20 ++++++++++---------- doc/user/depends.xml | 22 +++++++++++----------- doc/user/less-simple.in | 10 +++++++--- doc/user/less-simple.xml | 10 +++++++--- doc/user/libraries.in | 2 +- doc/user/nodes.in | 24 ++++++++++++++++++++---- doc/user/nodes.xml | 24 ++++++++++++++++++++---- 10 files changed, 121 insertions(+), 53 deletions(-) diff --git a/doc/scons.mod b/doc/scons.mod index a2927cf8..7f1b54a4 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -46,7 +46,6 @@ ranlib"> rmic"> SCons"> -scons"> ScCons"> swig"> tar"> @@ -128,6 +127,7 @@ build"> Makefile"> Makefiles"> +scons"> SConscript"> SConstruct"> Sconstruct"> @@ -463,11 +463,11 @@ --> -bar"> +bar"> common1.c"> common2.c"> custom.py"> -goodbye"> +goodbye"> goodbye.o"> goodbye.obj"> file.dll"> @@ -476,10 +476,10 @@ file.o"> file.obj"> file.out"> -foo"> +foo"> foo.o"> foo.obj"> -hello"> +hello"> hello.c"> hello.exe"> hello.h"> @@ -487,8 +487,8 @@ hello.obj"> libfile_a"> libfile_so"> -new_hello"> -new_hello.exe"> +new_hello"> +new_hello.exe"> prog"> prog1"> prog2"> diff --git a/doc/user/build-install.in b/doc/user/build-install.in index e473e376..86163611 100644 --- a/doc/user/build-install.in +++ b/doc/user/build-install.in @@ -136,7 +136,7 @@ If you need to install Python and have a choice, we recommend using the most recent Python 2.5 version available. Python 2.5 has significant improvements - the help speed up the performance of &SCons;. + that help speed up the performance of &SCons;. @@ -214,8 +214,7 @@ - Or, you can use a graphical RPM package manager - like gnorpm. + Or, you can use a graphical RPM package manager. See your package manager application's documention for specific instructions about how to use it to install a downloaded RPM. @@ -411,7 +410,7 @@ This will build &SCons;, - install the scons script + install the &scons; script in the default system scripts directory (/usr/local/bin or C:\Python25\Scripts), @@ -549,7 +548,7 @@ For example, to install &SCons; in appropriate locations relative to the user's $HOME directory, - the scons script in + the &scons; script in $HOME/bin and the build engine in $HOME/lib/scons, @@ -570,6 +569,21 @@ + + + This can also be used to experiment with a newer + version of &SCons; than the one installed + in your system locations. + Of course, the location in which you install the + newer version of the &scons; script + ($HOME/bin in the above example) + must be configured in your &PATH; variable + before the directory containing + the system-installed version + of the &scons; script. + + + diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml index e473e376..86163611 100644 --- a/doc/user/build-install.xml +++ b/doc/user/build-install.xml @@ -136,7 +136,7 @@ If you need to install Python and have a choice, we recommend using the most recent Python 2.5 version available. Python 2.5 has significant improvements - the help speed up the performance of &SCons;. + that help speed up the performance of &SCons;. @@ -214,8 +214,7 @@ - Or, you can use a graphical RPM package manager - like gnorpm. + Or, you can use a graphical RPM package manager. See your package manager application's documention for specific instructions about how to use it to install a downloaded RPM. @@ -411,7 +410,7 @@ This will build &SCons;, - install the scons script + install the &scons; script in the default system scripts directory (/usr/local/bin or C:\Python25\Scripts), @@ -549,7 +548,7 @@ For example, to install &SCons; in appropriate locations relative to the user's $HOME directory, - the scons script in + the &scons; script in $HOME/bin and the build engine in $HOME/lib/scons, @@ -570,6 +569,21 @@ + + + This can also be used to experiment with a newer + version of &SCons; than the one installed + in your system locations. + Of course, the location in which you install the + newer version of the &scons; script + ($HOME/bin in the above example) + must be configured in your &PATH; variable + before the directory containing + the system-installed version + of the &scons; script. + + + diff --git a/doc/user/depends.in b/doc/user/depends.in index 8cd99703..f0fa853e 100644 --- a/doc/user/depends.in +++ b/doc/user/depends.in @@ -27,10 +27,10 @@ So far we've seen how &SCons; handles one-time builds. But one of the main functions of a build tool like &SCons; - is to rebuild only the necessary things + is to rebuild only what is necessary when source files change--or, put another way, &SCons; should not - waste time rebuilding things that have already been built. + waste time rebuilding things that don't need to be rebuilt. You can see this at work simply by re-invoking &SCons; after building our simple &hello; example: @@ -168,7 +168,7 @@ - Using MD5 Signatures to decide if an input file has changed + Using MD5 signatures to decide if an input file has changed has one surprising benefit: if a source file has been changed in such a way that the contents of the @@ -237,7 +237,7 @@ The most familiar way to use time stamps is the way &Make; does: that is, have &SCons; decide - and target must be rebuilt if + that a target must be rebuilt if a source file's modification time is newer than the target file. @@ -366,8 +366,8 @@ As a performance enhancement, &SCons; provides a way to use MD5 checksums of file contents - but to only read the contents - whenever the file's timestamp has changed. + but to read those contents + only when the file's timestamp has changed. To do this, call the &Decider; function with 'MD5-timestamp' argument as follows: @@ -444,11 +444,11 @@ While most developers are programming, this isn't a problem in practice, since it's unlikely that someone will have built - and then thought quickly enought to make a substantive + and then thought quickly enough to make a substantive change to a source file within one second. Certain build scripts or continuous integration tools may, however, - rely on the ability to applying changes to files + rely on the ability to apply changes to files automatically and then rebuild as quickly as possible, in which case use of Decider('MD5-timestamp') @@ -486,7 +486,7 @@ We'd like to have each target file depend on only its section of the input file. However, since the input file may contain a lot of data, - we only want to open the input file if its timestamp has changed. + we want to open the input file only if its timestamp has changed. This could done with a custom &Decider; function that might look something like this: @@ -615,7 +615,7 @@ For example, if we arbitrarily want to build one program using MD5 checkums - and another use file modification times + and another using file modification times from the same source we might configure it this way: diff --git a/doc/user/depends.xml b/doc/user/depends.xml index 512ac689..0e9740f4 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -27,10 +27,10 @@ So far we've seen how &SCons; handles one-time builds. But one of the main functions of a build tool like &SCons; - is to rebuild only the necessary things + is to rebuild only what is necessary when source files change--or, put another way, &SCons; should not - waste time rebuilding things that have already been built. + waste time rebuilding things that don't need to be rebuilt. You can see this at work simply by re-invoking &SCons; after building our simple &hello; example: @@ -175,7 +175,7 @@ - Using MD5 Signatures to decide if an input file has changed + Using MD5 signatures to decide if an input file has changed has one surprising benefit: if a source file has been changed in such a way that the contents of the @@ -249,7 +249,7 @@ The most familiar way to use time stamps is the way &Make; does: that is, have &SCons; decide - and target must be rebuilt if + that a target must be rebuilt if a source file's modification time is newer than the target file. @@ -350,7 +350,7 @@ % touch -t 198901010000 hello.c % scons -Q hello cc -o hello.o -c hello.c - scons: `hello' is up to date. + cc -o hello hello.o @@ -376,8 +376,8 @@ As a performance enhancement, &SCons; provides a way to use MD5 checksums of file contents - but to only read the contents - whenever the file's timestamp has changed. + but to read those contents + only when the file's timestamp has changed. To do this, call the &Decider; function with 'MD5-timestamp' argument as follows: @@ -449,11 +449,11 @@ While most developers are programming, this isn't a problem in practice, since it's unlikely that someone will have built - and then thought quickly enought to make a substantive + and then thought quickly enough to make a substantive change to a source file within one second. Certain build scripts or continuous integration tools may, however, - rely on the ability to applying changes to files + rely on the ability to apply changes to files automatically and then rebuild as quickly as possible, in which case use of Decider('MD5-timestamp') @@ -491,7 +491,7 @@ We'd like to have each target file depend on only its section of the input file. However, since the input file may contain a lot of data, - we only want to open the input file if its timestamp has changed. + we want to open the input file only if its timestamp has changed. This could done with a custom &Decider; function that might look something like this: @@ -615,7 +615,7 @@ For example, if we arbitrarily want to build one program using MD5 checkums - and another use file modification times + and another using file modification times from the same source we might configure it this way: diff --git a/doc/user/less-simple.in b/doc/user/less-simple.in index 23b585c2..f7bd7d58 100644 --- a/doc/user/less-simple.in +++ b/doc/user/less-simple.in @@ -231,8 +231,12 @@ - The SCons man page has more details on using &Glob; with Variant - directories and Repositories, and returning strings rather than Nodes. + The SCons man page has more details on using &Glob; + with variant directories + (see , below) + and repositories + (see , below), + and returning strings rather than Nodes. @@ -578,7 +582,7 @@ &SCons; recognizes that the object files for the &common1_c; and &common2_c; source files - each only need to be built once, + each need to be built only once, even though the resulting object files are each linked in to both of the resulting executable programs: diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml index 28fc0537..0bc382ef 100644 --- a/doc/user/less-simple.xml +++ b/doc/user/less-simple.xml @@ -220,8 +220,12 @@ - The SCons man page has more details on using &Glob; with Variant - directories and Repositories, and returning strings rather than Nodes. + The SCons man page has more details on using &Glob; + with variant directories + (see , below) + and repositories + (see , below), + and returning strings rather than Nodes. @@ -544,7 +548,7 @@ &SCons; recognizes that the object files for the &common1_c; and &common2_c; source files - each only need to be built once, + each need to be built only once, even though the resulting object files are each linked in to both of the resulting executable programs: diff --git a/doc/user/libraries.in b/doc/user/libraries.in index 73ba6c92..e219e214 100644 --- a/doc/user/libraries.in +++ b/doc/user/libraries.in @@ -62,7 +62,7 @@ &SCons; uses the appropriate library prefix and suffix for your system. So on POSIX or Linux systems, the above example would build as follows - (although &ranlib may not be called on all systems): + (although &ranlib; may not be called on all systems): diff --git a/doc/user/nodes.in b/doc/user/nodes.in index 6d4b267d..d8169df4 100644 --- a/doc/user/nodes.in +++ b/doc/user/nodes.in @@ -44,7 +44,7 @@ &Node; objects that identify the target file or files that will be built. These returned &Nodes; can be passed - as source files to other builder methods, + as arguments to other builder methods. @@ -81,7 +81,7 @@ - The problem with listing the names as strings + The problem with specifying the names as strings is that our &SConstruct; file is no longer portable across operating systems. It won't, for example, work on Windows @@ -155,7 +155,7 @@ between Nodes that represent files and Nodes that represent directories. &SCons; supports &File; and &Dir; - functions that, repectively, + functions that, respectively, return a file or directory Node: @@ -231,6 +231,11 @@ One of the most common things you can do with a Node is use it to print the file name that the node represents. + Keep in mind, though, that because the object + returned by a builder call + is a list of Nodes, + you must use Python subscripts + to fetch individual Nodes from the list. For example, the following &SConstruct; file: @@ -267,6 +272,17 @@ scons -Q + + + Note that in the above example, + the object_list[0] + extracts an actual Node object + from the list, + and the Python print statement + converts the object to a string for printing. + + +
@@ -276,7 +292,7 @@ Printing a &Node;'s name as described in the previous section - works because the string representation of a &Node; + works because the string representation of a &Node; object is the name of the file. If you want to do something other than print the name of the file, diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml index 28af9736..8f3436a4 100644 --- a/doc/user/nodes.xml +++ b/doc/user/nodes.xml @@ -44,7 +44,7 @@ &Node; objects that identify the target file or files that will be built. These returned &Nodes; can be passed - as source files to other builder methods, + as arguments to other builder methods. @@ -81,7 +81,7 @@ - The problem with listing the names as strings + The problem with specifying the names as strings is that our &SConstruct; file is no longer portable across operating systems. It won't, for example, work on Windows @@ -153,7 +153,7 @@ between Nodes that represent files and Nodes that represent directories. &SCons; supports &File; and &Dir; - functions that, repectively, + functions that, respectively, return a file or directory Node: @@ -227,6 +227,11 @@ One of the most common things you can do with a Node is use it to print the file name that the node represents. + Keep in mind, though, that because the object + returned by a builder call + is a list of Nodes, + you must use Python subscripts + to fetch individual Nodes from the list. For example, the following &SConstruct; file: @@ -272,6 +277,17 @@ link /nologo /OUT:hello.exe hello.obj + + + Note that in the above example, + the object_list[0] + extracts an actual Node object + from the list, + and the Python print statement + converts the object to a string for printing. + + +
@@ -281,7 +297,7 @@ Printing a &Node;'s name as described in the previous section - works because the string representation of a &Node; + works because the string representation of a &Node; object is the name of the file. If you want to do something other than print the name of the file, -- 2.26.2