diff options
Diffstat (limited to 'doc/user')
63 files changed, 3140 insertions, 616 deletions
diff --git a/doc/user/ENV.in b/doc/user/ENV.in index b1edd81..56d5901 100644 --- a/doc/user/ENV.in +++ b/doc/user/ENV.in @@ -31,7 +31,7 @@ the same external environment that you used to execute &SCons;. Instead, it uses the dictionary - stored in the &ENV; construction variable + stored in the &cv-link-ENV; construction variable as the external environment for executing commands. @@ -62,7 +62,7 @@ If you want to execute any commands--compilers, linkers, etc.--that are not in these default locations, you need to set the &PATH; value - in the &ENV; dictionary + in the &cv-ENV; dictionary in your construction environment. </para> @@ -82,14 +82,14 @@ <para> - Assign a dictionary to the &ENV; + Assign a dictionary to the &cv-ENV; construction variable in this way completely resets the external environment so that the only variable that will be set when external commands are executed will be the &PATH; value. If you want to use the rest of - the values in &ENV; and only + the values in &cv-ENV; and only set the value of &PATH;, the most straightforward way is probably: @@ -146,7 +146,7 @@ </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> --> diff --git a/doc/user/ENV.sgml b/doc/user/ENV.sgml index c2d7296..aa65ebd 100644 --- a/doc/user/ENV.sgml +++ b/doc/user/ENV.sgml @@ -31,7 +31,7 @@ the same external environment that you used to execute &SCons;. Instead, it uses the dictionary - stored in the &ENV; construction variable + stored in the &cv-link-ENV; construction variable as the external environment for executing commands. @@ -62,7 +62,7 @@ If you want to execute any commands--compilers, linkers, etc.--that are not in these default locations, you need to set the &PATH; value - in the &ENV; dictionary + in the &cv-ENV; dictionary in your construction environment. </para> @@ -82,14 +82,14 @@ <para> - Assign a dictionary to the &ENV; + Assign a dictionary to the &cv-ENV; construction variable in this way completely resets the external environment so that the only variable that will be set when external commands are executed will be the &PATH; value. If you want to use the rest of - the values in &ENV; and only + the values in &cv-ENV; and only set the value of &PATH;, the most straightforward way is probably: @@ -146,7 +146,7 @@ </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> --> diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST index e266393..3af2c9c 100644 --- a/doc/user/MANIFEST +++ b/doc/user/MANIFEST @@ -1,6 +1,7 @@ actions.sgml alias.sgml ant.sgml +builders.sgml builders-built-in.sgml builders-commands.sgml builders-writing.sgml @@ -15,6 +16,7 @@ ENV.sgml environments.sgml errors.sgml example.sgml +factories.sgml help.sgml hierarchy.sgml install.sgml @@ -24,8 +26,10 @@ less-simple.sgml main.sgml make.sgml nodes.sgml +parseconfig.sgml precious.sgml preface.sgml +python.sgml repositories.sgml run.sgml scanners.sgml @@ -34,8 +38,10 @@ separate.sgml simple.sgml sourcecode.sgml tasks.sgml +tools.sgml troubleshoot.sgml variants.sgml +variables.sgml SCons-win32-install-1.jpg SCons-win32-install-2.jpg SCons-win32-install-3.jpg diff --git a/doc/user/alias.in b/doc/user/alias.in index d2344a2..686c004 100644 --- a/doc/user/alias.in +++ b/doc/user/alias.in @@ -50,7 +50,7 @@ </para> <scons_output example="ex1" os="posix"> - <command>scons -Q install</command> + <scons_output_command>scons -Q install</scons_output_command> </scons_output> <para> @@ -95,8 +95,8 @@ </para> <scons_output example="ex2" os="posix"> - <command>scons -Q install-bin</command> - <command>scons -Q install-lib</command> - <command>scons -Q -c __ROOT__/</command> - <command>scons -Q install</command> + <scons_output_command>scons -Q install-bin</scons_output_command> + <scons_output_command>scons -Q install-lib</scons_output_command> + <scons_output_command>scons -Q -c __ROOT__/</scons_output_command> + <scons_output_command>scons -Q install</scons_output_command> </scons_output> diff --git a/doc/user/build-install.in b/doc/user/build-install.in index 0f63bd9..763c13e 100644 --- a/doc/user/build-install.in +++ b/doc/user/build-install.in @@ -78,6 +78,12 @@ </para> + <!-- + Robert P.J. Day has suggested using "python -V", + but that's not supported in 1.5.2, so we're going + to leave this as is for now. + --> + <screen> $ <userinput>python</userinput> Python 2.2.2 (#1, Feb 24 2003, 19:13:11) @@ -156,6 +162,7 @@ &SCons; comes in RPM (Red Hat Package Manager) format, pre-built and ready to install on Red Hat Linux, + Fedora Core, or any other Linux distribution that uses RPM. Your distribution may already have an &SCons; RPM built specifically for it; @@ -406,36 +413,6 @@ </para> - <section> - <title>Building and Installing &SCons; Without Administrative Privileges</title> - - <para> - - If you don't have the right privileges to install &SCons; - in a system location, - you can install it in a location of your choosing - by specifying the <literal>--prefix=</literal> option: - - </para> - - <screen> - # <userinput>python setup.py install --prefix=$HOME</userinput> - </screen> - - <para> - - This would install &SCons; in appropriate locations - relative to the user's <literal>$HOME</literal> directory, - the <application>scons</application> script in - <filename>$HOME/bin</filename> - and the build engine in - <filename>$HOME/lib/scons</filename>. - You may, of course, specify any other location you prefer. - - </para> - - </section> - <!-- <section> @@ -487,11 +464,6 @@ or <filename>C:\Python2.2\scons-__VERSION__</filename> directory, for example. - You can also specify <option>--prefix=</option>, - in which case <filename>setup.py</filename> - will install the build engine - in a version-specific directory - relative to the specified prefix. </para> @@ -512,6 +484,82 @@ </section> + <section> + <title>Installing &SCons; in Other Locations</title> + + <para> + + You can install &SCons; in locations other than + the default by specifying the <option>--prefix=</option> option: + + </para> + + <screen> + # <userinput>python setup.py install --prefix=/opt/scons</userinput> + </screen> + + <para> + + This would + install the <application>scons</application> script in + <filename>/opt/scons/bin</filename> + and the build engine in + <filename>/opt/scons/lib/scons</filename>, + + </para> + + <para> + + Note that you can specify both the <option>--prefix=</option> + and the <option>--version-lib</option> options + at the same type, + in which case <filename>setup.py</filename> + will install the build engine + in a version-specific directory + relative to the specified prefix. + Adding <option>--version-lib</option> to the + above example would install the build engine in + <filename>/opt/scons/lib/scons-__VERSION__</filename>. + + </para> + + </section> + + <section> + <title>Building and Installing &SCons; Without Administrative Privileges</title> + + <para> + + If you don't have the right privileges to install &SCons; + in a system location, + simply use the <literal>--prefix=</literal> option + to install it in a location of your choosing. + For example, + to install &SCons; in appropriate locations + relative to the user's <literal>$HOME</literal> directory, + the <application>scons</application> script in + <filename>$HOME/bin</filename> + and the build engine in + <filename>$HOME/lib/scons</filename>, + simply type: + + </para> + + <screen> + $ <userinput>python setup.py install --prefix=$HOME</userinput> + </screen> + + <para> + + You may, of course, specify any other location you prefer, + and may use the <option>--version-lib</option> option + if you would like to install version-specific directories + relative to the specified prefix. + + </para> + + </section> + </section> <!-- diff --git a/doc/user/build-install.sgml b/doc/user/build-install.sgml index 0f63bd9..763c13e 100644 --- a/doc/user/build-install.sgml +++ b/doc/user/build-install.sgml @@ -78,6 +78,12 @@ </para> + <!-- + Robert P.J. Day has suggested using "python -V", + but that's not supported in 1.5.2, so we're going + to leave this as is for now. + --> + <screen> $ <userinput>python</userinput> Python 2.2.2 (#1, Feb 24 2003, 19:13:11) @@ -156,6 +162,7 @@ &SCons; comes in RPM (Red Hat Package Manager) format, pre-built and ready to install on Red Hat Linux, + Fedora Core, or any other Linux distribution that uses RPM. Your distribution may already have an &SCons; RPM built specifically for it; @@ -406,36 +413,6 @@ </para> - <section> - <title>Building and Installing &SCons; Without Administrative Privileges</title> - - <para> - - If you don't have the right privileges to install &SCons; - in a system location, - you can install it in a location of your choosing - by specifying the <literal>--prefix=</literal> option: - - </para> - - <screen> - # <userinput>python setup.py install --prefix=$HOME</userinput> - </screen> - - <para> - - This would install &SCons; in appropriate locations - relative to the user's <literal>$HOME</literal> directory, - the <application>scons</application> script in - <filename>$HOME/bin</filename> - and the build engine in - <filename>$HOME/lib/scons</filename>. - You may, of course, specify any other location you prefer. - - </para> - - </section> - <!-- <section> @@ -487,11 +464,6 @@ or <filename>C:\Python2.2\scons-__VERSION__</filename> directory, for example. - You can also specify <option>--prefix=</option>, - in which case <filename>setup.py</filename> - will install the build engine - in a version-specific directory - relative to the specified prefix. </para> @@ -512,6 +484,82 @@ </section> + <section> + <title>Installing &SCons; in Other Locations</title> + + <para> + + You can install &SCons; in locations other than + the default by specifying the <option>--prefix=</option> option: + + </para> + + <screen> + # <userinput>python setup.py install --prefix=/opt/scons</userinput> + </screen> + + <para> + + This would + install the <application>scons</application> script in + <filename>/opt/scons/bin</filename> + and the build engine in + <filename>/opt/scons/lib/scons</filename>, + + </para> + + <para> + + Note that you can specify both the <option>--prefix=</option> + and the <option>--version-lib</option> options + at the same type, + in which case <filename>setup.py</filename> + will install the build engine + in a version-specific directory + relative to the specified prefix. + Adding <option>--version-lib</option> to the + above example would install the build engine in + <filename>/opt/scons/lib/scons-__VERSION__</filename>. + + </para> + + </section> + + <section> + <title>Building and Installing &SCons; Without Administrative Privileges</title> + + <para> + + If you don't have the right privileges to install &SCons; + in a system location, + simply use the <literal>--prefix=</literal> option + to install it in a location of your choosing. + For example, + to install &SCons; in appropriate locations + relative to the user's <literal>$HOME</literal> directory, + the <application>scons</application> script in + <filename>$HOME/bin</filename> + and the build engine in + <filename>$HOME/lib/scons</filename>, + simply type: + + </para> + + <screen> + $ <userinput>python setup.py install --prefix=$HOME</userinput> + </screen> + + <para> + + You may, of course, specify any other location you prefer, + and may use the <option>--version-lib</option> option + if you would like to install version-specific directories + relative to the specified prefix. + + </para> + + </section> + </section> <!-- diff --git a/doc/user/builders-built-in.in b/doc/user/builders-built-in.in index 1c7ed9f..8b0f16f 100644 --- a/doc/user/builders-built-in.in +++ b/doc/user/builders-built-in.in @@ -44,7 +44,7 @@ <para> - As we've seen, the &Program; Builder + As we've seen, the &b-link-Program; Builder is used to build an executable program. The &source; argument is one or more source-code files or object files, @@ -70,9 +70,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $PROGPREFIX + &cv-link-PROGPREFIX; and - $PROGSUFFIX + &cv-link-PROGSUFFIX; construction variables will be appended appropriately. For example: @@ -119,9 +119,9 @@ Two construction variables control what libraries will be linked with the resulting program. - The &LIBS; variable is a list of the names of + The &cv-link-LIBS; variable is a list of the names of libraries that will be linked into any programs, - and the &LIBPATH; variables is a list of + and the &cv-link-LIBPATH; variables is a list of directories that will be searched for the specified libraries. &SCons; will construct the right command-line @@ -151,7 +151,7 @@ </para> <scons_output example="libs" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -161,14 +161,14 @@ </para> <scons_output example="libs" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> - The &LIBS; construction variable + The &cv-LIBS; construction variable is turned into command line options - by appending the &LIBLINKPREFIX; and &LIBLINKSUFFIX; + by appending the &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX; construction variables to the beginning and end, respectively, of each specified library. @@ -176,9 +176,9 @@ <para> - The &LIBPATH; construction variable + The &cv-LIBPATH; construction variable is turned into command line options - by appending the &LIBDIRPREFIX; and &LIBDIRSUFFIX; + by appending the &cv-link-LIBDIRPREFIX; and &cv-link-LIBDIRSUFFIX; construction variables to the beginning and end, respectively, of each specified library. @@ -187,9 +187,9 @@ <para> Other relevant construction variables - include those used by the &Object; + include those used by the &b-link-Object; builders to affect how the - source files specified as input to the &Program; + source files specified as input to the &t-Program; builders are turned into object files; see the next section. @@ -198,10 +198,10 @@ <para> The command line used to control how a program is linked - is specified by the &LINKCOM; construction variable. + is specified by the &cv-link-LINKCOM; construction variable. By default, it uses the - &LINK; construction variable - and the &LINKFLAGS; construction variable. + &cv-link-LINK; construction variable + and the &cv-link-LINKFLAGS; construction variable. </para> @@ -224,7 +224,7 @@ <para> - The &StaticObject; Builder + The &b-link-StaticObject; Builder is used to build an object file suitable for static linking into a program, or for inclusion in a static library. @@ -251,9 +251,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $OBJPREFIX + &cv-link-OBJPREFIX; and - $OBJSUFFIX + &cv-link-OBJSUFFIX; construction variables will be appended appropriately. For example: @@ -303,7 +303,7 @@ <para> - The &SharedObject; Builder + The &b-link-SharedObject; Builder is used to build an object file suitable for shared linking into a program, or for inclusion in a shared library. @@ -330,9 +330,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $SHOBJPREFIX + &cv-link-SHOBJPREFIX; and - $SHOBJSUFFIX + &cv-link-SHOBJSUFFIX; construction variables will be appended appropriately. For example: @@ -382,7 +382,7 @@ <para> - The &Object; Builder is a synonym for &StaticObject; + The &b-link-Object; Builder is a synonym for &b-link-StaticObject; and is completely equivalent. </para> @@ -406,7 +406,7 @@ <para> - The &StaticLibrary; Builder + The &b-link-StaticLibrary; Builder is used to create a library suitable for static linking into a program. The &source; argument is one or more @@ -425,9 +425,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $LIBPREFIX + &cv-link-LIBPREFIX; and - $LIBSUFFIX + &cv-link-LIBSUFFIX; construction variables will be appended appropriately. For example: @@ -480,7 +480,7 @@ <para> - The &SharedLibrary; Builder + The &b-link-SharedLibrary; Builder is used to create a shared library suitable for linking with a program. The &source; argument is one or more @@ -499,9 +499,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $SHLIBPREFIX + &cv-link-SHLIBPREFIX; and - $SHLIBSUFFIX + &cv-link-SHLIBSUFFIX; construction variables will be appended appropriately. For example: @@ -554,7 +554,7 @@ <para> - The &Library; Builder is a synonym for &StaticLibrary; + The &b-link-Library; Builder is a synonym for &b-link-StaticLibrary; and is completely equivalent. </para> @@ -715,7 +715,7 @@ <para> - The &Tar; Builder object uses the &tar; + The &b-link-Tar; Builder object uses the &tar; utility to create archives of files and/or directory trees: @@ -739,7 +739,7 @@ </scons_example> <scons_output example="ex1" os="posix"> - <command>scons -Q .</command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <para> @@ -748,11 +748,11 @@ is to create a compressed archive using the <option>-z</option> option. This is easily handled by specifying - the value of the &TARFLAGS; variable + the value of the &cv-link-TARFLAGS; variable when you create the construction environment. Note, however, that the <option>-c</option> used to to instruct &tar; to create the archive - is part of the default value of &TARFLAGS;, + is part of the default value of &cv-TARFLAGS;, so you need to set it both options: </para> @@ -768,13 +768,13 @@ </scons_example> <scons_output example="ex2" os="posix"> - <command>scons -Q .</command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <para> you may also wish to set the value of the - &TARSUFFIX; construction variable + &cv-link-TARSUFFIX; construction variable to your desired suffix for compress &tar; archives, so that &SCons; can append it to the target file name without your having to specify it explicitly: @@ -793,7 +793,7 @@ </scons_example> <scons_output example="ex3" os="posix"> - <command>scons -Q .</command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> </section> @@ -803,7 +803,7 @@ <para> - The &Zip; Builder object creates archives of files + The &b-link-Zip; Builder object creates archives of files and/or directory trees in the ZIP file format. Python versions 1.6 or later contain an internal &zipfile; module @@ -835,7 +835,7 @@ </para> <scons_output example="ex4" os="posix"> - <command>scons -Q .</command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <para> @@ -870,7 +870,7 @@ <para> - The &Java; builder takes one or more input + The &b-link-Java; builder takes one or more input <filename>.java</filename> files and turns them into one or more <filename>.class</filename> files diff --git a/doc/user/builders-built-in.sgml b/doc/user/builders-built-in.sgml index 767e1d2..84877a3 100644 --- a/doc/user/builders-built-in.sgml +++ b/doc/user/builders-built-in.sgml @@ -44,7 +44,7 @@ <para> - As we've seen, the &Program; Builder + As we've seen, the &b-link-Program; Builder is used to build an executable program. The &source; argument is one or more source-code files or object files, @@ -70,9 +70,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $PROGPREFIX + &cv-link-PROGPREFIX; and - $PROGSUFFIX + &cv-link-PROGSUFFIX; construction variables will be appended appropriately. For example: @@ -119,9 +119,9 @@ Two construction variables control what libraries will be linked with the resulting program. - The &LIBS; variable is a list of the names of + The &cv-link-LIBS; variable is a list of the names of libraries that will be linked into any programs, - and the &LIBPATH; variables is a list of + and the &cv-link-LIBPATH; variables is a list of directories that will be searched for the specified libraries. &SCons; will construct the right command-line @@ -164,9 +164,9 @@ <para> - The &LIBS; construction variable + The &cv-LIBS; construction variable is turned into command line options - by appending the &LIBLINKPREFIX; and &LIBLINKSUFFIX; + by appending the &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX; construction variables to the beginning and end, respectively, of each specified library. @@ -174,9 +174,9 @@ <para> - The &LIBPATH; construction variable + The &cv-LIBPATH; construction variable is turned into command line options - by appending the &LIBDIRPREFIX; and &LIBDIRSUFFIX; + by appending the &cv-link-LIBDIRPREFIX; and &cv-link-LIBDIRSUFFIX; construction variables to the beginning and end, respectively, of each specified library. @@ -185,9 +185,9 @@ <para> Other relevant construction variables - include those used by the &Object; + include those used by the &b-link-Object; builders to affect how the - source files specified as input to the &Program; + source files specified as input to the &t-Program; builders are turned into object files; see the next section. @@ -196,10 +196,10 @@ <para> The command line used to control how a program is linked - is specified by the &LINKCOM; construction variable. + is specified by the &cv-link-LINKCOM; construction variable. By default, it uses the - &LINK; construction variable - and the &LINKFLAGS; construction variable. + &cv-link-LINK; construction variable + and the &cv-link-LINKFLAGS; construction variable. </para> @@ -222,7 +222,7 @@ <para> - The &StaticObject; Builder + The &b-link-StaticObject; Builder is used to build an object file suitable for static linking into a program, or for inclusion in a static library. @@ -249,9 +249,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $OBJPREFIX + &cv-link-OBJPREFIX; and - $OBJSUFFIX + &cv-link-OBJSUFFIX; construction variables will be appended appropriately. For example: @@ -301,7 +301,7 @@ <para> - The &SharedObject; Builder + The &b-link-SharedObject; Builder is used to build an object file suitable for shared linking into a program, or for inclusion in a shared library. @@ -328,9 +328,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $SHOBJPREFIX + &cv-link-SHOBJPREFIX; and - $SHOBJSUFFIX + &cv-link-SHOBJSUFFIX; construction variables will be appended appropriately. For example: @@ -380,7 +380,7 @@ <para> - The &Object; Builder is a synonym for &StaticObject; + The &b-link-Object; Builder is a synonym for &b-link-StaticObject; and is completely equivalent. </para> @@ -404,7 +404,7 @@ <para> - The &StaticLibrary; Builder + The &b-link-StaticLibrary; Builder is used to create a library suitable for static linking into a program. The &source; argument is one or more @@ -423,9 +423,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $LIBPREFIX + &cv-link-LIBPREFIX; and - $LIBSUFFIX + &cv-link-LIBSUFFIX; construction variables will be appended appropriately. For example: @@ -478,7 +478,7 @@ <para> - The &SharedLibrary; Builder + The &b-link-SharedLibrary; Builder is used to create a shared library suitable for linking with a program. The &source; argument is one or more @@ -497,9 +497,9 @@ The target file's prefix and suffix may be omitted, and the values from the - $SHLIBPREFIX + &cv-link-SHLIBPREFIX; and - $SHLIBSUFFIX + &cv-link-SHLIBSUFFIX; construction variables will be appended appropriately. For example: @@ -552,7 +552,7 @@ <para> - The &Library; Builder is a synonym for &StaticLibrary; + The &b-link-Library; Builder is a synonym for &b-link-StaticLibrary; and is completely equivalent. </para> @@ -713,7 +713,7 @@ <para> - The &Tar; Builder object uses the &tar; + The &b-link-Tar; Builder object uses the &tar; utility to create archives of files and/or directory trees: @@ -737,11 +737,11 @@ is to create a compressed archive using the <option>-z</option> option. This is easily handled by specifying - the value of the &TARFLAGS; variable + the value of the &cv-link-TARFLAGS; variable when you create the construction environment. Note, however, that the <option>-c</option> used to to instruct &tar; to create the archive - is part of the default value of &TARFLAGS;, + is part of the default value of &cv-TARFLAGS;, so you need to set it both options: </para> @@ -759,7 +759,7 @@ <para> you may also wish to set the value of the - &TARSUFFIX; construction variable + &cv-link-TARSUFFIX; construction variable to your desired suffix for compress &tar; archives, so that &SCons; can append it to the target file name without your having to specify it explicitly: @@ -784,7 +784,7 @@ <para> - The &Zip; Builder object creates archives of files + The &b-link-Zip; Builder object creates archives of files and/or directory trees in the ZIP file format. Python versions 1.6 or later contain an internal &zipfile; module @@ -844,7 +844,7 @@ <para> - The &Java; builder takes one or more input + The &b-link-Java; builder takes one or more input <filename>.java</filename> files and turns them into one or more <filename>.class</filename> files diff --git a/doc/user/builders-commands.in b/doc/user/builders-commands.in index f22fbd0..13a5c56 100644 --- a/doc/user/builders-commands.in +++ b/doc/user/builders-commands.in @@ -63,7 +63,7 @@ for a specific action to be executed to build a specific file or files. This looks a lot like the other builders - (like &Program;, &Object;, etc.), + (like &b-link-Program;, &b-link-Object;, etc.), but takes as an additional argument the command to be executed to build the file: @@ -80,14 +80,14 @@ </scons_example> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> This is often more convenient than creating a &Builder; object - and adding it to the &BUILDERS; variable + and adding it to the &cv-link-BUILDERS; variable of a &consenv; </para> @@ -112,5 +112,5 @@ </scons_example> <scons_output example="ex2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> diff --git a/doc/user/builders-commands.sgml b/doc/user/builders-commands.sgml index bef6ded..d2b990a 100644 --- a/doc/user/builders-commands.sgml +++ b/doc/user/builders-commands.sgml @@ -63,7 +63,7 @@ for a specific action to be executed to build a specific file or files. This looks a lot like the other builders - (like &Program;, &Object;, etc.), + (like &b-link-Program;, &b-link-Object;, etc.), but takes as an additional argument the command to be executed to build the file: @@ -76,14 +76,14 @@ <screen> % <userinput>scons -Q</userinput> - sed 's/x/y/' < foo.in > foo.out + sed 's/x/y/' < foo.in > foo.out </screen> <para> This is often more convenient than creating a &Builder; object - and adding it to the &BUILDERS; variable + and adding it to the &cv-link-BUILDERS; variable of a &consenv; </para> diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in index afd862b..ebfef5d 100644 --- a/doc/user/builders-writing.in +++ b/doc/user/builders-writing.in @@ -151,9 +151,9 @@ This functionality could be invoked as in the following example: until it's attached to a &consenv; so that we can call it to arrange for files to be built. - This is done through the &BUILDERS; + This is done through the &cv-link-BUILDERS; &consvar; in an environment. - The &BUILDERS; variable is a Python dictionary + The &cv-BUILDERS; variable is a Python dictionary that maps the names by which you want to call various &Builder; objects to the objects themselves. For example, if we want to call the @@ -202,17 +202,17 @@ This functionality could be invoked as in the following example: </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> - Note, however, that the default &BUILDERS; + Note, however, that the default &cv-BUILDERS; variable in a &consenv; comes with a default set of &Builder; objects already defined: - &Program;, &Library;, etc. - And when we explicitly set the &BUILDERS; variable + &b-link-Program;, &b-link-Library;, etc. + And when we explicitly set the &cv-BUILDERS; variable when we create the &consenv;, the default &Builder;s are no longer part of the environment: @@ -235,14 +235,14 @@ This functionality could be invoked as in the following example: </scons_example> <scons_output example="ex2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> To be able use both our own defined &Builder; objects and the default &Builder; objects in the same &consenv;, - you can either add to the &BUILDERS; variable + you can either add to the &cv-BUILDERS; variable using the &Append; function: </para> @@ -279,7 +279,7 @@ This functionality could be invoked as in the following example: <para> Or you can explicitly set the appropriately-named - key in the &BUILDERS; dictionary: + key in the &cv-BUILDERS; dictionary: </para> @@ -296,12 +296,12 @@ This functionality could be invoked as in the following example: Either way, the same &consenv; can then use both the newly-defined <function>Foo</function> &Builder; - and the default &Program; &Builder;: + and the default &b-link-Program; &Builder;: </para> <scons_output example="ex3"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -358,7 +358,7 @@ This functionality could be invoked as in the following example: </sconstruct> <scons_output example="ex4"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -499,7 +499,7 @@ This functionality could be invoked as in the following example: </para> <scons_output example="ex5"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -651,7 +651,7 @@ This functionality could be invoked as in the following example: </sconstruct> <scons_output example="ex6"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -716,7 +716,7 @@ This functionality could be invoked as in the following example: </sconstruct> <scons_output example="ex7"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <programlisting> @@ -761,7 +761,7 @@ This functionality could be invoked as in the following example: </scons_example> <scons_output example="ex8"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/builders-writing.sgml b/doc/user/builders-writing.sgml index 9b211e2..9085c0e 100644 --- a/doc/user/builders-writing.sgml +++ b/doc/user/builders-writing.sgml @@ -151,9 +151,9 @@ This functionality could be invoked as in the following example: until it's attached to a &consenv; so that we can call it to arrange for files to be built. - This is done through the &BUILDERS; + This is done through the &cv-link-BUILDERS; &consvar; in an environment. - The &BUILDERS; variable is a Python dictionary + The &cv-BUILDERS; variable is a Python dictionary that maps the names by which you want to call various &Builder; objects to the objects themselves. For example, if we want to call the @@ -189,17 +189,17 @@ This functionality could be invoked as in the following example: <screen> % <userinput>scons -Q</userinput> - foobuild < file.input > file.foo + foobuild < file.input > file.foo </screen> <para> - Note, however, that the default &BUILDERS; + Note, however, that the default &cv-BUILDERS; variable in a &consenv; comes with a default set of &Builder; objects already defined: - &Program;, &Library;, etc. - And when we explicitly set the &BUILDERS; variable + &b-link-Program;, &b-link-Library;, etc. + And when we explicitly set the &cv-BUILDERS; variable when we create the &consenv;, the default &Builder;s are no longer part of the environment: @@ -215,7 +215,7 @@ This functionality could be invoked as in the following example: <screen> % <userinput>scons -Q</userinput> - AttributeError: SConsEnvironment instance has no attribute 'Program': + AttributeError: 'SConsEnvironment' object has no attribute 'Program': File "SConstruct", line 4: env.Program('hello.c') </screen> @@ -224,7 +224,7 @@ This functionality could be invoked as in the following example: To be able use both our own defined &Builder; objects and the default &Builder; objects in the same &consenv;, - you can either add to the &BUILDERS; variable + you can either add to the &cv-BUILDERS; variable using the &Append; function: </para> @@ -242,7 +242,7 @@ This functionality could be invoked as in the following example: <para> Or you can explicitly set the appropriately-named - key in the &BUILDERS; dictionary: + key in the &cv-BUILDERS; dictionary: </para> @@ -259,13 +259,13 @@ This functionality could be invoked as in the following example: Either way, the same &consenv; can then use both the newly-defined <function>Foo</function> &Builder; - and the default &Program; &Builder;: + and the default &b-link-Program; &Builder;: </para> <screen> % <userinput>scons -Q</userinput> - foobuild < file.input > file.foo + foobuild < file.input > file.foo cc -c -o hello.o hello.c cc -o hello hello.o </screen> @@ -305,8 +305,8 @@ This functionality could be invoked as in the following example: <screen> % <userinput>scons -Q</userinput> - foobuild < file1.input > file1.foo - foobuild < file2.input > file2.foo + foobuild < file1.input > file1.foo + foobuild < file2.input > file2.foo </screen> <para> @@ -578,7 +578,7 @@ This functionality could be invoked as in the following example: <screen> % <userinput>scons -Q</userinput> - foobuild < file.input > file.foo + foobuild < file.input > file.foo </screen> <para> @@ -665,7 +665,7 @@ This functionality could be invoked as in the following example: </scons_example> <scons_output example="ex8"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/builders.in b/doc/user/builders.in new file mode 100644 index 0000000..2bc139d --- /dev/null +++ b/doc/user/builders.in @@ -0,0 +1,56 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<!-- +<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> + +<refentry id="Command"> + +<refmeta> +<refentrytitle>Command</refentrytitle> +</refmeta> + +<methodsynopsis> + <methodname>env.Command</methodname> + <methodparam>foo</methodparam> + <methodparam>bar</methodparam> +</methodsynopsis> + +</refentry> +--> + +<para> + +This appendix contains descriptions of all of the +Builders that are <emphasis>potentially</emphasis> +available "out of the box" in this version of SCons. + +</para> + +<variablelist> + +&builders-gen; + +</variablelist> diff --git a/doc/user/builders.sgml b/doc/user/builders.sgml new file mode 100644 index 0000000..2bc139d --- /dev/null +++ b/doc/user/builders.sgml @@ -0,0 +1,56 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<!-- +<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> + +<refentry id="Command"> + +<refmeta> +<refentrytitle>Command</refentrytitle> +</refmeta> + +<methodsynopsis> + <methodname>env.Command</methodname> + <methodparam>foo</methodparam> + <methodparam>bar</methodparam> +</methodsynopsis> + +</refentry> +--> + +<para> + +This appendix contains descriptions of all of the +Builders that are <emphasis>potentially</emphasis> +available "out of the box" in this version of SCons. + +</para> + +<variablelist> + +&builders-gen; + +</variablelist> diff --git a/doc/user/caching.in b/doc/user/caching.in index 552f3c1..0195c43 100644 --- a/doc/user/caching.in +++ b/doc/user/caching.in @@ -93,9 +93,9 @@ </para> <scons_output example="ex1"> - <command>scons -Q</command> - <command>scons -Q -c</command> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -129,9 +129,9 @@ </para> <scons_output example="ex1"> - <command>scons -Q</command> - <command>scons -Q -c</command> - <command>scons -Q --cache-show</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q --cache-show</scons_output_command> </scons_output> <para> @@ -176,11 +176,11 @@ </para> <scons_output example="ex1"> - <command>scons -Q</command> - <command>scons -Q -c</command> - <command>scons -Q</command> - <command>scons -Q -c</command> - <command>scons -Q --cache-disable</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q --cache-disable</scons_output_command> </scons_output> </section> @@ -217,12 +217,12 @@ </para> <scons_output example="ex1"> - <command>scons -Q --cache-disable</command> - <command>scons -Q -c</command> - <command>scons -Q --cache-disable</command> - <command>scons -Q --cache-force</command> - <command>scons -Q -c</command> - <command>scons -Q</command> + <scons_output_command>scons -Q --cache-disable</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q --cache-disable</scons_output_command> + <scons_output_command>scons -Q --cache-force</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> diff --git a/doc/user/command-line.in b/doc/user/command-line.in index f23755f..b444d30 100644 --- a/doc/user/command-line.in +++ b/doc/user/command-line.in @@ -78,9 +78,9 @@ </scons_example> <scons_output example="SCONSFLAGS"> - <command>scons</command> - <command>export SCONSFLAGS="-Q"</command> - <command environment="SCONSFLAGS=-Q">scons</command> + <scons_output_command>scons</scons_output_command> + <scons_output_command>export SCONSFLAGS="-Q"</scons_output_command> + <scons_output_command environment="SCONSFLAGS=-Q">scons</scons_output_command> </scons_output> <para> @@ -147,8 +147,8 @@ </para> <scons_output example="COMMAND_LINE_TARGETS"> - <command>scons -Q</command> - <command>scons -Q bar</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q bar</scons_output_command> </scons_output> <para> @@ -209,9 +209,9 @@ </para> <scons_output example="Default1"> - <command>scons -Q</command> - <command>scons -Q</command> - <command>scons -Q goodbye</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q goodbye</scons_output_command> </scons_output> <para> @@ -226,7 +226,7 @@ </para> <scons_output example="Default1"> - <command>scons -Q .</command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <para> @@ -285,8 +285,8 @@ </para> <scons_output example="Default2"> - <command>scons -Q</command> - <command>scons -Q .</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <para> @@ -327,9 +327,9 @@ </para> <scons_output example="Default3"> - <command>scons -Q</command> - <command>scons -Q</command> - <command>scons -Q .</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <para> @@ -363,8 +363,8 @@ </para> <scons_output example="Default4"> - <command>scons -Q</command> - <command>scons -Q .</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q .</scons_output_command> </scons_output> <section> @@ -408,7 +408,7 @@ </para> <scons_output example="DEFAULT_TARGETS_1"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -444,7 +444,7 @@ </para> <scons_output example="DEFAULT_TARGETS_2"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -537,9 +537,9 @@ </para> <scons_output example="BUILD_TARGETS_1"> - <command>scons -Q</command> - <command>scons -Q prog2</command> - <command>scons -Q -c .</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q prog2</scons_output_command> + <scons_output_command>scons -Q -c .</scons_output_command> </scons_output> </section> @@ -587,7 +587,7 @@ <para> - The following code sets the &CCFLAGS; construction + The following code sets the &cv-link-CCFLAGS; construction variable in response to the <varname>debug</varname> flag being set in the &ARGUMENTS; dictionary: @@ -616,10 +616,10 @@ </para> <scons_output example="ARGUMENTS"> - <command>scons -Q debug=0</command> - <command>scons -Q debug=0</command> - <command>scons -Q debug=1</command> - <command>scons -Q debug=1</command> + <scons_output_command>scons -Q debug=0</scons_output_command> + <scons_output_command>scons -Q debug=0</scons_output_command> + <scons_output_command>scons -Q debug=1</scons_output_command> + <scons_output_command>scons -Q debug=1</scons_output_command> </scons_output> <para> @@ -668,7 +668,7 @@ to pass the value to the C compiler. Here's how you might do that by setting the appropriate value in a dictionary for the - &CPPDEFINES; construction variable: + &cv-link-CPPDEFINES; construction variable: </para> @@ -718,7 +718,7 @@ </para> <scons_output example="Options1"> - <command>scons -Q RELEASE=1</command> + <scons_output_command>scons -Q RELEASE=1</scons_output_command> </scons_output> </section> @@ -763,7 +763,7 @@ </para> <scons_output example="Options_Help"> - <command>scons -Q -h</command> + <scons_output_command>scons -Q -h</scons_output_command> </scons_output> <para> @@ -835,7 +835,7 @@ </para> <scons_output example="Options_custom_py_1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -872,7 +872,7 @@ </para> <scons_output example="Options_custom_py_2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -940,11 +940,11 @@ </para> <scons_output example="BoolOption"> - <command>scons -Q RELEASE=yes foo.o</command> + <scons_output_command>scons -Q RELEASE=yes foo.o</scons_output_command> </scons_output> <scons_output example="BoolOption"> - <command>scons -Q RELEASE=t foo.o</command> + <scons_output_command>scons -Q RELEASE=t foo.o</scons_output_command> </scons_output> <para> @@ -969,11 +969,11 @@ </para> <scons_output example="BoolOption"> - <command>scons -Q RELEASE=no foo.o</command> + <scons_output_command>scons -Q RELEASE=no foo.o</scons_output_command> </scons_output> <scons_output example="BoolOption"> - <command>scons -Q RELEASE=f foo.o</command> + <scons_output_command>scons -Q RELEASE=f foo.o</scons_output_command> </scons_output> <para> @@ -996,7 +996,7 @@ </para> <scons_output example="BoolOption"> - <command>scons -Q RELEASE=bad_value foo.o</command> + <scons_output_command>scons -Q RELEASE=bad_value foo.o</scons_output_command> </scons_output> </section> @@ -1043,9 +1043,9 @@ </para> <scons_output example="EnumOption"> - <command>scons -Q COLOR=red foo.o</command> - <command>scons -Q COLOR=blue foo.o</command> - <command>scons -Q COLOR=green foo.o</command> + <scons_output_command>scons -Q COLOR=red foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=blue foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=green foo.o</scons_output_command> </scons_output> <para> @@ -1058,7 +1058,7 @@ </para> <scons_output example="EnumOption"> - <command>scons -Q COLOR=magenta foo.o</command> + <scons_output_command>scons -Q COLOR=magenta foo.o</scons_output_command> </scons_output> <para> @@ -1101,7 +1101,7 @@ </para> <scons_output example="EnumOption_map"> - <command>scons -Q COLOR=navy foo.o</command> + <scons_output_command>scons -Q COLOR=navy foo.o</scons_output_command> </scons_output> <para> @@ -1115,9 +1115,9 @@ </para> <scons_output example="EnumOption"> - <command>scons -Q COLOR=Red foo.o</command> - <command>scons -Q COLOR=BLUE foo.o</command> - <command>scons -Q COLOR=nAvY foo.o</command> + <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=BLUE foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command> </scons_output> <para> @@ -1153,10 +1153,10 @@ </para> <scons_output example="EnumOption_ic1"> - <command>scons -Q COLOR=Red foo.o</command> - <command>scons -Q COLOR=BLUE foo.o</command> - <command>scons -Q COLOR=nAvY foo.o</command> - <command>scons -Q COLOR=green foo.o</command> + <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=BLUE foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=green foo.o</scons_output_command> </scons_output> <para> @@ -1198,9 +1198,9 @@ </para> <scons_output example="EnumOption_ic2"> - <command>scons -Q COLOR=Red foo.o</command> - <command>scons -Q COLOR=nAvY foo.o</command> - <command>scons -Q COLOR=GREEN foo.o</command> + <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command> + <scons_output_command>scons -Q COLOR=GREEN foo.o</scons_output_command> </scons_output> </section> @@ -1243,8 +1243,8 @@ </para> <scons_output example="ListOption"> - <command>scons -Q COLORS=red,blue foo.o</command> - <command>scons -Q COLORS=blue,green,red foo.o</command> + <scons_output_command>scons -Q COLORS=red,blue foo.o</scons_output_command> + <scons_output_command>scons -Q COLORS=blue,green,red foo.o</scons_output_command> </scons_output> <para> @@ -1258,8 +1258,8 @@ </para> <scons_output example="ListOption"> - <command>scons -Q COLORS=all foo.o</command> - <command>scons -Q COLORS=none foo.o</command> + <scons_output_command>scons -Q COLORS=all foo.o</scons_output_command> + <scons_output_command>scons -Q COLORS=none foo.o</scons_output_command> </scons_output> <para> @@ -1270,7 +1270,7 @@ </para> <scons_output example="ListOption"> - <command>scons -Q COLORS=magenta foo.o</command> + <scons_output_command>scons -Q COLORS=magenta foo.o</scons_output_command> </scons_output> </section> @@ -1320,8 +1320,8 @@ </para> <scons_output example="PathOption"> - <command>scons -Q foo.o</command> - <command>scons -Q CONFIG=__ROOT__/usr/local/etc/other_config foo.o</command> + <scons_output_command>scons -Q foo.o</scons_output_command> + <scons_output_command>scons -Q CONFIG=__ROOT__/usr/local/etc/other_config foo.o</scons_output_command> </scons_output> <para> @@ -1333,7 +1333,7 @@ </para> <scons_output example="PathOption"> - <command>scons -Q CONFIG=__ROOT__/does/not/exist foo.o</command> + <scons_output_command>scons -Q CONFIG=__ROOT__/does/not/exist foo.o</scons_output_command> </scons_output> <para> @@ -1500,10 +1500,10 @@ </para> <scons_output example="PackageOption"> - <command>scons -Q foo.o</command> - <command>scons -Q PACKAGE=__ROOT__/usr/local/location foo.o</command> - <command>scons -Q PACKAGE=yes foo.o</command> - <command>scons -Q PACKAGE=no foo.o</command> + <scons_output_command>scons -Q foo.o</scons_output_command> + <scons_output_command>scons -Q PACKAGE=__ROOT__/usr/local/location foo.o</scons_output_command> + <scons_output_command>scons -Q PACKAGE=yes foo.o</scons_output_command> + <scons_output_command>scons -Q PACKAGE=no foo.o</scons_output_command> </scons_output> </section> diff --git a/doc/user/command-line.sgml b/doc/user/command-line.sgml index 70658e0..565d9f8 100644 --- a/doc/user/command-line.sgml +++ b/doc/user/command-line.sgml @@ -568,7 +568,7 @@ <para> - The following code sets the &CCFLAGS; construction + The following code sets the &cv-link-CCFLAGS; construction variable in response to the <varname>debug</varname> flag being set in the &ARGUMENTS; dictionary: @@ -650,7 +650,7 @@ to pass the value to the C compiler. Here's how you might do that by setting the appropriate value in a dictionary for the - &CPPDEFINES; construction variable: + &cv-link-CPPDEFINES; construction variable: </para> diff --git a/doc/user/depends.in b/doc/user/depends.in index ab422b6..0262924 100644 --- a/doc/user/depends.in +++ b/doc/user/depends.in @@ -67,8 +67,8 @@ operating system on which the build is performed (as reported by C<uname </scons_example> <scons_output example="ex1" os="posix"> - <command>scons -Q</command> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -83,8 +83,8 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1" os="posix"> - <command>scons -Q hello</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -132,9 +132,9 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1" os="posix"> - <command>scons -Q hello</command> - <command>touch hello.c</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>touch hello.c</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -154,9 +154,9 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1" os="posix"> - <command>scons -Q hello</command> - <command output=" [CHANGE THE CONTENTS OF hello.c]">edit hello.c</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.c]">edit hello.c</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -209,9 +209,9 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex2" os="posix"> - <command>scons -Q hello</command> - <command>touch hello.c</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>touch hello.c</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> </section> @@ -252,9 +252,9 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1" os="posix"> - <command>scons -Q hello</command> - <command output=" [CHANGE THE CONTENTS OF hello.c]">edit hello.c</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.c]">edit hello.c</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -339,9 +339,9 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex3" os="posix"> - <command>scons -Q hello</command> - <command output=" [CHANGE A COMMENT IN hello.c]" edit="STRIP CCCOM line">edit hello.c</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command output=" [CHANGE A COMMENT IN hello.c]" edit="STRIP CCCOM line">edit hello.c</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -364,7 +364,7 @@ operating system on which the build is performed (as reported by C<uname </section> <section> - <title>Implicit Dependencies: The &CPPPATH; Construction Variable</title> + <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> <para> @@ -415,7 +415,7 @@ operating system on which the build is performed (as reported by C<uname <para> - The &CPPPATH; value + The &cv-CPPPATH; value tells &SCons; to look in the current directory (<literal>'.'</literal>) for any files included by C source files @@ -425,17 +425,17 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex4" os="posix"> - <command>scons -Q hello</command> - <command>scons -Q hello</command> - <command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> First, notice that &SCons; added the <literal>-I.</literal> argument - from the &CPPPATH; variable + from the &cv-CPPPATH; variable so that the compilation would find the &hello_h; file in the local directory. @@ -462,8 +462,8 @@ operating system on which the build is performed (as reported by C<uname <para> - Like the &LIBPATH; variable, - the &CPPPATH; variable + Like the &cv-LIBPATH; variable, + the &cv-CPPPATH; variable may be a list of directories, or a string separated by the system-specific path separate character @@ -490,7 +490,7 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex5" os="posix"> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -500,7 +500,7 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex5" os="win32"> - <command>scons -Q hello.exe</command> + <scons_output_command>scons -Q hello.exe</scons_output_command> </scons_output> </section> @@ -554,8 +554,8 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1"> - <command>scons -Q --implicit-cache hello</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q --implicit-cache hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -610,8 +610,8 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1"> - <command>scons -Q --implicit-deps-changed hello</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q --implicit-deps-changed hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -645,8 +645,8 @@ operating system on which the build is performed (as reported by C<uname </para> <scons_output example="ex1"> - <command>scons -Q --implicit-deps-unchanged hello</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q --implicit-deps-unchanged hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> </scons_output> <para> @@ -699,10 +699,10 @@ operating system on which the build is performed (as reported by C<uname <!-- <scons_output example="ignore"> - <command>scons -Q hello</command> - <command>scons -Q hello</command> - <command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> XXX THIS EXAMPLE SHOULD BE UP-TO-DATE! XXX </scons_output> --> diff --git a/doc/user/depends.sgml b/doc/user/depends.sgml index b372885..3d74025 100644 --- a/doc/user/depends.sgml +++ b/doc/user/depends.sgml @@ -375,7 +375,7 @@ operating system on which the build is performed (as reported by C<uname </section> <section> - <title>Implicit Dependencies: The &CPPPATH; Construction Variable</title> + <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> <para> @@ -422,7 +422,7 @@ operating system on which the build is performed (as reported by C<uname <para> - The &CPPPATH; value + The &cv-CPPPATH; value tells &SCons; to look in the current directory (<literal>'.'</literal>) for any files included by C source files @@ -448,7 +448,7 @@ operating system on which the build is performed (as reported by C<uname First, notice that &SCons; added the <literal>-I.</literal> argument - from the &CPPPATH; variable + from the &cv-CPPPATH; variable so that the compilation would find the &hello_h; file in the local directory. @@ -475,8 +475,8 @@ operating system on which the build is performed (as reported by C<uname <para> - Like the &LIBPATH; variable, - the &CPPPATH; variable + Like the &cv-LIBPATH; variable, + the &cv-CPPPATH; variable may be a list of directories, or a string separated by the system-specific path separate character @@ -711,10 +711,10 @@ operating system on which the build is performed (as reported by C<uname <!-- <scons_output example="ignore"> - <command>scons -Q hello</command> - <command>scons -Q hello</command> - <command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command> - <command>scons -Q hello</command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> XXX THIS EXAMPLE SHOULD BE UP-TO-DATE! XXX </scons_output> --> diff --git a/doc/user/environments.in b/doc/user/environments.in index 47a3c44..586242c 100644 --- a/doc/user/environments.in +++ b/doc/user/environments.in @@ -468,7 +468,8 @@ environment undisturbed. and further specifies that the <literal>-O2</literal> (optimization level two) flag should be used when compiling the object file. - In other words, the explicit initializations of &CC; and &CCFLAGS; + In other words, the explicit initializations of + &cv-link-CC; and &cv-link-CCFLAGS; override the default values in the newly-created construction environment. So a run from this example would look like: @@ -476,7 +477,7 @@ environment undisturbed. </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <section> @@ -514,7 +515,7 @@ environment undisturbed. </scons_example> <scons_output example="ex2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -522,7 +523,7 @@ environment undisturbed. We can even use multiple construction environments to build multiple versions of a single program. If you do this by simply trying to use the - &Program; builder with both environments, though, + &b-link-Program; builder with both environments, though, like this: </para> @@ -548,17 +549,17 @@ environment undisturbed. </para> <scons_output example="ex3"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> - This is because the two &Program; calls have + This is because the two &b-Program; calls have each implicitly told &SCons; to generate an object file named <filename>foo.o</filename>, - one with a &CCFLAGS; value of + one with a &cv-link-CCFLAGS; value of <literal>-O2</literal> - and one with a &CCFLAGS; value of + and one with a &cv-link-CCFLAGS; value of <literal>-g</literal>. &SCons; can't just decide that one of them should take precedence over the other, @@ -568,7 +569,7 @@ environment undisturbed. that each environment compile <filename>foo.c</filename> to a separately-named object file - using the &Object; call, like so: + using the &b-link-Object; builder, like so: </para> @@ -590,12 +591,12 @@ environment undisturbed. <para> - Notice that each call to the &Object; builder + Notice that each call to the &b-Object; builder returns a value, an internal &SCons; object that represents the object file that will be built. We then use that object - as input to the &Program; builder. + as input to the &b-Program; builder. This avoids having to specify explicitly the object file name in multiple places, and makes for a compact, readable @@ -605,7 +606,7 @@ environment undisturbed. </para> <scons_output example="ex4"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -633,10 +634,10 @@ environment undisturbed. to create three versions of a program, one optimized, one debug, and one with neither. We could do this by creating a "base" construction environment - that sets &CC; to &gcc;, + that sets &cv-link-CC; to &gcc;, and then creating two copies, - one which sets &CCFLAGS; for optimization - and the other which sets &CCFLAGS; for debugging: + one which sets &cv-link-CCFLAGS; for optimization + and the other which sets &cv-CCFLAGS; for debugging: </para> @@ -666,7 +667,7 @@ environment undisturbed. </para> <scons_output example="ex5"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -693,12 +694,12 @@ environment undisturbed. This example &SConstruct; file doesn't build anything, but because it's actually a Python script, - it will print the value of &CC; for us: + it will print the value of &cv-link-CC; for us: </para> <scons_output example="ex6"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -729,7 +730,7 @@ environment undisturbed. </para> <scons_output example="ex6b" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -739,7 +740,7 @@ environment undisturbed. </para> <scons_output example="ex6b" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -775,7 +776,7 @@ environment undisturbed. the example from the previous section that used <literal>env['CC']</literal> - to fetch the value of &CC; + to fetch the value of &cv-link-CC; could also be written as: </para> @@ -794,7 +795,7 @@ environment undisturbed. re-expanded until there are no expansions left in the string. So a simple fetch of a value like - <varname>$CCCOM</varname>: + &cv-link-CCCOM;: </para> @@ -805,7 +806,7 @@ environment undisturbed. <para> - Will print the unexpanded value of &CCCOM;, + Will print the unexpanded value of &cv-CCCOM;, showing us the construction variables that still need to be expanded: @@ -848,7 +849,7 @@ environment undisturbed. (Note that because we're not expanding this in the context of building something there are no target or source files - for <varname>$TARGET</varname> and <varname>$SOURCES</varname> to expand. + for &cv-link-TARGET; and &cv-link-SOURCES; to expand. </para> @@ -895,7 +896,7 @@ environment undisturbed. </para> <scons_output example="Replace1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -923,7 +924,7 @@ environment undisturbed. </para> <scons_output example="Replace-nonexistent"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -972,14 +973,14 @@ environment undisturbed. </para> <scons_output example="Replace2"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> Because the replacement occurs while the &SConscript; files are being read, - the <literal>$CCFLAGS</literal> + the &cv-link-CCFLAGS; variable has already been set to <literal>-DDEFINE2</literal> by the time the &foo_o; target is built, @@ -1021,7 +1022,7 @@ environment undisturbed. </para> <scons_output example="ex8"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -1046,7 +1047,7 @@ environment undisturbed. </para> <scons_output example="Append-nonexistent"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -1081,7 +1082,7 @@ environment undisturbed. </para> <scons_output example="ex9"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -1106,7 +1107,7 @@ environment undisturbed. </para> <scons_output example="Prepend-nonexistent"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml index 1ff2fb3..14be5af 100644 --- a/doc/user/environments.sgml +++ b/doc/user/environments.sgml @@ -463,7 +463,8 @@ environment undisturbed. and further specifies that the <literal>-O2</literal> (optimization level two) flag should be used when compiling the object file. - In other words, the explicit initializations of &CC; and &CCFLAGS; + In other words, the explicit initializations of + &cv-link-CC; and &cv-link-CCFLAGS; override the default values in the newly-created construction environment. So a run from this example would look like: @@ -515,7 +516,7 @@ environment undisturbed. We can even use multiple construction environments to build multiple versions of a single program. If you do this by simply trying to use the - &Program; builder with both environments, though, + &b-link-Program; builder with both environments, though, like this: </para> @@ -544,12 +545,12 @@ environment undisturbed. <para> - This is because the two &Program; calls have + This is because the two &b-Program; calls have each implicitly told &SCons; to generate an object file named <filename>foo.o</filename>, - one with a &CCFLAGS; value of + one with a &cv-link-CCFLAGS; value of <literal>-O2</literal> - and one with a &CCFLAGS; value of + and one with a &cv-link-CCFLAGS; value of <literal>-g</literal>. &SCons; can't just decide that one of them should take precedence over the other, @@ -559,7 +560,7 @@ environment undisturbed. that each environment compile <filename>foo.c</filename> to a separately-named object file - using the &Object; call, like so: + using the &b-link-Object; builder, like so: </para> @@ -576,12 +577,12 @@ environment undisturbed. <para> - Notice that each call to the &Object; builder + Notice that each call to the &b-Object; builder returns a value, an internal &SCons; object that represents the object file that will be built. We then use that object - as input to the &Program; builder. + as input to the &b-Program; builder. This avoids having to specify explicitly the object file name in multiple places, and makes for a compact, readable @@ -623,10 +624,10 @@ environment undisturbed. to create three versions of a program, one optimized, one debug, and one with neither. We could do this by creating a "base" construction environment - that sets &CC; to &gcc;, + that sets &cv-link-CC; to &gcc;, and then creating two copies, - one which sets &CCFLAGS; for optimization - and the other which sets &CCFLAGS; for debugging: + one which sets &cv-link-CCFLAGS; for optimization + and the other which sets &cv-CCFLAGS; for debugging: </para> @@ -682,7 +683,7 @@ environment undisturbed. This example &SConstruct; file doesn't build anything, but because it's actually a Python script, - it will print the value of &CC; for us: + it will print the value of &cv-link-CC; for us: </para> @@ -772,7 +773,7 @@ environment undisturbed. the example from the previous section that used <literal>env['CC']</literal> - to fetch the value of &CC; + to fetch the value of &cv-link-CC; could also be written as: </para> @@ -791,7 +792,7 @@ environment undisturbed. re-expanded until there are no expansions left in the string. So a simple fetch of a value like - <varname>$CCCOM</varname>: + &cv-link-CCCOM;: </para> @@ -802,7 +803,7 @@ environment undisturbed. <para> - Will print the unexpanded value of &CCCOM;, + Will print the unexpanded value of &cv-CCCOM;, showing us the construction variables that still need to be expanded: @@ -845,7 +846,7 @@ environment undisturbed. (Note that because we're not expanding this in the context of building something there are no target or source files - for <varname>$TARGET</varname> and <varname>$SOURCES</varname> to expand. + for &cv-link-TARGET; and &cv-link-SOURCES; to expand. </para> @@ -975,7 +976,7 @@ environment undisturbed. Because the replacement occurs while the &SConscript; files are being read, - the <literal>$CCFLAGS</literal> + the &cv-link-CCFLAGS; variable has already been set to <literal>-DDEFINE2</literal> by the time the &foo_o; target is built, diff --git a/doc/user/factories.in b/doc/user/factories.in new file mode 100644 index 0000000..95145d8 --- /dev/null +++ b/doc/user/factories.in @@ -0,0 +1,470 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + + &SCons; provides a number of platform-independent functions, + called <literal>factories</literal>, + that perform common file system manipulations + like copying, moving or deleting files and directories, + or making directories. + These functions are <literal>factories</literal> + because they don't perform the action + at the time they're called, + they each return an &Action; object + that can be executed at the appropriate time. + + </para> + + <section> + <title>Copying Files or Directories: The &Copy; Factory</title> + + <para> + + Suppose you want to arrange to make a copy of a file, + and the &Install; builder isn't appropriate + because it may make a hard link on POSIX systems. + One way would be to use the &Copy; action factory + in conjunction with the &Command; builder: + + </para> + + <scons_example name="Copy1"> + <file name="SConstruct" printme="1"> + Command("file.out", "file.in", Copy("$TARGET", "$SOURCE")) + </file> + <file name="file.in">file.in</file> + </scons_example> + + <para> + + Notice that the action returned by the &Copy; factory + will expand the &cv-TARGET; and &cv-SOURCE; strings + at the time &file_out; is built, + and that the order of the arguments + is the same as that of a builder itself--that is, + target first, followed by source: + + </para> + + <scons_output example="Copy1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <para> + + You can, of course, name a file explicitly + instead of using &cv-TARGET; or &cv-SOURCE;: + + </para> + + <scons_example name="Copy2"> + <file name="SConstruct" printme="1"> + Command("file.out", [], Copy("$TARGET", "file.in")) + </file> + <file name="file.in">file.in</file> + </scons_example> + + <para> + + Which executes as: + + </para> + + <scons_output example="Copy2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <para> + + The usefulness of the &Copy; factory + becomes more apparent when + you use it in a list of actions + passed to the &Command; builder. + For example, suppose you needed to run a + file through a utility that only modifies files in-place, + and can't "pipe" input to output. + One solution is to copy the source file + to a temporary file name, + run the utility, + and then copy the modified temporary file to the target, + which the &Copy; factory makes extremely easy: + + </para> + + <scons_example name="Copy3"> + <file name="S" printme="1"> + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Copy("$TARGET", "tempfile"), + ]) + </file> + <file name="SConstruct"> + env = DefaultEnvironment() + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() + SConscript('S') + </file> + <file name="file.in">file.in</file> + <file name="modify" chmod="0755"> + touch $* + </file> + </scons_example> + + <para> + + The output then looks like: + + </para> + + <scons_output example="Copy3"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + </section> + + <section> + <title>Deleting Files or Directories: The &Delete; Factory</title> + + <para> + + If you need to delete a file, + then the &Delete; factory + can be used in much the same way as + the &Copy; factory. + For example, if we want to make sure that + the temporary file + in our last example doesn't exist before + we copy to it, + we could add &Delete; to the beginning + of the command list: + + </para> + + <scons_example name="Delete1"> + <file name="S" printme="1"> + Command("file.out", "file.in", + [ + Delete("tempfile"), + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Copy("$TARGET", "tempfile"), + ]) + </file> + <file name="SConstruct"> + env = DefaultEnvironment() + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() + SConscript('S') + </file> + <file name="file.in">file.in</file> + <file name="modify" chmod="0755"> + touch $* + </file> + </scons_example> + + <para> + + When then executes as follows: + + </para> + + <scons_output example="Delete1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <para> + + Of course, like all of these &Action; factories, + the &Delete factory also expands + &cv-TARGET; and &cv-SOURCE; variables appropriately. + For example: + + </para> + + <scons_example name="Delete2"> + <file name="SConstruct" printme="1"> + Command("file.out", "file.in", + [ + Delete("$TARGET"), + Copy("$TARGET", "$SOURCE") + ]) + </file> + <file name="file.in">file.in</file> + </scons_example> + + <para> + + Executes as: + + </para> + + <scons_output example="Delete2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <para> + + (Note, however, that you typically don't need to + call the &Delete; factory explicitly in this way; + by default, &SCons; deletes its target(s) + for you before executing any action. + + </para> + + </section> + + <section> + <title>Moving (Renaming) Files or Directories: The &Move; Factory</title> + + <para> + + The &Move; factory + allows you to rename a file or directory. + For example, if we don't want to copy the temporary file, + we could: + + </para> + + <scons_example name="Move"> + <file name="S" printme="1"> + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Move("$TARGET", "tempfile"), + ]) + </file> + <file name="SConstruct"> + env = DefaultEnvironment() + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() + SConscript('S') + </file> + <file name="file.in">file.in</file> + <file name="modify" chmod="0755"> + touch $* + </file> + </scons_example> + + <para> + + Which would execute as: + + </para> + + <scons_output example="Move"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + </section> + + <section> + <title>Updating the Modification Time of a File: The &Touch; Factory</title> + + <para> + + If you just need to update the + recorded modification time for a file, + use the &Touch; factory: + + </para> + + <scons_example name="Touch"> + <file name="S" printme="1"> + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Move("$TARGET", "tempfile"), + ]) + </file> + <file name="SConstruct"> + env = DefaultEnvironment() + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() + SConscript('S') + </file> + <file name="file.in">file.in</file> + <file name="modify" chmod="0755"> + touch $* + </file> + </scons_example> + + <para> + + Which executes as: + + </para> + + <scons_output example="Touch"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + </section> + + <section> + <title>Creating a Directory: The &Mkdir; Factory</title> + + <para> + + If you need to create a directory, + use the &Mkdir; factory. + For example, if we need to process + a file in a temporary directory + in which the processing tool + will create other files that we don't care about, + you could: + + </para> + + <scons_example name="Mkdir"> + <file name="S" printme="1"> + Command("file.out", "file.in", + [ + Delete("tempdir"), + Mkdir("tempdir"), + Copy("tempdir/${SOURCE.file}", "$SOURCE"), + "process tempdir", + Move("$TARGET", "tempdir/output_file"), + Delete("tempdir"), + ]) + </file> + <file name="SConstruct"> + env = DefaultEnvironment() + import os + env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() + SConscript('S') + </file> + <file name="file.in">file.in</file> + <file name="process" chmod="0755"> + touch $* + </file> + </scons_example> + + <para> + + Which executes as: + + </para> + + <scons_output example="Mkdir"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + </section> + + <section> + <title>Changing File or Directory Permissions: The &Chmod; Factory</title> + + <para> + + To change permissions on a file or directory, + use the &Chmod; factory. + The permission argument uses POSIX-style + permission bits and should typically + be expressed as an octal, + not decimal, number: + + </para> + + <scons_example name="Chmod"> + <file name="SConstruct" printme="1"> + Command("file.out", "file.in", + [ + Copy("$TARGET", "$SOURCE"), + Chmod("$TARGET", 0755), + ]) + </file> + <file name="file.in">file.in</file> + </scons_example> + + <para> + + Which executes: + + </para> + + <scons_output example="Chmod"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + </section> + + <section> + <title>Executing an action immediately: the &Execute; Function</title> + + <para> + + We've been showing you how to use &Action; factories + in the &Command; function. + You can also execute an &Action; returned by a factory + (or actually, any &Action;) + at the time the &SConscript; file is read + by wrapping it up in the &Execute; function. + For example, if we need to make sure that + a directory exists before we build any targets, + + + </para> + + <scons_example name="Execute"> + <file name="SConstruct" printme="1"> + Execute(Mkdir('__ROOT__/tmp/my_temp_directory')) + </file> + </scons_example> + + <para> + + Notice that this will + create the directory while + the &SConscript; file is being read: + + </para> + + <scons_output example="Execute"> + <scons_output_command>scons</scons_output_command> + </scons_output> + + <para> + + If you're familiar with Python, + you may wonder why you would want to use this + instead of just calling the native Python + <function>os.mkdir()</function> function. + The advantage here is that the &Mkdir; + action will behave appropriately if the user + specifies the &SCons; <option>-n</option> or + <option>-q</option> options--that is, + it will print the action but not actually + make the directory when <option>-n</option> is specified, + or make the directory but not print the action + when <option>-q</option> is specified. + + </para> + + </section> diff --git a/doc/user/factories.sgml b/doc/user/factories.sgml new file mode 100644 index 0000000..b145ff2 --- /dev/null +++ b/doc/user/factories.sgml @@ -0,0 +1,427 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + + &SCons; provides a number of platform-independent functions, + called <literal>factories</literal>, + that perform common file system manipulations + like copying, moving or deleting files and directories, + or making directories. + These functions are <literal>factories</literal> + because they don't perform the action + at the time they're called, + they each return an &Action; object + that can be executed at the appropriate time. + + </para> + + <section> + <title>Copying Files or Directories: The &Copy; Factory</title> + + <para> + + Suppose you want to arrange to make a copy of a file, + and the &Install; builder isn't appropriate + because it may make a hard link on POSIX systems. + One way would be to use the &Copy; action factory + in conjunction with the &Command; builder: + + </para> + + <programlisting> + Command("file.out", "file.in", Copy("$TARGET", "$SOURCE")) + </programlisting> + + <para> + + Notice that the action returned by the &Copy; factory + will expand the &cv-TARGET; and &cv-SOURCE; strings + at the time &file_out; is built, + and that the order of the arguments + is the same as that of a builder itself--that is, + target first, followed by source: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Copy("file.out", "file.in") + </screen> + + <para> + + You can, of course, name a file explicitly + instead of using &cv-TARGET; or &cv-SOURCE;: + + </para> + + <programlisting> + Command("file.out", [], Copy("$TARGET", "file.in")) + </programlisting> + + <para> + + Which executes as: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Copy("file.out", "file.in") + </screen> + + <para> + + The usefulness of the &Copy; factory + becomes more apparent when + you use it in a list of actions + passed to the &Command; builder. + For example, suppose you needed to run a + file through a utility that only modifies files in-place, + and can't "pipe" input to output. + One solution is to copy the source file + to a temporary file name, + run the utility, + and then copy the modified temporary file to the target, + which the &Copy; factory makes extremely easy: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Copy("$TARGET", "tempfile"), + ]) + </programlisting> + + <para> + + The output then looks like: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Copy("tempfile", "file.in") + modify tempfile + Copy("file.out", "tempfile") + </screen> + + </section> + + <section> + <title>Deleting Files or Directories: The &Delete; Factory</title> + + <para> + + If you need to delete a file, + then the &Delete; factory + can be used in much the same way as + the &Copy; factory. + For example, if we want to make sure that + the temporary file + in our last example doesn't exist before + we copy to it, + we could add &Delete; to the beginning + of the command list: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Delete("tempfile"), + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Copy("$TARGET", "tempfile"), + ]) + </programlisting> + + <para> + + When then executes as follows: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Delete("tempfile") + Copy("tempfile", "file.in") + modify tempfile + Copy("file.out", "tempfile") + </screen> + + <para> + + Of course, like all of these &Action; factories, + the &Delete; factory also expands + &cv-TARGET; and &cv-SOURCE; variables appropriately. + For example: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Delete("$TARGET"), + Copy("$TARGET", "$SOURCE") + ]) + </programlisting> + + <para> + + Executes as: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Delete("file.out") + Copy("file.out", "file.in") + </screen> + + <para> + + (Note, however, that you typically don't need to + call the &Delete; factory explicitly in this way; + by default, &SCons; deletes its target(s) + for you before executing any action. + + </para> + + </section> + + <section> + <title>Moving (Renaming) Files or Directories: The &Move; Factory</title> + + <para> + + The &Move; factory + allows you to rename a file or directory. + For example, if we don't want to copy the temporary file, + we could: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Move("$TARGET", "tempfile"), + ]) + </programlisting> + + <para> + + Which would execute as: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Copy("tempfile", "file.in") + modify tempfile + Move("file.out", "tempfile") + </screen> + + </section> + + <section> + <title>Updating the Modification Time of a File: The &Touch; Factory</title> + + <para> + + If you just need to update the + recorded modification time for a file, + use the &Touch; factory: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Copy("tempfile", "$SOURCE"), + "modify tempfile", + Move("$TARGET", "tempfile"), + ]) + </programlisting> + + <para> + + Which executes as: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Copy("tempfile", "file.in") + modify tempfile + Move("file.out", "tempfile") + </screen> + + </section> + + <section> + <title>Creating a Directory: The &Mkdir; Factory</title> + + <para> + + If you need to create a directory, + use the &Mkdir; factory. + For example, if we need to process + a file in a temporary directory + in which the processing tool + will create other files that we don't care about, + you could: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Delete("tempdir"), + Mkdir("tempdir"), + Copy("tempdir/${SOURCE.file}", "$SOURCE"), + "process tempdir", + Move("$TARGET", "tempdir/output_file"), + Delete("tempdir"), + ]) + </programlisting> + + <para> + + Which executes as: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Delete("tempdir") + Mkdir("tempdir") + Copy("tempdir/file.in", "file.in") + process tempdir + Move("file.out", "tempdir/output_file") + scons: *** [file.out] No such file or directory + </screen> + + </section> + + <section> + <title>Changing File or Directory Permissions: The &Chmod; Factory</title> + + <para> + + To change permissions on a file or directory, + use the &Chmod; factory. + The permission argument uses POSIX-style + permission bits and should typically + be expressed as an octal, + not decimal, number: + + </para> + + <programlisting> + Command("file.out", "file.in", + [ + Copy("$TARGET", "$SOURCE"), + Chmod("$TARGET", 0755), + ]) + </programlisting> + + <para> + + Which executes: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + Copy("file.out", "file.in") + Chmod("file.out", 0755) + </screen> + + </section> + + <section> + <title>Executing an action immediately: the &Execute; Function</title> + + <para> + + We've been showing you how to use &Action; factories + in the &Command; function. + You can also execute an &Action; returned by a factory + (or actually, any &Action;) + at the time the &SConscript; file is read + by wrapping it up in the &Execute; function. + For example, if we need to make sure that + a directory exists before we build any targets, + + + </para> + + <programlisting> + Execute(Mkdir('/tmp/my_temp_directory')) + </programlisting> + + <para> + + Notice that this will + create the directory while + the &SConscript; file is being read: + + </para> + + <screen> + % <userinput>scons</userinput> + scons: Reading SConscript files ... + Mkdir("/tmp/my_temp_directory") + scons: done reading SConscript files. + scons: Building targets ... + scons: `.' is up to date. + scons: done building targets. + </screen> + + <para> + + If you're familiar with Python, + you may wonder why you would want to use this + instead of just calling the native Python + <function>os.mkdir()</function> function. + The advantage here is that the &Mkdir; + action will behave appropriately if the user + specifies the &SCons; <option>-n</option> or + <option>-q</option> options--that is, + it will print the action but not actually + make the directory when <option>-n</option> is specified, + or make the directory but not print the action + when <option>-q</option> is specified. + + </para> + + </section> diff --git a/doc/user/help.in b/doc/user/help.in index d4b2caa..4356d18 100644 --- a/doc/user/help.in +++ b/doc/user/help.in @@ -61,7 +61,66 @@ </para> <scons_output example="ex1"> - <command>scons -h</command> + <scons_output_command>scons -h</scons_output_command> + </scons_output> + + <para> + + The &SConscript; files may contain + multiple calls to the &Help; function, + in which case the specified text(s) + will be concatenated when displayed. + This allows you to split up the + help text across multiple &SConscript; files. + In this situation, the order in + which the &SConscript; files are called + will determine the order in which the &Help; functions are called, + which will determine the order in which + the various bits of text will get concatenated. + + </para> + + <para> + + Another use would be to make the help text conditional + on some variable. + For example, suppose you only want to display + a line about building a Windows-only + version of a program when actually + run on Windows. + The following &SConstruct; file: + + </para> + + <scons_example name="ex2"> + <file name="SConstruct" printme="1"> + env = Environment() + + Help("\nType: 'scons program' to build the production program.\n") + + if env['PLATFORM'] == 'win32': + Help("\nType: 'scons windebug' to build the Windows debug version.\n") + </file> + </scons_example> + + <para> + + Will display the completely help text on Windows: + + </para> + + <scons_output example="ex2" os="win32"> + <scons_output_command>scons -h</scons_output_command> + </scons_output> + + <para> + + But only show the relevant option on a Linux or UNIX system: + + </para> + + <scons_output example="ex2" os="posix"> + <scons_output_command>scons -h</scons_output_command> </scons_output> <para> diff --git a/doc/user/help.sgml b/doc/user/help.sgml index 9db5bf0..ca44a40 100644 --- a/doc/user/help.sgml +++ b/doc/user/help.sgml @@ -71,6 +71,77 @@ <para> + The &SConscript; files may contain + multiple calls to the &Help; function, + in which case the specified text(s) + will be concatenated when displayed. + This allows you to split up the + help text across multiple &SConscript; files. + In this situation, the order in + which the &SConscript; files are called + will determine the order in which the &Help; functions are called, + which will determine the order in which + the various bits of text will get concatenated. + + </para> + + <para> + + Another use would be to make the help text conditional + on some variable. + For example, suppose you only want to display + a line about building a Windows-only + version of a program when actually + run on Windows. + The following &SConstruct; file: + + </para> + + <programlisting> + env = Environment() + + Help("\nType: 'scons program' to build the production program.\n") + + if env['PLATFORM'] == 'win32': + Help("\nType: 'scons windebug' to build the Windows debug version.\n") + </programlisting> + + <para> + + Will display the completely help text on Windows: + + </para> + + <screen> + C:\><userinput>scons -h</userinput> + scons: Reading SConscript files ... + scons: done reading SConscript files. + + Type: 'scons program' to build the production program. + + Type: 'scons windebug' to build the Windows debug version. + + Use scons -H for help about command-line options. + </screen> + + <para> + + But only show the relevant option on a Linux or UNIX system: + + </para> + + <screen> + % <userinput>scons -h</userinput> + scons: Reading SConscript files ... + scons: done reading SConscript files. + + Type: 'scons program' to build the production program. + + Use scons -H for help about command-line options. + </screen> + + <para> + If there is no &Help; text in the &SConstruct; or &SConscript; files, &SCons; will revert to displaying its diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in index 0c4563d..355aca3 100644 --- a/doc/user/hierarchy.in +++ b/doc/user/hierarchy.in @@ -340,7 +340,7 @@ make no difference to the build. </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -411,7 +411,7 @@ make no difference to the build. </para> <scons_output example="ex2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -462,7 +462,7 @@ make no difference to the build. </para> <scons_output example="ex3"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -767,7 +767,7 @@ make no difference to the build. </para> <scons_output example="Return"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/install.in b/doc/user/install.in index dfbb822..ac9510f 100644 --- a/doc/user/install.in +++ b/doc/user/install.in @@ -62,8 +62,8 @@ </para> <scons_output example="ex1"> - <command>scons -Q</command> - <command>scons -Q __ROOT__/usr/bin</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q __ROOT__/usr/bin</scons_output_command> </scons_output> <para> @@ -101,8 +101,8 @@ </para> <scons_output example="ex2"> - <command>scons -Q</command> - <command>scons -Q install</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q install</scons_output_command> </scons_output> <section> @@ -155,7 +155,7 @@ </para> <scons_output example="ex3"> - <command>scons -Q install</command> + <scons_output_command>scons -Q install</scons_output_command> </scons_output> </section> @@ -194,7 +194,7 @@ </para> <scons_output example="ex4"> - <command>scons -Q install</command> + <scons_output_command>scons -Q install</scons_output_command> </scons_output> </section> @@ -241,7 +241,7 @@ </para> <scons_output example="ex5"> - <command>scons -Q install</command> + <scons_output_command>scons -Q install</scons_output_command> </scons_output> </section> diff --git a/doc/user/java.in b/doc/user/java.in index 66b9c86..9768dab 100644 --- a/doc/user/java.in +++ b/doc/user/java.in @@ -38,7 +38,7 @@ </para> <section> - <title>Building Java Class Files: the &Java; Builder</title> + <title>Building Java Class Files: the &b-Java; Builder</title> <para> @@ -49,7 +49,7 @@ to turn them into one or more <filename>.class</filename> files. In &SCons;, you do this - by giving the &Java; Builder + by giving the &b-link-Java; Builder a target directory in which to put the <filename>.class</filename> files, and a source directory that contains @@ -99,7 +99,7 @@ </para> <scons_output example="java"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -191,8 +191,8 @@ </para> <scons_output example="java-classes"> - <command>scons -Q</command> - <command>scons -Q classes</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q classes</scons_output_command> </scons_output> <para> @@ -215,25 +215,25 @@ </para> <scons_output example="java-classes"> - <command>scons -Q</command> - <command>scons -Q -c classes</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c classes</scons_output_command> </scons_output> </section> <section> - <title>Building Java Archive (<filename>.jar</filename>) Files: the &Jar; Builder</title> + <title>Building Java Archive (<filename>.jar</filename>) Files: the &b-Jar; Builder</title> <para> After building the class files, it's common to collect them into a Java archive (<filename>.jar</filename>) file, - which you do by calling the &Jar; Builder method. + which you do by calling the &b-link-Jar; Builder method. If you want to just collect all of the class files within a subdirectory, you can just specify that subdirectory - as the &Jar; source: + as the &b-Jar; source: </para> @@ -281,7 +281,7 @@ </para> <scons_output example="jar1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -291,13 +291,13 @@ for multiple programs in one location, and only archive some of them in each <filename>.jar</filename> file, - you can pass the &Jar; builder a + you can pass the &b-Jar; builder a list of files as its source. It's extremely simple to create multiple <filename>.jar</filename> files this way, using the lists of target class files created - by calls to the &Java; builder - as sources to the various &Jar; calls: + by calls to the &b-link-Java; builder + as sources to the various &b-Jar; calls: </para> @@ -357,19 +357,19 @@ </para> <scons_output example="jar2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> <section> - <title>Building C Header and Stub Files: the &JavaH; Builder</title> + <title>Building C Header and Stub Files: the &b-JavaH; Builder</title> <para> You can generate C header and source files for implementing native methods, - by using the &JavaH; Builder. + by using the &b-link-JavaH; Builder. There are several ways of using the &JavaH Builder. One typical invocation might look like: @@ -412,7 +412,7 @@ <para> The source is a list of class files generated by the - call to the &Java; Builder, + call to the &b-link-Java; Builder, and the target is the output directory in which we want the C header files placed. The target @@ -422,7 +422,7 @@ </para> <scons_output example="javah"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -447,15 +447,15 @@ Although it's more convenient to use the list of class files returned by - the &Java; Builder - as the source of a call to the &JavaH; Builder, + the &b-Java; Builder + as the source of a call to the &b-JavaH; Builder, you <emphasis>can</emphasis> specify the list of class files by hand, if you prefer. If you do, you need to set the - &JAVACLASSDIR; construction variable - when calling &JavaH;: + &cv-link-JAVACLASSDIR; construction variable + when calling &b-JavaH;: </para> @@ -498,14 +498,14 @@ <para> - The &JAVACLASSDIR; value then + The &cv-JAVACLASSDIR; value then gets converted into the <option>-classpath</option> when &SCons; runs &javah;: </para> <scons_output example="JAVACLASSDIR"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -513,7 +513,7 @@ Lastly, if you don't want a separate header file generated for each source file, you can specify an explicit File Node - as the target of the &JavaH; Builder: + as the target of the &b-JavaH; Builder: </para> @@ -554,7 +554,7 @@ <para> Because &SCons; assumes by default - that the target of the &JavaH; builder is a directory, + that the target of the &b-JavaH; builder is a directory, you need to use the &File; function to make sure that &SCons; doesn't create a directory named <filename>native.h</filename>. @@ -565,20 +565,20 @@ </para> <scons_output example="javah_file"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> <section> - <title>Building RMI Stub and Skeleton Class Files: the &RMIC; Builder</title> + <title>Building RMI Stub and Skeleton Class Files: the &b-RMIC; Builder</title> <para> You can generate Remote Method Invocation stubs - by using the &RMIC; Builder. + by using the &b-link-RMIC; Builder. The source is a list of directories, - typically returned by a call to the &Java; Builder, + typically returned by a call to the &b-link-Java; Builder, and the target is an output directory where the <filename>_Stub.class</filename> and <filename>_Skel.class</filename> files will @@ -613,7 +613,7 @@ <para> - As it did with the &JavaH; Builder, + As it did with the &b-link-JavaH; Builder, &SCons; remembers the class directory and passes it as the <option>-classpath</option> option to &rmic: @@ -621,7 +621,7 @@ </para> <scons_output example="RMIC"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> diff --git a/doc/user/java.sgml b/doc/user/java.sgml index e3eee53..1876916 100644 --- a/doc/user/java.sgml +++ b/doc/user/java.sgml @@ -38,7 +38,7 @@ </para> <section> - <title>Building Java Class Files: the &Java; Builder</title> + <title>Building Java Class Files: the &b-Java; Builder</title> <para> @@ -49,7 +49,7 @@ to turn them into one or more <filename>.class</filename> files. In &SCons;, you do this - by giving the &Java; Builder + by giving the &b-link-Java; Builder a target directory in which to put the <filename>.class</filename> files, and a source directory that contains @@ -158,18 +158,18 @@ </section> <section> - <title>Building Java Archive (<filename>.jar</filename>) Files: the &Jar; Builder</title> + <title>Building Java Archive (<filename>.jar</filename>) Files: the &b-Jar; Builder</title> <para> After building the class files, it's common to collect them into a Java archive (<filename>.jar</filename>) file, - which you do by calling the &Jar; Builder method. + which you do by calling the &b-link-Jar; Builder method. If you want to just collect all of the class files within a subdirectory, you can just specify that subdirectory - as the &Jar; source: + as the &b-Jar; source: </para> @@ -200,13 +200,13 @@ for multiple programs in one location, and only archive some of them in each <filename>.jar</filename> file, - you can pass the &Jar; builder a + you can pass the &b-Jar; builder a list of files as its source. It's extremely simple to create multiple <filename>.jar</filename> files this way, using the lists of target class files created - by calls to the &Java; builder - as sources to the various &Jar; calls: + by calls to the &b-link-Java; builder + as sources to the various &b-Jar; calls: </para> @@ -238,13 +238,13 @@ </section> <section> - <title>Building C Header and Stub Files: the &JavaH; Builder</title> + <title>Building C Header and Stub Files: the &b-JavaH; Builder</title> <para> You can generate C header and source files for implementing native methods, - by using the &JavaH; Builder. + by using the &b-link-JavaH; Builder. There are several ways of using the &JavaH; Builder. One typical invocation might look like: @@ -258,7 +258,7 @@ <para> The source is a list of class files generated by the - call to the &Java; Builder, + call to the &b-link-Java; Builder, and the target is the output directory in which we want the C header files placed. The target @@ -295,15 +295,15 @@ Although it's more convenient to use the list of class files returned by - the &Java; Builder - as the source of a call to the &JavaH; Builder, + the &b-Java; Builder + as the source of a call to the &b-JavaH; Builder, you <emphasis>can</emphasis> specify the list of class files by hand, if you prefer. If you do, you need to set the - &JAVACLASSDIR; construction variable - when calling &JavaH;: + &cv-link-JAVACLASSDIR; construction variable + when calling &b-JavaH;: </para> @@ -317,7 +317,7 @@ <para> - The &JAVACLASSDIR; value then + The &cv-JAVACLASSDIR; value then gets converted into the <option>-classpath</option> when &SCons; runs &javah;: @@ -334,7 +334,7 @@ Lastly, if you don't want a separate header file generated for each source file, you can specify an explicit File Node - as the target of the &JavaH; Builder: + as the target of the &b-JavaH; Builder: </para> @@ -346,7 +346,7 @@ <para> Because &SCons; assumes by default - that the target of the &JavaH; builder is a directory, + that the target of the &b-JavaH; builder is a directory, you need to use the &File; function to make sure that &SCons; doesn't create a directory named <filename>native.h</filename>. @@ -365,14 +365,14 @@ </section> <section> - <title>Building RMI Stub and Skeleton Class Files: the &RMIC; Builder</title> + <title>Building RMI Stub and Skeleton Class Files: the &b-RMIC; Builder</title> <para> You can generate Remote Method Invocation stubs - by using the &RMIC; Builder. + by using the &b-link-RMIC; Builder. The source is a list of directories, - typically returned by a call to the &Java; Builder, + typically returned by a call to the &b-link-Java; Builder, and the target is an output directory where the <filename>_Stub.class</filename> and <filename>_Skel.class</filename> files will @@ -387,7 +387,7 @@ <para> - As it did with the &JavaH; Builder, + As it did with the &b-link-JavaH; Builder, &SCons; remembers the class directory and passes it as the <option>-classpath</option> option to &rmic;: diff --git a/doc/user/less-simple.in b/doc/user/less-simple.in index c0dafb1..ccc59b6 100644 --- a/doc/user/less-simple.in +++ b/doc/user/less-simple.in @@ -40,7 +40,7 @@ <para> - You've seen that when you call the &Program; builder method, + You've seen that when you call the &b-link-Program; builder method, it builds the resulting program with the same base name as the source file. That is, the following call to build an @@ -91,7 +91,7 @@ </para> <scons_output example="target" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -102,7 +102,7 @@ </para> <scons_output example="target" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -146,7 +146,7 @@ </para> <scons_output example="ex2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -193,7 +193,7 @@ </para> <scons_output example="ex3" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -203,7 +203,7 @@ </para> <scons_output example="ex3" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -220,7 +220,7 @@ </para> <sconstruct> - Program('hello', ['file1.c', 'file2']) + Program('hello', ['file1.c', 'file2.c']) </sconstruct> <para> @@ -351,13 +351,13 @@ <para> Putting the call to the &Split; function - inside the <function>Program</function> call + inside the &b-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 - <function>Program</function> function: + &b-Program; function: </para> @@ -451,7 +451,7 @@ In order to compile multiple programs within the same &SConstruct; file, - simply call the <function>Program</function> method + simply call the &Program; method multiple times, once for each program you need to build: @@ -480,7 +480,7 @@ </para> <scons_output example="ex4"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -555,7 +555,7 @@ </para> <scons_output example="ex5"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> diff --git a/doc/user/less-simple.sgml b/doc/user/less-simple.sgml index d3a6edc..1aa993d 100644 --- a/doc/user/less-simple.sgml +++ b/doc/user/less-simple.sgml @@ -40,7 +40,7 @@ <para> - You've seen that when you call the &Program; builder method, + You've seen that when you call the &b-link-Program; builder method, it builds the resulting program with the same base name as the source file. That is, the following call to build an @@ -209,7 +209,7 @@ </para> <programlisting> - Program('hello', ['file1.c', 'file2']) + Program('hello', ['file1.c', 'file2.c']) </programlisting> <para> @@ -340,13 +340,13 @@ <para> Putting the call to the &Split; function - inside the <function>Program</function> call + inside the &b-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 - <function>Program</function> function: + &b-Program; function: </para> @@ -440,7 +440,7 @@ In order to compile multiple programs within the same &SConstruct; file, - simply call the <function>Program</function> method + simply call the &Program; method multiple times, once for each program you need to build: diff --git a/doc/user/libraries.in b/doc/user/libraries.in index 542cd13..e5368d1 100644 --- a/doc/user/libraries.in +++ b/doc/user/libraries.in @@ -37,8 +37,8 @@ <para> - You build your own libraries by specifying &Library; - instead of &Program;: + You build your own libraries by specifying &b-link-Library; + instead of &b-link-Program;: </para> @@ -67,7 +67,7 @@ </para> <scons_output example="ex1" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -78,7 +78,7 @@ </para> <scons_output example="ex1" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -94,14 +94,14 @@ </para> <section> - <title>Building Static Libraries Explicitly: the &StaticLibrary; Builder</title> + <title>Building Static Libraries Explicitly: the &b-StaticLibrary; Builder</title> <para> - The &Library; function builds a traditional static library. + The &b-link-Library; function builds a traditional static library. If you want to be explicit about the type of library being built, - you can use the synonym &StaticLibrary; function - instead of &Library: + you can use the synonym &b-link-StaticLibrary; function + instead of &b-Library: </para> @@ -114,20 +114,20 @@ <para> There is no functional difference between the - &StaticLibrary; and &Library; functions. + &b-link-StaticLibrary; and &b-Library; functions. </para> </section> <section> - <title>Building Shared (DLL) Libraries: the &SharedLibrary; Builder</title> + <title>Building Shared (DLL) Libraries: the &b-SharedLibrary; Builder</title> <para> If you want to build a shared library (on POSIX systems) or a DLL file (on Windows systems), - you use the &SharedLibrary; function: + you use the &b-link-SharedLibrary; function: </para> @@ -153,7 +153,7 @@ </para> <scons_output example="SharedLibrary" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -163,7 +163,7 @@ </para> <scons_output example="SharedLibrary" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -188,10 +188,10 @@ Usually, you build a library because you want to link it with one or more programs. You link libraries with a program by specifying - the libraries in the &LIBS; construction variable, + the libraries in the &cv-link-LIBS; construction variable, and by specifying the directory in which the library will be found in the - &LIBPATH; construction variable: + &cv-link-LIBPATH; construction variable: </para> @@ -231,7 +231,7 @@ </para> <scons_output example="ex2" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -242,7 +242,7 @@ </para> <scons_output example="ex2" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -288,7 +288,7 @@ </section> <section> - <title>Finding Libraries: the &LIBPATH; Construction Variable</title> + <title>Finding Libraries: the &cv-LIBPATH; Construction Variable</title> <para> @@ -296,8 +296,8 @@ certain system-defined directories for libraries. &SCons; knows how to look for libraries in directories that you specify with the - &LIBPATH; construction variable. - &LIBPATH; consists of a list of + &cv-link-LIBPATH; construction variable. + &cv-LIBPATH; consists of a list of directory names, like so: </para> @@ -356,7 +356,7 @@ </para> <scons_output example="ex3" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -367,7 +367,7 @@ </para> <scons_output example="ex3" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> diff --git a/doc/user/libraries.sgml b/doc/user/libraries.sgml index 8e25c9a..aab3045 100644 --- a/doc/user/libraries.sgml +++ b/doc/user/libraries.sgml @@ -37,8 +37,8 @@ <para> - You build your own libraries by specifying &Library; - instead of &Program;: + You build your own libraries by specifying &b-link-Library; + instead of &b-link-Program;: </para> @@ -92,14 +92,14 @@ </para> <section> - <title>Building Static Libraries Explicitly: the &StaticLibrary; Builder</title> + <title>Building Static Libraries Explicitly: the &b-StaticLibrary; Builder</title> <para> - The &Library; function builds a traditional static library. + The &b-link-Library; function builds a traditional static library. If you want to be explicit about the type of library being built, - you can use the synonym &StaticLibrary; function - instead of &Library;: + you can use the synonym &b-link-StaticLibrary; function + instead of &b-Library: </para> @@ -110,20 +110,20 @@ <para> There is no functional difference between the - &StaticLibrary; and &Library; functions. + &b-link-StaticLibrary; and &b-Library; functions. </para> </section> <section> - <title>Building Shared (DLL) Libraries: the &SharedLibrary; Builder</title> + <title>Building Shared (DLL) Libraries: the &b-SharedLibrary; Builder</title> <para> If you want to build a shared library (on POSIX systems) or a DLL file (on Windows systems), - you use the &SharedLibrary; function: + you use the &b-link-SharedLibrary; function: </para> @@ -157,6 +157,7 @@ cl /nologo /c f2.c /Fof2.obj cl /nologo /c f3.c /Fof3.obj link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj + RegServerFunc(target, source, env) </screen> <para> @@ -181,10 +182,10 @@ Usually, you build a library because you want to link it with one or more programs. You link libraries with a program by specifying - the libraries in the &LIBS; construction variable, + the libraries in the &cv-link-LIBS; construction variable, and by specifying the directory in which the library will be found in the - &LIBPATH; construction variable: + &cv-link-LIBPATH; construction variable: </para> @@ -280,7 +281,7 @@ </section> <section> - <title>Finding Libraries: the &LIBPATH; Construction Variable</title> + <title>Finding Libraries: the &cv-LIBPATH; Construction Variable</title> <para> @@ -288,8 +289,8 @@ certain system-defined directories for libraries. &SCons; knows how to look for libraries in directories that you specify with the - &LIBPATH; construction variable. - &LIBPATH; consists of a list of + &cv-link-LIBPATH; construction variable. + &cv-LIBPATH; consists of a list of directory names, like so: </para> diff --git a/doc/user/main.in b/doc/user/main.in index 3e0e047..a720915 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -32,10 +32,20 @@ <!ENTITY % scons SYSTEM "../scons.mod"> %scons; + <!ENTITY % builders-mod SYSTEM "builders.mod"> + %builders-mod; + + <!ENTITY % tools-mod SYSTEM "tools.mod"> + %tools-mod; + + <!ENTITY % variables-mod SYSTEM "variables.mod"> + %variables-mod; + <!ENTITY actions SYSTEM "actions.sgml"> <!ENTITY alias SYSTEM "alias.sgml"> <!ENTITY ant SYSTEM "ant.sgml"> <!ENTITY build-install SYSTEM "build-install.sgml"> + <!ENTITY builders SYSTEM "builders.sgml"> <!ENTITY builders-built-in SYSTEM "builders-built-in.sgml"> <!ENTITY builders-commands SYSTEM "builders-commands.sgml"> <!ENTITY builders-writing SYSTEM "builders-writing.sgml"> @@ -48,6 +58,7 @@ <!ENTITY environments SYSTEM "environments.sgml"> <!ENTITY errors SYSTEM "errors.sgml"> <!ENTITY example SYSTEM "example.sgml"> + <!ENTITY factories SYSTEM "factories.sgml"> <!ENTITY help SYSTEM "help.sgml"> <!ENTITY hierarchy SYSTEM "hierarchy.sgml"> <!ENTITY java SYSTEM "java.sgml"> @@ -56,8 +67,10 @@ <!ENTITY libraries SYSTEM "libraries.sgml"> <!ENTITY make SYSTEM "make.sgml"> <!ENTITY nodes SYSTEM "nodes.sgml"> + <!ENTITY parseconfig SYSTEM "parseconfig.sgml"> <!ENTITY precious SYSTEM "precious.sgml"> <!ENTITY preface SYSTEM "preface.sgml"> + <!ENTITY python SYSTEM "python.sgml"> <!ENTITY repositories SYSTEM "repositories.sgml"> <!ENTITY run SYSTEM "run.sgml"> <!ENTITY scanners SYSTEM "scanners.sgml"> @@ -66,9 +79,15 @@ <!ENTITY simple SYSTEM "simple.sgml"> <!ENTITY sourcecode SYSTEM "sourcecode.sgml"> <!ENTITY tasks SYSTEM "tasks.sgml"> + <!ENTITY tools SYSTEM "tools.sgml"> <!ENTITY troubleshoot SYSTEM "troubleshoot.sgml"> + <!ENTITY variables SYSTEM "variables.sgml"> <!ENTITY variants SYSTEM "variants.sgml"> + <!ENTITY builders-gen SYSTEM "builders.gen"> + <!ENTITY tools-gen SYSTEM "tools.gen"> + <!ENTITY variables-gen SYSTEM "variables.gen"> + ]> <book> @@ -137,6 +156,15 @@ &environments; </chapter> + <!-- + + <chapter id="chap-parseconfig"> + <title>Finding Installed Library Information: the &ParseConfig; Function</title> + &parseconfig; + </chapter> + + --> + <chapter id="chap-ENV"> <title>Controlling the External Environment Used to Execute Build Commands</title> &ENV_file; @@ -157,6 +185,11 @@ &install; </chapter> + <chapter id="chap-factories"> + <title>Platform-Independent File System Manipulation</title> + &factories; + </chapter> + <chapter id="chap-precious"> <title>Preventing Removal of Targets: the &Precious; Function</title> &precious; @@ -273,6 +306,21 @@ Tools() --> + <appendix id="app-variables"> + <title>Construction Variables</title> + &variables; + </appendix> + + <appendix id="app-builders"> + <title>Builders</title> + &builders; + </appendix> + + <appendix id="app-tools"> + <title>Tools</title> + &tools; + </appendix> + <appendix id="app-tasks"> <title>Handling Common Tasks</title> &tasks; @@ -280,6 +328,11 @@ <!-- + <appendix id="app-python"> + <title>Python Overview</title> + &example; + </appendix> + <appendix id="app-example"> <title>Complex &SCons; Example</title> &example; diff --git a/doc/user/main.sgml b/doc/user/main.sgml index 3e0e047..a720915 100644 --- a/doc/user/main.sgml +++ b/doc/user/main.sgml @@ -32,10 +32,20 @@ <!ENTITY % scons SYSTEM "../scons.mod"> %scons; + <!ENTITY % builders-mod SYSTEM "builders.mod"> + %builders-mod; + + <!ENTITY % tools-mod SYSTEM "tools.mod"> + %tools-mod; + + <!ENTITY % variables-mod SYSTEM "variables.mod"> + %variables-mod; + <!ENTITY actions SYSTEM "actions.sgml"> <!ENTITY alias SYSTEM "alias.sgml"> <!ENTITY ant SYSTEM "ant.sgml"> <!ENTITY build-install SYSTEM "build-install.sgml"> + <!ENTITY builders SYSTEM "builders.sgml"> <!ENTITY builders-built-in SYSTEM "builders-built-in.sgml"> <!ENTITY builders-commands SYSTEM "builders-commands.sgml"> <!ENTITY builders-writing SYSTEM "builders-writing.sgml"> @@ -48,6 +58,7 @@ <!ENTITY environments SYSTEM "environments.sgml"> <!ENTITY errors SYSTEM "errors.sgml"> <!ENTITY example SYSTEM "example.sgml"> + <!ENTITY factories SYSTEM "factories.sgml"> <!ENTITY help SYSTEM "help.sgml"> <!ENTITY hierarchy SYSTEM "hierarchy.sgml"> <!ENTITY java SYSTEM "java.sgml"> @@ -56,8 +67,10 @@ <!ENTITY libraries SYSTEM "libraries.sgml"> <!ENTITY make SYSTEM "make.sgml"> <!ENTITY nodes SYSTEM "nodes.sgml"> + <!ENTITY parseconfig SYSTEM "parseconfig.sgml"> <!ENTITY precious SYSTEM "precious.sgml"> <!ENTITY preface SYSTEM "preface.sgml"> + <!ENTITY python SYSTEM "python.sgml"> <!ENTITY repositories SYSTEM "repositories.sgml"> <!ENTITY run SYSTEM "run.sgml"> <!ENTITY scanners SYSTEM "scanners.sgml"> @@ -66,9 +79,15 @@ <!ENTITY simple SYSTEM "simple.sgml"> <!ENTITY sourcecode SYSTEM "sourcecode.sgml"> <!ENTITY tasks SYSTEM "tasks.sgml"> + <!ENTITY tools SYSTEM "tools.sgml"> <!ENTITY troubleshoot SYSTEM "troubleshoot.sgml"> + <!ENTITY variables SYSTEM "variables.sgml"> <!ENTITY variants SYSTEM "variants.sgml"> + <!ENTITY builders-gen SYSTEM "builders.gen"> + <!ENTITY tools-gen SYSTEM "tools.gen"> + <!ENTITY variables-gen SYSTEM "variables.gen"> + ]> <book> @@ -137,6 +156,15 @@ &environments; </chapter> + <!-- + + <chapter id="chap-parseconfig"> + <title>Finding Installed Library Information: the &ParseConfig; Function</title> + &parseconfig; + </chapter> + + --> + <chapter id="chap-ENV"> <title>Controlling the External Environment Used to Execute Build Commands</title> &ENV_file; @@ -157,6 +185,11 @@ &install; </chapter> + <chapter id="chap-factories"> + <title>Platform-Independent File System Manipulation</title> + &factories; + </chapter> + <chapter id="chap-precious"> <title>Preventing Removal of Targets: the &Precious; Function</title> &precious; @@ -273,6 +306,21 @@ Tools() --> + <appendix id="app-variables"> + <title>Construction Variables</title> + &variables; + </appendix> + + <appendix id="app-builders"> + <title>Builders</title> + &builders; + </appendix> + + <appendix id="app-tools"> + <title>Tools</title> + &tools; + </appendix> + <appendix id="app-tasks"> <title>Handling Common Tasks</title> &tasks; @@ -280,6 +328,11 @@ <!-- + <appendix id="app-python"> + <title>Python Overview</title> + &example; + </appendix> + <appendix id="app-example"> <title>Complex &SCons; Example</title> &example; diff --git a/doc/user/nodes.in b/doc/user/nodes.in index fd9846a..a5d05dc 100644 --- a/doc/user/nodes.in +++ b/doc/user/nodes.in @@ -52,7 +52,7 @@ For example, suppose that we want to build the two object files that make up a program with different options. - This would mean calling the &Object; + This would mean calling the &b-link-Object; builder once for each object file, specifying the desired options: @@ -67,7 +67,7 @@ One way to combine these object files into the resulting program - would be to call the &Program; + would be to call the &b-link-Program; builder with the names of the object files listed as sources: @@ -94,9 +94,9 @@ <para> A better solution is to assign the lists of targets - returned by the calls to the &Object; builder to variables, + returned by the calls to the &b-Object; builder to variables, which we can then concatenate in our - call to the &Program; builder: + call to the &b-Program; builder: </para> @@ -122,7 +122,7 @@ </para> <scons_output example="ex1" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -132,7 +132,7 @@ </para> <scons_output example="ex1" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -254,7 +254,7 @@ </para> <scons_output example="print" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -264,7 +264,7 @@ </para> <scons_output example="print" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -311,7 +311,7 @@ </para> <scons_output example="print" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -347,7 +347,7 @@ </para> <scons_output example="print" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/nodes.sgml b/doc/user/nodes.sgml index 8e24f14..b6bcb89 100644 --- a/doc/user/nodes.sgml +++ b/doc/user/nodes.sgml @@ -52,7 +52,7 @@ For example, suppose that we want to build the two object files that make up a program with different options. - This would mean calling the &Object; + This would mean calling the &b-link-Object; builder once for each object file, specifying the desired options: @@ -67,7 +67,7 @@ One way to combine these object files into the resulting program - would be to call the &Program; + would be to call the &b-link-Program; builder with the names of the object files listed as sources: @@ -94,9 +94,9 @@ <para> A better solution is to assign the lists of targets - returned by the calls to the &Object; builder to variables, + returned by the calls to the &b-Object; builder to variables, which we can then concatenate in our - call to the &Program; builder: + call to the &b-Program; builder: </para> @@ -351,7 +351,7 @@ </para> <scons_output example="print" os="posix"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/parseconfig.in b/doc/user/parseconfig.in new file mode 100644 index 0000000..d3f563c --- /dev/null +++ b/doc/user/parseconfig.in @@ -0,0 +1,81 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + + Configuring the right options to build programs to work with the + libraries--especially shared libraries--installed on a POSIX system + can be very complicated. + Various utilies with names that end in <filename>config</filename> + can return command-line options for the + GNU Compiler Collection + + </para> + + <para> + + &SCons; construction environments have a &ParseConfig; method + that executes a utility and configures + the appropriate construction variables + in the environment + based on the command-line options + returned by the specified command. + + </para> + + </para> + + <scons_example name="ParseConfig1"> + <file name="SConstruct" printme="1"> + env = Environment() + env.ParseConfig("pkg-config") + </file> + <file name="f1.c"> + int f1() { } + </file> + <file name="f2.c"> + int f2() { } + </file> + <file name="f3.c"> + int f3() { } + </file> + </scons_example> + + <para> + + &SCons; will execute the specified command string + and XXX + + </para> + + <scons_output example="ParseConfig1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <para> + + XXX + + </para> diff --git a/doc/user/parseconfig.sgml b/doc/user/parseconfig.sgml new file mode 100644 index 0000000..067ef37 --- /dev/null +++ b/doc/user/parseconfig.sgml @@ -0,0 +1,72 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + + Configuring the right options to build programs to work with the + libraries--especially shared libraries--installed on a POSIX system + can be very complicated. + Various utilies with names that end in <filename>config</filename> + can return command-line options for the + GNU Compiler Collection + + </para> + + <para> + + &SCons; construction environments have a &ParseConfig; method + that executes a utility and configures + the appropriate construction variables + in the environment + based on the command-line options + returned by the specified command. + + </para> + + </para> + + <programlisting> + env = Environment() + env.ParseConfig("pkg-config") + </programlisting> + + <para> + + &SCons; will execute the specified command string + and XXX + + </para> + + <screen> + % <userinput>scons -Q</userinput> + scons: `.' is up to date. + Must specify package names on the command line + </screen> + + <para> + + XXX + + </para> diff --git a/doc/user/precious.in b/doc/user/precious.in index fb32f2b..f5e000b 100644 --- a/doc/user/precious.in +++ b/doc/user/precious.in @@ -79,7 +79,7 @@ which the C<AfterBuild> method is called. </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> diff --git a/doc/user/preface.in b/doc/user/preface.in index 190dad1..9d0323e 100644 --- a/doc/user/preface.in +++ b/doc/user/preface.in @@ -228,7 +228,8 @@ One word of warning as you read through this Guide: Like too much Open Source software out there, - the &SCons; documentation lags the available features. + the &SCons; documentation isn't always + kept up-to-date with the available features. In other words, there's a lot that &SCons; can do that isn't yet covered in this User's Guide. diff --git a/doc/user/preface.sgml b/doc/user/preface.sgml index dfececd..47dbd98 100644 --- a/doc/user/preface.sgml +++ b/doc/user/preface.sgml @@ -228,7 +228,8 @@ One word of warning as you read through this Guide: Like too much Open Source software out there, - the &SCons; documentation lags the available features. + the &SCons; documentation isn't always + kept up-to-date with the available features. In other words, there's a lot that &SCons; can do that isn't yet covered in this User's Guide. diff --git a/doc/user/python.in b/doc/user/python.in new file mode 100644 index 0000000..e2a7cdd --- /dev/null +++ b/doc/user/python.in @@ -0,0 +1,154 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <!-- + + <section> + <title>Python Overview</title> + + <para> + + This section will provide a brief overview of + the Python programming language. + Skip this section if you are already familiar with Python + (or you're really intent on diving into &SCons; + and just picking up things as you go). + + </para> + + <para> + + Python has a lot of good + documentation freely available on-line + to help you get started. + The standard tutorial is available at XXX. + + + </para> + + <para> + + Python is very easy to pick up. + + </para> + + <para> + + Python variables must be assigned to before they can be referenced. + + </para> + + <para> + + Assignment is like most programming languages: + + x = 1 + 2 + z = 3 * x + + </para> + + <para> + + Function calls look like most language function calls: + + a = f(g) + + </para> + + <para> + + Define functions like so: + + def func(arg1, arg2): + return arg1 * arg 2 + + The number of parameters + + </para> + + <para> + + Strings can be enclosed in single quotes or double quotes, + backslashes are used to escape characters, + triple-quote syntax lets you include quotes and newlines, + raw strings begin with 'r'. + + </para> + + <para> + + Lists are enclosed in square brackets, + list items are separated by commas. + List references use square brackets and integer index values, + slice notation lets you select, delete or replace a range. + + </para> + + <para> + + Dictionaries (hashes) are enclosed in curly brackets, + : separates keys from values, + , separates items. + Dictionary values are referenced using square brackets. + + </para> + + <para> + + Access class attributes (including methods) using a '.'. + + </para> + + <para> + + if: statements look like + + elif: statements look like + + else: statements look like + + </para> + + <para> + + for: statements look like + + while: statements look like + + break statements look like + + continue statements look like + + </para> + + <para> + + pass + + </para> + + </section> + + --> diff --git a/doc/user/python.sgml b/doc/user/python.sgml new file mode 100644 index 0000000..e2a7cdd --- /dev/null +++ b/doc/user/python.sgml @@ -0,0 +1,154 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <!-- + + <section> + <title>Python Overview</title> + + <para> + + This section will provide a brief overview of + the Python programming language. + Skip this section if you are already familiar with Python + (or you're really intent on diving into &SCons; + and just picking up things as you go). + + </para> + + <para> + + Python has a lot of good + documentation freely available on-line + to help you get started. + The standard tutorial is available at XXX. + + + </para> + + <para> + + Python is very easy to pick up. + + </para> + + <para> + + Python variables must be assigned to before they can be referenced. + + </para> + + <para> + + Assignment is like most programming languages: + + x = 1 + 2 + z = 3 * x + + </para> + + <para> + + Function calls look like most language function calls: + + a = f(g) + + </para> + + <para> + + Define functions like so: + + def func(arg1, arg2): + return arg1 * arg 2 + + The number of parameters + + </para> + + <para> + + Strings can be enclosed in single quotes or double quotes, + backslashes are used to escape characters, + triple-quote syntax lets you include quotes and newlines, + raw strings begin with 'r'. + + </para> + + <para> + + Lists are enclosed in square brackets, + list items are separated by commas. + List references use square brackets and integer index values, + slice notation lets you select, delete or replace a range. + + </para> + + <para> + + Dictionaries (hashes) are enclosed in curly brackets, + : separates keys from values, + , separates items. + Dictionary values are referenced using square brackets. + + </para> + + <para> + + Access class attributes (including methods) using a '.'. + + </para> + + <para> + + if: statements look like + + elif: statements look like + + else: statements look like + + </para> + + <para> + + for: statements look like + + while: statements look like + + break statements look like + + continue statements look like + + </para> + + <para> + + pass + + </para> + + </section> + + --> diff --git a/doc/user/repositories.in b/doc/user/repositories.in index 79d9a75..d2c9236 100644 --- a/doc/user/repositories.in +++ b/doc/user/repositories.in @@ -240,7 +240,7 @@ subdirectories under the repository tree. </para> <scons_output example="ex1"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -264,7 +264,7 @@ subdirectories under the repository tree. </scons_example> <scons_output example="ex2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> gcc -c /usr/repository1/hello.c -o hello.o gcc -o hello hello.o </scons_output> @@ -289,7 +289,7 @@ subdirectories under the repository tree. </scons_example> <scons_output example="ex3"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -376,8 +376,8 @@ subdirectories under the repository tree. </scons_example> <scons_output example="ex4"> - <command>cd /usr/repository1</command> - <command>scons -Q</command> + <scons_output_command>cd /usr/repository1</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -402,9 +402,9 @@ subdirectories under the repository tree. <!-- <scons_output example="ex4"> - <command>cd $HOME/build</command> - <command>edit hello.c</command> - <command>scons -Q -Y __ROOT__/usr/repository1</command> + <scons_output_command>cd $HOME/build</scons_output_command> + <scons_output_command>edit hello.c</scons_output_command> + <scons_output_command>scons -Q -Y __ROOT__/usr/repository1</scons_output_command> </scons_output> --> <screen> diff --git a/doc/user/repositories.sgml b/doc/user/repositories.sgml index e728bc4..0392853 100644 --- a/doc/user/repositories.sgml +++ b/doc/user/repositories.sgml @@ -374,9 +374,9 @@ subdirectories under the repository tree. <!-- <scons_output example="ex4"> - <command>cd $HOME/build</command> - <command>edit hello.c</command> - <command>scons -Q -Y __ROOT__/usr/repository1</command> + <scons_output_command>cd $HOME/build</scons_output_command> + <scons_output_command>edit hello.c</scons_output_command> + <scons_output_command>scons -Q -Y __ROOT__/usr/repository1</scons_output_command> </scons_output> --> <screen> diff --git a/doc/user/scanners.in b/doc/user/scanners.in index 946c058..a0029ef 100644 --- a/doc/user/scanners.in +++ b/doc/user/scanners.in @@ -228,7 +228,7 @@ over the file scanning rather than being called for each input line: A list of directories that form the search path for included files for this scanner. - This is how &SCons; handles the &CPPPATH; and &LIBPATH; + This is how &SCons; handles the &cv-link-CPPPATH; and &cv-link-LIBPATH; variables. </para> @@ -257,7 +257,7 @@ over the file scanning rather than being called for each input line: which typically takes an <literal>skeys</literal> argument to associate the type of file suffix with this scanner. The Scanner object must then be associated with the - &SCANNERS; construction variable of a construction environment, + &cv-link-SCANNERS; construction variable of a construction environment, typically by using the &Append; method: </para> @@ -320,10 +320,10 @@ over the file scanning rather than being called for each input line: </para> <scons_output example="scan"> - <command>scons -Q</command> - <command output=" [CHANGE THE CONTENTS OF other_file]">edit other_file</command> - <command>scons -Q</command> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF other_file]">edit other_file</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> --> diff --git a/doc/user/scanners.sgml b/doc/user/scanners.sgml index 4632369..b4756c5 100644 --- a/doc/user/scanners.sgml +++ b/doc/user/scanners.sgml @@ -228,7 +228,7 @@ over the file scanning rather than being called for each input line: A list of directories that form the search path for included files for this scanner. - This is how &SCons; handles the &CPPPATH; and &LIBPATH; + This is how &SCons; handles the &cv-link-CPPPATH; and &cv-link-LIBPATH; variables. </para> @@ -257,7 +257,7 @@ over the file scanning rather than being called for each input line: which typically takes an <literal>skeys</literal> argument to associate the type of file suffix with this scanner. The Scanner object must then be associated with the - &SCANNERS; construction variable of a construction environment, + &cv-link-SCANNERS; construction variable of a construction environment, typically by using the &Append; method: </para> @@ -306,10 +306,10 @@ over the file scanning rather than being called for each input line: </para> <scons_output example="scan"> - <command>scons -Q</command> - <command output=" [CHANGE THE CONTENTS OF other_file]">edit other_file</command> - <command>scons -Q</command> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF other_file]">edit other_file</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> --> diff --git a/doc/user/sconf.in b/doc/user/sconf.in index 525b0fc..14c10b7 100644 --- a/doc/user/sconf.in +++ b/doc/user/sconf.in @@ -67,6 +67,28 @@ <para> + &SCons; provides a number of basic checks, + as well as a mechanism for adding your own custom checks. + + </para> + + <para> + + Note that &SCons; uses its own dependency + mechanism to determine when a check + needs to be run--that is, + &SCons; does not run the checks + every time it is invoked, + but caches the values returned by previous checks + and uses the cached values unless something has changed. + This saves a tremendous amount + of developer time while working on + cross-platform build issues. + + </para> + + <para> + The next sections describe the basic checks that &SCons; supports, as well as how to add your own custom checks. @@ -229,14 +251,14 @@ </para> - <programlisting> + <sconstruct> env = Environment() conf = Configure(env) if not conf.CheckType('off_t', '#include &lt;sys/types.h&gt;\n'): print 'Did not find off_t typedef, assuming int' conf.env.Append(CCFLAGS = '-Doff_t=int') env = conf.Finish() - </programlisting> + </sconstruct> </section> @@ -259,7 +281,7 @@ </para> - <programlisting> + <sconstruct> mylib_test_source_file = """ #include &lt;mylib.h&gt; int main(int argc, char **argv) @@ -274,7 +296,7 @@ result = context.TryLink(mylib_test_source_file, '.c') context.Result(result) return result - </programlisting> + </sconstruct> <para> @@ -336,7 +358,7 @@ </para> - <programlisting> + <sconstruct> mylib_test_source_file = """ #include &lt;mylib.h&gt; int main(int argc, char **argv) @@ -361,7 +383,7 @@ # We would then add actual calls like Program() to build # something using the "env" construction environment. - </programlisting> + </sconstruct> <para> @@ -396,3 +418,54 @@ </screen> </section> + + <section> + <title>Not Configuring When Cleaning Targets</title> + + <para> + + Using multi-platform configuration + as described in the previous sections + will run the configuration commands + even when invoking + <userinput>scons -c</userinput> + to clean targets: + + </para> + + <screen> + % <userinput>scons -Q -c</userinput> + Checking for MyLibrary... ok + Removed foo.o + Removed foo + </screen> + + <para> + + Although running the platform checks + when removing targets doesn't hurt anything, + it's usually unnecessary. + You can avoid this by using the + &GetOption(); method to + check whether the <option>-c</option> (clean) + option has been invoked on the command line: + + </para> + + <sconstruct> + env = Environment() + if not env.GetOption('clean'): + conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) + if not conf.CheckMyLibrary(): + print 'MyLibrary is not installed!' + Exit(1) + env = conf.Finish() + </sconstruct> + + <screen> + % <userinput>scons -Q -c</userinput> + Removed foo.o + Removed foo + </screen> + + </section> diff --git a/doc/user/sconf.sgml b/doc/user/sconf.sgml index 2e2a698..997c97d 100644 --- a/doc/user/sconf.sgml +++ b/doc/user/sconf.sgml @@ -67,6 +67,28 @@ <para> + &SCons; provides a number of basic checks, + as well as a mechanism for adding your own custom checks. + + </para> + + <para> + + Note that &SCons; uses its own dependency + mechanism to determine when a check + needs to be run--that is, + &SCons; does not run the checks + every time it is invoked, + but caches the values returned by previous checks + and uses the cached values unless something has changed. + This saves a tremendous amount + of developer time while working on + cross-platform build issues. + + </para> + + <para> + The next sections describe the basic checks that &SCons; supports, as well as how to add your own custom checks. @@ -396,3 +418,54 @@ </screen> </section> + + <section> + <title>Not Configuring When Cleaning Targets</title> + + <para> + + Using multi-platform configuration + as described in the previous sections + will run the configuration commands + even when invoking + <userinput>scons -c</userinput> + to clean targets: + + </para> + + <screen> + % <userinput>scons -Q -c</userinput> + Checking for MyLibrary... ok + Removed foo.o + Removed foo + </screen> + + <para> + + Although running the platform checks + when removing targets doesn't hurt anything, + it's usually unnecessary. + You can avoid this by using the + &GetOption;(); method to + check whether the <option>-c</option> (clean) + option has been invoked on the command line: + + </para> + + <programlisting> + env = Environment() + if not env.GetOption('clean'): + conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) + if not conf.CheckMyLibrary(): + print 'MyLibrary is not installed!' + Exit(1) + env = conf.Finish() + </programlisting> + + <screen> + % <userinput>scons -Q -c</userinput> + Removed foo.o + Removed foo + </screen> + + </section> diff --git a/doc/user/separate.in b/doc/user/separate.in index d613f42..6d497a2 100644 --- a/doc/user/separate.in +++ b/doc/user/separate.in @@ -160,9 +160,9 @@ program using the F<build/foo.c> path name. </para> <scons_output example="ex1"> - <command>ls src</command> - <command>scons -Q</command> - <command>ls build</command> + <scons_output_command>ls src</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>ls build</scons_output_command> </scons_output> <para> @@ -357,9 +357,9 @@ program using the F<build/foo.c> path name. </para> <scons_output example="ex_builddir"> - <command>ls src</command> - <command>scons -Q</command> - <command>ls build</command> + <scons_output_command>ls src</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>ls build</scons_output_command> </scons_output> <para> @@ -388,9 +388,9 @@ program using the F<build/foo.c> path name. </para> <scons_output example="ex_duplicate_0"> - <command>ls src</command> - <command>scons -Q</command> - <command>ls build</command> + <scons_output_command>ls src</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>ls build</scons_output_command> </scons_output> </section> @@ -439,9 +439,9 @@ program using the F<build/foo.c> path name. </para> <scons_output example="example_builddir_sconscript"> - <command>ls src</command> - <command>scons -Q</command> - <command>ls build</command> + <scons_output_command>ls src</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>ls build</scons_output_command> </scons_output> <para> diff --git a/doc/user/simple.in b/doc/user/simple.in index 4ac6d33..57fdd3a 100644 --- a/doc/user/simple.in +++ b/doc/user/simple.in @@ -77,7 +77,7 @@ and the input file from which you want it built (the <filename>hello.c</filename> file). - &Program; is a &builder_method;, + &b-link-Program; is a <firstterm>builder_method</firstterm>, a Python call that tells &SCons; that you want to build an executable program. @@ -92,7 +92,7 @@ </para> <scons_output example="ex1" os="posix"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -103,7 +103,7 @@ </para> <scons_output example="ex1" os="win32"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -147,10 +147,10 @@ <para> - The &Program; builder method is only one of + The &b-link-Program; builder method is only one of many builder methods that &SCons; provides to build different types of files. - Another is the &Object; builder method, + Another is the &b-link-Object; builder method, which tells &SCons; to build an object file from the specified source file: @@ -173,7 +173,7 @@ </para> <scons_output example="Object" os="posix"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -184,7 +184,7 @@ </para> <scons_output example="Object" os="win32"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> </section> @@ -195,8 +195,8 @@ <para> &SCons; also makes building with Java extremely easy. - Unlike the &Program; and &Object; builder methods, - however, the &Java; builder method + Unlike the &b-link-Program; and &b-link-Object; builder methods, + however, the &b-link-Java; builder method requires that you specify the name of a destination directory in which you want the class files placed, @@ -231,7 +231,7 @@ </para> <scons_output example="java" os="posix"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -272,8 +272,8 @@ </scons_example> <scons_output example="clean" os="posix"> - <command>scons</command> - <command>scons -c</command> + <scons_output_command>scons</scons_output_command> + <scons_output_command>scons -c</scons_output_command> </scons_output> <para> @@ -283,8 +283,8 @@ </para> <scons_output example="clean" os="win32"> - <command>scons</command> - <command>scons -c</command> + <scons_output_command>scons</scons_output_command> + <scons_output_command>scons -c</scons_output_command> </scons_output> <para> @@ -378,7 +378,7 @@ which to do things. </para> </footnote> - In other words, when you call the &Program; builder + In other words, when you call the &b-link-Program; builder (or any other builder method), you're not telling &SCons; to build the program at the instant the builder method is called. @@ -396,7 +396,7 @@ <para> &SCons; reflects this distinction between - <emphasis>calling a builder method like</emphasis> &Program;> + <emphasis>calling a builder method like</emphasis> &b-Program;> and <emphasis>actually building the program</emphasis> by printing the status messages that indicate when it's "just reading" the &SConstruct; file, @@ -415,7 +415,7 @@ Python has a <literal>print</literal> statement that prints a string of characters to the screen. If we put <literal>print</literal> statements around - our calls to the &Program; builder method: + our calls to the &b-Program; builder method: </para> @@ -447,7 +447,7 @@ </para> <scons_output example="declarative" os="posix"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -475,7 +475,7 @@ </para> <scons_output example="ex1" os="win32"> - <command>scons</command> + <scons_output_command>scons</scons_output_command> </scons_output> <para> @@ -501,7 +501,7 @@ </para> <scons_output example="ex1" os="win32"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> diff --git a/doc/user/simple.sgml b/doc/user/simple.sgml index b925d04..fc68d17 100644 --- a/doc/user/simple.sgml +++ b/doc/user/simple.sgml @@ -72,7 +72,7 @@ and the input file from which you want it built (the <filename>hello.c</filename> file). - &Program; is a &builder_method;, + &b-link-Program; is a <firstterm>builder_method</firstterm>, a Python call that tells &SCons; that you want to build an executable program. @@ -154,10 +154,10 @@ <para> - The &Program; builder method is only one of + The &b-link-Program; builder method is only one of many builder methods that &SCons; provides to build different types of files. - Another is the &Object; builder method, + Another is the &b-link-Object; builder method, which tells &SCons; to build an object file from the specified source file: @@ -207,8 +207,8 @@ <para> &SCons; also makes building with Java extremely easy. - Unlike the &Program; and &Object; builder methods, - however, the &Java; builder method + Unlike the &b-link-Program; and &b-link-Object; builder methods, + however, the &b-link-Java; builder method requires that you specify the name of a destination directory in which you want the class files placed, @@ -401,7 +401,7 @@ which to do things. </para> </footnote> - In other words, when you call the &Program; builder + In other words, when you call the &b-link-Program; builder (or any other builder method), you're not telling &SCons; to build the program at the instant the builder method is called. @@ -419,7 +419,7 @@ <para> &SCons; reflects this distinction between - <emphasis>calling a builder method like</emphasis> &Program;> + <emphasis>calling a builder method like</emphasis> &b-Program;> and <emphasis>actually building the program</emphasis> by printing the status messages that indicate when it's "just reading" the &SConstruct; file, @@ -438,7 +438,7 @@ Python has a <literal>print</literal> statement that prints a string of characters to the screen. If we put <literal>print</literal> statements around - our calls to the &Program; builder method: + our calls to the &b-Program; builder method: </para> diff --git a/doc/user/sourcecode.in b/doc/user/sourcecode.in index c40c512..04c76d0 100644 --- a/doc/user/sourcecode.in +++ b/doc/user/sourcecode.in @@ -54,7 +54,7 @@ </scons_example> <scons_output example="ex_bitkeeper"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -77,7 +77,7 @@ </scons_example> <scons_output example="ex_cvs"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -103,7 +103,7 @@ </scons_example> <scons_output example="ex_rcs"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -129,7 +129,7 @@ </scons_example> <scons_output example="ex_sccs"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> @@ -154,7 +154,7 @@ </scons_example> <scons_output example="ex_subversion"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/sourcecode.sgml b/doc/user/sourcecode.sgml index daa9ad7..6ea0b21 100644 --- a/doc/user/sourcecode.sgml +++ b/doc/user/sourcecode.sgml @@ -153,7 +153,7 @@ </scons_example> <scons_output example="ex_subversion"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> diff --git a/doc/user/tools.in b/doc/user/tools.in new file mode 100644 index 0000000..8eaa35e --- /dev/null +++ b/doc/user/tools.in @@ -0,0 +1,38 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<para> + +This appendix contains descriptions of all of the +Tools that are +available "out of the box" in this version of SCons. + +</para> + +<variablelist> + +&tools-gen; + +</variablelist> diff --git a/doc/user/tools.sgml b/doc/user/tools.sgml new file mode 100644 index 0000000..8eaa35e --- /dev/null +++ b/doc/user/tools.sgml @@ -0,0 +1,38 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<para> + +This appendix contains descriptions of all of the +Tools that are +available "out of the box" in this version of SCons. + +</para> + +<variablelist> + +&tools-gen; + +</variablelist> diff --git a/doc/user/troubleshoot.in b/doc/user/troubleshoot.in index e5c008d..206e50e 100644 --- a/doc/user/troubleshoot.in +++ b/doc/user/troubleshoot.in @@ -77,9 +77,9 @@ </para> <scons_output example="explain1" os="posix"> - <command>scons -Q</command> - <command>scons -Q</command> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> <para> @@ -100,7 +100,7 @@ </para> <scons_output example="explain1" os="posix"> - <command>scons -Q --debug=explain</command> + <scons_output_command>scons -Q --debug=explain</scons_output_command> </scons_output> <para> @@ -145,9 +145,9 @@ </scons_example> <scons_output example="explain2" os="posix"> - <command>scons -Q</command> - <command output=" [CHANGE THE CONTENTS OF file2.c]">edit file2.c</command> - <command>scons -Q --debug=explain</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF file2.c]">edit file2.c</scons_output_command> + <scons_output_command>scons -Q --debug=explain</scons_output_command> </scons_output> <para> @@ -188,9 +188,121 @@ </scons_example> <scons_output example="explain3" os="posix"> - <command>scons -Q</command> - <command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</command> - <command>scons -Q --debug=explain</command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</scons_output_command> + <scons_output_command>scons -Q --debug=explain</scons_output_command> + </scons_output> + + </section> + + <section> + <title>What's in That Construction Environment? the &Dump; Method</title> + + <para> + + When you create a construction environment, + &SCons; populates it + with construction variables that are set up + for various compilers, linkers and utilities + that it finds on your system. + Although this is usually helpful and what you want, + it might be frustrating if &SCons; + doesn't set certain variables that you + expect to be sit. + In situations like this, + it's sometimes helpful to use the + construction environment &Dump; method + to print all or some of + the construction variables. + Note that the &Dump; method + <emphasis>returns</emphasis> + the representation of the variables + in the environment + for you to print (or otherwise manipulate): + + </para> + + <scons_example name="Dump"> + <file name="SConstruct" print="1"> + env = Environment() + print env.Dump() + </file> + </scons_example> + + <para> + + On a POSIX system with gcc installed, + this might generate: + + </para> + + <scons_output example="Dump" os="posix" tools="gcc"> + <scons_output_command>scons</scons_output_command> + </scons_output> + + <para> + + On a Windows system with Visual C++ + the output might look like: + + </para> + + <scons_output example="Dump" os="win32" tools="msvc"> + <scons_output_command>scons</scons_output_command> + </scons_output> + + <para> + + The construction environments in these examples have + actually been restricted to just gcc and Visual C++, + respectively. + In a real-life situation, + the construction environments will + likely contain a great many more variables. + + </para> + + <para> + + To make it easier to see just what you're + interested in, + the &Dump; method allows you to + specify a specific constrcution variable + that you want to disply. + For example, + it's not unusual to want to verify + the external environment used to execute build commands, + to make sure that the PATH and other + environment variables are set up the way they should be. + You can do this as follows: + + </para> + + <scons_example name="Dump_ENV"> + <file name="SConstruct" print="1"> + env = Environment() + print env.Dump('ENV') + </file> + </scons_example> + + <para> + + Which might display the following when executed on a POSIX system: + + </para> + + <scons_output example="Dump_ENV" os="posix"> + <scons_output_command>scons</scons_output_command> + </scons_output> + + <para> + + And the following when executed on a Windows system: + + </para> + + <scons_output example="Dump_ENV" os="win32"> + <scons_output_command>scons</scons_output_command> </scons_output> </section> diff --git a/doc/user/troubleshoot.sgml b/doc/user/troubleshoot.sgml index aee2aee..5cd1c9e 100644 --- a/doc/user/troubleshoot.sgml +++ b/doc/user/troubleshoot.sgml @@ -185,3 +185,276 @@ </screen> </section> + + <section> + <title>What's in That Construction Environment? the &Dump; Method</title> + + <para> + + When you create a construction environment, + &SCons; populates it + with construction variables that are set up + for various compilers, linkers and utilities + that it finds on your system. + Although this is usually helpful and what you want, + it might be frustrating if &SCons; + doesn't set certain variables that you + expect to be sit. + In situations like this, + it's sometimes helpful to use the + construction environment &Dump; method + to print all or some of + the construction variables. + Note that the &Dump; method + <emphasis>returns</emphasis> + the representation of the variables + in the environment + for you to print (or otherwise manipulate): + + </para> + + + + <para> + + On a POSIX system with gcc installed, + this might generate: + + </para> + + <screen> + % <userinput>scons</userinput> + scons: Reading SConscript files ... + { 'BUILDERS': {}, + 'CPPSUFFIXES': [ '.c', + '.C', + '.cxx', + '.cpp', + '.c++', + '.cc', + '.h', + '.H', + '.hxx', + '.hpp', + '.hh', + '.F', + '.fpp', + '.FPP', + '.S', + '.spp', + '.SPP'], + 'DSUFFIXES': ['.d'], + 'Dir': <SCons.Defaults.Variable_Method_Caller instance at 0x829dcb4>, + 'ENV': {'PATH': '/usr/local/bin:/bin:/usr/bin'}, + 'ESCAPE': <function escape at 0x837d2a4>, + 'File': <SCons.Defaults.Variable_Method_Caller instance at 0x829e0fc>, + 'IDLSUFFIXES': ['.idl', '.IDL'], + 'INSTALL': <function copyFunc at 0x829db9c>, + 'LIBPREFIX': 'lib', + 'LIBPREFIXES': '$LIBPREFIX', + 'LIBSUFFIX': '.a', + 'LIBSUFFIXES': ['$LIBSUFFIX', '$SHLIBSUFFIX'], + 'OBJPREFIX': '', + 'OBJSUFFIX': '.o', + 'PDFPREFIX': '', + 'PDFSUFFIX': '.pdf', + 'PLATFORM': 'posix', + 'PROGPREFIX': '', + 'PROGSUFFIX': '', + 'PSPAWN': <function piped_env_spawn at 0x837d384>, + 'PSPREFIX': '', + 'PSSUFFIX': '.ps', + 'RDirs': <SCons.Defaults.Variable_Method_Caller instance at 0x829e46c>, + 'SCANNERS': [], + 'SHELL': 'sh', + 'SHLIBPREFIX': '$LIBPREFIX', + 'SHLIBSUFFIX': '.so', + 'SHOBJPREFIX': '$OBJPREFIX', + 'SHOBJSUFFIX': '$OBJSUFFIX', + 'SPAWN': <function spawnvpe_spawn at 0x8377fdc>, + 'TEMPFILE': <class SCons.Defaults.NullCmdGenerator at 0x829ddec>, + 'TOOLS': [], + '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}', + '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET)} $)', + '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET)} $)', + '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}', + '__RPATH': '$_RPATH', + '_concat': <function _concat at 0x829dc0c>, + '_defines': <function _defines at 0x829dc7c>, + '_stripixes': <function _stripixes at 0x829dc44>} + scons: done reading SConscript files. + scons: Building targets ... + scons: `.' is up to date. + scons: done building targets. + </screen> + + <para> + + On a Windows system with Visual C++ + the output might look like: + + </para> + + <screen> + C:\><userinput>scons</userinput> + scons: Reading SConscript files ... + { 'BUILDERS': {'Object': <SCons.Memoize.MultiStepBuilder object at 0x83493e4>, 'SharedObject': <SCons.Memoize.MultiStepBuilder object at 0x8349fec>, 'StaticObject': <SCons.Memoize.MultiStepBuilder object at 0x83493e4>, 'PCH': <SCons.Memoize.BuilderBase object at 0x83418cc>, 'RES': <SCons.Memoize.BuilderBase object at 0x8367cec>}, + 'CC': 'cl', + 'CCCOM': <SCons.Memoize.FunctionAction object at 0x8340454>, + 'CCCOMFLAGS': '$CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo$TARGET $CCPCHFLAGS $CCPDBFLAGS', + 'CCFLAGS': ['/nologo'], + 'CCPCHFLAGS': ['${(PCH and "/Yu%s /Fp%s"%(PCHSTOP or "",File(PCH))) or ""}'], + 'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'], + 'CFILESUFFIX': '.c', + 'CPPDEFPREFIX': '/D', + 'CPPDEFSUFFIX': '', + 'CPPSUFFIXES': [ '.c', + '.C', + '.cxx', + '.cpp', + '.c++', + '.cc', + '.h', + '.H', + '.hxx', + '.hpp', + '.hh', + '.F', + '.fpp', + '.FPP', + '.S', + '.spp', + '.SPP'], + 'CXX': '$CC', + 'CXXCOM': '$CXX $CXXFLAGS $CCCOMFLAGS', + 'CXXFILESUFFIX': '.cc', + 'CXXFLAGS': ['$CCFLAGS', '$(', '/TP', '$)'], + 'DSUFFIXES': ['.d'], + 'Dir': <SCons.Defaults.Variable_Method_Caller instance at 0x829dcb4>, + 'ENV': { 'INCLUDE': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\include', + 'LIB': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\lib', + 'PATH': 'C:\\Program Files\\Microsoft Visual Studio\\Common\\tools\\WIN95;C:\\Program Files\\Microsoft Visual Studio\\Common\\MSDev98\\bin;C:\\Program Files\\Microsoft Visual Studio\\Common\\tools;C:\\Program Files\\Microsoft Visual Studio/VC98\\bin', + 'PATHEXT': '.COM;.EXE;.BAT;.CMD'}, + 'ESCAPE': <function <lambda> at 0x82339ec>, + 'File': <SCons.Defaults.Variable_Method_Caller instance at 0x829e0fc>, + 'IDLSUFFIXES': ['.idl', '.IDL'], + 'INCPREFIX': '/I', + 'INCSUFFIX': '', + 'INSTALL': <function copyFunc at 0x829db9c>, + 'LIBPREFIX': '', + 'LIBPREFIXES': ['$LIBPREFIX'], + 'LIBSUFFIX': '.lib', + 'LIBSUFFIXES': ['$LIBSUFFIX'], + 'MAXLINELENGTH': 2048, + 'MSVS': {'VERSION': '6.0', 'VERSIONS': ['6.0']}, + 'MSVS_VERSION': '6.0', + 'OBJPREFIX': '', + 'OBJSUFFIX': '.obj', + 'PCHCOM': '$CXX $CXXFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo${TARGETS[1]} /Yc$PCHSTOP /Fp${TARGETS[0]} $CCPDBFLAGS $PCHPDBFLAGS', + 'PCHPDBFLAGS': ['${(PDB and "/Yd") or ""}'], + 'PDFPREFIX': '', + 'PDFSUFFIX': '.pdf', + 'PLATFORM': 'win32', + 'PROGPREFIX': '', + 'PROGSUFFIX': '.exe', + 'PSPAWN': <function piped_spawn at 0x8372bc4>, + 'PSPREFIX': '', + 'PSSUFFIX': '.ps', + 'RC': 'rc', + 'RCCOM': '$RC $_CPPDEFFLAGS $_CPPINCFLAGS $RCFLAGS /fo$TARGET $SOURCES', + 'RCFLAGS': [], + 'RDirs': <SCons.Defaults.Variable_Method_Caller instance at 0x829e46c>, + 'SCANNERS': [], + 'SHCC': '$CC', + 'SHCCCOM': <SCons.Memoize.FunctionAction object at 0x83494bc>, + 'SHCCFLAGS': ['$CCFLAGS'], + 'SHCXX': '$CXX', + 'SHCXXCOM': '$SHCXX $SHCXXFLAGS $CCCOMFLAGS', + 'SHCXXFLAGS': ['$CXXFLAGS'], + 'SHELL': None, + 'SHLIBPREFIX': '', + 'SHLIBSUFFIX': '.dll', + 'SHOBJPREFIX': '$OBJPREFIX', + 'SHOBJSUFFIX': '$OBJSUFFIX', + 'SPAWN': <function spawn at 0x8374c34>, + 'STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME': 1, + 'TEMPFILE': <class SCons.Platform.win32.TempFileMunge at 0x835edc4>, + 'TOOLS': ['msvc'], + '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}', + '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET)} $)', + '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET)} $)', + '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}', + '_concat': <function _concat at 0x829dc0c>, + '_defines': <function _defines at 0x829dc7c>, + '_stripixes': <function _stripixes at 0x829dc44>} + scons: done reading SConscript files. + scons: Building targets ... + scons: `.' is up to date. + scons: done building targets. + </screen> + + <para> + + The construction environments in these examples have + actually been restricted to just gcc and Visual C++, + respectively. + In a real-life situation, + the construction environments will + likely contain a great many more variables. + + </para> + + <para> + + To make it easier to see just what you're + interested in, + the &Dump; method allows you to + specify a specific constrcution variable + that you want to disply. + For example, + it's not unusual to want to verify + the external environment used to execute build commands, + to make sure that the PATH and other + environment variables are set up the way they should be. + You can do this as follows: + + </para> + + + + <para> + + Which might display the following when executed on a POSIX system: + + </para> + + <screen> + % <userinput>scons</userinput> + scons: Reading SConscript files ... + {'PATH': '/usr/local/bin:/bin:/usr/bin'} + scons: done reading SConscript files. + scons: Building targets ... + scons: `.' is up to date. + scons: done building targets. + </screen> + + <para> + + And the following when executed on a Windows system: + + </para> + + <screen> + C:\><userinput>scons</userinput> + scons: Reading SConscript files ... + { 'INCLUDE': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\include', + 'LIB': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\lib', + 'PATH': 'C:\\Program Files\\Microsoft Visual Studio\\Common\\tools\\WIN95;C:\\Program Files\\Microsoft Visual Studio\\Common\\MSDev98\\bin;C:\\Program Files\\Microsoft Visual Studio\\Common\\tools;C:\\Program Files\\Microsoft Visual Studio/VC98\\bin', + 'PATHEXT': '.COM;.EXE;.BAT;.CMD'} + scons: done reading SConscript files. + scons: Building targets ... + scons: `.' is up to date. + scons: done building targets. + </screen> + + </section> diff --git a/doc/user/variables.in b/doc/user/variables.in new file mode 100644 index 0000000..7009996 --- /dev/null +++ b/doc/user/variables.in @@ -0,0 +1,56 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<para> + +This appendix contains descriptions of all of the +construction variables that are <emphasis>potentially</emphasis> +available "out of the box" in this version of SCons. +Whether or not setting a construction variable +in a construction environment +will actually have an effect depends on +whether any of the Tools and/or Builders +that use the variable have been +included in the construction environment. + +</para> + +<para> + +In this appendix, we have +appended the initial <envar>$</envar> +(dollar sign) to the beginning of each +variable name when it appears in the text, +but left off the dollar sign +in the left-hand column +where the name appears for each entry. + +</para> + +<variablelist> + +&variables-gen; + +</variablelist> diff --git a/doc/user/variables.sgml b/doc/user/variables.sgml new file mode 100644 index 0000000..7009996 --- /dev/null +++ b/doc/user/variables.sgml @@ -0,0 +1,56 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<para> + +This appendix contains descriptions of all of the +construction variables that are <emphasis>potentially</emphasis> +available "out of the box" in this version of SCons. +Whether or not setting a construction variable +in a construction environment +will actually have an effect depends on +whether any of the Tools and/or Builders +that use the variable have been +included in the construction environment. + +</para> + +<para> + +In this appendix, we have +appended the initial <envar>$</envar> +(dollar sign) to the beginning of each +variable name when it appears in the text, +but left off the dollar sign +in the left-hand column +where the name appears for each entry. + +</para> + +<variablelist> + +&variables-gen; + +</variablelist> diff --git a/doc/user/variants.in b/doc/user/variants.in index 82d938b..2bdc394 100644 --- a/doc/user/variants.in +++ b/doc/user/variants.in @@ -49,7 +49,8 @@ is pretty smart about rebuilding things when you change options. <para> - The &BuildDir; function now gives us everything + The &build_dir; keyword argument of + the &SConscript; function provides everything we need to show how easy it is to create variant builds using &SCons;. Suppose, for example, that we want to @@ -79,11 +80,6 @@ is pretty smart about rebuilding things when you change options. Export('env') env.SConscript('src/SConscript', build_dir='build/$PLATFORM') - - # - #BuildDir("#build/$PLATFORM", 'src') - #SConscript("build/$PLATFORM/hello/SConscript") - #SConscript("build/$PLATFORM/world/SConscript") </file> <directory name="src"></directory> <directory name="src/hello"></directory> @@ -125,7 +121,7 @@ is pretty smart about rebuilding things when you change options. </para> <scons_output example="ex_variants" os="posix"> - <command>scons -Q OS=linux</command> + <scons_output_command>scons -Q OS=linux</scons_output_command> </scons_output> <para> @@ -135,7 +131,7 @@ is pretty smart about rebuilding things when you change options. </para> <scons_output example="ex_variants" os="win32"> - <command>scons -Q OS=windows</command> + <scons_output_command>scons -Q OS=windows</scons_output_command> </scons_output> <!-- @@ -149,7 +145,7 @@ is pretty smart about rebuilding things when you change options. </scons_example> <scons_output example="ex_var2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> --> diff --git a/doc/user/variants.sgml b/doc/user/variants.sgml index 0ef7d1f..57d96e0 100644 --- a/doc/user/variants.sgml +++ b/doc/user/variants.sgml @@ -49,7 +49,8 @@ is pretty smart about rebuilding things when you change options. <para> - The &BuildDir; function now gives us everything + The &build_dir; keyword argument of + the &SConscript; function provides everything we need to show how easy it is to create variant builds using &SCons;. Suppose, for example, that we want to @@ -78,11 +79,6 @@ is pretty smart about rebuilding things when you change options. Export('env') env.SConscript('src/SConscript', build_dir='build/$PLATFORM') - - # - #BuildDir("#build/$PLATFORM", 'src') - #SConscript("build/$PLATFORM/hello/SConscript") - #SConscript("build/$PLATFORM/world/SConscript") </programlisting> <para> @@ -132,7 +128,7 @@ is pretty smart about rebuilding things when you change options. </scons_example> <scons_output example="ex_var2"> - <command>scons -Q</command> + <scons_output_command>scons -Q</scons_output_command> </scons_output> --> |