diff options
Diffstat (limited to 'doc/user')
108 files changed, 19944 insertions, 26936 deletions
diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST index 21c63b0..62da288 100644 --- a/doc/user/MANIFEST +++ b/doc/user/MANIFEST @@ -1,3 +1,6 @@ +# We don't use a wildcard for the XML files +# here, because it would pull in the created +# ones as well... actions.xml add-method.xml alias.xml @@ -46,7 +49,11 @@ tools.xml troubleshoot.xml variants.xml variables.xml -SCons-win32-install-1.jpg -SCons-win32-install-2.jpg -SCons-win32-install-3.jpg -SCons-win32-install-4.jpg +*.jpg +*.xsl +*.css +SConstruct +titlepage/bricks.jpg +titlepage/mapnik_final_colors.svg +titlepage/SCons_path.svg +titlepage/SConsBuildBricks_path.svg diff --git a/doc/user/README b/doc/user/README index 7b79162..132d5e4 100644 --- a/doc/user/README +++ b/doc/user/README @@ -1,4 +1,4 @@ -# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation +# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation When adding a new file, add it to main.xml and MANIFEST. diff --git a/doc/user/SConstruct b/doc/user/SConstruct new file mode 100644 index 0000000..fa38396 --- /dev/null +++ b/doc/user/SConstruct @@ -0,0 +1,66 @@ +# +# SConstruct file for building SCons documentation. +# + +# +# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation +# +# 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. + +import os + +env = Environment(ENV={'PATH' : os.environ['PATH']}, + tools=['docbook','gs','zip'], + toolpath=['../../src/engine/SCons/Tool'], + DOCBOOK_DEFAULT_XSL_HTML='html.xsl', + DOCBOOK_DEFAULT_XSL_HTMLCHUNKED='chtml.xsl', + DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl') + +has_pdf = False +if (env.WhereIs('fop') or + env.WhereIs('xep')): + has_pdf = True + +# +# UserGuide for SCons +# +env.DocbookXInclude('scons_xi.xml', 'main.xml') +env.DocbookXslt('scons_ex.xml', 'scons_xi.xml', + xsl='../xslt/xinclude_examples.xslt') +env.DocbookXInclude('scons_exi.xml', 'scons_ex.xml') +env.DocbookXslt('scons_db.xml', 'scons_exi.xml', + xsl='../xslt/to_docbook.xslt') +env.DocbookHtml('index.html','scons_db.xml') +env.DocbookHtmlChunked('index.html', 'scons_db.xml', base_dir='scons-user/') +if has_pdf: + env.DocbookPdf('scons-user.pdf','scons_db.xml') + +has_gs = False +if env.WhereIs('gs'): + has_gs = True + +# +# Create the EPUB format +# +if has_gs and has_pdf: + jpg = env.Gs('OEBPS/cover.jpg','scons-user.pdf', + GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -dJPEGQ=100 -r72x72 -q') + epub = env.DocbookEpub('scons-user.epub', 'scons_db.xml', xsl='epub.xsl') + env.Depends(epub, jpg) diff --git a/doc/user/actions.in b/doc/user/actions.in deleted file mode 100644 index 21e3075..0000000 --- a/doc/user/actions.in +++ /dev/null @@ -1,404 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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. - ---> - -<!-- - -=head1 Build actions - -Cons supports several types of B<build actions> that can be performed -to construct one or more target files. Usually, a build action is -a construction command, that is, a command-line string that invokes -an external command. Cons can also execute Perl code embedded in a -command-line string, and even supports an experimental ability to build -a target file by executing a Perl code reference directly. - -A build action is usually specified as the value of a construction -variable: - - $env = new cons( - CCCOM => '%CC %CFLAGS %_IFLAGS -c %< -o %>', - LINKCOM => '[perl] &link_executable("%>", "%<")', - ARCOM => sub { my($env, $target, @sources) = @_; - # code to create an archive - } - ); - -A build action may be associated directly with one or more target files -via the C<Command> method; see below. - -=head2 Construction commands - -A construction command goes through expansion of construction variables -and C<%-> pseudo-variables, as described above, to create the actual -command line that Cons will execute to generate the target file or -files. - -After substitution occurs, strings of white space are converted into -single blanks, and leading and trailing white space is eliminated. It -is therefore currently not possible to introduce variable length white -space in strings passed into a command. - -If a multi-line command string is provided, the commands are executed -sequentially. If any of the commands fails, then none of the rest are -executed, and the target is not marked as updated, i.e. a new signature is -not stored for the target. - -Normally, if all the commands succeed, and return a zero status (or whatever -platform-specific indication of success is required), then a new signature -is stored for the target. If a command erroneously reports success even -after a failure, then Cons will assume that the target file created by that -command is accurate and up-to-date. - -The first word of each command string, after expansion, is assumed to be an -executable command looked up on the C<PATH> environment variable (which is, -in turn, specified by the C<ENV> construction variable). If this command is -found on the path, then the target will depend upon it: the command will -therefore be automatically built, as necessary. It's possible to write -multi-part commands to some shells, separated by semi-colons. Only the first -command word will be depended upon, however, so if you write your command -strings this way, you must either explicitly set up a dependency (with the -C<Depends> method), or be sure that the command you are using is a system -command which is expected to be available. If it isn't available, you will, -of course, get an error. - -Cons normally prints a command before executing it. This behavior is -suppressed if the first character of the command is C<@>. Note that -you may need to separate the C<@> from the command name or escape it to -prevent C<@cmd> from looking like an array to Perl quote operators that -perform interpolation: - - # The first command line is incorrect, - # because "@cp" looks like an array - # to the Perl qq// function. - # Use the second form instead. - Command $env 'foo', 'foo.in', qq( - @cp %< tempfile - @ cp tempfile %> - ); - -If there are shell meta characters anywhere in the expanded command line, -such as C<E<lt>>, C<E<gt>>, quotes, or semi-colon, then the command -will actually be executed by invoking a shell. This means that a command -such as: - - cd foo - -alone will typically fail, since there is no command C<cd> on the path. But -the command string: - - cd $<:d; tar cf $>:f $<:f - -when expanded will still contain the shell meta character semi-colon, and a -shell will be invoked to interpret the command. Since C<cd> is interpreted -by this sub-shell, the command will execute as expected. - -=head2 Perl expressions - -If any command (even one within a multi-line command) begins with -C<[perl]>, the remainder of that command line will be evaluated by the -running Perl instead of being forked by the shell. If an error occurs -in parsing the Perl code, or if the Perl expression returns 0 or undef, -the command will be considered to have failed. For example, here is a -simple command which creates a file C<foo> directly from Perl: - - $env = new cons(); - Command $env 'foo', - qq([perl] open(FOO,'>foo');print FOO "hi\\n"; close(FOO); 1); - -Note that when the command is executed, you are in the same package as -when the F<Construct> or F<Conscript> file was read, so you can call -Perl functions you've defined in the same F<Construct> or F<Conscript> -file in which the C<Command> appears: - - $env = new cons(); - sub create_file { - my $file = shift; - open(FILE, ">$file"); - print FILE "hi\n"; - close(FILE); - return 1; - } - Command $env 'foo', "[perl] &create_file('%>')"; - -The Perl string will be used to generate the signature for the derived -file, so if you change the string, the file will be rebuilt. The contents -of any subroutines you call, however, are not part of the signature, -so if you modify a called subroutine such as C<create_file> above, -the target will I<not> be rebuilt. Caveat user. - -=head2 Perl code references [EXPERIMENTAL] - -Cons supports the ability to create a derived file by directly executing -a Perl code reference. This feature is considered EXPERIMENTAL and -subject to change in the future. - -A code reference may either be a named subroutine referenced by the -usual C<\&> syntax: - - sub build_output { - my($env, $target, @sources) = @_; - print "build_output building $target\n"; - open(OUT, ">$target"); - foreach $src (@sources) { - if (! open(IN, "<$src")) { - print STDERR "cannot open '$src': $!\n"; - return undef; - } - print OUT, <IN>; - } - close(OUT); - return 1; - } - Command $env 'output', \&build_output; - -or the code reference may be an anonymous subroutine: - - Command $env 'output', sub { - my($env, $target, @sources) = @_; - print "building $target\n"; - open(FILE, ">$target"); - print FILE "hello\n"; - close(FILE); - return 1; - }; - -To build the target file, the referenced subroutine is passed, in order: -the construction environment used to generate the target; the path -name of the target itself; and the path names of all the source files -necessary to build the target file. - -The code reference is expected to generate the target file, of course, -but may manipulate the source and target files in any way it chooses. -The code reference must return a false value (C<undef> or C<0>) if -the build of the file failed. Any true value indicates a successful -build of the target. - -Building target files using code references is considered EXPERIMENTAL -due to the following current limitations: - -=over 4 - -Cons does I<not> print anything to indicate the code reference is being -called to build the file. The only way to give the user any indication -is to have the code reference explicitly print some sort of "building" -message, as in the above examples. - -Cons does not generate any signatures for code references, so if the -code in the reference changes, the target will I<not> be rebuilt. - -Cons has no public method to allow a code reference to extract -construction variables. This would be good to allow generalization of -code references based on the current construction environment, but would -also complicate the problem of generating meaningful signatures for code -references. - -=back - -Support for building targets via code references has been released in -this version to encourage experimentation and the seeking of possible -solutions to the above limitations. - ---> - - <para> - - &SCons; supports several types of &build_actions; - that can be performed to build one or more target files. - Usually, a &build_action; is a command-line string - that invokes an external command. - A build action can also be an external command - specified as a list of arguments, - or even a Python function. - - </para> - - <para> - - Build action objects are created by the &Action; function. - This function is, in fact, what &SCons; uses - to interpret the &action; - keyword argument when you call the &Builder; function. - So the following line that creates a simple Builder: - - </para> - - <sconstruct> - b = Builder(action = 'build < $SOURCE > $TARGET') - </sconstruct> - - <para> - - Is equivalent to: - - </para> - - <sconstruct> - b = Builder(action = Action('build < $SOURCE > $TARGET')) - </sconstruct> - - <para> - - The advantage of using the &Action; function directly - is that it can take a number of additional options - to modify the action's behavior in many useful ways. - - </para> - - <section> - <title>Command Strings as Actions</title> - - <section> - <title>Suppressing Command-Line Printing</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>Ignoring Exit Status</title> - - <para> - - XXX - - </para> - - </section> - - </section> - - <section> - <title>Argument Lists as Actions</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>Python Functions as Actions</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>Modifying How an Action is Printed</title> - - <section> - <title>XXX: the &strfunction; keyword argument</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>XXX: the &cmdstr; keyword argument</title> - - <para> - - XXX - - </para> - - </section> - - </section> - - <section> - <title>Making an Action Depend on Variable Contents: the &varlist; keyword argument</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>chdir=1</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>Batch Building of Multiple Targets from Separate Sources: the &batch_key; keyword argument</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>Manipulating the Exit Status of an Action: the &exitstatfunc; keyword argument</title> - - <para> - - XXX - - </para> - - </section> - - <!-- - - ??? - - <section> - <title>presub=</title> - - <para> - - XXX - - </para> - - </section> - - --> diff --git a/doc/user/actions.xml b/doc/user/actions.xml index 4a99a24..7973549 100644 --- a/doc/user/actions.xml +++ b/doc/user/actions.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-actions" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>&SCons; Actions</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -244,9 +266,9 @@ solutions to the above limitations. </para> - <programlisting> - b = Builder(action = 'build < $SOURCE > $TARGET') - </programlisting> + <sconstruct> +b = Builder(action = 'build < $SOURCE > $TARGET') + </sconstruct> <para> @@ -254,9 +276,9 @@ solutions to the above limitations. </para> - <programlisting> - b = Builder(action = Action('build < $SOURCE > $TARGET')) - </programlisting> + <sconstruct> +b = Builder(action = Action('build < $SOURCE > $TARGET')) + </sconstruct> <para> @@ -402,3 +424,5 @@ solutions to the above limitations. </section> --> + +</chapter> diff --git a/doc/user/add-method.in b/doc/user/add-method.in deleted file mode 100644 index a0c21a3..0000000 --- a/doc/user/add-method.in +++ /dev/null @@ -1,127 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - The &AddMethod; function is used to add a method - to an environment. It's typically used to add a "pseudo-builder," - a function that looks like a &Builder; but - wraps up calls to multiple other &Builder;s - or otherwise processes its arguments - before calling one or more &Builder;s. - In the following example, - we want to install the program into the standard - <filename>/usr/bin</filename> directory hierarchy, - but also copy it into a local <filename>install/bin</filename> - directory from which a package might be built: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - def install_in_bin_dirs(env, source): - """Install source in both bin dirs""" - i1 = env.Install("$BIN", source) - i2 = env.Install("$LOCALBIN", source) - return [i1[0], i2[0]] # Return a list, like a normal builder - env = Environment(BIN='__ROOT__/usr/bin', LOCALBIN='#install/bin') - env.AddMethod(install_in_bin_dirs, "InstallInBinDirs") - env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - This produces the following: - </para> - - <scons_output example="ex1"> - <scons_output_command>scons -Q /</scons_output_command> - </scons_output> - - <para> - - As mentioned, a pseudo-builder also provides more flexibility - in parsing arguments than you can get with a &Builder;. - The next example shows a pseudo-builder with a - named argument that modifies the filename, and a separate argument - for the resource file (rather than having the builder figure it out - by file extension). This example also demonstrates using the global - &AddMethod; function to add a method to the global Environment class, - so it will be used in all subsequently created environments. - - </para> - - <scons_example name="ex2"> - <file name="SConstruct" printme="1"> - def BuildTestProg(env, testfile, resourcefile, testdir="tests"): - """Build the test program; - prepends "test_" to src and target, - and puts target into testdir.""" - srcfile = "test_%s.c" % testfile - target = "%s/test_%s" % (testdir, testfile) - if env['PLATFORM'] == 'win32': - resfile = env.RES(resourcefile) - p = env.Program(target, [srcfile, resfile]) - else: - p = env.Program(target, srcfile) - return p - AddMethod(Environment, BuildTestProg) - - env = Environment() - env.BuildTestProg('stuff', resourcefile='res.rc') - </file> - <file name="test_stuff.c"> - int main() { printf("Hello, world!\n"); } - </file> - <file name="res.rc"> - res.rc - </file> - </scons_example> - - <para> - This produces the following on Linux: - </para> - - <scons_output example="ex2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - And the following on Windows: - </para> - - <scons_output example="ex2" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - Using &AddMethod; is better than just adding an instance method - to a &consenv; because it gets called as a proper method, - and because &AddMethod; provides for copying the method - to any clones of the &consenv; instance. - </para> diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml index 717f24c..50a2d01 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-add-method" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Pseudo-Builders: the AddMethod function</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -39,28 +61,29 @@ </para> - <programlisting> - def install_in_bin_dirs(env, source): - """Install source in both bin dirs""" - i1 = env.Install("$BIN", source) - i2 = env.Install("$LOCALBIN", source) - return [i1[0], i2[0]] # Return a list, like a normal builder - env = Environment(BIN='/usr/bin', LOCALBIN='#install/bin') - env.AddMethod(install_in_bin_dirs, "InstallInBinDirs") - env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs - </programlisting> + <scons_example name="addmethod_ex1"> + <file name="SConstruct" printme="1"> +def install_in_bin_dirs(env, source): + """Install source in both bin dirs""" + i1 = env.Install("$BIN", source) + i2 = env.Install("$LOCALBIN", source) + return [i1[0], i2[0]] # Return a list, like a normal builder +env = Environment(BIN='__ROOT__/usr/bin', LOCALBIN='#install/bin') +env.AddMethod(install_in_bin_dirs, "InstallInBinDirs") +env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> This produces the following: </para> - <screen> - % <userinput>scons -Q /</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - Install file: "hello" as "/usr/bin/hello" - Install file: "hello" as "install/bin/hello" - </screen> + <scons_output example="addmethod_ex1" suffix="1"> + <scons_output_command>scons -Q /</scons_output_command> + </scons_output> <para> @@ -75,46 +98,48 @@ </para> - <programlisting> - def BuildTestProg(env, testfile, resourcefile, testdir="tests"): - """Build the test program; - prepends "test_" to src and target, - and puts target into testdir.""" - srcfile = "test_%s.c" % testfile - target = "%s/test_%s" % (testdir, testfile) - if env['PLATFORM'] == 'win32': - resfile = env.RES(resourcefile) - p = env.Program(target, [srcfile, resfile]) - else: - p = env.Program(target, srcfile) - return p - AddMethod(Environment, BuildTestProg) - - env = Environment() - env.BuildTestProg('stuff', resourcefile='res.rc') - </programlisting> + <scons_example name="addmethod_ex2"> + <file name="SConstruct" printme="1"> +def BuildTestProg(env, testfile, resourcefile, testdir="tests"): + """Build the test program; + prepends "test_" to src and target, + and puts target into testdir.""" + srcfile = "test_%s.c" % testfile + target = "%s/test_%s" % (testdir, testfile) + if env['PLATFORM'] == 'win32': + resfile = env.RES(resourcefile) + p = env.Program(target, [srcfile, resfile]) + else: + p = env.Program(target, srcfile) + return p +AddMethod(Environment, BuildTestProg) + +env = Environment() +env.BuildTestProg('stuff', resourcefile='res.rc') + </file> + <file name="test_stuff.c"> +int main() { printf("Hello, world!\n"); } + </file> + <file name="res.rc"> +res.rc + </file> + </scons_example> <para> This produces the following on Linux: </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o test_stuff.o -c test_stuff.c - cc -o tests/test_stuff test_stuff.o - </screen> + <scons_output example="addmethod_ex2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> And the following on Windows: </para> - <screen> - C:\><userinput>scons -Q</userinput> - rc /fores.res res.rc - cl /Fotest_stuff.obj /c test_stuff.c /nologo - link /nologo /OUT:tests\test_stuff.exe test_stuff.obj res.res - embedManifestExeCheck(target, source, env) - </screen> + <scons_output example="addmethod_ex2" os="win32" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> Using &AddMethod; is better than just adding an instance method @@ -122,3 +147,5 @@ and because &AddMethod; provides for copying the method to any clones of the &consenv; instance. </para> + +</chapter> diff --git a/doc/user/alias.in b/doc/user/alias.in deleted file mode 100644 index 9d1a596..0000000 --- a/doc/user/alias.in +++ /dev/null @@ -1,102 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - We've already seen how you can use the &Alias; - function to create a target named <literal>install</literal>: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - env = Environment() - hello = env.Program('hello.c') - env.Install('__ROOT__/usr/bin', hello) - env.Alias('install', '__ROOT__/usr/bin') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - You can then use this alias on the command line - to tell &SCons; more naturally that you want to install files: - - </para> - - <scons_output example="ex1" os="posix"> - <scons_output_command>scons -Q install</scons_output_command> - </scons_output> - - <para> - - Like other &Builder; methods, though, - the &Alias; method returns an object - representing the alias being built. - You can then use this object as input to anothother &Builder;. - This is especially useful if you use such an object - as input to another call to the &Alias; &Builder;, - allowing you to create a hierarchy - of nested aliases: - - </para> - - <scons_example name="ex2"> - <file name="SConstruct" printme="1"> - env = Environment() - p = env.Program('foo.c') - l = env.Library('bar.c') - env.Install('__ROOT__/usr/bin', p) - env.Install('__ROOT__/usr/lib', l) - ib = env.Alias('install-bin', '__ROOT__/usr/bin') - il = env.Alias('install-lib', '__ROOT__/usr/lib') - env.Alias('install', [ib, il]) - </file> - <file name="foo.c"> - int main() { printf("foo.c\n"); } - </file> - <file name="bar.c"> - void bar() { printf("bar.c\n"); } - </file> - </scons_example> - - <para> - - This example defines separate <literal>install</literal>, - <literal>install-bin</literal>, - and <literal>install-lib</literal> aliases, - allowing you finer control over what gets installed: - - </para> - - <scons_output example="ex2" os="posix"> - <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/alias.xml b/doc/user/alias.xml index 47b1da9..883ebef 100644 --- a/doc/user/alias.xml +++ b/doc/user/alias.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-alias" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Alias Targets</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -30,12 +52,17 @@ </para> - <programlisting> - env = Environment() - hello = env.Program('hello.c') - env.Install('/usr/bin', hello) - env.Alias('install', '/usr/bin') - </programlisting> + <scons_example name="alias_ex1"> + <file name="SConstruct" printme="1"> +env = Environment() +hello = env.Program('hello.c') +env.Install('__ROOT__/usr/bin', hello) +env.Alias('install', '__ROOT__/usr/bin') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -44,12 +71,9 @@ </para> - <screen> - % <userinput>scons -Q install</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - Install file: "hello" as "/usr/bin/hello" - </screen> + <scons_output example="alias_ex1" os="posix" suffix="1"> + <scons_output_command>scons -Q install</scons_output_command> + </scons_output> <para> @@ -64,16 +88,24 @@ </para> - <programlisting> - env = Environment() - p = env.Program('foo.c') - l = env.Library('bar.c') - env.Install('/usr/bin', p) - env.Install('/usr/lib', l) - ib = env.Alias('install-bin', '/usr/bin') - il = env.Alias('install-lib', '/usr/lib') - env.Alias('install', [ib, il]) - </programlisting> + <scons_example name="alias_ex2"> + <file name="SConstruct" printme="1"> +env = Environment() +p = env.Program('foo.c') +l = env.Library('bar.c') +env.Install('__ROOT__/usr/bin', p) +env.Install('__ROOT__/usr/lib', l) +ib = env.Alias('install-bin', '__ROOT__/usr/bin') +il = env.Alias('install-lib', '__ROOT__/usr/lib') +env.Alias('install', [ib, il]) + </file> + <file name="foo.c"> +int main() { printf("foo.c\n"); } + </file> + <file name="bar.c"> +void bar() { printf("bar.c\n"); } + </file> + </scons_example> <para> @@ -84,29 +116,11 @@ </para> - <screen> - % <userinput>scons -Q install-bin</userinput> - cc -o foo.o -c foo.c - cc -o foo foo.o - Install file: "foo" as "/usr/bin/foo" - % <userinput>scons -Q install-lib</userinput> - cc -o bar.o -c bar.c - ar rc libbar.a bar.o - ranlib libbar.a - Install file: "libbar.a" as "/usr/lib/libbar.a" - % <userinput>scons -Q -c /</userinput> - Removed foo.o - Removed foo - Removed /usr/bin/foo - Removed bar.o - Removed libbar.a - Removed /usr/lib/libbar.a - % <userinput>scons -Q install</userinput> - cc -o foo.o -c foo.c - cc -o foo foo.o - Install file: "foo" as "/usr/bin/foo" - cc -o bar.o -c bar.c - ar rc libbar.a bar.o - ranlib libbar.a - Install file: "libbar.a" as "/usr/lib/libbar.a" - </screen> + <scons_output example="alias_ex2" os="posix" suffix="1"> + <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> + +</chapter> diff --git a/doc/user/ant.in b/doc/user/ant.in deleted file mode 100644 index 87ad4b0..0000000 --- a/doc/user/ant.in +++ /dev/null @@ -1,52 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - XXX - - </para> - - <section> - <title>Differences Between &Ant; and &SCons;</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>Advantages of &SCons; Over &Ant;</title> - - <para> - - XXX - - </para> - - </section> diff --git a/doc/user/ant.xml b/doc/user/ant.xml index 87ad4b0..1808d9e 100644 --- a/doc/user/ant.xml +++ b/doc/user/ant.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<appendix id="app-ant" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Converting From Ant</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -50,3 +72,5 @@ </para> </section> + +</appendix> diff --git a/doc/user/build-install.in b/doc/user/build-install.in deleted file mode 100644 index 57f4b84..0000000 --- a/doc/user/build-install.in +++ /dev/null @@ -1,709 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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 chapter will take you through the basic steps - of installing &SCons; on your system, - and building &SCons; if you don't have a - pre-built package available - (or simply prefer the flexibility of building it yourself). - Before that, however, this chapter will also describe the basic steps - involved in installing Python on your system, - in case that is necessary. - Fortunately, both &SCons; and Python - are very easy to install on almost any system, - and Python already comes installed on many systems. - - </para> - - <!-- - - <para> - - Lastly, this chapter also contains a section that - provides a brief overview of the Python programming language, - which is the language used to implement &SCons;, - and which forms the basis of the &SCons; configuration files. - Becoming familiar with some Python concepts will make it easier - to understand many of the examples in this User's Guide. - Nevertheless, it <emphasis>is</emphasis> possible - to configure simple &SCons; builds without knowing Python, - so you can skip this section if you - want to dive in and pick up things - by example- -or, of course, if you are - already familiar with Python. - - </para> - - --> - - <section> - <title>Installing Python</title> - - <para> - - Because &SCons; is written in Python, - you must obviously have Python installed on your system - to use &SCons;. - Before you try to install Python, - you should check to see if Python is already - available on your system by typing - <userinput>python -V</userinput> - (capital 'V') - or - <userinput>python --version</userinput> - at your system's command-line prompt. - - </para> - - <screen> - $ <userinput>python -V</userinput> - Python 2.5.1 - </screen> - - <para> - - And on a Windows system with Python installed: - - </para> - - <screen> - C:\><userinput>python -V</userinput> - Python 2.5.1 - </screen> - - <para> - - If Python is not installed on your system, - you will see an error message - stating something like "command not found" - (on UNIX or Linux) - or "'python' is not recognized - as an internal or external command, operable progam or batch file" - (on Windows). - In that case, you need to install Python - before you can install &SCons;. - - </para> - - <para> - - The standard location for information - about downloading and installing Python is - <ulink url="http://www.python.org/download/">http://www.python.org/download/</ulink>. - See that page for information about - how to download and install Python on your system. - - </para> - - <para> - - &SCons; will work with any 2.x version of Python from 2.4 on; - 3.0 and later are not yet supported. - If you need to install Python and have a choice, - we recommend using the most recent 2.x Python version available. - Newer Pythons have significant improvements - that help speed up the performance of &SCons;. - - </para> - - </section> - - <section> - <title>Installing &SCons; From Pre-Built Packages</title> - - <para> - - &SCons; comes pre-packaged for installation on a number of systems, - including Linux and Windows systems. - You do not need to read this entire section, - you should need to read only the section - appropriate to the type of system you're running on. - - </para> - - <section> - <title>Installing &SCons; on Red Hat (and Other RPM-based) Linux Systems</title> - - <para> - - &SCons; comes in RPM (Red Hat Package Manager) format, - pre-built and ready to install on Red Hat Linux, - Fedora, - or any other Linux distribution that uses RPM. - Your distribution may - already have an &SCons; RPM built specifically for it; - many do, including SUSE, Mandrake and Fedora. - You can check for the availability of an &SCons; RPM - on your distribution's download servers, - or by consulting an RPM search site like - <ulink url="http://www.rpmfind.net/">http://www.rpmfind.net/</ulink> or - <ulink url="http://rpm.pbone.net/">http://rpm.pbone.net/</ulink>. - - </para> - - <para> - - If your distribution supports installation via - <application>yum</application>, - you should be able to install &SCons; by running: - - </para> - - <screen> - # <userinput>yum install scons</userinput> - </screen> - - <para> - - If your Linux distribution does not already have - a specific &SCons; RPM file, - you can download and install from the - generic RPM provided by the &SCons; project. - This will install the - SCons script(s) in <filename>/usr/bin</filename>, - and the SCons library modules in - <filename>/usr/lib/scons</filename>. - - </para> - - <para> - - To install from the command line, simply download the - appropriate <filename>.rpm</filename> file, - and then run: - - </para> - - <screen> - # <userinput>rpm -Uvh scons-2.3.0-1.noarch.rpm</userinput> - </screen> - - <para> - - Or, you can use a graphical RPM package manager. - See your package manager application's documention - for specific instructions about - how to use it to install a downloaded RPM. - - </para> - - </section> - - <section> - <title>Installing &SCons; on Debian Linux Systems</title> - - <para> - - Debian Linux systems use a different package management - format that also makes it very easy to install &SCons;. - - </para> - - <para> - - If your system is connected to the Internet, - you can install the latest official Debian package - by running: - - </para> - - <screen> - # <userinput>apt-get install scons</userinput> - </screen> - - <!-- - - <para> - - Alternatively, - you can download the Debian package built - by the &SCons; project - and install it manually by running: - - </para> - - <screen> - # <userinput>db-XXX scons-*.deb</userinput> - </screen> - - --> - - </section> - - <section> - <title>Installing &SCons; on Windows Systems</title> - - <para> - - &SCons; provides a Windows installer - that makes installation extremely easy. - Download the <filename>scons-2.3.0.win32.exe</filename> - file from the &SCons; download page at - <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</ulink>. - Then all you need to do is execute the file - (usually by clicking on its icon in Windows Explorer). - These will take you through a small - sequence of windows that will install - &SCons; on your system. - - <!-- - Things are a little more complicated - if you are using the Cygwin version of Python. - This is because Cygwin - tries to make a Windows system look more - POSIX-like (or UNIX-like or Linux-like, if you prefer) - by having the Cygwin utilities, - including Cygwin Python, - interpret file name arguments on the command line - using the forward-slash (<filename>/</filename>) - as the directory separator, - instead of the normal Windows behavior of the - backslash (<filename>\</filename>) as the directory separator. - --> - - </para> - - <!-- - - <section> - <title>Installing &SCons; on Windows Systems Without Cygwin Python</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>Installing &SCons; on Windows Systems With Cygwin Python</title> - - <para> - - XXX - - </para> - - </section> - - --> - - <!-- - - XXX - don't have the kinks worked out on how to - get these to display properly in all formats, - so comment them out for now. - - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="SCons-win32-install-1.jpg" format="jpg" align="center"> - </imageobject> - </mediaobject> - </screenshot> - - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="SCons-win32-install-2.jpg" format="jpg" align="center"> - </imageobject> - </mediaobject> - </screenshot> - - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="SCons-win32-install-3.jpg" format="jpg" align="center"> - </imageobject> - </mediaobject> - </screenshot> - - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="SCons-win32-install-4.jpg" format="jpg" align="center"> - </imageobject> - </mediaobject> - </screenshot> - - --> - - </section> - - </section> - - <section> - <title>Building and Installing &SCons; on Any System</title> - - <para> - - If a pre-built &SCons; package is not available for your system, - then you can still easily build and install &SCons; using the native - Python <filename>distutils</filename> package. - - </para> - - <para> - - The first step is to download either the - <filename>scons-2.3.0.tar.gz</filename> - or <filename>scons-2.3.0.zip</filename>, - which are available from the SCons download page at - <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>. - - </para> - - <para> - - Unpack the archive you downloaded, - using a utility like <application>tar</application> - on Linux or UNIX, - or <application>WinZip</application> on Windows. - This will create a directory called - <filename>scons-2.3.0</filename>, - usually in your local directory. - Then change your working directory to that directory - and install &SCons; by executing the following commands: - - </para> - - <screen> - # <userinput>cd scons-2.3.0</userinput> - # <userinput>python setup.py install</userinput> - </screen> - - <para> - - This will build &SCons;, - install the &scons; script - in the python which is used to run the setup.py's scripts directory - (<filename>/usr/local/bin</filename> or - <filename>C:\Python25\Scripts</filename>), - and will install the &SCons; build engine - in the corresponding library directory for the python used - (<filename>/usr/local/lib/scons</filename> or - <filename>C:\Python25\scons</filename>). - Because these are system directories, - you may need root (on Linux or UNIX) or Administrator (on Windows) - privileges to install &SCons; like this. - - </para> - - <!-- - - <section> - <title>Building and Installing &SCons; in the Standard Python Library Directories</title> - - <para> - - XXX - - </para> - - </section> - - --> - - <section> - <title>Building and Installing Multiple Versions of &SCons; Side-by-Side</title> - - <para> - - The &SCons; <filename>setup.py</filename> script - has some extensions that support - easy installation of multiple versions of &SCons; - in side-by-side locations. - This makes it easier to download and - experiment with different versions of &SCons; - before moving your official build process to a new version, - for example. - - </para> - - <para> - - To install &SCons; in a version-specific location, - add the <option>--version-lib</option> option - when you call <filename>setup.py</filename>: - - </para> - - <screen> - # <userinput>python setup.py install --version-lib</userinput> - </screen> - - <para> - - This will install the &SCons; build engine - in the - <filename>/usr/lib/scons-2.3.0</filename> - or - <filename>C:\Python25\scons-2.3.0</filename> - directory, for example. - - </para> - - <para> - - If you use the <option>--version-lib</option> option - the first time you install &SCons;, - you do not need to specify it each time you install - a new version. - The &SCons; <filename>setup.py</filename> script - will detect the version-specific directory name(s) - and assume you want to install all versions - in version-specific directories. - You can override that assumption in the future - by explicitly specifying the <option>--standalone-lib</option> option. - - </para> - - </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-2.3.0</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 &scons; 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> - - <para> - - This can also be used to experiment with a newer - version of &SCons; than the one installed - in your system locations. - Of course, the location in which you install the - newer version of the &scons; script - (<filename>$HOME/bin</filename> in the above example) - must be configured in your &PATH; variable - before the directory containing - the system-installed version - of the &scons; script. - - </para> - - </section> - - </section> - - <!-- - - <section> - <title>Python Basics</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/build-install.xml b/doc/user/build-install.xml index 57f4b84..d3e0875 100644 --- a/doc/user/build-install.xml +++ b/doc/user/build-install.xml @@ -1,6 +1,32 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + + <!ENTITY % version SYSTEM "../version.xml"> + %version; + + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-build-install" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Building and Installing &SCons;</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -80,8 +106,8 @@ </para> <screen> - $ <userinput>python -V</userinput> - Python 2.5.1 +$ <userinput>python -V</userinput> +Python 2.5.1 </screen> <para> @@ -91,8 +117,8 @@ </para> <screen> - C:\><userinput>python -V</userinput> - Python 2.5.1 +C:\><userinput>python -V</userinput> +Python 2.5.1 </screen> <para> @@ -174,7 +200,7 @@ </para> <screen> - # <userinput>yum install scons</userinput> +# <userinput>yum install scons</userinput> </screen> <para> @@ -199,7 +225,7 @@ </para> <screen> - # <userinput>rpm -Uvh scons-2.3.0-1.noarch.rpm</userinput> +# <userinput>rpm -Uvh scons-&buildversion;-1.noarch.rpm</userinput> </screen> <para> @@ -232,7 +258,7 @@ </para> <screen> - # <userinput>apt-get install scons</userinput> +# <userinput>apt-get install scons</userinput> </screen> <!-- @@ -247,7 +273,7 @@ </para> <screen> - # <userinput>db-XXX scons-*.deb</userinput> +# <userinput>db-XXX scons-*.deb</userinput> </screen> --> @@ -261,7 +287,7 @@ &SCons; provides a Windows installer that makes installation extremely easy. - Download the <filename>scons-2.3.0.win32.exe</filename> + Download the <filename>scons-&buildversion;.win32.exe</filename> file from the &SCons; download page at <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</ulink>. Then all you need to do is execute the file @@ -371,8 +397,8 @@ <para> The first step is to download either the - <filename>scons-2.3.0.tar.gz</filename> - or <filename>scons-2.3.0.zip</filename>, + <filename>scons-&buildversion;.tar.gz</filename> + or <filename>scons-&buildversion;.zip</filename>, which are available from the SCons download page at <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>. @@ -385,7 +411,7 @@ on Linux or UNIX, or <application>WinZip</application> on Windows. This will create a directory called - <filename>scons-2.3.0</filename>, + <filename>scons-&buildversion;</filename>, usually in your local directory. Then change your working directory to that directory and install &SCons; by executing the following commands: @@ -393,8 +419,8 @@ </para> <screen> - # <userinput>cd scons-2.3.0</userinput> - # <userinput>python setup.py install</userinput> +# <userinput>cd scons-&buildversion;</userinput> +# <userinput>python setup.py install</userinput> </screen> <para> @@ -454,16 +480,16 @@ </para> <screen> - # <userinput>python setup.py install --version-lib</userinput> +# <userinput>python setup.py install --version-lib</userinput> </screen> <para> This will install the &SCons; build engine in the - <filename>/usr/lib/scons-2.3.0</filename> + <filename>/usr/lib/scons-&buildversion;</filename> or - <filename>C:\Python25\scons-2.3.0</filename> + <filename>C:\Python25\scons-&buildversion;</filename> directory, for example. </para> @@ -496,7 +522,7 @@ </para> <screen> - # <userinput>python setup.py install --prefix=/opt/scons</userinput> +# <userinput>python setup.py install --prefix=/opt/scons</userinput> </screen> <para> @@ -520,7 +546,7 @@ 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-2.3.0</filename>. + <filename>/opt/scons/lib/scons-&buildversion;</filename>. </para> @@ -547,7 +573,7 @@ </para> <screen> - $ <userinput>python setup.py install --prefix=$HOME</userinput> +$ <userinput>python setup.py install --prefix=$HOME</userinput> </screen> <para> @@ -707,3 +733,5 @@ </section> --> + +</chapter> diff --git a/doc/user/builders-built-in.in b/doc/user/builders-built-in.in deleted file mode 100644 index f248d76..0000000 --- a/doc/user/builders-built-in.in +++ /dev/null @@ -1,950 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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 the ability to build a lot of different - types of files right "out of the box." - So far, we've been using &SCons;' ability to build - programs, objects and libraries to - illustrate much of the underlying functionality of &SCons; - This section will describe all of the different - types of files that you can build with &SCons;, - and the built-in &Builder; objects used to build them. - By default, all of the &Builder; objects in this section - can be built either with or without an explicit - construction environment. - - </para> - - <section> - <title>Programs: the &Program; Builder</title> - - <para> - - 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, - and the ⌖ argument is the - name of the executable program name to be created. - For example: - - </para> - - <programlisting> - Program('prog', 'file1.o') - </programlisting> - - <para> - - Will create the &prog; - executable on a POSIX system, - the &prog_exe; executable on a Windows system. - - </para> - - <para> - - The target file's prefix and suffix may be omitted, - and the values from the - &cv-link-PROGPREFIX; - and - &cv-link-PROGSUFFIX; - construction variables - will be appended appropriately. - For example: - - </para> - - <programlisting> - env = Environment(PROGPREFIX='my', PROGSUFFIX='.xxx') - env.Program('prog', ['file1.o', 'file2.o']) - </programlisting> - - <para> - - Will create a program named - <filename>myprog.xxx</filename> - regardless of the system on which it is run. - - </para> - - <para> - - If you omit the ⌖, - the base of the first input - file name specified - becomes the base of the target - program created. - For example: - - </para> - - <programlisting> - Program(['hello.c', 'goodbye.c']) - </programlisting> - - <para> - - Will create the &hello; - executable on a POSIX system, - the &hello_exe; executable on a Windows system. - - </para> - - <para> - - Two construction variables control what libraries - will be linked with the resulting program. - The &cv-link-LIBS; variable is a list of the names of - libraries that will be linked into any programs, - 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 - options for the running system. - For example: - - </para> - - <scons_example name="libs"> - <file name="SConstruct" printme="1"> - env = Environment(LIBS = ['foo1', 'foo2'], - LIBPATH = ['/usr/dir1', 'dir2']) - env.Program(['hello.c', 'goodbye.c']) - </file> - <file name="hello.c"> - int hello() { printf("Hello, world!\n"); } - </file> - <file name="goodbye.c"> - int goodbye() { printf("Goodbye, world!\n"); } - </file> - </scons_example> - - <para> - - Will execute as follows on a POSIX system: - - </para> - - <scons_output example="libs" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - And execute as follows on a Windows system: - - </para> - - <scons_output example="libs" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - The &cv-LIBS; construction variable - is turned into command line options - by appending the &cv-link-LIBLINKPREFIX; and &cv-link-LIBLINKSUFFIX; - construction variables to the beginning and end, - respectively, of each specified library. - - </para> - - <para> - - The &cv-LIBPATH; construction variable - is turned into command line options - by appending the &cv-link-LIBDIRPREFIX; and &cv-link-LIBDIRSUFFIX; - construction variables to the beginning and end, - respectively, of each specified library. - - </para> - - <para> - - Other relevant construction variables - include those used by the &b-link-Object; - builders to affect how the - source files specified as input to the &t-Program; - builders are turned into object files; - see the next section. - - </para> - - <para> - - The command line used to control how a program is linked - is specified by the &cv-link-LINKCOM; construction variable. - By default, it uses the - &cv-link-LINK; construction variable - and the &cv-link-LINKFLAGS; construction variable. - - </para> - - </section> - - <section> - <title>Object-File Builders</title> - - <para> - - &SCons; provides separate Builder objects - to create static and shared object files. - The distinction becomes especially important when - archiving object files into different types of libraries. - - </para> - - <section> - <title>The &StaticObject; Builder</title> - - <para> - - 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. - The &source; argument is a single source-code file, - and the ⌖ argument is the - name of the static object file to be created. - For example: - - </para> - - <programlisting> - StaticObject('file', 'file.c') - </programlisting> - - <para> - - Will create the &file_o; - object file on a POSIX system, - the &file_obj; executable on a Windows system. - - </para> - - <para> - - The target file's prefix and suffix may be omitted, - and the values from the - &cv-link-OBJPREFIX; - and - &cv-link-OBJSUFFIX; - construction variables - will be appended appropriately. - For example: - - </para> - - <programlisting> - env = Environment(OBJPREFIX='my', OBJSUFFIX='.xxx') - env.StaticObject('file', 'file.c') - </programlisting> - - <para> - - Will create an object file named - <filename>myfile.xxx</filename> - regardless of the system on which it is run. - - </para> - - <para> - - If you omit the ⌖, - the base of the first input - file name specified - beomces the base of the name - of the static object file to be created. - For example: - - </para> - - <programlisting> - StaticObject('file.c') - </programlisting> - - <para> - - Will create the &file_o; - executable on a POSIX system, - the &file_obj; executable on a Windows system. - - </para> - - </section> - - <section> - <title>The &SharedObject; Builder</title> - - <para> - - 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. - The &source; argument is a single source-code file, - and the ⌖ argument is the - name of the shared object file to be created. - For example: - - </para> - - <programlisting> - SharedObject('file', 'file.c') - </programlisting> - - <para> - - Will create the &file_o; - object file on a POSIX system, - the &file_obj; executable on a Windows system. - - </para> - - <para> - - The target file's prefix and suffix may be omitted, - and the values from the - &cv-link-SHOBJPREFIX; - and - &cv-link-SHOBJSUFFIX; - construction variables - will be appended appropriately. - For example: - - </para> - - <programlisting> - env = Environment(SHOBJPREFIX='my', SHOBJSUFFIX='.xxx') - env.SharedObject('file', 'file.c') - </programlisting> - - <para> - - Will create an object file named - <filename>myfile.xxx</filename> - regardless of the system on which it is run. - - </para> - - <para> - - If you omit the ⌖, - the base of the first input - file name specified - becomes the base of the name - of the shared object file to be created. - For example: - - </para> - - <programlisting> - SharedObject('file.c') - </programlisting> - - <para> - - Will create the &file_o; - executable on a POSIX system, - the &file_obj; executable on a Windows system. - - </para> - - </section> - - <section> - <title>The &Object; Builder</title> - - <para> - - The &b-link-Object; Builder is a synonym for &b-link-StaticObject; - and is completely equivalent. - - </para> - - </section> - - </section> - - <section> - <title>Library Builders</title> - - <para> - - &SCons; provides separate Builder objects - to create static and shared libraries. - - </para> - - <section> - <title>The &StaticLibrary; Builder</title> - - <para> - - 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 - source-code files or object files, - and the ⌖ argument is the - name of the static library to be created. - For example: - - </para> - - <programlisting> - StaticLibrary('foo', ['file1.c', 'file2.c']) - </programlisting> - - <para> - - The target file's prefix and suffix may be omitted, - and the values from the - &cv-link-LIBPREFIX; - and - &cv-link-LIBSUFFIX; - construction variables - will be appended appropriately. - For example: - - </para> - - <programlisting> - env = Environment(LIBPREFIX='my', LIBSUFFIX='.xxx') - env.StaticLibrary('lib', ['file1.o', 'file2.o']) - </programlisting> - - <para> - - Will create an object file named - <filename>mylib.xxx</filename> - regardless of the system on which it is run. - - </para> - - <programlisting> - StaticLibrary('foo', ['file1.c', 'file2.c']) - </programlisting> - - <para> - - If you omit the ⌖, - the base of the first input - file name specified - becomes the base of the name of the static object file to be created. - For example: - - </para> - - <programlisting> - StaticLibrary(['file.c', 'another.c']) - </programlisting> - - <para> - - Will create the &libfile_a; - library on a POSIX system, - the &file_lib; library on a Windows system. - - </para> - - </section> - - <section> - <title>The &SharedLibrary; Builder</title> - - <para> - - 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 - source-code files or object files, - and the ⌖ argument is the - name of the shared library to be created. - For example: - - </para> - - <programlisting> - SharedLibrary('foo', ['file1.c', 'file2.c']) - </programlisting> - - <para> - - The target file's prefix and suffix may be omitted, - and the values from the - &cv-link-SHLIBPREFIX; - and - &cv-link-SHLIBSUFFIX; - construction variables - will be appended appropriately. - For example: - - </para> - - <programlisting> - env = Environment(SHLIBPREFIX='my', SHLIBSUFFIX='.xxx') - env.SharedLibrary('shared', ['file1.o', 'file2.o']) - </programlisting> - - <para> - - Will create an object file named - <filename>myshared.xxx</filename> - regardless of the system on which it is run. - - </para> - - <programlisting> - SharedLibrary('foo', ['file1.c', 'file2.c']) - </programlisting> - - <para> - - If you omit the ⌖, - the base of the first input - file name specified - becomes the base of the name of the shared library to be created. - For example: - - </para> - - <programlisting> - SharedLibrary(['file.c', 'another.c']) - </programlisting> - - <para> - - Will create the &libfile_so; - library on a POSIX system, - the &file_dll; library on a Windows system. - - </para> - - </section> - - <section> - <title>The &Library; Builder</title> - - <para> - - The &b-link-Library; Builder is a synonym for &b-link-StaticLibrary; - and is completely equivalent. - - </para> - - </section> - - </section> - - <section> - <title>Pre-Compiled Headers: the &PCH; Builder</title> - - <para> - - XXX PCH() - - </para> - - </section> - - <section> - <title>Microsoft Visual C++ Resource Files: the &RES; Builder</title> - - <para> - - XXX RES() - - </para> - - </section> - - <section> - <title>Source Files</title> - - <para> - - By default - &SCons; supports two Builder objects - that know how to build source files - from other input files. - These are typically invoked "internally" - to turn files that need preprocessing into other source files. - - </para> - - <section> - <title>The &CFile; Builder</title> - - <para> - - XXX CFile() - - </para> - - <programlisting> - XXX CFile() programlisting - </programlisting> - - <screen> - XXX CFile() screen - </screen> - - </section> - - <section> - <title>The &CXXFile; Builder</title> - - <para> - - XXX CXXFILE() - - </para> - - <programlisting> - XXX CXXFILE() programlisting - </programlisting> - - <screen> - XXX CXXFILE() screen - </screen> - - </section> - - </section> - - <section> - <title>Documents</title> - - <para> - - &SCons; provides a number of Builder objects - for creating different types of documents. - - </para> - - <section> - <title>The &DVI; Builder</title> - - <para> - - XXX DVI() para - - </para> - - <programlisting> - XXX DVI() programlisting - </programlisting> - - <screen> - XXX DVI() screen - </screen> - - </section> - - <section> - <title>The &PDF; Builder</title> - - <para> - - XXX PDF() para - - </para> - - </section> - - <section> - <title>The &PostScript; Builder</title> - - <para> - - XXX PostScript() para - - </para> - - <programlisting> - XXX PostScript() programlisting - </programlisting> - - <screen> - XXX PostScript() screen - </screen> - - </section> - - </section> - - <section> - <title>Archives</title> - - <para> - - &SCons; provides Builder objects - for creating two different types of archive files. - - </para> - - <section> - <title>The &Tar; Builder</title> - - <para> - - The &b-link-Tar; Builder object uses the &tar; - utility to create archives of files - and/or directory trees: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - env = Environment() - env.Tar('out1.tar', ['file1', 'file2']) - env.Tar('out2', 'directory') - </file> - <file name="file1"> - file1 - </file> - <file name="file2"> - file2 - </file> - <file name="directory/file3"> - directory/file3 - </file> - </scons_example> - - <scons_output example="ex1" os="posix"> - <scons_output_command>scons -Q .</scons_output_command> - </scons_output> - - <para> - - One common requirement when creating a &tar; archive - is to create a compressed archive using the - <option>-z</option> option. - This is easily handled by specifying - 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 &cv-TARFLAGS;, - so you need to set it both options: - - </para> - - <scons_example name="ex2"> - <file name="SConstruct" printme="1"> - env = Environment(TARFLAGS = '-c -z') - env.Tar('out.tar.gz', 'directory') - </file> - <file name="directory/file"> - directory/file - </file> - </scons_example> - - <scons_output example="ex2" os="posix"> - <scons_output_command>scons -Q .</scons_output_command> - </scons_output> - - <para> - - you may also wish to set the value of the - &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: - - </para> - - <scons_example name="ex3"> - <file name="SConstruct" printme="1"> - env = Environment(TARFLAGS = '-c -z', - TARSUFFIX = '.tgz') - env.Tar('out', 'directory') - </file> - <file name="directory/file"> - directory/file - </file> - </scons_example> - - <scons_output example="ex3" os="posix"> - <scons_output_command>scons -Q .</scons_output_command> - </scons_output> - - </section> - - <section> - <title>The &Zip; Builder</title> - - <para> - - 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 - that &SCons; will use. - In this case, given the following - &SConstruct; file: - - </para> - - <scons_example name="ex4"> - <file name="SConstruct" printme="1"> - env = Environment() - env.Zip('out', ['file1', 'file2']) - </file> - <file name="file1"> - file1 - </file> - <file name="file2"> - file2 - </file> - </scons_example> - - <para> - - Your output will reflect the fact - that an internal Python function - is being used to create the output ZIP archive: - - </para> - - <scons_output example="ex4" os="posix"> - <scons_output_command>scons -Q .</scons_output_command> - </scons_output> - - </section> - - </section> - - <section> - <title>Java</title> - - <para> - - &SCons; provides Builder objects - for creating various types of Java output files. - - </para> - - <section> - <title>Building Class Files: the &Java; Builder</title> - - <para> - - 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 - Unlike most builders, however, - the &Java; builder takes - target and source <emphasis>directories</emphasis>, - not files, as input. - - </para> - - <programlisting> - env = Environment() - env.Java(target = 'classes', source = 'src') - </programlisting> - - <para> - - The &Java; builder will then - search the specified source directory - tree for all <filename>.java</filename> files, - and pass any out-of-date - - </para> - - <screen> - XXX Java() screen - </screen> - - </section> - - <section> - <title>The &Jar; Builder</title> - - <para> - - XXX The &Jar; builder object - - </para> - - <programlisting> - env = Environment() - env.Java(target = 'classes', source = 'src') - env.Jar(target = '', source = 'classes') - </programlisting> - - <screen> - XXX Jar() screen - </screen> - - </section> - - <section> - <title>Building C header and stub files: the &JavaH; Builder</title> - - <para> - - XXX JavaH() para - - </para> - - <programlisting> - XXX JavaH() programlisting - </programlisting> - - <screen> - XXX JavaH() screen - </screen> - - </section> - - <section> - <title>Building RMI stub and skeleton class files: the &RMIC; Builder</title> - - <para> - - XXX RMIC() para - - </para> - - <programlisting> - XXX RMIC() programlisting - </programlisting> - - <screen> - XXX RMIC() screen - </screen> - - </section> - - </section> diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml index 7151bf4..455b7a3 100644 --- a/doc/user/builders-built-in.xml +++ b/doc/user/builders-built-in.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-builders-built-in" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Built-In Builders</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -55,7 +77,7 @@ </para> <programlisting> - Program('prog', 'file1.o') +Program('prog', 'file1.o') </programlisting> <para> @@ -80,8 +102,8 @@ </para> <programlisting> - env = Environment(PROGPREFIX='my', PROGSUFFIX='.xxx') - env.Program('prog', ['file1.o', 'file2.o']) +env = Environment(PROGPREFIX='my', PROGSUFFIX='.xxx') +env.Program('prog', ['file1.o', 'file2.o']) </programlisting> <para> @@ -104,7 +126,7 @@ </para> <programlisting> - Program(['hello.c', 'goodbye.c']) +Program(['hello.c', 'goodbye.c']) </programlisting> <para> @@ -130,11 +152,19 @@ </para> - <programlisting> - env = Environment(LIBS = ['foo1', 'foo2'], - LIBPATH = ['/usr/dir1', 'dir2']) - env.Program(['hello.c', 'goodbye.c']) - </programlisting> + <scons_example name="buildersbuiltin_libs"> + <file name="SConstruct" printme="1"> +env = Environment(LIBS = ['foo1', 'foo2'], + LIBPATH = ['/usr/dir1', 'dir2']) +env.Program(['hello.c', 'goodbye.c']) + </file> + <file name="hello.c"> +int hello() { printf("Hello, world!\n"); } + </file> + <file name="goodbye.c"> +int goodbye() { printf("Goodbye, world!\n"); } + </file> + </scons_example> <para> @@ -142,12 +172,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o goodbye.o -c goodbye.c - cc -o hello.o -c hello.c - cc -o hello hello.o goodbye.o -L/usr/dir1 -Ldir2 -lfoo1 -lfoo2 - </screen> + <scons_output example="buildersbuiltin_libs" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -155,13 +182,9 @@ </para> - <screen> - C:\><userinput>scons -Q</userinput> - cl /Fogoodbye.obj /c goodbye.c /nologo - cl /Fohello.obj /c hello.c /nologo - link /nologo /OUT:hello.exe /LIBPATH:\usr\dir1 /LIBPATH:dir2 foo1.lib foo2.lib hello.obj goodbye.obj - embedManifestExeCheck(target, source, env) - </screen> + <scons_output example="buildersbuiltin_libs" os="win32" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -188,7 +211,7 @@ Other relevant construction variables include those used by the &b-link-Object; builders to affect how the - source files specified as input to the &t-Program; + source files specified as input to the <literal>Program</literal> builders are turned into object files; see the next section. @@ -235,7 +258,7 @@ </para> <programlisting> - StaticObject('file', 'file.c') +StaticObject('file', 'file.c') </programlisting> <para> @@ -260,8 +283,8 @@ </para> <programlisting> - env = Environment(OBJPREFIX='my', OBJSUFFIX='.xxx') - env.StaticObject('file', 'file.c') +env = Environment(OBJPREFIX='my', OBJSUFFIX='.xxx') +env.StaticObject('file', 'file.c') </programlisting> <para> @@ -284,7 +307,7 @@ </para> <programlisting> - StaticObject('file.c') +StaticObject('file.c') </programlisting> <para> @@ -314,7 +337,7 @@ </para> <programlisting> - SharedObject('file', 'file.c') +SharedObject('file', 'file.c') </programlisting> <para> @@ -339,8 +362,8 @@ </para> <programlisting> - env = Environment(SHOBJPREFIX='my', SHOBJSUFFIX='.xxx') - env.SharedObject('file', 'file.c') +env = Environment(SHOBJPREFIX='my', SHOBJSUFFIX='.xxx') +env.SharedObject('file', 'file.c') </programlisting> <para> @@ -363,7 +386,7 @@ </para> <programlisting> - SharedObject('file.c') +SharedObject('file.c') </programlisting> <para> @@ -417,7 +440,7 @@ </para> <programlisting> - StaticLibrary('foo', ['file1.c', 'file2.c']) +StaticLibrary('foo', ['file1.c', 'file2.c']) </programlisting> <para> @@ -434,8 +457,8 @@ </para> <programlisting> - env = Environment(LIBPREFIX='my', LIBSUFFIX='.xxx') - env.StaticLibrary('lib', ['file1.o', 'file2.o']) +env = Environment(LIBPREFIX='my', LIBSUFFIX='.xxx') +env.StaticLibrary('lib', ['file1.o', 'file2.o']) </programlisting> <para> @@ -447,7 +470,7 @@ </para> <programlisting> - StaticLibrary('foo', ['file1.c', 'file2.c']) +StaticLibrary('foo', ['file1.c', 'file2.c']) </programlisting> <para> @@ -461,7 +484,7 @@ </para> <programlisting> - StaticLibrary(['file.c', 'another.c']) +StaticLibrary(['file.c', 'another.c']) </programlisting> <para> @@ -491,7 +514,7 @@ </para> <programlisting> - SharedLibrary('foo', ['file1.c', 'file2.c']) +SharedLibrary('foo', ['file1.c', 'file2.c']) </programlisting> <para> @@ -508,8 +531,8 @@ </para> <programlisting> - env = Environment(SHLIBPREFIX='my', SHLIBSUFFIX='.xxx') - env.SharedLibrary('shared', ['file1.o', 'file2.o']) +env = Environment(SHLIBPREFIX='my', SHLIBSUFFIX='.xxx') +env.SharedLibrary('shared', ['file1.o', 'file2.o']) </programlisting> <para> @@ -521,7 +544,7 @@ </para> <programlisting> - SharedLibrary('foo', ['file1.c', 'file2.c']) +SharedLibrary('foo', ['file1.c', 'file2.c']) </programlisting> <para> @@ -535,7 +558,7 @@ </para> <programlisting> - SharedLibrary(['file.c', 'another.c']) +SharedLibrary(['file.c', 'another.c']) </programlisting> <para> @@ -608,11 +631,11 @@ </para> <programlisting> - XXX CFile() programlisting +XXX CFile() programlisting </programlisting> <screen> - XXX CFile() screen +XXX CFile() screen </screen> </section> @@ -627,11 +650,11 @@ </para> <programlisting> - XXX CXXFILE() programlisting +XXX CXXFILE() programlisting </programlisting> <screen> - XXX CXXFILE() screen +XXX CXXFILE() screen </screen> </section> @@ -658,11 +681,11 @@ </para> <programlisting> - XXX DVI() programlisting +XXX DVI() programlisting </programlisting> <screen> - XXX DVI() screen +XXX DVI() screen </screen> </section> @@ -688,11 +711,11 @@ </para> <programlisting> - XXX PostScript() programlisting +XXX PostScript() programlisting </programlisting> <screen> - XXX PostScript() screen +XXX PostScript() screen </screen> </section> @@ -720,17 +743,26 @@ </para> - <programlisting> - env = Environment() - env.Tar('out1.tar', ['file1', 'file2']) - env.Tar('out2', 'directory') - </programlisting> + <scons_example name="buildersbuiltin_ex1"> + <file name="SConstruct" printme="1"> +env = Environment() +env.Tar('out1.tar', ['file1', 'file2']) +env.Tar('out2', 'directory') + </file> + <file name="file1"> +file1 + </file> + <file name="file2"> +file2 + </file> + <file name="directory/file3"> +directory/file3 + </file> + </scons_example> - <screen> - % <userinput>scons -Q .</userinput> - tar -c -f out1.tar file1 file2 - tar -c -f out2.tar directory - </screen> + <scons_output example="buildersbuiltin_ex1" os="posix" suffix="1"> + <scons_output_command>scons -Q .</scons_output_command> + </scons_output> <para> @@ -747,15 +779,19 @@ </para> - <programlisting> - env = Environment(TARFLAGS = '-c -z') - env.Tar('out.tar.gz', 'directory') - </programlisting> + <scons_example name="buildersbuiltin_ex2"> + <file name="SConstruct" printme="1"> +env = Environment(TARFLAGS = '-c -z') +env.Tar('out.tar.gz', 'directory') + </file> + <file name="directory/file"> +directory/file + </file> + </scons_example> - <screen> - % <userinput>scons -Q .</userinput> - tar -c -z -f out.tar.gz directory - </screen> + <scons_output example="buildersbuiltin_ex2" os="posix" suffix="1"> + <scons_output_command>scons -Q .</scons_output_command> + </scons_output> <para> @@ -767,16 +803,20 @@ </para> - <programlisting> - env = Environment(TARFLAGS = '-c -z', - TARSUFFIX = '.tgz') - env.Tar('out', 'directory') - </programlisting> + <scons_example name="buildersbuiltin_ex3"> + <file name="SConstruct" printme="1"> +env = Environment(TARFLAGS = '-c -z', + TARSUFFIX = '.tgz') +env.Tar('out', 'directory') + </file> + <file name="directory/file"> +directory/file + </file> + </scons_example> - <screen> - % <userinput>scons -Q .</userinput> - tar -c -z -f out.tgz directory - </screen> + <scons_output example="buildersbuiltin_ex3" os="posix" suffix="1"> + <scons_output_command>scons -Q .</scons_output_command> + </scons_output> </section> @@ -795,10 +835,18 @@ </para> - <programlisting> - env = Environment() - env.Zip('out', ['file1', 'file2']) - </programlisting> + <scons_example name="buildersbuiltin_ex4"> + <file name="SConstruct" printme="1"> +env = Environment() +env.Zip('out', ['file1', 'file2']) + </file> + <file name="file1"> +file1 + </file> + <file name="file2"> +file2 + </file> + </scons_example> <para> @@ -808,10 +856,9 @@ </para> - <screen> - % <userinput>scons -Q .</userinput> - zip(["out.zip"], ["file1", "file2"]) - </screen> + <scons_output example="buildersbuiltin_ex4" os="posix" suffix="1"> + <scons_output_command>scons -Q .</scons_output_command> + </scons_output> </section> @@ -844,8 +891,8 @@ </para> <programlisting> - env = Environment() - env.Java(target = 'classes', source = 'src') +env = Environment() +env.Java(target = 'classes', source = 'src') </programlisting> <para> @@ -858,7 +905,7 @@ </para> <screen> - XXX Java() screen +XXX Java() screen </screen> </section> @@ -873,13 +920,13 @@ </para> <programlisting> - env = Environment() - env.Java(target = 'classes', source = 'src') - env.Jar(target = '', source = 'classes') +env = Environment() +env.Java(target = 'classes', source = 'src') +env.Jar(target = '', source = 'classes') </programlisting> <screen> - XXX Jar() screen +XXX Jar() screen </screen> </section> @@ -894,11 +941,11 @@ </para> <programlisting> - XXX JavaH() programlisting +XXX JavaH() programlisting </programlisting> <screen> - XXX JavaH() screen +XXX JavaH() screen </screen> </section> @@ -913,13 +960,15 @@ </para> <programlisting> - XXX RMIC() programlisting +XXX RMIC() programlisting </programlisting> <screen> - XXX RMIC() screen +XXX RMIC() screen </screen> </section> </section> + +</chapter> diff --git a/doc/user/builders-commands.in b/doc/user/builders-commands.in deleted file mode 100644 index 45f0787..0000000 --- a/doc/user/builders-commands.in +++ /dev/null @@ -1,156 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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. - ---> - - <!-- - - =head2 The C<Command> method - - - The C<Command> method is called as follows: - - Command $env <target>, <inputs>, <build action>; - - The target is made dependent upon the list of input files specified, and the - inputs must be built successfully or Cons will not attempt to build the - target. - - To specify a command with multiple targets, you can specify a reference to a - list of targets. In Perl, a list reference can be created by enclosing a - list in square brackets. Hence the following command: - - Command $env ['foo.h', 'foo.c'], 'foo.template', q( - gen %1 - ); - - could be used in a case where the command C<gen> creates two files, both - F<foo.h> and F<foo.c>. - - --> - - <para> - - Creating a &Builder; and attaching it to a &consenv; - allows for a lot of flexibility when you - want to re-use actions - to build multiple files of the same type. - This can, however, be cumbersome - if you only need to execute one specific command - to build a single file (or group of files). - For these situations, &SCons; supports a - &Command; &Builder; that arranges - for a specific action to be executed - to build a specific file or files. - This looks a lot like the other builders - (like &b-link-Program;, &b-link-Object;, etc.), - but takes as an additional argument - the command to be executed to build the file: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - env = Environment() - env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET") - </file> - <file name="foo.in"> - foo.in - </file> - </scons_example> - - <para> - - When executed, - &SCons; runs the specified command, - substituting &cv-link-SOURCE; and &cv-link-TARGET; - as expected: - - </para> - - <scons_output example="ex1"> - <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 &cv-link-BUILDERS; variable - of a &consenv; - - </para> - - <para> - - Note that the action you specify to the - &Command; &Builder; can be any legal &SCons; &Action;, - such as a Python function: - - </para> - - <scons_example name="ex2"> - <file name="SConstruct" printme="1"> - env = Environment() - def build(target, source, env): - # Whatever it takes to build - return None - env.Command('foo.out', 'foo.in', build) - </file> - <file name="foo.in"> - foo.in - </file> - </scons_example> - - <para> - - Which executes as follows: - - </para> - - <scons_output example="ex2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Note that &cv-link-SOURCE; and &cv-link-TARGET; are expanded - in the source and target as well as of SCons 1.1, - so you can write: - - </para> - - <scons_example name="ex3"> - <file name="SConstruct" printme="1"> - env.Command('${SOURCE.basename}.out', 'foo.in', build) - </file> - </scons_example> - - - <para> - - which does the same thing as the previous example, but allows you - to avoid repeating yourself. - - </para> - diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml index 0d3918d..5e179a4 100644 --- a/doc/user/builders-commands.xml +++ b/doc/user/builders-commands.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-builders-commands" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Not Writing a Builder: the &Command; Builder</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -69,10 +91,15 @@ </para> - <programlisting> - env = Environment() - env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET") - </programlisting> + <scons_example name="builderscommands_ex1"> + <file name="SConstruct" printme="1"> +env = Environment() +env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET") + </file> + <file name="foo.in"> +foo.in + </file> + </scons_example> <para> @@ -83,10 +110,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - sed 's/x/y/' < foo.in > foo.out - </screen> + <scons_output example="builderscommands_ex1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -105,13 +131,18 @@ </para> - <programlisting> - env = Environment() - def build(target, source, env): - # Whatever it takes to build - return None - env.Command('foo.out', 'foo.in', build) - </programlisting> + <scons_example name="builderscommands_ex2"> + <file name="SConstruct" printme="1"> +env = Environment() +def build(target, source, env): + # Whatever it takes to build + return None +env.Command('foo.out', 'foo.in', build) + </file> + <file name="foo.in"> +foo.in + </file> + </scons_example> <para> @@ -119,10 +150,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - build(["foo.out"], ["foo.in"]) - </screen> + <scons_output example="builderscommands_ex2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -132,9 +162,11 @@ </para> - <programlisting> - env.Command('${SOURCE.basename}.out', 'foo.in', build) - </programlisting> + <scons_example name="builderscommands_ex3"> + <file name="SConstruct" printme="1"> +env.Command('${SOURCE.basename}.out', 'foo.in', build) + </file> + </scons_example> <para> @@ -144,3 +176,5 @@ </para> + +</chapter> diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in deleted file mode 100644 index 74d5473..0000000 --- a/doc/user/builders-writing.in +++ /dev/null @@ -1,1108 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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. - ---> - -<!-- - -=head2 Adding new methods - -For slightly more demanding changes, you may wish to add new methods to the -C<cons> package. Here's an example of a very simple extension, -C<InstallScript>, which installs a tcl script in a requested location, but -edits the script first to reflect a platform-dependent path that needs to be -installed in the script: - - # cons::InstallScript - Create a platform dependent version of a shell - # script by replacing string ``#!your-path-here'' with platform specific - # path $BIN_DIR. - - sub cons::InstallScript { - my ($env, $dst, $src) = @_; - Command $env $dst, $src, qq( - sed s+your-path-here+$BIN_DIR+ %< > %> - chmod oug+x %> - ); - } - -Notice that this method is defined directly in the C<cons> package (by -prefixing the name with C<cons::>). A change made in this manner will be -globally visible to all environments, and could be called as in the -following example: - - InstallScript $env "$BIN/foo", "foo.tcl"; - -For a small improvement in generality, the C<BINDIR> variable could be -passed in as an argument or taken from the construction environment-,-as -C<%BINDIR>. - - -=head2 Overriding methods - -Instead of adding the method to the C<cons> name space, you could define a -new package which inherits existing methods from the C<cons> package and -overrides or adds others. This can be done using Perl's inheritance -mechanisms. - -The following example defines a new package C<cons::switch> which -overrides the standard C<Library> method. The overridden method builds -linked library modules, rather than library archives. A new -constructor is provided. Environments created with this constructor -will have the new library method; others won't. - - package cons::switch; - BEGIN {@ISA = 'cons'} - - sub new { - shift; - bless new cons(@_); - } - - sub Library { - my($env) = shift; - my($lib) = shift; - my(@objs) = Objects $env @_; - Command $env $lib, @objs, q( - %LD -r %LDFLAGS %< -o %> - ); - } - -This functionality could be invoked as in the following example: - - $env = new cons::switch(@overrides); - ... - Library $env 'lib.o', 'foo.c', 'bar.c'; - ---> - - <para> - - Although &SCons; provides many useful methods - for building common software products - (programs, libraries, documents, etc.), - you frequently want to be - able to build some other type of file - not supported directly by &SCons;. - Fortunately, &SCons; makes it very easy - to define your own &Builder; objects - for any custom file types you want to build. - (In fact, the &SCons; interfaces for creating - &Builder; objects are flexible enough and easy enough to use - that all of the the &SCons; built-in &Builder; objects - are created using the mechanisms described in this section.) - - </para> - - <section> - <title>Writing Builders That Execute External Commands</title> - - <para> - - The simplest &Builder; to create is - one that executes an external command. - For example, if we want to build - an output file by running the contents - of the input file through a command named - <literal>foobuild</literal>, - creating that &Builder; might look like: - - </para> - - <programlisting> - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - </programlisting> - - <para> - - All the above line does is create a free-standing - &Builder; object. - The next section will show us how to actually use it. - - </para> - - </section> - - <section> - <title>Attaching a Builder to a &ConsEnv;</title> - - <para> - - A &Builder; object isn't useful - 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 &cv-link-BUILDERS; - &consvar; in an environment. - 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 - &Builder; we just defined by the name - <function>Foo</function>, - our &SConstruct; file might look like: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct"> - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env = Environment(BUILDERS = {'Foo' : bld}) - import os - env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() - env.Foo('file.foo', 'file.input') - </file> - <file name="file.input"> - file.input - </file> - <file name="foobuild" chmod="0755"> - cat - </file> - </scons_example> - - <sconstruct> - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env = Environment(BUILDERS = {'Foo' : bld}) - </sconstruct> - - <para> - - With the &Builder; attached to our &consenv; - with the name <function>Foo</function>, - we can now actually call it like so: - - </para> - - <programlisting> - env.Foo('file.foo', 'file.input') - </programlisting> - - <para> - - Then when we run &SCons; it looks like: - - </para> - - <scons_output example="ex1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Note, however, that the default &cv-BUILDERS; - variable in a &consenv; - comes with a default set of &Builder; objects - already defined: - &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: - - </para> - - <!-- - The ToolSurrogate stuff that's used to capture output initializes - SCons.Defaults.ConstructionEnvironment with its own list of TOOLS. - In this next example, we want to show the user that when they - set the BUILDERS explicitly, the call to env.Program() generates - an AttributeError. This won't happen with all of the default - ToolSurrogates in the default construction environment. To make the - AttributeError show up, we have to overwite the default construction - environment's TOOLS variable so Program() builder doesn't show up. - - We do this by executing a slightly different SConstruct file than the - one we print in the guide, with two extra statements at the front - that overwrite the TOOLS variable as described. Note that we have - to jam those statements on to the first line to keep the line number - in the generated error consistent with what the user will see in the - User's Guide. - --> - <scons_example name="ex2"> - <file name="SConstruct"> - import SCons.Defaults; SCons.Defaults.ConstructionEnvironment['TOOLS'] = {}; bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file.foo', 'file.input') - env.Program('hello.c') - </file> - <file name="SConstruct.printme" printme="1"> - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file.foo', 'file.input') - env.Program('hello.c') - </file> - <file name="file.input"> - file.input - </file> - <file name="hello.c"> - hello.c - </file> - </scons_example> - - <scons_output example="ex2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - To be able to use both our own defined &Builder; objects - and the default &Builder; objects in the same &consenv;, - you can either add to the &cv-BUILDERS; variable - using the &Append; function: - - </para> - - <scons_example name="ex3"> - <file name="SConstruct"> - env = Environment() - import os - env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env.Append(BUILDERS = {'Foo' : bld}) - env.Foo('file.foo', 'file.input') - env.Program('hello.c') - </file> - <file name="file.input"> - file.input - </file> - <file name="hello.c"> - hello.c - </file> - <file name="foobuild" chmod="0755"> - cat - </file> - </scons_example> - - <sconstruct> - env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env.Append(BUILDERS = {'Foo' : bld}) - env.Foo('file.foo', 'file.input') - env.Program('hello.c') - </sconstruct> - - <para> - - Or you can explicitly set the appropriately-named - key in the &cv-BUILDERS; dictionary: - - </para> - - <sconstruct> - env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env['BUILDERS']['Foo'] = bld - env.Foo('file.foo', 'file.input') - env.Program('hello.c') - </sconstruct> - - <para> - - Either way, the same &consenv; - can then use both the newly-defined - <function>Foo</function> &Builder; - and the default &b-link-Program; &Builder;: - - </para> - - <scons_output example="ex3"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Letting &SCons; Handle The File Suffixes</title> - - <para> - - By supplying additional information - when you create a &Builder;, - you can let &SCons; add appropriate file - suffixes to the target and/or the source file. - For example, rather than having to specify - explicitly that you want the <literal>Foo</literal> - &Builder; to build the <literal>file.foo</literal> - target file from the <literal>file.input</literal> source file, - you can give the <literal>.foo</literal> - and <literal>.input</literal> suffixes to the &Builder;, - making for more compact and readable calls to - the <literal>Foo</literal> &Builder;: - - </para> - - <scons_example name="ex4"> - <file name="SConstruct"> - bld = Builder(action = 'foobuild < $SOURCE > $TARGET', - suffix = '.foo', - src_suffix = '.input') - env = Environment(BUILDERS = {'Foo' : bld}) - import os - env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() - env.Foo('file1') - env.Foo('file2') - </file> - <file name="file1.input"> - file1.input - </file> - <file name="file2.input"> - file2.input - </file> - <file name="foobuild" chmod="0755"> - cat - </file> - </scons_example> - - <sconstruct> - bld = Builder(action = 'foobuild < $SOURCE > $TARGET', - suffix = '.foo', - src_suffix = '.input') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file1') - env.Foo('file2') - </sconstruct> - - <scons_output example="ex4"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - You can also supply a <literal>prefix</literal> keyword argument - if it's appropriate to have &SCons; append a prefix - to the beginning of target file names. - - </para> - - </section> - - <section> - <title>Builders That Execute Python Functions</title> - - <para> - - In &SCons;, you don't have to call an external command - to build a file. - You can, instead, define a Python function - that a &Builder; object can invoke - to build your target file (or files). - Such a &buildfunc; definition looks like: - - </para> - - <programlisting> - def build_function(target, source, env): - # Code to build "target" from "source" - return None - </programlisting> - - <para> - - The arguments of a &buildfunc; are: - - </para> - - <variablelist> - - <varlistentry> - <term>target</term> - - <listitem> - <para> - - A list of Node objects representing - the target or targets to be - built by this builder function. - The file names of these target(s) - may be extracted using the Python &str; function. - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>source</term> - - <listitem> - <para> - - A list of Node objects representing - the sources to be - used by this builder function to build the targets. - The file names of these source(s) - may be extracted using the Python &str; function. - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>env</term> - - <listitem> - <para> - - The &consenv; used for building the target(s). - The builder function may use any of the - environment's construction variables - in any way to affect how it builds the targets. - - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - - The builder function must - return a <literal>0</literal> or <literal>None</literal> value - if the target(s) are built successfully. - The builder function - may raise an exception - or return any non-zero value - to indicate that the build is unsuccessful, - - </para> - - <para> - - Once you've defined the Python function - that will build your target file, - defining a &Builder; object for it is as - simple as specifying the name of the function, - instead of an external command, - as the &Builder;'s - <literal>action</literal> - argument: - - </para> - - <scons_example name="ex5"> - <file name="SConstruct" printme="1"> - def build_function(target, source, env): - # Code to build "target" from "source" - return None - bld = Builder(action = build_function, - suffix = '.foo', - src_suffix = '.input') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file') - </file> - <file name="file.input"> - file.input - </file> - </scons_example> - - <para> - - And notice that the output changes slightly, - reflecting the fact that a Python function, - not an external command, - is now called to build the target file: - - </para> - - <scons_output example="ex5"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Builders That Create Actions Using a &Generator;</title> - - <para> - - &SCons; Builder objects can create an action "on the fly" - by using a function called a &generator;. - This provides a great deal of flexibility to - construct just the right list of commands - to build your target. - A &generator; looks like: - - </para> - - <programlisting> - def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (target[0], source[0]) - </programlisting> - - <para> - - The arguments of a &generator; are: - - </para> - - <variablelist> - - <varlistentry> - <term>source</term> - - <listitem> - <para> - - A list of Node objects representing - the sources to be built - by the command or other action - generated by this function. - The file names of these source(s) - may be extracted using the Python &str; function. - - </para> - </listitem> - - </varlistentry> - - <varlistentry> - <term>target</term> - - <listitem> - <para> - - A list of Node objects representing - the target or targets to be built - by the command or other action - generated by this function. - The file names of these target(s) - may be extracted using the Python &str; function. - - </para> - </listitem> - - </varlistentry> - - <varlistentry> - <term>env</term> - - <listitem> - <para> - - The &consenv; used for building the target(s). - The generator may use any of the - environment's construction variables - in any way to determine what command - or other action to return. - - </para> - </listitem> - - </varlistentry> - - <varlistentry> - <term>for_signature</term> - - <listitem> - <para> - - A flag that specifies whether the - generator is being called to contribute to a build signature, - as opposed to actually executing the command. - - <!-- XXX NEED MORE HERE, describe generators use in signatures --> - - </para> - </listitem> - - </varlistentry> - - </variablelist> - - <para> - - The &generator; must return a - command string or other action that will be used to - build the specified target(s) from the specified source(s). - - </para> - - <para> - - Once you've defined a &generator;, - you create a &Builder; to use it - by specifying the generator keyword argument - instead of <literal>action</literal>. - - </para> - - <scons_example name="ex6"> - <file name="SConstruct"> - def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (source[0], target[0]) - bld = Builder(generator = generate_actions, - suffix = '.foo', - src_suffix = '.input') - env = Environment(BUILDERS = {'Foo' : bld}) - import os - env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() - env.Foo('file') - </file> - <file name="file.input"> - file.input - </file> - <file name="foobuild" chmod="0755"> - cat - </file> - </scons_example> - - <sconstruct> - def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (source[0], target[0]) - bld = Builder(generator = generate_actions, - suffix = '.foo', - src_suffix = '.input') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file') - </sconstruct> - - <scons_output example="ex6"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Note that it's illegal to specify both an - <literal>action</literal> - and a - <literal>generator</literal> - for a &Builder;. - - </para> - - </section> - - <section> - <title>Builders That Modify the Target or Source Lists Using an &Emitter;</title> - - <para> - - &SCons; supports the ability for a Builder to modify the - lists of target(s) from the specified source(s). - You do this by defining an &emitter; function - that takes as its arguments - the list of the targets passed to the builder, - the list of the sources passed to the builder, - and the construction environment. - The emitter function should return the modified - lists of targets that should be built - and sources from which the targets will be built. - - </para> - - <para> - - For example, suppose you want to define a Builder - that always calls a <filename>foobuild</filename> program, - and you want to automatically add - a new target file named - <filename>new_target</filename> - and a new source file named - <filename>new_source</filename> - whenever it's called. - The &SConstruct; file might look like this: - - </para> - - <scons_example name="ex7"> - <file name="SConstruct"> - def modify_targets(target, source, env): - target.append('new_target') - source.append('new_source') - return target, source - bld = Builder(action = 'foobuild $TARGETS - $SOURCES', - suffix = '.foo', - src_suffix = '.input', - emitter = modify_targets) - env = Environment(BUILDERS = {'Foo' : bld}) - import os - env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() - env.Foo('file') - </file> - <file name="file.input"> - file.input - </file> - <file name="new_source"> - new_source - </file> - <file name="foobuild" chmod="0755"> - cat - </file> - </scons_example> - - <sconstruct> - def modify_targets(target, source, env): - target.append('new_target') - source.append('new_source') - return target, source - bld = Builder(action = 'foobuild $TARGETS - $SOURCES', - suffix = '.foo', - src_suffix = '.input', - emitter = modify_targets) - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file') - </sconstruct> - - <para> - - And would yield the following output: - - </para> - - <scons_output example="ex7"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - One very flexible thing that you can do is - use a construction variable to specify - different emitter functions for different - construction variable. - To do this, specify a string - containing a construction variable - expansion as the emitter when you call - the &Builder; function, - and set that construction variable to - the desired emitter function - in different construction environments: - - </para> - - <scons_example name="MY_EMITTER"> - - <file name="SConstruct" printme="1"> - bld = Builder(action = 'my_command $SOURCES > $TARGET', - suffix = '.foo', - src_suffix = '.input', - emitter = '$MY_EMITTER') - def modify1(target, source, env): - return target, source + ['modify1.in'] - def modify2(target, source, env): - return target, source + ['modify2.in'] - env1 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify1) - env2 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify2) - env1.Foo('file1') - env2.Foo('file2') - import os - env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() - env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() - </file> - <file name="file1.input"> - file1.input - </file> - <file name="file2.input"> - file2.input - </file> - <file name="modify1.in"> - modify1.input - </file> - <file name="modify2.in"> - modify2.input - </file> - <file name="my_command" chmod="0755"> - cat - </file> - - </scons_example> - - <sconstruct> - bld = Builder(action = 'my_command $SOURCES > $TARGET', - suffix = '.foo', - src_suffix = '.input', - emitter = '$MY_EMITTER') - def modify1(target, source, env): - return target, source + ['modify1.in'] - def modify2(target, source, env): - return target, source + ['modify2.in'] - env1 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify1) - env2 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify2) - env1.Foo('file1') - env2.Foo('file2') - </sconstruct> - - <para> - - In this example, the <filename>modify1.in</filename> - and <filename>modify2.in</filename> files - get added to the source lists - of the different commands: - - </para> - - <scons_output example="MY_EMITTER"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <!-- - - <section> - <title>target_factor=, source_factory=</title> - - </section> - - <section> - <title>target_scanner=, source_scanner=</title> - - </section> - - <section> - <title>multi=</title> - - </section> - - <section> - <title>single_source=</title> - - </section> - - <section> - <title>src_builder=</title> - - </section> - - <section> - <title>ensure_suffix=</title> - - </section> - - --> - - <section> - <title>Where To Put Your Custom Builders and Tools</title> - - <para> - - The <filename>site_scons</filename> directories give you a place to - put Python modules and packages that you can import into your &SConscript; files - (<filename>site_scons</filename>), - add-on tools that can integrate into &SCons; - (<filename>site_scons/site_tools</filename>), - and a <filename>site_scons/site_init.py</filename> file that - gets read before any &SConstruct; or &SConscript; file, - allowing you to change &SCons;'s default behavior. - - </para> - - <para> - - Each system type (Windows, Mac, Linux, etc.) searches a canonical - set of directories for site_scons; see the man page for details. - The top-level SConstruct's site_scons dir is always searched last, - and its dir is placed first in the tool path so it overrides all - others. - - </para> - - <para> - - If you get a tool from somewhere (the &SCons; wiki or a third party, - for instance) and you'd like to use it in your project, a - <filename>site_scons</filename> dir is the simplest place to put it. - Tools come in two flavors; either a Python function that operates on - an &Environment; or a Python module or package containing two functions, - <function>exists()</function> and <function>generate()</function>. - - </para> - - <para> - - A single-function Tool can just be included in your - <filename>site_scons/site_init.py</filename> file where it will be - parsed and made available for use. For instance, you could have a - <filename>site_scons/site_init.py</filename> file like this: - - </para> - - <scons_example name="site1"> - <file name="site_scons/site_init.py" printme="1"> - def TOOL_ADD_HEADER(env): - """A Tool to add a header from $HEADER to the source file""" - add_header = Builder(action=['echo "$HEADER" > $TARGET', - 'cat $SOURCE >> $TARGET']) - env.Append(BUILDERS = {'AddHeader' : add_header}) - env['HEADER'] = '' # set default value - </file> - <file name="SConstruct"> - env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") - env.AddHeader('tgt', 'src') - </file> - <file name="src"> - hi there - </file> - </scons_example> - - <para> - - and a &SConstruct; like this: - - </para> - - <sconstruct> - # Use TOOL_ADD_HEADER from site_scons/site_init.py - env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") - env.AddHeader('tgt', 'src') - </sconstruct> - - <para> - - The <function>TOOL_ADD_HEADER</function> tool method will be - called to add the <function>AddHeader</function> tool to the - environment. - - </para> - - <!-- - <scons_output example="site1" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - --> - - <para> - A more full-fledged tool with - <function>exists()</function> and <function>generate()</function> - methods can be installed either as a module in the file - <filename>site_scons/site_tools/toolname.py</filename> or as a - package in the - directory <filename>site_scons/site_tools/toolname</filename>. In - the case of using a package, the <function>exists()</function> - and <function>generate()</function> are in the - file <filename>site_scons/site_tools/toolname/__init__.py</filename>. - (In all the above case <filename>toolname</filename> is replaced - by the name of the tool.) - Since <filename>site_scons/site_tools</filename> is automatically - added to the head of the tool search path, any tool found there - will be available to all environments. Furthermore, a tool found - there will override a built-in tool of the same name, so if you - need to change the behavior of a built-in - tool, <filename>site_scons</filename> gives you the hook you need. - </para> - - <para> - Many people have a library of utility Python functions they'd like - to include in &SConscript;s; just put that module in - <filename>site_scons/my_utils.py</filename> or any valid Python module name of your - choice. For instance you can do something like this in - <filename>site_scons/my_utils.py</filename> to add - <function>build_id</function> and <function>MakeWorkDir</function> - functions: - </para> - - <scons_example name="site2"> - <file name="site_scons/my_utils.py" printme="1"> - from SCons.Script import * # for Execute and Mkdir - def build_id(): - """Return a build ID (stub version)""" - return "100" - def MakeWorkDir(workdir): - """Create the specified dir immediately""" - Execute(Mkdir(workdir)) - </file> - <file name="SConscript"> - import my_utils - MakeWorkDir('/tmp/work') - print "build_id=" + my_utils.build_id() - </file> - </scons_example> - - <para> - - And then in your &SConscript; or any sub-&SConscript; anywhere in - your build, you can import <filename>my_utils</filename> and use it: - - </para> - - <sconstruct> - import my_utils - print "build_id=" + my_utils.build_id() - my_utils.MakeWorkDir('/tmp/work') - </sconstruct> - - <para> - Note that although you can put this library in - <filename>site_scons/site_init.py</filename>, - it is no better there than <filename>site_scons/my_utils.py</filename> - since you still have to import that module into your &SConscript;. - Also note that in order to refer to objects in the SCons namespace - such as &Environment; or &Mkdir; or &Execute; in any file other - than a &SConstruct; or &SConscript; you always need to do - </para> - <sconstruct> - from SCons.Script import * - </sconstruct> - - <para> - This is true in modules in <filename>site_scons</filename> such as - <filename>site_scons/site_init.py</filename> as well. - </para> - - <para> - - You can use any of the user- or machine-wide site dirs such as - <filename>~/.scons/site_scons</filename> instead of - <filename>./site_scons</filename>, or use the - <literal>--site-dir</literal> option to point to your own dir. - <filename>site_init.py</filename> and - <filename>site_tools</filename> will be located under that dir. - To avoid using a <filename>site_scons</filename> dir at all, - even if it exists, use the <literal>--no-site-dir</literal> - option. - - </para> - - </section> - - - <!-- - - <section> - <title>Builders That Use Other Builders</title> - - <para> - - XXX para - - </para> - - <scons_example name="ex8"> - <file name="SConstruct" printme="1"> - env = Environment() - #env.SourceCode('.', env.BitKeeper('my_command')) - env.Program('hello.c') - </file> - <file name="hello.c"> - hello.c - </file> - </scons_example> - - <scons_output example="ex8"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - --> diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index e6b165b..bc7983d 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-builders-writing" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Writing Your Own Builders</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -129,7 +151,7 @@ This functionality could be invoked as in the following example: </para> <programlisting> - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +bld = Builder(action = 'foobuild < $SOURCE > $TARGET') </programlisting> <para> @@ -163,12 +185,26 @@ This functionality could be invoked as in the following example: </para> - + <scons_example name="builderswriting_ex1"> + <file name="SConstruct"> +bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +env = Environment(BUILDERS = {'Foo' : bld}) +import os +env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() +env.Foo('file.foo', 'file.input') + </file> + <file name="file.input"> +file.input + </file> + <file name="foobuild" chmod="0755"> +cat + </file> + </scons_example> - <programlisting> - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env = Environment(BUILDERS = {'Foo' : bld}) - </programlisting> + <sconstruct> +bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +env = Environment(BUILDERS = {'Foo' : bld}) + </sconstruct> <para> @@ -179,7 +215,7 @@ This functionality could be invoked as in the following example: </para> <programlisting> - env.Foo('file.foo', 'file.input') +env.Foo('file.foo', 'file.input') </programlisting> <para> @@ -188,10 +224,9 @@ This functionality could be invoked as in the following example: </para> - <screen> - % <userinput>scons -Q</userinput> - foobuild < file.input > file.foo - </screen> + <scons_output example="builderswriting_ex1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -224,19 +259,30 @@ This functionality could be invoked as in the following example: in the generated error consistent with what the user will see in the User's Guide. --> - <programlisting> - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file.foo', 'file.input') - env.Program('hello.c') - </programlisting> + <scons_example name="builderswriting_ex2"> + <file name="SConstruct"> +import SCons.Defaults; SCons.Defaults.ConstructionEnvironment['TOOLS'] = {}; bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file.foo', 'file.input') +env.Program('hello.c') + </file> + <file name="SConstruct.printme" printme="1"> +bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file.foo', 'file.input') +env.Program('hello.c') + </file> + <file name="file.input"> +file.input + </file> + <file name="hello.c"> +hello.c + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - AttributeError: 'SConsEnvironment' object has no attribute 'Program': - File "/home/my/project/SConstruct", line 4: - env.Program('hello.c') - </screen> + <scons_output example="builderswriting_ex2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -247,15 +293,34 @@ This functionality could be invoked as in the following example: </para> - + <scons_example name="builderswriting_ex3"> + <file name="SConstruct"> +env = Environment() +import os +env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() +bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +env.Append(BUILDERS = {'Foo' : bld}) +env.Foo('file.foo', 'file.input') +env.Program('hello.c') + </file> + <file name="file.input"> +file.input + </file> + <file name="hello.c"> +hello.c + </file> + <file name="foobuild" chmod="0755"> +cat + </file> + </scons_example> - <programlisting> - env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env.Append(BUILDERS = {'Foo' : bld}) - env.Foo('file.foo', 'file.input') - env.Program('hello.c') - </programlisting> + <sconstruct> +env = Environment() +bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +env.Append(BUILDERS = {'Foo' : bld}) +env.Foo('file.foo', 'file.input') +env.Program('hello.c') + </sconstruct> <para> @@ -264,13 +329,13 @@ This functionality could be invoked as in the following example: </para> - <programlisting> - env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') - env['BUILDERS']['Foo'] = bld - env.Foo('file.foo', 'file.input') - env.Program('hello.c') - </programlisting> + <sconstruct> +env = Environment() +bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +env['BUILDERS']['Foo'] = bld +env.Foo('file.foo', 'file.input') +env.Program('hello.c') + </sconstruct> <para> @@ -281,12 +346,9 @@ This functionality could be invoked as in the following example: </para> - <screen> - % <userinput>scons -Q</userinput> - foobuild < file.input > file.foo - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="builderswriting_ex3" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -310,22 +372,40 @@ This functionality could be invoked as in the following example: </para> - + <scons_example name="builderswriting_ex4"> + <file name="SConstruct"> +bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + suffix = '.foo', + src_suffix = '.input') +env = Environment(BUILDERS = {'Foo' : bld}) +import os +env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() +env.Foo('file1') +env.Foo('file2') + </file> + <file name="file1.input"> +file1.input + </file> + <file name="file2.input"> +file2.input + </file> + <file name="foobuild" chmod="0755"> +cat + </file> + </scons_example> - <programlisting> - bld = Builder(action = 'foobuild < $SOURCE > $TARGET', - suffix = '.foo', - src_suffix = '.input') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file1') - env.Foo('file2') - </programlisting> + <sconstruct> +bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + suffix = '.foo', + src_suffix = '.input') +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file1') +env.Foo('file2') + </sconstruct> - <screen> - % <userinput>scons -Q</userinput> - foobuild < file1.input > file1.foo - foobuild < file2.input > file2.foo - </screen> + <scons_output example="builderswriting_ex4" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -352,9 +432,9 @@ This functionality could be invoked as in the following example: </para> <programlisting> - def build_function(target, source, env): - # Code to build "target" from "source" - return None +def build_function(target, source, env): + # Code to build "target" from "source" + return None </programlisting> <para> @@ -439,16 +519,21 @@ This functionality could be invoked as in the following example: </para> - <programlisting> - def build_function(target, source, env): - # Code to build "target" from "source" - return None - bld = Builder(action = build_function, - suffix = '.foo', - src_suffix = '.input') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file') - </programlisting> + <scons_example name="builderswriting_ex5"> + <file name="SConstruct" printme="1"> +def build_function(target, source, env): + # Code to build "target" from "source" + return None +bld = Builder(action = build_function, + suffix = '.foo', + src_suffix = '.input') +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file') + </file> + <file name="file.input"> +file.input + </file> + </scons_example> <para> @@ -459,10 +544,9 @@ This functionality could be invoked as in the following example: </para> - <screen> - % <userinput>scons -Q</userinput> - build_function(["file.foo"], ["file.input"]) - </screen> + <scons_output example="builderswriting_ex5" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -481,8 +565,8 @@ This functionality could be invoked as in the following example: </para> <programlisting> - def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (target[0], source[0]) +def generate_actions(source, target, env, for_signature): + return 'foobuild < %s > %s' % (target[0], source[0]) </programlisting> <para> @@ -582,22 +666,39 @@ This functionality could be invoked as in the following example: </para> - - - <programlisting> - def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (source[0], target[0]) - bld = Builder(generator = generate_actions, - suffix = '.foo', - src_suffix = '.input') - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file') - </programlisting> + <scons_example name="builderswriting_ex6"> + <file name="SConstruct"> +def generate_actions(source, target, env, for_signature): + return 'foobuild < %s > %s' % (source[0], target[0]) +bld = Builder(generator = generate_actions, + suffix = '.foo', + src_suffix = '.input') +env = Environment(BUILDERS = {'Foo' : bld}) +import os +env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() +env.Foo('file') + </file> + <file name="file.input"> +file.input + </file> + <file name="foobuild" chmod="0755"> +cat + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - foobuild < file.input > file.foo - </screen> + <sconstruct> +def generate_actions(source, target, env, for_signature): + return 'foobuild < %s > %s' % (source[0], target[0]) +bld = Builder(generator = generate_actions, + suffix = '.foo', + src_suffix = '.input') +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file') + </sconstruct> + + <scons_output example="builderswriting_ex6" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -643,20 +744,44 @@ This functionality could be invoked as in the following example: </para> - + <scons_example name="builderswriting_ex7"> + <file name="SConstruct"> +def modify_targets(target, source, env): + target.append('new_target') + source.append('new_source') + return target, source +bld = Builder(action = 'foobuild $TARGETS - $SOURCES', + suffix = '.foo', + src_suffix = '.input', + emitter = modify_targets) +env = Environment(BUILDERS = {'Foo' : bld}) +import os +env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() +env.Foo('file') + </file> + <file name="file.input"> +file.input + </file> + <file name="new_source"> +new_source + </file> + <file name="foobuild" chmod="0755"> +cat + </file> + </scons_example> - <programlisting> - def modify_targets(target, source, env): - target.append('new_target') - source.append('new_source') - return target, source - bld = Builder(action = 'foobuild $TARGETS - $SOURCES', - suffix = '.foo', - src_suffix = '.input', - emitter = modify_targets) - env = Environment(BUILDERS = {'Foo' : bld}) - env.Foo('file') - </programlisting> + <sconstruct> +def modify_targets(target, source, env): + target.append('new_target') + source.append('new_source') + return target, source +bld = Builder(action = 'foobuild $TARGETS - $SOURCES', + suffix = '.foo', + src_suffix = '.input', + emitter = modify_targets) +env = Environment(BUILDERS = {'Foo' : bld}) +env.Foo('file') + </sconstruct> <para> @@ -664,10 +789,9 @@ This functionality could be invoked as in the following example: </para> - <screen> - % <userinput>scons -Q</userinput> - foobuild file.foo new_target - file.input new_source - </screen> + <scons_output example="builderswriting_ex7" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -685,43 +809,61 @@ This functionality could be invoked as in the following example: </para> - <programlisting> - bld = Builder(action = 'my_command $SOURCES > $TARGET', - suffix = '.foo', - src_suffix = '.input', - emitter = '$MY_EMITTER') - def modify1(target, source, env): - return target, source + ['modify1.in'] - def modify2(target, source, env): - return target, source + ['modify2.in'] - env1 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify1) - env2 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify2) - env1.Foo('file1') - env2.Foo('file2') - import os - env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() - env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() + <scons_example name="builderswriting_MY_EMITTER"> + + <file name="SConstruct" printme="1"> +bld = Builder(action = 'my_command $SOURCES > $TARGET', + suffix = '.foo', + src_suffix = '.input', + emitter = '$MY_EMITTER') +def modify1(target, source, env): + return target, source + ['modify1.in'] +def modify2(target, source, env): + return target, source + ['modify2.in'] +env1 = Environment(BUILDERS = {'Foo' : bld}, + MY_EMITTER = modify1) +env2 = Environment(BUILDERS = {'Foo' : bld}, + MY_EMITTER = modify2) +env1.Foo('file1') +env2.Foo('file2') +import os +env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() +env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() + </file> + <file name="file1.input"> +file1.input + </file> + <file name="file2.input"> +file2.input + </file> + <file name="modify1.in"> +modify1.input + </file> + <file name="modify2.in"> +modify2.input + </file> + <file name="my_command" chmod="0755"> +cat + </file> - </programlisting> + </scons_example> - <programlisting> - bld = Builder(action = 'my_command $SOURCES > $TARGET', - suffix = '.foo', - src_suffix = '.input', - emitter = '$MY_EMITTER') - def modify1(target, source, env): - return target, source + ['modify1.in'] - def modify2(target, source, env): - return target, source + ['modify2.in'] - env1 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify1) - env2 = Environment(BUILDERS = {'Foo' : bld}, - MY_EMITTER = modify2) - env1.Foo('file1') - env2.Foo('file2') - </programlisting> + <sconstruct> +bld = Builder(action = 'my_command $SOURCES > $TARGET', + suffix = '.foo', + src_suffix = '.input', + emitter = '$MY_EMITTER') +def modify1(target, source, env): + return target, source + ['modify1.in'] +def modify2(target, source, env): + return target, source + ['modify2.in'] +env1 = Environment(BUILDERS = {'Foo' : bld}, + MY_EMITTER = modify1) +env2 = Environment(BUILDERS = {'Foo' : bld}, + MY_EMITTER = modify2) +env1.Foo('file1') +env2.Foo('file2') + </sconstruct> <para> @@ -732,11 +874,9 @@ This functionality could be invoked as in the following example: </para> - <screen> - % <userinput>scons -Q</userinput> - my_command file1.input modify1.in > file1.foo - my_command file2.input modify2.in > file2.foo - </screen> + <scons_output example="builderswriting_MY_EMITTER" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -820,14 +960,23 @@ This functionality could be invoked as in the following example: </para> - <programlisting> - def TOOL_ADD_HEADER(env): - """A Tool to add a header from $HEADER to the source file""" - add_header = Builder(action=['echo "$HEADER" > $TARGET', - 'cat $SOURCE >> $TARGET']) - env.Append(BUILDERS = {'AddHeader' : add_header}) - env['HEADER'] = '' # set default value - </programlisting> + <scons_example name="builderswriting_site1"> + <file name="site_scons/site_init.py" printme="1"> +def TOOL_ADD_HEADER(env): + """A Tool to add a header from $HEADER to the source file""" + add_header = Builder(action=['echo "$HEADER" > $TARGET', + 'cat $SOURCE >> $TARGET']) + env.Append(BUILDERS = {'AddHeader' : add_header}) + env['HEADER'] = '' # set default value + </file> + <file name="SConstruct"> +env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") +env.AddHeader('tgt', 'src') + </file> + <file name="src"> +hi there + </file> + </scons_example> <para> @@ -835,11 +984,11 @@ This functionality could be invoked as in the following example: </para> - <programlisting> - # Use TOOL_ADD_HEADER from site_scons/site_init.py - env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") - env.AddHeader('tgt', 'src') - </programlisting> + <sconstruct> +# Use TOOL_ADD_HEADER from site_scons/site_init.py +env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") +env.AddHeader('tgt', 'src') + </sconstruct> <para> @@ -850,7 +999,7 @@ This functionality could be invoked as in the following example: </para> <!-- - <scons_output example="site1" os="posix"> + <scons_output example="builderswriting_site1" os="posix" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> @@ -885,15 +1034,22 @@ This functionality could be invoked as in the following example: functions: </para> - <programlisting> - from SCons.Script import * # for Execute and Mkdir - def build_id(): - """Return a build ID (stub version)""" - return "100" - def MakeWorkDir(workdir): - """Create the specified dir immediately""" - Execute(Mkdir(workdir)) - </programlisting> + <scons_example name="builderswriting_site2"> + <file name="site_scons/my_utils.py" printme="1"> +from SCons.Script import * # for Execute and Mkdir +def build_id(): + """Return a build ID (stub version)""" + return "100" +def MakeWorkDir(workdir): + """Create the specified dir immediately""" + Execute(Mkdir(workdir)) + </file> + <file name="SConscript"> +import my_utils +MakeWorkDir('/tmp/work') +print "build_id=" + my_utils.build_id() + </file> + </scons_example> <para> @@ -902,11 +1058,11 @@ This functionality could be invoked as in the following example: </para> - <programlisting> - import my_utils - print "build_id=" + my_utils.build_id() - my_utils.MakeWorkDir('/tmp/work') - </programlisting> + <sconstruct> +import my_utils +print "build_id=" + my_utils.build_id() +my_utils.MakeWorkDir('/tmp/work') + </sconstruct> <para> Note that although you can put this library in @@ -917,9 +1073,9 @@ This functionality could be invoked as in the following example: such as &Environment; or &Mkdir; or &Execute; in any file other than a &SConstruct; or &SConscript; you always need to do </para> - <programlisting> - from SCons.Script import * - </programlisting> + <sconstruct> +from SCons.Script import * + </sconstruct> <para> This is true in modules in <filename>site_scons</filename> such as @@ -954,21 +1110,23 @@ This functionality could be invoked as in the following example: </para> - <scons_example name="ex8"> + <scons_example name="builderswriting_ex8"> <file name="SConstruct" printme="1"> - env = Environment() - #env.SourceCode('.', env.BitKeeper('my_command')) - env.Program('hello.c') +env = Environment() +#env.SourceCode('.', env.BitKeeper('my_command')) +env.Program('hello.c') </file> <file name="hello.c"> - hello.c +hello.c </file> </scons_example> - <scons_output example="ex8"> + <scons_output example="builderswriting_ex8" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> --> + +</chapter> diff --git a/doc/user/builders.xml b/doc/user/builders.xml index 0db5641..c1ac032 100644 --- a/doc/user/builders.xml +++ b/doc/user/builders.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<appendix id="app-builders" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Builders</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -23,25 +44,6 @@ --> -<!-- -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" -"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> - -<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 @@ -50,8 +52,6 @@ available "out of the box" in this version of SCons. </para> -<variablelist> - -&builders-gen; +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../generated/builders.gen"/> -</variablelist> +</appendix> diff --git a/doc/user/caching.in b/doc/user/caching.in deleted file mode 100644 index 8611962..0000000 --- a/doc/user/caching.in +++ /dev/null @@ -1,502 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - On multi-developer software projects, - you can sometimes speed up every developer's builds a lot by - allowing them to share the derived files that they build. - &SCons; makes this easy, as well as reliable. - - </para> - - <section> - <title>Specifying the Shared Cache Directory</title> - - <para> - - To enable sharing of derived files, - use the &CacheDir; function - in any &SConscript; file: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct"> - env = Environment() - env.Program('hello.c') - CacheDir('cache') - </file> - <file name="hello.c"> - hello.c - </file> - <directory name="cache"> - </directory> - <file name="not_used" printme="1"> - CacheDir('/usr/local/build_cache') - </file> - </scons_example> - - <para> - - Note that the directory you specify must already exist - and be readable and writable by all developers - who will be sharing derived files. - It should also be in some central location - that all builds will be able to access. - In environments where developers are using separate systems - (like individual workstations) for builds, - this directory would typically be - on a shared or NFS-mounted file system. - - </para> - - <para> - - Here's what happens: - When a build has a &CacheDir; specified, - every time a file is built, - it is stored in the shared cache directory - along with its MD5 build signature. - <footnote> - <para> - Actually, the MD5 signature is used as the name of the file - in the shared cache directory in which the contents are stored. - </para> - </footnote> - On subsequent builds, - before an action is invoked to build a file, - &SCons; will check the shared cache directory - to see if a file with the exact same build - signature already exists. - If so, the derived file will not be built locally, - but will be copied into the local build directory - from the shared cache directory, - like so: - - </para> - - <scons_output example="ex1"> - <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> - - <para> - - Note that the &CacheDir; feature still calculates - MD5 build sigantures for the shared cache file names - even if you configure &SCons; to use timestamps - to decide if files are up to date. - (See the <xref linkend="chap-depends"></xref> - chapter for information about the &Decider; function.) - Consequently, using &CacheDir; may reduce or eliminate any - potential performance improvements - from using timestamps for up-to-date decisions. - - </para> - - </section> - - <section> - <title>Keeping Build Output Consistent</title> - - <para> - - One potential drawback to using a shared cache - is that the output printed by &SCons; - can be inconsistent from invocation to invocation, - because any given file may be rebuilt one time - and retrieved from the shared cache the next time. - This can make analyzing build output more difficult, - especially for automated scripts that - expect consistent output each time. - - </para> - - <para> - - If, however, you use the <literal>--cache-show</literal> option, - &SCons; will print the command line that it - <emphasis>would</emphasis> have executed - to build the file, - even when it is retrieving the file from the shared cache. - This makes the build output consistent - every time the build is run: - - </para> - - <scons_output example="ex1"> - <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> - - The trade-off, of course, is that you no longer - know whether or not &SCons; - has retrieved a derived file from cache - or has rebuilt it locally. - - </para> - - </section> - - <section> - <title>Not Using the Shared Cache for Specific Files</title> - - <para> - - You may want to disable caching for certain - specific files in your configuration. - For example, if you only want to put - executable files in a central cache, - but not the intermediate object files, - you can use the &NoCache; - function to specify that the - object files should not be cached: - - </para> - - <scons_example name="ex-NoCache"> - <file name="SConstruct" printme="1"> - env = Environment() - obj = env.Object('hello.c') - env.Program('hello.c') - CacheDir('cache') - NoCache('hello.o') - </file> - <file name="hello.c"> - hello.c - </file> - <directory name="cache"> - </directory> - </scons_example> - - <para> - - Then when you run &scons; after cleaning - the built targets, - it will recompile the object file locally - (since it doesn't exist in the shared cache directory), - but still realize that the shared cache directory - contains an up-to-date executable program - that can be retrieved instead of re-linking: - - </para> - - <!-- - - <scons_output example="ex1"> - <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> - - --> - - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q -c</userinput> - Removed hello.o - Removed hello - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - Retrieved `hello' from cache - </screen> - - </section> - - <section> - <title>Disabling the Shared Cache</title> - - <para> - - Retrieving an already-built file - from the shared cache - is usually a significant time-savings - over rebuilding the file, - but how much of a savings - (or even whether it saves time at all) - can depend a great deal on your - system or network configuration. - For example, retrieving cached files - from a busy server over a busy network - might end up being slower than - rebuilding the files locally. - - </para> - - <para> - - In these cases, you can specify - the <literal>--cache-disable</literal> - command-line option to tell &SCons; - to not retrieve already-built files from the - shared cache directory: - - </para> - - <scons_output example="ex1"> - <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> - - <section> - <title>Populating a Shared Cache With Already-Built Files</title> - - <para> - - Sometimes, you may have one or more derived files - already built in your local build tree - that you wish to make available to other people doing builds. - For example, you may find it more effective to perform - integration builds with the cache disabled - (per the previous section) - and only populate the shared cache directory - with the built files after the integration build - has completed successfully. - This way, the cache will only get filled up - with derived files that are part of a complete, successful build - not with files that might be later overwritten - while you debug integration problems. - - </para> - - <para> - - In this case, you can use the - the <literal>--cache-force</literal> option - to tell &SCons; to put all derived files in the cache, - even if the files already exist in your local tree - from having been built by a previous invocation: - - </para> - - <scons_output example="ex1"> - <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</scons_output_command> - </scons_output> - - <para> - - Notice how the above sample run - demonstrates that the <literal>--cache-disable</literal> - option avoids putting the built - <filename>hello.o</filename> - and - <filename>hello</filename> files in the cache, - but after using the <literal>--cache-force</literal> option, - the files have been put in the cache - for the next invocation to retrieve. - - </para> - - </section> - - <section> - <title>Minimizing Cache Contention: the <literal>--random</literal> Option</title> - - <para> - - If you allow multiple builds to update the - shared cache directory simultaneously, - two builds that occur at the same time - can sometimes start "racing" - with one another to build the same files - in the same order. - If, for example, - you are linking multiple files into an executable program: - - </para> - - <scons_example name="ex-random"> - <file name="SConstruct" printme="1"> - Program('prog', - ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c']) - </file> - <file name="f1.c">f1.c</file> - <file name="f2.c">f2.c</file> - <file name="f3.c">f3.c</file> - <file name="f4.c">f4.c</file> - <file name="f5.c">f5.c</file> - <file name="f6.c">f6.c</file> - </scons_example> - - <para> - - &SCons; will normally build the input object files - on which the program depends in their normal, sorted order: - - </para> - - <scons_output example="ex-random"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - But if two such builds take place simultaneously, - they may each look in the cache at nearly the same - time and both decide that <filename>f1.o</filename> - must be rebuilt and pushed into the shared cache directory, - then both decide that <filename>f2.o</filename> - must be rebuilt (and pushed into the shared cache directory), - then both decide that <filename>f3.o</filename> - must be rebuilt... - This won't cause any actual build problems--both - builds will succeed, - generate correct output files, - and populate the cache--but - it does represent wasted effort. - - </para> - - <para> - - To alleviate such contention for the cache, - you can use the <literal>--random</literal> command-line option - to tell &SCons; to build dependencies - in a random order: - - </para> - - <!-- - - The following <screen> output was generated by this: - - <scons_output example="ex-random"> - <scons_output_command>scons -Q - -random</scons_output_command> - </scons_output> - - We captured it directly here to guarantee a "random" order, - guarding against the potential for - -random to happen - to return things in the original sorted order. - - --> - - <screen> - % <userinput>scons -Q --random</userinput> - cc -o f3.o -c f3.c - cc -o f1.o -c f1.c - cc -o f5.o -c f5.c - cc -o f2.o -c f2.c - cc -o f4.o -c f4.c - cc -o prog f1.o f2.o f3.o f4.o f5.o - </screen> - - <para> - - Multiple builds using the <literal>--random</literal> option - will usually build their dependencies in different, - random orders, - which minimizes the chances for a lot of - contention for same-named files - in the shared cache directory. - Multiple simultaneous builds might still race to try to build - the same target file on occasion, - but long sequences of inefficient contention - should be rare. - - </para> - - <para> - - Note, of course, - the <literal>--random</literal> option - will cause the output that &SCons; prints - to be inconsistent from invocation to invocation, - which may be an issue when - trying to compare output from different build runs. - - </para> - - <para> - - If you want to make sure dependencies will be built - in a random order without having to specify - the <literal>--random</literal> on very command line, - you can use the &SetOption; function to - set the <literal>random</literal> option - within any &SConscript; file: - - </para> - - <scons_example name="ex-random"> - <file name="SConstruct" printme="1"> - SetOption('random', 1) - Program('prog', - ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c']) - </file> - <file name="f1.c">f1.c</file> - <file name="f2.c">f2.c</file> - <file name="f3.c">f3.c</file> - <file name="f4.c">f4.c</file> - <file name="f5.c">f5.c</file> - <file name="f6.c">f6.c</file> - </scons_example> - - </section> - - <!-- - - <section> - <title>Troubleshooting Shared Caching: the &cache-debug; Option</title> - - <para> - - XXX describe the - - cache-debug option - XXX maybe point to the troubleshooting appendix? - - </para> - - </section> - - --> - - <!-- - - <section> - - <para> - - XXX describe CacheDir management: monitoring, deleting, etc. - - </para> - - </section> - - --> diff --git a/doc/user/caching.xml b/doc/user/caching.xml index afa6e6f..2f5642b 100644 --- a/doc/user/caching.xml +++ b/doc/user/caching.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-caching" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Caching Built Files</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -43,9 +65,21 @@ </para> - <programlisting> - CacheDir('/usr/local/build_cache') - </programlisting> + <scons_example name="caching_ex1"> + <file name="SConstruct"> +env = Environment() +env.Program('hello.c') +CacheDir('cache') + </file> + <file name="hello.c"> +hello.c + </file> + <directory name="cache"> + </directory> + <file name="not_used" printme="1"> +CacheDir('/usr/local/build_cache') + </file> + </scons_example> <para> @@ -86,17 +120,11 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q -c</userinput> - Removed hello.o - Removed hello - % <userinput>scons -Q</userinput> - Retrieved `hello.o' from cache - Retrieved `hello' from cache - </screen> + <scons_output example="caching_ex1" suffix="1"> + <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> <para> @@ -142,17 +170,11 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q -c</userinput> - Removed hello.o - Removed hello - % <userinput>scons -Q --cache-show</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="caching_ex1" suffix="2"> + <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> @@ -181,13 +203,20 @@ </para> - <programlisting> - env = Environment() - obj = env.Object('hello.c') - env.Program('hello.c') - CacheDir('cache') - NoCache('hello.o') - </programlisting> + <scons_example name="ex-NoCache"> + <file name="SConstruct" printme="1"> +env = Environment() +obj = env.Object('hello.c') +env.Program('hello.c') +CacheDir('cache') +NoCache('hello.o') + </file> + <file name="hello.c"> +hello.c + </file> + <directory name="cache"> + </directory> + </scons_example> <para> @@ -203,7 +232,7 @@ <!-- - <scons_output example="ex1"> + <scons_output example="caching_ex1" suffix="3"> <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> @@ -212,15 +241,15 @@ --> <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q -c</userinput> - Removed hello.o - Removed hello - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - Retrieved `hello' from cache +% <userinput>scons -Q</userinput> +cc -o hello.o -c hello.c +cc -o hello hello.o +% <userinput>scons -Q -c</userinput> +Removed hello.o +Removed hello +% <userinput>scons -Q</userinput> +cc -o hello.o -c hello.c +Retrieved `hello' from cache </screen> </section> @@ -255,23 +284,13 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q -c</userinput> - Removed hello.o - Removed hello - % <userinput>scons -Q</userinput> - Retrieved `hello.o' from cache - Retrieved `hello' from cache - % <userinput>scons -Q -c</userinput> - Removed hello.o - Removed hello - % <userinput>scons -Q --cache-disable</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="caching_ex1" suffix="4"> + <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> @@ -306,21 +325,13 @@ </para> - <screen> - % <userinput>scons -Q --cache-disable</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q -c</userinput> - Removed hello.o - Removed hello - % <userinput>scons -Q --cache-disable</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q --cache-force</userinput> - scons: `.' is up to date. - % <userinput>scons -Q</userinput> - scons: `.' is up to date. - </screen> + <scons_output example="caching_ex1" suffix="5"> + <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</scons_output_command> + </scons_output> <para> @@ -354,10 +365,18 @@ </para> - <programlisting> - Program('prog', - ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c']) - </programlisting> + <scons_example name="caching_ex-random"> + <file name="SConstruct" printme="1"> +Program('prog', + ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c']) + </file> + <file name="f1.c">f1.c</file> + <file name="f2.c">f2.c</file> + <file name="f3.c">f3.c</file> + <file name="f4.c">f4.c</file> + <file name="f5.c">f5.c</file> + <file name="f6.c">f6.c</file> + </scons_example> <para> @@ -366,15 +385,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o f1.o -c f1.c - cc -o f2.o -c f2.c - cc -o f3.o -c f3.c - cc -o f4.o -c f4.c - cc -o f5.o -c f5.c - cc -o prog f1.o f2.o f3.o f4.o f5.o - </screen> + <scons_output example="caching_ex-random" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -407,24 +420,24 @@ The following <screen> output was generated by this: - <scons_output example="ex-random"> + <scons_output example="caching_ex-random" suffix="2"> <scons_output_command>scons -Q - -random</scons_output_command> </scons_output> - We captured it directly here to guarantee a "random" order, - guarding against the potential for - -random to happen - to return things in the original sorted order. +We captured it directly here to guarantee a "random" order, +guarding against the potential for - -random to happen +to return things in the original sorted order. - --> +--> <screen> - % <userinput>scons -Q --random</userinput> - cc -o f3.o -c f3.c - cc -o f1.o -c f1.c - cc -o f5.o -c f5.c - cc -o f2.o -c f2.c - cc -o f4.o -c f4.c - cc -o prog f1.o f2.o f3.o f4.o f5.o + % <userinput>scons -Q --random</userinput> + cc -o f3.o -c f3.c + cc -o f1.o -c f1.c + cc -o f5.o -c f5.c + cc -o f2.o -c f2.c + cc -o f4.o -c f4.c + cc -o prog f1.o f2.o f3.o f4.o f5.o </screen> <para> @@ -464,14 +477,19 @@ </para> - <programlisting> - Program('prog', - ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c']) - - SetOption('random', 1) - Program('prog', - ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c']) - </programlisting> + <scons_example name="caching_ex-random"> + <file name="SConstruct" printme="1"> +SetOption('random', 1) +Program('prog', + ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c']) + </file> + <file name="f1.c">f1.c</file> + <file name="f2.c">f2.c</file> + <file name="f3.c">f3.c</file> + <file name="f4.c">f4.c</file> + <file name="f5.c">f5.c</file> + <file name="f6.c">f6.c</file> + </scons_example> </section> @@ -504,3 +522,5 @@ </section> --> + +</chapter> diff --git a/doc/user/errors.in b/doc/user/chtml.xsl index 9e8078c..5c9591a 100644 --- a/doc/user/errors.in +++ b/doc/user/chtml.xsl @@ -1,41 +1,60 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - XXX - - </para> - - <section> - <title>XXX</title> - - <para> - - XXX - - </para> - - </section> +<?xml version='1.0'?>
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation
+
+ 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.
+
+-->
+<xsl:stylesheet
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ version="1.0">
+
+ <xsl:import href="../../src/engine/SCons/Tool/docbook/docbook-xsl-1.76.1/html/chunk.xsl"/>
+
+<xsl:param name="base.dir" select="'scons-user/'"/>
+<xsl:param name="l10n.gentext.default.language" select="'en'"/>
+<xsl:param name="section.autolabel" select="1"/>
+<xsl:param name="html.stylesheet" select="'scons.css'"/>
+<xsl:param name="generate.toc">
+/appendix toc,title
+article/appendix nop
+/article toc,title
+book toc,title,figure,table,example,equation
+/chapter toc,title
+part toc,title
+/preface toc,title
+reference toc,title
+/sect1 toc
+/sect2 toc
+/sect3 toc
+/sect4 toc
+/sect5 toc
+/section toc
+set toc,title
+</xsl:param>
+
+<!-- Prevent our EPUB cover image from getting included -->
+<xsl:template match="mediaobject[@role = 'cover']">
+</xsl:template>
+
+</xsl:stylesheet>
+
diff --git a/doc/user/command-line.in b/doc/user/command-line.in deleted file mode 100644 index 5d28b04..0000000 --- a/doc/user/command-line.in +++ /dev/null @@ -1,2345 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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 ways - for the writer of the &SConscript; files - to give the users who will run &SCons; - a great deal of control over the build execution. - The arguments that the user can specify on - the command line are broken down into three types: - - </para> - - <variablelist> - - <varlistentry> - <term>Options</term> - - <listitem> - <para> - - Command-line options always begin with - one or two <literal>-</literal> (hyphen) characters. - &SCons; provides ways for you to examine - and set options values from within your &SConscript; files, - as well as the ability to define your own - custom options. - See <xref linkend="sect-command-line-options"></xref>, below. - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Variables</term> - - <listitem> - <para> - - Any command-line argument containing an <literal>=</literal> - (equal sign) is considered a variable setting with the form - <varname>variable</varname>=<varname>value</varname>. - &SCons; provides direct access to - all of the command-line variable settings, - the ability to apply command-line variable settings - to construction environments, - and functions for configuring - specific types of variables - (Boolean values, path names, etc.) - with automatic validation of the user's specified values. - See <xref linkend="sect-command-line-variables"></xref>, below. - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Targets</term> - - <listitem> - <para> - - Any command-line argument that is not an option - or a variable setting - (does not begin with a hyphen - and does not contain an equal sign) - is considered a target that the user - (presumably) wants &SCons; to build. - A list of Node objects representing - the target or targets to build. - &SCons; provides access to the list of specified targets, - as well as ways to set the default list of targets - from within the &SConscript; files. - See <xref linkend="sect-command-line-targets"></xref>, below. - - </para> - </listitem> - </varlistentry> - - </variablelist> - - <section id="sect-command-line-options"> - <title>Command-Line Options</title> - - <para> - - &SCons; has many <emphasis>command-line options</emphasis> - that control its behavior. - A &SCons; <emphasis>command-line option</emphasis> - always begins with one or two <literal>-</literal> (hyphen) - characters. - - </para> - - <section> - <title>Not Having to Specify Command-Line Options Each Time: the &SCONSFLAGS; Environment Variable</title> - - <para> - - Users may find themselves supplying - the same command-line options every time - they run &SCons;. - For example, you might find it saves time - to specify a value of <literal>-j 2</literal> - to have &SCons; run up to two build commands in parallel. - To avoid having to type <literal>-j 2</literal> by hand - every time, - you can set the external environment variable - &SCONSFLAGS; to a string containing - command-line options that you want &SCons; to use. - - </para> - - <para> - - If, for example, - you're using a POSIX shell that's - compatible with the Bourne shell, - and you always want &SCons; to use the - <literal>-Q</literal> option, - you can set the &SCONSFLAGS; - environment as follows: - - </para> - - <scons_example name="SCONSFLAGS"> - <file name="SConstruct"> - def b(target, source, env): - pass - def s(target, source, env): - return " ... [build output] ..." - a = Action(b, strfunction = s) - env = Environment(BUILDERS = {'A' : Builder(action=a)}) - env.A('foo.out', 'foo.in') - </file> - <file name="foo.in"> - foo.in - </file> - </scons_example> - - <scons_output example="SCONSFLAGS"> - <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> - - Users of &csh;-style shells on POSIX systems - can set the &SCONSFLAGS; environment as follows: - - </para> - - <screen> - $ <userinput>setenv SCONSFLAGS "-Q"</userinput> - </screen> - - <para> - - Windows users may typically want to set the - &SCONSFLAGS; in the appropriate tab of the - <literal>System Properties</literal> window. - - </para> - - </section> - - <section> - <title>Getting Values Set by Command-Line Options: the &GetOption; Function</title> - - <para> - - &SCons; provides the &GetOption; function - to get the values set by the various command-line options. - One common use of this is to check whether or not - the <literal>-h</literal> or <literal>--help</literal> option - has been specified. - Normally, &SCons; does not print its help text - until after it has read all of the &SConscript; files, - because it's possible that help text has been added - by some subsidiary &SConscript; file deep in the - source tree hierarchy. - Of course, reading all of the &SConscript; files - takes extra time. - - </para> - - <para> - - If you know that your configuration does not define - any additional help text in subsidiary &SConscript; files, - you can speed up the command-line help available to users - by using the &GetOption; function to load the - subsidiary &SConscript; files only if the - the user has <emphasis>not</emphasis> specified - the <literal>-h</literal> or <literal>--help</literal> option, - like so: - - </para> - - <sconstruct> - if not GetOption('help'): - SConscript('src/SConscript', export='env') - </sconstruct> - - <para> - - In general, the string that you pass to the - &GetOption; function to fetch the value of a command-line - option setting is the same as the "most common" long option name - (beginning with two hyphen characters), - although there are some exceptions. - The list of &SCons; command-line options - and the &GetOption; strings for fetching them, - are available in the - <xref linkend="sect-command-line-option-strings"></xref> section, - below. - - </para> - - </section> - - <section> - <title>Setting Values of Command-Line Options: the &SetOption; Function</title> - - <para> - - You can also set the values of &SCons; - command-line options from within the &SConscript; files - by using the &SetOption; function. - The strings that you use to set the values of &SCons; - command-line options are available in the - <xref linkend="sect-command-line-option-strings"></xref> section, - below. - - </para> - - <para> - - One use of the &SetOption; function is to - specify a value for the <literal>-j</literal> - or <literal>--jobs</literal> option, - so that users get the improved performance - of a parallel build without having to specify the option by hand. - A complicating factor is that a good value - for the <literal>-j</literal> option is - somewhat system-dependent. - One rough guideline is that the more processors - your system has, - the higher you want to set the - <literal>-j</literal> value, - in order to take advantage of the number of CPUs. - - </para> - - <para> - - For example, suppose the administrators - of your development systems - have standardized on setting a - <varname>NUM_CPU</varname> environment variable - to the number of processors on each system. - A little bit of Python code - to access the environment variable - and the &SetOption; function - provide the right level of flexibility: - - </para> - - <scons_example name="SetOption"> - <file name="SConstruct" printme="1"> - import os - num_cpu = int(os.environ.get('NUM_CPU', 2)) - SetOption('num_jobs', num_cpu) - print "running with -j", GetOption('num_jobs') - </file> - <file name="foo.in"> - foo.in - </file> - </scons_example> - - <para> - - The above snippet of code - sets the value of the <literal>--jobs</literal> option - to the value specified in the - <varname>$NUM_CPU</varname> environment variable. - (This is one of the exception cases - where the string is spelled differently from - the from command-line option. - The string for fetching or setting the <literal>--jobs</literal> - value is <literal>num_jobs</literal> - for historical reasons.) - The code in this example prints the <literal>num_jobs</literal> - value for illustrative purposes. - It uses a default value of <literal>2</literal> - to provide some minimal parallelism even on - single-processor systems: - - </para> - - <scons_output example="SetOption"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - But if the <varname>$NUM_CPU</varname> - environment variable is set, - then we use that for the default number of jobs: - - </para> - - <scons_output example="SetOption"> - <scons_output_command>export NUM_CPU="4"</scons_output_command> - <scons_output_command environment="NUM_CPU=4">scons -Q</scons_output_command> - </scons_output> - - <para> - - But any explicit - <literal>-j</literal> or <literal>--jobs</literal> - value the user specifies an the command line is used first, - regardless of whether or not - the <varname>$NUM_CPU</varname> environment - variable is set: - - </para> - - <scons_output example="SetOption"> - <scons_output_command>scons -Q -j 7</scons_output_command> - <scons_output_command>export NUM_CPU="4"</scons_output_command> - <scons_output_command environment="NUM_CPU=4">scons -Q -j 3</scons_output_command> - </scons_output> - - </section> - - <section id="sect-command-line-option-strings"> - <title>Strings for Getting or Setting Values of &SCons; Command-Line Options</title> - - <para> - - The strings that you can pass to the &GetOption; - and &SetOption; functions usually correspond to the - first long-form option name - (beginning with two hyphen characters: <literal>--</literal>), - after replacing any remaining hyphen characters - with underscores. - - </para> - - <para> - - The full list of strings and the variables they - correspond to is as follows: - - </para> - - <informaltable> - <tgroup cols="2" align="left"> - - <thead> - - <row> - <entry>String for &GetOption; and &SetOption;</entry> - <entry>Command-Line Option(s)</entry> - </row> - - </thead> - - <tbody> - - <row> - <entry><literal>cache_debug</literal></entry> - <entry><option>--cache-debug</option></entry> - </row> - - <row> - <entry><literal>cache_disable</literal></entry> - <entry><option>--cache-disable</option></entry> - </row> - - <row> - <entry><literal>cache_force</literal></entry> - <entry><option>--cache-force</option></entry> - </row> - - <row> - <entry><literal>cache_show</literal></entry> - <entry><option>--cache-show</option></entry> - </row> - - <row> - <entry><literal>clean</literal></entry> - <entry><option>-c</option>, - <option>--clean</option>, - <option>--remove</option></entry> - </row> - - <row> - <entry><literal>config</literal></entry> - <entry><option>--config</option></entry> - </row> - - <row> - <entry><literal>directory</literal></entry> - <entry><option>-C</option>, - <option>--directory</option></entry> - </row> - - <row> - <entry><literal>diskcheck</literal></entry> - <entry><option>--diskcheck</option></entry> - </row> - - <row> - <entry><literal>duplicate</literal></entry> - <entry><option>--duplicate</option></entry> - </row> - - <row> - <entry><literal>file</literal></entry> - <entry><option>-f</option>, - <option>--file</option>, - <option>--makefile </option>, - <option>--sconstruct</option></entry> - </row> - - <row> - <entry><literal>help</literal></entry> - <entry><option>-h</option>, - <option>--help</option></entry> - </row> - - <row> - <entry><literal>ignore_errors</literal></entry> - <entry><option>--ignore-errors</option></entry> - </row> - - <row> - <entry><literal>implicit_cache</literal></entry> - <entry><option>--implicit-cache</option></entry> - </row> - - <row> - <entry><literal>implicit_deps_changed</literal></entry> - <entry><option>--implicit-deps-changed</option></entry> - </row> - - <row> - <entry><literal>implicit_deps_unchanged</literal></entry> - <entry><option>--implicit-deps-unchanged</option></entry> - </row> - - <row> - <entry><literal>interactive</literal></entry> - <entry><option>--interact</option>, - <option>--interactive</option></entry> - </row> - - <row> - <entry><literal>keep_going</literal></entry> - <entry><option>-k</option>, - <option>--keep-going</option></entry> - </row> - - <row> - <entry><literal>max_drift</literal></entry> - <entry><option>--max-drift</option></entry> - </row> - - <row> - <entry><literal>no_exec</literal></entry> - <entry><option>-n</option>, - <option>--no-exec</option>, - <option>--just-print</option>, - <option>--dry-run</option>, - <option>--recon</option></entry> - </row> - - <row> - <entry><literal>no_site_dir</literal></entry> - <entry><option>--no-site-dir</option></entry> - </row> - - <row> - <entry><literal>num_jobs</literal></entry> - <entry><option>-j</option>, - <option>--jobs</option></entry> - </row> - - <row> - <entry><literal>profile_file</literal></entry> - <entry><option>--profile</option></entry> - </row> - - <row> - <entry><literal>question</literal></entry> - <entry><option>-q</option>, - <option>--question</option></entry> - </row> - - <row> - <entry><literal>random</literal></entry> - <entry><option>--random</option></entry> - </row> - - <row> - <entry><literal>repository</literal></entry> - <entry><option>-Y</option>, - <option>--repository</option>, - <option>--srcdir</option></entry> - </row> - - <row> - <entry><literal>silent</literal></entry> - <entry><option>-s</option>, - <option>--silent</option>, - <option>--quiet</option></entry> - </row> - - <row> - <entry><literal>site_dir</literal></entry> - <entry><option>--site-dir</option></entry> - </row> - - <row> - <entry><literal>stack_size</literal></entry> - <entry><option>--stack-size</option></entry> - </row> - - <row> - <entry><literal>taskmastertrace_file</literal></entry> - <entry><option>--taskmastertrace</option></entry> - </row> - - <row> - <entry><literal>warn</literal></entry> - <entry><option>--warn</option> <option>--warning</option></entry> - </row> - - </tbody> - - </tgroup> - </informaltable> - - </section> - - <section> - <title>Adding Custom Command-Line Options: the &AddOption; Function</title> - - <para> - - &SCons; also allows you to define your own - command-line options with the &AddOption; function. - The &AddOption; function takes the same arguments - as the <function>optparse.add_option</function> function - from the standard Python library. - <footnote> - <para> - The &AddOption; function is, - in fact, implemented using a subclass - of the <classname>optparse.OptionParser</classname>. - </para> - </footnote> - Once you have added a custom command-line option - with the &AddOption; function, - the value of the option (if any) is immediately available - using the standard &GetOption; function. - (The value can also be set using &SetOption;, - although that's not very useful in practice - because a default value can be specified in - directly in the &AddOption; call.) - - </para> - - <para> - - One useful example of using this functionality - is to provide a <option>--prefix</option> for users: - - </para> - - <scons_example name="AddOption"> - <file name="SConstruct" printme="1"> - AddOption('--prefix', - dest='prefix', - type='string', - nargs=1, - action='store', - metavar='DIR', - help='installation prefix') - - env = Environment(PREFIX = GetOption('prefix')) - - installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in') - Default(installed_foo) - </file> - <file name="foo.in"> - foo.in - </file> - </scons_example> - - <para> - - The above code uses the &GetOption; function - to set the <varname>$PREFIX</varname> - construction variable to any - value that the user specifies with a command-line - option of <literal>--prefix</literal>. - Because <varname>$PREFIX</varname> - will expand to a null string if it's not initialized, - running &SCons; without the - option of <literal>--prefix</literal> - will install the file in the - <filename>/usr/bin/</filename> directory: - - </para> - - <scons_output example="AddOption"> - <scons_output_command>scons -Q -n</scons_output_command> - </scons_output> - - <para> - - But specifying <literal>--prefix=/tmp/install</literal> - on the command line causes the file to be installed in the - <filename>/tmp/install/usr/bin/</filename> directory: - - </para> - - <scons_output example="AddOption"> - <scons_output_command>scons -Q -n --prefix=/tmp/install</scons_output_command> - </scons_output> - - </section> - - </section> - - <section id="sect-command-line-variables"> - <title>Command-Line <varname>variable</varname>=<varname>value</varname> Build Variables</title> - - <para> - - You may want to control various aspects - of your build by allowing the user - to specify <varname>variable</varname>=<varname>value</varname> - values on the command line. - For example, suppose you - want users to be able to - build a debug version of a program - by running &SCons; as follows: - - </para> - - <screen> - % <userinput>scons -Q debug=1</userinput> - </screen> - - <para> - - &SCons; provides an &ARGUMENTS; dictionary - that stores all of the - <varname>variable</varname>=<varname>value</varname> - assignments from the command line. - This allows you to modify - aspects of your build in response - to specifications on the command line. - (Note that unless you want to require - that users <emphasis>always</emphasis> - specify a variable, - you probably want to use - the Python - <literal>ARGUMENTS.get()</literal> function, - which allows you to specify a default value - to be used if there is no specification - on the command line.) - - </para> - - <para> - - The following code sets the &cv-link-CCFLAGS; construction - variable in response to the <varname>debug</varname> - flag being set in the &ARGUMENTS; dictionary: - - </para> - - <scons_example name="ARGUMENTS"> - <file name="SConstruct" printme="1"> - env = Environment() - debug = ARGUMENTS.get('debug', 0) - if int(debug): - env.Append(CCFLAGS = '-g') - env.Program('prog.c') - </file> - <file name="prog.c"> - prog.c - </file> - </scons_example> - - <para> - - This results in the <varname>-g</varname> - compiler option being used when - <literal>debug=1</literal> - is used on the command line: - - </para> - - <scons_output example="ARGUMENTS"> - <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> - - Notice that &SCons; keeps track of - the last values used to build the object files, - and as a result correctly rebuilds - the object and executable files - only when the value of the <literal>debug</literal> - argument has changed. - - </para> - - <para> - - The &ARGUMENTS; dictionary has two minor drawbacks. - First, because it is a dictionary, - it can only store one value for each specified keyword, - and thus only "remembers" the last setting - for each keyword on the command line. - This makes the &ARGUMENTS; dictionary - inappropriate if users should be able to - specify multiple values - on the command line for a given keyword. - Second, it does not preserve - the order in which the variable settings - were specified, - which is a problem if - you want the configuration to - behave differently in response - to the order in which the build - variable settings were specified on the command line. - - </para> - - <para> - - To accomodate these requirements, - &SCons; provides an &ARGLIST; variable - that gives you direct access to - <varname>variable</varname>=<varname>value</varname> - settings on the command line, - in the exact order they were specified, - and without removing any duplicate settings. - Each element in the &ARGLIST; variable - is itself a two-element list - containing the keyword and the value - of the setting, - and you must loop through, - or otherwise select from, - the elements of &ARGLIST; to - process the specific settings you want - in whatever way is appropriate for your configuration. - For example, - the following code to let the user - add to the &CPPDEFINES; construction variable - by specifying multiple - <varname>define=</varname> - settings on the command line: - - </para> - - <scons_example name="ARGLIST"> - <file name="SConstruct" printme="1"> - cppdefines = [] - for key, value in ARGLIST: - if key == 'define': - cppdefines.append(value) - env = Environment(CPPDEFINES = cppdefines) - env.Object('prog.c') - </file> - <file name="prog.c"> - prog.c - </file> - </scons_example> - - <para> - - Yields the following output: - - </para> - - <scons_output example="ARGLIST"> - <scons_output_command>scons -Q define=FOO</scons_output_command> - <scons_output_command>scons -Q define=FOO define=BAR</scons_output_command> - </scons_output> - - <para> - - Note that the &ARGLIST; and &ARGUMENTS; - variables do not interfere with each other, - but merely provide slightly different views - into how the user specified - <varname>variable</varname>=<varname>value</varname> - settings on the command line. - You can use both variables in the same - &SCons; configuration. - In general, the &ARGUMENTS; dictionary - is more convenient to use, - (since you can just fetch variable - settings through a dictionary access), - and the &ARGLIST; list - is more flexible - (since you can examine the - specific order in which - the user's command-line variabe settings). - - </para> - - <section> - <title>Controlling Command-Line Build Variables</title> - - <para> - - Being able to use a command-line build variable like - <literal>debug=1</literal> is handy, - but it can be a chore to write specific Python code - to recognize each such variable, - check for errors and provide appropriate messages, - and apply the values to a construction variable. - To help with this, - &SCons; supports a class to - define such build variables easily, - and a mechanism to apply the - build variables to a construction environment. - This allows you to control how the build variables affect - construction environments. - - </para> - - <para> - - For example, suppose that you want users to set - a &RELEASE; construction variable on the - command line whenever the time comes to build - a program for release, - and that the value of this variable - should be added to the command line - with the appropriate <literal>-D</literal> option - (or other command line option) - 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 - &cv-link-CPPDEFINES; construction variable: - - </para> - - <scons_example name="Variables1"> - <file name="SConstruct" printme="1"> - vars = Variables(None, ARGUMENTS) - vars.Add('RELEASE', 'Set to 1 to build for release', 0) - env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) - env.Program(['foo.c', 'bar.c']) - </file> - <file name="foo.c"> - foo.c - </file> - <file name="bar.c"> - bar.c - </file> - </scons_example> - - <para> - - This &SConstruct; file first creates a &Variables; object - which uses the values from the command-line options dictionary &ARGUMENTS; - (the <literal>vars = Variables(None, ARGUMENTS)</literal> call). - It then uses the object's &Add; - method to indicate that the &RELEASE; - variable can be set on the command line, - and that its default value will be <literal>0</literal> - (the third argument to the &Add; method). - The second argument is a line of help text; - we'll learn how to use it in the next section. - - </para> - - <para> - - We then pass the created &Variables; - object as a &variables; keyword argument - to the &Environment; call - used to create the construction environment. - This then allows a user to set the - &RELEASE; build variable on the command line - and have the variable show up in - the command line used to build each object from - a C source file: - - </para> - - <scons_output example="Variables1"> - <scons_output_command>scons -Q RELEASE=1</scons_output_command> - </scons_output> - - <para> - - NOTE: Before &SCons; release 0.98.1, these build variables - were known as "command-line build options." - The class was actually named the &Options; class, - and in the sections below, - the various functions were named - &BoolOption;, &EnumOption;, &ListOption;, - &PathOption;, &PackageOption; and &AddOptions;. - These older names still work, - and you may encounter them in older - &SConscript; files, - but they have been officially deprecated - as of &SCons; version 2.0. - - </para> - - </section> - - <section> - <title>Providing Help for Command-Line Build Variables</title> - - <para> - - To make command-line build variables most useful, - you ideally want to provide - some help text that will describe - the available variables - when the user runs <literal>scons -h</literal>. - You could write this text by hand, - but &SCons; provides an easier way. - &Variables; objects support a - &GenerateHelpText; method - that will, as its name suggests, - generate text that describes - the various variables that - have been added to it. - You then pass the output from this method to - the &Help; function: - - </para> - - <scons_example name="Variables_Help"> - <file name="SConstruct" printme="1"> - vars = Variables(None, ARGUMENTS) - vars.Add('RELEASE', 'Set to 1 to build for release', 0) - env = Environment(variables = vars) - Help(vars.GenerateHelpText(env)) - </file> - </scons_example> - - <para> - - &SCons; will now display some useful text - when the <literal>-h</literal> option is used: - - </para> - - <scons_output example="Variables_Help"> - <scons_output_command>scons -Q -h</scons_output_command> - </scons_output> - - <para> - - Notice that the help output shows the default value, - and the current actual value of the build variable. - - </para> - - </section> - - <section> - <title>Reading Build Variables From a File</title> - - <para> - - Giving the user a way to specify the - value of a build variable on the command line - is useful, - but can still be tedious - if users must specify the variable - every time they run &SCons;. - We can let users provide customized build variable settings - in a local file by providing a - file name when we create the - &Variables; object: - - </para> - - <scons_example name="Variables_custom_py_1"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add('RELEASE', 'Set to 1 to build for release', 0) - env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) - env.Program(['foo.c', 'bar.c']) - Help(vars.GenerateHelpText(env)) - </file> - <file name="foo.c"> - foo.c - </file> - <file name="bar.c"> - bar.c - </file> - <file name="custom.py"> - RELEASE = 1 - </file> - </scons_example> - - <para> - - This then allows the user to control the &RELEASE; - variable by setting it in the &custom_py; file: - - </para> - - <scons_example_file example="Variables_custom_py_1" name="custom.py"></scons_example_file> - - <para> - - Note that this file is actually executed - like a Python script. - Now when we run &SCons;: - - </para> - - <scons_output example="Variables_custom_py_1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - And if we change the contents of &custom_py; to: - - </para> - - <scons_example name="Variables_custom_py_2"> - <file name="SConstruct"> - vars = Variables('custom.py') - vars.Add('RELEASE', 'Set to 1 to build for release', 0) - env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) - env.Program(['foo.c', 'bar.c']) - Help(vars.GenerateHelpText(env)) - </file> - <file name="foo.c"> - foo.c - </file> - <file name="bar.c"> - bar.c - </file> - <file name="custom.py" printme="1"> - RELEASE = 0 - </file> - </scons_example> - - <para> - - The object files are rebuilt appropriately - with the new variable: - - </para> - - <scons_output example="Variables_custom_py_2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Finally, you can combine both methods with: - - </para> - - <screen> - vars = Variables('custom.py', ARGUMENTS) - </screen> - - <para> - - where values in the option file &custom_py; get overwritten - by the ones specified on the command line. - - </para> - - </section> - - <section> - <title>Pre-Defined Build Variable Functions</title> - - <para> - - &SCons; provides a number of functions - that provide ready-made behaviors - for various types of command-line build variables. - - </para> - - <section> - <title>True/False Values: the &BoolVariable; Build Variable Function</title> - - <para> - - It's often handy to be able to specify a - variable that controls a simple Boolean variable - with a &true; or &false; value. - It would be even more handy to accomodate - users who have different preferences for how to represent - &true; or &false; values. - The &BoolVariable; function - makes it easy to accomodate these - common representations of - &true; or &false;. - - </para> - - <para> - - The &BoolVariable; function takes three arguments: - the name of the build variable, - the default value of the build variable, - and the help string for the variable. - It then returns appropriate information for - passing to the &Add; method of a &Variables; object, like so: - - </para> - - <scons_example name="BoolVariable"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add(BoolVariable('RELEASE', 'Set to build for release', 0)) - env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - </scons_example> - - <para> - - With this build variable, - the &RELEASE; variable can now be enabled by - setting it to the value <literal>yes</literal> - or <literal>t</literal>: - - </para> - - <scons_output example="BoolVariable"> - <scons_output_command>scons -Q RELEASE=yes foo.o</scons_output_command> - </scons_output> - - <scons_output example="BoolVariable"> - <scons_output_command>scons -Q RELEASE=t foo.o</scons_output_command> - </scons_output> - - <para> - - Other values that equate to &true; include - <literal>y</literal>, - <literal>1</literal>, - <literal>on</literal> - and - <literal>all</literal>. - - </para> - - <para> - - Conversely, &RELEASE; may now be given a &false; - value by setting it to - <literal>no</literal> - or - <literal>f</literal>: - - </para> - - <scons_output example="BoolVariable"> - <scons_output_command>scons -Q RELEASE=no foo.o</scons_output_command> - </scons_output> - - <scons_output example="BoolVariable"> - <scons_output_command>scons -Q RELEASE=f foo.o</scons_output_command> - </scons_output> - - <para> - - Other values that equate to &false; include - <literal>n</literal>, - <literal>0</literal>, - <literal>off</literal> - and - <literal>none</literal>. - - </para> - - <para> - - Lastly, if a user tries to specify - any other value, - &SCons; supplies an appropriate error message: - - </para> - - <scons_output example="BoolVariable"> - <scons_output_command>scons -Q RELEASE=bad_value foo.o</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Single Value From a List: the &EnumVariable; Build Variable Function</title> - - <para> - - Suppose that we want a user to be able to - set a &COLOR; variable - that selects a background color to be - displayed by an application, - but that we want to restrict the - choices to a specific set of allowed colors. - This can be set up quite easily - using the &EnumVariable;, - which takes a list of &allowed_values; - in addition to the variable name, - default value, - and help text arguments: - - </para> - - <scons_example name="EnumVariable"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add(EnumVariable('COLOR', 'Set background color', 'red', - allowed_values=('red', 'green', 'blue'))) - env = Environment(variables = vars, - CPPDEFINES={'COLOR' : '"${COLOR}"'}) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - </scons_example> - - <para> - - The user can now explicity set the &COLOR; build variable - to any of the specified allowed values: - - </para> - - <scons_output example="EnumVariable"> - <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> - - But, almost more importantly, - an attempt to set &COLOR; - to a value that's not in the list - generates an error message: - - </para> - - <scons_output example="EnumVariable"> - <scons_output_command>scons -Q COLOR=magenta foo.o</scons_output_command> - </scons_output> - - <para> - - The &EnumVariable; function also supports a way - to map alternate names to allowed values. - Suppose, for example, - that we want to allow the user - to use the word <literal>navy</literal> as a synonym for - <literal>blue</literal>. - We do this by adding a ↦ dictionary - that will map its key values - to the desired legal value: - - </para> - - <scons_example name="EnumVariable_map"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add(EnumVariable('COLOR', 'Set background color', 'red', - allowed_values=('red', 'green', 'blue'), - map={'navy':'blue'})) - env = Environment(variables = vars, - CPPDEFINES={'COLOR' : '"${COLOR}"'}) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - </scons_example> - - <para> - - As desired, the user can then use - <literal>navy</literal> on the command line, - and &SCons; will translate it into <literal>blue</literal> - when it comes time to use the &COLOR; - variable to build a target: - - </para> - - <scons_output example="EnumVariable_map"> - <scons_output_command>scons -Q COLOR=navy foo.o</scons_output_command> - </scons_output> - - <para> - - By default, when using the &EnumVariable; function, - arguments that differ - from the legal values - only in case - are treated as illegal values: - - </para> - - <scons_output example="EnumVariable"> - <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> - - The &EnumVariable; function can take an additional - &ignorecase; keyword argument that, - when set to <literal>1</literal>, - tells &SCons; to allow case differences - when the values are specified: - - </para> - - <scons_example name="EnumVariable_ic1"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add(EnumVariable('COLOR', 'Set background color', 'red', - allowed_values=('red', 'green', 'blue'), - map={'navy':'blue'}, - ignorecase=1)) - env = Environment(variables = vars, - CPPDEFINES={'COLOR' : '"${COLOR}"'}) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - </scons_example> - - <para> - - Which yields the output: - - </para> - - <scons_output example="EnumVariable_ic1"> - <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> - - Notice that an &ignorecase; value of <literal>1</literal> - preserves the case-spelling that the user supplied. - If you want &SCons; to translate the names - into lower-case, - regardless of the case used by the user, - specify an &ignorecase; value of <literal>2</literal>: - - </para> - - <scons_example name="EnumVariable_ic2"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add(EnumVariable('COLOR', 'Set background color', 'red', - allowed_values=('red', 'green', 'blue'), - map={'navy':'blue'}, - ignorecase=2)) - env = Environment(variables = vars, - CPPDEFINES={'COLOR' : '"${COLOR}"'}) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - </scons_example> - - <para> - - Now &SCons; will use values of - <literal>red</literal>, - <literal>green</literal> or - <literal>blue</literal> - regardless of how the user spells - those values on the command line: - - </para> - - <scons_output example="EnumVariable_ic2"> - <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> - - <section> - <title>Multiple Values From a List: the &ListVariable; Build Variable Function</title> - - <para> - - Another way in which you might want to allow users - to control a build variable is to - specify a list of one or more legal values. - &SCons; supports this through the &ListVariable; function. - If, for example, we want a user to be able to set a - &COLORS; variable to one or more of the legal list of values: - - </para> - - <scons_example name="ListVariable"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add(ListVariable('COLORS', 'List of colors', 0, - ['red', 'green', 'blue'])) - env = Environment(variables = vars, - CPPDEFINES={'COLORS' : '"${COLORS}"'}) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - </scons_example> - - <para> - - A user can now specify a comma-separated list - of legal values, - which will get translated into a space-separated - list for passing to the any build commands: - - </para> - - <scons_output example="ListVariable"> - <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> - - In addition, the &ListVariable; function - allows the user to specify explicit keywords of - &all; or &none; - to select all of the legal values, - or none of them, respectively: - - </para> - - <scons_output example="ListVariable"> - <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> - - And, of course, an illegal value - still generates an error message: - - </para> - - <scons_output example="ListVariable"> - <scons_output_command>scons -Q COLORS=magenta foo.o</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Path Names: the &PathVariable; Build Variable Function</title> - - <para> - - &SCons; supports a &PathVariable; function - to make it easy to create a build variable - to control an expected path name. - If, for example, you need to - define a variable in the preprocessor - that controls the location of a - configuration file: - - </para> - - <scons_example name="PathVariable"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add(PathVariable('CONFIG', - 'Path to configuration file', - '__ROOT__/etc/my_config')) - env = Environment(variables = vars, - CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'}) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - <file name="__ROOT__/etc/my_config"> - /opt/location - </file> - <file name="__ROOT__/usr/local/etc/other_config"> - /opt/location - </file> - </scons_example> - - <para> - - This then allows the user to - override the &CONFIG; build variable - on the command line as necessary: - - </para> - - <scons_output example="PathVariable"> - <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> - - By default, &PathVariable; checks to make sure - that the specified path exists and generates an error if it - doesn't: - - </para> - - <scons_output example="PathVariable"> - <scons_output_command>scons -Q CONFIG=__ROOT__/does/not/exist foo.o</scons_output_command> - </scons_output> - - <para> - - &PathVariable; provides a number of methods - that you can use to change this behavior. - If you want to ensure that any specified paths are, - in fact, files and not directories, - use the &PathVariable_PathIsFile; method: - - </para> - - <scons_example name="PathIsFile"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add(PathVariable('CONFIG', - 'Path to configuration file', - '__ROOT__/etc/my_config', - PathVariable.PathIsFile)) - env = Environment(variables = vars, - CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'}) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - <file name="__ROOT__/etc/my_config"> - /opt/location - </file> - </scons_example> - - <para> - - Conversely, to ensure that any specified paths are - directories and not files, - use the &PathVariable_PathIsDir; method: - - </para> - - <scons_example name="PathIsDir"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add(PathVariable('DBDIR', - 'Path to database directory', - '__ROOT__/var/my_dbdir', - PathVariable.PathIsDir)) - env = Environment(variables = vars, - CPPDEFINES={'DBDIR' : '"$DBDIR"'}) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - <file name="__ROOT__/var/my_dbdir"> - /opt/location - </file> - </scons_example> - - <para> - - If you want to make sure that any specified paths - are directories, - and you would like the directory created - if it doesn't already exist, - use the &PathVariable_PathIsDirCreate; method: - - </para> - - <scons_example name="PathIsDirCreate"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add(PathVariable('DBDIR', - 'Path to database directory', - '__ROOT__/var/my_dbdir', - PathVariable.PathIsDirCreate)) - env = Environment(variables = vars, - CPPDEFINES={'DBDIR' : '"$DBDIR"'}) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - <file name="__ROOT__/var/my_dbdir"> - /opt/location - </file> - </scons_example> - - <para> - - Lastly, if you don't care whether the path exists, - is a file, or a directory, - use the &PathVariable_PathAccept; method - to accept any path that the user supplies: - - </para> - - <scons_example name="PathAccept"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add(PathVariable('OUTPUT', - 'Path to output file or directory', - None, - PathVariable.PathAccept)) - env = Environment(variables = vars, - CPPDEFINES={'OUTPUT' : '"$OUTPUT"'}) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - </scons_example> - - </section> - - <section> - <title>Enabled/Disabled Path Names: the &PackageVariable; Build Variable Function</title> - - <para> - - Sometimes you want to give users - even more control over a path name variable, - allowing them to explicitly enable or - disable the path name - by using <literal>yes</literal> or <literal>no</literal> keywords, - in addition to allow them - to supply an explicit path name. - &SCons; supports the &PackageVariable; - function to support this: - - </para> - - <scons_example name="PackageVariable"> - <file name="SConstruct" printme="1"> - vars = Variables('custom.py') - vars.Add(PackageVariable('PACKAGE', - 'Location package', - '__ROOT__/opt/location')) - env = Environment(variables = vars, - CPPDEFINES={'PACKAGE' : '"$PACKAGE"'}) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - <file name="__ROOT__/opt/location"> - /opt/location - </file> - <file name="__ROOT__/usr/local/location"> - /opt/location - </file> - </scons_example> - - <para> - - When the &SConscript; file uses the &PackageVariable; funciton, - user can now still use the default - or supply an overriding path name, - but can now explicitly set the - specified variable to a value - that indicates the package should be enabled - (in which case the default should be used) - or disabled: - - </para> - - <scons_output example="PackageVariable"> - <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> - - </section> - - <section> - <title>Adding Multiple Command-Line Build Variables at Once</title> - - <para> - - Lastly, &SCons; provides a way to add - multiple build variables to a &Variables; object at once. - Instead of having to call the &Add; method - multiple times, - you can call the &AddVariables; - method with a list of build variables - to be added to the object. - Each build variable is specified - as either a tuple of arguments, - just like you'd pass to the &Add; method itself, - or as a call to one of the pre-defined - functions for pre-packaged command-line build variables. - in any order: - - </para> - - <scons_example name="AddVariables_1"> - <file name="SConstruct" printme="1"> - vars = Variables() - vars.AddVariables( - ('RELEASE', 'Set to 1 to build for release', 0), - ('CONFIG', 'Configuration file', '/etc/my_config'), - BoolVariable('warnings', 'compilation with -Wall and similiar', 1), - EnumVariable('debug', 'debug output and symbols', 'no', - allowed_values=('yes', 'no', 'full'), - map={}, ignorecase=0), # case sensitive - ListVariable('shared', - 'libraries to build as shared libraries', - 'all', - names = list_of_libs), - PackageVariable('x11', - 'use X11 installed here (yes = search some places)', - 'yes'), - PathVariable('qtdir', 'where the root of Qt is installed', qtdir), - ) - </file> - </scons_example> - - <para> - </para> - - </section> - - <section> - <title>Handling Unknown Command-Line Build Variables: the &UnknownVariables; Function</title> - - <para> - - Users may, of course, - occasionally misspell variable names in their command-line settings. - &SCons; does not generate an error or warning - for any unknown variables the users specifies on the command line. - (This is in no small part because you may be - processing the arguments directly using the &ARGUMENTS; dictionary, - and therefore &SCons; can't know in the general case - whether a given "misspelled" variable is - really unknown and a potential problem, - or something that your &SConscript; file - will handle directly with some Python code.) - - </para> - - <para> - - If, however, you're using a &Variables; object to - define a specific set of command-line build variables - that you expect users to be able to set, - you may want to provide an error - message or warning of your own - if the user supplies a variable setting - that is <emphasis>not</emphasis> among - the defined list of variable names known to the &Variables; object. - You can do this by calling the &UnknownVariables; - method of the &Variables; object: - - </para> - - <scons_example name="UnknownVariables"> - <file name="SConstruct" printme="1"> - vars = Variables(None) - vars.Add('RELEASE', 'Set to 1 to build for release', 0) - env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) - unknown = vars.UnknownVariables() - if unknown: - print "Unknown variables:", unknown.keys() - Exit(1) - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - </scons_example> - - <para> - - The &UnknownVariables; method returns a dictionary - containing the keywords and values - of any variables the user specified on the command line - that are <emphasis>not</emphasis> - among the variables known to the &Variables; object - (from having been specified using - the &Variables; object's&Add; method). - In the examble above, - we check for whether the dictionary - returned by the &UnknownVariables; is non-empty, - and if so print the Python list - containing the names of the unknwown variables - and then call the &Exit; function - to terminate &SCons;: - - </para> - - <scons_output example="UnknownVariables"> - <scons_output_command>scons -Q NOT_KNOWN=foo</scons_output_command> - </scons_output> - - <para> - - Of course, you can process the items in the - dictionary returned by the &UnknownVariables; function - in any way appropriate to your build configuration, - including just printing a warning message - but not exiting, - logging an error somewhere, - etc. - - </para> - - <para> - - Note that you must delay the call of &UnknownVariables; - until after you have applied the &Variables; object - to a construction environment - with the <literal>variables=</literal> - keyword argument of an &Environment; call. - - </para> - - </section> - - </section> - - <section id="sect-command-line-targets"> - <title>Command-Line Targets</title> - - <section> - <title>Fetching Command-Line Targets: the &COMMAND_LINE_TARGETS; Variable</title> - - <para> - - &SCons; supports a &COMMAND_LINE_TARGETS; variable - that lets you fetch the list of targets that the - user specified on the command line. - You can use the targets to manipulate the - build in any way you wish. - As a simple example, - suppose that you want to print a reminder - to the user whenever a specific program is built. - You can do this by checking for the - target in the &COMMAND_LINE_TARGETS; list: - - </para> - - <scons_example name="COMMAND_LINE_TARGETS"> - <file name="SConstruct" printme="1"> - if 'bar' in COMMAND_LINE_TARGETS: - print "Don't forget to copy `bar' to the archive!" - Default(Program('foo.c')) - Program('bar.c') - </file> - <file name="foo.c"> - foo.c - </file> - <file name="bar.c"> - foo.c - </file> - </scons_example> - - <para> - - Then, running &SCons; with the default target - works as it always does, - but explicity specifying the &bar; target - on the command line generates the warning message: - - </para> - - <scons_output example="COMMAND_LINE_TARGETS"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q bar</scons_output_command> - </scons_output> - - <para> - - Another practical use for the &COMMAND_LINE_TARGETS; variable - might be to speed up a build - by only reading certain subsidiary &SConscript; - files if a specific target is requested. - - </para> - - </section> - - <section> - <title>Controlling the Default Targets: the &Default; Function</title> - - <para> - - One of the most basic things you can control - is which targets &SCons; will build by default--that is, - when there are no targets specified on the command line. - As mentioned previously, - &SCons; will normally build every target - in or below the current directory - by default--that is, when you don't - explicitly specify one or more targets - on the command line. - Sometimes, however, you may want - to specify explicitly that only - certain programs, or programs in certain directories, - should be built by default. - You do this with the &Default; function: - - </para> - - <scons_example name="Default1"> - <file name="SConstruct" printme="1"> - env = Environment() - hello = env.Program('hello.c') - env.Program('goodbye.c') - Default(hello) - </file> - <file name="hello.c"> - hello.c - </file> - <file name="goodbye.c"> - goodbye.c - </file> - </scons_example> - - <para> - - This &SConstruct; file knows how to build two programs, - &hello; and &goodbye;, - but only builds the - &hello; program by default: - - </para> - - <scons_output example="Default1"> - <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> - - Note that, even when you use the &Default; - function in your &SConstruct; file, - you can still explicitly specify the current directory - (<literal>.</literal>) on the command line - to tell &SCons; to build - everything in (or below) the current directory: - - </para> - - <scons_output example="Default1"> - <scons_output_command>scons -Q .</scons_output_command> - </scons_output> - - <para> - - You can also call the &Default; - function more than once, - in which case each call - adds to the list of targets to be built by default: - - </para> - - <scons_example name="Default2"> - <file name="SConstruct" printme="1"> - env = Environment() - prog1 = env.Program('prog1.c') - Default(prog1) - prog2 = env.Program('prog2.c') - prog3 = env.Program('prog3.c') - Default(prog3) - </file> - <file name="prog1.c"> - prog1.c - </file> - <file name="prog2.c"> - prog2.c - </file> - <file name="prog3.c"> - prog3.c - </file> - </scons_example> - - <para> - - Or you can specify more than one target - in a single call to the &Default; function: - - </para> - - <programlisting> - env = Environment() - prog1 = env.Program('prog1.c') - prog2 = env.Program('prog2.c') - prog3 = env.Program('prog3.c') - Default(prog1, prog3) - </programlisting> - - <para> - - Either of these last two examples - will build only the - <application>prog1</application> - and - <application>prog3</application> - programs by default: - - </para> - - <scons_output example="Default2"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q .</scons_output_command> - </scons_output> - - <para> - - You can list a directory as - an argument to &Default;: - - </para> - - <scons_example name="Default3"> - <file name="SConstruct" printme="1"> - env = Environment() - env.Program(['prog1/main.c', 'prog1/foo.c']) - env.Program(['prog2/main.c', 'prog2/bar.c']) - Default('prog1') - </file> - <directory name="prog1"></directory> - <directory name="prog2"></directory> - <file name="prog1/main.c"> - int main() { printf("prog1/main.c\n"); } - </file> - <file name="prog1/foo.c"> - int foo() { printf("prog1/foo.c\n"); } - </file> - <file name="prog2/main.c"> - int main() { printf("prog2/main.c\n"); } - </file> - <file name="prog2/bar.c"> - int bar() { printf("prog2/bar.c\n"); } - </file> - </scons_example> - - <para> - - In which case only the target(s) in that - directory will be built by default: - - </para> - - <scons_output example="Default3"> - <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> - - Lastly, if for some reason you don't want - any targets built by default, - you can use the Python <literal>None</literal> - variable: - - </para> - - <scons_example name="Default4"> - <file name="SConstruct" printme="1"> - env = Environment() - prog1 = env.Program('prog1.c') - prog2 = env.Program('prog2.c') - Default(None) - </file> - <file name="prog1.c"> - prog1.c - </file> - <file name="prog2.c"> - prog2.c - </file> - </scons_example> - - <para> - - Which would produce build output like: - - </para> - - <scons_output example="Default4"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q .</scons_output_command> - </scons_output> - - <section> - <title>Fetching the List of Default Targets: the &DEFAULT_TARGETS; Variable</title> - - <para> - - &SCons; supports a &DEFAULT_TARGETS; variable - that lets you get at the current list of default targets. - The &DEFAULT_TARGETS; variable has - two important differences from the &COMMAND_LINE_TARGETS; variable. - First, the &DEFAULT_TARGETS; variable is a list of - internal &SCons; nodes, - so you need to convert the list elements to strings - if you want to print them or look for a specific target name. - Fortunately, you can do this easily - by using the Python <function>map</function> function - to run the list through <function>str</function>: - - </para> - - <scons_example name="DEFAULT_TARGETS_1"> - <file name="SConstruct" printme="1"> - prog1 = Program('prog1.c') - Default(prog1) - print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS) - </file> - <file name="prog1.c"> - prog1.c - </file> - </scons_example> - - <para> - - (Keep in mind that all of the manipulation of the - &DEFAULT_TARGETS; list takes place during the - first phase when &SCons; is reading up the &SConscript; files, - which is obvious if - we leave off the <literal>-Q</literal> flag when we run &SCons;:) - - </para> - - <scons_output example="DEFAULT_TARGETS_1"> - <scons_output_command>scons</scons_output_command> - </scons_output> - - <para> - - Second, - the contents of the &DEFAULT_TARGETS; list change - in response to calls to the &Default; function, - as you can see from the following &SConstruct; file: - - </para> - - <scons_example name="DEFAULT_TARGETS_2"> - <file name="SConstruct" printme="1"> - prog1 = Program('prog1.c') - Default(prog1) - print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS) - prog2 = Program('prog2.c') - Default(prog2) - print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS) - </file> - <file name="prog1.c"> - prog1.c - </file> - <file name="prog2.c"> - prog2.c - </file> - </scons_example> - - <para> - - Which yields the output: - - </para> - - <scons_output example="DEFAULT_TARGETS_2"> - <scons_output_command>scons</scons_output_command> - </scons_output> - - <para> - - In practice, this simply means that you - need to pay attention to the order in - which you call the &Default; function - and refer to the &DEFAULT_TARGETS; list, - to make sure that you don't examine the - list before you've added the default targets - you expect to find in it. - - </para> - - </section> - - </section> - - <section> - <title>Fetching the List of Build Targets, Regardless of Origin: the &BUILD_TARGETS; Variable</title> - - <para> - - We've already been introduced to the - &COMMAND_LINE_TARGETS; variable, - which contains a list of targets specified on the command line, - and the &DEFAULT_TARGETS; variable, - which contains a list of targets specified - via calls to the &Default; method or function. - Sometimes, however, - you want a list of whatever targets - &SCons; will try to build, - regardless of whether the targets came from the - command line or a &Default; call. - You could code this up by hand, as follows: - - </para> - - <sconstruct> - if COMMAND_LINE_TARGETS: - targets = COMMAND_LINE_TARGETS - else: - targets = DEFAULT_TARGETS - </sconstruct> - - <para> - - &SCons;, however, provides a convenient - &BUILD_TARGETS; variable - that eliminates the need for this by-hand manipulation. - Essentially, the &BUILD_TARGETS; variable - contains a list of the command-line targets, - if any were specified, - and if no command-line targets were specified, - it contains a list of the targets specified - via the &Default; method or function. - - </para> - - <para> - - Because &BUILD_TARGETS; may contain a list of &SCons; nodes, - you must convert the list elements to strings - if you want to print them or look for a specific target name, - just like the &DEFAULT_TARGETS; list: - - </para> - - <scons_example name="BUILD_TARGETS_1"> - <file name="SConstruct" printme="1"> - prog1 = Program('prog1.c') - Program('prog2.c') - Default(prog1) - print "BUILD_TARGETS is", map(str, BUILD_TARGETS) - </file> - <file name="prog1.c"> - prog1.c - </file> - <file name="prog2.c"> - prog2.c - </file> - </scons_example> - - <para> - - Notice how the value of &BUILD_TARGETS; - changes depending on whether a target is - specified on the command line: - - </para> - - <scons_output example="BUILD_TARGETS_1"> - <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> - - </section> diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index 1888ac0..2819d3d 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-command-line" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Controlling a Build From the Command Line</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -146,19 +168,26 @@ </para> - - - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - ... [build output] ... - scons: done building targets. - % <userinput>export SCONSFLAGS="-Q"</userinput> - % <userinput>scons</userinput> - ... [build output] ... - </screen> + <scons_example name="commandline_SCONSFLAGS"> + <file name="SConstruct"> +def b(target, source, env): + pass +def s(target, source, env): + return " ... [build output] ..." +a = Action(b, strfunction = s) +env = Environment(BUILDERS = {'A' : Builder(action=a)}) +env.A('foo.out', 'foo.in') + </file> + <file name="foo.in"> +foo.in + </file> + </scons_example> + + <scons_output example="commandline_SCONSFLAGS" suffix="1"> + <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> @@ -168,7 +197,7 @@ </para> <screen> - $ <userinput>setenv SCONSFLAGS "-Q"</userinput> +$ <userinput>setenv SCONSFLAGS "-Q"</userinput> </screen> <para> @@ -214,10 +243,10 @@ </para> - <programlisting> - if not GetOption('help'): - SConscript('src/SConscript', export='env') - </programlisting> + <sconstruct> +if not GetOption('help'): + SConscript('src/SConscript', export='env') + </sconstruct> <para> @@ -283,12 +312,17 @@ </para> - <programlisting> - import os - num_cpu = int(os.environ.get('NUM_CPU', 2)) - SetOption('num_jobs', num_cpu) - print "running with -j", GetOption('num_jobs') - </programlisting> + <scons_example name="commandline_SetOption"> + <file name="SConstruct" printme="1"> +import os +num_cpu = int(os.environ.get('NUM_CPU', 2)) +SetOption('num_jobs', num_cpu) +print "running with -j", GetOption('num_jobs') + </file> + <file name="foo.in"> +foo.in + </file> + </scons_example> <para> @@ -310,11 +344,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - running with -j 2 - scons: `.' is up to date. - </screen> + <scons_output example="commandline_SetOption" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -324,12 +356,10 @@ </para> - <screen> - % <userinput>export NUM_CPU="4"</userinput> - % <userinput>scons -Q</userinput> - running with -j 4 - scons: `.' is up to date. - </screen> + <scons_output example="commandline_SetOption" suffix="2"> + <scons_output_command>export NUM_CPU="4"</scons_output_command> + <scons_output_command environment="NUM_CPU=4">scons -Q</scons_output_command> + </scons_output> <para> @@ -342,15 +372,11 @@ </para> - <screen> - % <userinput>scons -Q -j 7</userinput> - running with -j 7 - scons: `.' is up to date. - % <userinput>export NUM_CPU="4"</userinput> - % <userinput>scons -Q -j 3</userinput> - running with -j 3 - scons: `.' is up to date. - </screen> + <scons_output example="commandline_SetOption" suffix="3"> + <scons_output_command>scons -Q -j 7</scons_output_command> + <scons_output_command>export NUM_CPU="4"</scons_output_command> + <scons_output_command environment="NUM_CPU=4">scons -Q -j 3</scons_output_command> + </scons_output> </section> @@ -600,20 +626,25 @@ </para> - <programlisting> - AddOption('--prefix', - dest='prefix', - type='string', - nargs=1, - action='store', - metavar='DIR', - help='installation prefix') - - env = Environment(PREFIX = GetOption('prefix')) - - installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in') - Default(installed_foo) - </programlisting> + <scons_example name="commandline_AddOption"> + <file name="SConstruct" printme="1"> +AddOption('--prefix', + dest='prefix', + type='string', + nargs=1, + action='store', + metavar='DIR', + help='installation prefix') + +env = Environment(PREFIX = GetOption('prefix')) + +installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in') +Default(installed_foo) + </file> + <file name="foo.in"> +foo.in + </file> + </scons_example> <para> @@ -631,10 +662,9 @@ </para> - <screen> - % <userinput>scons -Q -n</userinput> - Install file: "foo.in" as "/usr/bin/foo.in" - </screen> + <scons_output example="commandline_AddOption" suffix="1"> + <scons_output_command>scons -Q -n</scons_output_command> + </scons_output> <para> @@ -644,10 +674,9 @@ </para> - <screen> - % <userinput>scons -Q -n --prefix=/tmp/install</userinput> - Install file: "foo.in" as "/tmp/install/usr/bin/foo.in" - </screen> + <scons_output example="commandline_AddOption" suffix="2"> + <scons_output_command>scons -Q -n --prefix=/tmp/install</scons_output_command> + </scons_output> </section> @@ -670,7 +699,7 @@ </para> <screen> - % <userinput>scons -Q debug=1</userinput> +% <userinput>scons -Q debug=1</userinput> </screen> <para> @@ -702,13 +731,18 @@ </para> - <programlisting> - env = Environment() - debug = ARGUMENTS.get('debug', 0) - if int(debug): - env.Append(CCFLAGS = '-g') - env.Program('prog.c') - </programlisting> + <scons_example name="commandline_ARGUMENTS"> + <file name="SConstruct" printme="1"> +env = Environment() +debug = ARGUMENTS.get('debug', 0) +if int(debug): + env.Append(CCFLAGS = '-g') +env.Program('prog.c') + </file> + <file name="prog.c"> +prog.c + </file> + </scons_example> <para> @@ -719,18 +753,12 @@ </para> - <screen> - % <userinput>scons -Q debug=0</userinput> - cc -o prog.o -c prog.c - cc -o prog prog.o - % <userinput>scons -Q debug=0</userinput> - scons: `.' is up to date. - % <userinput>scons -Q debug=1</userinput> - cc -o prog.o -c -g prog.c - cc -o prog prog.o - % <userinput>scons -Q debug=1</userinput> - scons: `.' is up to date. - </screen> + <scons_output example="commandline_ARGUMENTS" suffix="1"> + <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> @@ -792,14 +820,19 @@ </para> - <programlisting> - cppdefines = [] - for key, value in ARGLIST: - if key == 'define': - cppdefines.append(value) - env = Environment(CPPDEFINES = cppdefines) - env.Object('prog.c') - </programlisting> + <scons_example name="commandline_ARGLIST"> + <file name="SConstruct" printme="1"> +cppdefines = [] +for key, value in ARGLIST: + if key == 'define': + cppdefines.append(value) +env = Environment(CPPDEFINES = cppdefines) +env.Object('prog.c') + </file> + <file name="prog.c"> +prog.c + </file> + </scons_example> <para> @@ -807,12 +840,10 @@ </para> - <screen> - % <userinput>scons -Q define=FOO</userinput> - cc -o prog.o -c -DFOO prog.c - % <userinput>scons -Q define=FOO define=BAR</userinput> - cc -o prog.o -c -DFOO -DBAR prog.c - </screen> + <scons_output example="commandline_ARGLIST" suffix="1"> + <scons_output_command>scons -Q define=FOO</scons_output_command> + <scons_output_command>scons -Q define=FOO define=BAR</scons_output_command> + </scons_output> <para> @@ -874,13 +905,21 @@ </para> - <programlisting> - vars = Variables(None, ARGUMENTS) - vars.Add('RELEASE', 'Set to 1 to build for release', 0) - env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) - env.Program(['foo.c', 'bar.c']) - </programlisting> + <scons_example name="commandline_Variables1"> + <file name="SConstruct" printme="1"> +vars = Variables(None, ARGUMENTS) +vars.Add('RELEASE', 'Set to 1 to build for release', 0) +env = Environment(variables = vars, + CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) +env.Program(['foo.c', 'bar.c']) + </file> + <file name="foo.c"> +foo.c + </file> + <file name="bar.c"> +bar.c + </file> + </scons_example> <para> @@ -911,12 +950,9 @@ </para> - <screen> - % <userinput>scons -Q RELEASE=1</userinput> - cc -o bar.o -c -DRELEASE_BUILD=1 bar.c - cc -o foo.o -c -DRELEASE_BUILD=1 foo.c - cc -o foo foo.o bar.o - </screen> + <scons_output example="commandline_Variables1" suffix="1"> + <scons_output_command>scons -Q RELEASE=1</scons_output_command> + </scons_output> <para> @@ -960,12 +996,14 @@ </para> - <programlisting> - vars = Variables(None, ARGUMENTS) - vars.Add('RELEASE', 'Set to 1 to build for release', 0) - env = Environment(variables = vars) - Help(vars.GenerateHelpText(env)) - </programlisting> + <scons_example name="commandline_Variables_Help"> + <file name="SConstruct" printme="1"> +vars = Variables(None, ARGUMENTS) +vars.Add('RELEASE', 'Set to 1 to build for release', 0) +env = Environment(variables = vars) +Help(vars.GenerateHelpText(env)) + </file> + </scons_example> <para> @@ -974,15 +1012,9 @@ </para> - <screen> - % <userinput>scons -Q -h</userinput> - - RELEASE: Set to 1 to build for release - default: 0 - actual: 0 - - Use scons -H for help about command-line options. - </screen> + <scons_output example="commandline_Variables_Help" suffix="1"> + <scons_output_command>scons -Q -h</scons_output_command> + </scons_output> <para> @@ -1011,14 +1043,25 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add('RELEASE', 'Set to 1 to build for release', 0) - env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) - env.Program(['foo.c', 'bar.c']) - Help(vars.GenerateHelpText(env)) - </programlisting> + <scons_example name="commandline_Variables_custom_py_1"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add('RELEASE', 'Set to 1 to build for release', 0) +env = Environment(variables = vars, + CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) +env.Program(['foo.c', 'bar.c']) +Help(vars.GenerateHelpText(env)) + </file> + <file name="foo.c"> +foo.c + </file> + <file name="bar.c"> +bar.c + </file> + <file name="custom.py"> +RELEASE = 1 + </file> + </scons_example> <para> @@ -1027,9 +1070,7 @@ </para> - <programlisting> - RELEASE = 1 - </programlisting> + <scons_example_file example="commandline_Variables_custom_py_1" name="custom.py"></scons_example_file> <para> @@ -1039,12 +1080,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o bar.o -c -DRELEASE_BUILD=1 bar.c - cc -o foo.o -c -DRELEASE_BUILD=1 foo.c - cc -o foo foo.o bar.o - </screen> + <scons_output example="commandline_Variables_custom_py_1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1052,9 +1090,25 @@ </para> - <programlisting> - RELEASE = 0 - </programlisting> + <scons_example name="commandline_Variables_custom_py_2"> + <file name="SConstruct"> + vars = Variables('custom.py') + vars.Add('RELEASE', 'Set to 1 to build for release', 0) + env = Environment(variables = vars, + CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) + env.Program(['foo.c', 'bar.c']) + Help(vars.GenerateHelpText(env)) + </file> + <file name="foo.c"> +foo.c + </file> + <file name="bar.c"> +bar.c + </file> + <file name="custom.py" printme="1"> +RELEASE = 0 + </file> + </scons_example> <para> @@ -1063,12 +1117,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o bar.o -c -DRELEASE_BUILD=0 bar.c - cc -o foo.o -c -DRELEASE_BUILD=0 foo.c - cc -o foo foo.o bar.o - </screen> + <scons_output example="commandline_Variables_custom_py_2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1077,7 +1128,7 @@ </para> <screen> - vars = Variables('custom.py', ARGUMENTS) +vars = Variables('custom.py', ARGUMENTS) </screen> <para> @@ -1129,13 +1180,18 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add(BoolVariable('RELEASE', 'Set to build for release', 0)) - env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) - env.Program('foo.c') - </programlisting> + <scons_example name="commandline_BoolVariable"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add(BoolVariable('RELEASE', 'Set to build for release', 0)) +env = Environment(variables = vars, + CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + </scons_example> <para> @@ -1146,15 +1202,13 @@ </para> - <screen> - % <userinput>scons -Q RELEASE=yes foo.o</userinput> - cc -o foo.o -c -DRELEASE_BUILD=True foo.c - </screen> + <scons_output example="commandline_BoolVariable" suffix="1"> + <scons_output_command>scons -Q RELEASE=yes foo.o</scons_output_command> + </scons_output> - <screen> - % <userinput>scons -Q RELEASE=t foo.o</userinput> - cc -o foo.o -c -DRELEASE_BUILD=True foo.c - </screen> + <scons_output example="commandline_BoolVariable" suffix="2"> + <scons_output_command>scons -Q RELEASE=t foo.o</scons_output_command> + </scons_output> <para> @@ -1177,15 +1231,13 @@ </para> - <screen> - % <userinput>scons -Q RELEASE=no foo.o</userinput> - cc -o foo.o -c -DRELEASE_BUILD=False foo.c - </screen> + <scons_output example="commandline_BoolVariable" suffix="3"> + <scons_output_command>scons -Q RELEASE=no foo.o</scons_output_command> + </scons_output> - <screen> - % <userinput>scons -Q RELEASE=f foo.o</userinput> - cc -o foo.o -c -DRELEASE_BUILD=False foo.c - </screen> + <scons_output example="commandline_BoolVariable" suffix="4"> + <scons_output_command>scons -Q RELEASE=f foo.o</scons_output_command> + </scons_output> <para> @@ -1206,13 +1258,9 @@ </para> - <screen> - % <userinput>scons -Q RELEASE=bad_value foo.o</userinput> - - scons: *** Error converting option: RELEASE - Invalid value for boolean option: bad_value - File "/home/my/project/SConstruct", line 4, in <module> - </screen> + <scons_output example="commandline_BoolVariable" suffix="5"> + <scons_output_command>scons -Q RELEASE=bad_value foo.o</scons_output_command> + </scons_output> </section> @@ -1236,14 +1284,19 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add(EnumVariable('COLOR', 'Set background color', 'red', - allowed_values=('red', 'green', 'blue'))) - env = Environment(variables = vars, - CPPDEFINES={'COLOR' : '"${COLOR}"'}) - env.Program('foo.c') - </programlisting> + <scons_example name="commandline_EnumVariable"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add(EnumVariable('COLOR', 'Set background color', 'red', + allowed_values=('red', 'green', 'blue'))) +env = Environment(variables = vars, + CPPDEFINES={'COLOR' : '"${COLOR}"'}) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + </scons_example> <para> @@ -1252,14 +1305,11 @@ </para> - <screen> - % <userinput>scons -Q COLOR=red foo.o</userinput> - cc -o foo.o -c -DCOLOR="red" foo.c - % <userinput>scons -Q COLOR=blue foo.o</userinput> - cc -o foo.o -c -DCOLOR="blue" foo.c - % <userinput>scons -Q COLOR=green foo.o</userinput> - cc -o foo.o -c -DCOLOR="green" foo.c - </screen> + <scons_output example="commandline_EnumVariable" suffix="1"> + <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> @@ -1270,12 +1320,9 @@ </para> - <screen> - % <userinput>scons -Q COLOR=magenta foo.o</userinput> - - scons: *** Invalid value for option COLOR: magenta. Valid values are: ('red', 'green', 'blue') - File "/home/my/project/SConstruct", line 5, in <module> - </screen> + <scons_output example="commandline_EnumVariable" suffix="2"> + <scons_output_command>scons -Q COLOR=magenta foo.o</scons_output_command> + </scons_output> <para> @@ -1291,15 +1338,20 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add(EnumVariable('COLOR', 'Set background color', 'red', - allowed_values=('red', 'green', 'blue'), - map={'navy':'blue'})) - env = Environment(variables = vars, - CPPDEFINES={'COLOR' : '"${COLOR}"'}) - env.Program('foo.c') - </programlisting> + <scons_example name="EnumVariable_map"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add(EnumVariable('COLOR', 'Set background color', 'red', + allowed_values=('red', 'green', 'blue'), + map={'navy':'blue'})) +env = Environment(variables = vars, + CPPDEFINES={'COLOR' : '"${COLOR}"'}) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + </scons_example> <para> @@ -1311,10 +1363,9 @@ </para> - <screen> - % <userinput>scons -Q COLOR=navy foo.o</userinput> - cc -o foo.o -c -DCOLOR="blue" foo.c - </screen> + <scons_output example="EnumVariable_map" suffix="1"> + <scons_output_command>scons -Q COLOR=navy foo.o</scons_output_command> + </scons_output> <para> @@ -1326,20 +1377,11 @@ </para> - <screen> - % <userinput>scons -Q COLOR=Red foo.o</userinput> - - scons: *** Invalid value for option COLOR: Red. Valid values are: ('red', 'green', 'blue') - File "/home/my/project/SConstruct", line 5, in <module> - % <userinput>scons -Q COLOR=BLUE foo.o</userinput> - - scons: *** Invalid value for option COLOR: BLUE. Valid values are: ('red', 'green', 'blue') - File "/home/my/project/SConstruct", line 5, in <module> - % <userinput>scons -Q COLOR=nAvY foo.o</userinput> - - scons: *** Invalid value for option COLOR: nAvY. Valid values are: ('red', 'green', 'blue') - File "/home/my/project/SConstruct", line 5, in <module> - </screen> + <scons_output example="commandline_EnumVariable" suffix="3"> + <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> @@ -1351,16 +1393,21 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add(EnumVariable('COLOR', 'Set background color', 'red', - allowed_values=('red', 'green', 'blue'), - map={'navy':'blue'}, - ignorecase=1)) - env = Environment(variables = vars, - CPPDEFINES={'COLOR' : '"${COLOR}"'}) - env.Program('foo.c') - </programlisting> + <scons_example name="commandline_EnumVariable_ic1"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add(EnumVariable('COLOR', 'Set background color', 'red', + allowed_values=('red', 'green', 'blue'), + map={'navy':'blue'}, + ignorecase=1)) +env = Environment(variables = vars, + CPPDEFINES={'COLOR' : '"${COLOR}"'}) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + </scons_example> <para> @@ -1368,16 +1415,12 @@ </para> - <screen> - % <userinput>scons -Q COLOR=Red foo.o</userinput> - cc -o foo.o -c -DCOLOR="Red" foo.c - % <userinput>scons -Q COLOR=BLUE foo.o</userinput> - cc -o foo.o -c -DCOLOR="BLUE" foo.c - % <userinput>scons -Q COLOR=nAvY foo.o</userinput> - cc -o foo.o -c -DCOLOR="blue" foo.c - % <userinput>scons -Q COLOR=green foo.o</userinput> - cc -o foo.o -c -DCOLOR="green" foo.c - </screen> + <scons_output example="commandline_EnumVariable_ic1" suffix="1"> + <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> @@ -1390,16 +1433,21 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add(EnumVariable('COLOR', 'Set background color', 'red', - allowed_values=('red', 'green', 'blue'), - map={'navy':'blue'}, - ignorecase=2)) - env = Environment(variables = vars, - CPPDEFINES={'COLOR' : '"${COLOR}"'}) - env.Program('foo.c') - </programlisting> + <scons_example name="commandline_EnumVariable_ic2"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add(EnumVariable('COLOR', 'Set background color', 'red', + allowed_values=('red', 'green', 'blue'), + map={'navy':'blue'}, + ignorecase=2)) +env = Environment(variables = vars, + CPPDEFINES={'COLOR' : '"${COLOR}"'}) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + </scons_example> <para> @@ -1412,14 +1460,11 @@ </para> - <screen> - % <userinput>scons -Q COLOR=Red foo.o</userinput> - cc -o foo.o -c -DCOLOR="red" foo.c - % <userinput>scons -Q COLOR=nAvY foo.o</userinput> - cc -o foo.o -c -DCOLOR="blue" foo.c - % <userinput>scons -Q COLOR=GREEN foo.o</userinput> - cc -o foo.o -c -DCOLOR="green" foo.c - </screen> + <scons_output example="commandline_EnumVariable_ic2" suffix="1"> + <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> @@ -1437,14 +1482,19 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add(ListVariable('COLORS', 'List of colors', 0, - ['red', 'green', 'blue'])) - env = Environment(variables = vars, - CPPDEFINES={'COLORS' : '"${COLORS}"'}) - env.Program('foo.c') - </programlisting> + <scons_example name="commandline_ListVariable"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add(ListVariable('COLORS', 'List of colors', 0, + ['red', 'green', 'blue'])) +env = Environment(variables = vars, + CPPDEFINES={'COLORS' : '"${COLORS}"'}) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + </scons_example> <para> @@ -1455,12 +1505,10 @@ </para> - <screen> - % <userinput>scons -Q COLORS=red,blue foo.o</userinput> - cc -o foo.o -c -DCOLORS="red blue" foo.c - % <userinput>scons -Q COLORS=blue,green,red foo.o</userinput> - cc -o foo.o -c -DCOLORS="blue green red" foo.c - </screen> + <scons_output example="commandline_ListVariable" suffix="1"> + <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> @@ -1472,12 +1520,10 @@ </para> - <screen> - % <userinput>scons -Q COLORS=all foo.o</userinput> - cc -o foo.o -c -DCOLORS="red green blue" foo.c - % <userinput>scons -Q COLORS=none foo.o</userinput> - cc -o foo.o -c -DCOLORS="" foo.c - </screen> + <scons_output example="commandline_ListVariable" suffix="2"> + <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> @@ -1486,13 +1532,9 @@ </para> - <screen> - % <userinput>scons -Q COLORS=magenta foo.o</userinput> - - scons: *** Error converting option: COLORS - Invalid value(s) for option: magenta - File "/home/my/project/SConstruct", line 5, in <module> - </screen> + <scons_output example="commandline_ListVariable" suffix="3"> + <scons_output_command>scons -Q COLORS=magenta foo.o</scons_output_command> + </scons_output> </section> @@ -1511,15 +1553,26 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add(PathVariable('CONFIG', - 'Path to configuration file', - '/etc/my_config')) - env = Environment(variables = vars, - CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'}) - env.Program('foo.c') - </programlisting> + <scons_example name="commandline_PathVariable"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add(PathVariable('CONFIG', + 'Path to configuration file', + '__ROOT__/etc/my_config')) +env = Environment(variables = vars, + CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'}) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + <file name="__ROOT__/etc/my_config"> +/opt/location + </file> + <file name="__ROOT__/usr/local/etc/other_config"> +/opt/location + </file> + </scons_example> <para> @@ -1529,12 +1582,10 @@ </para> - <screen> - % <userinput>scons -Q foo.o</userinput> - cc -o foo.o -c -DCONFIG_FILE="/etc/my_config" foo.c - % <userinput>scons -Q CONFIG=/usr/local/etc/other_config foo.o</userinput> - scons: `foo.o' is up to date. - </screen> + <scons_output example="commandline_PathVariable" suffix="1"> + <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> @@ -1544,12 +1595,9 @@ </para> - <screen> - % <userinput>scons -Q CONFIG=/does/not/exist foo.o</userinput> - - scons: *** Path for option CONFIG does not exist: /does/not/exist - File "/home/my/project/SConstruct", line 6, in <module> - </screen> + <scons_output example="commandline_PathVariable" suffix="2"> + <scons_output_command>scons -Q CONFIG=__ROOT__/does/not/exist foo.o</scons_output_command> + </scons_output> <para> @@ -1561,16 +1609,24 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add(PathVariable('CONFIG', - 'Path to configuration file', - '/etc/my_config', - PathVariable.PathIsFile)) - env = Environment(variables = vars, - CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'}) - env.Program('foo.c') - </programlisting> + <scons_example name="commandline_PathIsFile"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add(PathVariable('CONFIG', + 'Path to configuration file', + '__ROOT__/etc/my_config', + PathVariable.PathIsFile)) +env = Environment(variables = vars, + CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'}) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + <file name="__ROOT__/etc/my_config"> +/opt/location + </file> + </scons_example> <para> @@ -1580,16 +1636,24 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add(PathVariable('DBDIR', - 'Path to database directory', - '/var/my_dbdir', - PathVariable.PathIsDir)) - env = Environment(variables = vars, - CPPDEFINES={'DBDIR' : '"$DBDIR"'}) - env.Program('foo.c') - </programlisting> + <scons_example name="commandline_PathIsDir"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add(PathVariable('DBDIR', + 'Path to database directory', + '__ROOT__/var/my_dbdir', + PathVariable.PathIsDir)) +env = Environment(variables = vars, + CPPDEFINES={'DBDIR' : '"$DBDIR"'}) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + <file name="__ROOT__/var/my_dbdir"> +/opt/location + </file> + </scons_example> <para> @@ -1601,16 +1665,24 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add(PathVariable('DBDIR', - 'Path to database directory', - '/var/my_dbdir', - PathVariable.PathIsDirCreate)) - env = Environment(variables = vars, - CPPDEFINES={'DBDIR' : '"$DBDIR"'}) - env.Program('foo.c') - </programlisting> + <scons_example name="commandline_PathIsDirCreate"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add(PathVariable('DBDIR', + 'Path to database directory', + '__ROOT__/var/my_dbdir', + PathVariable.PathIsDirCreate)) +env = Environment(variables = vars, + CPPDEFINES={'DBDIR' : '"$DBDIR"'}) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + <file name="__ROOT__/var/my_dbdir"> +/opt/location + </file> + </scons_example> <para> @@ -1621,16 +1693,21 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add(PathVariable('OUTPUT', - 'Path to output file or directory', - None, - PathVariable.PathAccept)) - env = Environment(variables = vars, - CPPDEFINES={'OUTPUT' : '"$OUTPUT"'}) - env.Program('foo.c') - </programlisting> + <scons_example name="commandline_PathAccept"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add(PathVariable('OUTPUT', + 'Path to output file or directory', + None, + PathVariable.PathAccept)) +env = Environment(variables = vars, + CPPDEFINES={'OUTPUT' : '"$OUTPUT"'}) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + </scons_example> </section> @@ -1651,15 +1728,26 @@ </para> - <programlisting> - vars = Variables('custom.py') - vars.Add(PackageVariable('PACKAGE', - 'Location package', - '/opt/location')) - env = Environment(variables = vars, - CPPDEFINES={'PACKAGE' : '"$PACKAGE"'}) - env.Program('foo.c') - </programlisting> + <scons_example name="commandline_PackageVariable"> + <file name="SConstruct" printme="1"> +vars = Variables('custom.py') +vars.Add(PackageVariable('PACKAGE', + 'Location package', + '__ROOT__/opt/location')) +env = Environment(variables = vars, + CPPDEFINES={'PACKAGE' : '"$PACKAGE"'}) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + <file name="__ROOT__/opt/location"> +/opt/location + </file> + <file name="__ROOT__/usr/local/location"> +/opt/location + </file> + </scons_example> <para> @@ -1674,16 +1762,12 @@ </para> - <screen> - % <userinput>scons -Q foo.o</userinput> - cc -o foo.o -c -DPACKAGE="/opt/location" foo.c - % <userinput>scons -Q PACKAGE=/usr/local/location foo.o</userinput> - cc -o foo.o -c -DPACKAGE="/usr/local/location" foo.c - % <userinput>scons -Q PACKAGE=yes foo.o</userinput> - cc -o foo.o -c -DPACKAGE="True" foo.c - % <userinput>scons -Q PACKAGE=no foo.o</userinput> - cc -o foo.o -c -DPACKAGE="False" foo.c - </screen> + <scons_output example="commandline_PackageVariable" suffix="1"> + <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> @@ -1710,25 +1794,27 @@ </para> - <programlisting> - vars = Variables() - vars.AddVariables( - ('RELEASE', 'Set to 1 to build for release', 0), - ('CONFIG', 'Configuration file', '/etc/my_config'), - BoolVariable('warnings', 'compilation with -Wall and similiar', 1), - EnumVariable('debug', 'debug output and symbols', 'no', - allowed_values=('yes', 'no', 'full'), - map={}, ignorecase=0), # case sensitive - ListVariable('shared', - 'libraries to build as shared libraries', - 'all', - names = list_of_libs), - PackageVariable('x11', - 'use X11 installed here (yes = search some places)', - 'yes'), - PathVariable('qtdir', 'where the root of Qt is installed', qtdir), - ) - </programlisting> + <scons_example name="commandline_AddVariables_1"> + <file name="SConstruct" printme="1"> +vars = Variables() +vars.AddVariables( + ('RELEASE', 'Set to 1 to build for release', 0), + ('CONFIG', 'Configuration file', '/etc/my_config'), + BoolVariable('warnings', 'compilation with -Wall and similiar', 1), + EnumVariable('debug', 'debug output and symbols', 'no', + allowed_values=('yes', 'no', 'full'), + map={}, ignorecase=0), # case sensitive + ListVariable('shared', + 'libraries to build as shared libraries', + 'all', + names = list_of_libs), + PackageVariable('x11', + 'use X11 installed here (yes = search some places)', + 'yes'), + PathVariable('qtdir', 'where the root of Qt is installed', qtdir), +) + </file> + </scons_example> <para> </para> @@ -1769,17 +1855,22 @@ </para> - <programlisting> - vars = Variables(None) - vars.Add('RELEASE', 'Set to 1 to build for release', 0) - env = Environment(variables = vars, - CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) - unknown = vars.UnknownVariables() - if unknown: - print "Unknown variables:", unknown.keys() - Exit(1) - env.Program('foo.c') - </programlisting> + <scons_example name="commandline_UnknownVariables"> + <file name="SConstruct" printme="1"> +vars = Variables(None) +vars.Add('RELEASE', 'Set to 1 to build for release', 0) +env = Environment(variables = vars, + CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'}) +unknown = vars.UnknownVariables() +if unknown: + print "Unknown variables:", unknown.keys() + Exit(1) +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + </scons_example> <para> @@ -1800,10 +1891,9 @@ </para> - <screen> - % <userinput>scons -Q NOT_KNOWN=foo</userinput> - Unknown variables: ['NOT_KNOWN'] - </screen> + <scons_output example="commandline_UnknownVariables" suffix="1"> + <scons_output_command>scons -Q NOT_KNOWN=foo</scons_output_command> + </scons_output> <para> @@ -1852,12 +1942,20 @@ </para> - <programlisting> - if 'bar' in COMMAND_LINE_TARGETS: - print "Don't forget to copy `bar' to the archive!" - Default(Program('foo.c')) - Program('bar.c') - </programlisting> + <scons_example name="commandline_COMMAND_LINE_TARGETS"> + <file name="SConstruct" printme="1"> +if 'bar' in COMMAND_LINE_TARGETS: + print "Don't forget to copy `bar' to the archive!" +Default(Program('foo.c')) +Program('bar.c') + </file> + <file name="foo.c"> +foo.c + </file> + <file name="bar.c"> +foo.c + </file> + </scons_example> <para> @@ -1868,15 +1966,10 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o foo.o -c foo.c - cc -o foo foo.o - % <userinput>scons -Q bar</userinput> - Don't forget to copy `bar' to the archive! - cc -o bar.o -c bar.c - cc -o bar bar.o - </screen> + <scons_output example="commandline_COMMAND_LINE_TARGETS" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q bar</scons_output_command> + </scons_output> <para> @@ -1911,12 +2004,20 @@ </para> - <programlisting> - env = Environment() - hello = env.Program('hello.c') - env.Program('goodbye.c') - Default(hello) - </programlisting> + <scons_example name="commandline_Default1"> + <file name="SConstruct" printme="1"> +env = Environment() +hello = env.Program('hello.c') +env.Program('goodbye.c') +Default(hello) + </file> + <file name="hello.c"> +hello.c + </file> + <file name="goodbye.c"> +goodbye.c + </file> + </scons_example> <para> @@ -1927,16 +2028,11 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q</userinput> - scons: `hello' is up to date. - % <userinput>scons -Q goodbye</userinput> - cc -o goodbye.o -c goodbye.c - cc -o goodbye goodbye.o - </screen> + <scons_output example="commandline_Default1" suffix="1"> + <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> @@ -1949,13 +2045,9 @@ </para> - <screen> - % <userinput>scons -Q .</userinput> - cc -o goodbye.o -c goodbye.c - cc -o goodbye goodbye.o - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="commandline_Default1" suffix="2"> + <scons_output_command>scons -Q .</scons_output_command> + </scons_output> <para> @@ -1966,14 +2058,25 @@ </para> - <programlisting> - env = Environment() - prog1 = env.Program('prog1.c') - Default(prog1) - prog2 = env.Program('prog2.c') - prog3 = env.Program('prog3.c') - Default(prog3) - </programlisting> + <scons_example name="commandline_Default2"> + <file name="SConstruct" printme="1"> +env = Environment() +prog1 = env.Program('prog1.c') +Default(prog1) +prog2 = env.Program('prog2.c') +prog3 = env.Program('prog3.c') +Default(prog3) + </file> + <file name="prog1.c"> +prog1.c + </file> + <file name="prog2.c"> +prog2.c + </file> + <file name="prog3.c"> +prog3.c + </file> + </scons_example> <para> @@ -1983,11 +2086,11 @@ </para> <programlisting> - env = Environment() - prog1 = env.Program('prog1.c') - prog2 = env.Program('prog2.c') - prog3 = env.Program('prog3.c') - Default(prog1, prog3) +env = Environment() +prog1 = env.Program('prog1.c') +prog2 = env.Program('prog2.c') +prog3 = env.Program('prog3.c') +Default(prog1, prog3) </programlisting> <para> @@ -2001,16 +2104,10 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o prog1.o -c prog1.c - cc -o prog1 prog1.o - cc -o prog3.o -c prog3.c - cc -o prog3 prog3.o - % <userinput>scons -Q .</userinput> - cc -o prog2.o -c prog2.c - cc -o prog2 prog2.o - </screen> + <scons_output example="commandline_Default2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q .</scons_output_command> + </scons_output> <para> @@ -2019,12 +2116,28 @@ </para> - <programlisting> - env = Environment() - env.Program(['prog1/main.c', 'prog1/foo.c']) - env.Program(['prog2/main.c', 'prog2/bar.c']) - Default('prog1') - </programlisting> + <scons_example name="commandline_Default3"> + <file name="SConstruct" printme="1"> +env = Environment() +env.Program(['prog1/main.c', 'prog1/foo.c']) +env.Program(['prog2/main.c', 'prog2/bar.c']) +Default('prog1') + </file> + <directory name="prog1"></directory> + <directory name="prog2"></directory> + <file name="prog1/main.c"> +int main() { printf("prog1/main.c\n"); } + </file> + <file name="prog1/foo.c"> +int foo() { printf("prog1/foo.c\n"); } + </file> + <file name="prog2/main.c"> +int main() { printf("prog2/main.c\n"); } + </file> + <file name="prog2/bar.c"> +int bar() { printf("prog2/bar.c\n"); } + </file> + </scons_example> <para> @@ -2033,18 +2146,11 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o prog1/foo.o -c prog1/foo.c - cc -o prog1/main.o -c prog1/main.c - cc -o prog1/main prog1/main.o prog1/foo.o - % <userinput>scons -Q</userinput> - scons: `prog1' is up to date. - % <userinput>scons -Q .</userinput> - cc -o prog2/bar.o -c prog2/bar.c - cc -o prog2/main.o -c prog2/main.c - cc -o prog2/main prog2/main.o prog2/bar.o - </screen> + <scons_output example="commandline_Default3" suffix="1"> + <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> @@ -2055,12 +2161,20 @@ </para> - <programlisting> - env = Environment() - prog1 = env.Program('prog1.c') - prog2 = env.Program('prog2.c') - Default(None) - </programlisting> + <scons_example name="commandline_Default4"> + <file name="SConstruct" printme="1"> +env = Environment() +prog1 = env.Program('prog1.c') +prog2 = env.Program('prog2.c') +Default(None) + </file> + <file name="prog1.c"> +prog1.c + </file> + <file name="prog2.c"> +prog2.c + </file> + </scons_example> <para> @@ -2068,15 +2182,10 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - scons: *** No targets specified and no Default() targets found. Stop. - % <userinput>scons -Q .</userinput> - cc -o prog1.o -c prog1.c - cc -o prog1 prog1.o - cc -o prog2.o -c prog2.c - cc -o prog2 prog2.o - </screen> + <scons_output example="commandline_Default4" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q .</scons_output_command> + </scons_output> <section> <title>Fetching the List of Default Targets: the &DEFAULT_TARGETS; Variable</title> @@ -2097,11 +2206,16 @@ </para> - <programlisting> - prog1 = Program('prog1.c') - Default(prog1) - print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS) - </programlisting> + <scons_example name="commandline_DEFAULT_TARGETS_1"> + <file name="SConstruct" printme="1"> +prog1 = Program('prog1.c') +Default(prog1) +print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS) + </file> + <file name="prog1.c"> +prog1.c + </file> + </scons_example> <para> @@ -2113,16 +2227,9 @@ </para> - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - DEFAULT_TARGETS is ['prog1'] - scons: done reading SConscript files. - scons: Building targets ... - cc -o prog1.o -c prog1.c - cc -o prog1 prog1.o - scons: done building targets. - </screen> + <scons_output example="commandline_DEFAULT_TARGETS_1" suffix="1"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -2133,14 +2240,22 @@ </para> - <programlisting> - prog1 = Program('prog1.c') - Default(prog1) - print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS) - prog2 = Program('prog2.c') - Default(prog2) - print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS) - </programlisting> + <scons_example name="commandline_DEFAULT_TARGETS_2"> + <file name="SConstruct" printme="1"> +prog1 = Program('prog1.c') +Default(prog1) +print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS) +prog2 = Program('prog2.c') +Default(prog2) +print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS) + </file> + <file name="prog1.c"> +prog1.c + </file> + <file name="prog2.c"> +prog2.c + </file> + </scons_example> <para> @@ -2148,19 +2263,9 @@ </para> - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - DEFAULT_TARGETS is now ['prog1'] - DEFAULT_TARGETS is now ['prog1', 'prog2'] - scons: done reading SConscript files. - scons: Building targets ... - cc -o prog1.o -c prog1.c - cc -o prog1 prog1.o - cc -o prog2.o -c prog2.c - cc -o prog2 prog2.o - scons: done building targets. - </screen> + <scons_output example="commandline_DEFAULT_TARGETS_2" suffix="1"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -2198,12 +2303,12 @@ </para> - <programlisting> - if COMMAND_LINE_TARGETS: - targets = COMMAND_LINE_TARGETS - else: - targets = DEFAULT_TARGETS - </programlisting> + <sconstruct> +if COMMAND_LINE_TARGETS: + targets = COMMAND_LINE_TARGETS +else: + targets = DEFAULT_TARGETS + </sconstruct> <para> @@ -2228,12 +2333,20 @@ </para> - <programlisting> - prog1 = Program('prog1.c') - Program('prog2.c') - Default(prog1) - print "BUILD_TARGETS is", map(str, BUILD_TARGETS) - </programlisting> + <scons_example name="commandline_BUILD_TARGETS_1"> + <file name="SConstruct" printme="1"> +prog1 = Program('prog1.c') +Program('prog2.c') +Default(prog1) +print "BUILD_TARGETS is", map(str, BUILD_TARGETS) + </file> + <file name="prog1.c"> +prog1.c + </file> + <file name="prog2.c"> +prog2.c + </file> + </scons_example> <para> @@ -2243,23 +2356,14 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - BUILD_TARGETS is ['prog1'] - cc -o prog1.o -c prog1.c - cc -o prog1 prog1.o - % <userinput>scons -Q prog2</userinput> - BUILD_TARGETS is ['prog2'] - cc -o prog2.o -c prog2.c - cc -o prog2 prog2.o - % <userinput>scons -Q -c .</userinput> - BUILD_TARGETS is ['.'] - Removed prog1.o - Removed prog1 - Removed prog2.o - Removed prog2 - </screen> + <scons_output example="commandline_BUILD_TARGETS_1" suffix="1"> + <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> </section> + +</chapter> diff --git a/doc/user/copyright.in b/doc/user/copyright.in deleted file mode 100644 index d78221c..0000000 --- a/doc/user/copyright.in +++ /dev/null @@ -1,32 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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. - ---> - -<blockquote> - <para> - - SCons User's Guide Copyright (c) 2004, 2005, 2006, 2007 Steven Knight - - </para> -</blockquote> diff --git a/doc/user/copyright.xml b/doc/user/copyright.xml index d78221c..de8fac9 100644 --- a/doc/user/copyright.xml +++ b/doc/user/copyright.xml @@ -1,6 +1,16 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; +]> + +<legalnotice xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -30,3 +40,5 @@ </para> </blockquote> + +</legalnotice> diff --git a/doc/user/cover.jpg b/doc/user/cover.jpg Binary files differnew file mode 100644 index 0000000..e2c2cb3 --- /dev/null +++ b/doc/user/cover.jpg diff --git a/doc/user/depends.in b/doc/user/depends.in deleted file mode 100644 index de2e11c..0000000 --- a/doc/user/depends.in +++ /dev/null @@ -1,1872 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - So far we've seen how &SCons; handles one-time builds. - But one of the main functions of a build tool like &SCons; - is to rebuild only what is necessary - when source files change--or, put another way, - &SCons; should <emphasis>not</emphasis> - waste time rebuilding things that don't need to be rebuilt. - You can see this at work simply by re-invoking &SCons; - after building our simple &hello; example: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct"> - Program('hello.c') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <scons_output example="ex1" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - The second time it is executed, - &SCons; realizes that the &hello; program - is up-to-date with respect to the current &hello_c; source file, - and avoids rebuilding it. - You can see this more clearly by naming - the &hello; program explicitly on the command line: - - </para> - - <scons_output example="ex1" os="posix"> - <scons_output_command>scons -Q hello</scons_output_command> - <scons_output_command>scons -Q hello</scons_output_command> - </scons_output> - - <para> - - Note that &SCons; reports <literal>"...is up to date"</literal> - only for target files named explicitly on the command line, - to avoid cluttering the output. - - </para> - - <section> - <title>Deciding When an Input File Has Changed: the &Decider; Function</title> - - <para> - - Another aspect of avoiding unnecessary rebuilds - is the fundamental build tool behavior - of <emphasis>rebuilding</emphasis> - things when an input file changes, - so that the built software is up to date. - By default, - &SCons; keeps track of this through an - MD5 &signature;, or checksum, of the contents of each file, - although you can easily configure - &SCons; to use the - modification times (or time stamps) - instead. - You can even specify your own Python function - for deciding if an input file has changed. - - </para> - - <section> - <title>Using MD5 Signatures to Decide if a File Has Changed</title> - - <para> - - By default, - &SCons; keeps track of whether a file has changed - based on an MD5 checksum of the file's contents, - not the file's modification time. - This means that you may be surprised by the - default &SCons; behavior if you are used to the - &Make; convention of forcing - a rebuild by updating the file's modification time - (using the &touch; command, for example): - - </para> - - <scons_output example="ex1" os="posix"> - <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> - - Even though the file's modification time has changed, - &SCons; realizes that the contents of the - &hello_c; file have <emphasis>not</emphasis> changed, - and therefore that the &hello; program - need not be rebuilt. - This avoids unnecessary rebuilds when, - for example, someone rewrites the - contents of a file without making a change. - But if the contents of the file really do change, - then &SCons; detects the change - and rebuilds the program as required: - - </para> - - <scons_output example="ex1" os="posix"> - <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> - - Note that you can, if you wish, - specify this default behavior - (MD5 signatures) explicitly - using the &Decider; function as follows: - - </para> - - <sconstruct> - Program('hello.c') - Decider('MD5') - </sconstruct> - - <para> - - You can also use the string <literal>'content'</literal> - as a synonym for <literal>'MD5'</literal> - when calling the &Decider; function. - - </para> - - <section> - <title>Ramifications of Using MD5 Signatures</title> - - <para> - - Using MD5 signatures to decide if an input file has changed - has one surprising benefit: - if a source file has been changed - in such a way that the contents of the - rebuilt target file(s) - will be exactly the same as the last time - the file was built, - then any "downstream" target files - that depend on the rebuilt-but-not-changed target - file actually need not be rebuilt. - - </para> - - <para> - - So if, for example, - a user were to only change a comment in a &hello_c; file, - then the rebuilt &hello_o; file - would be exactly the same as the one previously built - (assuming the compiler doesn't put any build-specific - information in the object file). - &SCons; would then realize that it would not - need to rebuild the &hello; program as follows: - - </para> - - <scons_output example="ex1" os="posix"> - <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> - - In essence, &SCons; - "short-circuits" any dependent builds - when it realizes that a target file - has been rebuilt to exactly the same file as the last build. - This does take some extra processing time - to read the contents of the target (&hello_o;) file, - but often saves time when the rebuild that was avoided - would have been time-consuming and expensive. - - </para> - - </section> - - </section> - - <section> - <title>Using Time Stamps to Decide If a File Has Changed</title> - - <para> - - If you prefer, you can - configure &SCons; to use the modification time - of a file, not the file contents, - when deciding if a target needs to be rebuilt. - &SCons; gives you two ways to use time stamps - to decide if an input file has changed - since the last time a target has been built. - - </para> - - <para> - - The most familiar way to use time stamps - is the way &Make; does: - that is, have &SCons; decide - that a target must be rebuilt - if a source file's modification time is - <emphasis>newer</emphasis> - than the target file. - To do this, call the &Decider; - function as follows: - - </para> - - <scons_example name="newer"> - <file name="SConstruct" printme="1"> - Object('hello.c') - Decider('timestamp-newer') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - This makes &SCons; act like &Make; - when a file's modification time is updated - (using the &touch; command, for example): - - </para> - - <scons_output example="newer" os="posix"> - <scons_output_command>scons -Q hello.o</scons_output_command> - <scons_output_command>touch hello.c</scons_output_command> - <scons_output_command>scons -Q hello.o</scons_output_command> - </scons_output> - - <para> - - And, in fact, because this behavior is the same - as the behavior of &Make;, - you can also use the string <literal>'make'</literal> - as a synonym for <literal>'timestamp-newer'</literal> - when calling the &Decider; function: - - </para> - - <sconstruct> - Object('hello.c') - Decider('make') - </sconstruct> - - <para> - - One drawback to using times stamps exactly like &Make; - is that if an input file's modification time suddenly - becomes <emphasis>older</emphasis> than a target file, - the target file will not be rebuilt. - This can happen if an old copy of a source file is restored - from a backup archive, for example. - The contents of the restored file will likely be different - than they were the last time a dependent target was built, - but the target won't be rebuilt - because the modification time of the source file - is not newer than the target. - - </para> - - <para> - - Because &SCons; actually stores information - about the source files' time stamps whenever a target is built, - it can handle this situation by checking for - an exact match of the source file time stamp, - instead of just whether or not the source file - is newer than the target file. - To do this, specify the argument - <literal>'timestamp-match'</literal> - when calling the &Decider; function: - - </para> - - <scons_example name="match"> - <file name="SConstruct" printme="1"> - Object('hello.c') - Decider('timestamp-match') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - When configured this way, - &SCons; will rebuild a target whenever - a source file's modification time has changed. - So if we use the <literal>touch -t</literal> - option to change the modification time of - &hello_c; to an old date (January 1, 1989), - &SCons; will still rebuild the target file: - - </para> - - <scons_output example="match" os="posix"> - <scons_output_command>scons -Q hello.o</scons_output_command> - <scons_output_command>touch -t 198901010000 hello.c</scons_output_command> - <scons_output_command>scons -Q hello.o</scons_output_command> - </scons_output> - - <para> - - In general, the only reason to prefer - <literal>timestamp-newer</literal> - instead of - <literal>timestamp-match</literal>, - would be if you have some specific reason - to require this &Make;-like behavior of - not rebuilding a target when an otherwise-modified - source file is older. - - </para> - - </section> - - <section> - <title>Deciding If a File Has Changed Using Both MD Signatures and Time Stamps</title> - - <para> - - As a performance enhancement, - &SCons; provides a way to use - MD5 checksums of file contents - but to read those contents - only when the file's timestamp has changed. - To do this, call the &Decider; - function with <literal>'MD5-timestamp'</literal> - argument as follows: - - </para> - - <scons_example name="MD5-timestamp"> - <file name="SConstruct" printme="1"> - Program('hello.c') - Decider('MD5-timestamp') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - So configured, &SCons; will still behave like - it does when using <literal>Decider('MD5')</literal>: - - </para> - - <!-- - - We want to generate the output as follows, - but our "surrogate" system for generating the - output seems to get this wrong. - Just in-line the output for now. - - <scons_output example="MD5-timestamp" os="posix"> - <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_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> - - --> - - <screen> - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>touch hello.c</userinput> - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - % <userinput>edit hello.c</userinput> - [CHANGE THE CONTENTS OF hello.c] - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> - - <para> - - However, the second call to &SCons; in the above output, - when the build is up-to-date, - will have been performed by simply looking at the - modification time of the &hello_c; file, - not by opening it and performing - an MD5 checksum calcuation on its contents. - This can significantly speed up many up-to-date builds. - - </para> - - <para> - - The only drawback to using - <literal>Decider('MD5-timestamp')</literal> - is that &SCons; will <emphasis>not</emphasis> - rebuild a target file if a source file was modified - within one second of the last time &SCons; built the file. - While most developers are programming, - this isn't a problem in practice, - since it's unlikely that someone will have built - and then thought quickly enough to make a substantive - change to a source file within one second. - Certain build scripts or - continuous integration tools may, however, - rely on the ability to apply changes to files - automatically and then rebuild as quickly as possible, - in which case use of - <literal>Decider('MD5-timestamp')</literal> - may not be appropriate. - - </para> - - </section> - - <section> - <title>Writing Your Own Custom &Decider; Function</title> - - <para> - - The different string values that we've passed to - the &Decider; function are essentially used by &SCons; - to pick one of several specific internal functions - that implement various ways of deciding if a dependency - (usually a source file) - has changed since a target file has been built. - As it turns out, - you can also supply your own function - to decide if a dependency has changed. - - </para> - - <para> - - For example, suppose we have an input file - that contains a lot of data, - in some specific regular format, - that is used to rebuild a lot of different target files, - but each target file really only depends on - one particular section of the input file. - We'd like to have each target file depend on - only its section of the input file. - However, since the input file may contain a lot of data, - we want to open the input file only if its timestamp has changed. - This could be done with a custom - &Decider; function that might look something like this: - - </para> - - <scons_example name="function"> - <file name="SConstruct" printme="1"> - Program('hello.c') - def decide_if_changed(dependency, target, prev_ni): - if self.get_timestamp() != prev_ni.timestamp: - dep = str(dependency) - tgt = str(target) - if specific_part_of_file_has_changed(dep, tgt): - return True - return False - Decider(decide_if_changed) - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Note that in the function definition, - the <varname>dependency</varname> - (input file) is the first argument, - and then the ⌖. - Both of these are passed to the functions as - SCons &Node; objects, - which we convert to strings using the Python - <function>str()</function>. - - </para> - - <para> - - The third argument, <varname>prev_ni</varname>, - is an object that holds the - signature or timestamp information - that was recorded about the dependency - the last time the target was built. - A <varname>prev_ni</varname> object can hold - different information, - depending on the type of thing that the - <varname>dependency</varname> argument represents. - For normal files, - the <varname>prev_ni</varname> object - has the following attributes: - - </para> - - <variablelist> - - <varlistentry> - <term>.csig</term> - - <listitem> - <para> - The <emphasis>content signature</emphasis>, - or MD5 checksum, of the contents of the - <varname>dependency</varname> - file the list time the ⌖ was built. - </para> - </listitem> - - </varlistentry> - - <varlistentry> - <term>.size</term> - - <listitem> - <para> - The size in bytes of the <varname>dependency</varname> - file the list time the target was built. - </para> - </listitem> - - </varlistentry> - - <varlistentry> - <term>.timestamp</term> - - <listitem> - <para> - The modification time of the <varname>dependency</varname> - file the list time the ⌖ was built. - </para> - </listitem> - - </varlistentry> - - </variablelist> - - <para> - - Note that ignoring some of the arguments - in your custom &Decider; function - is a perfectly normal thing to do, - if they don't impact the way you want to - decide if the dependency file has changed. - - </para> - - <para> - - Another thing to look out for is the fact that the three - attributes above may not be present at the time of the first run. - Without any prior build, no targets have been created and no - <filename>.sconsign</filename> DB file exists yet. - So, you should always check whether the - <varname>prev_ni</varname> attribute in question is available. - - </para> - - <para> - - We finally present a small example for a - <varname>csig</varname>-based decider function. Note how the - signature information for the <varname>dependency</varname> file - has to get initialized via <function>get_csig</function> - during each function call (this is mandatory!). - - </para> - - <sconstruct> - env = Environment() - - def config_file_decider(dependency, target, prev_ni): - import os.path - - # We always have to init the .csig value... - dep_csig = dependency.get_csig() - # .csig may not exist, because no target was built yet... - if 'csig' not in dir(prev_ni): - return True - # Target file may not exist yet - if not os.path.exists(str(target.abspath)): - return True - if dep_csig != prev_ni.csig: - # Some change on source file => update installed one - return True - return False - - def update_file(): - f = open("test.txt","a") - f.write("some line\n") - f.close() - - update_file() - - # Activate our own decider function - env.Decider(config_file_decider) - - env.Install("install","test.txt") - </sconstruct> - - </section> - - <section> - <title>Mixing Different Ways of Deciding If a File Has Changed</title> - - <para> - - The previous examples have all demonstrated calling - the global &Decider; function - to configure all dependency decisions that &SCons; makes. - Sometimes, however, you want to be able to configure - different decision-making for different targets. - When that's necessary, you can use the - <function>env.Decider</function> - method to affect only the configuration - decisions for targets built with a - specific construction environment. - - </para> - - <para> - - For example, if we arbitrarily want to build - one program using MD5 checkums - and another using file modification times - from the same source - we might configure it this way: - - </para> - - <scons_example name="mixing"> - <file name="SConstruct" printme="1"> - env1 = Environment(CPPPATH = ['.']) - env2 = env1.Clone() - env2.Decider('timestamp-match') - env1.Program('prog-MD5', 'program1.c') - env2.Program('prog-timestamp', 'program2.c') - </file> - <file name="program1.c"> - #include "inc.h" - int main() { printf("Hello, world!\n"); } - </file> - <file name="program2.c"> - #include "inc.h" - int main() { printf("Hello, world!\n"); } - </file> - <file name="inc.h"> - #define INC 1 - </file> - </scons_example> - - <para> - - If both of the programs include the same - <filename>inc.h</filename> file, - then updating the modification time of - <filename>inc.h</filename> - (using the &touch; command) - will cause only <filename>prog-timestamp</filename> - to be rebuilt: - - </para> - - <scons_output example="mixing" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>touch inc.h</scons_output_command> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - </section> - - <section> - <title>Older Functions for Deciding When an Input File Has Changed</title> - - <para> - - &SCons; still supports two functions that used to be the - primary methods for configuring the - decision about whether or not an input file has changed. - These functions have been officially deprecated - as &SCons; version 2.0, - and their use is discouraged, - mainly because they rely on a somewhat - confusing distinction between how - source files and target files are handled. - These functions are documented here mainly in case you - encounter them in older &SConscript; files. - - </para> - - <section> - <title>The &SourceSignatures; Function</title> - - <para> - - The &SourceSignatures; function is fairly straightforward, - and supports two different argument values - to configure whether source file changes should be decided - using MD5 signatures: - - </para> - - <sconstruct> - Program('hello.c') - SourceSignatures('MD5') - </sconstruct> - - <para> - - Or using time stamps: - - </para> - - <sconstruct> - Program('hello.c') - SourceSignatures('timestamp') - </sconstruct> - - <para> - - These are roughly equivalent to specifying - <function>Decider('MD5')</function> - or - <function>Decider('timestamp-match')</function>, - respectively, - although it only affects how SCons makes - decisions about dependencies on - <emphasis>source</emphasis> files--that is, - files that are not built from any other files. - - </para> - - </section> - - <section> - <title>The &TargetSignatures; Function</title> - - <para> - - The &TargetSignatures; function - specifies how &SCons; decides - when a target file has changed - <emphasis>when it is used as a - dependency of (input to) another target</emphasis>--that is, - the &TargetSignatures; function configures - how the signatures of "intermediate" target files - are used when deciding if a "downstream" target file - must be rebuilt. - <footnote><para> - This easily-overlooked distinction between - how &SCons; decides if the target itself must be rebuilt - and how the target is then used to decide if a different - target must be rebuilt is one of the confusing - things that has led to the &TargetSignatures; - and &SourceSignatures; functions being - replaced by the simpler &Decider; function. - </para></footnote> - - </para> - - <para> - - The &TargetSignatures; function supports the same - <literal>'MD5'</literal> and <literal>'timestamp'</literal> - argument values that are supported by the &SourceSignatures;, - with the same meanings, but applied to target files. - That is, in the example: - - </para> - - <sconstruct> - Program('hello.c') - TargetSignatures('MD5') - </sconstruct> - - <para> - - The MD5 checksum of the &hello_o; target file - will be used to decide if it has changed since the last - time the "downstream" &hello; target file was built. - And in the example: - - </para> - - <sconstruct> - Program('hello.c') - TargetSignatures('timestamp') - </sconstruct> - - <para> - - The modification time of the &hello_o; target file - will be used to decide if it has changed since the last - time the "downstream" &hello; target file was built. - - </para> - - <para> - - The &TargetSignatures; function supports - two additional argument values: - <literal>'source'</literal> and <literal>'build'</literal>. - The <literal>'source'</literal> argument - specifies that decisions involving - whether target files have changed - since a previous build - should use the same behavior - for the decisions configured for source files - (using the &SourceSignatures; function). - So in the example: - - </para> - - <sconstruct> - Program('hello.c') - TargetSignatures('source') - SourceSignatures('timestamp') - </sconstruct> - - <para> - - All files, both targets and sources, - will use modification times - when deciding if an input file - has changed since the last - time a target was built. - - </para> - - <para> - - Lastly, the <literal>'build'</literal> argument - specifies that &SCons; should examine - the build status of a target file - and always rebuild a "downstream" target - if the target file was itself rebuilt, - without re-examining the contents or timestamp - of the newly-built target file. - If the target file was not rebuilt during - this &scons; invocation, - then the target file will be examined - the same way as configured by - the &SourceSignature; call - to decide if it has changed. - - </para> - - <para> - - This mimics the behavior of - <literal>build signatures</literal> - in earlier versions of &SCons;. - A &buildsignature; re-combined - signatures of all the input files - that went into making the target file, - so that the target file itself - did not need to have its contents read - to compute an MD5 signature. - This can improve performance for some configurations, - but is generally not as effective as using - <literal>Decider('MD5-timestamp')</literal>. - - </para> - - </section> - - </section> - - <section> - <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> - - <para> - - Now suppose that our "Hello, World!" program - actually has an <literal>#include</literal> line - to include the &hello_h; file in the compilation: - - </para> - - <scons_example name="include"> - <file name="SConstruct"> - Program('hello.c', CPPPATH = '.') - </file> - <file name="hello.c" printme="1"> - #include <hello.h> - int - main() - { - printf("Hello, %s!\n", string); - } - </file> - <file name="hello.h"> - #define string "world" - </file> - </scons_example> - - <para> - - And, for completeness, the &hello_h; file looks like this: - - </para> - - <scons_example_file example="include" name="hello.h"> - </scons_example_file> - - <para> - - In this case, we want &SCons; to recognize that, - if the contents of the &hello_h; file change, - the &hello; program must be recompiled. - To do this, we need to modify the - &SConstruct; file like so: - - </para> - - <scons_example_file example="include" name="SConstruct"> - </scons_example_file> - - <para> - - The &cv-link-CPPPATH; value - tells &SCons; to look in the current directory - (<literal>'.'</literal>) - for any files included by C source files - (<filename>.c</filename> or <filename>.h</filename> files). - With this assignment in the &SConstruct; file: - - </para> - - <scons_output example="include" os="posix"> - <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 &cv-CPPPATH; variable - so that the compilation would find the - &hello_h; file in the local directory. - - </para> - - <para> - - Second, realize that &SCons; knows that the &hello; - program must be rebuilt - because it scans the contents of - the &hello_c; file - for the <literal>#include</literal> lines that indicate - another file is being included in the compilation. - &SCons; records these as - <emphasis>implicit dependencies</emphasis> - of the target file, - Consequently, - when the &hello_h; file changes, - &SCons; realizes that the &hello_c; file includes it, - and rebuilds the resulting &hello; program - that depends on both the &hello_c; and &hello_h; files. - - </para> - - <para> - - Like the &cv-link-LIBPATH; variable, - the &cv-CPPPATH; variable - may be a list of directories, - or a string separated by - the system-specific path separation character - (':' on POSIX/Linux, ';' on Windows). - Either way, &SCons; creates the - right command-line options - so that the following example: - - </para> - - <scons_example name="ex5"> - <file name="SConstruct" printme="1"> - Program('hello.c', CPPPATH = ['include', '/home/project/inc']) - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Will look like this on POSIX or Linux: - - </para> - - <scons_output example="ex5" os="posix"> - <scons_output_command>scons -Q hello</scons_output_command> - </scons_output> - - <para> - - And like this on Windows: - - </para> - - <scons_output example="ex5" os="win32"> - <scons_output_command>scons -Q hello.exe</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Caching Implicit Dependencies</title> - - <para> - - Scanning each file for <literal>#include</literal> lines - does take some extra processing time. - When you're doing a full build of a large system, - the scanning time is usually a very small percentage - of the overall time spent on the build. - You're most likely to notice the scanning time, - however, when you <emphasis>rebuild</emphasis> - all or part of a large system: - &SCons; will likely take some extra time to "think about" - what must be built before it issues the - first build command - (or decides that everything is up to date - and nothing must be rebuilt). - - <!-- - Isn't this expensive? The answer is, it depends. If you do a full build of a - large system, the scanning time is insignificant. If you do a rebuild of a - large system, then Cons will spend a fair amount of time thinking about it - before it decides that nothing has to be done (although not necessarily more - time than make!). The good news is that Cons makes it very easy to - intelligently subset your build, when you are working on localized changes. - --> - - </para> - - <para> - - In practice, having &SCons; scan files saves time - relative to the amount of potential time - lost to tracking down subtle problems - introduced by incorrect dependencies. - Nevertheless, the "waiting time" - while &SCons; scans files can annoy - individual developers waiting for their builds to finish. - Consequently, &SCons; lets you cache - the implicit dependencies - that its scanners find, - for use by later builds. - You can do this by specifying the - &implicit-cache; option on the command line: - - </para> - - <scons_output example="ex1"> - <scons_output_command>scons -Q --implicit-cache hello</scons_output_command> - <scons_output_command>scons -Q hello</scons_output_command> - </scons_output> - - <para> - - If you don't want to specify &implicit-cache; - on the command line each time, - you can make it the default behavior for your build - by setting the &implicit_cache; option - in an &SConscript; file: - - </para> - - <sconstruct> - SetOption('implicit_cache', 1) - </sconstruct> - - <para> - - &SCons; does not cache implicit dependencies like this by default - because the &implicit-cache; causes &SCons; to simply use the implicit - dependencies stored during the last run, without any checking - for whether or not those dependencies are still correct. - Specifically, this means &implicit-cache; instructs &SCons; - to <emphasis>not</emphasis> rebuild "correctly" in the - following cases: - - - </para> - - <itemizedlist> - - <listitem> - <para> - - When &implicit-cache; is used, &SCons; will ignore any changes that - may have been made to search paths - (like &cv-CPPPATH; or &cv-LIBPATH;,). - This can lead to &SCons; not rebuilding a file if a change to - &cv-CPPPATH; would normally cause a different, same-named file from - a different directory to be used. - - </para> - </listitem> - - <listitem> - <para> - - When &implicit-cache; is used, &SCons; will not detect if a - same-named file has been added to a directory that is earlier in - the search path than the directory in which the file was found - last time. - - </para> - </listitem> - - </itemizedlist> - - <section> - <title>The &implicit-deps-changed; Option</title> - - <para> - - When using cached implicit dependencies, - sometimes you want to "start fresh" - and have &SCons; re-scan the files - for which it previously cached the dependencies. - For example, - if you have recently installed a new version of - external code that you use for compilation, - the external header files will have changed - and the previously-cached implicit dependencies - will be out of date. - You can update them by - running &SCons; with the &implicit-deps-changed; option: - - </para> - - <scons_output example="ex1"> - <scons_output_command>scons -Q --implicit-deps-changed hello</scons_output_command> - <scons_output_command>scons -Q hello</scons_output_command> - </scons_output> - - <para> - - In this case, &SCons; will re-scan all of the implicit dependencies - and cache updated copies of the information. - - </para> - - </section> - - <section> - <title>The &implicit-deps-unchanged; Option</title> - - <para> - - By default when caching dependencies, - &SCons; notices when a file has been modified - and re-scans the file for any updated - implicit dependency information. - Sometimes, however, you may want - to force &SCons; to use the cached implicit dependencies, - even if the source files changed. - This can speed up a build for example, - when you have changed your source files - but know that you haven't changed - any <literal>#include</literal> lines. - In this case, - you can use the &implicit-deps-unchanged; option: - - </para> - - <scons_output example="ex1"> - <scons_output_command>scons -Q --implicit-deps-unchanged hello</scons_output_command> - <scons_output_command>scons -Q hello</scons_output_command> - </scons_output> - - <para> - - In this case, - &SCons; will assume that the cached implicit - dependencies are correct and - will not bother to re-scan changed files. - For typical builds after small, - incremental changes to source files, - the savings may not be very big, - but sometimes every bit of - improved performance counts. - - </para> - - </section> - - <!-- - - <section> - <title>XXX max drift</title> - - XXX SetOption('max_drift') - - </section> - - --> - - </section> - - <section> - <title>Explicit Dependencies: the &Depends; Function</title> - - <para> - - Sometimes a file depends on another file - that is not detected by an &SCons; scanner. - For this situation, - &SCons; allows you to specific explicitly that one file - depends on another file, - and must be rebuilt whenever that file changes. - This is specified using the &Depends; method: - - </para> - - <programlisting> - hello = Program('hello.c') - Depends(hello, 'other_file') - </programlisting> - - <!-- XXX mention that you can use arrays for target and source? --> - - <screen> - % <userinput>scons -Q hello</userinput> - cc -c hello.c -o hello.o - cc -o hello hello.o - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - % <userinput>edit other_file</userinput> - [CHANGE THE CONTENTS OF other_file] - % <userinput>scons -Q hello</userinput> - cc -c hello.c -o hello.o - cc -o hello hello.o - </screen> - - <para> - - Note that the dependency - (the second argument to &Depends;) - may also be a list of Node objects - (for example, as returned by a call to a Builder): - - </para> - - <programlisting> - hello = Program('hello.c') - goodbye = Program('goodbye.c') - Depends(hello, goodbye) - </programlisting> - - <para> - - in which case the dependency or dependencies - will be built before the target(s): - - </para> - - <screen> - % <userinput>scons -Q hello</userinput> - cc -c goodbye.c -o goodbye.o - cc -o goodbye goodbye.o - cc -c hello.c -o hello.o - cc -o hello hello.o - </screen> - - </section> - - <section> - <title>Dependencies From External Files: the &ParseDepends; - Function</title> - - <para> - - &SCons; has built-in scanners for a number of languages. Sometimes - these scanners fail to extract certain implicit dependencies due - to limitations of the scanner implementation. - - </para> - - <para> - - The following example illustrates a case where the built-in C - scanner is unable to extract the implicit dependency on a header - file. - - </para> - - <scons_example name="macroinc"> - <file name="hello.c" printme="1"> - #define FOO_HEADER <foo.h> - #include FOO_HEADER - - int main() { - return FOO; - } - </file> - <file name="SConstruct"> - Program('hello', 'hello.c', CPPPATH='.') - </file> - <file name="foo.h"> - #define FOO 42 - </file> - </scons_example> - - <scons_output example="macroinc" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command output=" [CHANGE CONTENTS OF foo.h]" - >edit foo.h</scons_output_command> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Apparently, the scanner does not know about the header dependency. - Being not a full-fledged C preprocessor, the scanner does not - expand the macro. - - </para> - - <para> - - In these cases, you may also use the compiler to extract the - implicit dependencies. &ParseDepends; can parse the contents of - the compiler output in the style of &Make;, and explicitly - establish all of the listed dependencies. - - </para> - - <para> - - The following example uses &ParseDepends; to process a compiler - generated dependency file which is generated as a side effect - during compilation of the object file: - - </para> - - <!-- XXX The ParseDepends example below fakes proper working by a - priori specification of the dependency file. The produced hello.d - file is not found (or used) for unknown reasons. --> - - <scons_example name="parsedep"> - <file name="hello.c"> - #define FOO_HEADER <foo.h> - #include FOO_HEADER - - int main() { - return FOO; - } - </file> - <file name="SConstruct" printme="1"> - obj = Object('hello.c', CCFLAGS='-MD -MF hello.d', CPPPATH='.') - SideEffect('hello.d', obj) - ParseDepends('hello.d') - Program('hello', obj) - </file> - <file name="foo.h"> - #define FOO 42 - </file> - <file name="hello.d"> - hello.o: hello.c foo.h - </file> - </scons_example> - - <scons_output example="parsedep" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command output=" [CHANGE CONTENTS OF foo.h]" - >edit foo.h</scons_output_command> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Parsing dependencies from a compiler-generated - <filename>.d</filename> file has a chicken-and-egg problem, that - causes unnecessary rebuilds: - - </para> - - <scons_example name="parsedeprebuild"> - <file name="hello.c"> - #define FOO_HEADER <foo.h> - #include FOO_HEADER - - int main() { - return FOO; - } - </file> - <file name="SConstruct"> - obj = Object('hello.c', CCFLAGS='-MD -MF hello.d', CPPPATH='.') - SideEffect('hello.d', obj) - ParseDepends('hello.d') - Program('hello', obj) - </file> - <file name="foo.h"> - #define FOO 42 - </file> - </scons_example> - - <!-- - <scons_output example="parsedeprebuild" os="posix"> - <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> - --> - - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c -MD -MF hello.d -I. hello.c - cc -o hello hello.o - % <userinput>scons -Q --debug=explain</userinput> - scons: rebuilding `hello.o' because `foo.h' is a new dependency - cc -o hello.o -c -MD -MF hello.d -I. hello.c - % <userinput>scons -Q</userinput> - scons: `.' is up to date. - </screen> - - <para> - - In the first pass, the dependency file is generated while the - object file is compiled. At that time, &SCons; does not know about - the dependency on <filename>foo.h</filename>. In the second pass, - the object file is regenerated because <filename>foo.h</filename> - is detected as a new dependency. - - </para> - - <para> - - &ParseDepends; immediately reads the specified file at invocation - time and just returns if the file does not exist. A dependency - file generated during the build process is not automatically - parsed again. Hence, the compiler-extracted dependencies are not - stored in the signature database during the same build pass. This - limitation of &ParseDepends; leads to unnecessary recompilations. - Therefore, &ParseDepends; should only be used if scanners are not - available for the employed language or not powerful enough for the - specific task. - - </para> - - </section> - - <section> - <title>Ignoring Dependencies: the &Ignore; Function</title> - - <para> - - Sometimes it makes sense - to not rebuild a program, - even if a dependency file changes. - In this case, - you would tell &SCons; specifically - to ignore a dependency as follows: - - </para> - - <scons_example name="ignore"> - <file name="SConstruct" printme="1"> - hello_obj=Object('hello.c') - hello = Program(hello_obj) - Ignore(hello_obj, 'hello.h') - </file> - <file name="hello.c"> - #include "hello.h" - int main() { printf("Hello, %s!\n", string); } - </file> - <file name="hello.h"> - #define string "world" - </file> - </scons_example> - - <!-- XXX mention that you can use lists for target and source? --> - - <!-- - <scons_output example="ignore"> - <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> - --> - - <screen> - % <userinput>scons -Q hello</userinput> - cc -c -o hello.o hello.c - cc -o hello hello.o - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - % <userinput>edit hello.h</userinput> - [CHANGE THE CONTENTS OF hello.h] - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - </screen> - - <para> - - Now, the above example is a little contrived, - because it's hard to imagine a real-world situation - where you wouldn't want to rebuild &hello; - if the &hello_h; file changed. - A more realistic example - might be if the &hello; - program is being built in a - directory that is shared between multiple systems - that have different copies of the - &stdio_h; include file. - In that case, - &SCons; would notice the differences between - the different systems' copies of &stdio_h; - and would rebuild &hello; - each time you change systems. - You could avoid these rebuilds as follows: - - </para> - - <programlisting> - hello = Program('hello.c', CPPPATH=['/usr/include']) - Ignore(hello, '/usr/include/stdio.h') - </programlisting> - - <para> - &Ignore; can also be used to prevent a generated file from being built - by default. This is due to the fact that directories depend on - their contents. So to ignore a generated file from the default build, - you specify that the directory should ignore the generated file. - Note that the file will still be built if the user specifically - requests the target on scons command line, or if the file is - a dependency of another file which is requested and/or is built - by default. - </para> - - <scons_example name="ignore_explicit"> - <file name="SConstruct" printme="1"> - hello_obj=Object('hello.c') - hello = Program(hello_obj) - Ignore('.',[hello,hello_obj]) - </file> - <file name="hello.c"> - #include "stdio.h" - int main() { printf("Hello!\n"); } - </file> - </scons_example> - - <scons_output example="ignore_explicit" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q hello</scons_output_command> - <scons_output_command>scons -Q hello</scons_output_command> - </scons_output> - </section> - - <section> - <title>Order-Only Dependencies: the &Requires; Function</title> - - <para> - - Occasionally, - it may be useful to specify that a certain - file or directory must, if necessary, - be built or created before some other target is built, - but that changes to that file or directory - do <emphasis>not</emphasis> - require that the target itself be rebuilt. - Such a relationship is called an - <emphasis>order-only dependency</emphasis> - because it only affects the order in which - things must be built--the dependency before the target--but - it is not a strict dependency relationship - because the target should not - change in response to changes in the dependent file. - - </para> - - <para> - - For example, suppose that you want to create a file - every time you run a build - that identifies the time the build was performed, - the version number, etc., - and which is included in every program that you build. - The version file's contents will change every build. - If you specify a normal dependency relationship, - then every program that depends on - that file would be rebuilt every time you ran &SCons;. - For example, we could use some Python code in - a &SConstruct; file to create a new <filename>version.c</filename> file - with a string containing the current date every time - we run &SCons;, - and then link a program with the resulting object file - by listing <filename>version.c</filename> in the sources: - - </para> - - <scons_example name="no-Requires"> - <file name="SConstruct" printme="1"> - import time - - version_c_text = """ - char *date = "%s"; - """ % time.ctime(time.time()) - open('version.c', 'w').write(version_c_text) - - hello = Program(['hello.c', 'version.c']) - </file> - <file name="hello.c"> - extern char *date; - int main() { printf("Hello, %s! I was built: %s\n", date); } - </file> - </scons_example> - - <para> - - If we list <filename>version.c</filename> as an actual source file, - though, then the <filename>version.o</filename> file - will get rebuilt every time we run &SCons; - (because the &SConstruct; file itself changes - the contents of <filename>version.c</filename>) - and the <filename>hello</filename> executable - will get re-linked every time - (because the <filename>version.o</filename> file changes): - - </para> - - <scons_output example="no-Requires"> - <scons_output_command>scons -Q hello</scons_output_command> - <scons_output_command>sleep 1</scons_output_command> - <scons_output_command>scons -Q hello</scons_output_command> - <scons_output_command>sleep 1</scons_output_command> - <scons_output_command>scons -Q hello</scons_output_command> - </scons_output> - - <para> - - (Note that for the above example to work, - we &sleep; for one second in between each run, - so that the &SConstruct; file will create a - <filename>version.c</filename> file with a time string - that's one second later than the previous run.) - - </para> - - <para> - - One solution is to use the &Requires; function - to specify that the <filename>version.o</filename> - must be rebuilt before it is used by the link step, - but that changes to <filename>version.o</filename> - should not actually cause the <filename>hello</filename> - executable to be re-linked: - - </para> - - <scons_example name="Requires"> - <file name="SConstruct" printme="1"> - import time - - version_c_text = """ - char *date = "%s"; - """ % time.ctime(time.time()) - open('version.c', 'w').write(version_c_text) - - version_obj = Object('version.c') - - hello = Program('hello.c', - LINKFLAGS = str(version_obj[0])) - - Requires(hello, version_obj) - </file> - <file name="hello.c"> - extern char *date; - int main() { printf("Hello, %s! I was built: %s\n", date); } - </file> - </scons_example> - - <para> - - Notice that because we can no longer list <filename>version.c</filename> - as one of the sources for the <filename>hello</filename> program, - we have to find some other way to get it into the link command line. - For this example, we're cheating a bit and stuffing the - object file name (extracted from <literal>version_obj</literal> - list returned by the &b-Object; call) - into the &cv-link-LINKFLAGS; variable, - because &cv-LINKFLAGS; is already included - in the &cv-link-LINKCOM; command line. - - </para> - - <para> - - With these changes, - we get the desired behavior of only - re-linking the <filename>hello</filename> executable - when the <filename>hello.c</filename> has changed, - even though the <filename>version.o</filename> is rebuilt - (because the &SConstruct; file still changes the - <filename>version.c</filename> contents directly each run): - - </para> - - <scons_output example="Requires"> - <scons_output_command>scons -Q hello</scons_output_command> - <scons_output_command>sleep 1</scons_output_command> - <scons_output_command>scons -Q hello</scons_output_command> - <scons_output_command>sleep 1</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_command>sleep 1</scons_output_command> - <scons_output_command>scons -Q hello</scons_output_command> - </scons_output> - - </section> - - <section> - <title>The &AlwaysBuild; Function</title> - - <para> - - How &SCons; handles dependencies can also be affected - by the &AlwaysBuild; method. - When a file is passed to the &AlwaysBuild; method, - like so: - - </para> - - <scons_example name="AlwaysBuild"> - <file name="SConstruct" printme="1"> - hello = Program('hello.c') - AlwaysBuild(hello) - </file> - <file name="hello.c"> - int main() { printf("Hello, %s!\n", string); } - </file> - </scons_example> - - <para> - - Then the specified target file (&hello; in our example) - will always be considered out-of-date and - rebuilt whenever that target file is evaluated - while walking the dependency graph: - - </para> - - <scons_output example="AlwaysBuild"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - The &AlwaysBuild; function has a somewhat misleading name, - because it does not actually mean the target file will - be rebuilt every single time &SCons; is invoked. - Instead, it means that the target will, in fact, - be rebuilt whenever the target file is encountered - while evaluating the targets specified on - the command line (and their dependencies). - So specifying some other target on the command line, - a target that does <emphasis>not</emphasis> - itself depend on the &AlwaysBuild; target, - will still be rebuilt only if it's out-of-date - with respect to its dependencies: - - </para> - - <scons_output example="AlwaysBuild"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q hello.o</scons_output_command> - </scons_output> - - <!-- - - XXX AlwaysBuild() and Alias Nodes - - XXX AlwaysBuild() and Dir Nodes - - XXX AlwaysBuild() with no sources - - --> - - </section> - - <!-- - - <section> - <title>The &Salt; Method</title> - - <para> - - XXX Salt() (are we going to implement this ?) - - original Cons classic POD documentation: - -=head2 The C<Salt> method - -The C<Salt> method adds a constant value to the signature calculation -for every derived file. It is invoked as follows: - - Salt $string; - -Changing the Salt value will force a complete rebuild of every derived -file. This can be used to force rebuilds in certain desired -circumstances. For example, - - Salt `uname -s`; - -Would force a complete rebuild of every derived file whenever the -operating system on which the build is performed (as reported by C<uname --s>) changes. - - </para> - - </section> - - --> diff --git a/doc/user/depends.xml b/doc/user/depends.xml index d8e8719..5049565 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-depends" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Dependencies</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -36,15 +58,19 @@ </para> - + <scons_example name="depends_ex1"> + <file name="SConstruct"> +Program('hello.c') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } +</file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q</userinput> - scons: `.' is up to date. - </screen> + <scons_output example="depends_ex1" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -57,13 +83,10 @@ </para> - <screen> - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - </screen> + <scons_output example="depends_ex1" os="posix" suffix="2"> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + </scons_output> <para> @@ -112,14 +135,11 @@ </para> - <screen> - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>touch hello.c</userinput> - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - </screen> + <scons_output example="depends_ex1" os="posix" suffix="3"> + <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> @@ -137,16 +157,11 @@ </para> - <screen> - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>edit hello.c</userinput> - [CHANGE THE CONTENTS OF hello.c] - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="depends_ex1" os="posix" suffix="4"> + <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> @@ -157,10 +172,10 @@ </para> - <programlisting> - Program('hello.c') - Decider('MD5') - </programlisting> + <sconstruct> +Program('hello.c') +Decider('MD5') + </sconstruct> <para> @@ -201,16 +216,11 @@ </para> - <screen> - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>edit hello.c</userinput> - [CHANGE A COMMENT IN hello.c] - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c hello.c - scons: `hello' is up to date. - </screen> + <scons_output example="depends_ex1" os="posix" suffix="5"> + <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> @@ -258,10 +268,15 @@ </para> - <programlisting> - Object('hello.c') - Decider('timestamp-newer') - </programlisting> + <scons_example name="depends_newer"> + <file name="SConstruct" printme="1"> +Object('hello.c') +Decider('timestamp-newer') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -271,13 +286,11 @@ </para> - <screen> - % <userinput>scons -Q hello.o</userinput> - cc -o hello.o -c hello.c - % <userinput>touch hello.c</userinput> - % <userinput>scons -Q hello.o</userinput> - cc -o hello.o -c hello.c - </screen> + <scons_output example="depends_newer" os="posix" suffix="1"> + <scons_output_command>scons -Q hello.o</scons_output_command> + <scons_output_command>touch hello.c</scons_output_command> + <scons_output_command>scons -Q hello.o</scons_output_command> + </scons_output> <para> @@ -289,10 +302,10 @@ </para> - <programlisting> - Object('hello.c') - Decider('make') - </programlisting> + <sconstruct> +Object('hello.c') +Decider('make') + </sconstruct> <para> @@ -324,10 +337,15 @@ </para> - <programlisting> - Object('hello.c') - Decider('timestamp-match') - </programlisting> + <scons_example name="depends_match"> + <file name="SConstruct" printme="1"> +Object('hello.c') +Decider('timestamp-match') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -341,13 +359,11 @@ </para> - <screen> - % <userinput>scons -Q hello.o</userinput> - cc -o hello.o -c hello.c - % <userinput>touch -t 198901010000 hello.c</userinput> - % <userinput>scons -Q hello.o</userinput> - cc -o hello.o -c hello.c - </screen> + <scons_output example="depends_match" os="posix" suffix="1"> + <scons_output_command>scons -Q hello.o</scons_output_command> + <scons_output_command>touch -t 198901010000 hello.c</scons_output_command> + <scons_output_command>scons -Q hello.o</scons_output_command> + </scons_output> <para> @@ -380,10 +396,15 @@ </para> - <programlisting> - Program('hello.c') - Decider('MD5-timestamp') - </programlisting> + <scons_example name="depends_MD5-timestamp"> + <file name="SConstruct" printme="1"> +Program('hello.c') +Decider('MD5-timestamp') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -399,7 +420,7 @@ output seems to get this wrong. Just in-line the output for now. - <scons_output example="MD5-timestamp" os="posix"> + <scons_output example="depends_MD5-timestamp" os="posix" suffix="1"> <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> @@ -410,17 +431,17 @@ --> <screen> - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>touch hello.c</userinput> - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - % <userinput>edit hello.c</userinput> - [CHANGE THE CONTENTS OF hello.c] - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o +% <userinput>scons -Q hello</userinput> +cc -o hello.o -c hello.c +cc -o hello hello.o +% <userinput>touch hello.c</userinput> +% <userinput>scons -Q hello</userinput> +scons: `hello' is up to date. +% <userinput>edit hello.c</userinput> + [CHANGE THE CONTENTS OF hello.c] +% <userinput>scons -Q hello</userinput> +cc -o hello.o -c hello.c +cc -o hello hello.o </screen> <para> @@ -493,17 +514,22 @@ </para> - <programlisting> - Program('hello.c') - def decide_if_changed(dependency, target, prev_ni): - if self.get_timestamp() != prev_ni.timestamp: - dep = str(dependency) - tgt = str(target) - if specific_part_of_file_has_changed(dep, tgt): - return True - return False - Decider(decide_if_changed) - </programlisting> + <scons_example name="depends_function"> + <file name="SConstruct" printme="1"> +Program('hello.c') +def decide_if_changed(dependency, target, prev_ni): + if self.get_timestamp() != prev_ni.timestamp: + dep = str(dependency) + tgt = str(target) + if specific_part_of_file_has_changed(dep, tgt): + return True + return False +Decider(decide_if_changed) + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -608,37 +634,37 @@ </para> - <programlisting> - env = Environment() - - def config_file_decider(dependency, target, prev_ni): - import os.path - - # We always have to init the .csig value... - dep_csig = dependency.get_csig() - # .csig may not exist, because no target was built yet... - if 'csig' not in dir(prev_ni): - return True - # Target file may not exist yet - if not os.path.exists(str(target.abspath)): - return True - if dep_csig != prev_ni.csig: - # Some change on source file => update installed one - return True - return False - - def update_file(): - f = open("test.txt","a") - f.write("some line\n") - f.close() - - update_file() - - # Activate our own decider function - env.Decider(config_file_decider) - - env.Install("install","test.txt") - </programlisting> + <sconstruct> +env = Environment() + +def config_file_decider(dependency, target, prev_ni): + import os.path + + # We always have to init the .csig value... + dep_csig = dependency.get_csig() + # .csig may not exist, because no target was built yet... + if 'csig' not in dir(prev_ni): + return True + # Target file may not exist yet + if not os.path.exists(str(target.abspath)): + return True + if dep_csig != prev_ni.csig: + # Some change on source file => update installed one + return True + return False + +def update_file(): + f = open("test.txt","a") + f.write("some line\n") + f.close() + +update_file() + +# Activate our own decider function +env.Decider(config_file_decider) + +env.Install("install","test.txt") + </sconstruct> </section> @@ -670,13 +696,26 @@ </para> - <programlisting> - env1 = Environment(CPPPATH = ['.']) - env2 = env1.Clone() - env2.Decider('timestamp-match') - env1.Program('prog-MD5', 'program1.c') - env2.Program('prog-timestamp', 'program2.c') - </programlisting> + <scons_example name="depends_mixing"> + <file name="SConstruct" printme="1"> +env1 = Environment(CPPPATH = ['.']) +env2 = env1.Clone() +env2.Decider('timestamp-match') +env1.Program('prog-MD5', 'program1.c') +env2.Program('prog-timestamp', 'program2.c') + </file> + <file name="program1.c"> +#include "inc.h" +int main() { printf("Hello, world!\n"); } + </file> + <file name="program2.c"> +#include "inc.h" +int main() { printf("Hello, world!\n"); } + </file> + <file name="inc.h"> +#define INC 1 + </file> + </scons_example> <para> @@ -690,17 +729,11 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o program1.o -c -I. program1.c - cc -o prog-MD5 program1.o - cc -o program2.o -c -I. program2.c - cc -o prog-timestamp program2.o - % <userinput>touch inc.h</userinput> - % <userinput>scons -Q</userinput> - cc -o program2.o -c -I. program2.c - cc -o prog-timestamp program2.o - </screen> + <scons_output example="depends_mixing" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>touch inc.h</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -737,10 +770,10 @@ </para> - <programlisting> - Program('hello.c') - SourceSignatures('MD5') - </programlisting> + <sconstruct> +Program('hello.c') +SourceSignatures('MD5') + </sconstruct> <para> @@ -748,10 +781,10 @@ </para> - <programlisting> - Program('hello.c') - SourceSignatures('timestamp') - </programlisting> + <sconstruct> +Program('hello.c') +SourceSignatures('timestamp') + </sconstruct> <para> @@ -805,10 +838,10 @@ </para> - <programlisting> - Program('hello.c') - TargetSignatures('MD5') - </programlisting> + <sconstruct> +Program('hello.c') +TargetSignatures('MD5') + </sconstruct> <para> @@ -819,10 +852,10 @@ </para> - <programlisting> - Program('hello.c') - TargetSignatures('timestamp') - </programlisting> + <sconstruct> +Program('hello.c') +TargetSignatures('timestamp') + </sconstruct> <para> @@ -848,11 +881,11 @@ </para> - <programlisting> - Program('hello.c') - TargetSignatures('source') - SourceSignatures('timestamp') - </programlisting> + <sconstruct> +Program('hello.c') +TargetSignatures('source') +SourceSignatures('timestamp') + </sconstruct> <para> @@ -914,14 +947,22 @@ </para> - <programlisting> - #include <hello.h> - int - main() - { - printf("Hello, %s!\n", string); - } - </programlisting> + <scons_example name="depends_include"> + <file name="SConstruct"> +Program('hello.c', CPPPATH = '.') + </file> + <file name="hello.c" printme="1"> +#include <hello.h> +int +main() +{ + printf("Hello, %s!\n", string); +} + </file> + <file name="hello.h"> +#define string "world" + </file> + </scons_example> <para> @@ -929,10 +970,8 @@ </para> - - <programlisting> - #define string "world" - </programlisting> + <scons_example_file example="depends_include" name="hello.h"> + </scons_example_file> <para> @@ -944,10 +983,8 @@ </para> - - <programlisting> - Program('hello.c', CPPPATH = '.') - </programlisting> + <scons_example_file example="depends_include" name="SConstruct"> + </scons_example_file> <para> @@ -960,18 +997,12 @@ </para> - <screen> - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c -I. hello.c - cc -o hello hello.o - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - % <userinput>edit hello.h</userinput> - [CHANGE THE CONTENTS OF hello.h] - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c -I. hello.c - cc -o hello hello.o - </screen> + <scons_output example="depends_include" os="posix" suffix="1"> + <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> @@ -1016,9 +1047,14 @@ </para> - <programlisting> - Program('hello.c', CPPPATH = ['include', '/home/project/inc']) - </programlisting> + <scons_example name="depends_ex5"> + <file name="SConstruct" printme="1"> +Program('hello.c', CPPPATH = ['include', '/home/project/inc']) + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -1026,11 +1062,9 @@ </para> - <screen> - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c -Iinclude -I/home/project/inc hello.c - cc -o hello hello.o - </screen> + <scons_output example="depends_ex5" os="posix" suffix="1"> + <scons_output_command>scons -Q hello</scons_output_command> + </scons_output> <para> @@ -1038,12 +1072,9 @@ </para> - <screen> - C:\><userinput>scons -Q hello.exe</userinput> - cl /Fohello.obj /c hello.c /nologo /Iinclude /I\home\project\inc - link /nologo /OUT:hello.exe hello.obj - embedManifestExeCheck(target, source, env) - </screen> + <scons_output example="depends_ex5" os="win32" suffix="2"> + <scons_output_command>scons -Q hello.exe</scons_output_command> + </scons_output> </section> @@ -1095,13 +1126,10 @@ </para> - <screen> - % <userinput>scons -Q --implicit-cache hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - </screen> + <scons_output example="depends_ex1" suffix="6"> + <scons_output_command>scons -Q --implicit-cache hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + </scons_output> <para> @@ -1113,9 +1141,9 @@ </para> - <programlisting> - SetOption('implicit_cache', 1) - </programlisting> + <sconstruct> +SetOption('implicit_cache', 1) + </sconstruct> <para> @@ -1178,13 +1206,10 @@ </para> - <screen> - % <userinput>scons -Q --implicit-deps-changed hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - </screen> + <scons_output example="depends_ex1" suffix="7"> + <scons_output_command>scons -Q --implicit-deps-changed hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + </scons_output> <para> @@ -1216,13 +1241,10 @@ </para> - <screen> - % <userinput>scons -Q --implicit-deps-unchanged hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - </screen> + <scons_output example="depends_ex1" suffix="8"> + <scons_output_command>scons -Q --implicit-deps-unchanged hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + </scons_output> <para> @@ -1269,23 +1291,23 @@ </para> <programlisting> - hello = Program('hello.c') - Depends(hello, 'other_file') +hello = Program('hello.c') +Depends(hello, 'other_file') </programlisting> <!-- XXX mention that you can use arrays for target and source? --> <screen> - % <userinput>scons -Q hello</userinput> - cc -c hello.c -o hello.o - cc -o hello hello.o - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - % <userinput>edit other_file</userinput> - [CHANGE THE CONTENTS OF other_file] - % <userinput>scons -Q hello</userinput> - cc -c hello.c -o hello.o - cc -o hello hello.o +% <userinput>scons -Q hello</userinput> +cc -c hello.c -o hello.o +cc -o hello hello.o +% <userinput>scons -Q hello</userinput> +scons: `hello' is up to date. +% <userinput>edit other_file</userinput> + [CHANGE THE CONTENTS OF other_file] +% <userinput>scons -Q hello</userinput> +cc -c hello.c -o hello.o +cc -o hello hello.o </screen> <para> @@ -1298,9 +1320,9 @@ </para> <programlisting> - hello = Program('hello.c') - goodbye = Program('goodbye.c') - Depends(hello, goodbye) +hello = Program('hello.c') +goodbye = Program('goodbye.c') +Depends(hello, goodbye) </programlisting> <para> @@ -1311,11 +1333,11 @@ </para> <screen> - % <userinput>scons -Q hello</userinput> - cc -c goodbye.c -o goodbye.o - cc -o goodbye goodbye.o - cc -c hello.c -o hello.o - cc -o hello hello.o +% <userinput>scons -Q hello</userinput> +cc -c goodbye.c -o goodbye.o +cc -o goodbye goodbye.o +cc -c hello.c -o hello.o +cc -o hello hello.o </screen> </section> @@ -1340,24 +1362,28 @@ </para> - <programlisting> - #define FOO_HEADER <foo.h> - #include FOO_HEADER - - int main() { - return FOO; - } - </programlisting> - - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c -I. hello.c - cc -o hello hello.o - % <userinput>edit foo.h</userinput> - [CHANGE CONTENTS OF foo.h] - % <userinput>scons -Q</userinput> - scons: `.' is up to date. - </screen> + <scons_example name="depends_macroinc"> + <file name="hello.c" printme="1"> +#define FOO_HEADER <foo.h> +#include FOO_HEADER + +int main() { + return FOO; +} + </file> + <file name="SConstruct"> +Program('hello', 'hello.c', CPPPATH='.') + </file> + <file name="foo.h"> +#define FOO 42 + </file> + </scons_example> + + <scons_output example="depends_macroinc" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command output=" [CHANGE CONTENTS OF foo.h]">edit foo.h</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1388,22 +1414,34 @@ priori specification of the dependency file. The produced hello.d file is not found (or used) for unknown reasons. --> - <programlisting> - obj = Object('hello.c', CCFLAGS='-MD -MF hello.d', CPPPATH='.') - SideEffect('hello.d', obj) - ParseDepends('hello.d') - Program('hello', obj) - </programlisting> - - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c -MD -MF hello.d -I. hello.c - cc -o hello hello.o - % <userinput>edit foo.h</userinput> - [CHANGE CONTENTS OF foo.h] - % <userinput>scons -Q</userinput> - cc -o hello.o -c -MD -MF hello.d -I. hello.c - </screen> + <scons_example name="depends_parsedep"> + <file name="hello.c"> +#define FOO_HEADER <foo.h> +#include FOO_HEADER + +int main() { + return FOO; +} + </file> + <file name="SConstruct" printme="1"> +obj = Object('hello.c', CCFLAGS='-MD -MF hello.d', CPPPATH='.') +SideEffect('hello.d', obj) +ParseDepends('hello.d') +Program('hello', obj) + </file> + <file name="foo.h"> +#define FOO 42 + </file> + <file name="hello.d"> +hello.o: hello.c foo.h + </file> + </scons_example> + + <scons_output example="depends_parsedep" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command output=" [CHANGE CONTENTS OF foo.h]">edit foo.h</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1413,10 +1451,28 @@ </para> - + <scons_example name="depends_parsedeprebuild"> + <file name="hello.c"> +#define FOO_HEADER <foo.h> +#include FOO_HEADER + +int main() { + return FOO; +} + </file> + <file name="SConstruct"> +obj = Object('hello.c', CCFLAGS='-MD -MF hello.d', CPPPATH='.') +SideEffect('hello.d', obj) +ParseDepends('hello.d') +Program('hello', obj) + </file> + <file name="foo.h"> +#define FOO 42 + </file> + </scons_example> <!-- - <scons_output example="parsedeprebuild" os="posix"> + <scons_output example="depends_parsedeprebuild" os="posix" suffix="1"> <scons_output_command>scons -Q</scons_output_command> <scons_output_command>scons -Q</scons_output_command> <scons_output_command>scons -Q</scons_output_command> @@ -1424,14 +1480,14 @@ --> <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c -MD -MF hello.d -I. hello.c - cc -o hello hello.o - % <userinput>scons -Q --debug=explain</userinput> - scons: rebuilding `hello.o' because `foo.h' is a new dependency - cc -o hello.o -c -MD -MF hello.d -I. hello.c - % <userinput>scons -Q</userinput> - scons: `.' is up to date. +% <userinput>scons -Q</userinput> +cc -o hello.o -c -MD -MF hello.d -I. hello.c +cc -o hello hello.o +% <userinput>scons -Q --debug=explain</userinput> +scons: rebuilding `hello.o' because `foo.h' is a new dependency +cc -o hello.o -c -MD -MF hello.d -I. hello.c +% <userinput>scons -Q</userinput> +scons: `.' is up to date. </screen> <para> @@ -1474,16 +1530,25 @@ </para> - <programlisting> - hello_obj=Object('hello.c') - hello = Program(hello_obj) - Ignore(hello_obj, 'hello.h') - </programlisting> + <scons_example name="depends_ignore"> + <file name="SConstruct" printme="1"> +hello_obj=Object('hello.c') +hello = Program(hello_obj) +Ignore(hello_obj, 'hello.h') + </file> + <file name="hello.c"> +#include "hello.h" +int main() { printf("Hello, %s!\n", string); } + </file> + <file name="hello.h"> +#define string "world" + </file> + </scons_example> <!-- XXX mention that you can use lists for target and source? --> <!-- - <scons_output example="ignore"> + <scons_output example="depends_ignore" suffix="1"> <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> @@ -1493,15 +1558,15 @@ --> <screen> - % <userinput>scons -Q hello</userinput> - cc -c -o hello.o hello.c - cc -o hello hello.o - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - % <userinput>edit hello.h</userinput> - [CHANGE THE CONTENTS OF hello.h] - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. +% <userinput>scons -Q hello</userinput> +cc -c -o hello.o hello.c +cc -o hello hello.o +% <userinput>scons -Q hello</userinput> +scons: `hello' is up to date. +% <userinput>edit hello.h</userinput> + [CHANGE THE CONTENTS OF hello.h] +% <userinput>scons -Q hello</userinput> +scons: `hello' is up to date. </screen> <para> @@ -1526,8 +1591,8 @@ </para> <programlisting> - hello = Program('hello.c', CPPPATH=['/usr/include']) - Ignore(hello, '/usr/include/stdio.h') +hello = Program('hello.c', CPPPATH=['/usr/include']) +Ignore(hello, '/usr/include/stdio.h') </programlisting> <para> @@ -1541,21 +1606,23 @@ by default. </para> - <programlisting> - hello_obj=Object('hello.c') - hello = Program(hello_obj) - Ignore('.',[hello,hello_obj]) - </programlisting> - - <screen> - % <userinput>scons -Q</userinput> - scons: `.' is up to date. - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q hello</userinput> - scons: `hello' is up to date. - </screen> + <scons_example name="depends_ignore_explicit"> + <file name="SConstruct" printme="1"> +hello_obj=Object('hello.c') +hello = Program(hello_obj) +Ignore('.',[hello,hello_obj]) + </file> + <file name="hello.c"> +#include "stdio.h" +int main() { printf("Hello!\n"); } + </file> + </scons_example> + + <scons_output example="depends_ignore_explicit" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + </scons_output> </section> <section> @@ -1600,16 +1667,22 @@ </para> - <programlisting> - import time + <scons_example name="depends_no-Requires"> + <file name="SConstruct" printme="1"> +import time - version_c_text = """ - char *date = "%s"; - """ % time.ctime(time.time()) - open('version.c', 'w').write(version_c_text) +version_c_text = """ +char *date = "%s"; +""" % time.ctime(time.time()) +open('version.c', 'w').write(version_c_text) - hello = Program(['hello.c', 'version.c']) - </programlisting> +hello = Program(['hello.c', 'version.c']) + </file> + <file name="hello.c"> +extern char *date; +int main() { printf("Hello, %s! I was built: %s\n", date); } + </file> + </scons_example> <para> @@ -1624,20 +1697,13 @@ </para> - <screen> - % <userinput>scons -Q hello</userinput> - cc -o hello.o -c hello.c - cc -o version.o -c version.c - cc -o hello hello.o version.o - % <userinput>sleep 1</userinput> - % <userinput>scons -Q hello</userinput> - cc -o version.o -c version.c - cc -o hello hello.o version.o - % <userinput>sleep 1</userinput> - % <userinput>scons -Q hello</userinput> - cc -o version.o -c version.c - cc -o hello hello.o version.o - </screen> + <scons_output example="depends_no-Requires" suffix="1"> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>sleep 1</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>sleep 1</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + </scons_output> <para> @@ -1660,21 +1726,27 @@ </para> - <programlisting> - import time + <scons_example name="depends_Requires"> + <file name="SConstruct" printme="1"> +import time - version_c_text = """ - char *date = "%s"; - """ % time.ctime(time.time()) - open('version.c', 'w').write(version_c_text) +version_c_text = """ +char *date = "%s"; +""" % time.ctime(time.time()) +open('version.c', 'w').write(version_c_text) - version_obj = Object('version.c') +version_obj = Object('version.c') - hello = Program('hello.c', - LINKFLAGS = str(version_obj[0])) +hello = Program('hello.c', + LINKFLAGS = str(version_obj[0])) - Requires(hello, version_obj) - </programlisting> +Requires(hello, version_obj) + </file> + <file name="hello.c"> +extern char *date; +int main() { printf("Hello, %s! I was built: %s\n", date); } + </file> + </scons_example> <para> @@ -1702,27 +1774,16 @@ </para> - <screen> - % <userinput>scons -Q hello</userinput> - cc -o version.o -c version.c - cc -o hello.o -c hello.c - cc -o hello version.o hello.o - % <userinput>sleep 1</userinput> - % <userinput>scons -Q hello</userinput> - cc -o version.o -c version.c - scons: `hello' is up to date. - % <userinput>sleep 1</userinput> - % <userinput>edit hello.c</userinput> - [CHANGE THE CONTENTS OF hello.c] - % <userinput>scons -Q hello</userinput> - cc -o version.o -c version.c - cc -o hello.o -c hello.c - cc -o hello version.o hello.o - % <userinput>sleep 1</userinput> - % <userinput>scons -Q hello</userinput> - cc -o version.o -c version.c - scons: `hello' is up to date. - </screen> + <scons_output example="depends_Requires" suffix="1"> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>sleep 1</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + <scons_output_command>sleep 1</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_command>sleep 1</scons_output_command> + <scons_output_command>scons -Q hello</scons_output_command> + </scons_output> </section> @@ -1738,10 +1799,15 @@ </para> - <programlisting> - hello = Program('hello.c') - AlwaysBuild(hello) - </programlisting> + <scons_example name="depends_AlwaysBuild"> + <file name="SConstruct" printme="1"> +hello = Program('hello.c') +AlwaysBuild(hello) + </file> + <file name="hello.c"> +int main() { printf("Hello, %s!\n", string); } + </file> + </scons_example> <para> @@ -1752,13 +1818,10 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q</userinput> - cc -o hello hello.o - </screen> + <scons_output example="depends_AlwaysBuild" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1777,13 +1840,10 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q hello.o</userinput> - scons: `hello.o' is up to date. - </screen> + <scons_output example="depends_AlwaysBuild" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q hello.o</scons_output_command> + </scons_output> <!-- @@ -1830,3 +1890,5 @@ operating system on which the build is performed (as reported by C<uname </section> --> + +</chapter> diff --git a/doc/user/environments.in b/doc/user/environments.in deleted file mode 100644 index eebc486..0000000 --- a/doc/user/environments.in +++ /dev/null @@ -1,1752 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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. - ---> - -<!-- - -=head1 More on construction environments - -As previously mentioned, a B<construction environment> is an object that -has a set of keyword/value pairs and a set of methods, and which is used -to tell Cons how target files should be built. This section describes -how Cons uses and expands construction environment values to control its -build behavior. - -=head2 Construction variable expansion - -Construction variables from a construction environment are expanded -by preceding the keyword with a C<%> (percent sign): - - Construction variables: - XYZZY => 'abracadabra', - - The string: "The magic word is: %XYZZY!" - expands to: "The magic word is: abracadabra!" - -A construction variable name may be surrounded by C<{> and C<}> (curly -braces), which are stripped as part of the expansion. This can -sometimes be necessary to separate a variable expansion from trailing -alphanumeric characters: - - Construction variables: - OPT => 'value1', - OPTION => 'value2', - - The string: "%OPT %{OPT}ION %OPTION %{OPTION}" - expands to: "value1 value1ION value2 value2" - -Construction variable expansion is recursive, that is, a string -containing C<%->expansions after substitution will be re-expanded until -no further substitutions can be made: - - Construction variables: - STRING => 'The result is: %FOO', - FOO => '%BAR', - BAR => 'final value', - - The string: "The string says: %STRING" - expands to: "The string says: The result is: final value" - -If a construction variable is not defined in an environment, then the -null string is substituted: - - Construction variables: - FOO => 'value1', - BAR => 'value2', - - The string: "%FOO <%NO_VARIABLE> %BAR" - expands to: "value1 <> value2" - -A doubled C<%%> will be replaced by a single C<%>: - - The string: "Here is a percent sign: %%" - expands to: "Here is a percent sign: %" - -=head2 Default construction variables - -When you specify no arguments when creating a new construction -environment: - - $env = new cons(); - -Cons creates a reference to a new, default construction -environment. This contains a number of construction variables and some -methods. At the present writing, the default construction variables on a -UNIX system are: - - CC => 'cc', - CFLAGS => '', - CCCOM => '%CC %CFLAGS %_IFLAGS -c %< -o %>', - CXX => '%CC', - CXXFLAGS => '%CFLAGS', - CXXCOM => '%CXX %CXXFLAGS %_IFLAGS -c %< -o %>', - INCDIRPREFIX => '-I', - INCDIRSUFFIX => '', - LINK => '%CXX', - LINKCOM => '%LINK %LDFLAGS -o %> %< %_LDIRS %LIBS', - LINKMODULECOM => '%LD -r -o %> %<', - LIBDIRPREFIX => '-L', - LIBDIRSUFFIX => '', - AR => 'ar', - ARFLAGS => 'r', - ARCOM => ['%AR %ARFLAGS %> %<', '%RANLIB %>'], - RANLIB => 'ranlib', - AS => 'as', - ASFLAGS => '', - ASCOM => '%AS %ASFLAGS %< -o %>', - LD => 'ld', - LDFLAGS => '', - PREFLIB => 'lib', - SUFLIB => '.a', - SUFLIBS => '.so:.a', - SUFOBJ => '.o', - SIGNATURE => [ '*' => 'build' ], - ENV => { 'PATH' => '/bin:/usr/bin' }, - - -And on a Windows system (Windows NT), the default construction variables -are (unless the default rule style is set using the B<DefaultRules> -method): - - CC => 'cl', - CFLAGS => '/nologo', - CCCOM => '%CC %CFLAGS %_IFLAGS /c %< /Fo%>', - CXXCOM => '%CXX %CXXFLAGS %_IFLAGS /c %< /Fo%>', - INCDIRPREFIX => '/I', - INCDIRSUFFIX => '', - LINK => 'link', - LINKCOM => '%LINK %LDFLAGS /out:%> %< %_LDIRS %LIBS', - LINKMODULECOM => '%LD /r /o %> %<', - LIBDIRPREFIX => '/LIBPATH:', - LIBDIRSUFFIX => '', - AR => 'lib', - ARFLAGS => '/nologo ', - ARCOM => "%AR %ARFLAGS /out:%> %<", - RANLIB => '', - LD => 'link', - LDFLAGS => '/nologo ', - PREFLIB => '', - SUFEXE => '.exe', - SUFLIB => '.lib', - SUFLIBS => '.dll:.lib', - SUFOBJ => '.obj', - SIGNATURE => [ '*' => 'build' ], - -These variables are used by the various methods associated with the -environment. In particular, any method that ultimately invokes an external -command will substitute these variables into the final command, as -appropriate. For example, the C<Objects> method takes a number of source -files and arranges to derive, if necessary, the corresponding object -files: - - Objects $env 'foo.c', 'bar.c'; - -This will arrange to produce, if necessary, F<foo.o> and F<bar.o>. The -command invoked is simply C<%CCCOM>, which expands, through substitution, -to the appropriate external command required to build each object. The -substitution rules will be discussed in detail in the next section. - -The construction variables are also used for other purposes. For example, -C<CPPPATH> is used to specify a colon-separated path of include -directories. These are intended to be passed to the C preprocessor and are -also used by the C-file scanning machinery to determine the dependencies -involved in a C Compilation. - -Variables beginning with underscore are created by various methods, -and should normally be considered ``internal'' variables. For example, -when a method is called which calls for the creation of an object from -a C source, the variable C<_IFLAGS> is created: this corresponds to the -C<-I> switches required by the C compiler to represent the directories -specified by C<CPPPATH>. - -Note that, for any particular environment, the value of a variable is set -once, and then never reset (to change a variable, you must create a new -environment. Methods are provided for copying existing environments for this -purpose). Some internal variables, such as C<_IFLAGS> are created on demand, -but once set, they remain fixed for the life of the environment. - -The C<CFLAGS>, C<LDFLAGS>, and C<ARFLAGS> variables all supply a place -for passing options to the compiler, loader, and archiver, respectively. - -The C<INCDIRPREFIX> and C<INCDIRSUFFIX> variables specify option -strings to be appended to the beginning and end, respectively, of each -include directory so that the compiler knows where to find F<.h> files. -Similarly, the C<LIBDIRPREFIX> and C<LIBDIRSUFFIX> variables specify the -option string to be appended to the beginning of and end, respectively, -of each directory that the linker should search for libraries. - -Another variable, C<ENV>, is used to determine the system environment during -the execution of an external command. By default, the only environment -variable that is set is C<PATH>, which is the execution path for a UNIX -command. For the utmost reproducibility, you should really arrange to set -your own execution path, in your top-level F<Construct> file (or perhaps by -importing an appropriate construction package with the Perl C<use> -command). The default variables are intended to get you off the ground. - -=head2 Expanding variables in construction commands - -Within a construction command, construction variables will be expanded -according to the rules described above. In addition to normal variable -expansion from the construction environment, construction commands also -expand the following pseudo-variables to insert the specific input and -output files in the command line that will be executed: - -=over 10 - -=item %> - -The target file name. In a multi-target command, this expands to the -first target mentioned.) - -=item %0 - -Same as C<%E<gt>>. - -=item %1, %2, ..., %9 - -These refer to the first through ninth input file, respectively. - -=item %E<lt> - -The full set of input file names. If any of these have been used -anywhere else in the current command line (via C<%1>, C<%2>, etc.), then -those will be deleted from the list provided by C<%E<lt>>. Consider the -following command found in a F<Conscript> file in the F<test> directory: - - Command $env 'tgt', qw(foo bar baz), qq( - echo %< -i %1 > %> - echo %< -i %2 >> %> - echo %< -i %3 >> %> - ); - -If F<tgt> needed to be updated, then this would result in the execution of -the following commands, assuming that no remapping has been established for -the F<test> directory: - - echo test/bar test/baz -i test/foo > test/tgt - echo test/foo test/baz -i test/bar >> test/tgt - echo test/foo test/bar -i test/baz >> test/tgt - -=back - -Any of the above pseudo-variables may be followed immediately by one of -the following suffixes to select a portion of the expanded path name: - - :a the absolute path to the file name - :b the directory plus the file name stripped of any suffix - :d the directory - :f the file name - :s the file name suffix - :F the file name stripped of any suffix - :S the absolute path path to a Linked source file - -Continuing with the above example, C<%E<lt>:f> would expand to C<foo bar baz>, -and C<%E<gt>:d> would expand to C<test>. - -There are additional C<%> elements which affect the command line(s): - -=over 10 - -=item %[ %] - -It is possible to programmatically rewrite part of the command by -enclosing part of it between C<%[> and C<%]>. This will call the -construction variable named as the first word enclosed in the brackets -as a Perl code reference; the results of this call will be used to -replace the contents of the brackets in the command line. For example, -given an existing input file named F<tgt.in>: - - @keywords = qw(foo bar baz); - $env = new cons(X_COMMA => sub { join(",", @_) }); - Command $env 'tgt', 'tgt.in', qq( - echo '# Keywords: %[X_COMMA @keywords %]' > %> - cat %< >> %> - ); - -This will execute: - - echo '# Keywords: foo,bar,baz' > tgt - cat tgt.in >> tgt - -=item %( %) - -Cons includes the text of the command line in the MD5 signature for a -build, so that targets get rebuilt if you change the command line (to -add or remove an option, for example). Command-line text in between -C<%(> and C<%)>, however, will be ignored for MD5 signature calculation. - -Internally, Cons uses C<%(> and C<%)> around include and library -directory options (C<-I> and C<-L> on UNIX systems, C</I> and -C</LIBPATH> on Windows NT) to avoid rebuilds just because the directory -list changes. Rebuilds occur only if the changed directory list causes -any included I<files> to change, and a changed include file is detected -by the MD5 signature calculation on the actual file contents. - -=back - -XXX DESCRIBE THE Literal() FUNCTION, TOO XXX - -=head2 Expanding construction variables in file names - -Cons expands construction variables in the source and target file names -passed to the various construction methods according to the expansion -rules described above: - - $env = new cons( - DESTDIR => 'programs', - SRCDIR => 'src', - ); - Program $env '%DESTDIR/hello', '%SRCDIR/hello.c'; - -This allows for flexible configuration, through the construction -environment, of directory names, suffixes, etc. - ---> - - <para> - - An <literal>environment</literal> - is a collection of values that - can affect how a program executes. - &SCons; distinguishes between three - different types of environments - that can affect the behavior of &SCons; itself - (subject to the configuration in the &SConscript; files), - as well as the compilers and other tools it executes: - - </para> - - <variablelist> - - <varlistentry> - <term>External Environment</term> - - <listitem> - <para> - - The <literal>external environment</literal> - is the set of variables in the user's environment - at the time the user runs &SCons;. - These variables are available within the &SConscript; files - through the Python <literal>os.environ</literal> dictionary. - See <xref linkend="sect-external-environments"></xref>, below. - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&ConsEnv;</term> - - <listitem> - <para> - - A &consenv; - is a distinct object creating within - a &SConscript; file and - and which contains values that - affect how &SCons; decides - what action to use to build a target, - and even to define which targets - should be built from which sources. - One of the most powerful features of &SCons; - is the ability to create multiple &consenvs;, - including the ability to clone a new, customized - &consenv; from an existing &consenv;. - See <xref linkend="sect-construction-environments"></xref>, below. - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Execution Environment</term> - - <listitem> - <para> - - An <literal>execution environment</literal> - is the values that &SCons; sets - when executing an external - command (such as a compiler or linker) - to build one or more targets. - Note that this is not the same as - the <literal>external environment</literal> - (see above). - See <xref linkend="sect-execution-environments"></xref>, below. - - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - - Unlike &Make;, &SCons; does not automatically - copy or import values between different environments - (with the exception of explicit clones of &consenvs;, - which inherit values from their parent). - This is a deliberate design choice - to make sure that builds are, - by default, repeatable regardless of - the values in the user's external environment. - This avoids a whole class of problems with builds - where a developer's local build works - because a custom variable setting - causes a different compiler or build option to be used, - but the checked-in change breaks the official build - because it uses different environment variable settings. - - </para> - - <para> - - Note that the &SConscript; writer can - easily arrange for variables to be - copied or imported between environments, - and this is often very useful - (or even downright necessary) - to make it easy for developers - to customize the build in appropriate ways. - The point is <emphasis>not</emphasis> - that copying variables between different environments - is evil and must always be avoided. - Instead, it should be up to the - implementer of the build system - to make conscious choices - about how and when to import - a variable from one environment to another, - making informed decisions about - striking the right balance - between making the build - repeatable on the one hand - and convenient to use on the other. - - </para> - - <section id="sect-external-environments"> - <title>Using Values From the External Environment</title> - - <para> - - The <literal>external environment</literal> - variable settings that - the user has in force - when executing &SCons; - are available through the normal Python - <envar>os.environ</envar> - dictionary. - This means that you must add an - <literal>import os</literal> statement - to any &SConscript; file - in which you want to use - values from the user's external environment. - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - import os - </file> - <file name="foo.c"> - int main() { } - </file> - </scons_example> - - <para> - - More usefully, you can use the - <envar>os.environ</envar> - dictionary in your &SConscript; - files to initialize &consenvs; - with values from the user's external environment. - See the next section, - <xref linkend="sect-construction-environments"></xref>, - for information on how to do this. - - </para> - - </section> - - <section id="sect-construction-environments"> - <title>Construction Environments</title> - - <para> - - It is rare that all of the software in a large, - complicated system needs to be built the same way. - For example, different source files may need different options - enabled on the command line, - or different executable programs need to be linked - with different libraries. - &SCons; accommodates these different build - requirements by allowing you to create and - configure multiple &consenvs; - that control how the software is built. - A &consenv; is an object - that has a number of associated - &consvars;, each with a name and a value. - (A construction environment also has an attached - set of &Builder; methods, - about which we'll learn more later.) - - </para> - - <section> - <title>Creating a &ConsEnv;: the &Environment; Function</title> - - <para> - - A &consenv; is created by the &Environment; method: - - </para> - - <sconstruct> - env = Environment() - </sconstruct> - - <para> - - By default, &SCons; initializes every - new construction environment - with a set of &consvars; - based on the tools that it finds on your system, - plus the default set of builder methods - necessary for using those tools. - The construction variables - are initialized with values describing - the C compiler, - the Fortran compiler, - the linker, - etc., - as well as the command lines to invoke them. - - </para> - - <para> - - When you initialize a construction environment - you can set the values of the - environment's &consvars; - to control how a program is built. - For example: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - env = Environment(CC = 'gcc', - CCFLAGS = '-O2') - - env.Program('foo.c') - </file> - <file name="foo.c"> - int main() { } - </file> - </scons_example> - - <para> - - The construction environment in this example - is still initialized with the same default - construction variable values, - except that the user has explicitly specified use of the - GNU C compiler &gcc;, - 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 - &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: - - </para> - - <scons_output example="ex1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Fetching Values From a &ConsEnv;</title> - - <para> - - You can fetch individual construction variables - using the normal syntax - for accessing individual named items in a Python dictionary: - - </para> - - <scons_example name="ex6"> - <file name="SConstruct" printme="1"> - env = Environment() - print "CC is:", env['CC'] - </file> - </scons_example> - - <para> - - This example &SConstruct; file doesn't build anything, - but because it's actually a Python script, - it will print the value of &cv-link-CC; for us: - - </para> - - <scons_output example="ex6"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - A construction environment, however, - is actually an object with associated methods, etc. - If you want to have direct access to only the - dictionary of construction variables, - you can fetch this using the &Dictionary; method: - - </para> - - <scons_example name="ex6b"> - <file name="SConstruct" printme="1"> - env = Environment(FOO = 'foo', BAR = 'bar') - dict = env.Dictionary() - for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']: - print "key = %s, value = %s" % (key, dict[key]) - </file> - </scons_example> - - <para> - - This &SConstruct; file - will print the specified dictionary items for us on POSIX - systems as follows: - - </para> - - <scons_output example="ex6b" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - And on Windows: - - </para> - - <scons_output example="ex6b" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - If you want to loop and print the values of - all of the construction variables in a construction environment, - the Python code to do that in sorted order might look something like: - - </para> - - <sconstruct> - env = Environment() - for item in sorted(env.Dictionary().items()): - print "construction variable = '%s', value = '%s'" % item - </sconstruct> - - </section> - - <section> - <title>Expanding Values From a &ConsEnv;: the &subst; Method</title> - - <para> - - Another way to get information from - a construction environment - is to use the &subst; method - on a string containing <literal>$</literal> expansions - of construction variable names. - As a simple example, - the example from the previous - section that used - <literal>env['CC']</literal> - to fetch the value of &cv-link-CC; - could also be written as: - - </para> - - <sconstruct> - env = Environment() - print "CC is:", env.subst('$CC') - </sconstruct> - - <para> - - One advantage of using - &subst; to expand strings is - that construction variables - in the result get re-expanded until - there are no expansions left in the string. - So a simple fetch of a value like - &cv-link-CCCOM;: - - </para> - - <sconstruct> - env = Environment(CCFLAGS = '-DFOO') - print "CCCOM is:", env['CCCOM'] - </sconstruct> - - <para> - - Will print the unexpanded value of &cv-CCCOM;, - showing us the construction - variables that still need to be expanded: - - </para> - - <screen> - % <userinput>scons -Q</userinput> - CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES - scons: `.' is up to date. - </screen> - - <para> - - Calling the &subst; method on <varname>$CCOM</varname>, - however: - - </para> - - <sconstruct> - env = Environment(CCFLAGS = '-DFOO') - print "CCCOM is:", env.subst('$CCCOM') - </sconstruct> - - <para> - - Will recursively expand all of - the construction variables prefixed - with <literal>$</literal> (dollar signs), - showing us the final output: - - </para> - - <screen> - % <userinput>scons -Q</userinput> - CCCOM is: gcc -DFOO -c -o - scons: `.' is up to date. - </screen> - - <para> - - Note that because we're not expanding this - in the context of building something - there are no target or source files - for &cv-link-TARGET; and &cv-link-SOURCES; to expand. - - </para> - - </section> - - <section> - <title>Handling Problems With Value Expansion</title> - - <para> - - If a problem occurs when expanding a construction variable, - by default it is expanded to <literal>''</literal> - (a null string), and will not cause scons to fail. - </para> - - <scons_example name="missing1"> - <file name="SConstruct" printme="1"> - env = Environment() - print "value is:", env.subst( '->$MISSING<-' ) - </file> - </scons_example> - - <scons_output example="missing1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - This default behaviour can be changed using the &AllowSubstExceptions; - function. - When a problem occurs with a variable expansion it generates - an exception, and the &AllowSubstExceptions; function controls - which of these exceptions are actually fatal and which are - allowed to occur safely. By default, &NameError; and &IndexError; - are the two exceptions that are allowed to occur: so instead of - causing scons to fail, these are caught, the variable expanded to - <literal>''</literal> - and scons execution continues. - To require that all construction variable names exist, and that - indexes out of range are not allowed, call &AllowSubstExceptions; - with no extra arguments. - </para> - - <scons_example name="missing2"> - <file name="SConstruct" printme="1"> - AllowSubstExceptions() - env = Environment() - print "value is:", env.subst( '->$MISSING<-' ) - </file> - </scons_example> - - <scons_output example="missing2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - This can also be used to allow other exceptions that might occur, - most usefully with the <literal>${...}</literal> construction - variable syntax. For example, this would allow zero-division to - occur in a variable expansion in addition to the default exceptions - allowed - </para> - - <scons_example name="missing3"> - <file name="SConstruct" printme="1"> - AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) - env = Environment() - print "value is:", env.subst( '->${1 / 0}<-' ) - </file> - </scons_example> - - <scons_output example="missing3"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - <sconstruct> - </sconstruct> - - <para> - If &AllowSubstExceptions; is called multiple times, each call - completely overwrites the previous list of allowed exceptions. - </para> - - </section> - - <section> - <title>Controlling the Default &ConsEnv;: the &DefaultEnvironment; Function</title> - - <para> - - All of the &Builder; functions that we've introduced so far, - like &Program; and &Library;, - actually use a default &consenv; - that contains settings - for the various compilers - and other tools that - &SCons; configures by default, - or otherwise knows about - and has discovered on your system. - The goal of the default construction environment - is to make many configurations to "just work" - to build software using - readily available tools - with a minimum of configuration changes. - - </para> - - <para> - - You can, however, control the settings - in the default construction environment - by using the &DefaultEnvironment; function - to initialize various settings: - - </para> - - <sconstruct> - - DefaultEnvironment(CC = '/usr/local/bin/gcc') - - </sconstruct> - - <para> - - When configured as above, - all calls to the &Program; - or &Object; Builder - will build object files with the - <filename>/usr/local/bin/gcc</filename> - compiler. - - </para> - - <para> - - Note that the &DefaultEnvironment; function - returns the initialized - default construction environment object, - which can then be manipulated like any - other construction environment. - So the following - would be equivalent to the - previous example, - setting the &cv-CC; - variable to <filename>/usr/local/bin/gcc</filename> - but as a separate step after - the default construction environment has been initialized: - - </para> - - <sconstruct> - - env = DefaultEnvironment() - env['CC'] = '/usr/local/bin/gcc' - - </sconstruct> - - <para> - - One very common use of the &DefaultEnvironment; function - is to speed up &SCons; initialization. - As part of trying to make most default - configurations "just work," - &SCons; will actually - search the local system for installed - compilers and other utilities. - This search can take time, - especially on systems with - slow or networked file systems. - If you know which compiler(s) and/or - other utilities you want to configure, - you can control the search - that &SCons; performs - by specifying some specific - tool modules with which to - initialize the default construction environment: - - </para> - - <sconstruct> - - env = DefaultEnvironment(tools = ['gcc', 'gnulink'], - CC = '/usr/local/bin/gcc') - - </sconstruct> - - <para> - - So the above example would tell &SCons; - to explicitly configure the default environment - to use its normal GNU Compiler and GNU Linker settings - (without having to search for them, - or any other utilities for that matter), - and specifically to use the compiler found at - <filename>/usr/local/bin/gcc</filename>. - - </para> - - </section> - - <section> - <title>Multiple &ConsEnvs;</title> - - <para> - - The real advantage of construction environments - is that you can create as many different construction - environments as you need, - each tailored to a different way to build - some piece of software or other file. - If, for example, we need to build - one program with the <literal>-O2</literal> flag - and another with the <literal>-g</literal> (debug) flag, - we would do this like so: - - </para> - - <scons_example name="ex2"> - <file name="SConstruct" printme="1"> - opt = Environment(CCFLAGS = '-O2') - dbg = Environment(CCFLAGS = '-g') - - opt.Program('foo', 'foo.c') - - dbg.Program('bar', 'bar.c') - </file> - <file name="foo.c"> - int main() { } - </file> - <file name="bar.c"> - int main() { } - </file> - </scons_example> - - <scons_output example="ex2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - 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 - &b-link-Program; builder with both environments, though, - like this: - - </para> - - <scons_example name="ex3"> - <file name="SConstruct" printme="1"> - opt = Environment(CCFLAGS = '-O2') - dbg = Environment(CCFLAGS = '-g') - - opt.Program('foo', 'foo.c') - - dbg.Program('foo', 'foo.c') - </file> - <file name="foo.c"> - int main() { } - </file> - </scons_example> - - <para> - - Then &SCons; generates the following error: - - </para> - - <scons_output example="ex3"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - 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 &cv-link-CCFLAGS; value of - <literal>-O2</literal> - 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, - so it generates the error. - To avoid this problem, - we must explicitly specify - that each environment compile - <filename>foo.c</filename> - to a separately-named object file - using the &b-link-Object; builder, like so: - - </para> - - <scons_example name="ex4"> - <file name="SConstruct" printme="1"> - opt = Environment(CCFLAGS = '-O2') - dbg = Environment(CCFLAGS = '-g') - - o = opt.Object('foo-opt', 'foo.c') - opt.Program(o) - - d = dbg.Object('foo-dbg', 'foo.c') - dbg.Program(d) - </file> - <file name="foo.c"> - int main() { } - </file> - </scons_example> - - <para> - - 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 &b-Program; builder. - This avoids having to specify explicitly - the object file name in multiple places, - and makes for a compact, readable - &SConstruct; file. - Our &SCons; output then looks like: - - </para> - - <scons_output example="ex4"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Making Copies of &ConsEnvs;: the &Clone; Method</title> - - <para> - - Sometimes you want more than one construction environment - to share the same values for one or more variables. - Rather than always having to repeat all of the common - variables when you create each construction environment, - you can use the &Clone; method - to create a copy of a construction environment. - - </para> - - <para> - - Like the &Environment; call that creates a construction environment, - the &Clone; method takes &consvar; assignments, - which will override the values in the copied construction environment. - For example, suppose we want to use &gcc; - 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 &cv-link-CC; to &gcc;, - and then creating two copies, - one which sets &cv-link-CCFLAGS; for optimization - and the other which sets &cv-CCFLAGS; for debugging: - - </para> - - <scons_example name="ex5"> - <file name="SConstruct" printme="1"> - env = Environment(CC = 'gcc') - opt = env.Clone(CCFLAGS = '-O2') - dbg = env.Clone(CCFLAGS = '-g') - - env.Program('foo', 'foo.c') - - o = opt.Object('foo-opt', 'foo.c') - opt.Program(o) - - d = dbg.Object('foo-dbg', 'foo.c') - dbg.Program(d) - </file> - <file name="foo.c"> - int main() { } - </file> - </scons_example> - - <para> - - Then our output would look like: - - </para> - - <scons_output example="ex5"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Replacing Values: the &Replace; Method</title> - - <para> - - You can replace existing construction variable values - using the &Replace; method: - - </para> - - <scons_example name="Replace1"> - <file name="SConstruct" printme="1"> - env = Environment(CCFLAGS = '-DDEFINE1') - env.Replace(CCFLAGS = '-DDEFINE2') - env.Program('foo.c') - </file> - <file name="foo.c"> - int main() { } - </file> - </scons_example> - - <para> - - The replacing value - (<literal>-DDEFINE2</literal> in the above example) - completely replaces the value in the - construction environment: - - </para> - - <scons_output example="Replace1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - You can safely call &Replace; - for construction variables that - don't exist in the construction environment: - - </para> - - <scons_example name="Replace-nonexistent"> - <file name="SConstruct" printme="1"> - env = Environment() - env.Replace(NEW_VARIABLE = 'xyzzy') - print "NEW_VARIABLE =", env['NEW_VARIABLE'] - </file> - </scons_example> - - <para> - - In this case, - the construction variable simply - gets added to the construction environment: - - </para> - - <scons_output example="Replace-nonexistent"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Because the variables - aren't expanded until the construction environment - is actually used to build the targets, - and because &SCons; function and method calls - are order-independent, - the last replacement "wins" - and is used to build all targets, - regardless of the order in which - the calls to Replace() are - interspersed with calls to - builder methods: - - </para> - - <scons_example name="Replace2"> - <file name="SConstruct" printme="1"> - env = Environment(CCFLAGS = '-DDEFINE1') - print "CCFLAGS =", env['CCFLAGS'] - env.Program('foo.c') - - env.Replace(CCFLAGS = '-DDEFINE2') - print "CCFLAGS =", env['CCFLAGS'] - env.Program('bar.c') - </file> - <file name="foo.c"> - int main() { } - </file> - <file name="bar.c"> - int main() { } - </file> - </scons_example> - - <para> - - The timing of when the replacement - actually occurs relative - to when the targets get built - becomes apparent - if we run &scons; without the <literal>-Q</literal> - option: - - </para> - - <scons_output example="Replace2"> - <scons_output_command>scons</scons_output_command> - </scons_output> - - <para> - - Because the replacement occurs while - the &SConscript; files are being read, - the &cv-link-CCFLAGS; - variable has already been set to - <literal>-DDEFINE2</literal> - by the time the &foo_o; target is built, - even though the call to the &Replace; - method does not occur until later in - the &SConscript; file. - - </para> - - </section> - - <section> - <title>Setting Values Only If They're Not Already Defined: the &SetDefault; Method</title> - - <para> - - Sometimes it's useful to be able to specify - that a construction variable should be - set to a value only if the construction environment - does not already have that variable defined - You can do this with the &SetDefault; method, - which behaves similarly to the <function>set_default</function> - method of Python dictionary objects: - - </para> - - <sconstruct> - env.SetDefault(SPECIAL_FLAG = '-extra-option') - </sconstruct> - - <para> - - This is especially useful - when writing your own <literal>Tool</literal> modules - to apply variables to construction environments. - <!-- - See <xref linkend="chap-tool-modules"></xref> - for more information about writing - Tool modules. - --> - - </para> - - </section> - - <section> - <title>Appending to the End of Values: the &Append; Method</title> - - <para> - - You can append a value to - an existing construction variable - using the &Append; method: - - </para> - - <scons_example name="ex8"> - <file name="SConstruct" printme="1"> - env = Environment(CCFLAGS = ['-DMY_VALUE']) - env.Append(CCFLAGS = ['-DLAST']) - env.Program('foo.c') - </file> - <file name="foo.c"> - int main() { } - </file> - </scons_example> - - <para> - - &SCons; then supplies both the <literal>-DMY_VALUE</literal> and - <literal>-DLAST</literal> flags when compiling the object file: - - </para> - - <scons_output example="ex8"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - If the construction variable doesn't already exist, - the &Append; method will create it: - - </para> - - <scons_example name="Append-nonexistent"> - <file name="SConstruct" printme="1"> - env = Environment() - env.Append(NEW_VARIABLE = 'added') - print "NEW_VARIABLE =", env['NEW_VARIABLE'] - </file> - </scons_example> - - <para> - - Which yields: - - </para> - - <scons_output example="Append-nonexistent"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Note that the &Append; function tries to be "smart" - about how the new value is appended to the old value. - If both are strings, the previous and new strings - are simply concatenated. - Similarly, if both are lists, - the lists are concatenated. - If, however, one is a string and the other is a list, - the string is added as a new element to the list. - - </para> - - </section> - - <section> - <title>Appending Unique Values: the &AppendUnique; Method</title> - - <para> - - Some times it's useful to add a new value - only if the existing construction variable - doesn't already contain the value. - This can be done using the &AppendUnique; method: - - </para> - - <sconstruct> - env.AppendUnique(CCFLAGS=['-g']) - </sconstruct> - - <para> - - In the above example, - the <literal>-g</literal> would be added - only if the &cv-CCFLAGS; variable - does not already contain a <literal>-g</literal> value. - - </para> - - </section> - - <section> - <title>Appending to the Beginning of Values: the &Prepend; Method</title> - - <para> - - You can append a value to the beginning of - an existing construction variable - using the &Prepend; method: - - </para> - - <scons_example name="ex9"> - <file name="SConstruct" printme="1"> - env = Environment(CCFLAGS = ['-DMY_VALUE']) - env.Prepend(CCFLAGS = ['-DFIRST']) - env.Program('foo.c') - </file> - <file name="foo.c"> - int main() { } - </file> - </scons_example> - - <para> - - &SCons; then supplies both the <literal>-DFIRST</literal> and - <literal>-DMY_VALUE</literal> flags when compiling the object file: - - </para> - - <scons_output example="ex9"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - If the construction variable doesn't already exist, - the &Prepend; method will create it: - - </para> - - <scons_example name="Prepend-nonexistent"> - <file name="SConstruct" printme="1"> - env = Environment() - env.Prepend(NEW_VARIABLE = 'added') - print "NEW_VARIABLE =", env['NEW_VARIABLE'] - </file> - </scons_example> - - <para> - - Which yields: - - </para> - - <scons_output example="Prepend-nonexistent"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Like the &Append; function, - the &Prepend; function tries to be "smart" - about how the new value is appended to the old value. - If both are strings, the previous and new strings - are simply concatenated. - Similarly, if both are lists, - the lists are concatenated. - If, however, one is a string and the other is a list, - the string is added as a new element to the list. - - </para> - - </section> - - <section> - <title>Prepending Unique Values: the &PrependUnique; Method</title> - - <para> - - Some times it's useful to add a new value - to the beginning of a construction variable - only if the existing value - doesn't already contain the to-be-added value. - This can be done using the &PrependUnique; method: - - </para> - - <sconstruct> - env.PrependUnique(CCFLAGS=['-g']) - </sconstruct> - - <para> - - In the above example, - the <literal>-g</literal> would be added - only if the &cv-CCFLAGS; variable - does not already contain a <literal>-g</literal> value. - - </para> - - </section> - - </section> - - <section id="sect-execution-environments"> - <title>Controlling the Execution Environment for Issued Commands</title> - - <para> - - When &SCons; builds a target file, - it does not execute the commands with - the same external environment - that you used to execute &SCons;. - Instead, it uses the dictionary - stored in the &cv-link-ENV; construction variable - as the external environment - for executing commands. - - </para> - - <para> - - The most important ramification of this behavior - is that the &PATH; environment variable, - which controls where the operating system - will look for commands and utilities, - is not the same as in the external environment - from which you called &SCons;. - This means that &SCons; will not, by default, - necessarily find all of the tools - that you can execute from the command line. - - </para> - - <para> - - The default value of the &PATH; environment variable - on a POSIX system - is <literal>/usr/local/bin:/bin:/usr/bin</literal>. - The default value of the &PATH; environment variable - on a Windows system comes from the Windows registry - value for the command interpreter. - 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 &cv-ENV; dictionary - in your construction environment. - - </para> - - <para> - - The simplest way to do this is to initialize explicitly - the value when you create the construction environment; - this is one way to do that: - - </para> - - <sconstruct> - path = ['/usr/local/bin', '/bin', '/usr/bin'] - env = Environment(ENV = {'PATH' : path}) - </sconstruct> - - <para> - - 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 &cv-ENV; and only - set the value of &PATH;, - the most straightforward way is probably: - - </para> - - <sconstruct> - env['ENV']['PATH'] = ['/usr/local/bin', '/bin', '/usr/bin'] - </sconstruct> - - <para> - - Note that &SCons; does allow you to define - the directories in the &PATH; in a string, - separated by the pathname-separator character - for your system (':' on POSIX systems, ';' on Windows): - - </para> - - <sconstruct> - env['ENV']['PATH'] = '/usr/local/bin:/bin:/usr/bin' - </sconstruct> - - <para> - - But doing so makes your &SConscript; file less portable, - (although in this case that may not be a huge concern - since the directories you list are likley system-specific, anyway). - - </para> - - <!-- - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - env = Environment() - env.Command('foo', [], '__ROOT__/usr/bin/printenv.py') - </file> - <file name="__ROOT__/usr/bin/printenv.py" chmod="0755"> - #!/usr/bin/env python - import os - import sys - if len(sys.argv) > 1: - keys = sys.argv[1:] - else: - keys = sorted(os.environ.keys()) - for key in keys: - print " " + key + "=" + os.environ[key] - </file> - </scons_example> - - <para> - - </para> - - <scons_output example="ex1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - --> - - <section> - <title>Propagating &PATH; From the External Environment</title> - - <para> - - You may want to propagate the external &PATH; - to the execution environment for commands. - You do this by initializing the &PATH; - variable with the &PATH; value from - the <literal>os.environ</literal> - dictionary, - which is Python's way of letting you - get at the external environment: - - </para> - - <sconstruct> - import os - env = Environment(ENV = {'PATH' : os.environ['PATH']}) - </sconstruct> - - <para> - - Alternatively, you may find it easier - to just propagate the entire external - environment to the execution environment - for commands. - This is simpler to code than explicity - selecting the &PATH; value: - - </para> - - <sconstruct> - import os - env = Environment(ENV = os.environ) - </sconstruct> - - <para> - - Either of these will guarantee that - &SCons; will be able to execute - any command that you can execute from the command line. - The drawback is that the build can behave - differently if it's run by people with - different &PATH; values in their environment--for example, - if both the <literal>/bin</literal> and - <literal>/usr/local/bin</literal> directories - have different &cc; commands, - then which one will be used to compile programs - will depend on which directory is listed - first in the user's &PATH; variable. - - </para> - - </section> - - <section> - <title>Adding to <varname>PATH</varname> Values in the Execution Environment</title> - - <para> - - One of the most common requirements - for manipulating a variable in the execution environment - is to add one or more custom directories to a search - like the <envar>$PATH</envar> variable on Linux or POSIX systems, - or the <envar>%PATH%</envar> variable on Windows, - so that a locally-installed compiler or other utility - can be found when &SCons; tries to execute it to update a target. - &SCons; provides &PrependENVPath; and &AppendENVPath; functions - to make adding things to execution variables convenient. - You call these functions by specifying the variable - to which you want the value added, - and then value itself. - So to add some <filename>/usr/local</filename> directories - to the <envar>$PATH</envar> and <envar>$LIB</envar> variables, - you might: - - </para> - - <sconstruct> - env = Environment(ENV = os.environ) - env.PrependENVPath('PATH', '/usr/local/bin') - env.AppendENVPath('LIB', '/usr/local/lib') - </sconstruct> - - <para> - - Note that the added values are strings, - and if you want to add multiple directories to - a variable like <envar>$PATH</envar>, - you must include the path separate character - (<literal>:</literal> on Linux or POSIX, - <literal>;</literal> on Windows) - in the string. - - </para> - - </section> - - </section> diff --git a/doc/user/environments.xml b/doc/user/environments.xml index b0a7498..64625f4 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-environments" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Environments</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -466,9 +488,14 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - import os - </programlisting> + <scons_example name="environments_ex1"> + <file name="SConstruct" printme="1"> +import os + </file> + <file name="foo.c"> +int main() { } + </file> + </scons_example> <para> @@ -518,9 +545,9 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment() - </programlisting> + <sconstruct> +env = Environment() + </sconstruct> <para> @@ -550,14 +577,17 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - import os - - env = Environment(CC = 'gcc', - CCFLAGS = '-O2') + <scons_example name="environments_ex1"> + <file name="SConstruct" printme="1"> + env = Environment(CC = 'gcc', + CCFLAGS = '-O2') - env.Program('foo.c') - </programlisting> + env.Program('foo.c') + </file> + <file name="foo.c"> +int main() { } + </file> + </scons_example> <para> @@ -577,11 +607,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons -Q</userinput> - gcc -o foo.o -c -O2 foo.c - gcc -o foo foo.o - </screen> + <scons_output example="environments_ex1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -596,10 +624,12 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment() - print "CC is:", env['CC'] - </programlisting> + <scons_example name="environments_ex6"> + <file name="SConstruct" printme="1"> +env = Environment() +print "CC is:", env['CC'] + </file> + </scons_example> <para> @@ -609,11 +639,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons -Q</userinput> - CC is: cc - scons: `.' is up to date. - </screen> + <scons_output example="environments_ex6" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -625,12 +653,14 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment(FOO = 'foo', BAR = 'bar') - dict = env.Dictionary() - for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']: - print "key = %s, value = %s" % (key, dict[key]) - </programlisting> + <scons_example name="environments_ex6b"> + <file name="SConstruct" printme="1"> +env = Environment(FOO = 'foo', BAR = 'bar') +dict = env.Dictionary() +for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']: + print "key = %s, value = %s" % (key, dict[key]) + </file> + </scons_example> <para> @@ -640,13 +670,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons -Q</userinput> - key = OBJSUFFIX, value = .o - key = LIBSUFFIX, value = .a - key = PROGSUFFIX, value = - scons: `.' is up to date. - </screen> + <scons_output example="environments_ex6b" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -654,13 +680,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - C:\><userinput>scons -Q</userinput> - key = OBJSUFFIX, value = .obj - key = LIBSUFFIX, value = .lib - key = PROGSUFFIX, value = .exe - scons: `.' is up to date. - </screen> + <scons_output example="environments_ex6b" os="win32" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -670,11 +692,11 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment() - for item in sorted(env.Dictionary().items()): - print "construction variable = '%s', value = '%s'" % item - </programlisting> + <sconstruct> +env = Environment() +for item in sorted(env.Dictionary().items()): + print "construction variable = '%s', value = '%s'" % item + </sconstruct> </section> @@ -697,10 +719,10 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment() - print "CC is:", env.subst('$CC') - </programlisting> + <sconstruct> +env = Environment() +print "CC is:", env.subst('$CC') + </sconstruct> <para> @@ -714,10 +736,10 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment(CCFLAGS = '-DFOO') - print "CCCOM is:", env['CCCOM'] - </programlisting> + <sconstruct> +env = Environment(CCFLAGS = '-DFOO') +print "CCCOM is:", env['CCCOM'] + </sconstruct> <para> @@ -728,9 +750,9 @@ environment, of directory names, suffixes, etc. </para> <screen> - % <userinput>scons -Q</userinput> - CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES - scons: `.' is up to date. +% <userinput>scons -Q</userinput> +CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES +scons: `.' is up to date. </screen> <para> @@ -740,10 +762,10 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment(CCFLAGS = '-DFOO') - print "CCCOM is:", env.subst('$CCCOM') - </programlisting> + <sconstruct> +env = Environment(CCFLAGS = '-DFOO') +print "CCCOM is:", env.subst('$CCCOM') + </sconstruct> <para> @@ -755,9 +777,9 @@ environment, of directory names, suffixes, etc. </para> <screen> - % <userinput>scons -Q</userinput> - CCCOM is: gcc -DFOO -c -o - scons: `.' is up to date. +% <userinput>scons -Q</userinput> +CCCOM is: gcc -DFOO -c -o +scons: `.' is up to date. </screen> <para> @@ -781,16 +803,16 @@ environment, of directory names, suffixes, etc. (a null string), and will not cause scons to fail. </para> - <programlisting> - env = Environment() - print "value is:", env.subst( '->$MISSING<-' ) - </programlisting> + <scons_example name="environments_missing1"> + <file name="SConstruct" printme="1"> +env = Environment() +print "value is:", env.subst( '->$MISSING<-' ) + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - value is: -><- - scons: `.' is up to date. - </screen> + <scons_output example="environments_missing1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> This default behaviour can be changed using the &AllowSubstExceptions; @@ -808,18 +830,17 @@ environment, of directory names, suffixes, etc. with no extra arguments. </para> - <programlisting> - AllowSubstExceptions() - env = Environment() - print "value is:", env.subst( '->$MISSING<-' ) - </programlisting> + <scons_example name="environments_missing2"> + <file name="SConstruct" printme="1"> +AllowSubstExceptions() +env = Environment() +print "value is:", env.subst( '->$MISSING<-' ) + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - value is: - scons: *** NameError `MISSING' trying to evaluate `$MISSING' - File "/home/my/project/SConstruct", line 3, in <module> - </screen> + <scons_output example="environments_missing2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> This can also be used to allow other exceptions that might occur, @@ -829,19 +850,17 @@ environment, of directory names, suffixes, etc. allowed </para> - <programlisting> - AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) - env = Environment() - print "value is:", env.subst( '->${1 / 0}<-' ) - </programlisting> + <scons_example name="environments_missing3"> + <file name="SConstruct" printme="1"> +AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) +env = Environment() +print "value is:", env.subst( '->${1 / 0}<-' ) + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - value is: -><- - scons: `.' is up to date. - </screen> - <programlisting> - </programlisting> + <scons_output example="environments_missing3" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> If &AllowSubstExceptions; is called multiple times, each call @@ -881,11 +900,9 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - - DefaultEnvironment(CC = '/usr/local/bin/gcc') - - </programlisting> + <sconstruct> +DefaultEnvironment(CC = '/usr/local/bin/gcc') + </sconstruct> <para> @@ -915,12 +932,10 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - - env = DefaultEnvironment() - env['CC'] = '/usr/local/bin/gcc' - - </programlisting> + <sconstruct> +env = DefaultEnvironment() +env['CC'] = '/usr/local/bin/gcc' + </sconstruct> <para> @@ -944,12 +959,10 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - - env = DefaultEnvironment(tools = ['gcc', 'gnulink'], - CC = '/usr/local/bin/gcc') - - </programlisting> + <sconstruct> +env = DefaultEnvironment(tools = ['gcc', 'gnulink'], + CC = '/usr/local/bin/gcc') + </sconstruct> <para> @@ -982,22 +995,26 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - opt = Environment(CCFLAGS = '-O2') - dbg = Environment(CCFLAGS = '-g') + <scons_example name="environments_ex2"> + <file name="SConstruct" printme="1"> +opt = Environment(CCFLAGS = '-O2') +dbg = Environment(CCFLAGS = '-g') - opt.Program('foo', 'foo.c') +opt.Program('foo', 'foo.c') - dbg.Program('bar', 'bar.c') - </programlisting> +dbg.Program('bar', 'bar.c') + </file> + <file name="foo.c"> +int main() { } + </file> + <file name="bar.c"> +int main() { } + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - cc -o bar.o -c -g bar.c - cc -o bar bar.o - cc -o foo.o -c -O2 foo.c - cc -o foo foo.o - </screen> + <scons_output example="environments_ex2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1009,14 +1026,19 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - opt = Environment(CCFLAGS = '-O2') - dbg = Environment(CCFLAGS = '-g') + <scons_example name="environments_ex3"> + <file name="SConstruct" printme="1"> +opt = Environment(CCFLAGS = '-O2') +dbg = Environment(CCFLAGS = '-g') - opt.Program('foo', 'foo.c') +opt.Program('foo', 'foo.c') - dbg.Program('foo', 'foo.c') - </programlisting> +dbg.Program('foo', 'foo.c') + </file> + <file name="foo.c"> +int main() { } + </file> + </scons_example> <para> @@ -1024,12 +1046,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons -Q</userinput> - - scons: *** Two environments with different actions were specified for the same target: foo.o - File "/home/my/project/SConstruct", line 6, in <module> - </screen> + <scons_output example="environments_ex3" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1052,16 +1071,21 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - opt = Environment(CCFLAGS = '-O2') - dbg = Environment(CCFLAGS = '-g') + <scons_example name="environments_ex4"> + <file name="SConstruct" printme="1"> +opt = Environment(CCFLAGS = '-O2') +dbg = Environment(CCFLAGS = '-g') - o = opt.Object('foo-opt', 'foo.c') - opt.Program(o) +o = opt.Object('foo-opt', 'foo.c') +opt.Program(o) - d = dbg.Object('foo-dbg', 'foo.c') - dbg.Program(d) - </programlisting> +d = dbg.Object('foo-dbg', 'foo.c') +dbg.Program(d) + </file> + <file name="foo.c"> +int main() { } + </file> + </scons_example> <para> @@ -1079,13 +1103,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o foo-dbg.o -c -g foo.c - cc -o foo-dbg foo-dbg.o - cc -o foo-opt.o -c -O2 foo.c - cc -o foo-opt foo-opt.o - </screen> + <scons_output example="environments_ex4" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -1119,19 +1139,24 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment(CC = 'gcc') - opt = env.Clone(CCFLAGS = '-O2') - dbg = env.Clone(CCFLAGS = '-g') + <scons_example name="environments_ex5"> + <file name="SConstruct" printme="1"> +env = Environment(CC = 'gcc') +opt = env.Clone(CCFLAGS = '-O2') +dbg = env.Clone(CCFLAGS = '-g') - env.Program('foo', 'foo.c') +env.Program('foo', 'foo.c') - o = opt.Object('foo-opt', 'foo.c') - opt.Program(o) +o = opt.Object('foo-opt', 'foo.c') +opt.Program(o) - d = dbg.Object('foo-dbg', 'foo.c') - dbg.Program(d) - </programlisting> +d = dbg.Object('foo-dbg', 'foo.c') +dbg.Program(d) + </file> + <file name="foo.c"> +int main() { } + </file> + </scons_example> <para> @@ -1139,15 +1164,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons -Q</userinput> - gcc -o foo.o -c foo.c - gcc -o foo foo.o - gcc -o foo-dbg.o -c -g foo.c - gcc -o foo-dbg foo-dbg.o - gcc -o foo-opt.o -c -O2 foo.c - gcc -o foo-opt foo-opt.o - </screen> + <scons_output example="environments_ex5" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -1161,11 +1180,16 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment(CCFLAGS = '-DDEFINE1') - env.Replace(CCFLAGS = '-DDEFINE2') - env.Program('foo.c') - </programlisting> + <scons_example name="environments_Replace1"> + <file name="SConstruct" printme="1"> +env = Environment(CCFLAGS = '-DDEFINE1') +env.Replace(CCFLAGS = '-DDEFINE2') +env.Program('foo.c') + </file> + <file name="foo.c"> +int main() { } + </file> + </scons_example> <para> @@ -1176,11 +1200,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o foo.o -c -DDEFINE2 foo.c - cc -o foo foo.o - </screen> + <scons_output example="environments_Replace1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1190,11 +1212,13 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment() - env.Replace(NEW_VARIABLE = 'xyzzy') - print "NEW_VARIABLE =", env['NEW_VARIABLE'] - </programlisting> + <scons_example name="environments_Replace-nonexistent"> + <file name="SConstruct" printme="1"> +env = Environment() +env.Replace(NEW_VARIABLE = 'xyzzy') +print "NEW_VARIABLE =", env['NEW_VARIABLE'] + </file> + </scons_example> <para> @@ -1204,11 +1228,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons -Q</userinput> - NEW_VARIABLE = xyzzy - scons: `.' is up to date. - </screen> + <scons_output example="environments_Replace-nonexistent" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1226,15 +1248,23 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment(CCFLAGS = '-DDEFINE1') - print "CCFLAGS =", env['CCFLAGS'] - env.Program('foo.c') - - env.Replace(CCFLAGS = '-DDEFINE2') - print "CCFLAGS =", env['CCFLAGS'] - env.Program('bar.c') - </programlisting> + <scons_example name="environments_Replace2"> + <file name="SConstruct" printme="1"> +env = Environment(CCFLAGS = '-DDEFINE1') +print "CCFLAGS =", env['CCFLAGS'] +env.Program('foo.c') + +env.Replace(CCFLAGS = '-DDEFINE2') +print "CCFLAGS =", env['CCFLAGS'] +env.Program('bar.c') + </file> + <file name="foo.c"> +int main() { } + </file> + <file name="bar.c"> +int main() { } + </file> + </scons_example> <para> @@ -1247,19 +1277,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - CCFLAGS = -DDEFINE1 - CCFLAGS = -DDEFINE2 - scons: done reading SConscript files. - scons: Building targets ... - cc -o bar.o -c -DDEFINE2 bar.c - cc -o bar bar.o - cc -o foo.o -c -DDEFINE2 foo.c - cc -o foo foo.o - scons: done building targets. - </screen> + <scons_output example="environments_Replace2" suffix="1"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -1292,9 +1312,9 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env.SetDefault(SPECIAL_FLAG = '-extra-option') - </programlisting> + <sconstruct> +env.SetDefault(SPECIAL_FLAG = '-extra-option') + </sconstruct> <para> @@ -1322,11 +1342,16 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment(CCFLAGS = ['-DMY_VALUE']) - env.Append(CCFLAGS = ['-DLAST']) - env.Program('foo.c') - </programlisting> + <scons_example name="environments_ex8"> + <file name="SConstruct" printme="1"> +env = Environment(CCFLAGS = ['-DMY_VALUE']) +env.Append(CCFLAGS = ['-DLAST']) +env.Program('foo.c') + </file> + <file name="foo.c"> +int main() { } + </file> + </scons_example> <para> @@ -1335,11 +1360,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o foo.o -c -DMY_VALUE -DLAST foo.c - cc -o foo foo.o - </screen> + <scons_output example="environments_ex8" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1348,11 +1371,13 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment() - env.Append(NEW_VARIABLE = 'added') - print "NEW_VARIABLE =", env['NEW_VARIABLE'] - </programlisting> + <scons_example name="environments_Append-nonexistent"> + <file name="SConstruct" printme="1"> +env = Environment() +env.Append(NEW_VARIABLE = 'added') +print "NEW_VARIABLE =", env['NEW_VARIABLE'] + </file> + </scons_example> <para> @@ -1360,11 +1385,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons -Q</userinput> - NEW_VARIABLE = added - scons: `.' is up to date. - </screen> + <scons_output example="environments_Append-nonexistent" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1393,9 +1416,9 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env.AppendUnique(CCFLAGS=['-g']) - </programlisting> + <sconstruct> +env.AppendUnique(CCFLAGS=['-g']) + </sconstruct> <para> @@ -1419,11 +1442,16 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment(CCFLAGS = ['-DMY_VALUE']) - env.Prepend(CCFLAGS = ['-DFIRST']) - env.Program('foo.c') - </programlisting> + <scons_example name="environments_ex9"> + <file name="SConstruct" printme="1"> +env = Environment(CCFLAGS = ['-DMY_VALUE']) +env.Prepend(CCFLAGS = ['-DFIRST']) +env.Program('foo.c') + </file> + <file name="foo.c"> +int main() { } + </file> + </scons_example> <para> @@ -1432,11 +1460,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o foo.o -c -DFIRST -DMY_VALUE foo.c - cc -o foo foo.o - </screen> + <scons_output example="environments_ex9" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1445,11 +1471,13 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment() - env.Prepend(NEW_VARIABLE = 'added') - print "NEW_VARIABLE =", env['NEW_VARIABLE'] - </programlisting> + <scons_example name="environments_Prepend-nonexistent"> + <file name="SConstruct" printme="1"> +env = Environment() +env.Prepend(NEW_VARIABLE = 'added') +print "NEW_VARIABLE =", env['NEW_VARIABLE'] + </file> + </scons_example> <para> @@ -1457,11 +1485,9 @@ environment, of directory names, suffixes, etc. </para> - <screen> - % <userinput>scons -Q</userinput> - NEW_VARIABLE = added - scons: `.' is up to date. - </screen> + <scons_output example="environments_Prepend-nonexistent" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1492,9 +1518,9 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env.PrependUnique(CCFLAGS=['-g']) - </programlisting> + <sconstruct> +env.PrependUnique(CCFLAGS=['-g']) + </sconstruct> <para> @@ -1563,10 +1589,10 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - path = ['/usr/local/bin', '/bin', '/usr/bin'] - env = Environment(ENV = {'PATH' : path}) - </programlisting> + <sconstruct> +path = ['/usr/local/bin', '/bin', '/usr/bin'] +env = Environment(ENV = {'PATH' : path}) + </sconstruct> <para> @@ -1583,9 +1609,9 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env['ENV']['PATH'] = ['/usr/local/bin', '/bin', '/usr/bin'] - </programlisting> + <sconstruct> +env['ENV']['PATH'] = ['/usr/local/bin', '/bin', '/usr/bin'] + </sconstruct> <para> @@ -1596,9 +1622,9 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env['ENV']['PATH'] = '/usr/local/bin:/bin:/usr/bin' - </programlisting> + <sconstruct> +env['ENV']['PATH'] = '/usr/local/bin:/bin:/usr/bin' + </sconstruct> <para> @@ -1610,21 +1636,21 @@ environment, of directory names, suffixes, etc. <!-- - <scons_example name="ex1"> + <scons_example name="environments_ex1"> <file name="SConstruct" printme="1"> - env = Environment() - env.Command('foo', [], '__ROOT__/usr/bin/printenv.py') +env = Environment() +env.Command('foo', [], '__ROOT__/usr/bin/printenv.py') </file> <file name="__ROOT__/usr/bin/printenv.py" chmod="0755"> - #!/usr/bin/env python - import os - import sys - if len(sys.argv) > 1: - keys = sys.argv[1:] - else: - keys = sorted(os.environ.keys()) - for key in keys: - print " " + key + "=" + os.environ[key] +#!/usr/bin/env python +import os +import sys +if len(sys.argv) > 1: + keys = sys.argv[1:] +else: + keys = sorted(os.environ.keys()) +for key in keys: + print " " + key + "=" + os.environ[key] </file> </scons_example> @@ -1632,7 +1658,7 @@ environment, of directory names, suffixes, etc. </para> - <scons_output example="ex1"> + <scons_output example="environments_ex1" suffix="2"> <scons_output_command>scons -Q</scons_output_command> </scons_output> @@ -1654,10 +1680,10 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - import os - env = Environment(ENV = {'PATH' : os.environ['PATH']}) - </programlisting> + <sconstruct> +import os +env = Environment(ENV = {'PATH' : os.environ['PATH']}) + </sconstruct> <para> @@ -1670,10 +1696,10 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - import os - env = Environment(ENV = os.environ) - </programlisting> + <sconstruct> +import os +env = Environment(ENV = os.environ) + </sconstruct> <para> @@ -1717,11 +1743,11 @@ environment, of directory names, suffixes, etc. </para> - <programlisting> - env = Environment(ENV = os.environ) - env.PrependENVPath('PATH', '/usr/local/bin') - env.AppendENVPath('LIB', '/usr/local/lib') - </programlisting> + <sconstruct> +env = Environment(ENV = os.environ) +env.PrependENVPath('PATH', '/usr/local/bin') +env.AppendENVPath('LIB', '/usr/local/lib') + </sconstruct> <para> @@ -1738,3 +1764,5 @@ environment, of directory names, suffixes, etc. </section> </section> + +</chapter> diff --git a/doc/user/epub.css b/doc/user/epub.css new file mode 100644 index 0000000..31cebe5 --- /dev/null +++ b/doc/user/epub.css @@ -0,0 +1,33 @@ +/* This defines styles and classes used in the book */ +body { } +code { font-family: monospace; } +h1, h2, h3, h4, h5, h6 { text-align: center; margin-bottom:2em;} +h1.title { } +h2.author { } +p{ + padding:0; + margin:0; + text-indent:2em; +} +blockquote{ + margin-left:3em; + margin-right:3em; +} +.caption{ + text-align:center; + font-style:italic; + margin-bottom:1em; + margin-top:.2em; + font-size:.8em; +} +blockquote > p{ + text-indent:0; + margin-bottom:1em; +} +img{ + display:block; + margin-left: auto; + margin-right: auto; + text-align:center; + margin-top:1em; +} diff --git a/doc/user/example.in b/doc/user/epub.xsl index 9e8078c..ecc5c8b 100644 --- a/doc/user/example.in +++ b/doc/user/epub.xsl @@ -1,41 +1,36 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - XXX - - </para> - - <section> - <title>XXX</title> - - <para> - - XXX - - </para> - - </section> +<?xml version='1.0'?>
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation
+
+ 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.
+
+-->
+<xsl:stylesheet
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ version="1.0">
+
+ <xsl:import href="../../src/engine/SCons/Tool/docbook/docbook-xsl-1.76.1/epub/docbook.xsl"/>
+
+<xsl:param name="html.stylesheet" select="'epub.css'"/>
+
+</xsl:stylesheet>
+
diff --git a/doc/user/errors.xml b/doc/user/errors.xml index 9e8078c..174d4b7 100644 --- a/doc/user/errors.xml +++ b/doc/user/errors.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-errors" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Errors</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -39,3 +61,4 @@ </para> </section> +</chapter> diff --git a/doc/user/example.xml b/doc/user/example.xml index 9e8078c..0165b95 100644 --- a/doc/user/example.xml +++ b/doc/user/example.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<appendix id="app-example" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Complex &SCons; Example</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -39,3 +61,5 @@ </para> </section> + +</appendix> diff --git a/doc/user/factories.in b/doc/user/factories.in deleted file mode 100644 index 146f695..0000000 --- a/doc/user/factories.in +++ /dev/null @@ -1,507 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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 don't have a suitable pre-existing builder. - <footnote> - <para> - Unfortunately, in the early days of SCons design, - we used the name &Copy; for the function that - returns a copy of the environment, - otherwise that would be the logical choice for - a Builder that copies a file or directory tree - to a target location. - </para> - </footnote> - 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-link-TARGET; and &cv-link-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> - - Which 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-link-TARGET; and &cv-link-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> - - <para> - - One word of caution about using the &Delete; factory: - it has the same variable expansions available - as any other factory, including the &cv-SOURCE; variable. - Specifying <literal>Delete("$SOURCE")</literal> - is not something you usually want to do! - - </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 use: - - </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("$TARGET", "$SOURCE"), - Touch("$TARGET"), - ]) - </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> - </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 use: - - </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 using 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> - - <para> - - The &Execute; function returns the exit status - or return value of the underlying action being executed. - It will also print an error message if the action - fails and returns a non-zero value. - &SCons; will <emphasis>not</emphasis>, however, - actually stop the build if the action fails. - If you want the build to stop - in response to a failure in an action called by &Execute;, - you must do so by explicitly - checking the return value - and calling the &Exit; function - (or a Python equivalent): - - </para> - - <sconstruct> - if Execute(Mkdir('__ROOT__/tmp/my_temp_directory')): - # A problem occurred while making the temp directory. - Exit(1) - </sconstruct> - - </section> diff --git a/doc/user/factories.xml b/doc/user/factories.xml index ced0229..806e36b 100644 --- a/doc/user/factories.xml +++ b/doc/user/factories.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-factories" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Platform-Independent File System Manipulation</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -60,9 +82,12 @@ </para> - <programlisting> - Command("file.out", "file.in", Copy("$TARGET", "$SOURCE")) - </programlisting> + <scons_example name="factories_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> @@ -75,10 +100,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - Copy("file.out", "file.in") - </screen> + <scons_output example="factories_Copy1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -87,9 +111,12 @@ </para> - <programlisting> - Command("file.out", [], Copy("$TARGET", "file.in")) - </programlisting> + <scons_example name="factories_Copy2"> + <file name="SConstruct" printme="1"> +Command("file.out", [], Copy("$TARGET", "file.in")) + </file> + <file name="file.in">file.in</file> + </scons_example> <para> @@ -97,10 +124,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - Copy("file.out", "file.in") - </screen> + <scons_output example="factories_Copy2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -119,14 +145,26 @@ </para> - <programlisting> - Command("file.out", "file.in", - [ - Copy("tempfile", "$SOURCE"), - "modify tempfile", - Copy("$TARGET", "tempfile"), - ]) - </programlisting> + <scons_example name="factories_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> @@ -134,12 +172,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - Copy("tempfile", "file.in") - modify tempfile - Copy("file.out", "tempfile") - </screen> + <scons_output example="factories_Copy3" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -161,15 +196,27 @@ </para> - <programlisting> - Command("file.out", "file.in", - [ - Delete("tempfile"), - Copy("tempfile", "$SOURCE"), - "modify tempfile", - Copy("$TARGET", "tempfile"), - ]) - </programlisting> + <scons_example name="factories_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> @@ -177,13 +224,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - Delete("tempfile") - Copy("tempfile", "file.in") - modify tempfile - Copy("file.out", "tempfile") - </screen> + <scons_output example="factories_Delete1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -194,13 +237,16 @@ </para> - <programlisting> - Command("file.out", "file.in", - [ - Delete("$TARGET"), - Copy("$TARGET", "$SOURCE") - ]) - </programlisting> + <scons_example name="factories_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> @@ -208,11 +254,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - Delete("file.out") - Copy("file.out", "file.in") - </screen> + <scons_output example="factories_Delete2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -247,14 +291,26 @@ </para> - <programlisting> - Command("file.out", "file.in", - [ - Copy("tempfile", "$SOURCE"), - "modify tempfile", - Move("$TARGET", "tempfile"), - ]) - </programlisting> + <scons_example name="factories_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> @@ -262,12 +318,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - Copy("tempfile", "file.in") - modify tempfile - Move("file.out", "tempfile") - </screen> + <scons_output example="factories_Move" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -282,13 +335,22 @@ </para> - <programlisting> - Command("file.out", "file.in", - [ - Copy("$TARGET", "$SOURCE"), - Touch("$TARGET"), - ]) - </programlisting> + <scons_example name="factories_Touch"> + <file name="S" printme="1"> +Command("file.out", "file.in", + [ + Copy("$TARGET", "$SOURCE"), + Touch("$TARGET"), + ]) + </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> + </scons_example> <para> @@ -296,11 +358,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - Copy("file.out", "file.in") - Touch("file.out") - </screen> + <scons_output example="factories_Touch" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -319,17 +379,29 @@ </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> + <scons_example name="factories_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> @@ -337,15 +409,9 @@ </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] tempdir/output_file: No such file or directory - </screen> + <scons_output example="factories_Mkdir" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -363,13 +429,16 @@ </para> - <programlisting> - Command("file.out", "file.in", - [ - Copy("$TARGET", "$SOURCE"), - Chmod("$TARGET", 0755), - ]) - </programlisting> + <scons_example name="factories_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> @@ -377,11 +446,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - Copy("file.out", "file.in") - Chmod("file.out", 0755) - </screen> + <scons_output example="factories_Chmod" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -401,9 +468,11 @@ </para> - <programlisting> - Execute(Mkdir('/tmp/my_temp_directory')) - </programlisting> + <scons_example name="factories_Execute"> + <file name="SConstruct" printme="1"> +Execute(Mkdir('__ROOT__/tmp/my_temp_directory')) + </file> + </scons_example> <para> @@ -413,15 +482,9 @@ </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> + <scons_output example="factories_Execute" suffix="1"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -457,10 +520,12 @@ </para> - <programlisting> - if Execute(Mkdir('/tmp/my_temp_directory')): - # A problem occurred while making the temp directory. - Exit(1) - </programlisting> + <sconstruct> +if Execute(Mkdir('__ROOT__/tmp/my_temp_directory')): + # A problem occurred while making the temp directory. + Exit(1) + </sconstruct> </section> + +</chapter> diff --git a/doc/user/file-removal.in b/doc/user/file-removal.in deleted file mode 100644 index 479530c..0000000 --- a/doc/user/file-removal.in +++ /dev/null @@ -1,223 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - There are two occasions when &SCons; will, - by default, remove target files. - The first is when &SCons; determines that - an target file needs to be rebuilt - and removes the existing version of the target - before executing - The second is when &SCons; is invoked with the - <literal>-c</literal> option to "clean" - a tree of its built targets. - - These behaviours can be suppressed with the - &Precious; and &NoClean; functions, respectively. - - </para> - - <section> - <title>Preventing target removal during build: the &Precious; Function</title> - - <para> - - By default, &SCons; removes targets before building them. - Sometimes, however, this is not what you want. - For example, you may want to update a library incrementally, - not by having it deleted and then rebuilt from all - of the constituent object files. - In such cases, you can use the - &Precious; method to prevent - &SCons; from removing the target before it is built: - - </para> - - <scons_example name="precious-ex1"> - <file name="SConstruct" printme="1"> - env = Environment(RANLIBCOM='') - lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) - env.Precious(lib) - </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> - - Although the output doesn't look any different, - &SCons; does not, in fact, - delete the target library before rebuilding it: - - </para> - - <scons_output example="precious-ex1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - &SCons; will, however, still delete files marked as &Precious; - when the <literal>-c</literal> option is used. - - </para> - - </section> - - <section> - <title>Preventing target removal during clean: the &NoClean; Function</title> - - <para> - - By default, &SCons; removes all built targets when invoked - with the <literal>-c</literal> option to clean a source tree - of built targets. - Sometimes, however, this is not what you want. - For example, you may want to remove only intermediate generated files - (such as object files), - but leave the final targets - (the libraries) - untouched. - - In such cases, you can use the &NoClean; method to prevent &SCons; - from removing a target during a clean: - - </para> - - <scons_example name="noclean-ex1"> - <file name="SConstruct" printme="1"> - env = Environment(RANLIBCOM='') - lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) - env.NoClean(lib) - </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> - - Notice that the <filename>libfoo.a</filename> - is not listed as a removed file: - - </para> - - <scons_output example="noclean-ex1"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -c</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Removing additional files during clean: the &Clean; Function</title> - - <para> - - There may be additional files that you want removed - when the <literal>-c</literal> option is used, - but which &SCons; doesn't know about - because they're not normal target files. - For example, perhaps a command you invoke - creates a log file as - part of building the target file you want. - You would like the log file cleaned, - but you don't want to have to teach - SCons that the command - "builds" two files. - - </para> - - <para> - - You can use the &Clean; function to arrange for additional files - to be removed when the <literal>-c</literal> option is used. - Notice, however, that the &Clean; function takes two arguments, - and the <emphasis>second</emphasis> argument - is the name of the additional file you want cleaned - (<filename>foo.log</filename> in this example): - - </para> - - <scons_example name="clean-ex1"> - <file name="S" printme="1"> - t = Command('foo.out', 'foo.in', 'build -o $TARGET $SOURCE') - Clean(t, 'foo.log') - </file> - <file name="SConstruct"> - env = DefaultEnvironment() - import os - env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() - SConscript('S') - </file> - <file name="foo.in"> - foo.in - </file> - <file name="foo.log"> - foo.log - </file> - <file name="build" chmod="0755"> - cat $3 > $2 - </file> - </scons_example> - - <para> - - The first argument is the target with which you want - the cleaning of this additional file associated. - In the above example, - we've used the return value from the - &Command; function, - which represents the - <filename>foo.out</filename> - target. - Now whenever the - <filename>foo.out</filename> target is cleaned - by the <literal>-c</literal> option, - the <filename>foo.log</filename> file - will be removed as well: - - </para> - - <scons_output example="clean-ex1"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q -c</scons_output_command> - </scons_output> - - </section> diff --git a/doc/user/file-removal.xml b/doc/user/file-removal.xml index f2730c1..1b58abe 100644 --- a/doc/user/file-removal.xml +++ b/doc/user/file-removal.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-file-removal" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Controlling Removal of Targets</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -56,11 +78,22 @@ </para> - <programlisting> - env = Environment(RANLIBCOM='') - lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) - env.Precious(lib) - </programlisting> + <scons_example name="fileremoval_precious-ex1"> + <file name="SConstruct" printme="1"> + env = Environment(RANLIBCOM='') + lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) + env.Precious(lib) + </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> @@ -70,13 +103,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o f1.o -c f1.c - cc -o f2.o -c f2.c - cc -o f3.o -c f3.c - ar rc libfoo.a f1.o f2.o f3.o - </screen> + <scons_output example="fileremoval_precious-ex1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -107,11 +136,22 @@ </para> - <programlisting> - env = Environment(RANLIBCOM='') - lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) - env.NoClean(lib) - </programlisting> + <scons_example name="fileremoval_noclean-ex1"> + <file name="SConstruct" printme="1"> +env = Environment(RANLIBCOM='') +lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) +env.NoClean(lib) + </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> @@ -120,21 +160,10 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o f1.o -c f1.c - cc -o f2.o -c f2.c - cc -o f3.o -c f3.c - ar rc libfoo.a f1.o f2.o f3.o - % <userinput>scons -c</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Cleaning targets ... - Removed f1.o - Removed f2.o - Removed f3.o - scons: done cleaning targets. - </screen> + <scons_output example="fileremoval_noclean-ex1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -c</scons_output_command> + </scons_output> </section> @@ -168,10 +197,27 @@ </para> - <programlisting> - t = Command('foo.out', 'foo.in', 'build -o $TARGET $SOURCE') - Clean(t, 'foo.log') - </programlisting> + <scons_example name="fileremoval_clean-ex1"> + <file name="S" printme="1"> +t = Command('foo.out', 'foo.in', 'build -o $TARGET $SOURCE') +Clean(t, 'foo.log') + </file> + <file name="SConstruct"> +env = DefaultEnvironment() +import os +env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() +SConscript('S') + </file> + <file name="foo.in"> +foo.in + </file> + <file name="foo.log"> +foo.log + </file> + <file name="build" chmod="0755"> +cat $3 > $2 + </file> + </scons_example> <para> @@ -191,12 +237,11 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - build -o foo.out foo.in - % <userinput>scons -Q -c</userinput> - Removed foo.out - Removed foo.log - </screen> + <scons_output example="fileremoval_clean-ex1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c</scons_output_command> + </scons_output> </section> + +</chapter> diff --git a/doc/user/functions.in b/doc/user/functions.in deleted file mode 100644 index e7d633d..0000000 --- a/doc/user/functions.in +++ /dev/null @@ -1,38 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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 -function and construction environment methods -in this version of &SCons; - -</para> - -<variablelist> - -&functions-gen; - -</variablelist> diff --git a/doc/user/functions.xml b/doc/user/functions.xml index e7d633d..76a3449 100644 --- a/doc/user/functions.xml +++ b/doc/user/functions.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<appendix id="app-functions" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Functions and Environment Methods</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -31,8 +52,6 @@ in this version of &SCons; </para> -<variablelist> - -&functions-gen; +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../generated/functions.gen"/> -</variablelist> +</appendix> diff --git a/doc/user/gettext.in b/doc/user/gettext.in deleted file mode 100644 index 529ea22..0000000 --- a/doc/user/gettext.in +++ /dev/null @@ -1,351 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - The &t-link-gettext; toolset supports internationalization and localization - of SCons-based projects. Builders provided by &t-link-gettext; automatize - generation and updates of translation files. You can manage translations and - translation templates similarly to how it's done with autotools. - </para> - - <section> - <title>Prerequisites</title> - <para> - To follow examples provided in this chapter set up your operating system to - support two or more languages. In following examples we use locales - <literal>en_US</literal>, <literal>de_DE</literal>, and - <literal>pl_PL</literal>. - </para> - - <para> - Ensure, that you have <ulink - url="http://www.gnu.org/software/gettext/manual/gettext.html">GNU gettext - utilities</ulink> installed on your system. - </para> - - <para> - To edit translation files you may wish to install <ulink - url="http://www.poedit.net/">poedit</ulink> editor. - </para> - </section> - - <section> - <title>Simple project</title> - <para> - Let's start with a very simple project, the "Hello world" program - for example - <scons_example name="ex1"> - <file name="hello.c" printme="1"> - /* hello.c */ - #include <stdio.h> - int main(int argc, char* argv[]) - { - printf("Hello world\n"); - return 0; - } - </file> - </scons_example> - - Prepare a <filename>SConstruct</filename> to compile the program - as usual. - <scons_example name="ex2"> - <file name="SConstruct" printme="1"> - # SConstruct - env = Environment() - hello = Program(["hello.c"]) - </file> - </scons_example> - </para> - - <para> - Now we'll convert the project to a multi-lingual one. If you don't - already have <ulink - url="http://www.gnu.org/software/gettext/manual/gettext.html">GNU gettext - utilities</ulink> installed, install them from your preffered - package repository, or download from <ulink - url="http://ftp.gnu.org/gnu/gettext/"> - http://ftp.gnu.org/gnu/gettext/</ulink>. For the purpose of this example, - you should have following three locales installed on your system: - <literal>en_US</literal>, <literal>de_DE</literal> and - <literal>pl_PL</literal>. On debian, for example, you may enable certain - locales through <command>dpkg-reconfigure locales</command>. - </para> - - <para> - First prepare the <filename>hello.c</filename> program for - internationalization. Change the previous code so it reads as follows: - <scons_example name="ex3"> - <file name="hello.c" printme="1"> - /* hello.c */ - #include <stdio.h> - #include <libintl.h> - #include <locale.h> - int main(int argc, char* argv[]) - { - bindtextdomain("hello", "locale"); - setlocale(LC_ALL, ""); - textdomain("hello"); - printf(gettext("Hello world\n")); - return 0; - } - </file> - </scons_example> - Detailed recipes for such conversion can - be found at <ulink - url="http://www.gnu.org/software/gettext/manual/gettext.html#Sources"> - http://www.gnu.org/software/gettext/manual/gettext.html#Sources</ulink>. - The <function>gettext("...")</function> has two purposes. - First, it marks messages for the <command>xgettext(1)</command> program, which - we will use to extract from the sources the messages for localization. - Second, it calls the <literal>gettext</literal> library internals to - translate the message at runtime. - </para> - - <para> - Now we shall instruct SCons how to generate and maintain translation files. - For that, use the &b-link-Translate; builder and &b-link-MOFiles; builder. - The first one takes source files, extracts internationalized - messages from them, creates so-called <literal>POT</literal> file - (translation template), and then creates <literal>PO</literal> translation - files, one for each requested language. Later, during the development - lifecycle, the builder keeps all these files up-to date. The - &b-link-MOFiles; builder compiles the <literal>PO</literal> files to binary - form. Then install the <literal>MO</literal> files under directory - called <filename>locale</filename>. - </para> - - <para> The completed - <filename>SConstruct</filename> is as follows: - <scons_example name="ex4"> - <file name="SConstruct" printme="1"> - # SConstruct - env = Environment( tools = ['default', 'gettext'] ) - hello = env.Program(["hello.c"]) - env['XGETTEXTFLAGS'] = [ - '--package-name=%s' % 'hello', - '--package-version=%s' % '1.0', - ] - po = env.Translate(["pl","en", "de"], ["hello.c"], POAUTOINIT = 1) - mo = env.MOFiles(po) - InstallAs(["locale/en/LC_MESSAGES/hello.mo"], ["en.mo"]) - InstallAs(["locale/pl/LC_MESSAGES/hello.mo"], ["pl.mo"]) - InstallAs(["locale/de/LC_MESSAGES/hello.mo"], ["de.mo"]) - </file> - </scons_example> - </para> - <para> - Generate the translation files with <command>scons po-update</command>. - You should see the output from SCons simillar to this: - <screen> - user@host:$ scons po-update - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - Entering '/home/ptomulik/projects/tmp' - xgettext --package-name=hello --package-version=1.0 -o - hello.c - Leaving '/home/ptomulik/projects/tmp' - Writting 'messages.pot' (new file) - msginit --no-translator -l pl -i messages.pot -o pl.po - Created pl.po. - msginit --no-translator -l en -i messages.pot -o en.po - Created en.po. - msginit --no-translator -l de -i messages.pot -o de.po - Created de.po. - scons: done building targets. - </screen> - </para> - - <para> - If everything is right, you should see following new files. - <screen> - user@host:$ ls *.po* - de.po en.po messages.pot pl.po - </screen> - </para> - - <para> - Open <filename>en.po</filename> in <command>poedit</command> and provide - the English translation to message <literal>"Hello world\n"</literal>. Do the - same for <filename>de.po</filename> (deutsch) and - <filename>pl.po</filename> (polish). Let the translations be, for example: - <itemizedlist> - <listitem><para> - <literal>en: "Welcome to beautiful world!\n"</literal> - </para></listitem> - <listitem><para> - <literal>de: "Hallo Welt!\n"</literal> - </para></listitem> - <listitem><para> - <literal>pl: "Witaj swiecie!\n"</literal> - </para></listitem> - </itemizedlist> - </para> - <para> - Now compile the project by executing <command>scons</command>. The - output should be similar to this: - <screen> - user@host:$ scons - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - msgfmt -c -o de.mo de.po - msgfmt -c -o en.mo en.po - gcc -o hello.o -c hello.c - gcc -o hello hello.o - Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" - Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" - msgfmt -c -o pl.mo pl.po - Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" - scons: done building targets. - </screen> - SCons automatically compiled the <literal>PO</literal> files to binary format - <literal>MO</literal>, and the <literal>InstallAs</literal> lines installed - these files under <filename>locale</filename> folder. - </para> - <para> - Your program should be now ready. You may try it as follows (linux): - <screen> - user@host:$ LANG=en_US.UTF-8 ./hello - Welcome to beautiful world - </screen> - <screen> - user@host:$ LANG=de_DE.UTF-8 ./hello - Hallo Welt - </screen> - <screen> - user@host:$ LANG=pl_PL.UTF-8 ./hello - Witaj swiecie - </screen> - </para> - <para> - To demonstrate the further life of translation files, let's change Polish - translation (<command>poedit pl.po</command>) to <literal>"Witaj drogi - swiecie\n"</literal>. Run <command>scons</command> to see how scons - reacts to this - <screen> - user@host:$scons - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - msgfmt -c -o pl.mo pl.po - Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" - scons: done building targets. - </screen> - </para> - <para> - Now, open <filename>hello.c</filename> and add another one - <literal>printf</literal> line with new message. - <scons_example name="ex5"> - <file name="hello.c" printme="1"> - /* hello.c */ - #include <stdio.h> - #include <libintl.h> - #include <locale.h> - int main(int argc, char* argv[]) - { - bindtextdomain("hello", "locale"); - setlocale(LC_ALL, ""); - textdomain("hello"); - printf(gettext("Hello world\n")); - printf(gettext("and good bye\n")); - return 0; - } - </file> - </scons_example> - </para> - <para> - Compile project with <command>scons</command>. This time, the - <command>msgmerge(1)</command> program is used by SCons to update - <literal>PO</literal> file. The output from compilation is like: - <screen> - user@host:$scons - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - Entering '/home/ptomulik/projects/tmp' - xgettext --package-name=hello --package-version=1.0 -o - hello.c - Leaving '/home/ptomulik/projects/tmp' - Writting 'messages.pot' (messages in file were outdated) - msgmerge --update de.po messages.pot - ... done. - msgfmt -c -o de.mo de.po - msgmerge --update en.po messages.pot - ... done. - msgfmt -c -o en.mo en.po - gcc -o hello.o -c hello.c - gcc -o hello hello.o - Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" - Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" - msgmerge --update pl.po messages.pot - ... done. - msgfmt -c -o pl.mo pl.po - Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" - scons: done building targets. - </screen> - </para> - <para> - The next example demonstrates what happens if we change the source code - in such way that the internationalized messages do not change. The answer - is that none of translation files (<literal>POT</literal>, - <literal>PO</literal>) are touched (i.e. no content changes, no - creation/modification time changed and so on). Let's append another - line to the program (after the last printf), so its code becomes: - <scons_example name="ex6"> - <file name="hello.c" printme="1"> - /* hello.c */ - #include <stdio.h> - #include <libintl.h> - #include <locale.h> - int main(int argc, char* argv[]) - { - bindtextdomain("hello", "locale"); - setlocale(LC_ALL, ""); - textdomain("hello"); - printf(gettext("Hello world\n")); - printf(gettext("and good bye\n")); - printf("----------------\n"); - return a; - } - </file> - </scons_example> - Compile the project. You'll see on your screen - <screen> - user@host:$scons - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - Entering '/home/ptomulik/projects/tmp' - xgettext --package-name=hello --package-version=1.0 -o - hello.c - Leaving '/home/ptomulik/projects/tmp' - Not writting 'messages.pot' (messages in file found to be up-to-date) - gcc -o hello.o -c hello.c - gcc -o hello hello.o - scons: done building targets. - </screen> - As you see, the internationalized messages ditn't change, so the - <literal>POT</literal> and the rest of translation files have not - even been touched. - </para> - </section> diff --git a/doc/user/gettext.xml b/doc/user/gettext.xml index 706febe..c9cbcdb 100644 --- a/doc/user/gettext.xml +++ b/doc/user/gettext.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-gettext" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Internationalization and localization with gettext</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -40,12 +62,14 @@ </para> <para> - Ensure, that you have <ulink url="http://www.gnu.org/software/gettext/manual/gettext.html">GNU gettext + Ensure, that you have <ulink + url="http://www.gnu.org/software/gettext/manual/gettext.html">GNU gettext utilities</ulink> installed on your system. </para> <para> - To edit translation files you may wish to install <ulink url="http://www.poedit.net/">poedit</ulink> editor. + To edit translation files you may wish to install <ulink + url="http://www.poedit.net/">poedit</ulink> editor. </para> </section> @@ -54,30 +78,36 @@ <para> Let's start with a very simple project, the "Hello world" program for example - <programlisting> - /* hello.c */ - #include <stdio.h> - int main(int argc, char* argv[]) - { - printf("Hello world\n"); - return 0; - } - </programlisting> + <scons_example name="gettext_ex1"> + <file name="hello.c" printme="1"> +/* hello.c */ +#include <stdio.h> +int main(int argc, char* argv[]) +{ + printf("Hello world\n"); + return 0; +} + </file> + </scons_example> Prepare a <filename>SConstruct</filename> to compile the program as usual. - <programlisting> - # SConstruct - env = Environment() - hello = Program(["hello.c"]) - </programlisting> + <scons_example name="gettext_ex2"> + <file name="SConstruct" printme="1"> +# SConstruct +env = Environment() +hello = Program(["hello.c"]) + </file> + </scons_example> </para> <para> Now we'll convert the project to a multi-lingual one. If you don't - already have <ulink url="http://www.gnu.org/software/gettext/manual/gettext.html">GNU gettext + already have <ulink + url="http://www.gnu.org/software/gettext/manual/gettext.html">GNU gettext utilities</ulink> installed, install them from your preffered - package repository, or download from <ulink url="http://ftp.gnu.org/gnu/gettext/"> + package repository, or download from <ulink + url="http://ftp.gnu.org/gnu/gettext/"> http://ftp.gnu.org/gnu/gettext/</ulink>. For the purpose of this example, you should have following three locales installed on your system: <literal>en_US</literal>, <literal>de_DE</literal> and @@ -88,22 +118,25 @@ <para> First prepare the <filename>hello.c</filename> program for internationalization. Change the previous code so it reads as follows: - <programlisting> - /* hello.c */ - #include <stdio.h> - #include <libintl.h> - #include <locale.h> - int main(int argc, char* argv[]) - { - bindtextdomain("hello", "locale"); - setlocale(LC_ALL, ""); - textdomain("hello"); - printf(gettext("Hello world\n")); - return 0; - } - </programlisting> + <scons_example name="gettext_ex3"> + <file name="hello.c" printme="1"> +/* hello.c */ +#include <stdio.h> +#include <libintl.h> +#include <locale.h> +int main(int argc, char* argv[]) +{ + bindtextdomain("hello", "locale"); + setlocale(LC_ALL, ""); + textdomain("hello"); + printf(gettext("Hello world\n")); + return 0; +} + </file> + </scons_example> Detailed recipes for such conversion can - be found at <ulink url="http://www.gnu.org/software/gettext/manual/gettext.html#Sources"> + be found at <ulink + url="http://www.gnu.org/software/gettext/manual/gettext.html#Sources"> http://www.gnu.org/software/gettext/manual/gettext.html#Sources</ulink>. The <function>gettext("...")</function> has two purposes. First, it marks messages for the <command>xgettext(1)</command> program, which @@ -127,48 +160,50 @@ <para> The completed <filename>SConstruct</filename> is as follows: - <programlisting> - # SConstruct - env = Environment( tools = ['default', 'gettext'] ) - hello = env.Program(["hello.c"]) - env['XGETTEXTFLAGS'] = [ - '--package-name=%s' % 'hello', - '--package-version=%s' % '1.0', - ] - po = env.Translate(["pl","en", "de"], ["hello.c"], POAUTOINIT = 1) - mo = env.MOFiles(po) - InstallAs(["locale/en/LC_MESSAGES/hello.mo"], ["en.mo"]) - InstallAs(["locale/pl/LC_MESSAGES/hello.mo"], ["pl.mo"]) - InstallAs(["locale/de/LC_MESSAGES/hello.mo"], ["de.mo"]) - </programlisting> + <scons_example name="gettext_ex4"> + <file name="SConstruct" printme="1"> +# SConstruct +env = Environment( tools = ['default', 'gettext'] ) +hello = env.Program(["hello.c"]) +env['XGETTEXTFLAGS'] = [ + '--package-name=%s' % 'hello', + '--package-version=%s' % '1.0', +] +po = env.Translate(["pl","en", "de"], ["hello.c"], POAUTOINIT = 1) +mo = env.MOFiles(po) +InstallAs(["locale/en/LC_MESSAGES/hello.mo"], ["en.mo"]) +InstallAs(["locale/pl/LC_MESSAGES/hello.mo"], ["pl.mo"]) +InstallAs(["locale/de/LC_MESSAGES/hello.mo"], ["de.mo"]) + </file> + </scons_example> </para> <para> Generate the translation files with <command>scons po-update</command>. You should see the output from SCons simillar to this: <screen> - user@host:$ scons po-update - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - Entering '/home/ptomulik/projects/tmp' - xgettext --package-name=hello --package-version=1.0 -o - hello.c - Leaving '/home/ptomulik/projects/tmp' - Writting 'messages.pot' (new file) - msginit --no-translator -l pl -i messages.pot -o pl.po - Created pl.po. - msginit --no-translator -l en -i messages.pot -o en.po - Created en.po. - msginit --no-translator -l de -i messages.pot -o de.po - Created de.po. - scons: done building targets. +user@host:$ scons po-update +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons: Building targets ... +Entering '/home/ptomulik/projects/tmp' +xgettext --package-name=hello --package-version=1.0 -o - hello.c +Leaving '/home/ptomulik/projects/tmp' +Writting 'messages.pot' (new file) +msginit --no-translator -l pl -i messages.pot -o pl.po +Created pl.po. +msginit --no-translator -l en -i messages.pot -o en.po +Created en.po. +msginit --no-translator -l de -i messages.pot -o de.po +Created de.po. +scons: done building targets. </screen> </para> <para> If everything is right, you should see following new files. <screen> - user@host:$ ls *.po* - de.po en.po messages.pot pl.po +user@host:$ ls *.po* +de.po en.po messages.pot pl.po </screen> </para> @@ -193,19 +228,19 @@ Now compile the project by executing <command>scons</command>. The output should be similar to this: <screen> - user@host:$ scons - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - msgfmt -c -o de.mo de.po - msgfmt -c -o en.mo en.po - gcc -o hello.o -c hello.c - gcc -o hello hello.o - Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" - Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" - msgfmt -c -o pl.mo pl.po - Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" - scons: done building targets. +user@host:$ scons +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons: Building targets ... +msgfmt -c -o de.mo de.po +msgfmt -c -o en.mo en.po +gcc -o hello.o -c hello.c +gcc -o hello hello.o +Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" +Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" +msgfmt -c -o pl.mo pl.po +Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" +scons: done building targets. </screen> SCons automatically compiled the <literal>PO</literal> files to binary format <literal>MO</literal>, and the <literal>InstallAs</literal> lines installed @@ -214,16 +249,16 @@ <para> Your program should be now ready. You may try it as follows (linux): <screen> - user@host:$ LANG=en_US.UTF-8 ./hello - Welcome to beautiful world +user@host:$ LANG=en_US.UTF-8 ./hello +Welcome to beautiful world </screen> <screen> - user@host:$ LANG=de_DE.UTF-8 ./hello - Hallo Welt +user@host:$ LANG=de_DE.UTF-8 ./hello +Hallo Welt </screen> <screen> - user@host:$ LANG=pl_PL.UTF-8 ./hello - Witaj swiecie +user@host:$ LANG=pl_PL.UTF-8 ./hello +Witaj swiecie </screen> </para> <para> @@ -232,62 +267,64 @@ swiecie\n"</literal>. Run <command>scons</command> to see how scons reacts to this <screen> - user@host:$scons - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - msgfmt -c -o pl.mo pl.po - Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" - scons: done building targets. +user@host:$scons +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons: Building targets ... +msgfmt -c -o pl.mo pl.po +Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" +scons: done building targets. </screen> </para> <para> Now, open <filename>hello.c</filename> and add another one <literal>printf</literal> line with new message. - <programlisting> - /* hello.c */ - #include <stdio.h> - #include <libintl.h> - #include <locale.h> - int main(int argc, char* argv[]) - { - bindtextdomain("hello", "locale"); - setlocale(LC_ALL, ""); - textdomain("hello"); - printf(gettext("Hello world\n")); - printf(gettext("and good bye\n")); - return 0; - } - </programlisting> + <scons_example name="gettext_ex5"> + <file name="hello.c" printme="1"> +/* hello.c */ +#include <stdio.h> +#include <libintl.h> +#include <locale.h> +int main(int argc, char* argv[]) +{ + bindtextdomain("hello", "locale"); + setlocale(LC_ALL, ""); + textdomain("hello"); + printf(gettext("Hello world\n")); + printf(gettext("and good bye\n")); + return 0; +} + </file> + </scons_example> </para> <para> Compile project with <command>scons</command>. This time, the <command>msgmerge(1)</command> program is used by SCons to update <literal>PO</literal> file. The output from compilation is like: <screen> - user@host:$scons - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - Entering '/home/ptomulik/projects/tmp' - xgettext --package-name=hello --package-version=1.0 -o - hello.c - Leaving '/home/ptomulik/projects/tmp' - Writting 'messages.pot' (messages in file were outdated) - msgmerge --update de.po messages.pot - ... done. - msgfmt -c -o de.mo de.po - msgmerge --update en.po messages.pot - ... done. - msgfmt -c -o en.mo en.po - gcc -o hello.o -c hello.c - gcc -o hello hello.o - Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" - Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" - msgmerge --update pl.po messages.pot - ... done. - msgfmt -c -o pl.mo pl.po - Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" - scons: done building targets. +user@host:$scons +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons: Building targets ... +Entering '/home/ptomulik/projects/tmp' +xgettext --package-name=hello --package-version=1.0 -o - hello.c +Leaving '/home/ptomulik/projects/tmp' +Writting 'messages.pot' (messages in file were outdated) +msgmerge --update de.po messages.pot +... done. +msgfmt -c -o de.mo de.po +msgmerge --update en.po messages.pot +... done. +msgfmt -c -o en.mo en.po +gcc -o hello.o -c hello.c +gcc -o hello hello.o +Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" +Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" +msgmerge --update pl.po messages.pot +... done. +msgfmt -c -o pl.mo pl.po +Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" +scons: done building targets. </screen> </para> <para> @@ -297,38 +334,42 @@ <literal>PO</literal>) are touched (i.e. no content changes, no creation/modification time changed and so on). Let's append another line to the program (after the last printf), so its code becomes: - <programlisting> - /* hello.c */ - #include <stdio.h> - #include <libintl.h> - #include <locale.h> - int main(int argc, char* argv[]) - { - bindtextdomain("hello", "locale"); - setlocale(LC_ALL, ""); - textdomain("hello"); - printf(gettext("Hello world\n")); - printf(gettext("and good bye\n")); - printf("----------------\n"); - return a; - } - </programlisting> + <scons_example name="gettext_ex6"> + <file name="hello.c" printme="1"> +/* hello.c */ +#include <stdio.h> +#include <libintl.h> +#include <locale.h> +int main(int argc, char* argv[]) +{ + bindtextdomain("hello", "locale"); + setlocale(LC_ALL, ""); + textdomain("hello"); + printf(gettext("Hello world\n")); + printf(gettext("and good bye\n")); + printf("----------------\n"); + return a; +} + </file> + </scons_example> Compile the project. You'll see on your screen <screen> - user@host:$scons - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - Entering '/home/ptomulik/projects/tmp' - xgettext --package-name=hello --package-version=1.0 -o - hello.c - Leaving '/home/ptomulik/projects/tmp' - Not writting 'messages.pot' (messages in file found to be up-to-date) - gcc -o hello.o -c hello.c - gcc -o hello hello.o - scons: done building targets. +user@host:$scons +scons: Reading SConscript files ... +scons: done reading SConscript files. +scons: Building targets ... +Entering '/home/ptomulik/projects/tmp' +xgettext --package-name=hello --package-version=1.0 -o - hello.c +Leaving '/home/ptomulik/projects/tmp' +Not writting 'messages.pot' (messages in file found to be up-to-date) +gcc -o hello.o -c hello.c +gcc -o hello hello.o +scons: done building targets. </screen> As you see, the internationalized messages ditn't change, so the <literal>POT</literal> and the rest of translation files have not even been touched. </para> </section> + +</chapter> diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in deleted file mode 100644 index 473f519..0000000 --- a/doc/user/hierarchy.in +++ /dev/null @@ -1,794 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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. - ---> - -<!-- - - -=head2 The Build command - -By default, Cons does not change its working directory to the directory -containing a subsidiary F<Conscript> file it is including. This behavior -can be enabled for a build by specifying, in the top-level F<Construct> -file: - - Conscript_chdir 1; - -When enabled, Cons will change to the subsidiary F<Conscript> file's -containing directory while reading in that file, and then change back -to the top-level directory once the file has been processed. - -It is expected that this behavior will become the default in some future -version of Cons. To prepare for this transition, builds that expect -Cons to remain at the top of the build while it reads in a subsidiary -F<Conscript> file should explicitly disable this feature as follows: - - Conscript_chdir 0; - -=head2 Relative, top-relative, and absolute file names - -(There is another file prefix, ``!'', that is interpreted specially by -Cons. See discussion of the C<Link> command, below, for details.) - - -=head2 Using modules in build scripts - -You may pull modules into each F<Conscript> file using the normal Perl -C<use> or C<require> statements: - - use English; - require My::Module; - -Each C<use> or C<require> only affects the one F<Conscript> file in which -it appears. To use a module in multiple F<Conscript> files, you must -put a C<use> or C<require> statement in each one that needs the module. - - -=head2 Scope of variables - -The top-level F<Construct> file and all F<Conscript> files begin life in -a common, separate Perl package. B<Cons> controls the symbol table for -the package so that, the symbol table for each script is empty, except -for the F<Construct> file, which gets some of the command line arguments. -All of the variables that are set or used, therefore, are set by the -script itself, not by some external script. - -Variables can be explicitly B<imported> by a script from its parent -script. To import a variable, it must have been B<exported> by the parent -and initialized (otherwise an error will occur). - - -=head2 The Export command - -The C<Export> command is used as in the following example: - - $env = new cons(); - $INCLUDE = "#export/include"; - $LIB = "#export/lib"; - Export qw( env INCLUDE LIB ); - Build qw( util/Conscript ); - -The values of the simple variables mentioned in the C<Export> list will be -squirreled away by any subsequent C<Build> commands. The C<Export> command -will only export Perl B<scalar> variables, that is, variables whose name -begins with C<$>. Other variables, objects, etc. can be exported by -reference, but all scripts will refer to the same object, and this object -should be considered to be read-only by the subsidiary scripts and by the -original exporting script. It's acceptable, however, to assign a new value -to the exported scalar variable, that won't change the underlying variable -referenced. This sequence, for example, is OK: - - $env = new cons(); - Export qw( env INCLUDE LIB ); - Build qw( util/Conscript ); - $env = new cons(CFLAGS => '-O'); - Build qw( other/Conscript ); - -It doesn't matter whether the variable is set before or after the C<Export> -command. The important thing is the value of the variable at the time the -C<Build> command is executed. This is what gets squirreled away. Any -subsequent C<Export> commands, by the way, invalidate the first: you must -mention all the variables you wish to export on each C<Export> command. - - -=head2 The Import command - -Variables exported by the C<Export> command can be imported into subsidiary -scripts by the C<Import> command. The subsidiary script always imports -variables directly from the superior script. Consider this example: - - Import qw( env INCLUDE ); - -This is only legal if the parent script exported both C<$env> and -C<$INCLUDE>. It also must have given each of these variables values. It is -OK for the subsidiary script to only import a subset of the exported -variables (in this example, C<$LIB>, which was exported by the previous -example, is not imported). - -All the imported variables are automatically re-exported, so the sequence: - - Import qw ( env INCLUDE ); - Build qw ( beneath-me/Conscript ); - -will supply both C<$env> and C<$INCLUDE> to the subsidiary file. If only -C<$env> is to be exported, then the following will suffice: - - Import qw ( env INCLUDE ); - Export qw ( env ); - Build qw ( beneath-me/Conscript ); - -Needless to say, the variables may be modified locally before invoking -C<Build> on the subsidiary script. - -=head2 Build script evaluation order - -The only constraint on the ordering of build scripts is that superior -scripts are evaluated before their inferior scripts. The top-level -F<Construct> file, for instance, is evaluated first, followed by any -inferior scripts. This is all you really need to know about the evaluation -order, since order is generally irrelevant. Consider the following C<Build> -command: - - Build qw( - drivers/display/Conscript - drivers/mouse/Conscript - parser/Conscript - utilities/Conscript - ); - -We've chosen to put the script names in alphabetical order, simply because -that's the most convenient for maintenance purposes. Changing the order will -make no difference to the build. - ---> - - <para> - - The source code for large software projects - rarely stays in a single directory, - but is nearly always divided into a - hierarchy of directories. - Organizing a large software build using &SCons; - involves creating a hierarchy of build scripts - using the &SConscript; function. - - </para> - - <section> - <title>&SConscript; Files</title> - - <para> - - As we've already seen, - the build script at the top of the tree is called &SConstruct;. - The top-level &SConstruct; file can - use the &SConscript; function to - include other subsidiary scripts in the build. - These subsidiary scripts can, in turn, - use the &SConscript; function - to include still other scripts in the build. - By convention, these subsidiary scripts are usually - named &SConscript;. - For example, a top-level &SConstruct; file might - arrange for four subsidiary scripts to be included - in the build as follows: - - </para> - - <sconstruct> - SConscript(['drivers/display/SConscript', - 'drivers/mouse/SConscript', - 'parser/SConscript', - 'utilities/SConscript']) - </sconstruct> - - <para> - - In this case, the &SConstruct; file - lists all of the &SConscript; files in the build explicitly. - (Note, however, that not every directory in the tree - necessarily has an &SConscript; file.) - Alternatively, the <literal>drivers</literal> - subdirectory might contain an intermediate - &SConscript; file, - in which case the &SConscript; call in - the top-level &SConstruct; file - would look like: - - </para> - - <sconstruct> - SConscript(['drivers/SConscript', - 'parser/SConscript', - 'utilities/SConscript']) - </sconstruct> - - <para> - - And the subsidiary &SConscript; file in the - <literal>drivers</literal> subdirectory - would look like: - - </para> - - <sconstruct> - SConscript(['display/SConscript', - 'mouse/SConscript']) - </sconstruct> - - <para> - - Whether you list all of the &SConscript; files in the - top-level &SConstruct; file, - or place a subsidiary &SConscript; file in - intervening directories, - or use some mix of the two schemes, - is up to you and the needs of your software. - - </para> - - </section> - - <section> - <title>Path Names Are Relative to the &SConscript; Directory</title> - - <para> - - Subsidiary &SConscript; files make it easy to create a build - hierarchy because all of the file and directory names - in a subsidiary &SConscript; files are interpreted - relative to the directory in which the &SConscript; file lives. - Typically, this allows the &SConscript; file containing the - instructions to build a target file - to live in the same directory as the source files - from which the target will be built, - making it easy to update how the software is built - whenever files are added or deleted - (or other changes are made). - - </para> - - <para> - - For example, suppose we want to build two programs - &prog1; and &prog2; in two separate directories - with the same names as the programs. - One typical way to do this would be - with a top-level &SConstruct; file like this: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - SConscript(['prog1/SConscript', - 'prog2/SConscript']) - </file> - <file name="prog1/SConscript"> - env = Environment() - env.Program('prog1', ['main.c', 'foo1.c', 'foo2.c']) - </file> - <file name="prog2/SConscript"> - env = Environment() - env.Program('prog2', ['main.c', 'bar1.c', 'bar2.c']) - </file> - <directory name="prog1"></directory> - <file name="prog1/main.c"> - x - </file> - <file name="prog1/foo1.c"> - x - </file> - <file name="prog1/foo2.c"> - x - </file> - <directory name="prog2"></directory> - <file name="prog2/main.c"> - x - </file> - <file name="prog2/bar1.c"> - x - </file> - <file name="prog2/bar2.c"> - x - </file> - </scons_example> - - <para> - - And subsidiary &SConscript; files that look like this: - - </para> - - <scons_example_file example="ex1" name="prog1/SConscript"> - </scons_example_file> - - <para> - - And this: - - </para> - - <scons_example_file example="ex1" name="prog2/SConscript"> - </scons_example_file> - - <para> - - Then, when we run &SCons; in the top-level directory, - our build looks like: - - </para> - - <scons_output example="ex1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Notice the following: - - First, you can have files with the same names - in multiple directories, like main.c in the above example. - - Second, unlike standard recursive use of &Make;, - &SCons; stays in the top-level directory - (where the &SConstruct; file lives) - and issues commands that use the path names - from the top-level directory to the - target and source files within the hierarchy. - - </para> - - </section> - - <section> - <title>Top-Level Path Names in Subsidiary &SConscript; Files</title> - - <para> - - If you need to use a file from another directory, - it's sometimes more convenient to specify - the path to a file in another directory - from the top-level &SConstruct; directory, - even when you're using that file in - a subsidiary &SConscript; file in a subdirectory. - You can tell &SCons; to interpret a path name - as relative to the top-level &SConstruct; directory, - not the local directory of the &SConscript; file, - by appending a &hash; (hash mark) - to the beginning of the path name: - - </para> - - <scons_example name="ex2"> - <file name="SConstruct"> - SConscript('src/prog/SConscript') - </file> - <file name="src/prog/SConscript" printme="1"> - env = Environment() - env.Program('prog', ['main.c', '#lib/foo1.c', 'foo2.c']) - </file> - <file name="src/prog/main.c"> - x - </file> - <file name="lib/foo1.c"> - x - </file> - <file name="src/prog/foo2.c"> - x - </file> - </scons_example> - - <para> - - In this example, - the <literal>lib</literal> directory is - directly underneath the top-level &SConstruct; directory. - If the above &SConscript; file is in a subdirectory - named <literal>src/prog</literal>, - the output would look like: - - </para> - - <scons_output example="ex2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - (Notice that the <literal>lib/foo1.o</literal> object file - is built in the same directory as its source file. - See <xref linkend="chap-separate"></xref>, below, - for information about - how to build the object file in a different subdirectory.) - - </para> - - </section> - - <section> - <title>Absolute Path Names</title> - - <para> - - Of course, you can always specify - an absolute path name for a file--for example: - - </para> - - <scons_example name="ex3"> - <file name="SConstruct"> - SConscript('src/prog/SConscript') - </file> - <file name="src/prog/SConscript" printme="1"> - env = Environment() - env.Program('prog', ['main.c', '__ROOT__/usr/joe/lib/foo1.c', 'foo2.c']) - </file> - <file name="src/prog/main.c"> - x - </file> - <file name="__ROOT__/usr/joe/lib/foo1.c"> - x - </file> - <file name="src/prog/foo2.c"> - x - </file> - </scons_example> - - <para> - - Which, when executed, would yield: - - </para> - - <scons_output example="ex3"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - (As was the case with top-relative path names, - notice that the <literal>/usr/joe/lib/foo1.o</literal> object file - is built in the same directory as its source file. - See <xref linkend="chap-separate"></xref>, below, - for information about - how to build the object file in a different subdirectory.) - - </para> - - </section> - - <section> - <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title> - - <para> - - In the previous example, - each of the subsidiary &SConscript; files - created its own construction environment - by calling &Environment; separately. - This obviously works fine, - but if each program must be built - with the same construction variables, - it's cumbersome and error-prone to initialize - separate construction environments - in the same way over and over in each subsidiary - &SConscript; file. - - </para> - - <para> - - &SCons; supports the ability to <emphasis>export</emphasis> variables - from a parent &SConscript; file - to its subsidiary &SConscript; files, - which allows you to share common initialized - values throughout your build hierarchy. - - </para> - - <section> - <title>Exporting Variables</title> - - <para> - - There are two ways to export a variable, - such as a construction environment, - from an &SConscript; file, - so that it may be used by other &SConscript; files. - First, you can call the &Export; - function with a list of variables, - or a string of white-space separated variable names. - Each call to &Export; adds one - or more variables to a global list - of variables that are available for import - by other &SConscript; files. - - </para> - - <sconstruct> - env = Environment() - Export('env') - </sconstruct> - - <para> - - You may export more than one variable name at a time: - - </para> - - <sconstruct> - env = Environment() - debug = ARGUMENTS['debug'] - Export('env', 'debug') - </sconstruct> - - <para> - - Because white space is not legal in Python variable names, - the &Export; function will even automatically split - a string into separate names for you: - - </para> - - <sconstruct> - Export('env debug') - </sconstruct> - - <para> - - Second, you can specify a list of - variables to export as a second argument - to the &SConscript; function call: - - </para> - - <sconstruct> - SConscript('src/SConscript', 'env') - </sconstruct> - - <para> - - Or as the &exports; keyword argument: - - </para> - - <sconstruct> - SConscript('src/SConscript', exports='env') - </sconstruct> - - <para> - - These calls export the specified variables - to only the listed &SConscript; files. - You may, however, specify more than one - &SConscript; file in a list: - - </para> - - <sconstruct> - SConscript(['src1/SConscript', - 'src2/SConscript'], exports='env') - </sconstruct> - - <para> - - This is functionally equivalent to - calling the &SConscript; function - multiple times with the same &exports; argument, - one per &SConscript; file. - - </para> - - </section> - - <section> - <title>Importing Variables</title> - - <para> - - Once a variable has been exported from a calling - &SConscript; file, - it may be used in other &SConscript; files - by calling the &Import; function: - - </para> - - <sconstruct> - Import('env') - env.Program('prog', ['prog.c']) - </sconstruct> - - <para> - - The &Import; call makes the <literal>env</literal> construction - environment available to the &SConscript; file, - after which the variable can be used to build - programs, libraries, etc. - - </para> - - <para> - - Like the &Export; function, - the &Import; function can be used - with multiple variable names: - - </para> - - <sconstruct> - Import('env', 'debug') - env = env.Clone(DEBUG = debug) - env.Program('prog', ['prog.c']) - </sconstruct> - - <para> - - And the &Import; function will similarly - split a string along white-space - into separate variable names: - - </para> - - <sconstruct> - Import('env debug') - env = env.Clone(DEBUG = debug) - env.Program('prog', ['prog.c']) - </sconstruct> - - <para> - - Lastly, as a special case, - you may import all of the variables that - have been exported by supplying an asterisk - to the &Import; function: - - </para> - - <sconstruct> - Import('*') - env = env.Clone(DEBUG = debug) - env.Program('prog', ['prog.c']) - </sconstruct> - - <para> - - If you're dealing with a lot of &SConscript; files, - this can be a lot simpler than keeping - arbitrary lists of imported variables in each file. - - </para> - - </section> - - <section> - <title>Returning Values From an &SConscript; File</title> - - <para> - - Sometimes, you would like to be able to - use information from a subsidiary - &SConscript; file in some way. - For example, - suppose that you want to create one - library from source files - scattered throughout a number - of subsidiary &SConscript; files. - You can do this by using the &Return; - function to return values - from the subsidiary &SConscript; files - to the calling file. - - </para> - - <para> - - If, for example, we have two subdirectories - &foo; and &bar; - that should each contribute a source - file to a Library, - what we'd like to be able to do is - collect the object files - from the subsidiary &SConscript; calls - like this: - - </para> - - <scons_example name="Return"> - <file name="SConstruct" printme="1"> - env = Environment() - Export('env') - objs = [] - for subdir in ['foo', 'bar']: - o = SConscript('%s/SConscript' % subdir) - objs.append(o) - env.Library('prog', objs) - </file> - <directory name="foo"></directory> - <directory name="bar"></directory> - <file name="foo/SConscript"> - Import('env') - obj = env.Object('foo.c') - Return('obj') - </file> - <file name="bar/SConscript"> - Import('env') - obj = env.Object('bar.c') - Return('obj') - </file> - <file name="foo/foo.c"> - void foo(void) { printf("foo/foo.c\n"); } - </file> - <file name="bar/bar.c"> - void bar(void) { printf("bar/bar.c\n"); } - </file> - </scons_example> - - <para> - - We can do this by using the &Return; - function in the - <literal>foo/SConscript</literal> file like this: - - </para> - - <scons_example_file example="Return" name="foo/SConscript"> - </scons_example_file> - - <para> - - (The corresponding - <literal>bar/SConscript</literal> - file should be pretty obvious.) - Then when we run &SCons;, - the object files from the subsidiary subdirectories - are all correctly archived in the desired library: - - </para> - - <scons_output example="Return"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <!-- - XXX Return(stop=False) - --> - - </section> - - </section> - - <!-- - - <section> - <title>Executing From a Subdirectory: the -D, -u and -U Options</title> - - <para> - - XXX -D, -u and -U - - </para> - - </section> - - --> diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml index 17067d7..c0664ee 100644 --- a/doc/user/hierarchy.xml +++ b/doc/user/hierarchy.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-hierarchical" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Hierarchical Builds</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -196,12 +218,12 @@ make no difference to the build. </para> - <programlisting> - SConscript(['drivers/display/SConscript', - 'drivers/mouse/SConscript', - 'parser/SConscript', - 'utilities/SConscript']) - </programlisting> + <sconstruct> +SConscript(['drivers/display/SConscript', + 'drivers/mouse/SConscript', + 'parser/SConscript', + 'utilities/SConscript']) + </sconstruct> <para> @@ -218,11 +240,11 @@ make no difference to the build. </para> - <programlisting> - SConscript(['drivers/SConscript', - 'parser/SConscript', - 'utilities/SConscript']) - </programlisting> + <sconstruct> +SConscript(['drivers/SConscript', + 'parser/SConscript', + 'utilities/SConscript']) + </sconstruct> <para> @@ -232,10 +254,10 @@ make no difference to the build. </para> - <programlisting> - SConscript(['display/SConscript', - 'mouse/SConscript']) - </programlisting> + <sconstruct> +SConscript(['display/SConscript', + 'mouse/SConscript']) + </sconstruct> <para> @@ -279,10 +301,40 @@ make no difference to the build. </para> - <programlisting> - SConscript(['prog1/SConscript', - 'prog2/SConscript']) - </programlisting> + <scons_example name="hierarchy_ex1"> + <file name="SConstruct" printme="1"> +SConscript(['prog1/SConscript', + 'prog2/SConscript']) + </file> + <file name="prog1/SConscript"> +env = Environment() +env.Program('prog1', ['main.c', 'foo1.c', 'foo2.c']) + </file> + <file name="prog2/SConscript"> +env = Environment() +env.Program('prog2', ['main.c', 'bar1.c', 'bar2.c']) + </file> + <directory name="prog1"></directory> + <file name="prog1/main.c"> +x + </file> + <file name="prog1/foo1.c"> +x + </file> + <file name="prog1/foo2.c"> +x + </file> + <directory name="prog2"></directory> + <file name="prog2/main.c"> +x + </file> + <file name="prog2/bar1.c"> +x + </file> + <file name="prog2/bar2.c"> +x + </file> + </scons_example> <para> @@ -290,11 +342,8 @@ make no difference to the build. </para> - - <programlisting> - env = Environment() - env.Program('prog1', ['main.c', 'foo1.c', 'foo2.c']) - </programlisting> + <scons_example_file example="hierarchy_ex1" name="prog1/SConscript"> + </scons_example_file> <para> @@ -302,11 +351,8 @@ make no difference to the build. </para> - - <programlisting> - env = Environment() - env.Program('prog2', ['main.c', 'bar1.c', 'bar2.c']) - </programlisting> + <scons_example_file example="hierarchy_ex1" name="prog2/SConscript"> + </scons_example_file> <para> @@ -315,17 +361,9 @@ make no difference to the build. </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o prog1/foo1.o -c prog1/foo1.c - cc -o prog1/foo2.o -c prog1/foo2.c - cc -o prog1/main.o -c prog1/main.c - cc -o prog1/prog1 prog1/main.o prog1/foo1.o prog1/foo2.o - cc -o prog2/bar1.o -c prog2/bar1.c - cc -o prog2/bar2.o -c prog2/bar2.c - cc -o prog2/main.o -c prog2/main.c - cc -o prog2/prog2 prog2/main.o prog2/bar1.o prog2/bar2.o - </screen> + <scons_output example="hierarchy_ex1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -364,10 +402,24 @@ make no difference to the build. </para> - <programlisting> - env = Environment() - env.Program('prog', ['main.c', '#lib/foo1.c', 'foo2.c']) - </programlisting> + <scons_example name="hierarchy_ex2"> + <file name="SConstruct"> +SConscript('src/prog/SConscript') + </file> + <file name="src/prog/SConscript" printme="1"> +env = Environment() +env.Program('prog', ['main.c', '#lib/foo1.c', 'foo2.c']) + </file> + <file name="src/prog/main.c"> +x + </file> + <file name="lib/foo1.c"> +x + </file> + <file name="src/prog/foo2.c"> +x + </file> + </scons_example> <para> @@ -380,13 +432,9 @@ make no difference to the build. </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o lib/foo1.o -c lib/foo1.c - cc -o src/prog/foo2.o -c src/prog/foo2.c - cc -o src/prog/main.o -c src/prog/main.c - cc -o src/prog/prog src/prog/main.o lib/foo1.o src/prog/foo2.o - </screen> + <scons_output example="hierarchy_ex2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -410,10 +458,24 @@ make no difference to the build. </para> - <programlisting> - env = Environment() - env.Program('prog', ['main.c', '/usr/joe/lib/foo1.c', 'foo2.c']) - </programlisting> + <scons_example name="hierarchy_ex3"> + <file name="SConstruct"> +SConscript('src/prog/SConscript') + </file> + <file name="src/prog/SConscript" printme="1"> +env = Environment() +env.Program('prog', ['main.c', '__ROOT__/usr/joe/lib/foo1.c', 'foo2.c']) + </file> + <file name="src/prog/main.c"> +x + </file> + <file name="__ROOT__/usr/joe/lib/foo1.c"> +x + </file> + <file name="src/prog/foo2.c"> +x + </file> + </scons_example> <para> @@ -421,13 +483,9 @@ make no difference to the build. </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o src/prog/foo2.o -c src/prog/foo2.c - cc -o src/prog/main.o -c src/prog/main.c - cc -o /usr/joe/lib/foo1.o -c /usr/joe/lib/foo1.c - cc -o src/prog/prog src/prog/main.o /usr/joe/lib/foo1.o src/prog/foo2.o - </screen> + <scons_output example="hierarchy_ex3" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -490,10 +548,10 @@ make no difference to the build. </para> - <programlisting> - env = Environment() - Export('env') - </programlisting> + <sconstruct> +env = Environment() +Export('env') + </sconstruct> <para> @@ -501,11 +559,11 @@ make no difference to the build. </para> - <programlisting> - env = Environment() - debug = ARGUMENTS['debug'] - Export('env', 'debug') - </programlisting> + <sconstruct> +env = Environment() +debug = ARGUMENTS['debug'] +Export('env', 'debug') + </sconstruct> <para> @@ -515,9 +573,9 @@ make no difference to the build. </para> - <programlisting> - Export('env debug') - </programlisting> + <sconstruct> +Export('env debug') + </sconstruct> <para> @@ -527,9 +585,9 @@ make no difference to the build. </para> - <programlisting> - SConscript('src/SConscript', 'env') - </programlisting> + <sconstruct> +SConscript('src/SConscript', 'env') + </sconstruct> <para> @@ -537,9 +595,9 @@ make no difference to the build. </para> - <programlisting> - SConscript('src/SConscript', exports='env') - </programlisting> + <sconstruct> +SConscript('src/SConscript', exports='env') + </sconstruct> <para> @@ -550,10 +608,10 @@ make no difference to the build. </para> - <programlisting> - SConscript(['src1/SConscript', - 'src2/SConscript'], exports='env') - </programlisting> + <sconstruct> +SConscript(['src1/SConscript', + 'src2/SConscript'], exports='env') + </sconstruct> <para> @@ -578,10 +636,10 @@ make no difference to the build. </para> - <programlisting> - Import('env') - env.Program('prog', ['prog.c']) - </programlisting> + <sconstruct> +Import('env') +env.Program('prog', ['prog.c']) + </sconstruct> <para> @@ -600,11 +658,11 @@ make no difference to the build. </para> - <programlisting> - Import('env', 'debug') - env = env.Clone(DEBUG = debug) - env.Program('prog', ['prog.c']) - </programlisting> + <sconstruct> +Import('env', 'debug') +env = env.Clone(DEBUG = debug) +env.Program('prog', ['prog.c']) + </sconstruct> <para> @@ -614,11 +672,11 @@ make no difference to the build. </para> - <programlisting> - Import('env debug') - env = env.Clone(DEBUG = debug) - env.Program('prog', ['prog.c']) - </programlisting> + <sconstruct> +Import('env debug') +env = env.Clone(DEBUG = debug) +env.Program('prog', ['prog.c']) + </sconstruct> <para> @@ -629,11 +687,11 @@ make no difference to the build. </para> - <programlisting> - Import('*') - env = env.Clone(DEBUG = debug) - env.Program('prog', ['prog.c']) - </programlisting> + <sconstruct> +Import('*') +env = env.Clone(DEBUG = debug) +env.Program('prog', ['prog.c']) + </sconstruct> <para> @@ -678,15 +736,35 @@ make no difference to the build. </para> - <programlisting> - env = Environment() - Export('env') - objs = [] - for subdir in ['foo', 'bar']: - o = SConscript('%s/SConscript' % subdir) - objs.append(o) - env.Library('prog', objs) - </programlisting> + <scons_example name="hierarchy_Return"> + <file name="SConstruct" printme="1"> +env = Environment() +Export('env') +objs = [] +for subdir in ['foo', 'bar']: + o = SConscript('%s/SConscript' % subdir) + objs.append(o) +env.Library('prog', objs) + </file> + <directory name="foo"></directory> + <directory name="bar"></directory> + <file name="foo/SConscript"> +Import('env') +obj = env.Object('foo.c') +Return('obj') + </file> + <file name="bar/SConscript"> +Import('env') +obj = env.Object('bar.c') +Return('obj') + </file> + <file name="foo/foo.c"> +void foo(void) { printf("foo/foo.c\n"); } + </file> + <file name="bar/bar.c"> +void bar(void) { printf("bar/bar.c\n"); } + </file> + </scons_example> <para> @@ -696,12 +774,8 @@ make no difference to the build. </para> - - <programlisting> - Import('env') - obj = env.Object('foo.c') - Return('obj') - </programlisting> + <scons_example_file example="hierarchy_Return" name="foo/SConscript"> + </scons_example_file> <para> @@ -714,13 +788,9 @@ make no difference to the build. </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o bar/bar.o -c bar/bar.c - cc -o foo/foo.o -c foo/foo.c - ar rc libprog.a foo/foo.o bar/bar.o - ranlib libprog.a - </screen> + <scons_output example="hierarchy_Return" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <!-- XXX Return(stop=False) @@ -744,3 +814,5 @@ make no difference to the build. </section> --> + +</chapter> diff --git a/doc/user/builders.in b/doc/user/html.xsl index 0db5641..fd10751 100644 --- a/doc/user/builders.in +++ b/doc/user/html.xsl @@ -1,57 +1,59 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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 XML V4.3//EN" -"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> - -<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> +<?xml version='1.0'?>
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation
+
+ 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.
+
+-->
+<xsl:stylesheet
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ version="1.0">
+
+ <xsl:import href="../../src/engine/SCons/Tool/docbook/docbook-xsl-1.76.1/html/docbook.xsl"/>
+
+<xsl:param name="l10n.gentext.default.language" select="'en'"/>
+<xsl:param name="section.autolabel" select="1"/>
+<xsl:param name="html.stylesheet" select="'scons.css'"/>
+<xsl:param name="generate.toc">
+/appendix toc,title
+article/appendix nop
+/article toc,title
+book toc,title,figure,table,example,equation
+/chapter toc,title
+part toc,title
+/preface toc,title
+reference toc,title
+/sect1 toc
+/sect2 toc
+/sect3 toc
+/sect4 toc
+/sect5 toc
+/section toc
+set toc,title
+</xsl:param>
+
+<!-- Prevent our EPUB cover image from getting included -->
+<xsl:template match="mediaobject[@role = 'cover']">
+</xsl:template>
+
+</xsl:stylesheet>
+
diff --git a/doc/user/install.in b/doc/user/install.in deleted file mode 100644 index f0a5f26..0000000 --- a/doc/user/install.in +++ /dev/null @@ -1,247 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - Once a program is built, - it is often appropriate to install it in another - directory for public use. - You use the &Install; method - to arrange for a program, or any other file, - to be copied into a destination directory: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - env = Environment() - hello = env.Program('hello.c') - env.Install('__ROOT__/usr/bin', hello) - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Note, however, that installing a file is - still considered a type of file "build." - This is important when you remember that - the default behavior of &SCons; is - to build files in or below the current directory. - If, as in the example above, - you are installing files in a directory - outside of the top-level &SConstruct; file's directory tree, - you must specify that directory - (or a higher directory, such as <literal>/</literal>) - for it to install anything there: - - </para> - - <scons_output example="ex1"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q __ROOT__/usr/bin</scons_output_command> - </scons_output> - - <para> - - It can, however, be cumbersome to remember - (and type) the specific destination directory - in which the program (or any other file) - should be installed. - This is an area where the &Alias; - function comes in handy, - allowing you, for example, - to create a pseudo-target named <literal>install</literal> - that can expand to the specified destination directory: - - </para> - - <scons_example name="ex2"> - <file name="SConstruct" printme="1"> - env = Environment() - hello = env.Program('hello.c') - env.Install('__ROOT__/usr/bin', hello) - env.Alias('install', '__ROOT__/usr/bin') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - This then yields the more natural - ability to install the program - in its destination as follows: - - </para> - - <scons_output example="ex2"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q install</scons_output_command> - </scons_output> - - <section> - <title>Installing Multiple Files in a Directory</title> - - <para> - - You can install multiple files into a directory - simply by calling the &Install; function multiple times: - - </para> - - <scons_example name="ex3"> - <file name="SConstruct" printme="1"> - env = Environment() - hello = env.Program('hello.c') - goodbye = env.Program('goodbye.c') - env.Install('__ROOT__/usr/bin', hello) - env.Install('__ROOT__/usr/bin', goodbye) - env.Alias('install', '__ROOT__/usr/bin') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - <file name="goodbye.c"> - int main() { printf("Goodbye, world!\n"); } - </file> - </scons_example> - - <para> - - Or, more succinctly, listing the multiple input - files in a list - (just like you can do with any other builder): - - </para> - - <sconstruct> - env = Environment() - hello = env.Program('hello.c') - goodbye = env.Program('goodbye.c') - env.Install('__ROOT__/usr/bin', [hello, goodbye]) - env.Alias('install', '__ROOT__/usr/bin') - </sconstruct> - - <para> - - Either of these two examples yields: - - </para> - - <scons_output example="ex3"> - <scons_output_command>scons -Q install</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Installing a File Under a Different Name</title> - - <para> - - The &Install; method preserves the name - of the file when it is copied into the - destination directory. - If you need to change the name of the file - when you copy it, use the &InstallAs; function: - - </para> - - <scons_example name="ex4"> - <file name="SConstruct" printme="1"> - env = Environment() - hello = env.Program('hello.c') - env.InstallAs('__ROOT__/usr/bin/hello-new', hello) - env.Alias('install', '__ROOT__/usr/bin') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - This installs the <literal>hello</literal> - program with the name <literal>hello-new</literal> - as follows: - - </para> - - <scons_output example="ex4"> - <scons_output_command>scons -Q install</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Installing Multiple Files Under Different Names</title> - - <para> - - Lastly, if you have multiple files that all - need to be installed with different file names, - you can either call the &InstallAs; function - multiple times, or as a shorthand, - you can supply same-length lists - for both the target and source arguments: - - </para> - - <scons_example name="ex5"> - <file name="SConstruct" printme="1"> - env = Environment() - hello = env.Program('hello.c') - goodbye = env.Program('goodbye.c') - env.InstallAs(['__ROOT__/usr/bin/hello-new', - '__ROOT__/usr/bin/goodbye-new'], - [hello, goodbye]) - env.Alias('install', '__ROOT__/usr/bin') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - <file name="goodbye.c"> - int main() { printf("Goodbye, world!\n"); } - </file> - </scons_example> - - <para> - - In this case, the &InstallAs; function - loops through both lists simultaneously, - and copies each source file into its corresponding - target file name: - - </para> - - <scons_output example="ex5"> - <scons_output_command>scons -Q install</scons_output_command> - </scons_output> - - </section> diff --git a/doc/user/install.xml b/doc/user/install.xml index 37a508f..e229268 100644 --- a/doc/user/install.xml +++ b/doc/user/install.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<chapter id="chap-install" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Installing Files in Other Directories: the &Install; Builder</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -34,11 +56,16 @@ </para> - <programlisting> - env = Environment() - hello = env.Program('hello.c') - env.Install('/usr/bin', hello) - </programlisting> + <scons_example name="install_ex1"> + <file name="SConstruct" printme="1"> +env = Environment() +hello = env.Program('hello.c') +env.Install('__ROOT__/usr/bin', hello) + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -56,13 +83,10 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q /usr/bin</userinput> - Install file: "hello" as "/usr/bin/hello" - </screen> + <scons_output example="install_ex1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q __ROOT__/usr/bin</scons_output_command> + </scons_output> <para> @@ -78,12 +102,17 @@ </para> - <programlisting> - env = Environment() - hello = env.Program('hello.c') - env.Install('/usr/bin', hello) - env.Alias('install', '/usr/bin') - </programlisting> + <scons_example name="install_ex2"> + <file name="SConstruct" printme="1"> +env = Environment() +hello = env.Program('hello.c') +env.Install('__ROOT__/usr/bin', hello) +env.Alias('install', '__ROOT__/usr/bin') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -93,13 +122,10 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - % <userinput>scons -Q install</userinput> - Install file: "hello" as "/usr/bin/hello" - </screen> + <scons_output example="install_ex2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q install</scons_output_command> + </scons_output> <section> <title>Installing Multiple Files in a Directory</title> @@ -111,14 +137,22 @@ </para> - <programlisting> - env = Environment() - hello = env.Program('hello.c') - goodbye = env.Program('goodbye.c') - env.Install('/usr/bin', hello) - env.Install('/usr/bin', goodbye) - env.Alias('install', '/usr/bin') - </programlisting> + <scons_example name="install_ex3"> + <file name="SConstruct" printme="1"> +env = Environment() +hello = env.Program('hello.c') +goodbye = env.Program('goodbye.c') +env.Install('__ROOT__/usr/bin', hello) +env.Install('__ROOT__/usr/bin', goodbye) +env.Alias('install', '__ROOT__/usr/bin') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + <file name="goodbye.c"> +int main() { printf("Goodbye, world!\n"); } + </file> + </scons_example> <para> @@ -128,13 +162,13 @@ </para> - <programlisting> - env = Environment() - hello = env.Program('hello.c') - goodbye = env.Program('goodbye.c') - env.Install('/usr/bin', [hello, goodbye]) - env.Alias('install', '/usr/bin') - </programlisting> + <sconstruct> +env = Environment() +hello = env.Program('hello.c') +goodbye = env.Program('goodbye.c') +env.Install('__ROOT__/usr/bin', [hello, goodbye]) +env.Alias('install', '__ROOT__/usr/bin') + </sconstruct> <para> @@ -142,15 +176,9 @@ </para> - <screen> - % <userinput>scons -Q install</userinput> - cc -o goodbye.o -c goodbye.c - cc -o goodbye goodbye.o - Install file: "goodbye" as "/usr/bin/goodbye" - cc -o hello.o -c hello.c - cc -o hello hello.o - Install file: "hello" as "/usr/bin/hello" - </screen> + <scons_output example="install_ex3" suffix="1"> + <scons_output_command>scons -Q install</scons_output_command> + </scons_output> </section> @@ -167,12 +195,17 @@ </para> - <programlisting> - env = Environment() - hello = env.Program('hello.c') - env.InstallAs('/usr/bin/hello-new', hello) - env.Alias('install', '/usr/bin') - </programlisting> + <scons_example name="install_ex4"> + <file name="SConstruct" printme="1"> +env = Environment() +hello = env.Program('hello.c') +env.InstallAs('__ROOT__/usr/bin/hello-new', hello) +env.Alias('install', '__ROOT__/usr/bin') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -182,12 +215,9 @@ </para> - <screen> - % <userinput>scons -Q install</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - Install file: "hello" as "/usr/bin/hello-new" - </screen> + <scons_output example="install_ex4" suffix="1"> + <scons_output_command>scons -Q install</scons_output_command> + </scons_output> </section> @@ -205,15 +235,23 @@ </para> - <programlisting> - env = Environment() - hello = env.Program('hello.c') - goodbye = env.Program('goodbye.c') - env.InstallAs(['/usr/bin/hello-new', - '/usr/bin/goodbye-new'], - [hello, goodbye]) - env.Alias('install', '/usr/bin') - </programlisting> + <scons_example name="install_ex5"> + <file name="SConstruct" printme="1"> +env = Environment() +hello = env.Program('hello.c') +goodbye = env.Program('goodbye.c') +env.InstallAs(['__ROOT__/usr/bin/hello-new', + '__ROOT__/usr/bin/goodbye-new'], + [hello, goodbye]) +env.Alias('install', '__ROOT__/usr/bin') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + <file name="goodbye.c"> +int main() { printf("Goodbye, world!\n"); } + </file> + </scons_example> <para> @@ -224,14 +262,10 @@ </para> - <screen> - % <userinput>scons -Q install</userinput> - cc -o goodbye.o -c goodbye.c - cc -o goodbye goodbye.o - Install file: "goodbye" as "/usr/bin/goodbye-new" - cc -o hello.o -c hello.c - cc -o hello hello.o - Install file: "hello" as "/usr/bin/hello-new" - </screen> + <scons_output example="install_ex5" suffix="1"> + <scons_output_command>scons -Q install</scons_output_command> + </scons_output> </section> + +</chapter> diff --git a/doc/user/java.in b/doc/user/java.in deleted file mode 100644 index 5744055..0000000 --- a/doc/user/java.in +++ /dev/null @@ -1,657 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - So far, we've been using examples of - building C and C++ programs - to demonstrate the features of &SCons;. - &SCons; also supports building Java programs, - but Java builds are handled slightly differently, - which reflects the ways in which - the Java compiler and tools - build programs differently than - other languages' tool chains. - - </para> - - <section> - <title>Building Java Class Files: the &b-Java; Builder</title> - - <para> - - The basic activity when programming in Java, - of course, is to take one or more <filename>.java</filename> files - containing Java source code - and to call the Java compiler - to turn them into one or more - <filename>.class</filename> files. - In &SCons;, you do this - 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 - the <filename>.java</filename> files: - - </para> - - <scons_example name="java"> - <file name="SConstruct" printme="1"> - Java('classes', 'src') - </file> - <file name="src/Example1.java"> - public class Example1 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - <file name="src/Example2.java"> - public class Example2 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - <file name="src/Example3.java"> - public class Example3 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - </scons_example> - - <para> - - If the <filename>src</filename> directory contains - three <filename>.java</filename> source files, - then running &SCons; might look like this: - - </para> - - <scons_output example="java"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - &SCons; will actually search the <filename>src</filename> - directory tree for all of the <filename>.java</filename> files. - The Java compiler will then create the - necessary class files in the <filename>classes</filename> subdirectory, - based on the class names found in the <filename>.java</filename> files. - - </para> - - </section> - - <section> - <title>How &SCons; Handles Java Dependencies</title> - - <para> - - In addition to searching the source directory for - <filename>.java</filename> files, - &SCons; actually runs the <filename>.java</filename> files - through a stripped-down Java parser that figures out - what classes are defined. - In other words, &SCons; knows, - without you having to tell it, - what <filename>.class</filename> files - will be produced by the &javac; call. - So our one-liner example from the preceding section: - - </para> - - <scons_example name="java-classes"> - <file name="SConstruct" printme="1"> - Java('classes', 'src') - </file> - <file name="src/Example1.java"> - public class Example1 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - public class AdditionalClass1 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - <file name="src/Example2.java"> - public class Example2 - { - class Inner2 { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - } - </file> - <file name="src/Example3.java"> - public class Example3 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - public class AdditionalClass3 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - </scons_example> - - <para> - - Will not only tell you reliably - that the <filename>.class</filename> files - in the <filename>classes</filename> subdirectory - are up-to-date: - - </para> - - <scons_output example="java-classes"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q classes</scons_output_command> - </scons_output> - - <para> - - But it will also remove all of the generated - <filename>.class</filename> files, - even for inner classes, - without you having to specify them manually. - For example, if our - <filename>Example1.java</filename> - and - <filename>Example3.java</filename> - files both define additional classes, - and the class defined in <filename>Example2.java</filename> - has an inner class, - running <userinput>scons -c</userinput> - will clean up all of those <filename>.class</filename> files - as well: - - </para> - - <scons_output example="java-classes"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q -c classes</scons_output_command> - </scons_output> - - <para> - - To ensure correct handling of <filename>.class</filename> - dependencies in all cases, you need to tell &SCons; which Java - version is being used. This is needed because Java 1.5 changed - the <filename>.class</filename> file names for nested anonymous - inner classes. Use the <varname>JAVAVERSION</varname> construction - variable to specify the version in use. With Java 1.6, the - one-liner example can then be defined like this: - - </para> - - <sconstruct> - Java('classes', 'src', JAVAVERSION='1.6') - </sconstruct> - - <para> - See <varname>JAVAVERSION</varname> in the man page for more information. - </para> - - </section> - - <section> - <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 &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 &b-Jar; source: - - </para> - - <scons_example name="jar1"> - <file name="SConstruct" printme="1"> - Java(target = 'classes', source = 'src') - Jar(target = 'test.jar', source = 'classes') - </file> - <file name="src/Example1.java"> - public class Example1 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - <file name="src/Example2.java"> - public class Example2 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - <file name="src/Example3.java"> - public class Example3 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - </scons_example> - - <para> - - &SCons; will then pass that directory - to the &jar; command, - which will collect all of the underlying - <filename>.class</filename> files: - - </para> - - <scons_output example="jar1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - If you want to keep all of the - <filename>.class</filename> files - for multiple programs in one location, - and only archive some of them in - each <filename>.jar</filename> file, - 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 &b-link-Java; builder - as sources to the various &b-Jar; calls: - - </para> - - <scons_example name="jar2"> - <file name="SConstruct" printme="1"> - prog1_class_files = Java(target = 'classes', source = 'prog1') - prog2_class_files = Java(target = 'classes', source = 'prog2') - Jar(target = 'prog1.jar', source = prog1_class_files) - Jar(target = 'prog2.jar', source = prog2_class_files) - </file> - <file name="prog1/Example1.java"> - public class Example1 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - <file name="prog1/Example2.java"> - public class Example2 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - <file name="prog2/Example3.java"> - public class Example3 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - <file name="prog2/Example4.java"> - public class Example4 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - </scons_example> - - <para> - - This will then create - <filename>prog1.jar</filename> - and <filename>prog2.jar</filename> - next to the subdirectories - that contain their <filename>.java</filename> files: - - </para> - - <scons_output example="jar2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <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 &b-link-JavaH; Builder. - There are several ways of using the &JavaH; Builder. - One typical invocation might look like: - - </para> - - <scons_example name="javah"> - <file name="SConstruct" printme="1"> - classes = Java(target = 'classes', source = 'src/pkg/sub') - JavaH(target = 'native', source = classes) - </file> - <file name="src/pkg/sub/Example1.java"> - package pkg.sub; - public class Example1 - { - public static void main(String[] args) - { - } - } - </file> - <file name="src/pkg/sub/Example2.java"> - package pkg.sub; - public class Example2 - { - public static void main(String[] args) - { - } - } - </file> - <file name="src/pkg/sub/Example3.java"> - package pkg.sub; - public class Example3 - { - public static void main(String[] args) - { - } - } - </file> - </scons_example> - - <para> - - The source is a list of class files generated by the - 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 - gets converted into the <option>-d</option> - when &SCons; runs &javah;: - - </para> - - <scons_output example="javah"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - In this case, - the call to &javah; - will generate the header files - <filename>native/pkg_sub_Example1.h</filename>, - <filename>native/pkg_sub_Example2.h</filename> - and - <filename>native/pkg_sub_Example3.h</filename>. - Notice that &SCons; remembered that the class - files were generated with a target directory of - <filename>classes</filename>, - and that it then specified that target directory - as the <option>-classpath</option> option - to the call to &javah;. - - </para> - - <para> - - Although it's more convenient to use - the list of class files returned by - 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 - &cv-link-JAVACLASSDIR; construction variable - when calling &b-JavaH;: - - </para> - - <scons_example name="JAVACLASSDIR"> - <file name="SConstruct" printme="1"> - Java(target = 'classes', source = 'src/pkg/sub') - class_file_list = ['classes/pkg/sub/Example1.class', - 'classes/pkg/sub/Example2.class', - 'classes/pkg/sub/Example3.class'] - JavaH(target = 'native', source = class_file_list, JAVACLASSDIR = 'classes') - </file> - <file name="src/pkg/sub/Example1.java"> - package pkg.sub; - public class Example1 - { - public static void main(String[] args) - { - } - } - </file> - <file name="src/pkg/sub/Example2.java"> - package pkg.sub; - public class Example2 - { - public static void main(String[] args) - { - } - } - </file> - <file name="src/pkg/sub/Example3.java"> - package pkg.sub; - public class Example3 - { - public static void main(String[] args) - { - } - } - </file> - </scons_example> - - <para> - - The &cv-JAVACLASSDIR; value then - gets converted into the <option>-classpath</option> - when &SCons; runs &javah;: - - </para> - - <scons_output example="JAVACLASSDIR"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - 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 &b-JavaH; Builder: - - </para> - - <scons_example name="javah_file"> - <file name="SConstruct" printme="1"> - classes = Java(target = 'classes', source = 'src/pkg/sub') - JavaH(target = File('native.h'), source = classes) - </file> - <file name="src/pkg/sub/Example1.java"> - package pkg.sub; - public class Example1 - { - public static void main(String[] args) - { - } - } - </file> - <file name="src/pkg/sub/Example2.java"> - package pkg.sub; - public class Example2 - { - public static void main(String[] args) - { - } - } - </file> - <file name="src/pkg/sub/Example3.java"> - package pkg.sub; - public class Example3 - { - public static void main(String[] args) - { - } - } - </file> - </scons_example> - - <para> - - Because &SCons; assumes by default - 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>. - When a file is used, though, - &SCons; correctly converts the file name - into the &javah; <option>-o</option> option: - - </para> - - <scons_output example="javah_file"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Building RMI Stub and Skeleton Class Files: the &b-RMIC; Builder</title> - - <para> - - You can generate Remote Method Invocation stubs - by using the &b-link-RMIC; Builder. - The source is a list of directories, - 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 - be placed: - - </para> - - <scons_example name="RMIC"> - <file name="SConstruct" printme="1"> - classes = Java(target = 'classes', source = 'src/pkg/sub') - RMIC(target = 'outdir', source = classes) - </file> - <file name="src/pkg/sub/Example1.java"> - package pkg.sub; - public class Example1 - { - public static void main(String[] args) - { - } - } - </file> - <file name="src/pkg/sub/Example2.java"> - package pkg.sub; - public class Example2 - { - public static void main(String[] args) - { - } - } - </file> - </scons_example> - - <para> - - 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;: - - </para> - - <scons_output example="RMIC"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - This example would generate the files - <filename>outdir/pkg/sub/Example1_Skel.class</filename>, - <filename>outdir/pkg/sub/Example1_Stub.class</filename>, - <filename>outdir/pkg/sub/Example2_Skel.class</filename> and - <filename>outdir/pkg/sub/Example2_Stub.class</filename>. - - </para> - - </section> diff --git a/doc/user/java.xml b/doc/user/java.xml index 5827eec..95b20d2 100644 --- a/doc/user/java.xml +++ b/doc/user/java.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-java" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Java Builds</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -57,9 +78,38 @@ </para> - <programlisting> - Java('classes', 'src') - </programlisting> + <scons_example name="java_java"> + <file name="SConstruct" printme="1"> +Java('classes', 'src') + </file> + <file name="src/Example1.java"> +public class Example1 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + <file name="src/Example2.java"> +public class Example2 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + <file name="src/Example3.java"> +public class Example3 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + </scons_example> <para> @@ -69,10 +119,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java - </screen> + <scons_output example="java_java" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -104,9 +153,54 @@ </para> - <programlisting> - Java('classes', 'src') - </programlisting> + <scons_example name="java_java-classes"> + <file name="SConstruct" printme="1"> +Java('classes', 'src') + </file> + <file name="src/Example1.java"> +public class Example1 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} +public class AdditionalClass1 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + <file name="src/Example2.java"> +public class Example2 +{ + class Inner2 { + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } + } +} + </file> + <file name="src/Example3.java"> +public class Example3 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} +public class AdditionalClass3 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + </scons_example> <para> @@ -117,12 +211,10 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java - % <userinput>scons -Q classes</userinput> - scons: `classes' is up to date. - </screen> + <scons_output example="java_java-classes" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q classes</scons_output_command> + </scons_output> <para> @@ -143,17 +235,10 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java - % <userinput>scons -Q -c classes</userinput> - Removed classes/Example1.class - Removed classes/AdditionalClass1.class - Removed classes/Example2$Inner2.class - Removed classes/Example2.class - Removed classes/Example3.class - Removed classes/AdditionalClass3.class - </screen> + <scons_output example="java_java-classes" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q -c classes</scons_output_command> + </scons_output> <para> @@ -167,9 +252,9 @@ </para> - <programlisting> - Java('classes', 'src', JAVAVERSION='1.6') - </programlisting> + <sconstruct> +Java('classes', 'src', JAVAVERSION='1.6') + </sconstruct> <para> See <varname>JAVAVERSION</varname> in the man page for more information. @@ -193,10 +278,39 @@ </para> - <programlisting> - Java(target = 'classes', source = 'src') - Jar(target = 'test.jar', source = 'classes') - </programlisting> + <scons_example name="java_jar1"> + <file name="SConstruct" printme="1"> +Java(target = 'classes', source = 'src') +Jar(target = 'test.jar', source = 'classes') + </file> + <file name="src/Example1.java"> +public class Example1 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + <file name="src/Example2.java"> +public class Example2 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + <file name="src/Example3.java"> +public class Example3 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + </scons_example> <para> @@ -207,11 +321,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java - jar cf test.jar classes - </screen> + <scons_output example="java_jar1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -230,12 +342,50 @@ </para> - <programlisting> - prog1_class_files = Java(target = 'classes', source = 'prog1') - prog2_class_files = Java(target = 'classes', source = 'prog2') - Jar(target = 'prog1.jar', source = prog1_class_files) - Jar(target = 'prog2.jar', source = prog2_class_files) - </programlisting> + <scons_example name="java_jar2"> + <file name="SConstruct" printme="1"> +prog1_class_files = Java(target = 'classes', source = 'prog1') +prog2_class_files = Java(target = 'classes', source = 'prog2') +Jar(target = 'prog1.jar', source = prog1_class_files) +Jar(target = 'prog2.jar', source = prog2_class_files) + </file> + <file name="prog1/Example1.java"> +public class Example1 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + <file name="prog1/Example2.java"> +public class Example2 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + <file name="prog2/Example3.java"> +public class Example3 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + <file name="prog2/Example4.java"> +public class Example4 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + </scons_example> <para> @@ -247,13 +397,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - javac -d classes -sourcepath prog1 prog1/Example1.java prog1/Example2.java - javac -d classes -sourcepath prog2 prog2/Example3.java prog2/Example4.java - jar cf prog1.jar -C classes Example1.class -C classes Example2.class - jar cf prog2.jar -C classes Example3.class -C classes Example4.class - </screen> + <scons_output example="java_jar2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -270,10 +416,39 @@ </para> - <programlisting> - classes = Java(target = 'classes', source = 'src/pkg/sub') - JavaH(target = 'native', source = classes) - </programlisting> + <scons_example name="java_javah"> + <file name="SConstruct" printme="1"> +classes = Java(target = 'classes', source = 'src/pkg/sub') +JavaH(target = 'native', source = classes) + </file> + <file name="src/pkg/sub/Example1.java"> +package pkg.sub; +public class Example1 +{ + public static void main(String[] args) + { + } +} + </file> + <file name="src/pkg/sub/Example2.java"> +package pkg.sub; +public class Example2 +{ + public static void main(String[] args) + { + } +} + </file> + <file name="src/pkg/sub/Example3.java"> +package pkg.sub; +public class Example3 +{ + public static void main(String[] args) + { + } +} + </file> + </scons_example> <para> @@ -287,11 +462,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - javac -d classes -sourcepath src/pkg/sub src/pkg/sub/Example1.java src/pkg/sub/Example2.java src/pkg/sub/Example3.java - javah -d native -classpath classes pkg.sub.Example1 pkg.sub.Example2 pkg.sub.Example3 - </screen> + <scons_output example="java_javah" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -327,13 +500,42 @@ </para> - <programlisting> - Java(target = 'classes', source = 'src/pkg/sub') - class_file_list = ['classes/pkg/sub/Example1.class', - 'classes/pkg/sub/Example2.class', - 'classes/pkg/sub/Example3.class'] - JavaH(target = 'native', source = class_file_list, JAVACLASSDIR = 'classes') - </programlisting> + <scons_example name="java_JAVACLASSDIR"> + <file name="SConstruct" printme="1"> +Java(target = 'classes', source = 'src/pkg/sub') +class_file_list = ['classes/pkg/sub/Example1.class', + 'classes/pkg/sub/Example2.class', + 'classes/pkg/sub/Example3.class'] +JavaH(target = 'native', source = class_file_list, JAVACLASSDIR = 'classes') + </file> + <file name="src/pkg/sub/Example1.java"> +package pkg.sub; +public class Example1 +{ + public static void main(String[] args) + { + } +} + </file> + <file name="src/pkg/sub/Example2.java"> +package pkg.sub; +public class Example2 +{ + public static void main(String[] args) + { + } +} + </file> + <file name="src/pkg/sub/Example3.java"> +package pkg.sub; +public class Example3 +{ + public static void main(String[] args) + { + } +} + </file> + </scons_example> <para> @@ -343,11 +545,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - javac -d classes -sourcepath src/pkg/sub src/pkg/sub/Example1.java src/pkg/sub/Example2.java src/pkg/sub/Example3.java - javah -d native -classpath classes pkg.sub.Example1 pkg.sub.Example2 pkg.sub.Example3 - </screen> + <scons_output example="java_JAVACLASSDIR" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -358,10 +558,39 @@ </para> - <programlisting> - classes = Java(target = 'classes', source = 'src/pkg/sub') - JavaH(target = File('native.h'), source = classes) - </programlisting> + <scons_example name="java_javah_file"> + <file name="SConstruct" printme="1"> +classes = Java(target = 'classes', source = 'src/pkg/sub') +JavaH(target = File('native.h'), source = classes) + </file> + <file name="src/pkg/sub/Example1.java"> +package pkg.sub; +public class Example1 +{ + public static void main(String[] args) + { + } +} + </file> + <file name="src/pkg/sub/Example2.java"> +package pkg.sub; +public class Example2 +{ + public static void main(String[] args) + { + } +} + </file> + <file name="src/pkg/sub/Example3.java"> +package pkg.sub; +public class Example3 +{ + public static void main(String[] args) + { + } +} + </file> + </scons_example> <para> @@ -376,11 +605,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - javac -d classes -sourcepath src/pkg/sub src/pkg/sub/Example1.java src/pkg/sub/Example2.java src/pkg/sub/Example3.java - javah -o native.h -classpath classes pkg.sub.Example1 pkg.sub.Example2 pkg.sub.Example3 - </screen> + <scons_output example="java_javah_file" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -400,10 +627,30 @@ </para> - <programlisting> - classes = Java(target = 'classes', source = 'src/pkg/sub') - RMIC(target = 'outdir', source = classes) - </programlisting> + <scons_example name="java_RMIC"> + <file name="SConstruct" printme="1"> +classes = Java(target = 'classes', source = 'src/pkg/sub') +RMIC(target = 'outdir', source = classes) + </file> + <file name="src/pkg/sub/Example1.java"> +package pkg.sub; +public class Example1 +{ + public static void main(String[] args) + { + } +} + </file> + <file name="src/pkg/sub/Example2.java"> +package pkg.sub; +public class Example2 +{ + public static void main(String[] args) + { + } +} + </file> + </scons_example> <para> @@ -414,11 +661,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - javac -d classes -sourcepath src/pkg/sub src/pkg/sub/Example1.java src/pkg/sub/Example2.java - rmic -d outdir -classpath classes pkg.sub.Example1 pkg.sub.Example2 - </screen> + <scons_output example="java_RMIC" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -431,3 +676,5 @@ </para> </section> + +</chapter> diff --git a/doc/user/less-simple.in b/doc/user/less-simple.in deleted file mode 100644 index f3c251f..0000000 --- a/doc/user/less-simple.in +++ /dev/null @@ -1,623 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - In this chapter, - you will see several examples of - very simple build configurations using &SCons;, - which will demonstrate how easy - it is to use &SCons; to - build programs from several different programming languages - on different types of systems. - - </para> - - <section> - <title>Specifying the Name of the Target (Output) File</title> - - <para> - - 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 - executable program from the &hello_c; source file - will build an executable program named &hello; on POSIX systems, - and an executable program named &hello_exe; on Windows systems: - - </para> - - <programlisting> - Program('hello.c') - </programlisting> - - <para> - - If you want to build a program with - a different name than the base of the source file name, - you simply put the target file name - to the left of the source file name: - - </para> - - <scons_example name="target"> - <file name="SConstruct" printme="1"> - Program('new_hello', 'hello.c') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - (&SCons; requires the target file name first, - followed by the source file name, - so that the order mimics that of an - assignment statement in most programming languages, - including Python: - <literal>"program = source files"</literal>.) - - </para> - - <para> - - Now &SCons; will build an executable program - named &new_hello; when run on a POSIX system: - - </para> - - <scons_output example="target" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - And &SCons; will build an executable program - named &new_hello_exe; when run on a Windows system: - - </para> - - <scons_output example="target" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Compiling Multiple Source Files</title> - - <para> - - You've just seen how to configure &SCons; - to compile a program from a single source file. - It's more common, of course, - that you'll need to build a program from - many input source files, not just one. - To do this, you need to put the - source files in a Python list - (enclosed in square brackets), - like so: - - </para> - - <scons_example name="ex2"> - <file name="SConstruct" printme="1"> - Program(['prog.c', 'file1.c', 'file2.c']) - </file> - <file name="prog.c"> - int main() { printf("prog.c\n"); } - </file> - <file name="file1.c"> - void file1() { printf("file1.c\n"); } - </file> - <file name="file2.c"> - void file2() { printf("file2.c\n"); } - </file> - </scons_example> - - <para> - - A build of the above example would look like: - - </para> - - <scons_output example="ex2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Notice that &SCons; - deduces the output program name - from the first source file specified - in the list--that is, - because the first source file was &prog_c;, - &SCons; will name the resulting program &prog; - (or &prog_exe; on a Windows system). - If you want to specify a different program name, - then (as we've seen in the previous section) - you slide the list of source files - over to the right - to make room for the output program file name. - (&SCons; puts the output file name to the left - of the source file names - so that the order mimics that of an - assignment statement: "program = source files".) - This makes our example: - - </para> - - <scons_example name="ex3"> - <file name="SConstruct" printme="1"> - Program('program', ['prog.c', 'file1.c', 'file2.c']) - </file> - <file name="prog.c"> - int main() { printf("prog.c\n"); } - </file> - <file name="file1.c"> - void file1() { printf("file1.c\n"); } - </file> - <file name="file2.c"> - void file2() { printf("file2.c\n"); } - </file> - </scons_example> - - <para> - - On Linux, a build of this example would look like: - - </para> - - <scons_output example="ex3" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Or on Windows: - - </para> - - <scons_output example="ex3" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Making a list of files with &Glob;</title> - - <para> - - You can also use the &Glob; function to find all files matching a - certain template, using the standard shell pattern matching - characters <literal>*</literal>, <literal>?</literal> - and <literal>[abc]</literal> to match any of - <literal>a</literal>, <literal>b</literal> or <literal>c</literal>. - <literal>[!abc]</literal> is also supported, - to match any character <emphasis>except</emphasis> - <literal>a</literal>, <literal>b</literal> or <literal>c</literal>. - This makes many multi-source-file builds quite easy: - - </para> - - <sconstruct> - Program('program', Glob('*.c')) - </sconstruct> - - <para> - - The SCons man page has more details on using &Glob; - with variant directories - (see <xref linkend="chap-variants"></xref>, below) - and repositories - (see <xref linkend="chap-repositories"></xref>, below), - and returning strings rather than Nodes. - - </para> - - </section> - - <section> - <title>Specifying Single Files Vs. Lists of Files</title> - - <para> - - We've now shown you two ways to specify - the source for a program, - one with a list of files: - - </para> - - <sconstruct> - Program('hello', ['file1.c', 'file2.c']) - </sconstruct> - - <para> - - And one with a single file: - - </para> - - <sconstruct> - Program('hello', 'hello.c') - </sconstruct> - - <para> - - You could actually put a single file name in a list, too, - which you might prefer just for the sake of consistency: - - </para> - - <sconstruct> - Program('hello', ['hello.c']) - </sconstruct> - - <para> - - &SCons; functions will accept a single file name in either form. - In fact, internally, &SCons; treats all input as lists of files, - but allows you to omit the square brackets - to cut down a little on the typing - when there's only a single file name. - - </para> - - <important> - - <para> - - Although &SCons; functions - are forgiving about whether or not you - use a string vs. a list for a single file name, - Python itself is more strict about - treating lists and strings differently. - So where &SCons; allows either - a string or list: - - </para> - - <sconstruct> - # The following two calls both work correctly: - Program('program1', 'program1.c') - Program('program2', ['program2.c']) - </sconstruct> - - <para> - - Trying to do "Python things" that mix strings and - lists will cause errors or lead to incorrect results: - - </para> - - <sconstruct> - common_sources = ['file1.c', 'file2.c'] - - # THE FOLLOWING IS INCORRECT AND GENERATES A PYTHON ERROR - # BECAUSE IT TRIES TO ADD A STRING TO A LIST: - Program('program1', common_sources + 'program1.c') - - # The following works correctly, because it's adding two - # lists together to make another list. - Program('program2', common_sources + ['program2.c']) - </sconstruct> - - </important> - - </section> - - <section> - <title>Making Lists of Files Easier to Read</title> - - <para> - - One drawback to the use of a Python list - for source files is that - each file name must be enclosed in quotes - (either single quotes or double quotes). - This can get cumbersome and difficult to read - when the list of file names is long. - Fortunately, &SCons; and Python provide a number of ways - to make sure that - the &SConstruct; file stays easy to read. - - </para> - - <para> - - To make long lists of file names - easier to deal with, &SCons; provides a - &Split; function - that takes a quoted list of file names, - with the names separated by spaces or other white-space characters, - and turns it into a list of separate file names. - Using the &Split; function turns the - previous example into: - - </para> - - <programlisting> - Program('program', Split('main.c file1.c file2.c')) - </programlisting> - - <para> - - (If you're already familiar with Python, - you'll have realized that this is similar to the - <function>split()</function> method - in the Python standard <function>string</function> module. - Unlike the <function>split()</function> member function of strings, - however, the &Split; function - does not require a string as input - and will wrap up a single non-string object in a list, - or return its argument untouched if it's already a list. - This comes in handy as a way to make sure - arbitrary values can be passed to &SCons; functions - without having to check the type of the variable by hand.) - - </para> - - <para> - - Putting the call to the &Split; function - 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 - &b-Program; function: - - </para> - - <programlisting> - src_files = Split('main.c file1.c file2.c') - Program('program', src_files) - </programlisting> - - <para> - - Lastly, the &Split; function - doesn't care how much white space separates - the file names in the quoted string. - This allows you to create lists of file - names that span multiple lines, - which often makes for easier editing: - - </para> - - <programlisting> - src_files = Split("""main.c - file1.c - file2.c""") - Program('program', src_files) - </programlisting> - - <para> - - (Note in this example that we used - the Python "triple-quote" syntax, - which allows a string to contain - multiple lines. - The three quotes can be either - single or double quotes.) - - </para> - - </section> - - <section> - <title>Keyword Arguments</title> - - <para> - - &SCons; also allows you to identify - the output file and input source files - using Python keyword arguments. - The output file is known as the - <emphasis>target</emphasis>, - and the source file(s) are known (logically enough) as the - <emphasis>source</emphasis>. - The Python syntax for this is: - - </para> - - <programlisting> - src_files = Split('main.c file1.c file2.c') - Program(target = 'program', source = src_files) - </programlisting> - - <para> - - Because the keywords explicitly identify - what each argument is, - you can actually reverse the order if you prefer: - - </para> - - <programlisting> - src_files = Split('main.c file1.c file2.c') - Program(source = src_files, target = 'program') - </programlisting> - - <para> - - Whether or not you choose to use keyword arguments - to identify the target and source files, - and the order in which you specify them - when using keywords, - are purely personal choices; - &SCons; functions the same regardless. - - </para> - - </section> - - <section> - <title>Compiling Multiple Programs</title> - - <para> - - In order to compile multiple programs - within the same &SConstruct; file, - simply call the &Program; method - multiple times, - once for each program you need to build: - - </para> - - <scons_example name="ex4"> - <file name="SConstruct" printme="1"> - Program('foo.c') - Program('bar', ['bar1.c', 'bar2.c']) - </file> - <file name="foo.c"> - int main() { printf("foo.c\n"); } - </file> - <file name="bar1.c"> - int main() { printf("bar1.c\n"); } - </file> - <file name="bar2.c"> - void bar2() { printf("bar2.c\n"); } - </file> - </scons_example> - - <para> - - &SCons; would then build the programs as follows: - - </para> - - <scons_output example="ex4"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Notice that &SCons; does not necessarily build the - programs in the same order in which you specify - them in the &SConstruct; file. - &SCons; does, however, recognize that - the individual object files must be built - before the resulting program can be built. - We'll discuss this in greater detail in - the "Dependencies" section, below. - - </para> - - </section> - - <section> - <title>Sharing Source Files Between Multiple Programs</title> - - <para> - - It's common to re-use code by sharing source files - between multiple programs. - One way to do this is to create a library - from the common source files, - which can then be linked into resulting programs. - (Creating libraries is discussed in - <xref linkend="chap-libraries"></xref>, below.) - - </para> - - <para> - - A more straightforward, but perhaps less convenient, - way to share source files between multiple programs - is simply to include the common files - in the lists of source files for each program: - - </para> - - <scons_example name="ex5"> - <file name="SConstruct" printme="1"> - Program(Split('foo.c common1.c common2.c')) - Program('bar', Split('bar1.c bar2.c common1.c common2.c')) - </file> - <file name="foo.c"> - int main() { printf("foo.c\n"); } - </file> - <file name="bar1.c"> - int main() { printf("bar1.c\n"); } - </file> - <file name="bar2.c"> - int bar2() { printf("bar2.c\n"); } - </file> - <file name="common1.c"> - void common1() { printf("common1.c\n"); } - </file> - <file name="common2.c"> - void common22() { printf("common2.c\n"); } - </file> - </scons_example> - - <para> - - &SCons; recognizes that the object files for - the &common1_c; and &common2_c; source files - each need to be built only once, - even though the resulting object files are - each linked in to both of the resulting executable programs: - - </para> - - <scons_output example="ex5"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - If two or more programs - share a lot of common source files, - repeating the common files in the list for each program - can be a maintenance problem when you need to change the - list of common files. - You can simplify this by creating a separate Python list - to hold the common file names, - and concatenating it with other lists - using the Python + operator: - - </para> - - <programlisting> - common = ['common1.c', 'common2.c'] - foo_files = ['foo.c'] + common - bar_files = ['bar1.c', 'bar2.c'] + common - Program('foo', foo_files) - Program('bar', bar_files) - </programlisting> - - <para> - - This is functionally equivalent to the previous example. - - </para> - - </section> diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml index f41ea79..5bda302 100644 --- a/doc/user/less-simple.xml +++ b/doc/user/less-simple.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-less-simple" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Less Simple Things to Do With Builds</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -51,7 +72,7 @@ </para> <programlisting> - Program('hello.c') +Program('hello.c') </programlisting> <para> @@ -63,9 +84,14 @@ </para> - <programlisting> - Program('new_hello', 'hello.c') - </programlisting> + <scons_example name="lesssimple_target"> + <file name="SConstruct" printme="1"> +Program('new_hello', 'hello.c') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -85,11 +111,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o new_hello hello.o - </screen> + <scons_output example="lesssimple_target" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -98,12 +122,9 @@ </para> - <screen> - C:\><userinput>scons -Q</userinput> - cl /Fohello.obj /c hello.c /nologo - link /nologo /OUT:new_hello.exe hello.obj - embedManifestExeCheck(target, source, env) - </screen> + <scons_output example="lesssimple_target" os="win32" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -124,9 +145,20 @@ </para> - <programlisting> - Program(['prog.c', 'file1.c', 'file2.c']) - </programlisting> + <scons_example name="lesssimple_ex2"> + <file name="SConstruct" printme="1"> +Program(['prog.c', 'file1.c', 'file2.c']) + </file> + <file name="prog.c"> +int main() { printf("prog.c\n"); } + </file> + <file name="file1.c"> +void file1() { printf("file1.c\n"); } + </file> + <file name="file2.c"> +void file2() { printf("file2.c\n"); } + </file> + </scons_example> <para> @@ -134,13 +166,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o file1.o -c file1.c - cc -o file2.o -c file2.c - cc -o prog.o -c prog.c - cc -o prog prog.o file1.o file2.o - </screen> + <scons_output example="lesssimple_ex2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -164,9 +192,20 @@ </para> - <programlisting> - Program('program', ['prog.c', 'file1.c', 'file2.c']) - </programlisting> + <scons_example name="lesssimple_ex3"> + <file name="SConstruct" printme="1"> +Program('program', ['prog.c', 'file1.c', 'file2.c']) + </file> + <file name="prog.c"> +int main() { printf("prog.c\n"); } + </file> + <file name="file1.c"> +void file1() { printf("file1.c\n"); } + </file> + <file name="file2.c"> +void file2() { printf("file2.c\n"); } + </file> + </scons_example> <para> @@ -174,13 +213,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o file1.o -c file1.c - cc -o file2.o -c file2.c - cc -o prog.o -c prog.c - cc -o program prog.o file1.o file2.o - </screen> + <scons_output example="lesssimple_ex3" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -188,14 +223,9 @@ </para> - <screen> - C:\><userinput>scons -Q</userinput> - cl /Fofile1.obj /c file1.c /nologo - cl /Fofile2.obj /c file2.c /nologo - cl /Foprog.obj /c prog.c /nologo - link /nologo /OUT:program.exe prog.obj file1.obj file2.obj - embedManifestExeCheck(target, source, env) - </screen> + <scons_output example="lesssimple_ex3" os="win32" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -216,9 +246,9 @@ </para> - <programlisting> - Program('program', Glob('*.c')) - </programlisting> + <sconstruct> +Program('program', Glob('*.c')) + </sconstruct> <para> @@ -244,9 +274,9 @@ </para> - <programlisting> - Program('hello', ['file1.c', 'file2.c']) - </programlisting> + <sconstruct> +Program('hello', ['file1.c', 'file2.c']) + </sconstruct> <para> @@ -254,9 +284,9 @@ </para> - <programlisting> - Program('hello', 'hello.c') - </programlisting> + <sconstruct> +Program('hello', 'hello.c') + </sconstruct> <para> @@ -265,9 +295,9 @@ </para> - <programlisting> - Program('hello', ['hello.c']) - </programlisting> + <sconstruct> +Program('hello', ['hello.c']) + </sconstruct> <para> @@ -293,11 +323,11 @@ </para> - <programlisting> - # The following two calls both work correctly: - Program('program1', 'program1.c') - Program('program2', ['program2.c']) - </programlisting> + <sconstruct> +# The following two calls both work correctly: +Program('program1', 'program1.c') +Program('program2', ['program2.c']) + </sconstruct> <para> @@ -306,17 +336,17 @@ </para> - <programlisting> - common_sources = ['file1.c', 'file2.c'] + <sconstruct> +common_sources = ['file1.c', 'file2.c'] - # THE FOLLOWING IS INCORRECT AND GENERATES A PYTHON ERROR - # BECAUSE IT TRIES TO ADD A STRING TO A LIST: - Program('program1', common_sources + 'program1.c') +# THE FOLLOWING IS INCORRECT AND GENERATES A PYTHON ERROR +# BECAUSE IT TRIES TO ADD A STRING TO A LIST: +Program('program1', common_sources + 'program1.c') - # The following works correctly, because it's adding two - # lists together to make another list. - Program('program2', common_sources + ['program2.c']) - </programlisting> +# The following works correctly, because it's adding two +# lists together to make another list. +Program('program2', common_sources + ['program2.c']) + </sconstruct> </important> @@ -353,7 +383,7 @@ </para> <programlisting> - Program('program', Split('main.c file1.c file2.c')) +Program('program', Split('main.c file1.c file2.c')) </programlisting> <para> @@ -387,8 +417,8 @@ </para> <programlisting> - src_files = Split('main.c file1.c file2.c') - Program('program', src_files) +src_files = Split('main.c file1.c file2.c') +Program('program', src_files) </programlisting> <para> @@ -403,10 +433,10 @@ </para> <programlisting> - src_files = Split("""main.c - file1.c - file2.c""") - Program('program', src_files) +src_files = Split("""main.c + file1.c + file2.c""") +Program('program', src_files) </programlisting> <para> @@ -439,8 +469,8 @@ </para> <programlisting> - src_files = Split('main.c file1.c file2.c') - Program(target = 'program', source = src_files) +src_files = Split('main.c file1.c file2.c') +Program(target = 'program', source = src_files) </programlisting> <para> @@ -452,8 +482,8 @@ </para> <programlisting> - src_files = Split('main.c file1.c file2.c') - Program(source = src_files, target = 'program') +src_files = Split('main.c file1.c file2.c') +Program(source = src_files, target = 'program') </programlisting> <para> @@ -482,10 +512,21 @@ </para> - <programlisting> - Program('foo.c') - Program('bar', ['bar1.c', 'bar2.c']) - </programlisting> + <scons_example name="lesssimple_ex4"> + <file name="SConstruct" printme="1"> +Program('foo.c') +Program('bar', ['bar1.c', 'bar2.c']) + </file> + <file name="foo.c"> +int main() { printf("foo.c\n"); } + </file> + <file name="bar1.c"> +int main() { printf("bar1.c\n"); } + </file> + <file name="bar2.c"> +void bar2() { printf("bar2.c\n"); } + </file> + </scons_example> <para> @@ -493,14 +534,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o bar1.o -c bar1.c - cc -o bar2.o -c bar2.c - cc -o bar bar1.o bar2.o - cc -o foo.o -c foo.c - cc -o foo foo.o - </screen> + <scons_output example="lesssimple_ex4" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -541,10 +577,27 @@ </para> - <programlisting> - Program(Split('foo.c common1.c common2.c')) - Program('bar', Split('bar1.c bar2.c common1.c common2.c')) - </programlisting> + <scons_example name="lesssimple_ex5"> + <file name="SConstruct" printme="1"> +Program(Split('foo.c common1.c common2.c')) +Program('bar', Split('bar1.c bar2.c common1.c common2.c')) + </file> + <file name="foo.c"> +int main() { printf("foo.c\n"); } + </file> + <file name="bar1.c"> +int main() { printf("bar1.c\n"); } + </file> + <file name="bar2.c"> +int bar2() { printf("bar2.c\n"); } + </file> + <file name="common1.c"> +void common1() { printf("common1.c\n"); } + </file> + <file name="common2.c"> +void common22() { printf("common2.c\n"); } + </file> + </scons_example> <para> @@ -556,16 +609,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o bar1.o -c bar1.c - cc -o bar2.o -c bar2.c - cc -o common1.o -c common1.c - cc -o common2.o -c common2.c - cc -o bar bar1.o bar2.o common1.o common2.o - cc -o foo.o -c foo.c - cc -o foo foo.o common1.o common2.o - </screen> + <scons_output example="lesssimple_ex5" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -582,11 +628,11 @@ </para> <programlisting> - common = ['common1.c', 'common2.c'] - foo_files = ['foo.c'] + common - bar_files = ['bar1.c', 'bar2.c'] + common - Program('foo', foo_files) - Program('bar', bar_files) +common = ['common1.c', 'common2.c'] +foo_files = ['foo.c'] + common +bar_files = ['bar1.c', 'bar2.c'] + common +Program('foo', foo_files) +Program('bar', bar_files) </programlisting> <para> @@ -596,3 +642,5 @@ </para> </section> + +</chapter> diff --git a/doc/user/libraries.in b/doc/user/libraries.in deleted file mode 100644 index d8a6b49..0000000 --- a/doc/user/libraries.in +++ /dev/null @@ -1,445 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - It's often useful to organize large software projects - by collecting parts of the software into one or more libraries. - &SCons; makes it easy to create libraries - and to use them in the programs. - - </para> - - <section> - <title>Building Libraries</title> - - <para> - - You build your own libraries by specifying &b-link-Library; - instead of &b-link-Program;: - - </para> - - <scons_example name="ex1" printme="1"> - <file name="SConstruct" printme="1"> - Library('foo', ['f1.c', 'f2.c', 'f3.c']) - </file> - <file name="f1.c"> - void f1() { printf("f1.c\n"); } - </file> - <file name="f2.c"> - void f2() { printf("f2.c\n"); } - </file> - <file name="f3.c"> - void f3() { printf("f3.c\n"); } - </file> - </scons_example> - - <para> - - &SCons; uses the appropriate library prefix and suffix for your system. - So on POSIX or Linux systems, - the above example would build as follows - (although &ranlib; may not be called on all systems): - - </para> - - <scons_output example="ex1" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - On a Windows system, - a build of the above example would look like: - - </para> - - <scons_output example="ex1" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - The rules for the target name of the library - are similar to those for programs: - if you don't explicitly specify a target library name, - &SCons; will deduce one from the - name of the first source file specified, - and &SCons; will add an appropriate - file prefix and suffix if you leave them off. - - </para> - - <section> - <title>Building Libraries From Source Code or Object Files</title> - - <para> - - The previous example shows building a library from a - list of source files. - You can, however, also give the &b-link-Library; call - object files, - and it will correctly realize - In fact, you can arbitrarily mix source code files - and object files in the source list: - - </para> - - <scons_example name="objects" printme="1"> - <file name="SConstruct" printme="1"> - Library('foo', ['f1.c', 'f2.o', 'f3.c', 'f4.o']) - </file> - <file name="f1.c"> - void f1() { printf("f1.c\n"); } - </file> - <file name="f2.o"> - object file - </file> - <file name="f3.c"> - void f3() { printf("f3.c\n"); } - </file> - <file name="f4.o"> - object file - </file> - </scons_example> - - <para> - - And SCons realizes that only the source code files - must be compiled into object files - before creating the final library: - - </para> - - <scons_output example="objects" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Of course, in this example, the object files - must already exist for the build to succeed. - See <xref linkend="chap-nodes"></xref>, below, - for information about how you can - build object files explicitly - and include the built files in a library. - - </para> - - </section> - - <section> - <title>Building Static Libraries Explicitly: the &b-StaticLibrary; Builder</title> - - <para> - - 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 &b-link-StaticLibrary; function - instead of &b-Library;: - - </para> - - <scons_example name="StaticLibrary" printme="1"> - <file name="SConstruct" printme="1"> - StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) - </file> - </scons_example> - - <para> - - There is no functional difference between the - &b-link-StaticLibrary; and &b-Library; functions. - - </para> - - </section> - - <section> - <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 &b-link-SharedLibrary; function: - - </para> - - <scons_example name="SharedLibrary" printme="1"> - <file name="SConstruct" printme="1"> - SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) - </file> - <file name="f1.c"> - void f1() { printf("f1.c\n"); } - </file> - <file name="f2.c"> - void f2() { printf("f2.c\n"); } - </file> - <file name="f3.c"> - void f3() { printf("f3.c\n"); } - </file> - </scons_example> - - <para> - - The output on POSIX: - - </para> - - <scons_output example="SharedLibrary" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - And the output on Windows: - - </para> - - <scons_output example="SharedLibrary" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Notice again that &SCons; takes care of - building the output file correctly, - adding the <literal>-shared</literal> option - for a POSIX compilation, - and the <literal>/dll</literal> option on Windows. - - </para> - - </section> - - </section> - - <section> - <title>Linking with Libraries</title> - - <para> - - 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 &cv-link-LIBS; construction variable, - and by specifying the directory in which - the library will be found in the - &cv-link-LIBPATH; construction variable: - - <!-- In the preceding paragraph, the "$" notation for - LIBS, LIBPATH etc. is used for the first time. - Maybe some words of explanation would be nice. --> - - </para> - - <scons_example name="ex2"> - <file name="SConstruct" printme="1"> - Library('foo', ['f1.c', 'f2.c', 'f3.c']) - Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.') - </file> - <file name="f1.c"> - int main() { printf("Hello, world!\n"); } - </file> - <file name="f2.c"> - int main() { printf("Hello, world!\n"); } - </file> - <file name="f3.c"> - int main() { printf("Hello, world!\n"); } - </file> - <file name="prog.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Notice, of course, that you don't need to specify a library - prefix (like <literal>lib</literal>) - or suffix (like <literal>.a</literal> or <literal>.lib</literal>). - &SCons; uses the correct prefix or suffix for the current system. - - </para> - - <para> - - On a POSIX or Linux system, - a build of the above example would look like: - - </para> - - <scons_output example="ex2" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - On a Windows system, - a build of the above example would look like: - - </para> - - <scons_output example="ex2" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - As usual, notice that &SCons; has taken care - of constructing the correct command lines - to link with the specified library on each system. - - </para> - - <para> - - Note also that, - if you only have a single library to link with, - you can specify the library name in single string, - instead of a Python list, - so that: - - </para> - - <sconstruct> - Program('prog.c', LIBS='foo', LIBPATH='.') - </sconstruct> - - <para> - - is equivalent to: - - </para> - - <sconstruct> - Program('prog.c', LIBS=['foo'], LIBPATH='.') - </sconstruct> - - <para> - - This is similar to the way that &SCons; - handles either a string or a list to - specify a single source file. - - </para> - - </section> - - <section> - <title>Finding Libraries: the &cv-LIBPATH; Construction Variable</title> - - <para> - - By default, the linker will only look in - certain system-defined directories for libraries. - &SCons; knows how to look for libraries - in directories that you specify with the - &cv-link-LIBPATH; construction variable. - &cv-LIBPATH; consists of a list of - directory names, like so: - - </para> - - <scons_example name="ex3"> - <file name="SConstruct" printme="1"> - Program('prog.c', LIBS = 'm', - LIBPATH = ['/usr/lib', '/usr/local/lib']) - </file> - <file name="prog.c"> - int main() { printf("prog.c\n"); } - </file> - </scons_example> - - <para> - - Using a Python list is preferred because it's portable - across systems. Alternatively, you could put all of - the directory names in a single string, separated by the - system-specific path separator character: - a colon on POSIX systems: - - </para> - - <sconstruct> - LIBPATH = '/usr/lib:/usr/local/lib' - </sconstruct> - - <para> - - or a semi-colon on Windows systems: - - </para> - - <sconstruct> - LIBPATH = 'C:\\lib;D:\\lib' - </sconstruct> - - <para> - - (Note that Python requires that the backslash - separators in a Windows path name - be escaped within strings.) - - </para> - - <para> - - When the linker is executed, - &SCons; will create appropriate flags - so that the linker will look for - libraries in the same directories as &SCons;. - So on a POSIX or Linux system, - a build of the above example would look like: - - </para> - - <scons_output example="ex3" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - On a Windows system, - a build of the above example would look like: - - </para> - - <scons_output example="ex3" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - <!-- The link command is too wide in the PDF version. - There are some other examples of this throughout the document. --> - - <para> - - Note again that &SCons; has taken care of - the system-specific details of creating - the right command-line options. - - </para> - - </section> diff --git a/doc/user/libraries.xml b/doc/user/libraries.xml index f3a5492..aa4561e 100644 --- a/doc/user/libraries.xml +++ b/doc/user/libraries.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-libraries" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Building and Linking with Libraries</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -42,9 +63,20 @@ </para> - <programlisting> - Library('foo', ['f1.c', 'f2.c', 'f3.c']) - </programlisting> + <scons_example name="libraries_ex1" printme="1"> + <file name="SConstruct" printme="1"> +Library('foo', ['f1.c', 'f2.c', 'f3.c']) + </file> + <file name="f1.c"> +void f1() { printf("f1.c\n"); } + </file> + <file name="f2.c"> +void f2() { printf("f2.c\n"); } + </file> + <file name="f3.c"> +void f3() { printf("f3.c\n"); } + </file> + </scons_example> <para> @@ -55,14 +87,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o f1.o -c f1.c - cc -o f2.o -c f2.c - cc -o f3.o -c f3.c - ar rc libfoo.a f1.o f2.o f3.o - ranlib libfoo.a - </screen> + <scons_output example="libraries_ex1" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -71,13 +98,9 @@ </para> - <screen> - C:\><userinput>scons -Q</userinput> - cl /Fof1.obj /c f1.c /nologo - cl /Fof2.obj /c f2.c /nologo - cl /Fof3.obj /c f3.c /nologo - lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj - </screen> + <scons_output example="libraries_ex1" os="win32" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -106,9 +129,23 @@ </para> - <programlisting> - Library('foo', ['f1.c', 'f2.o', 'f3.c', 'f4.o']) - </programlisting> + <scons_example name="libraries_objects" printme="1"> + <file name="SConstruct" printme="1"> +Library('foo', ['f1.c', 'f2.o', 'f3.c', 'f4.o']) + </file> + <file name="f1.c"> +void f1() { printf("f1.c\n"); } + </file> + <file name="f2.o"> +object file + </file> + <file name="f3.c"> +void f3() { printf("f3.c\n"); } + </file> + <file name="f4.o"> +object file + </file> + </scons_example> <para> @@ -118,13 +155,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o f1.o -c f1.c - cc -o f3.o -c f3.c - ar rc libfoo.a f1.o f2.o f3.o f4.o - ranlib libfoo.a - </screen> + <scons_output example="libraries_objects" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -151,9 +184,11 @@ </para> - <programlisting> - StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) - </programlisting> + <scons_example name="libraries_StaticLibrary" printme="1"> + <file name="SConstruct" printme="1"> +StaticLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) + </file> + </scons_example> <para> @@ -175,9 +210,20 @@ </para> - <programlisting> - SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) - </programlisting> + <scons_example name="libraries_SharedLibrary" printme="1"> + <file name="SConstruct" printme="1"> +SharedLibrary('foo', ['f1.c', 'f2.c', 'f3.c']) + </file> + <file name="f1.c"> +void f1() { printf("f1.c\n"); } + </file> + <file name="f2.c"> +void f2() { printf("f2.c\n"); } + </file> + <file name="f3.c"> +void f3() { printf("f3.c\n"); } + </file> + </scons_example> <para> @@ -185,13 +231,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o f1.os -c f1.c - cc -o f2.os -c f2.c - cc -o f3.os -c f3.c - cc -o libfoo.so -shared f1.os f2.os f3.os - </screen> + <scons_output example="libraries_SharedLibrary" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -199,15 +241,9 @@ </para> - <screen> - C:\><userinput>scons -Q</userinput> - cl /Fof1.obj /c f1.c /nologo - cl /Fof2.obj /c f2.c /nologo - cl /Fof3.obj /c f3.c /nologo - link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj - RegServerFunc(target, source, env) - embedManifestDllCheck(target, source, env) - </screen> + <scons_output example="libraries_SharedLibrary" os="win32" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -242,10 +278,24 @@ </para> - <programlisting> - Library('foo', ['f1.c', 'f2.c', 'f3.c']) - Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.') - </programlisting> + <scons_example name="libraries_ex2"> + <file name="SConstruct" printme="1"> +Library('foo', ['f1.c', 'f2.c', 'f3.c']) +Program('prog.c', LIBS=['foo', 'bar'], LIBPATH='.') + </file> + <file name="f1.c"> +int main() { printf("Hello, world!\n"); } + </file> + <file name="f2.c"> +int main() { printf("Hello, world!\n"); } + </file> + <file name="f3.c"> +int main() { printf("Hello, world!\n"); } + </file> + <file name="prog.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -263,16 +313,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o f1.o -c f1.c - cc -o f2.o -c f2.c - cc -o f3.o -c f3.c - ar rc libfoo.a f1.o f2.o f3.o - ranlib libfoo.a - cc -o prog.o -c prog.c - cc -o prog prog.o -L. -lfoo -lbar - </screen> + <scons_output example="libraries_ex2" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -281,16 +324,9 @@ </para> - <screen> - C:\><userinput>scons -Q</userinput> - cl /Fof1.obj /c f1.c /nologo - cl /Fof2.obj /c f2.c /nologo - cl /Fof3.obj /c f3.c /nologo - lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj - cl /Foprog.obj /c prog.c /nologo - link /nologo /OUT:prog.exe /LIBPATH:. foo.lib bar.lib prog.obj - embedManifestExeCheck(target, source, env) - </screen> + <scons_output example="libraries_ex2" os="win32" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -310,9 +346,9 @@ </para> - <programlisting> - Program('prog.c', LIBS='foo', LIBPATH='.') - </programlisting> + <sconstruct> +Program('prog.c', LIBS='foo', LIBPATH='.') + </sconstruct> <para> @@ -320,9 +356,9 @@ </para> - <programlisting> - Program('prog.c', LIBS=['foo'], LIBPATH='.') - </programlisting> + <sconstruct> +Program('prog.c', LIBS=['foo'], LIBPATH='.') + </sconstruct> <para> @@ -349,10 +385,15 @@ </para> - <programlisting> - Program('prog.c', LIBS = 'm', - LIBPATH = ['/usr/lib', '/usr/local/lib']) - </programlisting> + <scons_example name="libraries_ex3"> + <file name="SConstruct" printme="1"> +Program('prog.c', LIBS = 'm', + LIBPATH = ['/usr/lib', '/usr/local/lib']) + </file> + <file name="prog.c"> +int main() { printf("prog.c\n"); } + </file> + </scons_example> <para> @@ -364,9 +405,9 @@ </para> - <programlisting> - LIBPATH = '/usr/lib:/usr/local/lib' - </programlisting> + <sconstruct> +LIBPATH = '/usr/lib:/usr/local/lib' + </sconstruct> <para> @@ -374,9 +415,9 @@ </para> - <programlisting> - LIBPATH = 'C:\\lib;D:\\lib' - </programlisting> + <sconstruct> +LIBPATH = 'C:\\lib;D:\\lib' + </sconstruct> <para> @@ -397,11 +438,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o prog.o -c prog.c - cc -o prog prog.o -L/usr/lib -L/usr/local/lib -lm - </screen> + <scons_output example="libraries_ex3" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -410,12 +449,9 @@ </para> - <screen> - C:\><userinput>scons -Q</userinput> - cl /Foprog.obj /c prog.c /nologo - link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj - embedManifestExeCheck(target, source, env) - </screen> + <scons_output example="libraries_ex3" os="win32" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <!-- The link command is too wide in the PDF version. There are some other examples of this throughout the document. --> @@ -428,3 +464,5 @@ </para> </section> + +</chapter> diff --git a/doc/user/main.in b/doc/user/main.in deleted file mode 100644 index 901c11f..0000000 --- a/doc/user/main.in +++ /dev/null @@ -1,411 +0,0 @@ -<?xml version="1.0"?> -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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 book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" -"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" -[ - - <!ENTITY % version SYSTEM "../version.xml"> - %version; - - <!ENTITY % scons SYSTEM "../scons.mod"> - %scons; - - <!ENTITY % builders-mod SYSTEM "builders.mod"> - %builders-mod; - - <!ENTITY % functions-mod SYSTEM "functions.mod"> - %functions-mod; - - <!ENTITY % tools-mod SYSTEM "tools.mod"> - %tools-mod; - - <!ENTITY % variables-mod SYSTEM "variables.mod"> - %variables-mod; - - <!ENTITY actions SYSTEM "actions.xml"> - <!ENTITY alias SYSTEM "alias.xml"> - <!ENTITY ant SYSTEM "ant.xml"> - <!ENTITY build-install SYSTEM "build-install.xml"> - <!ENTITY builders SYSTEM "builders.xml"> - <!ENTITY builders-built-in SYSTEM "builders-built-in.xml"> - <!ENTITY builders-commands SYSTEM "builders-commands.xml"> - <!ENTITY builders-writing SYSTEM "builders-writing.xml"> - <!ENTITY add-method SYSTEM "add-method.xml"> - <!ENTITY caching SYSTEM "caching.xml"> - <!ENTITY command-line SYSTEM "command-line.xml"> - <!ENTITY copyright SYSTEM "copyright.xml"> - <!ENTITY depends SYSTEM "depends.xml"> - <!ENTITY environments SYSTEM "environments.xml"> - <!ENTITY errors SYSTEM "errors.xml"> - <!ENTITY example SYSTEM "example.xml"> - <!ENTITY factories SYSTEM "factories.xml"> - <!ENTITY file-removal SYSTEM "file-removal.xml"> - <!ENTITY functions SYSTEM "functions.xml"> - <!ENTITY gettext SYSTEM "gettext.xml"> - <!ENTITY hierarchy SYSTEM "hierarchy.xml"> - <!ENTITY java SYSTEM "java.xml"> - <!ENTITY install SYSTEM "install.xml"> - <!ENTITY less-simple SYSTEM "less-simple.xml"> - <!ENTITY libraries SYSTEM "libraries.xml"> - <!ENTITY make SYSTEM "make.xml"> - <!ENTITY mergeflags SYSTEM "mergeflags.xml"> - <!ENTITY misc SYSTEM "misc.xml"> - <!ENTITY nodes SYSTEM "nodes.xml"> - <!ENTITY output SYSTEM "output.xml"> - <!ENTITY parseconfig SYSTEM "parseconfig.xml"> - <!ENTITY parseflags SYSTEM "parseflags.xml"> - <!ENTITY preface SYSTEM "preface.xml"> - <!ENTITY python SYSTEM "python.xml"> - <!ENTITY repositories SYSTEM "repositories.xml"> - <!ENTITY run SYSTEM "run.xml"> - <!ENTITY scanners SYSTEM "scanners.xml"> - <!ENTITY sconf SYSTEM "sconf.xml"> - <!ENTITY separate SYSTEM "separate.xml"> - <!ENTITY simple SYSTEM "simple.xml"> - <!ENTITY sourcecode SYSTEM "sourcecode.xml"> - <!ENTITY tasks SYSTEM "tasks.xml"> - <!ENTITY tools SYSTEM "tools.xml"> - <!ENTITY troubleshoot SYSTEM "troubleshoot.xml"> - <!ENTITY variables-xml SYSTEM "variables.xml"> - <!ENTITY variants SYSTEM "variants.xml"> - - <!ENTITY builders-gen SYSTEM "builders.gen"> - <!ENTITY functions-gen SYSTEM "functions.gen"> - <!ENTITY tools-gen SYSTEM "tools.gen"> - <!ENTITY variables-gen SYSTEM "variables.gen"> - -]> - - <!-- - - XXX Platform() - XXX Tools() - - XXX GetOption('duplicate') - XXX SetOption('duplicate') - XXX - - duplicate= - - XXX CheckTypeSize() - - XXX - - diskcheck= - - XXX - - warn= - - --> - -<book> - <bookinfo> - <title>SCons User Guide &buildversion;</title> - - <author> - <firstname>Steven</firstname> - <surname>Knight</surname> - </author> - - <edition>Revision &buildrevision; (&builddate;)</edition> - - <pubdate>2004, 2005, 2006, 2007, 2008, 2009, 2010</pubdate> - - <copyright> - <year>2004, 2005, 2006, 2007, 2008, 2009, 2010</year> - <holder>Steven Knight</holder> - </copyright> - - <legalnotice> - ©right; - </legalnotice> - - <releaseinfo>version &buildversion;</releaseinfo> - - </bookinfo> - - <preface id="chap-preface"> - <title>Preface</title> - &preface; - </preface> - - <chapter id="chap-build-install"> - <title>Building and Installing &SCons;</title> - &build-install; - </chapter> - - <chapter id="chap-simple"> - <title>Simple Builds</title> - &simple; - </chapter> - - <chapter id="chap-less-simple"> - <title>Less Simple Things to Do With Builds</title> - &less-simple; - </chapter> - - <chapter id="chap-libraries"> - <title>Building and Linking with Libraries</title> - &libraries; - </chapter> - - <chapter id="chap-nodes"> - <title>Node Objects</title> - &nodes; - </chapter> - - <chapter id="chap-depends"> - <title>Dependencies</title> - &depends; - </chapter> - - <chapter id="chap-environments"> - <title>Environments</title> - &environments; - </chapter> - - <chapter id="chap-manip-options"> - <title>Automatically Putting Command-line Options into their Construction Variables</title> - <!-- TODO: This intro paragraph should describe at a high-level - what these things do. People are likely to use the intro as a - (brief) overview of *what* these functions do to decide if this - chapter is where they should read in more detail. --> - <para> - This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; methods of a &consenv;. - </para> - <section id="sect-mergeflags"> - <title>Merging Options into the Environment: the &MergeFlags; Function</title> - &mergeflags; - </section> - <section id="sect-parseflags"> - <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title> - &parseflags; - </section> - <section id="sect-parseconfig"> - <title>Finding Installed Library Information: the &ParseConfig; Function</title> - &parseconfig; - </section> - <!-- - XXX parse_flags= option of Environment() - - <section id="sect-env-parseflags"> - <title>Adding Flags when Constructing Enviroment: the parse_flags Optional Argument</title> - &envparseflags; - </section> - --> - </chapter> - - <chapter id="chap-output"> - <title>Controlling Build Output</title> - &output; - </chapter> - - <chapter id="chap-command-line"> - <title>Controlling a Build From the Command Line</title> - &command-line; - </chapter> - - <chapter id="chap-install"> - <title>Installing Files in Other Directories: the &Install; Builder</title> - &install; - </chapter> - - <chapter id="chap-factories"> - <title>Platform-Independent File System Manipulation</title> - &factories; - </chapter> - - <chapter id="chap-file-removal"> - <title>Controlling Removal of Targets</title> - &file-removal; - </chapter> - - <chapter id="chap-hierarchical"> - <title>Hierarchical Builds</title> - &hierarchy; - </chapter> - - <chapter id="chap-separate"> - <title>Separating Source and Build Directories</title> - &separate; - </chapter> - - <chapter id="chap-variants"> - <title>Variant Builds</title> - &variants; - </chapter> - - <chapter id="chap-gettext"> - <title>Internationalization and localization with gettext</title> - &gettext; - </chapter> - - <!-- - - <chapter id="chap-builders-built-in"> - <title>Built-In Builders</title> - &builders-built-in; - </chapter> - - --> - - <chapter id="chap-builders-writing"> - <title>Writing Your Own Builders</title> - &builders-writing; - </chapter> - - <chapter id="chap-builders-commands"> - <title>Not Writing a Builder: the &Command; Builder</title> - &builders-commands; - </chapter> - - <chapter id="chap-add-method"> - <title>Pseudo-Builders: the AddMethod function</title> - &add-method; - </chapter> - - <!-- - - XXX Action() - XXX AddPostAction() - XXX AddPreAction() - - <chapter id="chap-actions"> - <title>&SCons; Actions</title> - &actions; - </chapter> - - --> - - <chapter id="chap-scanners"> - <title>Writing Scanners</title> - &scanners; - </chapter> - - <chapter id="chap-repositories"> - <title>Building From Code Repositories</title> - &repositories; - </chapter> - - <chapter id="chap-sconf"> - <title>Multi-Platform Configuration (&Autoconf; Functionality)</title> - &sconf; - </chapter> - - <!-- - - <chapter id="chap-sourcecode"> - <title>Fetching Files From Source Code Management Systems</title> - &sourcecode; - </chapter> - - --> - - <chapter id="chap-caching"> - <title>Caching Built Files</title> - &caching; - </chapter> - - <chapter id="chap-alias"> - <title>Alias Targets</title> - &alias; - </chapter> - - <chapter id="chap-java"> - <title>Java Builds</title> - &java; - </chapter> - - <!-- - - <chapter id="chap-run"> - <title>How to Run &SCons;</title> - &run; - </chapter> - - --> - - <chapter id="chap-misc"> - <title>Miscellaneous Functionality</title> - &misc; - </chapter> - - <chapter id="chap-troubleshooting"> - <title>Troubleshooting</title> - &troubleshoot; - </chapter> - - <appendix id="app-variables"> - <title>Construction Variables</title> - &variables-xml; - </appendix> - - <appendix id="app-builders"> - <title>Builders</title> - &builders; - </appendix> - - <appendix id="app-tools"> - <title>Tools</title> - &tools; - </appendix> - - <appendix id="app-functions"> - <title>Functions and Environment Methods</title> - &functions; - </appendix> - - <appendix id="app-tasks"> - <title>Handling Common Tasks</title> - &tasks; - </appendix> - - <!-- - - <appendix id="app-python"> - <title>Python Overview</title> - &example; - </appendix> - - <appendix id="app-example"> - <title>Complex &SCons; Example</title> - &example; - </appendix> - - <appendix id="app-make"> - <title>Converting From Make</title> - &make; - </appendix> - - <appendix id="app-cons"> - <title>Converting From Cons</title> - &cons; - </appendix> - - <appendix id="app-ant"> - <title>Converting From Ant</title> - &ant; - </appendix> - - --> - -</book> diff --git a/doc/user/main.xml b/doc/user/main.xml index 901c11f..afb5d51 100644 --- a/doc/user/main.xml +++ b/doc/user/main.xml @@ -1,7 +1,7 @@ <?xml version="1.0"?> <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -24,9 +24,7 @@ --> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" -"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" -[ +<!DOCTYPE sconsdoc [ <!ENTITY % version SYSTEM "../version.xml"> %version; @@ -34,70 +32,15 @@ <!ENTITY % scons SYSTEM "../scons.mod"> %scons; - <!ENTITY % builders-mod SYSTEM "builders.mod"> + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> %builders-mod; - - <!ENTITY % functions-mod SYSTEM "functions.mod"> + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> %functions-mod; - - <!ENTITY % tools-mod SYSTEM "tools.mod"> + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> %tools-mod; - - <!ENTITY % variables-mod SYSTEM "variables.mod"> + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> %variables-mod; - <!ENTITY actions SYSTEM "actions.xml"> - <!ENTITY alias SYSTEM "alias.xml"> - <!ENTITY ant SYSTEM "ant.xml"> - <!ENTITY build-install SYSTEM "build-install.xml"> - <!ENTITY builders SYSTEM "builders.xml"> - <!ENTITY builders-built-in SYSTEM "builders-built-in.xml"> - <!ENTITY builders-commands SYSTEM "builders-commands.xml"> - <!ENTITY builders-writing SYSTEM "builders-writing.xml"> - <!ENTITY add-method SYSTEM "add-method.xml"> - <!ENTITY caching SYSTEM "caching.xml"> - <!ENTITY command-line SYSTEM "command-line.xml"> - <!ENTITY copyright SYSTEM "copyright.xml"> - <!ENTITY depends SYSTEM "depends.xml"> - <!ENTITY environments SYSTEM "environments.xml"> - <!ENTITY errors SYSTEM "errors.xml"> - <!ENTITY example SYSTEM "example.xml"> - <!ENTITY factories SYSTEM "factories.xml"> - <!ENTITY file-removal SYSTEM "file-removal.xml"> - <!ENTITY functions SYSTEM "functions.xml"> - <!ENTITY gettext SYSTEM "gettext.xml"> - <!ENTITY hierarchy SYSTEM "hierarchy.xml"> - <!ENTITY java SYSTEM "java.xml"> - <!ENTITY install SYSTEM "install.xml"> - <!ENTITY less-simple SYSTEM "less-simple.xml"> - <!ENTITY libraries SYSTEM "libraries.xml"> - <!ENTITY make SYSTEM "make.xml"> - <!ENTITY mergeflags SYSTEM "mergeflags.xml"> - <!ENTITY misc SYSTEM "misc.xml"> - <!ENTITY nodes SYSTEM "nodes.xml"> - <!ENTITY output SYSTEM "output.xml"> - <!ENTITY parseconfig SYSTEM "parseconfig.xml"> - <!ENTITY parseflags SYSTEM "parseflags.xml"> - <!ENTITY preface SYSTEM "preface.xml"> - <!ENTITY python SYSTEM "python.xml"> - <!ENTITY repositories SYSTEM "repositories.xml"> - <!ENTITY run SYSTEM "run.xml"> - <!ENTITY scanners SYSTEM "scanners.xml"> - <!ENTITY sconf SYSTEM "sconf.xml"> - <!ENTITY separate SYSTEM "separate.xml"> - <!ENTITY simple SYSTEM "simple.xml"> - <!ENTITY sourcecode SYSTEM "sourcecode.xml"> - <!ENTITY tasks SYSTEM "tasks.xml"> - <!ENTITY tools SYSTEM "tools.xml"> - <!ENTITY troubleshoot SYSTEM "troubleshoot.xml"> - <!ENTITY variables-xml SYSTEM "variables.xml"> - <!ENTITY variants SYSTEM "variants.xml"> - - <!ENTITY builders-gen SYSTEM "builders.gen"> - <!ENTITY functions-gen SYSTEM "functions.gen"> - <!ENTITY tools-gen SYSTEM "tools.gen"> - <!ENTITY variables-gen SYSTEM "variables.gen"> - ]> <!-- @@ -117,72 +60,43 @@ --> -<book> +<book xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> <bookinfo> - <title>SCons User Guide &buildversion;</title> + <title>SCons &buildversion;</title> + <subtitle>User Guide</subtitle> <author> <firstname>Steven</firstname> <surname>Knight</surname> </author> - <edition>Revision &buildrevision; (&builddate;)</edition> + <corpauthor>Steven Knight</corpauthor> - <pubdate>2004, 2005, 2006, 2007, 2008, 2009, 2010</pubdate> + <pubdate>2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014</pubdate> <copyright> - <year>2004, 2005, 2006, 2007, 2008, 2009, 2010</year> + <year>2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014</year> <holder>Steven Knight</holder> </copyright> - <legalnotice> - ©right; - </legalnotice> - + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/> + <releaseinfo>version &buildversion;</releaseinfo> + <mediaobject role="cover"><imageobject><imagedata fileref="cover.jpg" format="JPG"/></imageobject></mediaobject> </bookinfo> - <preface id="chap-preface"> - <title>Preface</title> - &preface; - </preface> - - <chapter id="chap-build-install"> - <title>Building and Installing &SCons;</title> - &build-install; - </chapter> - - <chapter id="chap-simple"> - <title>Simple Builds</title> - &simple; - </chapter> - - <chapter id="chap-less-simple"> - <title>Less Simple Things to Do With Builds</title> - &less-simple; - </chapter> - - <chapter id="chap-libraries"> - <title>Building and Linking with Libraries</title> - &libraries; - </chapter> - - <chapter id="chap-nodes"> - <title>Node Objects</title> - &nodes; - </chapter> - - <chapter id="chap-depends"> - <title>Dependencies</title> - &depends; - </chapter> - - <chapter id="chap-environments"> - <title>Environments</title> - &environments; - </chapter> - + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="preface.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="build-install.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="simple.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="less-simple.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="libraries.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nodes.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="depends.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="environments.xml"/> + <chapter id="chap-manip-options"> <title>Automatically Putting Command-line Options into their Construction Variables</title> <!-- TODO: This intro paragraph should describe at a high-level @@ -192,96 +106,33 @@ <para> This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; methods of a &consenv;. </para> - <section id="sect-mergeflags"> - <title>Merging Options into the Environment: the &MergeFlags; Function</title> - &mergeflags; - </section> - <section id="sect-parseflags"> - <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title> - &parseflags; - </section> - <section id="sect-parseconfig"> - <title>Finding Installed Library Information: the &ParseConfig; Function</title> - &parseconfig; - </section> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="mergeflags.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="parseflags.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="parseconfig.xml"/> <!-- XXX parse_flags= option of Environment() - - <section id="sect-env-parseflags"> - <title>Adding Flags when Constructing Enviroment: the parse_flags Optional Argument</title> - &envparseflags; - </section> --> </chapter> - <chapter id="chap-output"> - <title>Controlling Build Output</title> - &output; - </chapter> - - <chapter id="chap-command-line"> - <title>Controlling a Build From the Command Line</title> - &command-line; - </chapter> - - <chapter id="chap-install"> - <title>Installing Files in Other Directories: the &Install; Builder</title> - &install; - </chapter> - - <chapter id="chap-factories"> - <title>Platform-Independent File System Manipulation</title> - &factories; - </chapter> - - <chapter id="chap-file-removal"> - <title>Controlling Removal of Targets</title> - &file-removal; - </chapter> - - <chapter id="chap-hierarchical"> - <title>Hierarchical Builds</title> - &hierarchy; - </chapter> - - <chapter id="chap-separate"> - <title>Separating Source and Build Directories</title> - &separate; - </chapter> - - <chapter id="chap-variants"> - <title>Variant Builds</title> - &variants; - </chapter> - - <chapter id="chap-gettext"> - <title>Internationalization and localization with gettext</title> - &gettext; - </chapter> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="output.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="command-line.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="install.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="factories.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="file-removal.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hierarchy.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="separate.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="variants.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="gettext.xml"/> <!-- - <chapter id="chap-builders-built-in"> - <title>Built-In Builders</title> - &builders-built-in; - </chapter> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="builders-built-in.xml"/> --> - <chapter id="chap-builders-writing"> - <title>Writing Your Own Builders</title> - &builders-writing; - </chapter> - - <chapter id="chap-builders-commands"> - <title>Not Writing a Builder: the &Command; Builder</title> - &builders-commands; - </chapter> - - <chapter id="chap-add-method"> - <title>Pseudo-Builders: the AddMethod function</title> - &add-method; - </chapter> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="builders-writing.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="builders-commands.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="add-method.xml"/> <!-- @@ -289,122 +140,44 @@ XXX AddPostAction() XXX AddPreAction() - <chapter id="chap-actions"> - <title>&SCons; Actions</title> - &actions; - </chapter> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="actions.xml"/> --> - <chapter id="chap-scanners"> - <title>Writing Scanners</title> - &scanners; - </chapter> - - <chapter id="chap-repositories"> - <title>Building From Code Repositories</title> - &repositories; - </chapter> - - <chapter id="chap-sconf"> - <title>Multi-Platform Configuration (&Autoconf; Functionality)</title> - &sconf; - </chapter> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="scanners.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="repositories.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sconf.xml"/> <!-- - <chapter id="chap-sourcecode"> - <title>Fetching Files From Source Code Management Systems</title> - &sourcecode; - </chapter> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="sourcecode.xml"/> --> - <chapter id="chap-caching"> - <title>Caching Built Files</title> - &caching; - </chapter> - - <chapter id="chap-alias"> - <title>Alias Targets</title> - &alias; - </chapter> - - <chapter id="chap-java"> - <title>Java Builds</title> - &java; - </chapter> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="caching.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="alias.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="java.xml"/> <!-- - <chapter id="chap-run"> - <title>How to Run &SCons;</title> - &run; - </chapter> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="run.xml"/> --> - <chapter id="chap-misc"> - <title>Miscellaneous Functionality</title> - &misc; - </chapter> - - <chapter id="chap-troubleshooting"> - <title>Troubleshooting</title> - &troubleshoot; - </chapter> - - <appendix id="app-variables"> - <title>Construction Variables</title> - &variables-xml; - </appendix> - - <appendix id="app-builders"> - <title>Builders</title> - &builders; - </appendix> - - <appendix id="app-tools"> - <title>Tools</title> - &tools; - </appendix> - - <appendix id="app-functions"> - <title>Functions and Environment Methods</title> - &functions; - </appendix> - - <appendix id="app-tasks"> - <title>Handling Common Tasks</title> - &tasks; - </appendix> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="misc.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="troubleshoot.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="variables.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="builders.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="functions.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tasks.xml"/> <!-- - <appendix id="app-python"> - <title>Python Overview</title> - &example; - </appendix> - - <appendix id="app-example"> - <title>Complex &SCons; Example</title> - &example; - </appendix> - - <appendix id="app-make"> - <title>Converting From Make</title> - &make; - </appendix> - - <appendix id="app-cons"> - <title>Converting From Cons</title> - &cons; - </appendix> - - <appendix id="app-ant"> - <title>Converting From Ant</title> - &ant; - </appendix> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="python.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="example.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="make.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ant.xml"/> --> diff --git a/doc/user/make.in b/doc/user/make.in deleted file mode 100644 index 876168a..0000000 --- a/doc/user/make.in +++ /dev/null @@ -1,121 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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. - ---> - -<!-- - -=head1 Why Cons? Why not Make? - -Cons is a B<make> replacement. In the following paragraphs, we look at a few -of the undesirable characteristics of make, and typical build environments -based on make, that motivated the development of Cons. - -=head2 Build complexity - -Traditional make-based systems of any size tend to become quite complex. The -original make utility and its derivatives have contributed to this tendency -in a number of ways. Make is not good at dealing with systems that are -spread over multiple directories. Various work-arounds are used to overcome -this difficulty; the usual choice is for make to invoke itself recursively -for each sub-directory of a build. This leads to complicated code, in which -it is often unclear how a variable is set, or what effect the setting of a -variable will have on the build as a whole. The make scripting language has -gradually been extended to provide more possibilities, but these have -largely served to clutter an already overextended language. Often, builds -are done in multiple passes in order to provide appropriate products from -one directory to another directory. This represents a further increase in -build complexity. - - -=head2 Build reproducibility - -The bane of all makes has always been the correct handling of -dependencies. Most often, an attempt is made to do a reasonable job of -dependencies within a single directory, but no serious attempt is made to do -the job between directories. Even when dependencies are working correctly, -make's reliance on a simple time stamp comparison to determine whether a -file is out of date with respect to its dependents is not, in general, -adequate for determining when a file should be rederived. If an external -library, for example, is rebuilt and then ``snapped'' into place, the -timestamps on its newly created files may well be earlier than the last -local build, since it was built before it became visible. - - -=head2 Variant builds - -Make provides only limited facilities for handling variant builds. With the -proliferation of hardware platforms and the need for debuggable -vs. optimized code, the ability to easily create these variants is -essential. More importantly, if variants are created, it is important to -either be able to separate the variants or to be able to reproduce the -original or variant at will. With make it is very difficult to separate the -builds into multiple build directories, separate from the source. And if -this technique isn't used, it's also virtually impossible to guarantee at -any given time which variant is present in the tree, without resorting to a -complete rebuild. - - -=head2 Repositories - -Make provides only limited support for building software from code that -exists in a central repository directory structure. The VPATH feature of -GNU make (and some other make implementations) is intended to provide this, -but doesn't work as expected: it changes the path of target file to the -VPATH name too early in its analysis, and therefore searches for all -dependencies in the VPATH directory. To ensure correct development builds, -it is important to be able to create a file in a local build directory and -have any files in a code repository (a VPATH directory, in make terms) that -depend on the local file get rebuilt properly. This isn't possible with -VPATH, without coding a lot of complex repository knowledge directly into -the makefiles. - ---> - - <para> - - XXX - - </para> - - <section> - <title>Differences Between &Make; and &SCons;</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>Advantages of &SCons; Over &Make;</title> - - <para> - - XXX - - </para> - - </section> diff --git a/doc/user/make.xml b/doc/user/make.xml index 876168a..69dd7f4 100644 --- a/doc/user/make.xml +++ b/doc/user/make.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<appendix id="app-make" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Converting From Make</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -119,3 +140,5 @@ the makefiles. </para> </section> + +</appendix> diff --git a/doc/user/mergeflags.in b/doc/user/mergeflags.in deleted file mode 100644 index f1997a0..0000000 --- a/doc/user/mergeflags.in +++ /dev/null @@ -1,137 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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; construction environments have a &MergeFlags; method - that merges a dictionary of values into the construction environment. - &MergeFlags; treats each value in the dictionary - as a list of options such as one might pass to a command - (such as a compiler or linker). - &MergeFlags; will not duplicate an option - if it already exists in the construction environment variable. - - </para> - - <para> - - &MergeFlags; tries to be intelligent about merging options. - When merging options to any variable - whose name ends in <varname>PATH</varname>, - &MergeFlags; keeps the leftmost occurrence of the option, - because in typical lists of directory paths, - the first occurrence "wins." - When merging options to any other variable name, - &MergeFlags; keeps the rightmost occurrence of the option, - because in a list of typical command-line options, - the last occurrence "wins." - - </para> - - <scons_example name="MergeFlags1"> - <file name="SConstruct" printme="1"> - env = Environment() - env.Append(CCFLAGS = '-option -O3 -O1') - flags = { 'CCFLAGS' : '-whatever -O3' } - env.MergeFlags(flags) - print env['CCFLAGS'] - </file> - </scons_example> - - <scons_output example="MergeFlags1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Note that the default value for &cv-link-CCFLAGS; - <!-- - [TODO: for when we make CLVar public] - is a <varname>CLVar</varname>, - --> - is an internal &SCons; object - which automatically converts - the options we specified as a string into a list. - - </para> - - <scons_example name="MergeFlags2"> - <file name="SConstruct" printme="1"> - env = Environment() - env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include']) - flags = { 'CPPPATH' : ['/usr/opt/include', '/usr/local/include'] } - env.MergeFlags(flags) - print env['CPPPATH'] - </file> - </scons_example> - - <scons_output example="MergeFlags2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Note that the default value for &cv-link-CPPPATH; - <!-- - [TODO: for when we make CLVar public] - is a Python list, not a <varname>CLVar</varname>, - --> - is a normal Python list, - so we must specify its values as a list - in the dictionary we pass to the &MergeFlags; function. - - </para> - - <para> - - If &MergeFlags; is passed anything other than a dictionary, - it calls the &ParseFlags; method to convert it into a dictionary. - - </para> - - <scons_example name="MergeFlags3"> - <file name="SConstruct" printme="1"> - env = Environment() - env.Append(CCFLAGS = '-option -O3 -O1') - env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include']) - env.MergeFlags('-whatever -I/usr/opt/include -O3 -I/usr/local/include') - print env['CCFLAGS'] - print env['CPPPATH'] - </file> - </scons_example> - - <scons_output example="MergeFlags3"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - In the combined example above, - &ParseFlags; has sorted the options into their corresponding variables - and returned a dictionary for &MergeFlags; to apply - to the construction variables - in the specified construction environment. - - </para> diff --git a/doc/user/mergeflags.xml b/doc/user/mergeflags.xml index b16e1b7..6434c1c 100644 --- a/doc/user/mergeflags.xml +++ b/doc/user/mergeflags.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<section id="sect-mergeflags" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Merging Options into the Environment: the &MergeFlags; Function</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -50,19 +71,19 @@ </para> - <programlisting> - env = Environment() - env.Append(CCFLAGS = '-option -O3 -O1') - flags = { 'CCFLAGS' : '-whatever -O3' } - env.MergeFlags(flags) - print env['CCFLAGS'] - </programlisting> + <scons_example name="mergeflags_MergeFlags1"> + <file name="SConstruct" printme="1"> +env = Environment() +env.Append(CCFLAGS = '-option -O3 -O1') +flags = { 'CCFLAGS' : '-whatever -O3' } +env.MergeFlags(flags) +print env['CCFLAGS'] + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - ['-option', '-O1', '-whatever', '-O3'] - scons: `.' is up to date. - </screen> + <scons_output example="mergeflags_MergeFlags1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -77,19 +98,19 @@ </para> - <programlisting> - env = Environment() - env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include']) - flags = { 'CPPPATH' : ['/usr/opt/include', '/usr/local/include'] } - env.MergeFlags(flags) - print env['CPPPATH'] - </programlisting> + <scons_example name="mergeflags_MergeFlags2"> + <file name="SConstruct" printme="1"> +env = Environment() +env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include']) +flags = { 'CPPPATH' : ['/usr/opt/include', '/usr/local/include'] } +env.MergeFlags(flags) +print env['CPPPATH'] + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - ['/include', '/usr/local/include', '/usr/include', '/usr/opt/include'] - scons: `.' is up to date. - </screen> + <scons_output example="mergeflags_MergeFlags2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -111,21 +132,20 @@ </para> - <programlisting> - env = Environment() - env.Append(CCFLAGS = '-option -O3 -O1') - env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include']) - env.MergeFlags('-whatever -I/usr/opt/include -O3 -I/usr/local/include') - print env['CCFLAGS'] - print env['CPPPATH'] - </programlisting> - - <screen> - % <userinput>scons -Q</userinput> - ['-option', '-O1', '-whatever', '-O3'] - ['/include', '/usr/local/include', '/usr/include', '/usr/opt/include'] - scons: `.' is up to date. - </screen> + <scons_example name="mergeflags_MergeFlags3"> + <file name="SConstruct" printme="1"> +env = Environment() +env.Append(CCFLAGS = '-option -O3 -O1') +env.Append(CPPPATH = ['/include', '/usr/local/include', '/usr/include']) +env.MergeFlags('-whatever -I/usr/opt/include -O3 -I/usr/local/include') +print env['CCFLAGS'] +print env['CPPPATH'] + </file> + </scons_example> + + <scons_output example="mergeflags_MergeFlags3" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -136,3 +156,5 @@ in the specified construction environment. </para> + +</section> diff --git a/doc/user/misc.in b/doc/user/misc.in deleted file mode 100644 index 19d123f..0000000 --- a/doc/user/misc.in +++ /dev/null @@ -1,606 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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; supports a lot of additional functionality - that doesn't readily fit into the other chapters. - - </para> - - <section> - <title>Verifying the Python Version: the &EnsurePythonVersion; Function</title> - - <para> - - Although the &SCons; code itself will run - on any 2.x Python version 2.4 or later, - you are perfectly free to make use of - Python syntax and modules from more modern versions - (for example, Python 2.5 or 2.6) - when writing your &SConscript; files - or your own local modules. - If you do this, it's usually helpful to - configure &SCons; to exit gracefully with an error message - if it's being run with a version of Python - that simply won't work with your code. - This is especially true if you're going to use &SCons; - to build source code that you plan to distribute publicly, - where you can't be sure of the Python version - that an anonymous remote user might use - to try to build your software. - - </para> - - <para> - - &SCons; provides an &EnsurePythonVersion; function for this. - You simply pass it the major and minor versions - numbers of the version of Python you require: - - </para> - - <!-- - - TODO: Figure out how to generate the error message - regardless of executing Python version by faking out - the infrastructure in some way. - - <scons_example name="EnsurePythonVersion"> - <file name="SConstruct" printme="1"> - EnsurePythonVersion(2, 5) - </file> - </scons_example> - - --> - - <sconstruct> - EnsurePythonVersion(2, 5) - </sconstruct> - - <para> - - And then &SCons; will exit with the following error - message when a user runs it with an unsupported - earlier version of Python: - - </para> - - <!-- - - TODO: Figure out how to generate the error message - regardless of executing Python version by faking out - the infrastructure in some way. - - <scons_output example="EnsurePythonVersion"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - --> - - <screen> - % <userinput>scons -Q</userinput> - Python 2.5 or greater required, but you have Python 2.3.6 - </screen> - - </section> - - <section> - <title>Verifying the SCons Version: the &EnsureSConsVersion; Function</title> - - <para> - - You may, of course, write your &SConscript; files - to use features that were only added in - recent versions of &SCons;. - When you publicly distribute software that is built using &SCons;, - it's helpful to have &SCons; - verify the version being used and - exit gracefully with an error message - if the user's version of &SCons; won't work - with your &SConscript; files. - &SCons; provides an &EnsureSConsVersion; function - that verifies the version of &SCons; - in the same - the &EnsurePythonVersion; function - verifies the version of Python, - by passing in the major and minor versions - numbers of the version of SCons you require: - - </para> - - <!-- - - TODO: Figure out how to generate the error message - regardless of executing SCons version by faking out - the infrastructure in some way. - - <scons_example name="EnsureSConsVersion"> - <file name="SConstruct" printme="1"> - EnsureSConsVersion(1, 0) - </file> - </scons_example> - - --> - - <sconstruct> - EnsureSConsVersion(1, 0) - </sconstruct> - - <para> - - And then &SCons; will exit with the following error - message when a user runs it with an unsupported - earlier version of &SCons;: - - </para> - - <!-- - - TODO: Figure out how to generate the error message - regardless of executing SCons version by faking out - the infrastructure in some way. - - <scons_output example="EnsureSConsVersion"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - --> - - <screen> - % <userinput>scons -Q</userinput> - SCons 1.0 or greater required, but you have SCons 0.98.5 - </screen> - - </section> - - <section> - <title>Explicitly Terminating &SCons; While Reading &SConscript; Files: the &Exit; Function</title> - - <para> - - &SCons; supports an &Exit; function - which can be used to terminate &SCons; - while reading the &SConscript; files, - usually because you've detected a condition - under which it doesn't make sense to proceed: - - </para> - - <scons_example name="Exit"> - <file name="SConstruct" printme="1"> - if ARGUMENTS.get('FUTURE'): - print "The FUTURE option is not supported yet!" - Exit(2) - env = Environment() - env.Program('hello.c') - </file> - <file name="hello.c"> - hello.c - </file> - </scons_example> - - <scons_output example="Exit"> - <scons_output_command>scons -Q FUTURE=1</scons_output_command> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - The &Exit; function takes as an argument - the (numeric) exit status that you want &SCons; to exit with. - If you don't specify a value, - the default is to exit with <literal>0</literal>, - which indicates successful execution. - - </para> - - <para> - - Note that the &Exit; function - is equivalent to calling the Python - <function>sys.exit</function> function - (which the it actually calls), - but because &Exit; is a &SCons; function, - you don't have to import the Python - <literal>sys</literal> module to use it. - - </para> - - </section> - - <section> - <title>Searching for Files: the &FindFile; Function</title> - - <para> - - The &FindFile; function searches for a file in a list of directories. - If there is only one directory, it can be given as a simple string. - The function returns a File node if a matching file exists, - or None if no file is found. - (See the documentation for the &Glob; function for an alternative way - of searching for entries in a directory.) - - </para> - - <scons_example name="FindFile1a"> - <file name="SConstruct" printme="1"> - # one directory - print FindFile('missing', '.') - t = FindFile('exists', '.') - print t.__class__, t - </file> - <file name="exists"> - exists - </file> - </scons_example> - - <scons_output example="FindFile1a" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <scons_example name="FindFile1b"> - <file name="SConstruct" printme="1"> - # several directories - includes = [ '.', 'include', 'src/include'] - headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] - for hdr in headers: - print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes) - </file> - <file name="config.h"> - exists - </file> - <directory name="src"></directory> - <directory name="src/include"></directory> - <file name="src/include/private.h"> - exists - </file> - <directory name="include"></directory> - <file name="include/dist.h"> - exists - </file> - </scons_example> - - <scons_output example="FindFile1b" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <!-- The man page says this should work, but it fails. - <para> - - If the 'file' parameter is a list of files, - a list of File nodes is returned. - - </para> - - <scons_example name="FindFile1c"> - <file name="SConstruct" printme="1"> - # several directories - includes = [ '.', 'include', 'src/include'] - headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] - print FindFile(headers, includes) - </file> - <file name="config.h"> - exists - </file> - <directory name="src"></directory> - <directory name="src/include"></directory> - </file> - <file name="src/include/private.h"> - exists - <directory name="include"></directory> - </file> - <file name="include/dist.h"> - exists - </scons_example> - - <scons_output example="FindFile1c" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - --> - - <para> - - If the file exists in more than one directory, - only the first occurrence is returned. - - </para> - - <scons_example name="FindFile1d"> - <file name="SConstruct" printme="1"> - print FindFile('multiple', ['sub1', 'sub2', 'sub3']) - print FindFile('multiple', ['sub2', 'sub3', 'sub1']) - print FindFile('multiple', ['sub3', 'sub1', 'sub2']) - </file> - <directory name="sub1"></directory> - <file name="sub1/multiple"> - exists - </file> - <directory name="sub2"></directory> - <file name="sub2/multiple"> - exists - </file> - <directory name="sub3"></directory> - <file name="sub3/multiple"> - exists - </file> - </scons_example> - - <scons_output example="FindFile1d" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <!-- file may be a list of file names or a single file name. --> - - <para> - - In addition to existing files, &FindFile; will also find derived files - (that is, non-leaf files) that haven't been built yet. - (Leaf files should already exist, or the build will fail!) - - </para> - - <scons_example name="FindFile2"> - <file name="SConstruct" printme="1"> - # Neither file exists, so build will fail - Command('derived', 'leaf', 'cat >$TARGET $SOURCE') - print FindFile('leaf', '.') - print FindFile('derived', '.') - </file> - </scons_example> - - <scons_output example="FindFile2" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <scons_example name="FindFile2"> - <file name="SConstruct" printme="1"> - # Only 'leaf' exists - Command('derived', 'leaf', 'cat >$TARGET $SOURCE') - print FindFile('leaf', '.') - print FindFile('derived', '.') - </file> - <file name="leaf"> - leaf - </file> - </scons_example> - - <scons_output example="FindFile2" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - If a source file exists, &FindFile; will correctly return the name - in the build directory. - - </para> - - <scons_example name="FindFile3"> - <file name="SConstruct" printme="1"> - # Only 'src/leaf' exists - VariantDir('build', 'src') - print FindFile('leaf', 'build') - </file> - <directory name="src"></directory> - <file name="src/leaf"> - leaf - </file> - </scons_example> - - <scons_output example="FindFile3" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Handling Nested Lists: the &Flatten; Function</title> - - <para> - - &SCons; supports a &Flatten; function - which takes an input Python sequence - (list or tuple) - and returns a flattened list - containing just the individual elements of - the sequence. - This can be handy when trying to examine - a list composed of the lists - returned by calls to various Builders. - For example, you might collect - object files built in different ways - into one call to the &Program; Builder - by just enclosing them in a list, as follows: - - </para> - - <scons_example name="Flatten1"> - <file name="SConstruct" printme="1"> - objects = [ - Object('prog1.c'), - Object('prog2.c', CCFLAGS='-DFOO'), - ] - Program(objects) - </file> - <file name="prog1.c"> - prog1.c - </file> - <file name="prog2.c"> - prog2.c - </file> - </scons_example> - - <para> - - Because the Builder calls in &SCons; - flatten their input lists, - this works just fine to build the program: - - </para> - - <scons_output example="Flatten1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - But if you were debugging your build - and wanted to print the absolute path - of each object file in the - <varname>objects</varname> list, - you might try the following simple approach, - trying to print each Node's - <literal>abspath</literal> - attribute: - - </para> - - <scons_example name="Flatten2"> - <file name="SConstruct" printme="1"> - objects = [ - Object('prog1.c'), - Object('prog2.c', CCFLAGS='-DFOO'), - ] - Program(objects) - - for object_file in objects: - print object_file.abspath - </file> - <file name="prog1.c"> - prog1.c - </file> - <file name="prog2.c"> - prog2.c - </file> - </scons_example> - - <para> - - This does not work as expected - because each call to <function>str</function> - is operating an embedded list returned by - each &Object; call, - not on the underlying Nodes within those lists: - - </para> - - <scons_output example="Flatten2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - The solution is to use the &Flatten; function - so that you can pass each Node to - the <function>str</function> separately: - - </para> - - <scons_example name="Flatten3"> - <file name="SConstruct" printme="1"> - objects = [ - Object('prog1.c'), - Object('prog2.c', CCFLAGS='-DFOO'), - ] - Program(objects) - - for object_file in Flatten(objects): - print object_file.abspath - </file> - <file name="prog1.c"> - prog1.c - </file> - <file name="prog2.c"> - prog2.c - </file> - </scons_example> - - <!-- - - TODO: can't use this now because it displays the temporary path name - - <scons_output example="Flatten3"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - --> - - <screen> - % <userinput>scons -Q</userinput> - /home/me/project/prog1.o - /home/me/project/prog2.o - cc -o prog1.o -c prog1.c - cc -o prog2.o -c -DFOO prog2.c - cc -o prog1 prog1.o prog2.o - </screen> - - </section> - - <section> - <title>Finding the Invocation Directory: the &GetLaunchDir; Function</title> - - <para> - - If you need to find the directory from - which the user invoked the &scons; command, - you can use the &GetLaunchDir; function: - - </para> - - <sconstruct> - env = Environment( - LAUNCHDIR = GetLaunchDir(), - ) - env.Command('directory_build_info', - '$LAUNCHDIR/build_info' - Copy('$TARGET', '$SOURCE')) - </sconstruct> - - <para> - - Because &SCons; is usually invoked from the top-level - directory in which the &SConstruct; file lives, - the Python <function>os.getcwd()</function> - is often equivalent. - However, the &SCons; - <literal>-u</literal>, - <literal>-U</literal> - and - <literal>-D</literal> - command-line options, - when invoked from a subdirectory, - will cause &SCons; to change to the directory - in which the &SConstruct; file is found. - When those options are used, - &GetLaunchDir; will still return the path to the - user's invoking subdirectory, - allowing the &SConscript; configuration - to still get at configuration (or other) files - from the originating directory. - - </para> - - </section> diff --git a/doc/user/misc.xml b/doc/user/misc.xml index 524bca3..1d892a4 100644 --- a/doc/user/misc.xml +++ b/doc/user/misc.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-misc" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Miscellaneous Functionality</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -68,17 +89,17 @@ regardless of executing Python version by faking out the infrastructure in some way. - <scons_example name="EnsurePythonVersion"> + <scons_example name="misc_EnsurePythonVersion"> <file name="SConstruct" printme="1"> - EnsurePythonVersion(2, 5) +EnsurePythonVersion(2, 5) </file> </scons_example> --> - <programlisting> - EnsurePythonVersion(2, 5) - </programlisting> + <sconstruct> +EnsurePythonVersion(2, 5) + </sconstruct> <para> @@ -94,15 +115,15 @@ regardless of executing Python version by faking out the infrastructure in some way. - <scons_output example="EnsurePythonVersion"> + <scons_output example="misc_EnsurePythonVersion" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> <screen> - % <userinput>scons -Q</userinput> - Python 2.5 or greater required, but you have Python 2.3.6 +% <userinput>scons -Q</userinput> +Python 2.5 or greater required, but you have Python 2.3.6 </screen> </section> @@ -137,17 +158,17 @@ regardless of executing SCons version by faking out the infrastructure in some way. - <scons_example name="EnsureSConsVersion"> + <scons_example name="misc_EnsureSConsVersion"> <file name="SConstruct" printme="1"> - EnsureSConsVersion(1, 0) +EnsureSConsVersion(1, 0) </file> </scons_example> --> - <programlisting> - EnsureSConsVersion(1, 0) - </programlisting> + <sconstruct> +EnsureSConsVersion(1, 0) + </sconstruct> <para> @@ -163,15 +184,15 @@ regardless of executing SCons version by faking out the infrastructure in some way. - <scons_output example="EnsureSConsVersion"> + <scons_output example="misc_EnsureSConsVersion" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> <screen> - % <userinput>scons -Q</userinput> - SCons 1.0 or greater required, but you have SCons 0.98.5 +% <userinput>scons -Q</userinput> +SCons 1.0 or greater required, but you have SCons 0.98.5 </screen> </section> @@ -189,21 +210,23 @@ </para> - <programlisting> - if ARGUMENTS.get('FUTURE'): - print "The FUTURE option is not supported yet!" - Exit(2) - env = Environment() - env.Program('hello.c') - </programlisting> + <scons_example name="misc_Exit"> + <file name="SConstruct" printme="1"> +if ARGUMENTS.get('FUTURE'): + print "The FUTURE option is not supported yet!" + Exit(2) +env = Environment() +env.Program('hello.c') + </file> + <file name="hello.c"> +hello.c + </file> + </scons_example> - <screen> - % <userinput>scons -Q FUTURE=1</userinput> - The FUTURE option is not supported yet! - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="misc_Exit" suffix="1"> + <scons_output_command>scons -Q FUTURE=1</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -243,36 +266,47 @@ </para> - <programlisting> - # one directory - print FindFile('missing', '.') - t = FindFile('exists', '.') - print t.__class__, t - </programlisting> + <scons_example name="misc_FindFile1a"> + <file name="SConstruct" printme="1"> +# one directory +print FindFile('missing', '.') +t = FindFile('exists', '.') +print t.__class__, t + </file> + <file name="exists"> + exists + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - None - <class 'SCons.Node.FS.File'> exists - scons: `.' is up to date. - </screen> + <scons_output example="misc_FindFile1a" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> - <programlisting> - # several directories - includes = [ '.', 'include', 'src/include'] - headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] - for hdr in headers: - print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes) - </programlisting> + <scons_example name="misc_FindFile1b"> + <file name="SConstruct" printme="1"> +# several directories +includes = [ '.', 'include', 'src/include'] +headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] +for hdr in headers: + print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes) + </file> + <file name="config.h"> +exists + </file> + <directory name="src"></directory> + <directory name="src/include"></directory> + <file name="src/include/private.h"> +exists + </file> + <directory name="include"></directory> + <file name="include/dist.h"> +exists + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - nonesuch.h: None - config.h: config.h - private.h: src/include/private.h - dist.h: include/dist.h - scons: `.' is up to date. - </screen> + <scons_output example="misc_FindFile1b" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <!-- The man page says this should work, but it fails. <para> @@ -282,28 +316,28 @@ </para> - <scons_example name="FindFile1c"> + <scons_example name="misc_FindFile1c"> <file name="SConstruct" printme="1"> - # several directories - includes = [ '.', 'include', 'src/include'] - headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] - print FindFile(headers, includes) +# several directories +includes = [ '.', 'include', 'src/include'] +headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] +print FindFile(headers, includes) </file> <file name="config.h"> - exists +exists </file> <directory name="src"></directory> <directory name="src/include"></directory> </file> <file name="src/include/private.h"> - exists +exists <directory name="include"></directory> </file> <file name="include/dist.h"> - exists +exists </scons_example> - <scons_output example="FindFile1c" os="posix"> + <scons_output example="misc_FindFile1c" os="posix" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> @@ -315,19 +349,29 @@ </para> - <programlisting> - print FindFile('multiple', ['sub1', 'sub2', 'sub3']) - print FindFile('multiple', ['sub2', 'sub3', 'sub1']) - print FindFile('multiple', ['sub3', 'sub1', 'sub2']) - </programlisting> + <scons_example name="misc_FindFile1d"> + <file name="SConstruct" printme="1"> +print FindFile('multiple', ['sub1', 'sub2', 'sub3']) +print FindFile('multiple', ['sub2', 'sub3', 'sub1']) +print FindFile('multiple', ['sub3', 'sub1', 'sub2']) + </file> + <directory name="sub1"></directory> + <file name="sub1/multiple"> +exists + </file> + <directory name="sub2"></directory> + <file name="sub2/multiple"> +exists + </file> + <directory name="sub3"></directory> + <file name="sub3/multiple"> +exists + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - sub1/multiple - sub2/multiple - sub3/multiple - scons: `.' is up to date. - </screen> + <scons_output example="misc_FindFile1d" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <!-- file may be a list of file names or a single file name. --> @@ -339,38 +383,34 @@ </para> - <programlisting> - # Neither file exists, so build will fail - Command('derived', 'leaf', 'cat >$TARGET $SOURCE') - print FindFile('leaf', '.') - print FindFile('derived', '.') - </programlisting> - - <screen> - % <userinput>scons -Q</userinput> - None - derived - scons: *** [derived] Source `leaf' not found, needed by target `derived'. - </screen> + <scons_example name="misc_FindFile2"> + <file name="SConstruct" printme="1"> +# Neither file exists, so build will fail +Command('derived', 'leaf', 'cat >$TARGET $SOURCE') +print FindFile('leaf', '.') +print FindFile('derived', '.') + </file> + </scons_example> - <programlisting> - # Neither file exists, so build will fail - Command('derived', 'leaf', 'cat >$TARGET $SOURCE') - print FindFile('leaf', '.') - print FindFile('derived', '.') + <scons_output example="misc_FindFile2" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> - # Only 'leaf' exists - Command('derived', 'leaf', 'cat >$TARGET $SOURCE') - print FindFile('leaf', '.') - print FindFile('derived', '.') - </programlisting> + <scons_example name="misc_FindFile2"> + <file name="SConstruct" printme="1"> +# Only 'leaf' exists +Command('derived', 'leaf', 'cat >$TARGET $SOURCE') +print FindFile('leaf', '.') +print FindFile('derived', '.') + </file> + <file name="leaf"> +leaf + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - leaf - derived - cat > derived leaf - </screen> + <scons_output example="misc_FindFile2" os="posix" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -379,17 +419,21 @@ </para> - <programlisting> - # Only 'src/leaf' exists - VariantDir('build', 'src') - print FindFile('leaf', 'build') - </programlisting> + <scons_example name="misc_FindFile3"> + <file name="SConstruct" printme="1"> +# Only 'src/leaf' exists +VariantDir('build', 'src') +print FindFile('leaf', 'build') + </file> + <directory name="src"></directory> + <file name="src/leaf"> +leaf + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - build/leaf - scons: `.' is up to date. - </screen> + <scons_output example="misc_FindFile3" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -414,13 +458,21 @@ </para> - <programlisting> - objects = [ - Object('prog1.c'), - Object('prog2.c', CCFLAGS='-DFOO'), - ] - Program(objects) - </programlisting> + <scons_example name="misc_Flatten1"> + <file name="SConstruct" printme="1"> +objects = [ + Object('prog1.c'), + Object('prog2.c', CCFLAGS='-DFOO'), +] +Program(objects) + </file> + <file name="prog1.c"> +prog1.c + </file> + <file name="prog2.c"> +prog2.c + </file> + </scons_example> <para> @@ -430,12 +482,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o prog1.o -c prog1.c - cc -o prog2.o -c -DFOO prog2.c - cc -o prog1 prog1.o prog2.o - </screen> + <scons_output example="misc_Flatten1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -450,16 +499,24 @@ </para> - <programlisting> - objects = [ - Object('prog1.c'), - Object('prog2.c', CCFLAGS='-DFOO'), - ] - Program(objects) - - for object_file in objects: - print object_file.abspath - </programlisting> + <scons_example name="misc_Flatten2"> + <file name="SConstruct" printme="1"> +objects = [ + Object('prog1.c'), + Object('prog2.c', CCFLAGS='-DFOO'), +] +Program(objects) + +for object_file in objects: + print object_file.abspath + </file> + <file name="prog1.c"> +prog1.c + </file> + <file name="prog2.c"> +prog2.c + </file> + </scons_example> <para> @@ -471,12 +528,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - AttributeError: 'NodeList' object has no attribute 'abspath': - File "/home/my/project/SConstruct", line 8: - print object_file.abspath - </screen> + <scons_output example="misc_Flatten2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -486,34 +540,42 @@ </para> - <programlisting> - objects = [ - Object('prog1.c'), - Object('prog2.c', CCFLAGS='-DFOO'), - ] - Program(objects) - - for object_file in Flatten(objects): - print object_file.abspath - </programlisting> + <scons_example name="misc_Flatten3"> + <file name="SConstruct" printme="1"> +objects = [ + Object('prog1.c'), + Object('prog2.c', CCFLAGS='-DFOO'), +] +Program(objects) + +for object_file in Flatten(objects): + print object_file.abspath + </file> + <file name="prog1.c"> +prog1.c + </file> + <file name="prog2.c"> +prog2.c + </file> + </scons_example> <!-- TODO: can't use this now because it displays the temporary path name - <scons_output example="Flatten3"> + <scons_output example="misc_Flatten3" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> <screen> - % <userinput>scons -Q</userinput> - /home/me/project/prog1.o - /home/me/project/prog2.o - cc -o prog1.o -c prog1.c - cc -o prog2.o -c -DFOO prog2.c - cc -o prog1 prog1.o prog2.o +% <userinput>scons -Q</userinput> +/home/me/project/prog1.o +/home/me/project/prog2.o +cc -o prog1.o -c prog1.c +cc -o prog2.o -c -DFOO prog2.c +cc -o prog1 prog1.o prog2.o </screen> </section> @@ -529,14 +591,14 @@ </para> - <programlisting> - env = Environment( - LAUNCHDIR = GetLaunchDir(), - ) - env.Command('directory_build_info', - '$LAUNCHDIR/build_info' - Copy('$TARGET', '$SOURCE')) - </programlisting> + <sconstruct> +env = Environment( + LAUNCHDIR = GetLaunchDir(), +) +env.Command('directory_build_info', + '$LAUNCHDIR/build_info' + Copy('$TARGET', '$SOURCE')) + </sconstruct> <para> @@ -563,3 +625,5 @@ </para> </section> + +</chapter> diff --git a/doc/user/nodes.in b/doc/user/nodes.in deleted file mode 100644 index 1cb5a3d..0000000 --- a/doc/user/nodes.in +++ /dev/null @@ -1,431 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - Internally, &SCons; represents all of the files - and directories it knows about as &Nodes;. - These internal objects - (not object <emphasis>files</emphasis>) - can be used in a variety of ways - to make your &SConscript; - files portable and easy to read. - - </para> - - <section> - <title>Builder Methods Return Lists of Target Nodes</title> - - <para> - - All builder methods return a list of - &Node; objects that identify the - target file or files that will be built. - These returned &Nodes; can be passed - as arguments to other builder methods. - - </para> - - <para> - - 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 &b-link-Object; - builder once for each object file, - specifying the desired options: - - </para> - - <sconstruct> - Object('hello.c', CCFLAGS='-DHELLO') - Object('goodbye.c', CCFLAGS='-DGOODBYE') - </sconstruct> - - <para> - - One way to combine these object files - into the resulting program - would be to call the &b-link-Program; - builder with the names of the object files - listed as sources: - - </para> - - <sconstruct> - Object('hello.c', CCFLAGS='-DHELLO') - Object('goodbye.c', CCFLAGS='-DGOODBYE') - Program(['hello.o', 'goodbye.o']) - </sconstruct> - - <para> - - The problem with specifying the names as strings - is that our &SConstruct; file is no longer portable - across operating systems. - It won't, for example, work on Windows - because the object files there would be - named &hello_obj; and &goodbye_obj;, - not &hello_o; and &goodbye_o;. - - </para> - - <para> - - A better solution is to assign the lists of targets - returned by the calls to the &b-Object; builder to variables, - which we can then concatenate in our - call to the &b-Program; builder: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - hello_list = Object('hello.c', CCFLAGS='-DHELLO') - goodbye_list = Object('goodbye.c', CCFLAGS='-DGOODBYE') - Program(hello_list + goodbye_list) - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - <file name="goodbye.c"> - int main() { printf("Goodbye, world!\n"); } - </file> - </scons_example> - - <para> - - This makes our &SConstruct; file portable again, - the build output on Linux looking like: - - </para> - - <scons_output example="ex1" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - And on Windows: - - </para> - - <scons_output example="ex1" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - We'll see examples of using the list of nodes - returned by builder methods throughout - the rest of this guide. - - </para> - - </section> - - <section> - <title>Explicitly Creating File and Directory Nodes</title> - - <para> - - It's worth mentioning here that - &SCons; maintains a clear distinction - between Nodes that represent files - and Nodes that represent directories. - &SCons; supports &File; and &Dir; - functions that, respectively, - return a file or directory Node: - - </para> - - <scons_example name="print"> - <file name="SConstruct" printme="1"> - hello_c = File('hello.c') - Program(hello_c) - - classes = Dir('classes') - Java(classes, 'src') - </file> - </scons_example> - - <para> - - Normally, you don't need to call - &File; or &Dir; directly, - because calling a builder method automatically - treats strings as the names of files or directories, - and translates them into - the Node objects for you. - The &File; and &Dir; functions can come in handy - in situations where you need to explicitly - instruct &SCons; about the type of Node being - passed to a builder or other function, - or unambiguously refer to a specific - file in a directory tree. - <!-- - (For an example of when you might - need to use &File; or &Dir; to - prevent ambiguous interpretation of a string - naming a file or directory, see - <xref linkend="chap-hierarchy">.) - --> - - </para> - - <para> - - There are also times when you may need to - refer to an entry in a file system - without knowing in advance - whether it's a file or a directory. - For those situations, - &SCons; also supports an &Entry; function, - which returns a Node - that can represent either a file or a directory. - - </para> - - <sconstruct> - xyzzy = Entry('xyzzy') - </sconstruct> - - <para> - - The returned <literal>xyzzy</literal> Node - will be turned into a file or directory Node - the first time it is used by a builder method - or other function that - requires one vs. the other. - - </para> - - </section> - - <section> - <title>Printing &Node; File Names</title> - - <para> - - One of the most common things you can do - with a Node is use it to print the - file name that the node represents. - Keep in mind, though, that because the object - returned by a builder call - is a <emphasis>list</emphasis> of Nodes, - you must use Python subscripts - to fetch individual Nodes from the list. - For example, the following &SConstruct; file: - - </para> - - <scons_example name="print"> - <file name="SConstruct" printme="1"> - object_list = Object('hello.c') - program_list = Program(object_list) - print "The object file is:", object_list[0] - print "The program file is:", program_list[0] - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Would print the following file names on a POSIX system: - - </para> - - <scons_output example="print" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - And the following file names on a Windows system: - - </para> - - <scons_output example="print" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Note that in the above example, - the <literal>object_list[0]</literal> - extracts an actual Node <emphasis>object</emphasis> - from the list, - and the Python <literal>print</literal> statement - converts the object to a string for printing. - - </para> - - </section> - - <section> - <title>Using a &Node;'s File Name as a String</title> - - <para> - - Printing a &Node;'s name - as described in the previous section - works because the string representation of a &Node; object - is the name of the file. - If you want to do something other than - print the name of the file, - you can fetch it by using the builtin Python - &str; function. - For example, if you want to use the Python - <function>os.path.exists</function> - to figure out whether a file - exists while the &SConstruct; file - is being read and executed, - you can fetch the string as follows: - - </para> - - <scons_example name="exists"> - <file name="SConstruct" printme="1"> - import os.path - program_list = Program('hello.c') - program_name = str(program_list[0]) - if not os.path.exists(program_name): - print program_name, "does not exist!" - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Which executes as follows on a POSIX system: - - </para> - - <scons_output example="exists" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>&GetBuildPath;: Getting the Path From a &Node; or String</title> - - <para> - - <function>env.GetBuildPath(file_or_list)</function> - returns the path of a &Node; or a string representing a - path. It can also take a list of &Node;s and/or strings, and - returns the list of paths. If passed a single &Node;, the result - is the same as calling <literal>str(node)</literal> (see above). - The string(s) can have embedded construction variables, which are - expanded as usual, using the calling environment's set of - variables. The paths can be files or directories, and do not have - to exist. - - </para> - - <scons_example name="GetBuildPath"> - <file name="SConstruct" printme="1"> - env=Environment(VAR="value") - n=File("foo.c") - print env.GetBuildPath([n, "sub/dir/$VAR"]) - </file> - </scons_example> - - <para> - - Would print the following file names: - - </para> - - <scons_output example="GetBuildPath" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - There is also a function version of &GetBuildPath; which can - be called without an &Environment;; that uses the default SCons - &Environment; to do substitution on any string arguments. - - </para> - - </section> - - <!-- - - <section> - <title>Fetching the Contents of a &Node;</title> - - <para> - - XXX Describe using read() and readlines() - when we add that as a public interface. - - </para> - - <scons_example name="read"> - <file name="SConstruct" printme="1"> - hello_c = File('hello.c') - contents = hello_c.read() - print "contents are:" - print contents - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Which executes as follows on a POSIX system: - - </para> - - <scons_output example="read" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - --> - - <!-- - - <section> - <title>Python Value &Node;</title> - - <para> - - XXX Value() - - </para> - - </section> - - --> diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml index 1a37013..c355ca6 100644 --- a/doc/user/nodes.xml +++ b/doc/user/nodes.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-nodes" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Node Objects</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -58,10 +79,10 @@ </para> - <programlisting> - Object('hello.c', CCFLAGS='-DHELLO') - Object('goodbye.c', CCFLAGS='-DGOODBYE') - </programlisting> + <sconstruct> +Object('hello.c', CCFLAGS='-DHELLO') +Object('goodbye.c', CCFLAGS='-DGOODBYE') + </sconstruct> <para> @@ -73,11 +94,11 @@ </para> - <programlisting> - Object('hello.c', CCFLAGS='-DHELLO') - Object('goodbye.c', CCFLAGS='-DGOODBYE') - Program(['hello.o', 'goodbye.o']) - </programlisting> + <sconstruct> +Object('hello.c', CCFLAGS='-DHELLO') +Object('goodbye.c', CCFLAGS='-DGOODBYE') +Program(['hello.o', 'goodbye.o']) + </sconstruct> <para> @@ -100,11 +121,19 @@ </para> - <programlisting> - hello_list = Object('hello.c', CCFLAGS='-DHELLO') - goodbye_list = Object('goodbye.c', CCFLAGS='-DGOODBYE') - Program(hello_list + goodbye_list) - </programlisting> + <scons_example name="nodes_ex1"> + <file name="SConstruct" printme="1"> +hello_list = Object('hello.c', CCFLAGS='-DHELLO') +goodbye_list = Object('goodbye.c', CCFLAGS='-DGOODBYE') +Program(hello_list + goodbye_list) + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + <file name="goodbye.c"> +int main() { printf("Goodbye, world!\n"); } + </file> + </scons_example> <para> @@ -113,12 +142,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o goodbye.o -c -DGOODBYE goodbye.c - cc -o hello.o -c -DHELLO hello.c - cc -o hello hello.o goodbye.o - </screen> + <scons_output example="nodes_ex1" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -126,13 +152,9 @@ </para> - <screen> - C:\><userinput>scons -Q</userinput> - cl /Fogoodbye.obj /c goodbye.c -DGOODBYE - cl /Fohello.obj /c hello.c -DHELLO - link /nologo /OUT:hello.exe hello.obj goodbye.obj - embedManifestExeCheck(target, source, env) - </screen> + <scons_output example="nodes_ex1" os="win32" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -159,13 +181,15 @@ </para> - <programlisting> - hello_c = File('hello.c') - Program(hello_c) + <scons_example name="nodes_print"> + <file name="SConstruct" printme="1"> +hello_c = File('hello.c') +Program(hello_c) - classes = Dir('classes') - Java(classes, 'src') - </programlisting> +classes = Dir('classes') +Java(classes, 'src') + </file> + </scons_example> <para> @@ -204,9 +228,9 @@ </para> - <programlisting> - xyzzy = Entry('xyzzy') - </programlisting> + <sconstruct> +xyzzy = Entry('xyzzy') + </sconstruct> <para> @@ -237,18 +261,17 @@ </para> - <programlisting> - hello_c = File('hello.c') - Program(hello_c) - - classes = Dir('classes') - Java(classes, 'src') - - object_list = Object('hello.c') - program_list = Program(object_list) - print "The object file is:", object_list[0] - print "The program file is:", program_list[0] - </programlisting> + <scons_example name="nodes_print"> + <file name="SConstruct" printme="1"> +object_list = Object('hello.c') +program_list = Program(object_list) +print "The object file is:", object_list[0] +print "The program file is:", program_list[0] + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -256,13 +279,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - The object file is: hello.o - The program file is: hello - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="nodes_print" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -270,14 +289,9 @@ </para> - <screen> - C:\><userinput>scons -Q</userinput> - The object file is: hello.obj - The program file is: hello.exe - cl /Fohello.obj /c hello.c /nologo - link /nologo /OUT:hello.exe hello.obj - embedManifestExeCheck(target, source, env) - </screen> + <scons_output example="nodes_print" os="win32" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -314,13 +328,18 @@ </para> - <programlisting> - import os.path - program_list = Program('hello.c') - program_name = str(program_list[0]) - if not os.path.exists(program_name): - print program_name, "does not exist!" - </programlisting> + <scons_example name="nodes_exists"> + <file name="SConstruct" printme="1"> +import os.path +program_list = Program('hello.c') +program_name = str(program_list[0]) +if not os.path.exists(program_name): + print program_name, "does not exist!" + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -328,12 +347,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - hello does not exist! - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="nodes_exists" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -354,11 +370,13 @@ </para> - <programlisting> - env=Environment(VAR="value") - n=File("foo.c") - print env.GetBuildPath([n, "sub/dir/$VAR"]) - </programlisting> + <scons_example name="nodes_GetBuildPath"> + <file name="SConstruct" printme="1"> +env=Environment(VAR="value") +n=File("foo.c") +print env.GetBuildPath([n, "sub/dir/$VAR"]) + </file> + </scons_example> <para> @@ -366,11 +384,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - ['foo.c', 'sub/dir/value'] - scons: `.' is up to date. - </screen> + <scons_output example="nodes_GetBuildPath" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -394,15 +410,15 @@ </para> - <scons_example name="read"> + <scons_example name="nodes_read"> <file name="SConstruct" printme="1"> - hello_c = File('hello.c') - contents = hello_c.read() - print "contents are:" - print contents +hello_c = File('hello.c') +contents = hello_c.read() +print "contents are:" +print contents </file> <file name="hello.c"> - int main() { printf("Hello, world!\n"); } +int main() { printf("Hello, world!\n"); } </file> </scons_example> @@ -412,7 +428,7 @@ </para> - <scons_output example="read" os="posix"> + <scons_output example="nodes_read" os="posix" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> @@ -434,3 +450,5 @@ </section> --> + +</chapter> diff --git a/doc/user/output.in b/doc/user/output.in deleted file mode 100644 index 5acf2c5..0000000 --- a/doc/user/output.in +++ /dev/null @@ -1,681 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - A key aspect of creating a usable build configuration - is providing good output from the build - so its users can readily understand - what the build is doing - and get information about how to control the build. - &SCons; provides several ways of - controlling output from the build configuration - to help make the build - more useful and understandable. - - </para> - - <section> - <title>Providing Build Help: the &Help; Function</title> - - <para> - - It's often very useful to be able to give - users some help that describes the - specific targets, build options, etc., - that can be used for your build. - &SCons; provides the &Help; function - to allow you to specify this help text: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - Help(""" - Type: 'scons program' to build the production program, - 'scons debug' to build the debug version. - """) - </file> - </scons_example> - - <para> - - (Note the above use of the Python triple-quote syntax, - which comes in very handy for - specifying multi-line strings like help text.) - - </para> - - <para> - - When the &SConstruct; or &SConscript; files - contain such a call to the &Help; function, - the specified help text will be displayed in response to - the &SCons; <literal>-h</literal> option: - - </para> - - <scons_output example="ex1"> - <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 complete 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> - - If there is no &Help; text in the &SConstruct; or - &SConscript; files, - &SCons; will revert to displaying its - standard list that describes the &SCons; command-line - options. - This list is also always displayed whenever - the <literal>-H</literal> option is used. - - </para> - - </section> - - <section> - <title>Controlling How &SCons; Prints Build Commands: the <envar>$*COMSTR</envar> Variables</title> - - <para> - - Sometimes the commands executed - to compile object files or link programs - (or build other targets) - can get very long, - long enough to make it difficult for users - to distinguish error messages or - other important build output - from the commands themselves. - All of the default <envar>$*COM</envar> variables - that specify the command lines - used to build various types of target files - have a corresponding <envar>$*COMSTR</envar> variable - that can be set to an alternative - string that will be displayed - when the target is built. - - </para> - - <para> - - For example, suppose you want to - have &SCons; display a - <literal>"Compiling"</literal> - message whenever it's compiling an object file, - and a - <literal>"Linking"</literal> - when it's linking an executable. - You could write a &SConstruct; file - that looks like: - - </para> - - <scons_example name="COMSTR"> - <file name="SConstruct" printme="1"> - env = Environment(CCCOMSTR = "Compiling $TARGET", - LINKCOMSTR = "Linking $TARGET") - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - </scons_example> - - <para> - - Which would then yield the output: - - </para> - - <!-- - - <scons_output example="COMSTR" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - --> - - <screen> - % <userinput>scons -Q</userinput> - Compiling foo.o - Linking foo - </screen> - - <para> - - &SCons; performs complete variable substitution - on <envar>$*COMSTR</envar> variables, - so they have access to all of the - standard variables like &cv-TARGET; &cv-SOURCES;, etc., - as well as any construction variables - that happen to be configured in - the construction environment - used to build a specific target. - - </para> - - <para> - - Of course, sometimes it's still important to - be able to see the exact command - that &SCons; will execute to build a target. - For example, you may simply need to verify - that &SCons; is configured to supply - the right options to the compiler, - or a developer may want to - cut-and-paste a compile command - to add a few options - for a custom test. - - </para> - - <para> - - One common way to give users - control over whether or not - &SCons; should print the actual command line - or a short, configured summary - is to add support for a - <varname>VERBOSE</varname> - command-line variable to your &SConstruct; file. - A simple configuration for this might look like: - - </para> - - <scons_example name="COMSTR-VERBOSE"> - <file name="SConstruct" printme="1"> - env = Environment() - if ARGUMENTS.get('VERBOSE') != "1': - env['CCCOMSTR'] = "Compiling $TARGET" - env['LINKCOMSTR'] = "Linking $TARGET" - env.Program('foo.c') - </file> - <file name="foo.c"> - foo.c - </file> - </scons_example> - - <para> - - - By only setting the appropriate - <envar>$*COMSTR</envar> variables - if the user specifies - <literal>VERBOSE=1</literal> - on the command line, - the user has control - over how &SCons; - displays these particular command lines: - - </para> - - <!-- - - <scons_output example="COMSTR-VERBOSE" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q -c</scons_output_command> - <scons_output_command>scons -Q VERBOSE=1</scons_output_command> - </scons_output> - - --> - - <screen> - % <userinput>scons -Q</userinput> - Compiling foo.o - Linking foo - % <userinput>scons -Q -c</userinput> - Removed foo.o - Removed foo - % <userinput>scons -Q VERBOSE=1</userinput> - cc -o foo.o -c foo.c - cc -o foo foo.o - </screen> - - </section> - - <section> - <title>Providing Build Progress Output: the &Progress; Function</title> - - <para> - - Another aspect of providing good build output - is to give the user feedback - about what &SCons; is doing - even when nothing is being built at the moment. - This can be especially true for large builds - when most of the targets are already up-to-date. - Because &SCons; can take a long time - making absolutely sure that every - target is, in fact, up-to-date - with respect to a lot of dependency files, - it can be easy for users to mistakenly - conclude that &SCons; is hung - or that there is some other problem with the build. - - </para> - - <para> - - One way to deal with this perception - is to configure &SCons; to print something to - let the user know what it's "thinking about." - The &Progress; function - allows you to specify a string - that will be printed for every file - that &SCons; is "considering" - while it is traversing the dependency graph - to decide what targets are or are not up-to-date. - - </para> - - <scons_example name="Progress-TARGET"> - <file name="SConstruct" printme="1"> - Progress('Evaluating $TARGET\n') - Program('f1.c') - Program('f2.c') - </file> - <file name="f1.c"> - f1.c - </file> - <file name="f2.c"> - f2.c - </file> - </scons_example> - - <para> - - Note that the &Progress; function does not - arrange for a newline to be printed automatically - at the end of the string (as does the Python - <literal>print</literal> statement), - and we must specify the - <literal>\n</literal> - that we want printed at the end of the configured string. - This configuration, then, - will have &SCons; - print that it is <literal>Evaluating</literal> - each file that it encounters - in turn as it traverses the dependency graph: - - </para> - - <scons_output example="Progress-TARGET" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Of course, normally you don't want to add - all of these additional lines to your build output, - as that can make it difficult for the user - to find errors or other important messages. - A more useful way to display - this progress might be - to have the file names printed - directly to the user's screen, - not to the same standard output - stream where build output is printed, - and to use a carriage return character - (<literal>\r</literal>) - so that each file name gets re-printed on the same line. - Such a configuration would look like: - - </para> - - <sconstruct> - Progress('$TARGET\r', - file=open('/dev/tty', 'w'), - overwrite=True) - Program('f1.c') - Program('f2.c') - </sconstruct> - - <para> - - Note that we also specified the - <literal>overwrite=True</literal> argument - to the &Progress; function, - which causes &SCons; to - "wipe out" the previous string with space characters - before printing the next &Progress; string. - Without the - <literal>overwrite=True</literal> argument, - a shorter file name would not overwrite - all of the charactes in a longer file name that - precedes it, - making it difficult to tell what the - actual file name is on the output. - Also note that we opened up the - <filename>/dev/tty</filename> file - for direct access (on POSIX) to - the user's screen. - On Windows, the equivalent would be to open - the <filename>con:</filename> file name. - - </para> - - <para> - - Also, it's important to know that although you can use - <literal>$TARGET</literal> to substitute the name of - the node in the string, - the &Progress; function does <emphasis>not</emphasis> - perform general variable substitution - (because there's not necessarily a construction - environment involved in evaluating a node - like a source file, for example). - - </para> - - <para> - - You can also specify a list of strings - to the &Progress; function, - in which case &SCons; will - display each string in turn. - This can be used to implement a "spinner" - by having &SCons; cycle through a - sequence of strings: - - </para> - - <sconstruct> - Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5) - Program('f1.c') - Program('f2.c') - </sconstruct> - - <para> - - Note that here we have also used the - <literal>interval=</literal> - keyword argument to have &SCons; - only print a new "spinner" string - once every five evaluated nodes. - Using an <literal>interval=</literal> count, - even with strings that use <literal>$TARGET</literal> like - our examples above, - can be a good way to lessen the - work that &SCons; expends printing &Progress; strings, - while still giving the user feedback - that indicates &SCons; is still - working on evaluating the build. - - </para> - - <para> - - Lastly, you can have direct control - over how to print each evaluated node - by passing a Python function - (or other Python callable) - to the &Progress; function. - Your function will be called - for each evaluated node, - allowing you to - implement more sophisticated logic - like adding a counter: - - </para> - - <scons_example name="Progress-callable"> - <file name="SConstruct" printme="1"> - screen = open('/dev/tty', 'w') - count = 0 - def progress_function(node) - count += 1 - screen.write('Node %4d: %s\r' % (count, node)) - - Progress(progress_function) - </file> - </scons_example> - - <para> - - Of course, if you choose, - you could completely ignore the - <varname>node</varname> argument to the function, - and just print a count, - or anything else you wish. - - </para> - - <para> - - (Note that there's an obvious follow-on question here: - how would you find the total number of nodes - that <emphasis>will be</emphasis> - evaluated so you can tell the user how - close the build is to finishing? - Unfortunately, in the general case, - there isn't a good way to do that, - short of having &SCons; evaluate its - dependency graph twice, - first to count the total and - the second time to actually build the targets. - This would be necessary because - you can't know in advance which - target(s) the user actually requested - to be built. - The entire build may consist of thousands of Nodes, - for example, - but maybe the user specifically requested - that only a single object file be built.) - - </para> - - </section> - - <section> - <title>Printing Detailed Build Status: the &GetBuildFailures; Function</title> - - <para> - - SCons, like most build tools, returns zero status to - the shell on success and nonzero status on failure. - Sometimes it's useful to give more information about - the build status at the end of the run, for instance - to print an informative message, send an email, or - page the poor slob who broke the build. - - </para> - - <para> - - SCons provides a &GetBuildFailures; method that - you can use in a python <function>atexit</function> function - to get a list of objects describing the actions that failed - while attempting to build targets. There can be more - than one if you're using <literal>-j</literal>. Here's a - simple example: - - </para> - - <scons_example name="gbf1"> - <file name="SConstruct" printme="1"> - import atexit - - def print_build_failures(): - from SCons.Script import GetBuildFailures - for bf in GetBuildFailures(): - print "%s failed: %s" % (bf.node, bf.errstr) - atexit.register(print_build_failures) - </file> - </scons_example> - - <para> - - The <function>atexit.register</function> call - registers <function>print_build_failures</function> - as an <function>atexit</function> callback, to be called - before &SCons; exits. When that function is called, - it calls &GetBuildFailures; to fetch the list of failed objects. - See the man page - for the detailed contents of the returned objects; - some of the more useful attributes are - <literal>.node</literal>, - <literal>.errstr</literal>, - <literal>.filename</literal>, and - <literal>.command</literal>. - The <literal>filename</literal> is not necessarily - the same file as the <literal>node</literal>; the - <literal>node</literal> is the target that was - being built when the error occurred, while the - <literal>filename</literal>is the file or dir that - actually caused the error. - Note: only call &GetBuildFailures; at the end of the - build; calling it at any other time is undefined. - - </para> - - <para> - - Here is a more complete example showing how to - turn each element of &GetBuildFailures; into a string: - - </para> - - <scons_example name="gbf2"> - <file name="SConstruct" printme="1"> - # Make the build fail if we pass fail=1 on the command line - if ARGUMENTS.get('fail', 0): - Command('target', 'source', ['/bin/false']) - - def bf_to_str(bf): - """Convert an element of GetBuildFailures() to a string - in a useful way.""" - import SCons.Errors - if bf is None: # unknown targets product None in list - return '(unknown tgt)' - elif isinstance(bf, SCons.Errors.StopError): - return str(bf) - elif bf.node: - return str(bf.node) + ': ' + bf.errstr - elif bf.filename: - return bf.filename + ': ' + bf.errstr - return 'unknown failure: ' + bf.errstr - import atexit - - def build_status(): - """Convert the build status to a 2-tuple, (status, msg).""" - from SCons.Script import GetBuildFailures - bf = GetBuildFailures() - if bf: - # bf is normally a list of build failures; if an element is None, - # it's because of a target that scons doesn't know anything about. - status = 'failed' - failures_message = "\n".join(["Failed building %s" % bf_to_str(x) - for x in bf if x is not None]) - else: - # if bf is None, the build completed successfully. - status = 'ok' - failures_message = '' - return (status, failures_message) - - def display_build_status(): - """Display the build status. Called by atexit. - Here you could do all kinds of complicated things.""" - status, failures_message = build_status() - if status == 'failed': - print "FAILED!!!!" # could display alert, ring bell, etc. - elif status == 'ok': - print "Build succeeded." - print failures_message - - atexit.register(display_build_status) - </file> - </scons_example> - - <para> - - When this runs, you'll see the appropriate output: - - </para> - - <scons_output example="gbf2"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q fail=1</scons_output_command> - </scons_output> - - </section> diff --git a/doc/user/output.xml b/doc/user/output.xml index e33d0ad..f0d3134 100644 --- a/doc/user/output.xml +++ b/doc/user/output.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-output" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Controlling Build Output</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -51,12 +72,14 @@ </para> - <programlisting> - Help(""" - Type: 'scons program' to build the production program, - 'scons debug' to build the debug version. - """) - </programlisting> + <scons_example name="output_ex1"> + <file name="SConstruct" printme="1"> +Help(""" +Type: 'scons program' to build the production program, + 'scons debug' to build the debug version. +""") + </file> + </scons_example> <para> @@ -75,16 +98,9 @@ </para> - <screen> - % <userinput>scons -h</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - - Type: 'scons program' to build the production program, - 'scons debug' to build the debug version. - - Use scons -H for help about command-line options. - </screen> + <scons_output example="output_ex1" suffix="1"> + <scons_output_command>scons -h</scons_output_command> + </scons_output> <para> @@ -114,14 +130,16 @@ </para> - <programlisting> - env = Environment() + <scons_example name="output_ex2"> + <file name="SConstruct" printme="1"> +env = Environment() - Help("\nType: 'scons program' to build the production program.\n") +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> +if env['PLATFORM'] == 'win32': + Help("\nType: 'scons windebug' to build the Windows debug version.\n") + </file> + </scons_example> <para> @@ -129,17 +147,9 @@ </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> + <scons_output example="output_ex2" os="win32" suffix="1"> + <scons_output_command>scons -h</scons_output_command> + </scons_output> <para> @@ -147,15 +157,9 @@ </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> + <scons_output example="output_ex2" os="posix" suffix="2"> + <scons_output_command>scons -h</scons_output_command> + </scons_output> <para> @@ -208,11 +212,16 @@ </para> - <programlisting> - env = Environment(CCCOMSTR = "Compiling $TARGET", - LINKCOMSTR = "Linking $TARGET") - env.Program('foo.c') - </programlisting> + <scons_example name="output_COMSTR"> + <file name="SConstruct" printme="1"> +env = Environment(CCCOMSTR = "Compiling $TARGET", + LINKCOMSTR = "Linking $TARGET") +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + </scons_example> <para> @@ -222,16 +231,16 @@ <!-- - <scons_output example="COMSTR" os="posix"> + <scons_output example="output_COMSTR" os="posix" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> <screen> - % <userinput>scons -Q</userinput> - Compiling foo.o - Linking foo +% <userinput>scons -Q</userinput> +Compiling foo.o +Linking foo </screen> <para> @@ -275,13 +284,18 @@ </para> - <programlisting> - env = Environment() - if ARGUMENTS.get('VERBOSE') != "1': - env['CCCOMSTR'] = "Compiling $TARGET" - env['LINKCOMSTR'] = "Linking $TARGET" - env.Program('foo.c') - </programlisting> + <scons_example name="output_COMSTR-VERBOSE"> + <file name="SConstruct" printme="1"> +env = Environment() +if ARGUMENTS.get('VERBOSE') != "1': + env['CCCOMSTR'] = "Compiling $TARGET" + env['LINKCOMSTR'] = "Linking $TARGET" +env.Program('foo.c') + </file> + <file name="foo.c"> +foo.c + </file> + </scons_example> <para> @@ -299,7 +313,7 @@ <!-- - <scons_output example="COMSTR-VERBOSE" os="posix"> + <scons_output example="output_COMSTR-VERBOSE" os="posix" suffix="1"> <scons_output_command>scons -Q</scons_output_command> <scons_output_command>scons -Q -c</scons_output_command> <scons_output_command>scons -Q VERBOSE=1</scons_output_command> @@ -308,15 +322,15 @@ --> <screen> - % <userinput>scons -Q</userinput> - Compiling foo.o - Linking foo - % <userinput>scons -Q -c</userinput> - Removed foo.o - Removed foo - % <userinput>scons -Q VERBOSE=1</userinput> - cc -o foo.o -c foo.c - cc -o foo foo.o +% <userinput>scons -Q</userinput> +Compiling foo.o +Linking foo +% <userinput>scons -Q -c</userinput> +Removed foo.o +Removed foo +% <userinput>scons -Q VERBOSE=1</userinput> +cc -o foo.o -c foo.c +cc -o foo foo.o </screen> </section> @@ -356,11 +370,19 @@ </para> - <programlisting> - Progress('Evaluating $TARGET\n') - Program('f1.c') - Program('f2.c') - </programlisting> + <scons_example name="output_Progress-TARGET"> + <file name="SConstruct" printme="1"> +Progress('Evaluating $TARGET\n') +Program('f1.c') +Program('f2.c') + </file> + <file name="f1.c"> +f1.c + </file> + <file name="f2.c"> +f2.c + </file> + </scons_example> <para> @@ -379,21 +401,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - Evaluating SConstruct - Evaluating f1.c - Evaluating f1.o - cc -o f1.o -c f1.c - Evaluating f1 - cc -o f1 f1.o - Evaluating f2.c - Evaluating f2.o - cc -o f2.o -c f2.c - Evaluating f2 - cc -o f2 f2.o - Evaluating . - </screen> + <scons_output example="output_Progress-TARGET" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -414,13 +424,13 @@ </para> - <programlisting> - Progress('$TARGET\r', - file=open('/dev/tty', 'w'), - overwrite=True) - Program('f1.c') - Program('f2.c') - </programlisting> + <sconstruct> +Progress('$TARGET\r', + file=open('/dev/tty', 'w'), + overwrite=True) +Program('f1.c') +Program('f2.c') + </sconstruct> <para> @@ -471,11 +481,11 @@ </para> - <programlisting> - Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5) - Program('f1.c') - Program('f2.c') - </programlisting> + <sconstruct> +Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5) +Program('f1.c') +Program('f2.c') + </sconstruct> <para> @@ -510,15 +520,17 @@ </para> - <programlisting> - screen = open('/dev/tty', 'w') - count = 0 - def progress_function(node) - count += 1 - screen.write('Node %4d: %s\r' % (count, node)) + <scons_example name="output_Progress-callable"> + <file name="SConstruct" printme="1"> +screen = open('/dev/tty', 'w') +count = 0 +def progress_function(node) + count += 1 + screen.write('Node %4d: %s\r' % (count, node)) - Progress(progress_function) - </programlisting> +Progress(progress_function) + </file> + </scons_example> <para> @@ -581,15 +593,17 @@ </para> - <programlisting> - import atexit + <scons_example name="output_gbf1"> + <file name="SConstruct" printme="1"> +import atexit - def print_build_failures(): - from SCons.Script import GetBuildFailures - for bf in GetBuildFailures(): - print "%s failed: %s" % (bf.node, bf.errstr) - atexit.register(print_build_failures) - </programlisting> +def print_build_failures(): + from SCons.Script import GetBuildFailures + for bf in GetBuildFailures(): + print "%s failed: %s" % (bf.node, bf.errstr) +atexit.register(print_build_failures) + </file> + </scons_example> <para> @@ -623,54 +637,56 @@ </para> - <programlisting> - # Make the build fail if we pass fail=1 on the command line - if ARGUMENTS.get('fail', 0): - Command('target', 'source', ['/bin/false']) - - def bf_to_str(bf): - """Convert an element of GetBuildFailures() to a string - in a useful way.""" - import SCons.Errors - if bf is None: # unknown targets product None in list - return '(unknown tgt)' - elif isinstance(bf, SCons.Errors.StopError): - return str(bf) - elif bf.node: - return str(bf.node) + ': ' + bf.errstr - elif bf.filename: - return bf.filename + ': ' + bf.errstr - return 'unknown failure: ' + bf.errstr - import atexit - - def build_status(): - """Convert the build status to a 2-tuple, (status, msg).""" - from SCons.Script import GetBuildFailures - bf = GetBuildFailures() - if bf: - # bf is normally a list of build failures; if an element is None, - # it's because of a target that scons doesn't know anything about. - status = 'failed' - failures_message = "\n".join(["Failed building %s" % bf_to_str(x) - for x in bf if x is not None]) - else: - # if bf is None, the build completed successfully. - status = 'ok' - failures_message = '' - return (status, failures_message) - - def display_build_status(): - """Display the build status. Called by atexit. - Here you could do all kinds of complicated things.""" - status, failures_message = build_status() - if status == 'failed': - print "FAILED!!!!" # could display alert, ring bell, etc. - elif status == 'ok': - print "Build succeeded." - print failures_message - - atexit.register(display_build_status) - </programlisting> + <scons_example name="output_gbf2"> + <file name="SConstruct" printme="1"> +# Make the build fail if we pass fail=1 on the command line +if ARGUMENTS.get('fail', 0): + Command('target', 'source', ['/bin/false']) + +def bf_to_str(bf): + """Convert an element of GetBuildFailures() to a string + in a useful way.""" + import SCons.Errors + if bf is None: # unknown targets product None in list + return '(unknown tgt)' + elif isinstance(bf, SCons.Errors.StopError): + return str(bf) + elif bf.node: + return str(bf.node) + ': ' + bf.errstr + elif bf.filename: + return bf.filename + ': ' + bf.errstr + return 'unknown failure: ' + bf.errstr +import atexit + +def build_status(): + """Convert the build status to a 2-tuple, (status, msg).""" + from SCons.Script import GetBuildFailures + bf = GetBuildFailures() + if bf: + # bf is normally a list of build failures; if an element is None, + # it's because of a target that scons doesn't know anything about. + status = 'failed' + failures_message = "\n".join(["Failed building %s" % bf_to_str(x) + for x in bf if x is not None]) + else: + # if bf is None, the build completed successfully. + status = 'ok' + failures_message = '' + return (status, failures_message) + +def display_build_status(): + """Display the build status. Called by atexit. + Here you could do all kinds of complicated things.""" + status, failures_message = build_status() + if status == 'failed': + print "FAILED!!!!" # could display alert, ring bell, etc. + elif status == 'ok': + print "Build succeeded." + print failures_message + +atexit.register(display_build_status) + </file> + </scons_example> <para> @@ -678,14 +694,11 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - scons: `.' is up to date. - Build succeeded. - % <userinput>scons -Q fail=1</userinput> - scons: *** [target] Source `source' not found, needed by target `target'. - FAILED!!!! - Failed building target: Source `source' not found, needed by target `target'. - </screen> + <scons_output example="output_gbf2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q fail=1</scons_output_command> + </scons_output> </section> + +</chapter> diff --git a/doc/user/parseconfig.in b/doc/user/parseconfig.in deleted file mode 100644 index 0566fe9..0000000 --- a/doc/user/parseconfig.in +++ /dev/null @@ -1,140 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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 - libraries--especially shared libraries--that are available - on POSIX systems can be very complicated. - To help this situation, - various utilies with names that end in <filename>config</filename> - return the command-line options for the GNU Compiler Collection (GCC) - that are needed to use these libraries; - for example, the command-line options - to use a library named <filename>lib</filename> - would be found by calling a utility named <filename>lib-config</filename>. - - </para> - - <para> - - A more recent convention is that these options - are available from the generic <filename>pkg-config</filename> program, - which has common framework, error handling, and the like, - so that all the package creator has to do is provide the set of strings - for his particular package. - - </para> - - <para> - - &SCons; construction environments have a &ParseConfig; method - that executes a <filename>*config</filename> utility - (either <filename>pkg-config</filename> or a - more specific utility) - and configures the appropriate construction variables - in the environment - based on the command-line options - returned by the specified command. - - </para> - - <scons_example name="ParseConfig1"> - <file name="SConstruct" printme="1"> - env = Environment() - env['CPPPATH'] = ['/lib/compat'] - env.ParseConfig("pkg-config x11 --cflags --libs") - print env['CPPPATH'] - </file> - </scons_example> - - <para> - - &SCons; will execute the specified command string, - parse the resultant flags, - and add the flags to the appropriate environment variables. - - </para> - - <!-- - This is how we used to generate the screen output below, but - as of (at least) Ubuntu Karmic, the pkg-config output for x11 - no longer reports back an include directory. Since this is just - for example anyway, we're just hard-coding the output. - - <scons_output example="ParseConfig1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - --> - - <screen> - % <userinput>scons -Q</userinput> - ['/lib/compat', '/usr/X11/include'] - scons: `.' is up to date. - </screen> - - <para> - - In the example above, &SCons; has added the include directory to - <varname>CPPPATH</varname>. - (Depending upon what other flags are emitted by the - <filename>pkg-config</filename> command, - other variables may have been extended as well.) - - </para> - - <para> - - Note that the options are merged with existing options using - the &MergeFlags; method, - so that each option only occurs once in the construction variable: - - </para> - - <scons_example name="ParseConfig2"> - <file name="SConstruct" printme="1"> - env = Environment() - env.ParseConfig("pkg-config x11 --cflags --libs") - env.ParseConfig("pkg-config x11 --cflags --libs") - print env['CPPPATH'] - </file> - </scons_example> - - <!-- - This is how we used to generate the screen output below, but - as of (at least) Ubuntu Karmic, the pkg-config output for x11 - no longer reports back an include directory. Since this is just - for example anyway, we're just hard-coding the output. - - <scons_output example="ParseConfig2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - --> - - <screen> - % <userinput>scons -Q</userinput> - ['/usr/X11/include'] - scons: `.' is up to date. - </screen> diff --git a/doc/user/parseconfig.xml b/doc/user/parseconfig.xml index 8f767e2..205416b 100644 --- a/doc/user/parseconfig.xml +++ b/doc/user/parseconfig.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<section id="sect-parseconfig" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Finding Installed Library Information: the &ParseConfig; Function</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -61,12 +82,14 @@ </para> - <programlisting> - env = Environment() - env['CPPPATH'] = ['/lib/compat'] - env.ParseConfig("pkg-config x11 --cflags --libs") - print env['CPPPATH'] - </programlisting> + <scons_example name="parseconfig_ex1"> + <file name="SConstruct" printme="1"> +env = Environment() +env['CPPPATH'] = ['/lib/compat'] +env.ParseConfig("pkg-config x11 --cflags --libs") +print env['CPPPATH'] + </file> + </scons_example> <para> @@ -82,15 +105,15 @@ no longer reports back an include directory. Since this is just for example anyway, we're just hard-coding the output. - <scons_output example="ParseConfig1"> + <scons_output example="parseconfig_ex1" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> <screen> - % <userinput>scons -Q</userinput> - ['/lib/compat', '/usr/X11/include'] - scons: `.' is up to date. +% <userinput>scons -Q</userinput> +['/lib/compat', '/usr/X11/include'] +scons: `.' is up to date. </screen> <para> @@ -111,12 +134,14 @@ </para> - <programlisting> - env = Environment() - env.ParseConfig("pkg-config x11 --cflags --libs") - env.ParseConfig("pkg-config x11 --cflags --libs") - print env['CPPPATH'] - </programlisting> + <scons_example name="parseconfig_ex2"> + <file name="SConstruct" printme="1"> +env = Environment() +env.ParseConfig("pkg-config x11 --cflags --libs") +env.ParseConfig("pkg-config x11 --cflags --libs") +print env['CPPPATH'] + </file> + </scons_example> <!-- This is how we used to generate the screen output below, but @@ -124,13 +149,15 @@ no longer reports back an include directory. Since this is just for example anyway, we're just hard-coding the output. - <scons_output example="ParseConfig2"> + <scons_output example="parseconfig_ex2" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> <screen> - % <userinput>scons -Q</userinput> - ['/usr/X11/include'] - scons: `.' is up to date. +% <userinput>scons -Q</userinput> +['/usr/X11/include'] +scons: `.' is up to date. </screen> + +</section> diff --git a/doc/user/parseflags.in b/doc/user/parseflags.in deleted file mode 100644 index 6ec716d..0000000 --- a/doc/user/parseflags.in +++ /dev/null @@ -1,176 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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; has a bewildering array of construction variables - for different types of options when building programs. - Sometimes you may not know exactly which variable - should be used for a particular option. - - </para> - - <para> - - &SCons; construction environments have a &ParseFlags; method - that takes a set of typical command-line options - and distrbutes them into the appropriate construction variables. - Historically, it was created to support the &ParseConfig; method, - so it focuses on options used by the GNU Compiler Collection (GCC) - for the C and C++ toolchains. - - </para> - - <para> - - &ParseFlags; returns a dictionary containing the options - distributed into their respective construction variables. - Normally, this dictionary would be passed to &MergeFlags; - to merge the options into a &consenv;, - but the dictionary can be edited if desired to provide - additional functionality. - (Note that if the flags are not going to be edited, - calling &MergeFlags; with the options directly - will avoid an additional step.) - - </para> - - <scons_example name="ParseFlags1"> - <file name="SConstruct" printme="1"> - env = Environment() - d = env.ParseFlags("-I/opt/include -L/opt/lib -lfoo") - for k,v in sorted(d.items()): - if v: - print k, v - env.MergeFlags(d) - env.Program('f1.c') - </file> - <file name="f1.c"> - int main() { return 0; } - </file> - </scons_example> - - <scons_output example="ParseFlags1" os="posix"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Note that if the options are limited to generic types - like those above, - they will be correctly translated for other platform types: - - </para> - - <scons_output example="ParseFlags1" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Since the assumption is that the flags are used for the GCC toolchain, - unrecognized flags are placed in &cv-link-CCFLAGS; - so they will be used for both C and C++ compiles: - - </para> - - <scons_example name="ParseFlags2"> - <file name="SConstruct" printme="1"> - env = Environment() - d = env.ParseFlags("-whatever") - for k,v in sorted(d.items()): - if v: - print k, v - env.MergeFlags(d) - env.Program('f1.c') - </file> - <file name="f1.c"> - int main() { return 0; } - </file> - </scons_example> - - <scons_output example="ParseFlags2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - &ParseFlags; will also accept a (recursive) list of strings as input; - the list is flattened before the strings are processed: - - </para> - - <scons_example name="ParseFlags3"> - <file name="SConstruct" printme="1"> - env = Environment() - d = env.ParseFlags(["-I/opt/include", ["-L/opt/lib", "-lfoo"]]) - for k,v in sorted(d.items()): - if v: - print k, v - env.MergeFlags(d) - env.Program('f1.c') - </file> - <file name="f1.c"> - int main() { return 0; } - </file> - </scons_example> - - <scons_output example="ParseFlags3"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - If a string begins with a "!" (an exclamation mark, often called a bang), - the string is passed to the shell for execution. - The output of the command is then parsed: - - </para> - - <scons_example name="ParseFlags4"> - <file name="SConstruct" printme="1"> - env = Environment() - d = env.ParseFlags(["!echo -I/opt/include", "!echo -L/opt/lib", "-lfoo"]) - for k,v in sorted(d.items()): - if v: - print k, v - env.MergeFlags(d) - env.Program('f1.c') - </file> - <file name="f1.c"> - int main() { return 0; } - </file> - </scons_example> - - <scons_output example="ParseFlags4"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - &ParseFlags; is regularly updated for new options; - consult the man page for details about those currently recognized. - - </para> diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml index 4bf572a..d5012e1 100644 --- a/doc/user/parseflags.xml +++ b/doc/user/parseflags.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<section id="sect-parseflags" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -57,24 +78,24 @@ </para> - <programlisting> - env = Environment() - d = env.ParseFlags("-I/opt/include -L/opt/lib -lfoo") - for k,v in sorted(d.items()): - if v: - print k, v - env.MergeFlags(d) - env.Program('f1.c') - </programlisting> - - <screen> - % <userinput>scons -Q</userinput> - CPPPATH ['/opt/include'] - LIBPATH ['/opt/lib'] - LIBS ['foo'] - cc -o f1.o -c -I/opt/include f1.c - cc -o f1 f1.o -L/opt/lib -lfoo - </screen> + <scons_example name="parseflags_ex1"> + <file name="SConstruct" printme="1"> +env = Environment() +d = env.ParseFlags("-I/opt/include -L/opt/lib -lfoo") +for k,v in sorted(d.items()): + if v: + print k, v +env.MergeFlags(d) +env.Program('f1.c') + </file> + <file name="f1.c"> +int main() { return 0; } + </file> + </scons_example> + + <scons_output example="parseflags_ex1" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -84,15 +105,9 @@ </para> - <screen> - C:\><userinput>scons -Q</userinput> - CPPPATH ['/opt/include'] - LIBPATH ['/opt/lib'] - LIBS ['foo'] - cl /Fof1.obj /c f1.c /nologo /I\opt\include - link /nologo /OUT:f1.exe /LIBPATH:\opt\lib foo.lib f1.obj - embedManifestExeCheck(target, source, env) - </screen> + <scons_output example="parseflags_ex1" os="win32" suffix="2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -102,22 +117,24 @@ </para> - <programlisting> - env = Environment() - d = env.ParseFlags("-whatever") - for k,v in sorted(d.items()): - if v: - print k, v - env.MergeFlags(d) - env.Program('f1.c') - </programlisting> - - <screen> - % <userinput>scons -Q</userinput> - CCFLAGS -whatever - cc -o f1.o -c -whatever f1.c - cc -o f1 f1.o - </screen> + <scons_example name="parseflags_ex2"> + <file name="SConstruct" printme="1"> +env = Environment() +d = env.ParseFlags("-whatever") +for k,v in sorted(d.items()): + if v: + print k, v +env.MergeFlags(d) +env.Program('f1.c') + </file> + <file name="f1.c"> + int main() { return 0; } + </file> + </scons_example> + + <scons_output example="parseflags_ex2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -126,24 +143,24 @@ </para> - <programlisting> - env = Environment() - d = env.ParseFlags(["-I/opt/include", ["-L/opt/lib", "-lfoo"]]) - for k,v in sorted(d.items()): - if v: - print k, v - env.MergeFlags(d) - env.Program('f1.c') - </programlisting> - - <screen> - % <userinput>scons -Q</userinput> - CPPPATH ['/opt/include'] - LIBPATH ['/opt/lib'] - LIBS ['foo'] - cc -o f1.o -c -I/opt/include f1.c - cc -o f1 f1.o -L/opt/lib -lfoo - </screen> + <scons_example name="parseflags_ex3"> + <file name="SConstruct" printme="1"> +env = Environment() +d = env.ParseFlags(["-I/opt/include", ["-L/opt/lib", "-lfoo"]]) +for k,v in sorted(d.items()): + if v: + print k, v +env.MergeFlags(d) +env.Program('f1.c') + </file> + <file name="f1.c"> +int main() { return 0; } + </file> + </scons_example> + + <scons_output example="parseflags_ex3" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -153,24 +170,24 @@ </para> - <programlisting> - env = Environment() - d = env.ParseFlags(["!echo -I/opt/include", "!echo -L/opt/lib", "-lfoo"]) - for k,v in sorted(d.items()): - if v: - print k, v - env.MergeFlags(d) - env.Program('f1.c') - </programlisting> - - <screen> - % <userinput>scons -Q</userinput> - CPPPATH ['/opt/include'] - LIBPATH ['/opt/lib'] - LIBS ['foo'] - cc -o f1.o -c -I/opt/include f1.c - cc -o f1 f1.o -L/opt/lib -lfoo - </screen> + <scons_example name="parseflags_ex4"> + <file name="SConstruct" printme="1"> +env = Environment() +d = env.ParseFlags(["!echo -I/opt/include", "!echo -L/opt/lib", "-lfoo"]) +for k,v in sorted(d.items()): + if v: + print k, v +env.MergeFlags(d) +env.Program('f1.c') + </file> + <file name="f1.c"> +int main() { return 0; } + </file> + </scons_example> + + <scons_output example="parseflags_ex4" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -178,3 +195,5 @@ consult the man page for details about those currently recognized. </para> + +</section> diff --git a/doc/user/pdf.xsl b/doc/user/pdf.xsl new file mode 100644 index 0000000..b536092 --- /dev/null +++ b/doc/user/pdf.xsl @@ -0,0 +1,75 @@ +<?xml version='1.0'?>
+<!--
+
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation
+
+ 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.
+
+-->
+
+<xsl:stylesheet
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ version="1.0">
+
+ <xsl:import href="../../src/engine/SCons/Tool/docbook/docbook-xsl-1.76.1/fo/docbook.xsl"/>
+ <xsl:include href="scons_title.xsl"/>
+<xsl:param name="l10n.gentext.default.language" select="'en'"/>
+<xsl:param name="section.autolabel" select="1"></xsl:param>
+<xsl:param name="paper.type" select="'letter'"></xsl:param>
+<xsl:param name="body.start.indent">0pt</xsl:param>
+<xsl:param name="shade.verbatim" select="1"></xsl:param>
+<xsl:param name="variablelist.term.break.after" select="1"></xsl:param>
+
+<xsl:param name="generate.toc">
+/appendix toc,title
+article/appendix nop
+/article toc,title
+book toc,title,figure,table,example,equation
+/chapter toc,title
+part toc,title
+/preface toc,title
+reference toc,title
+/sect1 toc
+/sect2 toc
+/sect3 toc
+/sect4 toc
+/sect5 toc
+/section toc
+set toc,title
+</xsl:param>
+
+<xsl:attribute-set name="variablelist.term.properties">
+ <xsl:attribute name="font-weight">bold</xsl:attribute>
+</xsl:attribute-set>
+
+<xsl:template match="variablelist">
+ <xsl:variable name="presentation">
+ <xsl:call-template name="pi.dbfo_list-presentation"/>
+ </xsl:variable>
+ <xsl:apply-templates select="." mode="vl.as.blocks"/>
+</xsl:template>
+
+<!-- Prevent our EPUB cover image from getting printed to the PDF -->
+<xsl:template match="mediaobject[@role = 'cover']">
+</xsl:template>
+
+</xsl:stylesheet>
+
diff --git a/doc/user/preface.in b/doc/user/preface.in deleted file mode 100644 index aa8eaf4..0000000 --- a/doc/user/preface.in +++ /dev/null @@ -1,426 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - Thank you for taking the time to read about &SCons;. - &SCons; is a next-generation - software construction tool, - or make tool--that is, a software utility - for building software (or other files) - and keeping built software up-to-date - whenever the underlying input files change. - - </para> - - <para> - - The most distinctive thing about &SCons; - is that its configuration files are - actually <emphasis>scripts</emphasis>, - written in the &Python; programming language. - This is in contrast to most alternative build tools, - which typically invent a new language to - configure the build. - &SCons; still has a learning curve, of course, - because you have to know what functions to call - to set up your build properly, - but the underlying syntax used should be familiar - to anyone who has ever looked at a Python script. - - </para> - - <para> - - Paradoxically, - using Python as the configuration file format - makes &SCons; - <emphasis>easier</emphasis> - for non-programmers to learn - than the cryptic languages of other build tools, - which are usually invented by programmers for other programmers. - This is in no small part due to the - consistency and readability that are hallmarks of Python. - It just so happens that making a real, live - scripting language the basis for the - configuration files - makes it a snap for more accomplished programmers - to do more complicated things with builds, - as necessary. - - </para> - - <!-- - - <section> - <title>Why &SCons;?</title> - - <para> - - &SCons; is a response to a perennial problem: - building software is harder than it should be. - In a nutshell: the old, reliable model of the - venerable and ubiquitous &Make; program - has had a hard time keeping up with - how complicated building software has become. - The fact that &Make; has kept up as well as it has is impressive, - and a testament to how the simplicity. - But anyone who has wrestled with &Automake; and &Autoconf; - to try to guarantee that a bit of software - will build correctly on multiple platforms - can tell you that it takes a lot of work to get right. - - </para> - - </section> - - --> - - <section> - <title>&SCons; Principles</title> - - <para> - - There are a few overriding principles - we try to live up to in designing and implementing &SCons;: - - </para> - - <variablelist> - - <varlistentry> - <term>Correctness</term> - - <listitem> - <para> - - First and foremost, - by default, &SCons; guarantees a correct build - even if it means sacrificing performance a little. - We strive to guarantee the build is correct - regardless of how the software being built is structured, - how it may have been written, - or how unusual the tools are that build it. - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Performance</term> - - <listitem> - <para> - - Given that the build is correct, - we try to make &SCons; build software - as quickly as possible. - In particular, wherever we may have needed to slow - down the default &SCons; behavior to guarantee a correct build, - we also try to make it easy to speed up &SCons; - through optimization options that let you trade off - guaranteed correctness in all end cases for - a speedier build in the usual cases. - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Convenience</term> - - <listitem> - <para> - - &SCons; tries to do as much for you out of the box as reasonable, - including detecting the right tools on your system - and using them correctly to build the software. - - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - - In a nutshell, we try hard to make &SCons; just - "do the right thing" and build software correctly, - with a minimum of hassles. - - </para> - - </section> - - <!-- - - <section> - <title>History</title> - - <para> - - &SCons; originated with a design - that was submitted to the Software Carpentry - design competition in 2000. - - </para> - - <para> - - &SCons; is the direct descendant - of a Perl utility called &Cons;. - &Cons; in turn based some of its ideas on &Jam;, - a build tool from Perforce Systems. - - </para> - - <para> - - XXX history of SCons - - </para> - - </section> - - --> - - <!-- - - <section> - <title>Conventions</title> - - <para> - - XXX conventions used in this manual - - </para> - - </section> - - --> - - <section> - <title>A Caveat About This Guide's Completeness</title> - - <para> - - One word of warning as you read through this Guide: - Like too much Open Source software out there, - 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. - (Come to think of it, - that also describes a lot of proprietary software, doesn't it?) - - </para> - - <para> - - Although this User's Guide isn't as complete as we'd like it to be, - our development process does emphasize - making sure that the &SCons; man page is kept up-to-date - with new features. - So if you're trying to figure out how to do something - that &SCons; supports - but can't find enough (or any) information here, - it would be worth your while to look - at the man page to see if the information is covered there. - And if you do, - maybe you'd even consider contributing - a section to the User's Guide - so the next person looking for - that information won't have to - go through the same thing...? - - </para> - - </section> - - <section> - <title>Acknowledgements</title> - - <para> - - &SCons; would not exist without a lot of help - from a lot of people, - many of whom may not even be aware - that they helped or served as inspiration. - So in no particular order, - and at the risk of leaving out someone: - - </para> - - <para> - - First and foremost, - &SCons; owes a tremendous debt to Bob Sidebotham, - the original author of the classic Perl-based &Cons; tool - which Bob first released to the world back around 1996. - Bob's work on Cons classic provided the underlying architecture - and model of specifying a build configuration - using a real scripting language. - My real-world experience working on Cons - informed many of the design decisions in SCons, - including the improved parallel build support, - making Builder objects easily definable by users, - and separating the build engine from the wrapping interface. - - </para> - - <para> - - Greg Wilson was instrumental in getting - &SCons; started as a real project - when he initiated the Software Carpentry design - competition in February 2000. - Without that nudge, - marrying the advantages of the Cons classic - architecture with the readability of Python - might have just stayed no more than a nice idea. - - </para> - - <para> - - The entire &SCons; team have been - absolutely wonderful to work with, - and &SCons; would be nowhere near as useful a - tool without the energy, enthusiasm - and time people have contributed over the past few years. - The "core team" - of Chad Austin, Anthony Roach, - Bill Deegan, Charles Crain, Steve Leblanc, Greg Noel, - Gary Oberbrunner, Greg Spencer and Christoph Wiedemann - have been great about reviewing my (and other) changes - and catching problems before they get in the code base. - Of particular technical note: - Anthony's outstanding and innovative work on the tasking engine - has given &SCons; a vastly superior parallel build model; - Charles has been the master of the crucial Node infrastructure; - Christoph's work on the Configure infrastructure - has added crucial Autoconf-like functionality; - and Greg has provided excellent support - for Microsoft Visual Studio. - - </para> - - <para> - - Special thanks to David Snopek for contributing - his underlying "Autoscons" code that formed - the basis of Christoph's work with the Configure functionality. - David was extremely generous in making - this code available to &SCons;, - given that he initially released it under the GPL - and &SCons; is released under a less-restrictive MIT-style license. - - </para> - - <!-- - - <para> - - &SCons; has received contributions - from many other people, of course: - Matt Balvin (extending long command-line support on Windows), - Allen Bierbaum (extensions and fixes to Options), - Steve Christensen (help text sorting and function action signature fixes), - Michael Cook (avoiding losing signal bits from executed commands), - Derrick 'dman' Hudson (), - Alex Jacques (work on the Windows scons.bat file), - Stephen Kennedy (performance enhancements), - Lachlan O'Dea (SharedObject() support for masm - and normalized paths for the WhereIs() function), - Damyan Pepper (keeping output like Make), - Jeff Petkau (significant fixes for CacheDir and other areas), - Stefan Reichor (Ghostscript support), - Zed Shaw (Append() and Replace() environment methods), - Terrel Shumway (build and test fixes, as well as the SCons Wiki) - and - sam th (dynamic checks for utilities). - - </para> - - --> - - <para> - - Thanks to Peter Miller - for his splendid change management system, &Aegis;, - which has provided the &SCons; project - with a robust development methodology from day one, - and which showed me how you could - integrate incremental regression tests into - a practical development cycle - (years before eXtreme Programming arrived on the scene). - - </para> - - <para> - - And last, thanks to Guido van Rossum - for his elegant scripting language, - which is the basis not only for the &SCons; implementation, - but for the interface itself. - - </para> - - </section> - - <section> - <title>Contact</title> - - <para> - - The best way to contact people involved with SCons, - including the author, - is through the SCons mailing lists. - - </para> - - <para> - - If you want to ask general questions about how to use &SCons; - send email to &scons-users;. - - </para> - - <para> - - If you want to contact the &SCons; development community directly, - send email to &scons-devel;. - - </para> - - <para> - - If you want to receive announcements about &SCons;, - join the low-volume &scons-announce; mailing list. - - </para> - - </section> diff --git a/doc/user/preface.xml b/doc/user/preface.xml index aa8eaf4..3937e57 100644 --- a/doc/user/preface.xml +++ b/doc/user/preface.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<preface id="chap-preface" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Preface</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -424,3 +445,5 @@ </para> </section> + +</preface> diff --git a/doc/user/python.in b/doc/user/python.in deleted file mode 100644 index 90a20d0..0000000 --- a/doc/user/python.in +++ /dev/null @@ -1,154 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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.xml b/doc/user/python.xml index 90a20d0..67b7671 100644 --- a/doc/user/python.xml +++ b/doc/user/python.xml @@ -1,6 +1,28 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; + +]> + +<appendix id="app-python" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Python overview</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -23,11 +45,6 @@ --> - <!-- - - <section> - <title>Python Overview</title> - <para> This section will provide a brief overview of @@ -149,6 +166,4 @@ </para> - </section> - - --> +</appendix> diff --git a/doc/user/repositories.in b/doc/user/repositories.in deleted file mode 100644 index 28d1233..0000000 --- a/doc/user/repositories.in +++ /dev/null @@ -1,641 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - Often, a software project will have - one or more central repositories, - directory trees that contain - source code, or derived files, or both. - You can eliminate additional unnecessary - rebuilds of files by having &SCons; - use files from one or more code repositories - to build files in your local build tree. - - </para> - - <section> - <title>The &Repository; Method</title> - - <!-- - - The repository directories specified may contain source files, derived files - (objects, libraries and executables), or both. If there is no local file - (source or derived) under the directory in which Cons is executed, then the - first copy of a same-named file found under a repository directory will be - used to build any local derived files. - - --> - - <para> - - It's often useful to allow multiple programmers working - on a project to build software from - source files and/or derived files that - are stored in a centrally-accessible repository, - a directory copy of the source code tree. - (Note that this is not the sort of repository - maintained by a source code management system - like BitKeeper, CVS, or Subversion.) - <!-- - For information about using &SCons; - with these systems, see the section, - "Fetching Files From Source Code Management Systems," - below.) - --> - You use the &Repository; method - to tell &SCons; to search one or more - central code repositories (in order) - for any source files and derived files - that are not present in the local build tree: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - env = Environment() - env.Program('hello.c') - Repository('__ROOT__/usr/repository1', '__ROOT__/usr/repository2') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Multiple calls to the &Repository; method - will simply add repositories to the global list - that &SCons; maintains, - with the exception that &SCons; will automatically eliminate - the current directory and any non-existent - directories from the list. - - </para> - - </section> - - <section> - <title>Finding source files in repositories</title> - - <para> - - The above example - specifies that &SCons; - will first search for files under - the <filename>/usr/repository1</filename> tree - and next under the <filename>/usr/repository2</filename> tree. - &SCons; expects that any files it searches - for will be found in the same position - relative to the top-level directory. - In the above example, if the &hello_c; file is not - found in the local build tree, - &SCons; will search first for - a <filename>/usr/repository1/hello.c</filename> file - and then for a <filename>/usr/repository2/hello.c</filename> file - to use in its place. - - </para> - - <para> - - So given the &SConstruct; file above, - if the &hello_c; file exists in the local - build directory, - &SCons; will rebuild the &hello; program - as normal: - - </para> - - <scons_output example="ex1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - If, however, there is no local &hello_c; file, - but one exists in <filename>/usr/repository1</filename>, - &SCons; will recompile the &hello; program - from the source file it finds in the repository: - - </para> - - <scons_example name="ex2"> - <file name="SConstruct"> - env = Environment() - env.Program('hello.c') - Repository('__ROOT__/usr/repository1', '__ROOT__/usr/repository2') - </file> - <file name="__ROOT__/usr/repository1/hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <scons_output example="ex2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - And similarly, if there is no local &hello_c; file - and no <filename>/usr/repository1/hello.c</filename>, - but one exists in <filename>/usr/repository2</filename>: - - </para> - - <scons_example name="ex3"> - <file name="SConstruct"> - env = Environment() - env.Program('hello.c') - Repository('__ROOT__/usr/repository1', '__ROOT__/usr/repository2') - </file> - <file name="__ROOT__/usr/repository2/hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <scons_output example="ex3"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - </para> - - </section> - - <section> - <title>Finding <literal>#include</literal> files in repositories</title> - - <para> - - We've already seen that SCons will scan the contents of - a source file for <literal>#include</literal> file names - and realize that targets built from that source file - also depend on the <literal>#include</literal> file(s). - For each directory in the &cv-link-CPPPATH; list, - &SCons; will actually search the corresponding directories - in any repository trees and establish the - correct dependencies on any - <literal>#include</literal> files that it finds - in repository directory. - - </para> - - <para> - - Unless the C compiler also knows about these directories - in the repository trees, though, - it will be unable to find the <literal>#include</literal> files. - If, for example, the &hello_c; file in - our previous example includes the &hello_h; - in its current directory, - and the &hello_h; only exists in the repository: - - </para> - - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - hello.c:1: hello.h: No such file or directory - </screen> - - <para> - - In order to inform the C compiler about the repositories, - &SCons; will add appropriate - <literal>-I</literal> flags to the compilation commands - for each directory in the &cv-CPPPATH; list. - So if we add the current directory to the - construction environment &cv-CPPPATH; like so: - - </para> - - <scons_example name="CPPPATH"> - <file name="SConstruct" printme="1"> - env = Environment(CPPPATH = ['.']) - env.Program('hello.c') - Repository('__ROOT__/usr/repository1') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Then re-executing &SCons; yields: - - </para> - - <scons_output example="CPPPATH"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - The order of the <literal>-I</literal> options replicates, - for the C preprocessor, - the same repository-directory search path - that &SCons; uses for its own dependency analysis. - If there are multiple repositories and multiple &cv-CPPPATH; - directories, &SCons; will add the repository directories - to the beginning of each &cv-CPPPATH; directory, - rapidly multiplying the number of <literal>-I</literal> flags. - If, for example, the &cv-CPPPATH; contains three directories - (and shorter repository path names!): - - </para> - - <scons_example name="CPPPATH3"> - <file name="SConstruct" printme="1"> - env = Environment(CPPPATH = ['dir1', 'dir2', 'dir3']) - env.Program('hello.c') - Repository('__ROOT__/r1', '__ROOT__/r2') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Then we'll end up with nine <literal>-I</literal> options - on the command line, - three (for each of the &cv-CPPPATH; directories) - times three (for the local directory plus the two repositories): - - </para> - - <scons_output example="CPPPATH3"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - -<!-- - -Cons classic did the following, does SCons? - -In order to shorten the command lines as much as possible, Cons will -remove C<-I> flags for any directories, locally or in the repositories, -which do not actually exist. (Note that the C<-I> flags are not included -in the MD5 signature calculation for the target file, so the target will -not be recompiled if the compilation command changes due to a directory -coming into existence.) - ---> - - <section> - <title>Limitations on <literal>#include</literal> files in repositories</title> - - <para> - - &SCons; relies on the C compiler's - <literal>-I</literal> options to control the order in which - the preprocessor will search the repository directories - for <literal>#include</literal> files. - This causes a problem, however, with how the C preprocessor - handles <literal>#include</literal> lines with - the file name included in double-quotes. - - </para> - - <para> - - As we've seen, - &SCons; will compile the &hello_c; file from - the repository if it doesn't exist in - the local directory. - If, however, the &hello_c; file in the repository contains - a <literal>#include</literal> line with the file name in - double quotes: - - </para> - - <programlisting> - #include "hello.h" - int - main(int argc, char *argv[]) - { - printf(HELLO_MESSAGE); - return (0); - } - </programlisting> - - <para> - - Then the C preprocessor will <emphasis>always</emphasis> - use a &hello_h; file from the repository directory first, - even if there is a &hello_h; file in the local directory, - despite the fact that the command line specifies - <literal>-I</literal> as the first option: - - </para> - - <scons_example name="quote1"> - <file name="SConstruct"> - env = Environment(CPPPATH = ['.']) - env.Program('hello.c') - Repository('__ROOT__/usr/repository1') - </file> - <file name="__ROOT__/usr/repository1/hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <scons_output example="quote1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - This behavior of the C preprocessor--always search - for a <literal>#include</literal> file in double-quotes - first in the same directory as the source file, - and only then search the <literal>-I</literal>--can - not, in general, be changed. - In other words, it's a limitation - that must be lived with if you want to use - code repositories in this way. - There are three ways you can possibly - work around this C preprocessor behavior: - - </para> - - <orderedlist> - - <listitem> - <para> - - Some modern versions of C compilers do have an option - to disable or control this behavior. - If so, add that option to &cv-link-CFLAGS; - (or &cv-link-CXXFLAGS; or both) in your construction environment(s). - Make sure the option is used for all construction - environments that use C preprocessing! - - </para> - </listitem> - - <listitem> - <para> - - Change all occurrences of <literal>#include "file.h"</literal> - to <literal>#include &lt;file.h&gt;</literal>. - Use of <literal>#include</literal> with angle brackets - does not have the same behavior--the <literal>-I</literal> - directories are searched first - for <literal>#include</literal> files--which - gives &SCons; direct control over the list of - directories the C preprocessor will search. - - </para> - </listitem> - - <listitem> - <para> - - Require that everyone working with compilation from - repositories check out and work on entire directories of files, - not individual files. - (If you use local wrapper scripts around - your source code control system's command, - you could add logic to enforce this restriction there. - - </para> - </listitem> - - </orderedlist> - - </section> - - </section> - - <section> - <title>Finding the &SConstruct; file in repositories</title> - - <para> - - &SCons; will also search in repositories - for the &SConstruct; file and any specified &SConscript; files. - This poses a problem, though: how can &SCons; search a - repository tree for an &SConstruct; file - if the &SConstruct; file itself contains the information - about the pathname of the repository? - To solve this problem, &SCons; allows you - to specify repository directories - on the command line using the <literal>-Y</literal> option: - - </para> - - <screen> - % <userinput>scons -Q -Y /usr/repository1 -Y /usr/repository2</userinput> - </screen> - - <para> - - When looking for source or derived files, - &SCons; will first search the repositories - specified on the command line, - and then search the repositories - specified in the &SConstruct; or &SConscript; files. - - </para> - - </section> - - <section> - <title>Finding derived files in repositories</title> - - <para> - - If a repository contains not only source files, - but also derived files (such as object files, - libraries, or executables), &SCons; will perform - its normal MD5 signature calculation to - decide if a derived file in a repository is up-to-date, - or the derived file must be rebuilt in the local build directory. - For the &SCons; signature calculation to work correctly, - a repository tree must contain the &sconsign; files - that &SCons; uses to keep track of signature information. - - </para> - - <para> - - Usually, this would be done by a build integrator - who would run &SCons; in the repository - to create all of its derived files and &sconsign; files, - or who would run &SCons; in a separate build directory - and copy the resulting tree to the desired repository: - - </para> - - <scons_example name="ex4"> - <file name="SConstruct"> - env = Environment() - env.Program(['hello.c', 'file1.c', 'file2.c']) - Repository('/usr/repository1', '/usr/repository2') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - <file name="file1.c"> - int f1() { printf("file1\n"); } - </file> - <file name="file2.c"> - int f2() { printf("file2.c\n"); } - </file> - </scons_example> - - <scons_output example="ex4"> - <scons_output_command>cd /usr/repository1</scons_output_command> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - (Note that this is safe even if the &SConstruct; file - lists <filename>/usr/repository1</filename> as a repository, - because &SCons; will remove the current build directory - from its repository list for that invocation.) - - </para> - - <para> - - Now, with the repository populated, - we only need to create the one local source file - we're interested in working with at the moment, - and use the <literal>-Y</literal> option to - tell &SCons; to fetch any other files it needs - from the repository: - - </para> - - <!-- - <scons_output example="ex4"> - <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> - % <userinput>cd $HOME/build</userinput> - % <userinput>edit hello.c</userinput> - % <userinput>scons -Q -Y /usr/repository1</userinput> - cc -c -o hello.o hello.c - cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o - </screen> - - <para> - - Notice that &SCons; realizes that it does not need to - rebuild local copies <filename>file1.o</filename> and <filename>file2.o</filename> files, - but instead uses the already-compiled files - from the repository. - - </para> - - </section> - - <section> - <title>Guaranteeing local copies of files</title> - - <para> - - If the repository tree contains the complete results of a build, - and we try to build from the repository - without any files in our local tree, - something moderately surprising happens: - - </para> - - <screen> - % <userinput>mkdir $HOME/build2</userinput> - % <userinput>cd $HOME/build2</userinput> - % <userinput>scons -Q -Y /usr/all/repository hello</userinput> - scons: `hello' is up-to-date. - </screen> - - <para> - - Why does &SCons; say that the &hello; program - is up-to-date when there is no &hello; program - in the local build directory? - Because the repository (not the local directory) - contains the up-to-date &hello; program, - and &SCons; correctly determines that nothing - needs to be done to rebuild that - up-to-date copy of the file. - - </para> - - <para> - - There are, however, many times when you want to ensure that a - local copy of a file always exists. - A packaging or testing script, for example, - may assume that certain generated files exist locally. - To tell &SCons; to make a copy of any up-to-date repository - file in the local build directory, - use the &Local; function: - - </para> - - <scons_example name="ex5"> - <file name="SConstruct" printme="1"> - env = Environment() - hello = env.Program('hello.c') - Local(hello) - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - If we then run the same command, - &SCons; will make a local copy of the program - from the repository copy, - and tell you that it is doing so: - - </para> - - <screen> - % <userinput>scons -Y /usr/all/repository hello</userinput> - Local copy of hello from /usr/all/repository/hello - scons: `hello' is up-to-date. - </screen> - - <para> - - (Notice that, because the act of making the local copy - is not considered a "build" of the &hello; file, - &SCons; still reports that it is up-to-date.) - - </para> - - </section> diff --git a/doc/user/repositories.xml b/doc/user/repositories.xml index 0d90d2e..c0ca5ee 100644 --- a/doc/user/repositories.xml +++ b/doc/user/repositories.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-repositories" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Building From Code Repositories</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -73,11 +94,16 @@ </para> - <programlisting> - env = Environment() - env.Program('hello.c') - Repository('/usr/repository1', '/usr/repository2') - </programlisting> + <scons_example name="repositories_ex1"> + <file name="SConstruct" printme="1"> +env = Environment() +env.Program('hello.c') +Repository('__ROOT__/usr/repository1', '__ROOT__/usr/repository2') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -124,11 +150,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="repositories_ex1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -139,13 +163,20 @@ </para> - - - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c /usr/repository1/hello.c - cc -o hello hello.o - </screen> + <scons_example name="repositories_ex2"> + <file name="SConstruct"> +env = Environment() +env.Program('hello.c') +Repository('__ROOT__/usr/repository1', '__ROOT__/usr/repository2') + </file> + <file name="__ROOT__/usr/repository1/hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> + + <scons_output example="repositories_ex2" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -155,13 +186,20 @@ </para> - - - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c /usr/repository2/hello.c - cc -o hello hello.o - </screen> + <scons_example name="repositories_ex3"> + <file name="SConstruct"> +env = Environment() +env.Program('hello.c') +Repository('__ROOT__/usr/repository1', '__ROOT__/usr/repository2') + </file> + <file name="__ROOT__/usr/repository2/hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> + + <scons_output example="repositories_ex3" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -200,9 +238,9 @@ </para> <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c hello.c - hello.c:1: hello.h: No such file or directory +% <userinput>scons -Q</userinput> +cc -o hello.o -c hello.c +hello.c:1: hello.h: No such file or directory </screen> <para> @@ -216,11 +254,16 @@ </para> - <programlisting> - env = Environment(CPPPATH = ['.']) - env.Program('hello.c') - Repository('/usr/repository1') - </programlisting> + <scons_example name="repositories_CPPPATH"> + <file name="SConstruct" printme="1"> +env = Environment(CPPPATH = ['.']) +env.Program('hello.c') +Repository('__ROOT__/usr/repository1') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -228,11 +271,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c -I. -I/usr/repository1 hello.c - cc -o hello hello.o - </screen> + <scons_output example="repositories_CPPPATH" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -249,11 +290,16 @@ </para> - <programlisting> - env = Environment(CPPPATH = ['dir1', 'dir2', 'dir3']) - env.Program('hello.c') - Repository('/r1', '/r2') - </programlisting> + <scons_example name="repositories_CPPPATH3"> + <file name="SConstruct" printme="1"> +env = Environment(CPPPATH = ['dir1', 'dir2', 'dir3']) +env.Program('hello.c') +Repository('__ROOT__/r1', '__ROOT__/r2') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -264,11 +310,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c -Idir1 -I/r1/dir1 -I/r2/dir1 -Idir2 -I/r1/dir2 -I/r2/dir2 -Idir3 -I/r1/dir3 -I/r2/dir3 hello.c - cc -o hello hello.o - </screen> + <scons_output example="repositories_CPPPATH3" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <!-- @@ -311,13 +355,13 @@ coming into existence.) </para> <programlisting> - #include "hello.h" - int - main(int argc, char *argv[]) - { - printf(HELLO_MESSAGE); - return (0); - } +#include "hello.h" +int +main(int argc, char *argv[]) +{ + printf(HELLO_MESSAGE); + return (0); +} </programlisting> <para> @@ -330,13 +374,20 @@ coming into existence.) </para> - - - <screen> - % <userinput>scons -Q</userinput> - cc -o hello.o -c -I. -I/usr/repository1 /usr/repository1/hello.c - cc -o hello hello.o - </screen> + <scons_example name="repositories_quote1"> + <file name="SConstruct"> +env = Environment(CPPPATH = ['.']) +env.Program('hello.c') +Repository('__ROOT__/usr/repository1') + </file> + <file name="__ROOT__/usr/repository1/hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> + + <scons_output example="repositories_quote1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -372,7 +423,7 @@ coming into existence.) <para> Change all occurrences of <literal>#include "file.h"</literal> - to <literal>#include <file.h></literal>. + to <literal>#include &lt;file.h&gt;</literal>. Use of <literal>#include</literal> with angle brackets does not have the same behavior--the <literal>-I</literal> directories are searched first @@ -420,7 +471,7 @@ coming into existence.) </para> <screen> - % <userinput>scons -Q -Y /usr/repository1 -Y /usr/repository2</userinput> +% <userinput>scons -Q -Y /usr/repository1 -Y /usr/repository2</userinput> </screen> <para> @@ -462,16 +513,27 @@ coming into existence.) </para> - - - <screen> - % <userinput>cd /usr/repository1</userinput> - % <userinput>scons -Q</userinput> - cc -o file1.o -c file1.c - cc -o file2.o -c file2.c - cc -o hello.o -c hello.c - cc -o hello hello.o file1.o file2.o - </screen> + <scons_example name="repositories_ex4"> + <file name="SConstruct"> +env = Environment() +env.Program(['hello.c', 'file1.c', 'file2.c']) +Repository('/usr/repository1', '/usr/repository2') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + <file name="file1.c"> +int f1() { printf("file1\n"); } + </file> + <file name="file2.c"> +int f2() { printf("file2.c\n"); } + </file> + </scons_example> + + <scons_output example="repositories_ex4" suffix="1"> + <scons_output_command>cd /usr/repository1</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -494,18 +556,18 @@ coming into existence.) </para> <!-- - <scons_output example="ex4"> + <scons_output example="repositories_ex4" suffix="2"> <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> - % <userinput>cd $HOME/build</userinput> - % <userinput>edit hello.c</userinput> - % <userinput>scons -Q -Y /usr/repository1</userinput> - cc -c -o hello.o hello.c - cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o +% <userinput>cd $HOME/build</userinput> +% <userinput>edit hello.c</userinput> +% <userinput>scons -Q -Y /usr/repository1</userinput> +cc -c -o hello.o hello.c +cc -o hello hello.o /usr/repository1/file1.o /usr/repository1/file2.o </screen> <para> @@ -532,10 +594,10 @@ coming into existence.) </para> <screen> - % <userinput>mkdir $HOME/build2</userinput> - % <userinput>cd $HOME/build2</userinput> - % <userinput>scons -Q -Y /usr/all/repository hello</userinput> - scons: `hello' is up-to-date. +% <userinput>mkdir $HOME/build2</userinput> +% <userinput>cd $HOME/build2</userinput> +% <userinput>scons -Q -Y /usr/all/repository hello</userinput> +scons: `hello' is up-to-date. </screen> <para> @@ -563,11 +625,16 @@ coming into existence.) </para> - <programlisting> - env = Environment() - hello = env.Program('hello.c') - Local(hello) - </programlisting> + <scons_example name="repositories_ex5"> + <file name="SConstruct" printme="1"> +env = Environment() +hello = env.Program('hello.c') +Local(hello) + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -579,9 +646,9 @@ coming into existence.) </para> <screen> - % <userinput>scons -Y /usr/all/repository hello</userinput> - Local copy of hello from /usr/all/repository/hello - scons: `hello' is up-to-date. +% <userinput>scons -Y /usr/all/repository hello</userinput> +Local copy of hello from /usr/all/repository/hello +scons: `hello' is up-to-date. </screen> <para> @@ -593,3 +660,5 @@ coming into existence.) </para> </section> + +</chapter> diff --git a/doc/user/run.in b/doc/user/run.in deleted file mode 100644 index 8a5075b..0000000 --- a/doc/user/run.in +++ /dev/null @@ -1,375 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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. - ---> - -<!-- - -=head1 Invoking Cons - -The C<cons> command is usually invoked from the root of the build tree. A -F<Construct> file must exist in that directory. If the C<-f> argument is -used, then an alternate F<Construct> file may be used (and, possibly, an -alternate root, since C<cons> will cd to F<Construct> file's containing -directory). - -If C<cons> is invoked from a child of the root of the build tree with -the C<-t> argument, it will walk up the directory hierarchy looking for a -F<Construct> file. (An alternate name may still be specified with C<-f>.) -The targets supplied on the command line will be modified to be relative -to the discovered F<Construct> file. For example, from a directory -containing a top-level F<Construct> file, the following invocation: - - % cd libfoo/subdir - % cons -t target - -is exactly equivalent to: - - % cons libfoo/subdir/target - -If there are any C<Default> targets specified in the directory hierarchy's -F<Construct> or F<Conscript> files, only the default targets at or below -the directory from which C<cons -t> was invoked will be built. - -The command is invoked as follows: - - cons <arguments> , <construct-args> - -where I<arguments> can be any of the following, in any order: - -=over 10 - -=item I<target> - -Build the specified target. If I<target> is a directory, then recursively -build everything within that directory. - -=item I<+pattern> - -Limit the F<Conscript> files considered to just those that match I<pattern>, -which is a Perl regular expression. Multiple C<+> arguments are accepted. - -=item I<name>=<val> - -Sets I<name> to value I<val> in the C<ARG> hash passed to the top-level -F<Construct> file. - -=item C<-cc> - -Show command that would have been executed, when retrieving from cache. No -indication that the file has been retrieved is given; this is useful for -generating build logs that can be compared with real build logs. - -=item C<-cd> - -Disable all caching. Do not retrieve from cache nor flush to cache. - -=item C<-cr> - -Build dependencies in random order. This is useful when building multiple -similar trees with caching enabled. - -=item C<-cs> - -Synchronize existing build targets that are found to be up-to-date with -cache. This is useful if caching has been disabled with -cc or just recently -enabled with UseCache. - -=item C<-d> - -Enable dependency debugging. - -=item C<-f> <file> - -Use the specified file instead of F<Construct> (but first change to -containing directory of I<file>). - -=item C<-h> - -Show a help message local to the current build if one such is defined, and -exit. - -=item C<-k> - -Keep going as far as possible after errors. - -=item C<-o> <file> - -Read override file I<file>. - -=item C<-p> - -Show construction products in specified trees. No build is attempted. - -=item C<-pa> - -Show construction products and associated actions. No build is attempted. - -=item C<-pw> - -Show products and where they are defined. No build is attempted. - -=item C<-q> - -Make the build quiet. Multiple C<-q> options may be specified. - -A single C<-q> options suppress messages about Installing and Removing -targets. - -Two C<-q> options suppress build command lines and target up-to-date -messages. - -=item C<-r> - -Remove construction products associated with <targets>. No build is -attempted. - -=item C<-R> <repos> - -Search for files in I<repos>. Multiple B<-R> I<repos> directories are -searched in the order specified. - -=item C<-S> <pkg> - -Use the sig::<pkg> package to calculate. Supported <pkg> values -include "md5" for MD5 signature calculation and "md5::debug" for debug -information about MD5 signature calculation. - -If the specified package ends in <::debug>, signature debug information -will be printed to the file name specified in the C<CONS_SIG_DEBUG> -environment variable, or to standard output if the environment variable -is not set. - -=item C<-t> - -Traverse up the directory hierarchy looking for a F<Construct> file, -if none exists in the current directory. Targets will be modified to -be relative to the F<Construct> file. - -Internally, C<cons> will change its working directory to the directory -which contains the top-level F<Construct> file and report: - - cons: Entering directory `top-level-directory' - -This message indicates to an invoking editor (such as emacs) or build -environment that Cons will now report all file names relative to the -top-level directory. This message can not be suppressed with the C<-q> -option. - -=item C<-v> - -Show C<cons> version and continue processing. - -=item C<-V> - -Show C<cons> version and exit. - -=item C<-wf> <file> - -Write all filenames considered into I<file>. - -=item C<-x> - -Show a help message similar to this one, and exit. - -=back - -And I<construct-args> can be any arguments that you wish to process in the -F<Construct> file. Note that there should be a B<-,-> separating the arguments -to cons and the arguments that you wish to process in the F<Construct> file. - -Processing of I<construct-args> can be done by any standard package like -B<Getopt> or its variants, or any user defined package. B<cons> will pass in -the I<construct-args> as B<@ARGV> and will not attempt to interpret anything -after the B<-,->. - - % cons -R /usr/local/repository -d os=solaris +driver -,- -c test -f DEBUG - -would pass the following to cons - - -R /usr/local/repository -d os=solaris +driver - -and the following, to the top level F<Construct> file as B<@ARGV> - - -c test -f DEBUG - -Note that C<cons -r .> is equivalent to a full recursive C<make clean>, -but requires no support in the F<Construct> file or any F<Conscript> -files. This is most useful if you are compiling files into source -directories (if you separate the F<build> and F<export> directories, -then you can just remove the directories). - -The options C<-p>, C<-pa>, and C<-pw> are extremely useful for use as an aid -in reading scripts or debugging them. If you want to know what script -installs F<export/include/foo.h>, for example, just type: - - % cons -pw export/include/foo.h - -=head1 Selective builds - -Cons provides two methods for reducing the size of given build. The first is -by specifying targets on the command line, and the second is a method for -pruning the build tree. We'll consider target specification first. - - -=head2 Selective targeting - -Like make, Cons allows the specification of ``targets'' on the command -line. Cons targets may be either files or directories. When a directory is -specified, this is simply a short-hand notation for every derivable -product-,-that Cons knows about-,-in the specified directory and below. For -example: - - % cons build/hello/hello.o - -means build F<hello.o> and everything that F<hello.o> might need. This is -from a previous version of the B<Hello, World!> program in which F<hello.o> -depended upon F<export/include/world.h>. If that file is not up-to-date -(because someone modified F<src/world/world.h)>, then it will be rebuilt, -even though it is in a directory remote from F<build/hello>. - -In this example: - - % cons build - -Everything in the F<build> directory is built, if necessary. Again, this may -cause more files to be built. In particular, both F<export/include/world.h> -and F<export/lib/libworld.a> are required by the F<build/hello> directory, -and so they will be built if they are out-of-date. - -If we do, instead: - - % cons export - -then only the files that should be installed in the export directory will be -rebuilt, if necessary, and then installed there. Note that C<cons build> -might build files that C<cons export> doesn't build, and vice-versa. - - -=head1 Build Pruning - -In conjunction with target selection, B<build pruning> can be used to reduce -the scope of the build. In the previous peAcH and baNaNa example, we have -already seen how script-driven build pruning can be used to make only half -of the potential build available for any given invocation of C<cons>. Cons -also provides, as a convenience, a command line convention that allows you -to specify which F<Conscript> files actually get ``built''-,-that is, -incorporated into the build tree. For example: - - % cons build +world - -The C<+> argument introduces a Perl regular expression. This must, of -course, be quoted at the shell level if there are any shell meta-characters -within the expression. The expression is matched against each F<Conscript> -file which has been mentioned in a C<Build> statement, and only those -scripts with matching names are actually incorporated into the build -tree. Multiple such arguments are allowed, in which case a match against any -of them is sufficient to cause a script to be included. - -In the example, above, the F<hello> program will not be built, since Cons -will have no knowledge of the script F<hello/Conscript>. The F<libworld.a> -archive will be built, however, if need be. - -There are a couple of uses for build pruning via the command line. Perhaps -the most useful is the ability to make local changes, and then, with -sufficient knowledge of the consequences of those changes, restrict the size -of the build tree in order to speed up the rebuild time. A second use for -build pruning is to actively prevent the recompilation of certain files that -you know will recompile due to, for example, a modified header file. You may -know that either the changes to the header file are immaterial, or that the -changes may be safely ignored for most of the tree, for testing -purposes.With Cons, the view is that it is pragmatic to admit this type of -behavior, with the understanding that on the next full build everything that -needs to be rebuilt will be. There is no equivalent to a ``make touch'' -command, to mark files as permanently up-to-date. So any risk that is -incurred by build pruning is mitigated. For release quality work, obviously, -we recommend that you do not use build pruning (it's perfectly OK to use -during integration, however, for checking compilation, etc. Just be sure to -do an unconstrained build before committing the integration). - ---> - - <para> - - XXX - - </para> - - <section> - <title>Command-Line Options</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>Getting at Command-Line Arguments</title> - - <para> - - XXX - - </para> - - </section> - - <section> - <title>Selective Builds</title> - - <para> - - XXX - - </para> - - </section> - - <!-- - - <section> - <title>Build Pruning</title> - - <para> - - XXX - - </para> - - </section> - - --> - - <section> - <title>Overriding Construction Variables</title> - - <para> - - XXX - - </para> - - </section> diff --git a/doc/user/run.xml b/doc/user/run.xml index 8a5075b..464a5a8 100644 --- a/doc/user/run.xml +++ b/doc/user/run.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-run" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>How to Run &SCons;</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -373,3 +394,5 @@ do an unconstrained build before committing the integration). </para> </section> + +</chapter> diff --git a/doc/user/scanners.in b/doc/user/scanners.in deleted file mode 100644 index 9237fb3..0000000 --- a/doc/user/scanners.in +++ /dev/null @@ -1,392 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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. - ---> - -<!-- - -=head1 Using and writing dependency scanners - -QuickScan allows simple target-independent scanners to be set up for -source files. Only one QuickScan scanner may be associated with any given -source file and environment, although the same scanner may (and should) -be used for multiple files of a given type. - -A QuickScan scanner is only ever invoked once for a given source file, -and it is only invoked if the file is used by some target in the tree -(i.e., there is a dependency on the source file). - -QuickScan is invoked as follows: - - QuickScan CONSENV CODEREF, FILENAME [, PATH] - -The subroutine referenced by CODEREF is expected to return a list of -filenames included directly by FILE. These filenames will, in turn, be -scanned. The optional PATH argument supplies a lookup path for finding -FILENAME and/or files returned by the user-supplied subroutine. The PATH -may be a reference to an array of lookup-directory names, or a string of -names separated by the system's separator character (':' on UNIX systems, -';' on Windows NT). - -The subroutine is called once for each line in the file, with $_ set to the -current line. If the subroutine needs to look at additional lines, or, for -that matter, the entire file, then it may read them itself, from the -filehandle SCAN. It may also terminate the loop, if it knows that no further -include information is available, by closing the filehandle. - -Whether or not a lookup path is provided, QuickScan first tries to lookup -the file relative to the current directory (for the top-level file -supplied directly to QuickScan), or from the directory containing the -file which referenced the file. This is not very general, but seems good -enough, especially if you have the luxury of writing your own utilities -and can control the use of the search path in a standard way. - -Here's a real example, taken from a F<Construct> file here: - - sub cons::SMFgen { - my($env, @tables) = @_; - foreach $t (@tables) { - $env->QuickScan(sub { /\b\S*?\.smf\b/g }, "$t.smf", - $env->{SMF_INCLUDE_PATH}); - $env->Command(["$t.smdb.cc","$t.smdb.h","$t.snmp.cc", - "$t.ami.cc", "$t.http.cc"], "$t.smf", - q(smfgen %( %SMF_INCLUDE_OPT %) %<)); - } - } - -The subroutine above finds all names of the form <name>.smf in the -file. It will return the names even if they're found within comments, -but that's OK (the mechanism is forgiving of extra files; they're just -ignored on the assumption that the missing file will be noticed when -the program, in this example, smfgen, is actually invoked). - -[NOTE that the form C<$env-E<gt>QuickScan ...> and C<$env-E<gt>Command -...> should not be necessary, but, for some reason, is required -for this particular invocation. This appears to be a bug in Perl or -a misunderstanding on my part; this invocation style does not always -appear to be necessary.] - -Here is another way to build the same scanner. This one uses an -explicit code reference, and also (unnecessarily, in this case) reads -the whole file itself: - - sub myscan { - my(@includes); - do { - push(@includes, /\b\S*?\.smf\b/g); - } while <SCAN>; - @includes - } - -Note that the order of the loop is reversed, with the loop test at the -end. This is because the first line is already read for you. This scanner -can be attached to a source file by: - - QuickScan $env \&myscan, "$_.smf"; - -This final example, which scans a different type of input file, takes -over the file scanning rather than being called for each input line: - - $env->QuickScan( - sub { my(@includes) = (); - do { - push(@includes, $3) - if /^(#include|import)\s+(\")(.+)(\")/ && $3 - } while <SCAN>; - @includes - }, - "$idlFileName", - "$env->{CPPPATH};$BUILD/ActiveContext/ACSCLientInterfaces" - ); - ---> - - <para> - - &SCons; has built-in scanners that know how to look in - C, Fortran and IDL source files for information about - other files that targets built from those files depend on--for example, - in the case of files that use the C preprocessor, - the <filename>.h</filename> files that are specified - using <literal>#include</literal> lines in the source. - You can use the same mechanisms that &SCons; uses to create - its built-in scanners to write scanners of your own for file types - that &SCons; does not know how to scan "out of the box." - - </para> - - <section> - <title>A Simple Scanner Example</title> - - <para> - - Suppose, for example, that we want to create a simple scanner - for <filename>.foo</filename> files. - A <filename>.foo</filename> file contains some text that - will be processed, - and can include other files on lines that begin - with <literal>include</literal> - followed by a file name: - - </para> - - <programlisting> - include filename.foo - </programlisting> - - <para> - - Scanning a file will be handled by a Python function - that you must supply. - Here is a function that will use the Python - <filename>re</filename> module - to scan for the <literal>include</literal> lines in our example: - - </para> - - <programlisting> - import re - - include_re = re.compile(r'^include\s+(\S+)$', re.M) - - def kfile_scan(node, env, path, arg): - contents = node.get_text_contents() - return env.File(include_re.findall(contents)) - </programlisting> - - <para> - - It is important to note that you - have to return a list of File nodes from the scanner function, simple - strings for the file names won't do. As in the examples we are showing here, - you can use the &File; - function of your current Environment in order to create nodes on the fly from - a sequence of file names with relative paths. - - </para> - - <para> - - The scanner function must - accept the four specified arguments - and return a list of implicit dependencies. - Presumably, these would be dependencies found - from examining the contents of the file, - although the function can perform any - manipulation at all to generate the list of - dependencies. - - </para> - - <variablelist> - - <varlistentry> - <term>node</term> - - <listitem> - <para> - - An &SCons; node object representing the file being scanned. - The path name to the file can be - used by converting the node to a string - using the <literal>str()</literal> function, - or an internal &SCons; <literal>get_text_contents()</literal> - object method can be used to fetch the contents. - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>env</term> - - <listitem> - <para> - - The construction environment in effect for this scan. - The scanner function may choose to use construction - variables from this environment to affect its behavior. - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>path</term> - - <listitem> - <para> - - A list of directories that form the search path for included files - for this scanner. - This is how &SCons; handles the &cv-link-CPPPATH; and &cv-link-LIBPATH; - variables. - - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>arg</term> - - <listitem> - <para> - - An optional argument that you can choose to - have passed to this scanner function by - various scanner instances. - - </para> - </listitem> - </varlistentry> - - </variablelist> - - <para> - - A Scanner object is created using the &Scanner; function, - 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 - &cv-link-SCANNERS; construction variable of a construction environment, - typically by using the &Append; method: - - </para> - - <programlisting> - kscan = Scanner(function = kfile_scan, - skeys = ['.k']) - env.Append(SCANNERS = kscan) - </programlisting> - - <para> - - When we put it all together, it looks like: - - </para> - - <scons_example name="scan"> - <file name="SConstruct" printme="1"> - import re - - include_re = re.compile(r'^include\s+(\S+)$', re.M) - - def kfile_scan(node, env, path): - contents = node.get_text_contents() - includes = include_re.findall(contents) - return env.File(includes) - - kscan = Scanner(function = kfile_scan, - skeys = ['.k']) - - env = Environment(ENV = {'PATH' : '__ROOT__/usr/local/bin'}) - env.Append(SCANNERS = kscan) - - env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') - </file> - <file name="foo.k"> - include other_file - </file> - <file name="other_file"> - other_file - </file> - <directory name="__ROOT__/usr"></directory> - <directory name="__ROOT__/usr/local"></directory> - <directory name="__ROOT__/usr/local/bin"></directory> - <file name="__ROOT_/usr/local/bin/kprocess" chmod="755"> - cat - </file> - </scons_example> - - <!-- - - <para> - - Now if we run &scons; - and then re-run it after changing the contents of - <filename>other_file</filename>, - the <filename>foo</filename> - target file will be automatically rebuilt: - - </para> - - <scons_output example="scan"> - <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> - - --> - - </section> - - <section> - <title>Adding a search path to a scanner: &FindPathDirs;</title> - - <para> - - Many scanners need to search for included files or dependencies - using a path variable; this is how &cv-link-CPPPATH; and - &cv-link-LIBPATH; work. The path to search is passed to your - scanner as the <literal>path</literal> argument. Path variables - may be lists of nodes, semicolon-separated strings, or even - contain SCons variables which need to be expanded. Fortunately, - &SCons; provides the &FindPathDirs; function which itself returns - a function to expand a given path (given as a SCons construction - variable name) to a list of paths at the time the scanner is - called. Deferring evaluation until that point allows, for - instance, the path to contain $TARGET references which differ for - each file scanned. - - </para> - - <para> - - Using &FindPathDirs; is quite easy. Continuing the above example, - using KPATH as the construction variable with the search path - (analogous to &cv-link-CPPPATH;), we just modify the &Scanner; - constructor call to include a path keyword arg: - - </para> - - <scons_example name="findpathdirs"> - <file name="SConstruct" printme="1"> - kscan = Scanner(function = kfile_scan, - skeys = ['.k'], - path=FindPathDirs('KPATH')) - </file> - </scons_example> - - <para> - - FindPathDirs returns a callable object that, when called, will - essentially expand the elements in env['KPATH'] and tell the - scanner to search in those dirs. It will also properly add - related repository and variant dirs to the search list. As a side - note, the returned method stores the path in an efficient way so - lookups are fast even when variable substitutions may be needed. - This is important since many files get scanned in a typical build. - - </para> - </section> diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml index 749db36..32faf29 100644 --- a/doc/user/scanners.xml +++ b/doc/user/scanners.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-scanners" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Writing Scanners</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -151,7 +172,7 @@ over the file scanning rather than being called for each input line: </para> <programlisting> - include filename.foo +include filename.foo </programlisting> <para> @@ -165,13 +186,13 @@ over the file scanning rather than being called for each input line: </para> <programlisting> - import re - - include_re = re.compile(r'^include\s+(\S+)$', re.M) - - def kfile_scan(node, env, path, arg): - contents = node.get_text_contents() - return env.File(include_re.findall(contents)) +import re + +include_re = re.compile(r'^include\s+(\S+)$', re.M) + +def kfile_scan(node, env, path, arg): + contents = node.get_text_contents() + return env.File(include_re.findall(contents)) </programlisting> <para> @@ -274,9 +295,9 @@ over the file scanning rather than being called for each input line: </para> <programlisting> - kscan = Scanner(function = kfile_scan, - skeys = ['.k']) - env.Append(SCANNERS = kscan) +kscan = Scanner(function = kfile_scan, + skeys = ['.k']) +env.Append(SCANNERS = kscan) </programlisting> <para> @@ -285,24 +306,38 @@ over the file scanning rather than being called for each input line: </para> - <programlisting> - import re - - include_re = re.compile(r'^include\s+(\S+)$', re.M) - - def kfile_scan(node, env, path): - contents = node.get_text_contents() - includes = include_re.findall(contents) - return env.File(includes) - - kscan = Scanner(function = kfile_scan, - skeys = ['.k']) - - env = Environment(ENV = {'PATH' : '/usr/local/bin'}) - env.Append(SCANNERS = kscan) - - env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') - </programlisting> + <scons_example name="scanners_scan"> + <file name="SConstruct" printme="1"> + import re + + include_re = re.compile(r'^include\s+(\S+)$', re.M) + + def kfile_scan(node, env, path): + contents = node.get_text_contents() + includes = include_re.findall(contents) + return env.File(includes) + + kscan = Scanner(function = kfile_scan, + skeys = ['.k']) + + env = Environment(ENV = {'PATH' : '__ROOT__/usr/local/bin'}) + env.Append(SCANNERS = kscan) + + env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET') + </file> + <file name="foo.k"> +include other_file + </file> + <file name="other_file"> +other_file + </file> + <directory name="__ROOT__/usr"></directory> + <directory name="__ROOT__/usr/local"></directory> + <directory name="__ROOT__/usr/local/bin"></directory> + <file name="__ROOT_/usr/local/bin/kprocess" chmod="755"> +cat + </file> + </scons_example> <!-- @@ -316,7 +351,7 @@ over the file scanning rather than being called for each input line: </para> - <scons_output example="scan"> + <scons_output example="scanners_scan" suffix="1"> <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> @@ -356,11 +391,13 @@ over the file scanning rather than being called for each input line: </para> - <programlisting> - kscan = Scanner(function = kfile_scan, - skeys = ['.k'], - path=FindPathDirs('KPATH')) - </programlisting> + <scons_example name="scanners_findpathdirs"> + <file name="SConstruct" printme="1"> +kscan = Scanner(function = kfile_scan, + skeys = ['.k'], + path=FindPathDirs('KPATH')) + </file> + </scons_example> <para> @@ -374,3 +411,5 @@ over the file scanning rather than being called for each input line: </para> </section> + +</chapter> diff --git a/doc/user/sconf.in b/doc/user/sconf.in deleted file mode 100644 index 31b7fcc..0000000 --- a/doc/user/sconf.in +++ /dev/null @@ -1,486 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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; has integrated support for multi-platform build configuration - similar to that offered by GNU &Autoconf;, - such as - figuring out what libraries or header files - are available on the local system. - This section describes how to use - this &SCons; feature. - - </para> - - <note> - <para> - This chapter is still under development, - so not everything is explained as well as it should be. - See the &SCons; man page for additional information. - </para> - </note> - - <section> - <title>&Configure_Contexts;</title> - - <para> - - The basic framework for multi-platform build configuration - in &SCons; is to attach a &configure_context; to a - construction environment by calling the &Configure; function, - perform a number of checks for - libraries, functions, header files, etc., - and to then call the configure context's &Finish; method - to finish off the configuration: - - </para> - - <sconstruct> - env = Environment() - conf = Configure(env) - # Checks for libraries, header files, etc. go here! - env = conf.Finish() - </sconstruct> - - <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. - - </para> - - </section> - - <section> - <title>Checking for the Existence of Header Files</title> - - <para> - - Testing the existence of a header file - requires knowing what language the header file is. - A configure context has a &CheckCHeader; method - that checks for the existence of a C header file: - - </para> - - <sconstruct> - env = Environment() - conf = Configure(env) - if not conf.CheckCHeader('math.h'): - print 'Math.h must be installed!' - Exit(1) - if conf.CheckCHeader('foo.h'): - conf.env.Append('-DHAS_FOO_H') - env = conf.Finish() - </sconstruct> - - <para> - - Note that you can choose to terminate - the build if a given header file doesn't exist, - or you can modify the construction environment - based on the existence of a header file. - - </para> - - <para> - - If you need to check for the existence - a C++ header file, - use the &CheckCXXHeader; method: - - </para> - - <sconstruct> - env = Environment() - conf = Configure(env) - if not conf.CheckCXXHeader('vector.h'): - print 'vector.h must be installed!' - Exit(1) - env = conf.Finish() - </sconstruct> - - </section> - - <section> - <title>Checking for the Availability of a Function</title> - - <para> - - Check for the availability of a specific function - using the &CheckFunc; method: - - </para> - - <sconstruct> - env = Environment() - conf = Configure(env) - if not conf.CheckFunc('strcpy'): - print 'Did not find strcpy(), using local version' - conf.env.Append(CPPDEFINES = '-Dstrcpy=my_local_strcpy') - env = conf.Finish() - </sconstruct> - - </section> - - <section> - <title>Checking for the Availability of a Library</title> - - <para> - - Check for the availability of a library - using the &CheckLib; method. - You only specify the basename of the library, - you don't need to add a <literal>lib</literal> - prefix or a <literal>.a</literal> or <literal>.lib</literal> suffix: - - </para> - - <sconstruct> - env = Environment() - conf = Configure(env) - if not conf.CheckLib('m'): - print 'Did not find libm.a or m.lib, exiting!' - Exit(1) - env = conf.Finish() - </sconstruct> - - <para> - - Because the ability to use a library successfully - often depends on having access to a header file - that describes the library's interface, - you can check for a library - <emphasis>and</emphasis> a header file - at the same time by using the - &CheckLibWithHeader; method: - - </para> - - <sconstruct> - env = Environment() - conf = Configure(env) - if not conf.CheckLibWithHeader('m', 'math.h', 'c'): - print 'Did not find libm.a or m.lib, exiting!' - Exit(1) - env = conf.Finish() - </sconstruct> - - <para> - - This is essentially shorthand for - separate calls to the &CheckHeader; and &CheckLib; - functions. - - </para> - - </section> - - <section> - <title>Checking for the Availability of a &typedef;</title> - - <para> - - Check for the availability of a &typedef; - by using the &CheckType; method: - - </para> - - <sconstruct> - env = Environment() - conf = Configure(env) - if not conf.CheckType('off_t'): - print 'Did not find off_t typedef, assuming int' - conf.env.Append(CCFLAGS = '-Doff_t=int') - env = conf.Finish() - </sconstruct> - - <para> - - You can also add a string that will be - placed at the beginning of the test file - that will be used to check for the &typedef;. - This provide a way to specify - files that must be included to find the &typedef;: - - </para> - - <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() - </sconstruct> - - </section> - - <section> - <title>Adding Your Own Custom Checks</title> - - <para> - - A custom check is a Python function - that checks for a certain condition to exist - on the running system, - usually using methods that &SCons; - supplies to take care of the details - of checking whether a compilation succeeds, - a link succeeds, - a program is runnable, - etc. - A simple custom check for the existence of - a specific library might look as follows: - - </para> - - <sconstruct> - mylib_test_source_file = """ - #include &lt;mylib.h&gt; - int main(int argc, char **argv) - { - MyLibrary mylib(argc, argv); - return 0; - } - """ - - def CheckMyLibrary(context): - context.Message('Checking for MyLibrary...') - result = context.TryLink(mylib_test_source_file, '.c') - context.Result(result) - return result - </sconstruct> - - <para> - - The &Message; and &Result; methods - should typically begin and end a custom check to - let the user know what's going on: - the &Message; call prints the - specified message (with no trailing newline) - and the &Result; call prints - <literal>yes</literal> if the check succeeds and - <literal>no</literal> if it doesn't. - The &TryLink; method - actually tests for whether the - specified program text - will successfully link. - - </para> - - <para> - - (Note that a custom check can modify - its check based on any arguments you - choose to pass it, - or by using or modifying the configure context environment - in the <literal>context.env</literal> attribute.) - - </para> - - <para> - - This custom check function is - then attached to the &configure_context; - by passing a dictionary - to the &Configure; call - that maps a name of the check - to the underlying function: - - </para> - - <sconstruct> - env = Environment() - conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) - </sconstruct> - - <para> - - You'll typically want to make - the check and the function name the same, - as we've done here, - to avoid potential confusion. - - </para> - - <para> - - We can then put these pieces together - and actually call the <literal>CheckMyLibrary</literal> check - as follows: - - </para> - - <sconstruct> - mylib_test_source_file = """ - #include &lt;mylib.h&gt; - int main(int argc, char **argv) - { - MyLibrary mylib(argc, argv); - return 0; - } - """ - - def CheckMyLibrary(context): - context.Message('Checking for MyLibrary... ') - result = context.TryLink(mylib_test_source_file, '.c') - context.Result(result) - return result - - env = Environment() - conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) - if not conf.CheckMyLibrary(): - print 'MyLibrary is not installed!' - Exit(1) - env = conf.Finish() - - # We would then add actual calls like Program() to build - # something using the "env" construction environment. - </sconstruct> - - <para> - - If MyLibrary is not installed on the system, - the output will look like: - - </para> - - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript file ... - Checking for MyLibrary... failed - MyLibrary is not installed! - </screen> - - <para> - - If MyLibrary is installed, - the output will look like: - - </para> - - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript file ... - Checking for MyLibrary... failed - scons: done reading SConscript - scons: Building targets ... - . - . - . - </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... yes - 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> - - <!-- - - <section> - <title>Controlling Configuration: the &config; Option</title> - - <para> - - XXX -D, -u and -U - - </para> - - </section> - - --> diff --git a/doc/user/sconf.xml b/doc/user/sconf.xml index 3ab022d..d5881e9 100644 --- a/doc/user/sconf.xml +++ b/doc/user/sconf.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-sconf" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Multi-Platform Configuration (&Autoconf; Functionality)</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -58,12 +79,12 @@ </para> - <programlisting> - env = Environment() - conf = Configure(env) - # Checks for libraries, header files, etc. go here! - env = conf.Finish() - </programlisting> + <sconstruct> +env = Environment() +conf = Configure(env) +# Checks for libraries, header files, etc. go here! +env = conf.Finish() + </sconstruct> <para> @@ -109,16 +130,16 @@ </para> - <programlisting> - env = Environment() - conf = Configure(env) - if not conf.CheckCHeader('math.h'): - print 'Math.h must be installed!' - Exit(1) - if conf.CheckCHeader('foo.h'): - conf.env.Append('-DHAS_FOO_H') - env = conf.Finish() - </programlisting> + <sconstruct> +env = Environment() +conf = Configure(env) +if not conf.CheckCHeader('math.h'): + print 'Math.h must be installed!' + Exit(1) +if conf.CheckCHeader('foo.h'): + conf.env.Append('-DHAS_FOO_H') +env = conf.Finish() + </sconstruct> <para> @@ -137,14 +158,14 @@ </para> - <programlisting> - env = Environment() - conf = Configure(env) - if not conf.CheckCXXHeader('vector.h'): - print 'vector.h must be installed!' - Exit(1) - env = conf.Finish() - </programlisting> + <sconstruct> +env = Environment() +conf = Configure(env) +if not conf.CheckCXXHeader('vector.h'): + print 'vector.h must be installed!' + Exit(1) +env = conf.Finish() + </sconstruct> </section> @@ -158,14 +179,14 @@ </para> - <programlisting> - env = Environment() - conf = Configure(env) - if not conf.CheckFunc('strcpy'): - print 'Did not find strcpy(), using local version' - conf.env.Append(CPPDEFINES = '-Dstrcpy=my_local_strcpy') - env = conf.Finish() - </programlisting> + <sconstruct> +env = Environment() +conf = Configure(env) +if not conf.CheckFunc('strcpy'): + print 'Did not find strcpy(), using local version' + conf.env.Append(CPPDEFINES = '-Dstrcpy=my_local_strcpy') +env = conf.Finish() + </sconstruct> </section> @@ -182,14 +203,14 @@ </para> - <programlisting> - env = Environment() - conf = Configure(env) - if not conf.CheckLib('m'): - print 'Did not find libm.a or m.lib, exiting!' - Exit(1) - env = conf.Finish() - </programlisting> + <sconstruct> +env = Environment() +conf = Configure(env) +if not conf.CheckLib('m'): + print 'Did not find libm.a or m.lib, exiting!' + Exit(1) +env = conf.Finish() + </sconstruct> <para> @@ -203,14 +224,14 @@ </para> - <programlisting> - env = Environment() - conf = Configure(env) - if not conf.CheckLibWithHeader('m', 'math.h', 'c'): - print 'Did not find libm.a or m.lib, exiting!' - Exit(1) - env = conf.Finish() - </programlisting> + <sconstruct> +env = Environment() +conf = Configure(env) +if not conf.CheckLibWithHeader('m', 'math.h', 'c'): + print 'Did not find libm.a or m.lib, exiting!' + Exit(1) +env = conf.Finish() + </sconstruct> <para> @@ -232,14 +253,14 @@ </para> - <programlisting> - env = Environment() - conf = Configure(env) - if not conf.CheckType('off_t'): - print 'Did not find off_t typedef, assuming int' - conf.env.Append(CCFLAGS = '-Doff_t=int') - env = conf.Finish() - </programlisting> + <sconstruct> +env = Environment() +conf = Configure(env) +if not conf.CheckType('off_t'): + print 'Did not find off_t typedef, assuming int' + conf.env.Append(CCFLAGS = '-Doff_t=int') +env = conf.Finish() + </sconstruct> <para> @@ -251,14 +272,14 @@ </para> - <programlisting> - env = Environment() - conf = Configure(env) - if not conf.CheckType('off_t', '#include <sys/types.h>\n'): - print 'Did not find off_t typedef, assuming int' - conf.env.Append(CCFLAGS = '-Doff_t=int') - env = conf.Finish() - </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() + </sconstruct> </section> @@ -281,22 +302,22 @@ </para> - <programlisting> - mylib_test_source_file = """ - #include <mylib.h> - int main(int argc, char **argv) - { - MyLibrary mylib(argc, argv); - return 0; - } - """ - - def CheckMyLibrary(context): - context.Message('Checking for MyLibrary...') - result = context.TryLink(mylib_test_source_file, '.c') - context.Result(result) - return result - </programlisting> + <sconstruct> +mylib_test_source_file = """ +#include &lt;mylib.h&gt; +int main(int argc, char **argv) +{ + MyLibrary mylib(argc, argv); + return 0; +} +""" + +def CheckMyLibrary(context): + context.Message('Checking for MyLibrary...') + result = context.TryLink(mylib_test_source_file, '.c') + context.Result(result) + return result + </sconstruct> <para> @@ -336,10 +357,10 @@ </para> - <programlisting> - env = Environment() - conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) - </programlisting> + <sconstruct> +env = Environment() +conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) + </sconstruct> <para> @@ -358,32 +379,32 @@ </para> - <programlisting> - mylib_test_source_file = """ - #include <mylib.h> - int main(int argc, char **argv) - { - MyLibrary mylib(argc, argv); - return 0; - } - """ - - def CheckMyLibrary(context): - context.Message('Checking for MyLibrary... ') - result = context.TryLink(mylib_test_source_file, '.c') - context.Result(result) - return result - - env = Environment() - conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) - if not conf.CheckMyLibrary(): - print 'MyLibrary is not installed!' - Exit(1) - env = conf.Finish() - - # We would then add actual calls like Program() to build - # something using the "env" construction environment. - </programlisting> + <sconstruct> +mylib_test_source_file = """ +#include &lt;mylib.h&gt; +int main(int argc, char **argv) +{ + MyLibrary mylib(argc, argv); + return 0; +} +""" + +def CheckMyLibrary(context): + context.Message('Checking for MyLibrary... ') + result = context.TryLink(mylib_test_source_file, '.c') + context.Result(result) + return result + +env = Environment() +conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) +if not conf.CheckMyLibrary(): + print 'MyLibrary is not installed!' + Exit(1) +env = conf.Finish() + +# We would then add actual calls like Program() to build +# something using the "env" construction environment. + </sconstruct> <para> @@ -393,10 +414,10 @@ </para> <screen> - % <userinput>scons</userinput> - scons: Reading SConscript file ... - Checking for MyLibrary... failed - MyLibrary is not installed! +% <userinput>scons</userinput> +scons: Reading SConscript file ... +Checking for MyLibrary... failed +MyLibrary is not installed! </screen> <para> @@ -407,14 +428,14 @@ </para> <screen> - % <userinput>scons</userinput> - scons: Reading SConscript file ... - Checking for MyLibrary... failed - scons: done reading SConscript - scons: Building targets ... - . - . - . +% <userinput>scons</userinput> +scons: Reading SConscript file ... +Checking for MyLibrary... failed +scons: done reading SConscript +scons: Building targets ... + . + . + . </screen> </section> @@ -434,10 +455,10 @@ </para> <screen> - % <userinput>scons -Q -c</userinput> - Checking for MyLibrary... yes - Removed foo.o - Removed foo +% <userinput>scons -Q -c</userinput> +Checking for MyLibrary... yes +Removed foo.o +Removed foo </screen> <para> @@ -452,20 +473,20 @@ </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> + <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 +% <userinput>scons -Q -c</userinput> +Removed foo.o +Removed foo </screen> </section> @@ -484,3 +505,5 @@ </section> --> + +</chapter> diff --git a/doc/user/scons.css b/doc/user/scons.css new file mode 100644 index 0000000..6941abb --- /dev/null +++ b/doc/user/scons.css @@ -0,0 +1,263 @@ +body { + background: #ffffff; + margin: 10px; + padding: 0; + font-family:palatino, georgia, verdana, arial, sans-serif; + } + + +a { + color: #80572a; + } + +a:hover { + color: #d72816; + text-decoration: none; + } + +tt { + color: #a14447; + } + +pre { + background: #e0e0e0; + } + +#main { + border: 1px solid; + border-color: black; + background-color: white; + background-image: url(../images/sconsback.png); + background-repeat: repeat-y 50% 0; + background-position: right top; + margin: 30px auto; + width: 750px; + } + +#banner { + background-image: url(../images/scons-banner.jpg); + border-bottom: 1px solid; + height: 95px; + } + +#menu { + font-family: sans-serif; + font-size: small; + line-height: 0.9em; + float: right; + width: 220px; + clear: both; + margin-top: 10px; + } + +#menu li { + margin-bottom: 7px; + } + +#menu li li { + margin-bottom: 2px; + } + +#menu li.submenuitems { + margin-bottom: 2px; + } + +#menu a { + text-decoration: none; + } + +#footer { + border-top: 1px solid black; + text-align: center; + font-size: small; + color: #822; + margin-top: 4px; + background: #eee; + } + +ul.hack { + list-style-position:inside; + } + +ul.menuitems { + list-style-type: none; + } + +ul.submenuitems { + list-style-type: none; + font-size: smaller; + margin-left: 0; + padding-left: 16px; + } + +ul.subsubmenuitems { + list-style-type: none; + font-size: smaller; + margin-left: 0; + padding-left: 16px; + } + +ol.upper-roman { + list-style-type: upper-roman; + } + +ol.decimal { + list-style-type: decimal; + } + +#currentpage { + font-weight: bold; + } + +#bodycontent { + margin: 15px; + width: 520px; + font-size: small; + line-height: 1.5em; + } + +#bodycontent li { + margin-bottom: 6px; + list-style-type: square; + } + +#sconsdownloadtable downloadtable { + display: table; + margin-left: 5%; + border-spacing: 12px 3px; + } + +#sconsdownloadtable downloadrow { + display: table-row; + } + +#sconsdownloadtable downloadentry { + display: table-cell; + text-align: center; + vertical-align: bottom; + } + +#sconsdownloadtable downloaddescription { + display: table-cell; + font-weight: bold; + text-align: left; + } + +#sconsdownloadtable downloadversion { + display: table-cell; + font-weight: bold; + text-align: center; + } + +#sconsdocversiontable sconsversiontable { + display: table; + margin-left: 10%; + border-spacing: 12px 3px; + } + +#sconsdocversiontable sconsversionrow { + display: table-row; + } + +#sconsdocversiontable docformat { + display: table-cell; + font-weight: bold; + text-align: center; + vertical-align: bottom; + } + +#sconsdocversiontable sconsversion { + display: table-cell; + font-weight: bold; + text-align: left; + } + +#sconsdocversiontable docversion { + display: table-cell; + font-weight: bold; + text-align: center; + } + +#osrating { + margin-left: 35px; + } + + +h2 { + color: #272; + color: #c01714; + font-family: sans-serif; + font-weight: normal; + } + +h2.pagetitle { + font-size: xx-large; + } +h3 { + margin-bottom: 10px; + } + +.date { + font-size: small; + color: gray; + } + +.link { + margin-bottom: 22px; + } + +.linkname { + } + +.linkdesc { + margin: 10px; + margin-top: 0; + } + +.quote { + margin-top: 20px; + margin-bottom: 10px; + background: #f8f8f8; + border: 1px solid; + border-color: #ddd; + } + +.quotetitle { + font-weight: bold; + font-size: large; + margin: 10px; + } + +.quotedesc { + margin-left: 20px; + margin-right: 10px; + margin-bottom: 15px; + } + +.quotetext { + margin-top: 20px; + margin-left: 20px; + margin-right: 10px; + font-style: italic; + } + +.quoteauthor { + font-size: small; + text-align: right; + margin-top: 10px; + margin-right: 7px; + } + +.sconslogo { + font-style: normal; + font-weight: bold; + color: #822; + } + +.downloadlink { + } + +.downloaddescription { + margin-left: 1em; + margin-bottom: 0.4em; + } diff --git a/doc/user/scons_title.xsl b/doc/user/scons_title.xsl new file mode 100644 index 0000000..52ca405 --- /dev/null +++ b/doc/user/scons_title.xsl @@ -0,0 +1,6352 @@ +<?xml version="1.0"?> +<!-- + + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation + + 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. + +--> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:exsl="http://exslt.org/common" + xmlns:fo="http://www.w3.org/1999/XSL/Format" + version="1.0" exclude-result-prefixes="exsl"> + +<!-- This stylesheet was created by template/titlepage.xsl; do not edit it by hand. --> + +<xsl:template name="article.titlepage.recto"> + <xsl:choose> + <xsl:when test="articleinfo/title"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/title"/> + </xsl:when> + <xsl:when test="artheader/title"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="articleinfo/subtitle"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/subtitle"/> + </xsl:when> + <xsl:when test="artheader/subtitle"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/mediaobject"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/mediaobject"/> + <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/mediaobject"/> +</xsl:template> + +<xsl:template name="article.titlepage.verso"> +</xsl:template> + +<xsl:template name="article.titlepage.separator"> +</xsl:template> + +<xsl:template name="article.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="article.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="article.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" font-family="{$title.fontset}"> + <xsl:variable name="recto.content"> + <xsl:call-template name="article.titlepage.before.recto"/> + <xsl:call-template name="article.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block start-indent="0pt" text-align="center"><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="article.titlepage.before.verso"/> + <xsl:call-template name="article.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="article.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="article.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="article.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="article.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="article.titlepage.recto.style" keep-with-next.within-column="always" font-size="24.8832pt" font-weight="bold"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::article[1]"/> +</xsl:call-template> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="article.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="mediaobject" mode="article.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="article.titlepage.recto.style"> +<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="set.titlepage.recto"> + <xsl:choose> + <xsl:when test="setinfo/title"> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="setinfo/subtitle"> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/corpauthor"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/authorgroup"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/author"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/othercredit"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/releaseinfo"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/copyright"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/legalnotice"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/pubdate"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/revision"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/revhistory"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/abstract"/> + <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="set.titlepage.verso"> +</xsl:template> + +<xsl:template name="set.titlepage.separator"> +</xsl:template> + +<xsl:template name="set.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="set.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="set.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="set.titlepage.before.recto"/> + <xsl:call-template name="set.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="set.titlepage.before.verso"/> + <xsl:call-template name="set.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="set.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="set.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="set.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style" text-align="center" font-size="24.8832pt" space-before="18.6624pt" font-weight="bold" font-family="{$title.fontset}"> +<xsl:call-template name="division.title"> +<xsl:with-param name="node" select="ancestor-or-self::set[1]"/> +</xsl:call-template> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style" font-family="{$title.fontset}" text-align="center"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="set.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="set.titlepage.recto.style"> +<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:param name="scons.inner.twidtha"> + <xsl:choose> + <xsl:when test="$paper.type = 'A4'">200mm</xsl:when> + <xsl:otherwise>205.9mm</xsl:otherwise> <!-- 8.5in-10mm --> + </xsl:choose> +</xsl:param> +<xsl:param name="scons.inner.twidthb"> + <xsl:choose> + <xsl:when test="$paper.type = 'A4'">190mm</xsl:when> + <xsl:otherwise>195.9mm</xsl:otherwise> <!-- 8.5in-20mm --> + </xsl:choose> +</xsl:param> +<xsl:param name="scons.inner.twidthc"> + <xsl:choose> + <xsl:when test="$paper.type = 'A4'">180mm</xsl:when> + <xsl:otherwise>185.9mm</xsl:otherwise> <!-- 8.5in-30mm --> + </xsl:choose> +</xsl:param> + +<xsl:template name="book.titlepage.recto"> + + <fo:block-container height="3mm"> + <fo:block></fo:block> + </fo:block-container> + <fo:block> + <fo:table table-layout="fixed" width="100%" padding="0pt" border-width="0pt" border-style="none"> + + <fo:table-column column-width="10mm"/> + <fo:table-column column-width="{$scons.inner.twidtha}"/> + <fo:table-body> + <fo:table-row text-align="center"> + <fo:table-cell> + <fo:block></fo:block> + </fo:table-cell> + <fo:table-cell text-align="center"> + <fo:block line-height="0"> + <fo:external-graphic + src="url(titlepage/SConsBuildBricks_path.svg)" + width="{$scons.inner.twidtha}" content-width="scale-to-fit" + scaling="uniform"/> + </fo:block></fo:table-cell> + </fo:table-row> + </fo:table-body> + </fo:table> + </fo:block> + + + <fo:block-container height="4cm"> + <fo:block></fo:block> + </fo:block-container> + +<fo:block> + <fo:table table-layout="fixed" width="100%" border-width="0pt" border-style="none"> + + <fo:table-column column-width="10mm"/> + <fo:table-column column-width="{$scons.inner.twidthc}"/> + <fo:table-column column-width="20mm"/> + + <fo:table-body> + <fo:table-row text-align="center"> + <fo:table-cell> + <fo:block></fo:block> + </fo:table-cell> + <fo:table-cell text-align="left" display-align="after"> + <xsl:choose> + <xsl:when test="bookinfo/title"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + <xsl:otherwise> + <fo:block><fo:inline> </fo:inline></fo:block> + </xsl:otherwise> + </xsl:choose> + </fo:table-cell> + <fo:table-cell> + <fo:block></fo:block> + </fo:table-cell> + </fo:table-row> + </fo:table-body> + </fo:table> + </fo:block> + +<!-- + <fo:block-container height="6mm"> + <fo:block></fo:block> + </fo:block-container> +--> + + <xsl:choose> + <xsl:when test="bookinfo/edition"> +<fo:block> + <fo:table table-layout="fixed" width="100%" border-width="0pt" border-style="none"> + + <fo:table-column column-width="10mm"/> + <fo:table-column column-width="{$scons.inner.twidthc}"/> + <fo:table-column column-width="20mm"/> + + <fo:table-body> + <fo:table-row text-align="center"> + <fo:table-cell> + <fo:block></fo:block> + </fo:table-cell> + <fo:table-cell text-align="left" display-align="after"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/edition"/> + </fo:table-cell> + <fo:table-cell> + <fo:block></fo:block> + </fo:table-cell> + </fo:table-row> + </fo:table-body> + </fo:table> + </fo:block> + + <fo:block-container height="9mm"> + <fo:block></fo:block> + </fo:block-container> + </xsl:when> + <xsl:otherwise> + <fo:block-container height="6mm"> + <fo:block></fo:block> + </fo:block-container> + </xsl:otherwise> + </xsl:choose> + + +<fo:block> + <fo:table table-layout="fixed" width="100%" border-width="0pt" border-style="none"> + + <fo:table-column column-width="10mm"/> + <fo:table-column column-width="{$scons.inner.twidthc}"/> + <fo:table-column column-width="20mm"/> + + <fo:table-body> + <fo:table-row text-align="center"> + <fo:table-cell> + <fo:block></fo:block> + </fo:table-cell> + <fo:table-cell text-align="left" display-align="after"> + <xsl:choose> + <xsl:when test="bookinfo/subtitle"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + <xsl:otherwise> + <fo:block><fo:inline> </fo:inline></fo:block> + </xsl:otherwise> + </xsl:choose> + </fo:table-cell> + <fo:table-cell> + <fo:block></fo:block> + </fo:table-cell> + </fo:table-row> + </fo:table-body> + </fo:table> + </fo:block> + + + <xsl:choose> + <xsl:when test="bookinfo/corpauthor"> + <fo:block-container height="15mm"> + <fo:block></fo:block> + </fo:block-container> +<fo:block> + <fo:table table-layout="fixed" width="100%" border-width="0pt" border-style="none"> + + <fo:table-column column-width="10mm"/> + <fo:table-column column-width="{$scons.inner.twidthc}"/> + <fo:table-column column-width="20mm"/> + + <fo:table-body> + <fo:table-row text-align="center"> + <fo:table-cell> + <fo:block></fo:block> + </fo:table-cell> + <fo:table-cell text-align="left" display-align="after"> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/corpauthor"/> + </fo:table-cell> + <fo:table-cell> + <fo:block></fo:block> + </fo:table-cell> + </fo:table-row> + </fo:table-body> + </fo:table> + </fo:block> + </xsl:when> + <xsl:otherwise> + </xsl:otherwise> + </xsl:choose> + + <fo:block-container height="9mm"> + <fo:block></fo:block> + </fo:block-container> + + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/mediaobject"/> + <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/mediaobject"/> +</xsl:template> + +<xsl:template name="book.titlepage.verso"> + <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/releaseinfo"/> + <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/copyright"/> + <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/pubdate"/> + <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/revision"/> + <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/legalnotice"/> +</xsl:template> + +<xsl:template name="book.titlepage.separator"> +</xsl:template> + +<xsl:template name="book.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="book.titlepage.before.verso"><fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" break-after="page"/> +</xsl:template> + +<xsl:template name="book.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="book.titlepage.before.recto"/> + <xsl:call-template name="book.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="book.titlepage.before.verso"/> + <xsl:call-template name="book.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="book.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="book.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="book.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<!-- +<xsl:template match="title" mode="book.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" text-align="center" font-size="24pt" space-before="18pt" font-weight="bold" font-family="'serif'"> +<xsl:call-template name="division.title"> +<xsl:with-param name="node" select="ancestor-or-self::book[1]"/> +</xsl:call-template> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="book.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" text-align="left" font-size="20pt" space-before="15pt" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</fo:block> +</xsl:template> +--> +<xsl:template match="corpauthor" mode="book.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" text-align="left" font-size="20pt" space-before="0pt" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="mediaobject" mode="book.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="book.titlepage.verso.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style"> +<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="book.titlepage.verso.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style"> +<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="book.titlepage.verso.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style"> +<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="book.titlepage.verso.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style"> +<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="part.titlepage.recto"> + <xsl:choose> + <xsl:when test="partinfo/title"> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="partinfo/subtitle"> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="part.titlepage.verso"> +</xsl:template> + +<xsl:template name="part.titlepage.separator"> +</xsl:template> + +<xsl:template name="part.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="part.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="part.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="part.titlepage.before.recto"/> + <xsl:call-template name="part.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="part.titlepage.before.verso"/> + <xsl:call-template name="part.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="part.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="part.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="part.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="part.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="part.titlepage.recto.style" text-align="center" font-size="24.8832pt" space-before="18.6624pt" font-weight="bold" font-family="{$title.fontset}"> +<xsl:call-template name="division.title"> +<xsl:with-param name="node" select="ancestor-or-self::part[1]"/> +</xsl:call-template> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="part.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="part.titlepage.recto.style" text-align="center" font-size="20.736pt" space-before="15.552pt" font-weight="bold" font-style="italic" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="partintro.titlepage.recto"> + <xsl:choose> + <xsl:when test="partintroinfo/title"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="partintroinfo/subtitle"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/corpauthor"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/corpauthor"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/authorgroup"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/authorgroup"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/author"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/author"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/othercredit"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/othercredit"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/releaseinfo"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/copyright"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/copyright"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/legalnotice"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/legalnotice"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/pubdate"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/pubdate"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/revision"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/revision"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/revhistory"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/revhistory"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/abstract"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/abstract"/> + <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="partintro.titlepage.verso"> +</xsl:template> + +<xsl:template name="partintro.titlepage.separator"> +</xsl:template> + +<xsl:template name="partintro.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="partintro.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="partintro.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="partintro.titlepage.before.recto"/> + <xsl:call-template name="partintro.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="partintro.titlepage.before.verso"/> + <xsl:call-template name="partintro.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="partintro.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="partintro.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="partintro.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style" text-align="center" font-size="24.8832pt" font-weight="bold" space-before="1em" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style" text-align="center" font-size="14.4pt" font-weight="bold" font-style="italic" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="partintro.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="partintro.titlepage.recto.style"> +<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="reference.titlepage.recto"> + <xsl:choose> + <xsl:when test="referenceinfo/title"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="referenceinfo/subtitle"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/corpauthor"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/corpauthor"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/authorgroup"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/authorgroup"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/author"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/author"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/othercredit"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/othercredit"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/releaseinfo"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/copyright"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/copyright"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/legalnotice"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/legalnotice"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/pubdate"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/pubdate"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/revision"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/revision"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/revhistory"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/revhistory"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/abstract"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/abstract"/> + <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="reference.titlepage.verso"> +</xsl:template> + +<xsl:template name="reference.titlepage.separator"> +</xsl:template> + +<xsl:template name="reference.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="reference.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="reference.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="reference.titlepage.before.recto"/> + <xsl:call-template name="reference.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="reference.titlepage.before.verso"/> + <xsl:call-template name="reference.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="reference.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="reference.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="reference.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style" text-align="center" font-size="24.8832pt" space-before="18.6624pt" font-weight="bold" font-family="{$title.fontset}"> +<xsl:call-template name="division.title"> +<xsl:with-param name="node" select="ancestor-or-self::reference[1]"/> +</xsl:call-template> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style" font-family="{$title.fontset}" text-align="center"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="reference.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="reference.titlepage.recto.style"> +<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="refsynopsisdiv.titlepage.recto"> + <xsl:choose> + <xsl:when test="refsynopsisdivinfo/title"> + <xsl:apply-templates mode="refsynopsisdiv.titlepage.recto.auto.mode" select="refsynopsisdivinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="refsynopsisdiv.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="refsynopsisdiv.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="refsynopsisdiv.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="refsynopsisdiv.titlepage.verso"> +</xsl:template> + +<xsl:template name="refsynopsisdiv.titlepage.separator"> +</xsl:template> + +<xsl:template name="refsynopsisdiv.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="refsynopsisdiv.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="refsynopsisdiv.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="refsynopsisdiv.titlepage.before.recto"/> + <xsl:call-template name="refsynopsisdiv.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="refsynopsisdiv.titlepage.before.verso"/> + <xsl:call-template name="refsynopsisdiv.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="refsynopsisdiv.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="refsynopsisdiv.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="refsynopsisdiv.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="refsynopsisdiv.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="refsynopsisdiv.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="refsynopsisdiv.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="refsection.titlepage.recto"> + <xsl:choose> + <xsl:when test="refsectioninfo/title"> + <xsl:apply-templates mode="refsection.titlepage.recto.auto.mode" select="refsectioninfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="refsection.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="refsection.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="refsection.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="refsection.titlepage.verso"> +</xsl:template> + +<xsl:template name="refsection.titlepage.separator"> +</xsl:template> + +<xsl:template name="refsection.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="refsection.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="refsection.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="refsection.titlepage.before.recto"/> + <xsl:call-template name="refsection.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="refsection.titlepage.before.verso"/> + <xsl:call-template name="refsection.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="refsection.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="refsection.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="refsection.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="refsection.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="refsection.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="refsection.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="refsect1.titlepage.recto"> + <xsl:choose> + <xsl:when test="refsect1info/title"> + <xsl:apply-templates mode="refsect1.titlepage.recto.auto.mode" select="refsect1info/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="refsect1.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="refsect1.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="refsect1.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="refsect1.titlepage.verso"> +</xsl:template> + +<xsl:template name="refsect1.titlepage.separator"> +</xsl:template> + +<xsl:template name="refsect1.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="refsect1.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="refsect1.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="refsect1.titlepage.before.recto"/> + <xsl:call-template name="refsect1.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="refsect1.titlepage.before.verso"/> + <xsl:call-template name="refsect1.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="refsect1.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="refsect1.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="refsect1.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="refsect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="refsect1.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="refsect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="refsect2.titlepage.recto"> + <xsl:choose> + <xsl:when test="refsect2info/title"> + <xsl:apply-templates mode="refsect2.titlepage.recto.auto.mode" select="refsect2info/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="refsect2.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="refsect2.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="refsect2.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="refsect2.titlepage.verso"> +</xsl:template> + +<xsl:template name="refsect2.titlepage.separator"> +</xsl:template> + +<xsl:template name="refsect2.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="refsect2.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="refsect2.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="refsect2.titlepage.before.recto"/> + <xsl:call-template name="refsect2.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="refsect2.titlepage.before.verso"/> + <xsl:call-template name="refsect2.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="refsect2.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="refsect2.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="refsect2.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="refsect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="refsect2.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="refsect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="refsect3.titlepage.recto"> + <xsl:choose> + <xsl:when test="refsect3info/title"> + <xsl:apply-templates mode="refsect3.titlepage.recto.auto.mode" select="refsect3info/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="refsect3.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="refsect3.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="refsect3.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="refsect3.titlepage.verso"> +</xsl:template> + +<xsl:template name="refsect3.titlepage.separator"> +</xsl:template> + +<xsl:template name="refsect3.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="refsect3.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="refsect3.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="refsect3.titlepage.before.recto"/> + <xsl:call-template name="refsect3.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="refsect3.titlepage.before.verso"/> + <xsl:call-template name="refsect3.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="refsect3.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="refsect3.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="refsect3.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="refsect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="refsect3.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="refsect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="dedication.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="dedication.titlepage.recto.style" margin-left="{$title.margin.left}" font-size="24.8832pt" font-family="{$title.fontset}" font-weight="bold"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::dedication[1]"/> +</xsl:call-template></fo:block> + <xsl:choose> + <xsl:when test="dedicationinfo/subtitle"> + <xsl:apply-templates mode="dedication.titlepage.recto.auto.mode" select="dedicationinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="dedication.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="dedication.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="dedication.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="dedication.titlepage.verso"> +</xsl:template> + +<xsl:template name="dedication.titlepage.separator"> +</xsl:template> + +<xsl:template name="dedication.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="dedication.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="dedication.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="dedication.titlepage.before.recto"/> + <xsl:call-template name="dedication.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="dedication.titlepage.before.verso"/> + <xsl:call-template name="dedication.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="dedication.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="dedication.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="dedication.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="dedication.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="dedication.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="dedication.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="preface.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style" margin-left="{$title.margin.left}" font-size="24.8832pt" font-family="{$title.fontset}" font-weight="bold"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::preface[1]"/> +</xsl:call-template></fo:block> + <xsl:choose> + <xsl:when test="prefaceinfo/subtitle"> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/corpauthor"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/corpauthor"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/authorgroup"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/authorgroup"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/author"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/author"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/othercredit"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/othercredit"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/releaseinfo"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/copyright"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/copyright"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/legalnotice"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/legalnotice"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/pubdate"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/pubdate"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/revision"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/revision"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/revhistory"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/revhistory"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/abstract"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/abstract"/> + <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="preface.titlepage.verso"> +</xsl:template> + +<xsl:template name="preface.titlepage.separator"> +</xsl:template> + +<xsl:template name="preface.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="preface.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="preface.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="preface.titlepage.before.recto"/> + <xsl:call-template name="preface.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="preface.titlepage.before.verso"/> + <xsl:call-template name="preface.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="preface.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="preface.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="preface.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="preface.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="preface.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="preface.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="preface.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="preface.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="preface.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="preface.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="preface.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="preface.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="preface.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="preface.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="preface.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="preface.titlepage.recto.style"> +<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="chapter.titlepage.recto"> + + <fo:block-container height="1cm"> + <fo:block></fo:block> + </fo:block-container> + +<fo:block text-align="center"> + <fo:leader leader-length="85%" leader-pattern="rule" rule-style="solid" rule-thickness="1pt" color="#C51410"/> +</fo:block> + + <fo:block-container height="0.7cm"> + <fo:block></fo:block> + </fo:block-container> + + <xsl:choose> + <xsl:when test="chapterinfo/title"> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + + <fo:block-container height="0.7cm"> + <fo:block></fo:block> + </fo:block-container> + + +<fo:block text-align="center"> + <fo:leader leader-length="85%" leader-pattern="rule" rule-style="solid" rule-thickness="1pt" color="#C51410"/> +</fo:block> + + <fo:block-container height="1cm"> + <fo:block></fo:block> + </fo:block-container> + +</xsl:template> + +<xsl:template name="chapter.titlepage.verso"> +</xsl:template> + +<xsl:template name="chapter.titlepage.separator"> +<!-- + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" break-after="page"/> +--> +</xsl:template> + +<xsl:template name="chapter.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="chapter.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="chapter.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" font-family="{$title.fontset}"> + <xsl:variable name="recto.content"> + <xsl:call-template name="chapter.titlepage.before.recto"/> + <xsl:call-template name="chapter.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block margin-left="{$title.margin.left}"><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="chapter.titlepage.before.verso"/> + <xsl:call-template name="chapter.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="chapter.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="chapter.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="chapter.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style" font-size="24.8832pt" font-weight="bold"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::chapter[1]"/> +</xsl:call-template> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style" space-before="0.5em" font-style="italic" font-size="14.4pt" font-weight="bold"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style" space-before="0.5em" space-after="0.5em" font-size="14.4pt"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style" space-before="0.5em" space-after="0.5em" font-size="14.4pt"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style" space-before="0.5em" space-after="0.5em" font-size="14.4pt"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="chapter.titlepage.recto.style"> +<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="appendix.titlepage.recto"> + <xsl:choose> + <xsl:when test="appendixinfo/title"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="appendixinfo/subtitle"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/corpauthor"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/corpauthor"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/authorgroup"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/authorgroup"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/author"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/author"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/othercredit"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/othercredit"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/releaseinfo"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/copyright"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/copyright"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/legalnotice"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/legalnotice"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/pubdate"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/pubdate"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/revision"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/revision"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/revhistory"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/revhistory"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/abstract"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/abstract"/> + <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="appendix.titlepage.verso"> +</xsl:template> + +<xsl:template name="appendix.titlepage.separator"> +</xsl:template> + +<xsl:template name="appendix.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="appendix.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="appendix.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="appendix.titlepage.before.recto"/> + <xsl:call-template name="appendix.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="appendix.titlepage.before.verso"/> + <xsl:call-template name="appendix.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="appendix.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="appendix.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="appendix.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style" margin-left="{$title.margin.left}" font-size="24.8832pt" font-weight="bold" font-family="{$title.fontset}"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::appendix[1]"/> +</xsl:call-template> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="appendix.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="appendix.titlepage.recto.style"> +<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="section.titlepage.recto"> + <xsl:choose> + <xsl:when test="sectioninfo/title"> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sectioninfo/subtitle"> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/corpauthor"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/authorgroup"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/author"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/othercredit"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/releaseinfo"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/copyright"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/legalnotice"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/pubdate"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/revision"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/revhistory"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/abstract"/> + <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="section.titlepage.verso"> +</xsl:template> + +<xsl:template name="section.titlepage.separator"> +</xsl:template> + +<xsl:template name="section.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="section.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="section.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="section.titlepage.before.recto"/> + <xsl:call-template name="section.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="section.titlepage.before.verso"/> + <xsl:call-template name="section.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="section.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="section.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="section.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style" margin-left="{$title.margin.left}" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="section.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="section.titlepage.recto.style"> +<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="sect1.titlepage.recto"> + <xsl:choose> + <xsl:when test="sect1info/title"> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sect1info/subtitle"> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/corpauthor"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/authorgroup"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/author"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/othercredit"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/releaseinfo"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/copyright"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/legalnotice"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/pubdate"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/revision"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/revhistory"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/abstract"/> + <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="sect1.titlepage.verso"> +</xsl:template> + +<xsl:template name="sect1.titlepage.separator"> +</xsl:template> + +<xsl:template name="sect1.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="sect1.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="sect1.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="sect1.titlepage.before.recto"/> + <xsl:call-template name="sect1.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="sect1.titlepage.before.verso"/> + <xsl:call-template name="sect1.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="sect1.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="sect1.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="sect1.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style" margin-left="{$title.margin.left}" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="sect1.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect1.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="sect2.titlepage.recto"> + <xsl:choose> + <xsl:when test="sect2info/title"> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sect2info/subtitle"> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/corpauthor"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/authorgroup"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/author"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/othercredit"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/releaseinfo"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/copyright"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/legalnotice"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/pubdate"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/revision"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/revhistory"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/abstract"/> + <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="sect2.titlepage.verso"> +</xsl:template> + +<xsl:template name="sect2.titlepage.separator"> +</xsl:template> + +<xsl:template name="sect2.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="sect2.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="sect2.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="sect2.titlepage.before.recto"/> + <xsl:call-template name="sect2.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="sect2.titlepage.before.verso"/> + <xsl:call-template name="sect2.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="sect2.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="sect2.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="sect2.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style" margin-left="{$title.margin.left}" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="sect2.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect2.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="sect3.titlepage.recto"> + <xsl:choose> + <xsl:when test="sect3info/title"> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sect3info/subtitle"> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/corpauthor"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/authorgroup"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/author"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/othercredit"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/releaseinfo"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/copyright"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/legalnotice"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/pubdate"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/revision"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/revhistory"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/abstract"/> + <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="sect3.titlepage.verso"> +</xsl:template> + +<xsl:template name="sect3.titlepage.separator"> +</xsl:template> + +<xsl:template name="sect3.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="sect3.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="sect3.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="sect3.titlepage.before.recto"/> + <xsl:call-template name="sect3.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="sect3.titlepage.before.verso"/> + <xsl:call-template name="sect3.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="sect3.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="sect3.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="sect3.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style" margin-left="{$title.margin.left}" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="sect3.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect3.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="sect4.titlepage.recto"> + <xsl:choose> + <xsl:when test="sect4info/title"> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sect4info/subtitle"> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/corpauthor"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/authorgroup"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/author"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/othercredit"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/releaseinfo"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/copyright"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/legalnotice"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/pubdate"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/revision"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/revhistory"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/abstract"/> + <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="sect4.titlepage.verso"> +</xsl:template> + +<xsl:template name="sect4.titlepage.separator"> +</xsl:template> + +<xsl:template name="sect4.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="sect4.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="sect4.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="sect4.titlepage.before.recto"/> + <xsl:call-template name="sect4.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="sect4.titlepage.before.verso"/> + <xsl:call-template name="sect4.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="sect4.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="sect4.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="sect4.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style" margin-left="{$title.margin.left}" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="sect4.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect4.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="sect5.titlepage.recto"> + <xsl:choose> + <xsl:when test="sect5info/title"> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sect5info/subtitle"> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/corpauthor"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/authorgroup"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/author"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/othercredit"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/releaseinfo"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/copyright"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/legalnotice"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/pubdate"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/revision"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/revhistory"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/abstract"/> + <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="sect5.titlepage.verso"> +</xsl:template> + +<xsl:template name="sect5.titlepage.separator"> +</xsl:template> + +<xsl:template name="sect5.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="sect5.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="sect5.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="sect5.titlepage.before.recto"/> + <xsl:call-template name="sect5.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="sect5.titlepage.before.verso"/> + <xsl:call-template name="sect5.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="sect5.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="sect5.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="sect5.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style" margin-left="{$title.margin.left}" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="sect5.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sect5.titlepage.recto.style"> +<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="simplesect.titlepage.recto"> + <xsl:choose> + <xsl:when test="simplesectinfo/title"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="simplesectinfo/subtitle"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/corpauthor"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/corpauthor"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/authorgroup"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/authorgroup"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/author"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/author"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/othercredit"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/othercredit"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/releaseinfo"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/copyright"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/copyright"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/legalnotice"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/legalnotice"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/pubdate"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/pubdate"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/revision"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/revision"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/revhistory"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/revhistory"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/abstract"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/abstract"/> + <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="simplesect.titlepage.verso"> +</xsl:template> + +<xsl:template name="simplesect.titlepage.separator"> +</xsl:template> + +<xsl:template name="simplesect.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="simplesect.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="simplesect.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="simplesect.titlepage.before.recto"/> + <xsl:call-template name="simplesect.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="simplesect.titlepage.before.verso"/> + <xsl:call-template name="simplesect.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="simplesect.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="simplesect.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="simplesect.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style" margin-left="{$title.margin.left}" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="simplesect.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="simplesect.titlepage.recto.style"> +<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="bibliography.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="bibliography.titlepage.recto.style" margin-left="{$title.margin.left}" font-size="24.8832pt" font-family="{$title.fontset}" font-weight="bold"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::bibliography[1]"/> +</xsl:call-template></fo:block> + <xsl:choose> + <xsl:when test="bibliographyinfo/subtitle"> + <xsl:apply-templates mode="bibliography.titlepage.recto.auto.mode" select="bibliographyinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="bibliography.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="bibliography.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="bibliography.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="bibliography.titlepage.verso"> +</xsl:template> + +<xsl:template name="bibliography.titlepage.separator"> +</xsl:template> + +<xsl:template name="bibliography.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="bibliography.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="bibliography.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="bibliography.titlepage.before.recto"/> + <xsl:call-template name="bibliography.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="bibliography.titlepage.before.verso"/> + <xsl:call-template name="bibliography.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="bibliography.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="bibliography.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="bibliography.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="bibliography.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="bibliography.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="bibliography.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="bibliodiv.titlepage.recto"> + <xsl:choose> + <xsl:when test="bibliodivinfo/title"> + <xsl:apply-templates mode="bibliodiv.titlepage.recto.auto.mode" select="bibliodivinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="bibliodiv.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="bibliodiv.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="bibliodiv.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="bibliodivinfo/subtitle"> + <xsl:apply-templates mode="bibliodiv.titlepage.recto.auto.mode" select="bibliodivinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="bibliodiv.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="bibliodiv.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="bibliodiv.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="bibliodiv.titlepage.verso"> +</xsl:template> + +<xsl:template name="bibliodiv.titlepage.separator"> +</xsl:template> + +<xsl:template name="bibliodiv.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="bibliodiv.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="bibliodiv.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="bibliodiv.titlepage.before.recto"/> + <xsl:call-template name="bibliodiv.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="bibliodiv.titlepage.before.verso"/> + <xsl:call-template name="bibliodiv.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="bibliodiv.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="bibliodiv.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="bibliodiv.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="bibliodiv.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="bibliodiv.titlepage.recto.style" margin-left="{$title.margin.left}" font-size="20.736pt" font-family="{$title.fontset}" font-weight="bold"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::bibliodiv[1]"/> +</xsl:call-template> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="bibliodiv.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="bibliodiv.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="bibliodiv.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="glossary.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="glossary.titlepage.recto.style" margin-left="{$title.margin.left}" font-size="24.8832pt" font-family="{$title.fontset}" font-weight="bold"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::glossary[1]"/> +</xsl:call-template></fo:block> + <xsl:choose> + <xsl:when test="glossaryinfo/subtitle"> + <xsl:apply-templates mode="glossary.titlepage.recto.auto.mode" select="glossaryinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="glossary.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="glossary.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="glossary.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="glossary.titlepage.verso"> +</xsl:template> + +<xsl:template name="glossary.titlepage.separator"> +</xsl:template> + +<xsl:template name="glossary.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="glossary.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="glossary.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="glossary.titlepage.before.recto"/> + <xsl:call-template name="glossary.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="glossary.titlepage.before.verso"/> + <xsl:call-template name="glossary.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="glossary.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="glossary.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="glossary.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="glossary.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="glossary.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="glossary.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="glossdiv.titlepage.recto"> + <xsl:choose> + <xsl:when test="glossdivinfo/title"> + <xsl:apply-templates mode="glossdiv.titlepage.recto.auto.mode" select="glossdivinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="glossdiv.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="glossdiv.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="glossdiv.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="glossdivinfo/subtitle"> + <xsl:apply-templates mode="glossdiv.titlepage.recto.auto.mode" select="glossdivinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="glossdiv.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="glossdiv.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="glossdiv.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="glossdiv.titlepage.verso"> +</xsl:template> + +<xsl:template name="glossdiv.titlepage.separator"> +</xsl:template> + +<xsl:template name="glossdiv.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="glossdiv.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="glossdiv.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="glossdiv.titlepage.before.recto"/> + <xsl:call-template name="glossdiv.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="glossdiv.titlepage.before.verso"/> + <xsl:call-template name="glossdiv.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="glossdiv.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="glossdiv.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="glossdiv.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="glossdiv.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="glossdiv.titlepage.recto.style" margin-left="{$title.margin.left}" font-size="20.736pt" font-family="{$title.fontset}" font-weight="bold"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::glossdiv[1]"/> +</xsl:call-template> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="glossdiv.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="glossdiv.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="glossdiv.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="index.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="index.titlepage.recto.style" margin-left="0pt" font-size="24.8832pt" font-family="{$title.fontset}" font-weight="bold"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::index[1]"/> +<xsl:with-param name="pagewide" select="1"/> +</xsl:call-template></fo:block> + <xsl:choose> + <xsl:when test="indexinfo/subtitle"> + <xsl:apply-templates mode="index.titlepage.recto.auto.mode" select="indexinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="index.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="index.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="index.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="index.titlepage.verso"> +</xsl:template> + +<xsl:template name="index.titlepage.separator"> +</xsl:template> + +<xsl:template name="index.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="index.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="index.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="index.titlepage.before.recto"/> + <xsl:call-template name="index.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="index.titlepage.before.verso"/> + <xsl:call-template name="index.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="index.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="index.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="index.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="index.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="index.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="index.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="indexdiv.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="indexdiv.titlepage.recto.style"> +<xsl:call-template name="indexdiv.title"> +<xsl:with-param name="title" select="title"/> +</xsl:call-template></fo:block> + <xsl:choose> + <xsl:when test="indexdivinfo/subtitle"> + <xsl:apply-templates mode="indexdiv.titlepage.recto.auto.mode" select="indexdivinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="indexdiv.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="indexdiv.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="indexdiv.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="indexdiv.titlepage.verso"> +</xsl:template> + +<xsl:template name="indexdiv.titlepage.separator"> +</xsl:template> + +<xsl:template name="indexdiv.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="indexdiv.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="indexdiv.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="indexdiv.titlepage.before.recto"/> + <xsl:call-template name="indexdiv.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="indexdiv.titlepage.before.verso"/> + <xsl:call-template name="indexdiv.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="indexdiv.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="indexdiv.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="indexdiv.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="indexdiv.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="indexdiv.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="indexdiv.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="setindex.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="setindex.titlepage.recto.style" margin-left="0pt" font-size="24.8832pt" font-family="{$title.fontset}" font-weight="bold"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::setindex[1]"/> +<xsl:with-param name="pagewide" select="1"/> +</xsl:call-template></fo:block> + <xsl:choose> + <xsl:when test="setindexinfo/subtitle"> + <xsl:apply-templates mode="setindex.titlepage.recto.auto.mode" select="setindexinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="setindex.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="setindex.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="setindex.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="setindex.titlepage.verso"> +</xsl:template> + +<xsl:template name="setindex.titlepage.separator"> +</xsl:template> + +<xsl:template name="setindex.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="setindex.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="setindex.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="setindex.titlepage.before.recto"/> + <xsl:call-template name="setindex.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="setindex.titlepage.before.verso"/> + <xsl:call-template name="setindex.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="setindex.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="setindex.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="setindex.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="setindex.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="setindex.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="setindex.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="colophon.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="colophon.titlepage.recto.style" margin-left="{$title.margin.left}" font-size="24.8832pt" font-family="{$title.fontset}" font-weight="bold"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::colophon[1]"/> +</xsl:call-template></fo:block> + <xsl:choose> + <xsl:when test="colophoninfo/subtitle"> + <xsl:apply-templates mode="colophon.titlepage.recto.auto.mode" select="colophoninfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="colophon.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="colophon.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="colophon.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="colophon.titlepage.verso"> +</xsl:template> + +<xsl:template name="colophon.titlepage.separator"> +</xsl:template> + +<xsl:template name="colophon.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="colophon.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="colophon.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="colophon.titlepage.before.recto"/> + <xsl:call-template name="colophon.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="colophon.titlepage.before.verso"/> + <xsl:call-template name="colophon.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="colophon.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="colophon.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="colophon.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="subtitle" mode="colophon.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="colophon.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="colophon.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="sidebar.titlepage.recto"> + <xsl:choose> + <xsl:when test="sidebarinfo/title"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="sidebarinfo/title"/> + </xsl:when> + <xsl:when test="docinfo/title"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="docinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="sidebarinfo/subtitle"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="sidebarinfo/subtitle"/> + </xsl:when> + <xsl:when test="docinfo/subtitle"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="docinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + +</xsl:template> + +<xsl:template name="sidebar.titlepage.verso"> +</xsl:template> + +<xsl:template name="sidebar.titlepage.separator"> +</xsl:template> + +<xsl:template name="sidebar.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="sidebar.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="sidebar.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="sidebar.titlepage.before.recto"/> + <xsl:call-template name="sidebar.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="sidebar.titlepage.before.verso"/> + <xsl:call-template name="sidebar.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="sidebar.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="sidebar.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="sidebar.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="sidebar.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sidebar.titlepage.recto.style" font-family="{$title.fontset}" font-weight="bold"> +<xsl:apply-templates select="." mode="sidebar.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="sidebar.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="sidebar.titlepage.recto.style" font-family="{$title.fontset}"> +<xsl:apply-templates select="." mode="sidebar.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="qandaset.titlepage.recto"> + <xsl:choose> + <xsl:when test="qandasetinfo/title"> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/title"/> + </xsl:when> + <xsl:when test="blockinfo/title"> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/title"/> + </xsl:when> + <xsl:when test="info/title"> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/title"/> + </xsl:when> + <xsl:when test="title"> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="title"/> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="qandasetinfo/subtitle"> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/subtitle"/> + </xsl:when> + <xsl:when test="blockinfo/subtitle"> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/subtitle"/> + </xsl:when> + <xsl:when test="info/subtitle"> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/subtitle"/> + </xsl:when> + <xsl:when test="subtitle"> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="subtitle"/> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/corpauthor"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/corpauthor"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/corpauthor"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/authorgroup"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/authorgroup"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/authorgroup"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/author"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/author"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/author"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/othercredit"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/othercredit"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/othercredit"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/releaseinfo"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/releaseinfo"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/releaseinfo"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/copyright"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/copyright"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/copyright"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/legalnotice"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/legalnotice"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/legalnotice"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/pubdate"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/pubdate"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/pubdate"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/revision"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/revision"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/revision"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/revhistory"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/revhistory"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/revhistory"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="qandasetinfo/abstract"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="blockinfo/abstract"/> + <xsl:apply-templates mode="qandaset.titlepage.recto.auto.mode" select="info/abstract"/> +</xsl:template> + +<xsl:template name="qandaset.titlepage.verso"> +</xsl:template> + +<xsl:template name="qandaset.titlepage.separator"> +</xsl:template> + +<xsl:template name="qandaset.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="qandaset.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="qandaset.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" font-family="{$title.fontset}"> + <xsl:variable name="recto.content"> + <xsl:call-template name="qandaset.titlepage.before.recto"/> + <xsl:call-template name="qandaset.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block start-indent="0pt" text-align="center"><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="qandaset.titlepage.before.verso"/> + <xsl:call-template name="qandaset.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="qandaset.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="qandaset.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="qandaset.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="title" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style" keep-with-next.within-column="always" font-size="24.8832pt" font-weight="bold"> +<xsl:call-template name="component.title"> +<xsl:with-param name="node" select="ancestor-or-self::qandaset[1]"/> +</xsl:call-template> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style"> +<xsl:apply-templates select="." mode="qandaset.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="corpauthor" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style" space-before="0.5em" font-size="14.4pt"> +<xsl:apply-templates select="." mode="qandaset.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="authorgroup" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style" space-before="0.5em" font-size="14.4pt"> +<xsl:apply-templates select="." mode="qandaset.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="author" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style" space-before="0.5em" font-size="14.4pt"> +<xsl:apply-templates select="." mode="qandaset.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="othercredit" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style" space-before="0.5em"> +<xsl:apply-templates select="." mode="qandaset.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="releaseinfo" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style" space-before="0.5em"> +<xsl:apply-templates select="." mode="qandaset.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="copyright" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style" space-before="0.5em"> +<xsl:apply-templates select="." mode="qandaset.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="legalnotice" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style" text-align="start" margin-left="0.5in" margin-right="0.5in" font-family="{$body.fontset}"> +<xsl:apply-templates select="." mode="qandaset.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="pubdate" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style" space-before="0.5em"> +<xsl:apply-templates select="." mode="qandaset.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revision" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style" space-before="0.5em"> +<xsl:apply-templates select="." mode="qandaset.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="revhistory" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style" space-before="0.5em"> +<xsl:apply-templates select="." mode="qandaset.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="abstract" mode="qandaset.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="qandaset.titlepage.recto.style" space-before="0.5em" text-align="start" margin-left="0.5in" margin-right="0.5in" font-family="{$body.fontset}"> +<xsl:apply-templates select="." mode="qandaset.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template name="table.of.contents.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="table.of.contents.titlepage.recto.style" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em" space-after="0.5em" margin-left="{$title.margin.left}" start-indent="0pt" font-size="17.28pt" font-weight="bold" font-family="{$title.fontset}"> +<xsl:call-template name="gentext"> +<xsl:with-param name="key" select="'TableofContents'"/> +</xsl:call-template></fo:block> +</xsl:template> + +<xsl:template name="table.of.contents.titlepage.verso"> +</xsl:template> + +<xsl:template name="table.of.contents.titlepage.separator"> +</xsl:template> + +<xsl:template name="table.of.contents.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="table.of.contents.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="table.of.contents.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="table.of.contents.titlepage.before.recto"/> + <xsl:call-template name="table.of.contents.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="table.of.contents.titlepage.before.verso"/> + <xsl:call-template name="table.of.contents.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="table.of.contents.titlepage.separator"/> + </fo:block> + +</xsl:template> + +<xsl:template match="*" mode="table.of.contents.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="table.of.contents.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template name="list.of.tables.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="list.of.tables.titlepage.recto.style" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em" space-after="0.5em" margin-left="{$title.margin.left}" start-indent="0pt" font-size="17.28pt" font-weight="bold" font-family="{$title.fontset}"> +<xsl:call-template name="gentext"> +<xsl:with-param name="key" select="'ListofTables'"/> +</xsl:call-template></fo:block> +</xsl:template> + +<xsl:template name="list.of.tables.titlepage.verso"> +</xsl:template> + +<xsl:template name="list.of.tables.titlepage.separator"> +</xsl:template> + +<xsl:template name="list.of.tables.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="list.of.tables.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="list.of.tables.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="list.of.tables.titlepage.before.recto"/> + <xsl:call-template name="list.of.tables.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="list.of.tables.titlepage.before.verso"/> + <xsl:call-template name="list.of.tables.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="list.of.tables.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="list.of.tables.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="list.of.tables.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template name="list.of.figures.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="list.of.figures.titlepage.recto.style" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em" space-after="0.5em" margin-left="{$title.margin.left}" start-indent="0pt" font-size="17.28pt" font-weight="bold" font-family="{$title.fontset}"> +<xsl:call-template name="gentext"> +<xsl:with-param name="key" select="'ListofFigures'"/> +</xsl:call-template></fo:block> +</xsl:template> + +<xsl:template name="list.of.figures.titlepage.verso"> +</xsl:template> + +<xsl:template name="list.of.figures.titlepage.separator"> +</xsl:template> + +<xsl:template name="list.of.figures.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="list.of.figures.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="list.of.figures.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="list.of.figures.titlepage.before.recto"/> + <xsl:call-template name="list.of.figures.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="list.of.figures.titlepage.before.verso"/> + <xsl:call-template name="list.of.figures.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="list.of.figures.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="list.of.figures.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="list.of.figures.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template name="list.of.examples.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="list.of.examples.titlepage.recto.style" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em" space-after="0.5em" margin-left="{$title.margin.left}" start-indent="0pt" font-size="17.28pt" font-weight="bold" font-family="{$title.fontset}"> +<xsl:call-template name="gentext"> +<xsl:with-param name="key" select="'ListofExamples'"/> +</xsl:call-template></fo:block> +</xsl:template> + +<xsl:template name="list.of.examples.titlepage.verso"> +</xsl:template> + +<xsl:template name="list.of.examples.titlepage.separator"> +</xsl:template> + +<xsl:template name="list.of.examples.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="list.of.examples.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="list.of.examples.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="list.of.examples.titlepage.before.recto"/> + <xsl:call-template name="list.of.examples.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="list.of.examples.titlepage.before.verso"/> + <xsl:call-template name="list.of.examples.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="list.of.examples.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="list.of.examples.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="list.of.examples.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template name="list.of.equations.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="list.of.equations.titlepage.recto.style" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em" space-after="0.5em" margin-left="{$title.margin.left}" start-indent="0pt" font-size="17.28pt" font-weight="bold" font-family="{$title.fontset}"> +<xsl:call-template name="gentext"> +<xsl:with-param name="key" select="'ListofEquations'"/> +</xsl:call-template></fo:block> +</xsl:template> + +<xsl:template name="list.of.equations.titlepage.verso"> +</xsl:template> + +<xsl:template name="list.of.equations.titlepage.separator"> +</xsl:template> + +<xsl:template name="list.of.equations.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="list.of.equations.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="list.of.equations.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="list.of.equations.titlepage.before.recto"/> + <xsl:call-template name="list.of.equations.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="list.of.equations.titlepage.before.verso"/> + <xsl:call-template name="list.of.equations.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="list.of.equations.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="list.of.equations.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="list.of.equations.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template name="list.of.procedures.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="list.of.procedures.titlepage.recto.style" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em" space-after="0.5em" margin-left="{$title.margin.left}" start-indent="0pt" font-size="17.28pt" font-weight="bold" font-family="{$title.fontset}"> +<xsl:call-template name="gentext"> +<xsl:with-param name="key" select="'ListofProcedures'"/> +</xsl:call-template></fo:block> +</xsl:template> + +<xsl:template name="list.of.procedures.titlepage.verso"> +</xsl:template> + +<xsl:template name="list.of.procedures.titlepage.separator"> +</xsl:template> + +<xsl:template name="list.of.procedures.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="list.of.procedures.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="list.of.procedures.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="list.of.procedures.titlepage.before.recto"/> + <xsl:call-template name="list.of.procedures.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="list.of.procedures.titlepage.before.verso"/> + <xsl:call-template name="list.of.procedures.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="list.of.procedures.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="list.of.procedures.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="list.of.procedures.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template name="list.of.unknowns.titlepage.recto"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="list.of.unknowns.titlepage.recto.style" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em" space-after="0.5em" margin-left="{$title.margin.left}" start-indent="0pt" font-size="17.28pt" font-weight="bold" font-family="{$title.fontset}"> +<xsl:call-template name="gentext"> +<xsl:with-param name="key" select="'ListofUnknown'"/> +</xsl:call-template></fo:block> +</xsl:template> + +<xsl:template name="list.of.unknowns.titlepage.verso"> +</xsl:template> + +<xsl:template name="list.of.unknowns.titlepage.separator"> +</xsl:template> + +<xsl:template name="list.of.unknowns.titlepage.before.recto"> +</xsl:template> + +<xsl:template name="list.of.unknowns.titlepage.before.verso"> +</xsl:template> + +<xsl:template name="list.of.unknowns.titlepage"> + <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> + <xsl:variable name="recto.content"> + <xsl:call-template name="list.of.unknowns.titlepage.before.recto"/> + <xsl:call-template name="list.of.unknowns.titlepage.recto"/> + </xsl:variable> + <xsl:variable name="recto.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count > 0)"> + <fo:block><xsl:copy-of select="$recto.content"/></fo:block> + </xsl:if> + <xsl:variable name="verso.content"> + <xsl:call-template name="list.of.unknowns.titlepage.before.verso"/> + <xsl:call-template name="list.of.unknowns.titlepage.verso"/> + </xsl:variable> + <xsl:variable name="verso.elements.count"> + <xsl:choose> + <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')"> + <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count > 0)"> + <fo:block><xsl:copy-of select="$verso.content"/></fo:block> + </xsl:if> + <xsl:call-template name="list.of.unknowns.titlepage.separator"/> + </fo:block> +</xsl:template> + +<xsl:template match="*" mode="list.of.unknowns.titlepage.recto.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + +<xsl:template match="*" mode="list.of.unknowns.titlepage.verso.mode"> + <!-- if an element isn't found in this mode, --> + <!-- try the generic titlepage.mode --> + <xsl:apply-templates select="." mode="titlepage.mode"/> +</xsl:template> + + +<!-- special titlepage masters for SCons Titlepage style in books --> +<xsl:template name="user.pagemasters"> + <!-- title pages --> + <fo:simple-page-master master-name="scons-titlepage-first" + page-width="{$page.width}" + page-height="{$page.height}" + margin-top="0mm" + margin-bottom="0mm" + margin-left="0mm" + margin-right="0mm"> + <xsl:attribute name="margin-{$direction.align.start}" select="0mm"/> + <xsl:attribute name="margin-{$direction.align.end}" select="0mm"/> + <xsl:if test="$axf.extensions != 0"> + <xsl:call-template name="axf-page-master-properties"> + <xsl:with-param name="page.master">scons-titlepage-first</xsl:with-param> + </xsl:call-template> + </xsl:if> + <fo:region-body margin-bottom="0mm" + margin-top="0mm" + column-gap="0mm" + column-count="{$column.count.titlepage}" + background-repeat="no-repeat" + background-image="url(titlepage/mapnik_final_colors.svg)" + background-position-vertical="center" + background-position-horizontal="center"> + </fo:region-body> + <fo:region-before region-name="xsl-region-before-first" + extent="{$region.before.extent}" + display-align="before"/> + <fo:region-after region-name="xsl-region-after-first" + extent="{$region.after.extent}" + display-align="after"/> + </fo:simple-page-master> + + <fo:simple-page-master master-name="scons-titlepage-odd" + page-width="{$page.width}" + page-height="{$page.height}" + margin-top="{$page.margin.top}" + margin-bottom="{$page.margin.bottom}"> + <xsl:attribute name="margin-{$direction.align.start}"> + <xsl:value-of select="$page.margin.outer"/> + <xsl:if test="$fop.extensions != 0"> + <xsl:value-of select="concat(' - (',$title.margin.left,')')"/> + </xsl:if> + </xsl:attribute> + <xsl:attribute name="margin-{$direction.align.end}"> + <xsl:value-of select="$page.margin.inner"/> + </xsl:attribute> + <xsl:if test="$axf.extensions != 0"> + <xsl:call-template name="axf-page-master-properties"> + <xsl:with-param name="page.master">scons-titlepage-odd</xsl:with-param> + </xsl:call-template> + </xsl:if> + <fo:region-body margin-bottom="{$body.margin.bottom}" + margin-top="{$body.margin.top}" + column-gap="{$column.gap.titlepage}" + column-count="{$column.count.titlepage}"> + </fo:region-body> + <fo:region-before region-name="xsl-region-before-odd" + extent="{$region.before.extent}" + display-align="before"/> + <fo:region-after region-name="xsl-region-after-odd" + extent="{$region.after.extent}" + display-align="after"/> + </fo:simple-page-master> + + <fo:simple-page-master master-name="scons-titlepage-even" + page-width="{$page.width}" + page-height="{$page.height}" + margin-top="{$page.margin.top}" + margin-bottom="{$page.margin.bottom}"> + <xsl:attribute name="margin-{$direction.align.start}"> + <xsl:value-of select="$page.margin.outer"/> + <xsl:if test="$fop.extensions != 0"> + <xsl:value-of select="concat(' - (',$title.margin.left,')')"/> + </xsl:if> + </xsl:attribute> + <xsl:attribute name="margin-{$direction.align.end}"> + <xsl:value-of select="$page.margin.inner"/> + </xsl:attribute> + <xsl:if test="$axf.extensions != 0"> + <xsl:call-template name="axf-page-master-properties"> + <xsl:with-param name="page.master">scons-titlepage-even</xsl:with-param> + </xsl:call-template> + </xsl:if> + <fo:region-body margin-bottom="{$body.margin.bottom}" + margin-top="{$body.margin.top}" + column-gap="{$column.gap.titlepage}" + column-count="{$column.count.titlepage}"> + </fo:region-body> + <fo:region-before region-name="xsl-region-before-even" + extent="{$region.before.extent}" + display-align="before"/> + <fo:region-after region-name="xsl-region-after-even" + extent="{$region.after.extent}" + display-align="after"/> + </fo:simple-page-master> + + <!-- chapter pages --> + <fo:simple-page-master master-name="scons-chapter-first" + page-width="{$page.width}" + page-height="{$page.height}" + margin-top="{$page.margin.top}" + margin-bottom="{$page.margin.bottom}"> + <xsl:attribute name="margin-{$direction.align.start}"> + <xsl:value-of select="$page.margin.outer"/> + <xsl:if test="$fop.extensions != 0"> + <xsl:value-of select="concat(' - (',$title.margin.left,')')"/> + </xsl:if> + </xsl:attribute> + <xsl:attribute name="margin-{$direction.align.end}"> + <xsl:value-of select="$page.margin.inner"/> + </xsl:attribute> + <xsl:if test="$axf.extensions != 0"> + <xsl:call-template name="axf-page-master-properties"> + <xsl:with-param name="page.master">scons-chapter-first</xsl:with-param> + </xsl:call-template> + </xsl:if> + <fo:region-body margin-bottom="{$body.margin.bottom}" + margin-top="{$body.margin.top}" + column-gap="{$column.gap.titlepage}" + column-count="{$column.count.titlepage}"> + </fo:region-body> + <fo:region-before region-name="xsl-region-before-first" + extent="{$region.before.extent}" + display-align="before"/> + <fo:region-after region-name="xsl-region-after-first" + extent="{$region.after.extent}" + display-align="after"/> + </fo:simple-page-master> + + <fo:simple-page-master master-name="scons-chapter-odd" + page-width="{$page.width}" + page-height="{$page.height}" + margin-top="{$page.margin.top}" + margin-bottom="{$page.margin.bottom}"> + <xsl:attribute name="margin-{$direction.align.start}"> + <xsl:value-of select="$page.margin.outer"/> + <xsl:if test="$fop.extensions != 0"> + <xsl:value-of select="concat(' - (',$title.margin.left,')')"/> + </xsl:if> + </xsl:attribute> + <xsl:attribute name="margin-{$direction.align.end}"> + <xsl:value-of select="$page.margin.inner"/> + </xsl:attribute> + <xsl:if test="$axf.extensions != 0"> + <xsl:call-template name="axf-page-master-properties"> + <xsl:with-param name="page.master">scons-chapter-odd</xsl:with-param> + </xsl:call-template> + </xsl:if> + <fo:region-body margin-bottom="{$body.margin.bottom}" + margin-top="{$body.margin.top}" + column-gap="{$column.gap.body}" + column-count="{$column.count.body}"> + </fo:region-body> + <fo:region-before region-name="xsl-region-before-odd" + extent="{$region.before.extent}" + display-align="before"/> + <fo:region-after region-name="xsl-region-after-odd" + extent="{$region.after.extent}" + display-align="after"/> + </fo:simple-page-master> + + <fo:simple-page-master master-name="scons-chapter-even" + page-width="{$page.width}" + page-height="{$page.height}" + margin-top="{$page.margin.top}" + margin-bottom="{$page.margin.bottom}"> + <xsl:attribute name="margin-{$direction.align.start}"> + <xsl:value-of select="$page.margin.outer"/> + <xsl:if test="$fop.extensions != 0"> + <xsl:value-of select="concat(' - (',$title.margin.left,')')"/> + </xsl:if> + </xsl:attribute> + <xsl:attribute name="margin-{$direction.align.end}"> + <xsl:value-of select="$page.margin.inner"/> + </xsl:attribute> + <xsl:if test="$axf.extensions != 0"> + <xsl:call-template name="axf-page-master-properties"> + <xsl:with-param name="page.master">scons-chapter-even</xsl:with-param> + </xsl:call-template> + </xsl:if> + <fo:region-body margin-bottom="{$body.margin.bottom}" + margin-top="{$body.margin.top}" + column-gap="{$column.gap.body}" + column-count="{$column.count.body}"> + </fo:region-body> + <fo:region-before region-name="xsl-region-before-even" + extent="{$region.before.extent}" + display-align="before"/> + <fo:region-after region-name="xsl-region-after-even" + extent="{$region.after.extent}" + display-align="after"/> + </fo:simple-page-master> + + <!-- definition of pagemasters for draft mode --> + <xsl:if test="$draft.mode != 'no'"> + <!-- draft title pages --> + <fo:simple-page-master master-name="scons-titlepage-first-draft" + page-width="{$page.width}" + page-height="{$page.height}" + margin-top="{$page.margin.top}" + margin-bottom="{$page.margin.bottom}"> + <xsl:attribute name="margin-{$direction.align.start}"> + <xsl:value-of select="$page.margin.outer"/> + <xsl:if test="$fop.extensions != 0"> + <xsl:value-of select="concat(' - (',$title.margin.left,')')"/> + </xsl:if> + </xsl:attribute> + <xsl:attribute name="margin-{$direction.align.end}"> + <xsl:value-of select="$page.margin.inner"/> + </xsl:attribute> + <xsl:if test="$axf.extensions != 0"> + <xsl:call-template name="axf-page-master-properties"> + <xsl:with-param name="page.master">scons-titlepage-first-draft</xsl:with-param> + </xsl:call-template> + </xsl:if> + <fo:region-body margin-bottom="{$body.margin.bottom}" + margin-top="{$body.margin.top}" + column-gap="{$column.gap.titlepage}" + column-count="{$column.count.titlepage}"> + <xsl:if test="$draft.watermark.image != ''"> + <xsl:attribute name="background-image"> + <xsl:call-template name="fo-external-image"> + <xsl:with-param name="filename" select="$draft.watermark.image"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="background-attachment">fixed</xsl:attribute> + <xsl:attribute name="background-repeat">no-repeat</xsl:attribute> + <xsl:attribute name="background-position-horizontal">center</xsl:attribute> + <xsl:attribute name="background-position-vertical">center</xsl:attribute> + </xsl:if> + </fo:region-body> + <fo:region-before region-name="xsl-region-before-first" + extent="{$region.before.extent}" + display-align="before"/> + <fo:region-after region-name="xsl-region-after-first" + extent="{$region.after.extent}" + display-align="after"/> + </fo:simple-page-master> + + <fo:simple-page-master master-name="scons-titlepage-odd-draft" + page-width="{$page.width}" + page-height="{$page.height}" + margin-top="{$page.margin.top}" + margin-bottom="{$page.margin.bottom}"> + <xsl:attribute name="margin-{$direction.align.start}"> + <xsl:value-of select="$page.margin.outer"/> + <xsl:if test="$fop.extensions != 0"> + <xsl:value-of select="concat(' - (',$title.margin.left,')')"/> + </xsl:if> + </xsl:attribute> + <xsl:attribute name="margin-{$direction.align.end}"> + <xsl:value-of select="$page.margin.inner"/> + </xsl:attribute> + <xsl:if test="$axf.extensions != 0"> + <xsl:call-template name="axf-page-master-properties"> + <xsl:with-param name="page.master">scons-titlepage-odd-draft</xsl:with-param> + </xsl:call-template> + </xsl:if> + <fo:region-body margin-bottom="{$body.margin.bottom}" + margin-top="{$body.margin.top}" + column-gap="{$column.gap.titlepage}" + column-count="{$column.count.titlepage}"> + <xsl:if test="$draft.watermark.image != ''"> + <xsl:attribute name="background-image"> + <xsl:call-template name="fo-external-image"> + <xsl:with-param name="filename" select="$draft.watermark.image"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="background-attachment">fixed</xsl:attribute> + <xsl:attribute name="background-repeat">no-repeat</xsl:attribute> + <xsl:attribute name="background-position-horizontal">center</xsl:attribute> + <xsl:attribute name="background-position-vertical">center</xsl:attribute> + </xsl:if> + </fo:region-body> + <fo:region-before region-name="xsl-region-before-odd" + extent="{$region.before.extent}" + display-align="before"/> + <fo:region-after region-name="xsl-region-after-odd" + extent="{$region.after.extent}" + display-align="after"/> + </fo:simple-page-master> + + <fo:simple-page-master master-name="scons-titlepage-even-draft" + page-width="{$page.width}" + page-height="{$page.height}" + margin-top="{$page.margin.top}" + margin-bottom="{$page.margin.bottom}"> + <xsl:attribute name="margin-{$direction.align.start}"> + <xsl:value-of select="$page.margin.outer"/> + <xsl:if test="$fop.extensions != 0"> + <xsl:value-of select="concat(' - (',$title.margin.left,')')"/> + </xsl:if> + </xsl:attribute> + <xsl:attribute name="margin-{$direction.align.end}"> + <xsl:value-of select="$page.margin.inner"/> + </xsl:attribute> + <xsl:if test="$axf.extensions != 0"> + <xsl:call-template name="axf-page-master-properties"> + <xsl:with-param name="page.master">scons-titlepage-even-draft</xsl:with-param> + </xsl:call-template> + </xsl:if> + <fo:region-body margin-bottom="{$body.margin.bottom}" + margin-top="{$body.margin.top}" + column-gap="{$column.gap.titlepage}" + column-count="{$column.count.titlepage}"> + <xsl:if test="$draft.watermark.image != ''"> + <xsl:attribute name="background-image"> + <xsl:call-template name="fo-external-image"> + <xsl:with-param name="filename" select="$draft.watermark.image"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="background-attachment">fixed</xsl:attribute> + <xsl:attribute name="background-repeat">no-repeat</xsl:attribute> + <xsl:attribute name="background-position-horizontal">center</xsl:attribute> + <xsl:attribute name="background-position-vertical">center</xsl:attribute> + </xsl:if> + </fo:region-body> + <fo:region-before region-name="xsl-region-before-even" + extent="{$region.before.extent}" + display-align="before"/> + <fo:region-after region-name="xsl-region-after-even" + extent="{$region.after.extent}" + display-align="after"/> + </fo:simple-page-master> + + <!-- draft chapter pages --> + <fo:simple-page-master master-name="scons-chapter-first-draft" + page-width="{$page.width}" + page-height="{$page.height}" + margin-top="{$page.margin.top}" + margin-bottom="{$page.margin.bottom}"> + <xsl:attribute name="margin-{$direction.align.start}"> + <xsl:value-of select="$page.margin.outer"/> + <xsl:if test="$fop.extensions != 0"> + <xsl:value-of select="concat(' - (',$title.margin.left,')')"/> + </xsl:if> + </xsl:attribute> + <xsl:attribute name="margin-{$direction.align.end}"> + <xsl:value-of select="$page.margin.inner"/> + </xsl:attribute> + <xsl:if test="$axf.extensions != 0"> + <xsl:call-template name="axf-page-master-properties"> + <xsl:with-param name="page.master">scons-chapter-first-draft</xsl:with-param> + </xsl:call-template> + </xsl:if> + <fo:region-body margin-bottom="{$body.margin.bottom}" + margin-top="{$body.margin.top}" + column-gap="{$column.gap.titlepage}" + column-count="{$column.count.titlepage}"> + <xsl:if test="$draft.watermark.image != ''"> + <xsl:attribute name="background-image"> + <xsl:call-template name="fo-external-image"> + <xsl:with-param name="filename" select="$draft.watermark.image"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="background-attachment">fixed</xsl:attribute> + <xsl:attribute name="background-repeat">no-repeat</xsl:attribute> + <xsl:attribute name="background-position-horizontal">center</xsl:attribute> + <xsl:attribute name="background-position-vertical">center</xsl:attribute> + </xsl:if> + </fo:region-body> + <fo:region-before region-name="xsl-region-before-first" + extent="{$region.before.extent}" + display-align="before"/> + <fo:region-after region-name="xsl-region-after-first" + extent="{$region.after.extent}" + display-align="after"/> + </fo:simple-page-master> + + <fo:simple-page-master master-name="scons-chapter-odd-draft" + page-width="{$page.width}" + page-height="{$page.height}" + margin-top="{$page.margin.top}" + margin-bottom="{$page.margin.bottom}"> + <xsl:attribute name="margin-{$direction.align.start}"> + <xsl:value-of select="$page.margin.outer"/> + <xsl:if test="$fop.extensions != 0"> + <xsl:value-of select="concat(' - (',$title.margin.left,')')"/> + </xsl:if> + </xsl:attribute> + <xsl:attribute name="margin-{$direction.align.end}"> + <xsl:value-of select="$page.margin.inner"/> + </xsl:attribute> + <xsl:if test="$axf.extensions != 0"> + <xsl:call-template name="axf-page-master-properties"> + <xsl:with-param name="page.master">scons-chapter-odd-draft</xsl:with-param> + </xsl:call-template> + </xsl:if> + <fo:region-body margin-bottom="{$body.margin.bottom}" + margin-top="{$body.margin.top}" + column-gap="{$column.gap.body}" + column-count="{$column.count.body}"> + <xsl:if test="$draft.watermark.image != ''"> + <xsl:attribute name="background-image"> + <xsl:call-template name="fo-external-image"> + <xsl:with-param name="filename" select="$draft.watermark.image"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="background-attachment">fixed</xsl:attribute> + <xsl:attribute name="background-repeat">no-repeat</xsl:attribute> + <xsl:attribute name="background-position-horizontal">center</xsl:attribute> + <xsl:attribute name="background-position-vertical">center</xsl:attribute> + </xsl:if> + </fo:region-body> + <fo:region-before region-name="xsl-region-before-odd" + extent="{$region.before.extent}" + display-align="before"/> + <fo:region-after region-name="xsl-region-after-odd" + extent="{$region.after.extent}" + display-align="after"/> + </fo:simple-page-master> + + <fo:simple-page-master master-name="scons-chapter-even-draft" + page-width="{$page.width}" + page-height="{$page.height}" + margin-top="{$page.margin.top}" + margin-bottom="{$page.margin.bottom}"> + <xsl:attribute name="margin-{$direction.align.start}"> + <xsl:value-of select="$page.margin.outer"/> + <xsl:if test="$fop.extensions != 0"> + <xsl:value-of select="concat(' - (',$title.margin.left,')')"/> + </xsl:if> + </xsl:attribute> + <xsl:attribute name="margin-{$direction.align.end}"> + <xsl:value-of select="$page.margin.inner"/> + </xsl:attribute> + <xsl:if test="$axf.extensions != 0"> + <xsl:call-template name="axf-page-master-properties"> + <xsl:with-param name="page.master">scons-chapter-even-draft</xsl:with-param> + </xsl:call-template> + </xsl:if> + <fo:region-body margin-bottom="{$body.margin.bottom}" + margin-top="{$body.margin.top}" + column-gap="{$column.gap.body}" + column-count="{$column.count.body}"> + <xsl:if test="$draft.watermark.image != ''"> + <xsl:attribute name="background-image"> + <xsl:call-template name="fo-external-image"> + <xsl:with-param name="filename" select="$draft.watermark.image"/> + </xsl:call-template> + </xsl:attribute> + <xsl:attribute name="background-attachment">fixed</xsl:attribute> + <xsl:attribute name="background-repeat">no-repeat</xsl:attribute> + <xsl:attribute name="background-position-horizontal">center</xsl:attribute> + <xsl:attribute name="background-position-vertical">center</xsl:attribute> + </xsl:if> + </fo:region-body> + <fo:region-before region-name="xsl-region-before-even" + extent="{$region.before.extent}" + display-align="before"/> + <fo:region-after region-name="xsl-region-after-even" + extent="{$region.after.extent}" + display-align="after"/> + </fo:simple-page-master> + </xsl:if> + + <!-- setup for title page(s) --> + <fo:page-sequence-master master-name="scons-titlepage"> + <fo:repeatable-page-master-alternatives> + <fo:conditional-page-master-reference master-reference="scons-titlepage-first" + page-position="first"/> + <fo:conditional-page-master-reference master-reference="scons-titlepage-odd" + odd-or-even="odd"/> + <fo:conditional-page-master-reference + odd-or-even="even"> + <xsl:attribute name="master-reference"> + <xsl:choose> + <xsl:when test="$double.sided != 0">scons-titlepage-even</xsl:when> + <xsl:otherwise>scons-titlepage-odd</xsl:otherwise> + </xsl:choose> + </xsl:attribute> + </fo:conditional-page-master-reference> + </fo:repeatable-page-master-alternatives> + </fo:page-sequence-master> + + <!-- definition of pagemasters for draft mode --> + <xsl:if test="$draft.mode != 'no'"> + <!-- draft title pages --> + + <fo:page-sequence-master master-name="scons-titlepage-draft"> + <fo:repeatable-page-master-alternatives> + <fo:conditional-page-master-reference master-reference="scons-titlepage-first-draft" + page-position="first"/> + <fo:conditional-page-master-reference master-reference="body-odd-draft" + odd-or-even="odd"/> + <fo:conditional-page-master-reference + odd-or-even="even"> + <xsl:attribute name="master-reference"> + <xsl:choose> + <xsl:when test="$double.sided != 0">body-even-draft</xsl:when> + <xsl:otherwise>body-odd-draft</xsl:otherwise> + </xsl:choose> + </xsl:attribute> + </fo:conditional-page-master-reference> + </fo:repeatable-page-master-alternatives> + </fo:page-sequence-master> + </xsl:if> + + <!-- setup for chapter pages --> + <fo:page-sequence-master master-name="scons-chapter"> + <fo:repeatable-page-master-alternatives> + <fo:conditional-page-master-reference master-reference="scons-chapter-first" + page-position="first"/> + <fo:conditional-page-master-reference master-reference="scons-chapter-odd" + odd-or-even="odd"/> + <fo:conditional-page-master-reference + odd-or-even="even"> + <xsl:attribute name="master-reference"> + <xsl:choose> + <xsl:when test="$double.sided != 0">scons-chapter-even</xsl:when> + <xsl:otherwise>scons-chapter-odd</xsl:otherwise> + </xsl:choose> + </xsl:attribute> + </fo:conditional-page-master-reference> + </fo:repeatable-page-master-alternatives> + </fo:page-sequence-master> + <!-- setup for draft chapter pages --> + <xsl:if test="$draft.mode != 'no'"> + <!-- draft chapter pages --> + <fo:page-sequence-master master-name="scons-chapter-draft"> + <fo:repeatable-page-master-alternatives> + <fo:conditional-page-master-reference master-reference="scons-chapter-first-draft" + page-position="first"/> + <fo:conditional-page-master-reference master-reference="scons-chapter-odd-draft" + odd-or-even="odd"/> + <fo:conditional-page-master-reference + odd-or-even="even"> + <xsl:attribute name="master-reference"> + <xsl:choose> + <xsl:when test="$double.sided != 0">scons-chapter-even-draft</xsl:when> + <xsl:otherwise>scons-chapter-odd-draft</xsl:otherwise> + </xsl:choose> + </xsl:attribute> + </fo:conditional-page-master-reference> + </fo:repeatable-page-master-alternatives> + </fo:page-sequence-master> + </xsl:if> + +</xsl:template> + +<!-- selecting our SCons pagemasters --> +<xsl:template name="select.user.pagemaster"> + <xsl:param name="element"/> + <xsl:param name="pageclass"/> + <xsl:param name="default-pagemaster"/> + + <xsl:choose> + <xsl:when test="$default-pagemaster = 'titlepage'"> + <xsl:value-of select="'scons-titlepage'" /> + </xsl:when> + <xsl:when test="$element = 'chapter' and + $default-pagemaster = 'body-draft'"> + <xsl:value-of select="'scons-chapter-draft'" /> + </xsl:when> + <xsl:when test="$element = 'chapter'"> + <xsl:value-of select="'scons-chapter'" /> + </xsl:when> + <xsl:when test="$default-pagemaster = 'titlepage-draft'"> + <xsl:value-of select="'scons-titlepage-draft'" /> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$default-pagemaster"/> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + + + +<xsl:template match="title" mode="book.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" text-align="left" display-align="after" color="#C51410" font-size="75pt" space-before="0pt" space-after="0pt" font-weight="bold" font-family="'serif'"> +<xsl:call-template name="division.title"> +<xsl:with-param name="node" select="ancestor-or-self::book[1]"/> +</xsl:call-template> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="book.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" text-align="left" display-align="after" font-size="28pt" space-before="0pt" space-after="0pt" font-family="{$title.fontset}" font-weight="normal"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="edition" mode="book.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" text-align="left" display-align="after" color="#C51410" font-size="56pt" space-before="0pt" space-after="0pt" font-family="'serif'" font-weight="normal"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + + +<xsl:attribute-set name="chap.label.properties"> + <xsl:attribute name="font-family"> + <xsl:value-of select="$title.fontset"/> + </xsl:attribute> + <xsl:attribute name="font-weight">bold</xsl:attribute> + <xsl:attribute name="color">#C51410</xsl:attribute> + <xsl:attribute name="keep-with-next.within-column">always</xsl:attribute> + <xsl:attribute name="text-align">center</xsl:attribute> + <xsl:attribute name="display-align">after</xsl:attribute> + <xsl:attribute name="space-before">0pt</xsl:attribute> + <xsl:attribute name="space-after">0pt</xsl:attribute> +</xsl:attribute-set> + +<xsl:attribute-set name="chap.title.properties"> + <xsl:attribute name="font-family"> + <xsl:value-of select="$title.fontset"/> + </xsl:attribute> + <xsl:attribute name="font-size">24pt</xsl:attribute> + <xsl:attribute name="color">#C51410</xsl:attribute> + <xsl:attribute name="font-weight">bold</xsl:attribute> + <xsl:attribute name="keep-with-next.within-column">always</xsl:attribute> + <xsl:attribute name="text-align">left</xsl:attribute> + <xsl:attribute name="display-align">after</xsl:attribute> + <xsl:attribute name="space-before">0pt</xsl:attribute> + <xsl:attribute name="space-after">0pt</xsl:attribute> + <xsl:attribute name="space-start">0.7em</xsl:attribute> +</xsl:attribute-set> + + +<!-- customization of chapter titles --> +<xsl:template name="chap.title"> + <xsl:param name="node" select="."/> + <xsl:param name="pagewide" select="0"/> + + <xsl:variable name="id"> + <xsl:call-template name="object.id"> + <xsl:with-param name="object" select="$node"/> + </xsl:call-template> + </xsl:variable> + + <xsl:variable name="title"> + <xsl:apply-templates select="$node" mode="object.title.markup"> + <xsl:with-param name="allow-anchors" select="1"/> + </xsl:apply-templates> + </xsl:variable> + + <xsl:variable name="titleabbrev"> + <xsl:apply-templates select="$node" mode="titleabbrev.markup"/> + </xsl:variable> + + <xsl:variable name="level"> + <xsl:choose> + <xsl:when test="ancestor::section"> + <xsl:value-of select="count(ancestor::section)+1"/> + </xsl:when> + <xsl:when test="ancestor::sect5">6</xsl:when> + <xsl:when test="ancestor::sect4">5</xsl:when> + <xsl:when test="ancestor::sect3">4</xsl:when> + <xsl:when test="ancestor::sect2">3</xsl:when> + <xsl:when test="ancestor::sect1">2</xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:if test="$passivetex.extensions != 0"> + <fotex:bookmark xmlns:fotex="http://www.tug.org/fotex" + fotex-bookmark-level="2" + fotex-bookmark-label="{$id}"> + <xsl:value-of select="$titleabbrev"/> + </fotex:bookmark> + </xsl:if> + + <fo:table table-layout="fixed" width="100%" border-width="0pt" border-style="none"> + + <fo:table-column column-width="17mm"/> + <fo:table-column/> + <fo:table-column column-width="17mm"/> + + <fo:table-body> + <fo:table-row text-align="center"> + <fo:table-cell> + <fo:block></fo:block> + </fo:table-cell> + <fo:table-cell xsl:use-attribute-sets="chap.title.properties"> + <fo:block> + + <fo:inline xsl:use-attribute-sets="chap.label.properties" font-size="57pt"><xsl:apply-templates select="$node" + mode="label.markup"/></fo:inline> + + <fo:inline xsl:use-attribute-sets="chap.title.properties"><xsl:apply-templates select="$node" + mode="title.markup"/></fo:inline> + </fo:block> + </fo:table-cell> + <fo:table-cell> + <fo:block></fo:block> + </fo:table-cell> + </fo:table-row> + </fo:table-body> + </fo:table> +</xsl:template> + +<xsl:template match="title" mode="chapter.titlepage.recto.auto.mode"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"> +<xsl:call-template name="chap.title"> +<xsl:with-param name="node" select="ancestor-or-self::chapter[1]"/> +</xsl:call-template> +</fo:block> +</xsl:template> + + +<xsl:template match="title" mode="header.content"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" space-before="0pt" space-after="0pt"> +<xsl:apply-templates select="."/> +</fo:block> +</xsl:template> + +<xsl:template match="subtitle" mode="header.content"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" space-before="0pt" space-after="0pt"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + +<xsl:template match="edition" mode="header.content"> +<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" space-before="0pt" space-after="0pt"> +<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/> +</fo:block> +</xsl:template> + + +<xsl:template name="header.table"> + <xsl:param name="pageclass" select="''"/> + <xsl:param name="sequence" select="''"/> + <xsl:param name="element" select="''"/> + <xsl:param name="gentext-key" select="''"/> + + <!-- default is a single table style for all headers --> + <!-- Customize it for different page classes or sequence location --> + + <xsl:choose> + <xsl:when test="$pageclass = 'index'"> + <xsl:attribute name="margin-left">0pt</xsl:attribute> + </xsl:when> + </xsl:choose> + + <xsl:variable name="column1"> + <xsl:choose> + <xsl:when test="$double.sided = 0">1</xsl:when> + <xsl:when test="$sequence = 'first' or $sequence = 'odd'">1</xsl:when> + <xsl:otherwise>3</xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:variable name="column3"> + <xsl:choose> + <xsl:when test="$double.sided = 0">3</xsl:when> + <xsl:when test="$sequence = 'first' or $sequence = 'odd'">3</xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:variable name="candidate"> + <fo:table table-layout="fixed" width="100%"> + <xsl:call-template name="head.sep.rule"> + <xsl:with-param name="pageclass" select="$pageclass"/> + <xsl:with-param name="sequence" select="$sequence"/> + <xsl:with-param name="gentext-key" select="$gentext-key"/> + </xsl:call-template> + + <fo:table-column column-number="1"> + <xsl:attribute name="column-width"> + <xsl:text>proportional-column-width(</xsl:text> + <xsl:call-template name="header.footer.width"> + <xsl:with-param name="location">header</xsl:with-param> + <xsl:with-param name="position" select="$column1"/> + </xsl:call-template> + <xsl:text>)</xsl:text> + </xsl:attribute> + </fo:table-column> + <fo:table-column column-number="2"> + <xsl:attribute name="column-width"> + <xsl:text>proportional-column-width(</xsl:text> + <xsl:call-template name="header.footer.width"> + <xsl:with-param name="location">header</xsl:with-param> + <xsl:with-param name="position" select="2"/> + </xsl:call-template> + <xsl:text>)</xsl:text> + </xsl:attribute> + </fo:table-column> + <fo:table-column column-number="3"> + <xsl:attribute name="column-width"> + <xsl:text>proportional-column-width(</xsl:text> + <xsl:call-template name="header.footer.width"> + <xsl:with-param name="location">header</xsl:with-param> + <xsl:with-param name="position" select="$column3"/> + </xsl:call-template> + <xsl:text>)</xsl:text> + </xsl:attribute> + </fo:table-column> + + <fo:table-body> + <fo:table-row> + <xsl:attribute name="block-progression-dimension.minimum"> + <xsl:value-of select="$header.table.height"/> + </xsl:attribute> + <fo:table-cell text-align="left" + display-align="before"> + <xsl:if test="$fop.extensions = 0"> + <xsl:attribute name="relative-align">baseline</xsl:attribute> + </xsl:if> + <fo:block> + <xsl:call-template name="header.content"> + <xsl:with-param name="pageclass" select="$pageclass"/> + <xsl:with-param name="sequence" select="$sequence"/> + <xsl:with-param name="position" select="'left'"/> + <xsl:with-param name="gentext-key" select="$gentext-key"/> + </xsl:call-template> + </fo:block> + </fo:table-cell> + <fo:table-cell text-align="center" + display-align="before"> + <xsl:if test="$fop.extensions = 0"> + <xsl:attribute name="relative-align">baseline</xsl:attribute> + </xsl:if> + <fo:block> + <xsl:call-template name="header.content"> + <xsl:with-param name="pageclass" select="$pageclass"/> + <xsl:with-param name="sequence" select="$sequence"/> + <xsl:with-param name="position" select="'center'"/> + <xsl:with-param name="gentext-key" select="$gentext-key"/> + </xsl:call-template> + </fo:block> + </fo:table-cell> + <fo:table-cell text-align="right" + display-align="before"> + <xsl:if test="$fop.extensions = 0"> + <xsl:attribute name="relative-align">baseline</xsl:attribute> + </xsl:if> + <fo:block> + <xsl:call-template name="header.content"> + <xsl:with-param name="pageclass" select="$pageclass"/> + <xsl:with-param name="sequence" select="$sequence"/> + <xsl:with-param name="position" select="'right'"/> + <xsl:with-param name="gentext-key" select="$gentext-key"/> + </xsl:call-template> + </fo:block> + </fo:table-cell> + </fo:table-row> + </fo:table-body> + </fo:table> + </xsl:variable> + + <!-- Really output a header? --> + <xsl:choose> + <xsl:when test="$pageclass = 'titlepage' and $gentext-key = 'book' + and $sequence='first'"> + <!-- no, book titlepages have no headers at all --> + </xsl:when> + <xsl:when test="$pageclass = 'scons-titlepage'"> + <!-- no, book titlepages have no headers at all --> + </xsl:when> + <xsl:when test="$pageclass = 'scons-chapter' and + $sequence = 'first'"> + <!-- no, book chapters have no headers at all --> + </xsl:when> + <xsl:when test="$sequence = 'blank' and $headers.on.blank.pages = 0"> + <!-- no output --> + </xsl:when> + <xsl:otherwise> + <xsl:copy-of select="$candidate"/> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + + +<xsl:template name="header.content"> + <xsl:param name="pageclass" select="''"/> + <xsl:param name="sequence" select="''"/> + <xsl:param name="position" select="''"/> + <xsl:param name="gentext-key" select="''"/> + + <fo:block> + + <!-- sequence can be odd, even, first, blank --> + <!-- position can be left, center, right --> + <xsl:choose> + + <xsl:when test="$pageclass = 'titlepage'"> + <!-- nop; no footer on title pages --> + </xsl:when> + + <xsl:when test="$double.sided != 0 and $sequence = 'even' + and $position='left'"> + <fo:retrieve-marker + retrieve-class-name="section.head.marker" + retrieve-position="first-including-carryover" + retrieve-boundary="page-sequence"/> + </xsl:when> + + <xsl:when test="$double.sided != 0 and + ($sequence = 'odd' or $sequence = 'first' or $sequence = 'blank') + and $position='right'"> + <fo:retrieve-marker + retrieve-class-name="section.head.marker" + retrieve-position="first-including-carryover" + retrieve-boundary="page-sequence"/> + </xsl:when> + + <xsl:when test="$double.sided != 0 and + ($sequence = 'odd' or $sequence = 'first' or $sequence = 'blank') + and $position='left'"> + <xsl:value-of select="/book/title"/> + </xsl:when> + + <xsl:when test="$double.sided != 0 and $sequence = 'even' + and $position='right'"> + <xsl:value-of select="/book/title"/> + </xsl:when> + + + <xsl:when test="$double.sided = 0 and $sequence = 'even' + and $position='right'"> + <xsl:value-of select="/book/title"/> + </xsl:when> + + <xsl:when test="$double.sided = 0 and $sequence = 'even' + and $position='left'"> + <xsl:value-of select="/book/title"/> + </xsl:when> + + <xsl:when test="$double.sided = 0 and ($sequence = 'odd' or $sequence = 'first') + and $position='right'"> + <fo:retrieve-marker + retrieve-class-name="section.head.marker" + retrieve-position="first-including-carryover" + retrieve-boundary="page-sequence"/> + </xsl:when> + + <xsl:when test="$double.sided = 0 and ($sequence = 'odd' or $sequence = 'first') + and $position='left'"> + <xsl:value-of select="/book/title"/> + </xsl:when> + + <xsl:when test="$double.sided = 0 and $sequence = 'even' + and $position='right'"> + <fo:retrieve-marker + retrieve-class-name="section.head.marker" + retrieve-position="first-including-carryover" + retrieve-boundary="page-sequence"/> + </xsl:when> + + + <xsl:when test="$position='center'"> +<!-- <xsl:apply-templates select="." + mode="titleabbrev.markup"/> +--> + </xsl:when> + + <xsl:when test="$sequence='blank'"> + <!-- nop --> + </xsl:when> + + <xsl:otherwise> + <!-- nop --> + </xsl:otherwise> + + </xsl:choose> + </fo:block> +</xsl:template> + + +<xsl:template name="footer.table"> + <xsl:param name="pageclass" select="''"/> + <xsl:param name="sequence" select="''"/> + <xsl:param name="gentext-key" select="''"/> + + <!-- default is a single table style for all footers --> + <!-- Customize it for different page classes or sequence location --> + + <xsl:choose> + <xsl:when test="$pageclass = 'index'"> + <xsl:attribute name="margin-left">0pt</xsl:attribute> + </xsl:when> + </xsl:choose> + + <xsl:variable name="column1"> + <xsl:choose> + <xsl:when test="$double.sided = 0">1</xsl:when> + <xsl:when test="$sequence = 'first' or $sequence = 'odd'">1</xsl:when> + <xsl:otherwise>3</xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:variable name="column3"> + <xsl:choose> + <xsl:when test="$double.sided = 0">3</xsl:when> + <xsl:when test="$sequence = 'first' or $sequence = 'odd'">3</xsl:when> + <xsl:otherwise>1</xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:variable name="candidate"> + <fo:table table-layout="fixed" width="100%"> + <xsl:call-template name="foot.sep.rule"> + <xsl:with-param name="pageclass" select="$pageclass"/> + <xsl:with-param name="sequence" select="$sequence"/> + <xsl:with-param name="gentext-key" select="$gentext-key"/> + </xsl:call-template> + <fo:table-column column-number="1"> + <xsl:attribute name="column-width"> + <xsl:text>proportional-column-width(</xsl:text> + <xsl:call-template name="header.footer.width"> + <xsl:with-param name="location">footer</xsl:with-param> + <xsl:with-param name="position" select="$column1"/> + </xsl:call-template> + <xsl:text>)</xsl:text> + </xsl:attribute> + </fo:table-column> + <fo:table-column column-number="2"> + <xsl:attribute name="column-width"> + <xsl:text>proportional-column-width(</xsl:text> + <xsl:call-template name="header.footer.width"> + <xsl:with-param name="location">footer</xsl:with-param> + <xsl:with-param name="position" select="2"/> + </xsl:call-template> + <xsl:text>)</xsl:text> + </xsl:attribute> + </fo:table-column> + <fo:table-column column-number="3"> + <xsl:attribute name="column-width"> + <xsl:text>proportional-column-width(</xsl:text> + <xsl:call-template name="header.footer.width"> + <xsl:with-param name="location">footer</xsl:with-param> + <xsl:with-param name="position" select="$column3"/> + </xsl:call-template> + <xsl:text>)</xsl:text> + </xsl:attribute> + </fo:table-column> + + <fo:table-body> + <fo:table-row> + <xsl:attribute name="block-progression-dimension.minimum"> + <xsl:value-of select="$footer.table.height"/> + </xsl:attribute> + <fo:table-cell text-align="left" + display-align="after"> + <xsl:if test="$fop.extensions = 0"> + <xsl:attribute name="relative-align">baseline</xsl:attribute> + </xsl:if> + <fo:block> + <xsl:call-template name="footer.content"> + <xsl:with-param name="pageclass" select="$pageclass"/> + <xsl:with-param name="sequence" select="$sequence"/> + <xsl:with-param name="position" select="'left'"/> + <xsl:with-param name="gentext-key" select="$gentext-key"/> + </xsl:call-template> + </fo:block> + </fo:table-cell> + <fo:table-cell text-align="center" + display-align="after"> + <xsl:if test="$fop.extensions = 0"> + <xsl:attribute name="relative-align">baseline</xsl:attribute> + </xsl:if> + <fo:block> + <xsl:call-template name="footer.content"> + <xsl:with-param name="pageclass" select="$pageclass"/> + <xsl:with-param name="sequence" select="$sequence"/> + <xsl:with-param name="position" select="'center'"/> + <xsl:with-param name="gentext-key" select="$gentext-key"/> + </xsl:call-template> + </fo:block> + </fo:table-cell> + <fo:table-cell text-align="right" + display-align="after"> + <xsl:if test="$fop.extensions = 0"> + <xsl:attribute name="relative-align">baseline</xsl:attribute> + </xsl:if> + <fo:block> + <xsl:call-template name="footer.content"> + <xsl:with-param name="pageclass" select="$pageclass"/> + <xsl:with-param name="sequence" select="$sequence"/> + <xsl:with-param name="position" select="'right'"/> + <xsl:with-param name="gentext-key" select="$gentext-key"/> + </xsl:call-template> + </fo:block> + </fo:table-cell> + </fo:table-row> + </fo:table-body> + </fo:table> + </xsl:variable> + + <!-- Really output a footer? --> + <xsl:choose> + <xsl:when test="$pageclass='titlepage' and $gentext-key='book' + and $sequence='first'"> + <!-- no, book titlepages have no footers at all --> + </xsl:when> + <xsl:when test="$pageclass = 'scons-titlepage'"> + <!-- no, book titlepages have no footers at all --> + </xsl:when> + <xsl:when test="$pageclass = 'scons-chapter' and + $sequence='first'"> + <!-- no, book chapters have no footers on first page --> + </xsl:when> + <xsl:when test="$sequence = 'blank' and $footers.on.blank.pages = 0"> + <!-- no output --> + </xsl:when> + <xsl:otherwise> + <xsl:copy-of select="$candidate"/> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + + +<xsl:template name="footer.content"> + <xsl:param name="pageclass" select="''"/> + <xsl:param name="sequence" select="''"/> + <xsl:param name="position" select="''"/> + <xsl:param name="gentext-key" select="''"/> + + <fo:block> + <!-- pageclass can be front, body, back --> + <!-- sequence can be odd, even, first, blank --> + <!-- position can be left, center, right --> + <xsl:choose> + <xsl:when test="$pageclass = 'titlepage'"> + <!-- nop; no footer on title pages --> + </xsl:when> + + <xsl:when test="$double.sided != 0 and $sequence = 'even' + and $position='left'"> + <fo:page-number/> + </xsl:when> + + <xsl:when test="$double.sided != 0 and + ($sequence = 'odd' or $sequence = 'first' or $sequence = 'blank') + and $position='right'"> + <fo:page-number/> + </xsl:when> + + <xsl:when test="$double.sided != 0 and + ($sequence = 'odd' or $sequence = 'first' or $sequence = 'blank') + and $position='left'"> + <fo:external-graphic + src="url(titlepage/SCons_path.svg)" + width="20mm" content-width="scale-to-fit" + scaling="uniform"/> + </xsl:when> + + <xsl:when test="$double.sided != 0 and $sequence = 'even' + and $position='right'"> + <fo:external-graphic + src="url(titlepage/SCons_path.svg)" + width="20mm" content-width="scale-to-fit" + scaling="uniform"/> + </xsl:when> + + + <xsl:when test="$double.sided = 0 and $sequence = 'even' + and $position='right'"> + <fo:external-graphic + src="url(titlepage/SCons_path.svg)" + width="20mm" content-width="scale-to-fit" + scaling="uniform"/> + </xsl:when> + + <xsl:when test="$double.sided = 0 and $sequence = 'even' + and $position='left'"> + <fo:external-graphic + src="url(titlepage/SCons_path.svg)" + width="20mm" content-width="scale-to-fit" + scaling="uniform"/> + </xsl:when> + + <xsl:when test="$double.sided = 0 and ($sequence = 'odd' or $sequence = 'first') + and $position='right'"> + <fo:page-number/> + </xsl:when> + + <xsl:when test="$double.sided = 0 and ($sequence = 'odd' or $sequence = 'first') + and $position='left'"> + <fo:external-graphic + src="url(titlepage/SCons_path.svg)" + width="20mm" content-width="scale-to-fit" + scaling="uniform"/> + </xsl:when> + + <xsl:when test="$double.sided = 0 and $sequence = 'even' + and $position='right'"> + <fo:page-number/> + </xsl:when> + + + <xsl:when test="$position='center'"> + </xsl:when> + + <xsl:when test="$sequence='blank'"> + <!-- nop --> + </xsl:when> + + + <xsl:otherwise> + <!-- nop --> + </xsl:otherwise> + </xsl:choose> + </fo:block> +</xsl:template> + +<xsl:template name="head.sep.rule"> + <xsl:param name="pageclass"/> + <xsl:param name="sequence"/> + <xsl:param name="gentext-key"/> + + <xsl:if test="$header.rule != 0"> + <xsl:attribute name="border-bottom-width">0.5pt</xsl:attribute> + <xsl:attribute name="border-bottom-style">solid</xsl:attribute> + <xsl:attribute name="border-bottom-color">#C51410</xsl:attribute> + </xsl:if> +</xsl:template> + + +<xsl:template name="foot.sep.rule"> + <xsl:param name="pageclass"/> + <xsl:param name="sequence"/> + <xsl:param name="gentext-key"/> + + <xsl:if test="$footer.rule != 0"> + <xsl:attribute name="border-top-width">0.5pt</xsl:attribute> + <xsl:attribute name="border-top-style">solid</xsl:attribute> + <xsl:attribute name="border-top-color">#C51410</xsl:attribute> + </xsl:if> +</xsl:template> + +<xsl:param name="header.column.widths">1 0 1</xsl:param> +<xsl:param name="footer.column.widths">1 0 1</xsl:param> +<xsl:param name="headers.on.blank.pages" select="1"/> +<xsl:param name="footers.on.blank.pages" select="1"/> + +</xsl:stylesheet> + diff --git a/doc/user/separate.in b/doc/user/separate.in deleted file mode 100644 index a8d0aab..0000000 --- a/doc/user/separate.in +++ /dev/null @@ -1,540 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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. - ---> - -<!-- - -=head1 Separating source and build trees - -It's often desirable to keep any derived files from the build completely -separate from the source files. This makes it much easier to keep track of -just what is a source file, and also makes it simpler to handle B<variant> -builds, especially if you want the variant builds to co-exist. - -=head2 Separating build and source directories using the Link command - -Cons provides a simple mechanism that handles all of these requirements. The -C<Link> command is invoked as in this example: - - Link 'build' => 'src'; - -The specified directories are ``linked'' to the specified source -directory. Let's suppose that you setup a source directory, F<src>, with the -sub-directories F<world> and F<hello> below it, as in the previous -example. You could then substitute for the original build lines the -following: - - Build qw( - build/world/Conscript - build/hello/Conscript - ); - -Notice that you treat the F<Conscript> file as if it existed in the build -directory. Now if you type the same command as before, you will get the -following results: - - % cons export - Install build/world/world.h as export/include/world.h - cc -Iexport/include -c build/hello/hello.c -o build/hello/hello.o - cc -Iexport/include -c build/world/world.c -o build/world/world.o - ar r build/world/libworld.a build/world/world.o - ar: creating build/world/libworld.a - ranlib build/world/libworld.a - Install build/world/libworld.a as export/lib/libworld.a - cc -o build/hello/hello build/hello/hello.o -Lexport/lib -lworld - Install build/hello/hello as export/bin/hello - -Again, Cons has taken care of the details for you. In particular, you will -notice that all the builds are done using source files and object files from -the build directory. For example, F<build/world/world.o> is compiled from -F<build/world/world.c>, and F<export/include/world.h> is installed from -F<build/world/world.h>. This is accomplished on most systems by the simple -expedient of ``hard'' linking the required files from each source directory -into the appropriate build directory. - -The links are maintained correctly by Cons, no matter what you do to the -source directory. If you modify a source file, your editor may do this ``in -place'' or it may rename it first and create a new file. In the latter case, -any hard link will be lost. Cons will detect this condition the next time -the source file is needed, and will relink it appropriately. - -You'll also notice, by the way, that B<no> changes were required to the -underlying F<Conscript> files. And we can go further, as we shall see in the -next section. - -=head2 Explicit references to the source directory - -When using the C<Link> command on some operating systems or with some -tool chains, it's sometimes useful to have a command actually use -the path name to the source directory, not the build directory. For -example, on systems that must copy, not "hard link," the F<src/> and -F<build/> copies of C<Linked> files, using the F<src/> path of a file -name might make an editor aware that a syntax error must be fixed in the -source directory, not the build directory. - -You can tell Cons that you want to use the "source path" for a file by -preceding the file name with a ``!'' (exclamation point). For example, -if we add a ``!'' to the beginning of a source file: - - Program $env "foo", "!foo.c"; # Notice initial ! on foo.c - -Cons will compile the target as follows: - - cc -c src/foo.c -o build/foo.o - cc -o build/foo build/foo.o - -Notice that Cons has compiled the program from the the F<src/foo.c> -source file. Without the initial ``!'', Cons would have compiled the -program using the F<build/foo.c> path name. - ---> - - <para> - - It's often useful to keep any built files completely - separate from the source files. - In &SCons;, this is usually done by creating one or more separate - <emphasis>variant directory trees</emphasis> - that are used to hold the built objects files, libraries, - and executable programs, etc. - for a specific flavor, or variant, of build. - &SCons; provides two ways to do this, - one through the &SConscript; function that we've already seen, - and the second through a more flexible &VariantDir; function. - - </para> - - <para> - - One historical note: the &VariantDir; function - used to be called &BuildDir;. - That name is still supported - but has been deprecated - because the &SCons; functionality - differs from the model of a "build directory" - implemented by other build systems like the GNU Autotools. - - </para> - - <section> - <title>Specifying a Variant Directory Tree as Part of an &SConscript; Call</title> - - <para> - - The most straightforward way to establish a variant directory tree - uses the fact that the usual way to - set up a build hierarchy is to have an - &SConscript; file in the source subdirectory. - If you then pass a &variant_dir; argument to the - &SConscript; function call: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - SConscript('src/SConscript', variant_dir='build') - </file> - <file name="src/SConscript"> - env = Environment() - env.Program('hello.c') - </file> - <file name="src/hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - &SCons; will then build all of the files in - the &build; subdirectory: - - </para> - - <scons_output example="ex1"> - <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> - - But wait a minute--what's going on here? - &SCons; created the object file - <filename>build/hello.o</filename> - in the &build; subdirectory, - as expected. - But even though our &hello_c; file lives in the &src; subdirectory, - &SCons; has actually compiled a - <filename>build/hello.c</filename> file - to create the object file. - - </para> - - <para> - - What's happened is that &SCons; has <emphasis>duplicated</emphasis> - the &hello_c; file from the &src; subdirectory - to the &build; subdirectory, - and built the program from there. - The next section explains why &SCons; does this. - - </para> - - </section> - - <section> - <title>Why &SCons; Duplicates Source Files in a Variant Directory Tree</title> - - <para> - - &SCons; duplicates source files in variant directory trees - because it's the most straightforward way to guarantee a correct build - <emphasis>regardless of include-file directory paths, - relative references between files, - or tool support for putting files in different locations</emphasis>, - and the &SCons; philosophy is to, by default, - guarantee a correct build in all cases. - - </para> - - <para> - - The most direct reason to duplicate source files - in variant directories - is simply that some tools (mostly older versions) - are written to only build their output files - in the same directory as the source files. - In this case, the choices are either - to build the output file in the source directory - and move it to the variant directory, - or to duplicate the source files in the variant directory. - - </para> - - <para> - - Additionally, - relative references between files - can cause problems if we don't - just duplicate the hierarchy of source files - in the variant directory. - You can see this at work in - use of the C preprocessor <literal>#include</literal> - mechanism with double quotes, not angle brackets: - - </para> - - <sconstruct> - #include "file.h" - </sconstruct> - - <para> - - The <emphasis>de facto</emphasis> standard behavior - for most C compilers in this case - is to first look in the same directory - as the source file that contains the <literal>#include</literal> line, - then to look in the directories in the preprocessor search path. - Add to this that the &SCons; implementation of - support for code repositories - (described below) - means not all of the files - will be found in the same directory hierarchy, - and the simplest way to make sure - that the right include file is found - is to duplicate the source files into the variant directory, - which provides a correct build - regardless of the original location(s) of the source files. - - </para> - - <para> - - Although source-file duplication guarantees a correct build - even in these end-cases, - it <emphasis>can</emphasis> usually be safely disabled. - The next section describes - how you can disable the duplication of source files - in the variant directory. - - </para> - - </section> - - <section> - <title>Telling &SCons; to Not Duplicate Source Files in the Variant Directory Tree</title> - - <para> - - In most cases and with most tool sets, - &SCons; can place its target files in a build subdirectory - <emphasis>without</emphasis> - duplicating the source files - and everything will work just fine. - You can disable the default &SCons; behavior - by specifying <literal>duplicate=0</literal> - when you call the &SConscript; function: - - </para> - - <sconstruct> - SConscript('src/SConscript', variant_dir='build', duplicate=0) - </sconstruct> - - <para> - - When this flag is specified, - &SCons; uses the variant directory - like most people expect--that is, - the output files are placed in the variant directory - while the source files stay in the source directory: - - </para> - - <screen> - % <userinput>ls src</userinput> - SConscript - hello.c - % <userinput>scons -Q</userinput> - cc -c src/hello.c -o build/hello.o - cc -o build/hello build/hello.o - % <userinput>ls build</userinput> - hello - hello.o - </screen> - - </section> - - <section> - <title>The &VariantDir; Function</title> - - <para> - - Use the &VariantDir; function to establish that target - files should be built in a separate directory - from the source files: - - </para> - - <scons_example name="ex_builddir"> - <file name="SConstruct" printme="1"> - VariantDir('build', 'src') - env = Environment() - env.Program('build/hello.c') - </file> - <file name="src/hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Note that when you're not using - an &SConscript; file in the &src; subdirectory, - you must actually specify that - the program must be built from - the <filename>build/hello.c</filename> - file that &SCons; will duplicate in the - &build; subdirectory. - - </para> - - <para> - - When using the &VariantDir; function directly, - &SCons; still duplicates the source files - in the variant directory by default: - - </para> - - <scons_output example="ex_builddir"> - <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> - - You can specify the same <literal>duplicate=0</literal> argument - that you can specify for an &SConscript; call: - - </para> - - <scons_example name="ex_duplicate_0"> - <file name="SConstruct" printme="1"> - VariantDir('build', 'src', duplicate=0) - env = Environment() - env.Program('build/hello.c') - </file> - <file name="src/hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - In which case &SCons; - will disable duplication of the source files: - - </para> - - <scons_output example="ex_duplicate_0"> - <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> - - <section> - <title>Using &VariantDir; With an &SConscript; File</title> - - <para> - - Even when using the &VariantDir; function, - it's much more natural to use it with - a subsidiary &SConscript; file. - For example, if the - <filename>src/SConscript</filename> - looks like this: - - </para> - - <scons_example name="example_builddir_sconscript"> - <file name="SConstruct"> - VariantDir('build', 'src') - SConscript('build/SConscript') - </file> - <file name="src/SConscript" printme="1"> - env = Environment() - env.Program('hello.c') - </file> - <file name="src/hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Then our &SConstruct; file could look like: - - </para> - - <scons_example_file example="example_builddir_sconscript" name="SConstruct"> - </scons_example_file> - - <para> - - Yielding the following output: - - </para> - - <scons_output example="example_builddir_sconscript"> - <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> - - Notice that this is completely equivalent - to the use of &SConscript; that we - learned about in the previous section. - - </para> - - </section> - - <section> - <title>Using &Glob; with &VariantDir;</title> - - <para> - - The &Glob; file name pattern matching function - works just as usual when using &VariantDir;. - For example, if the - <filename>src/SConscript</filename> - looks like this: - - </para> - - <scons_example name="example_glob_builddir_sconscript"> - <file name="SConstruct"> - VariantDir('build', 'src') - SConscript('build/SConscript') - </file> - <file name="src/SConscript" printme="1"> - env = Environment() - env.Program('hello', Glob('*.c')) - </file> - <file name="src/f1.c"> - #include "f2.h" - int main() { printf(f2()); } - </file> - <file name="src/f2.c"> - const char * f2() { return("Hello, world!\n"); } - </file> - <file name="src/f2.h"> - const char * f2(); - </file> - </scons_example> - - <para> - - Then with the same &SConstruct; file as in the previous section, - and source files <filename>f1.c</filename> - and <filename>f2.c</filename> in src, - we would see the following output: - - </para> - - <scons_output example="example_glob_builddir_sconscript"> - <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> - - The &Glob; function returns Nodes in the - <filename>build/</filename> tree, as you'd expect. - - </para> - - </section> - - <!-- - - <section> - <title>Why You'd Want to Call &VariantDir; Instead of &SConscript;</title> - - <para> - - XXX why call VariantDir() instead of SConscript(variant_dir=) - - </para> - - </section> - - --> diff --git a/doc/user/separate.xml b/doc/user/separate.xml index 8ad357c..e973795 100644 --- a/doc/user/separate.xml +++ b/doc/user/separate.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-separate" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Separating Source and Build Directories</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -151,9 +172,18 @@ program using the F<build/foo.c> path name. </para> - <programlisting> - SConscript('src/SConscript', variant_dir='build') - </programlisting> + <scons_example name="separate_ex1"> + <file name="SConstruct" printme="1"> +SConscript('src/SConscript', variant_dir='build') + </file> + <file name="src/SConscript"> +env = Environment() +env.Program('hello.c') + </file> + <file name="src/hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -162,15 +192,11 @@ program using the F<build/foo.c> path name. </para> - <screen> - % <userinput>ls src</userinput> - SConscript hello.c - % <userinput>scons -Q</userinput> - cc -o build/hello.o -c build/hello.c - cc -o build/hello build/hello.o - % <userinput>ls build</userinput> - SConscript hello hello.c hello.o - </screen> + <scons_output example="separate_ex1" suffix="1"> + <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> @@ -240,9 +266,9 @@ program using the F<build/foo.c> path name. </para> - <programlisting> - #include "file.h" - </programlisting> + <sconstruct> +#include "file.h" + </sconstruct> <para> @@ -293,9 +319,9 @@ program using the F<build/foo.c> path name. </para> - <programlisting> - SConscript('src/SConscript', variant_dir='build', duplicate=0) - </programlisting> + <sconstruct> +SConscript('src/SConscript', variant_dir='build', duplicate=0) + </sconstruct> <para> @@ -308,15 +334,15 @@ program using the F<build/foo.c> path name. </para> <screen> - % <userinput>ls src</userinput> - SConscript - hello.c - % <userinput>scons -Q</userinput> - cc -c src/hello.c -o build/hello.o - cc -o build/hello build/hello.o - % <userinput>ls build</userinput> - hello - hello.o +% <userinput>ls src</userinput> +SConscript +hello.c +% <userinput>scons -Q</userinput> +cc -c src/hello.c -o build/hello.o +cc -o build/hello build/hello.o +% <userinput>ls build</userinput> +hello +hello.o </screen> </section> @@ -332,11 +358,16 @@ program using the F<build/foo.c> path name. </para> - <programlisting> - VariantDir('build', 'src') - env = Environment() - env.Program('build/hello.c') - </programlisting> + <scons_example name="separate_builddir"> + <file name="SConstruct" printme="1"> +VariantDir('build', 'src') +env = Environment() +env.Program('build/hello.c') + </file> + <file name="src/hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -358,15 +389,11 @@ program using the F<build/foo.c> path name. </para> - <screen> - % <userinput>ls src</userinput> - hello.c - % <userinput>scons -Q</userinput> - cc -o build/hello.o -c build/hello.c - cc -o build/hello build/hello.o - % <userinput>ls build</userinput> - hello hello.c hello.o - </screen> + <scons_output example="separate_builddir" suffix="1"> + <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> @@ -375,11 +402,16 @@ program using the F<build/foo.c> path name. </para> - <programlisting> - VariantDir('build', 'src', duplicate=0) - env = Environment() - env.Program('build/hello.c') - </programlisting> + <scons_example name="separate_duplicate0"> + <file name="SConstruct" printme="1"> +VariantDir('build', 'src', duplicate=0) +env = Environment() +env.Program('build/hello.c') + </file> + <file name="src/hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -388,15 +420,11 @@ program using the F<build/foo.c> path name. </para> - <screen> - % <userinput>ls src</userinput> - hello.c - % <userinput>scons -Q</userinput> - cc -o build/hello.o -c src/hello.c - cc -o build/hello build/hello.o - % <userinput>ls build</userinput> - hello hello.o - </screen> + <scons_output example="separate_duplicate0" suffix="1"> + <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> @@ -414,10 +442,19 @@ program using the F<build/foo.c> path name. </para> - <programlisting> - env = Environment() - env.Program('hello.c') - </programlisting> + <scons_example name="separate_builddir_sconscript"> + <file name="SConstruct"> +VariantDir('build', 'src') +SConscript('build/SConscript') + </file> + <file name="src/SConscript" printme="1"> +env = Environment() +env.Program('hello.c') + </file> + <file name="src/hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -425,11 +462,8 @@ program using the F<build/foo.c> path name. </para> - - <programlisting> - VariantDir('build', 'src') - SConscript('build/SConscript') - </programlisting> + <scons_example_file example="separate_builddir_sconscript" name="SConstruct"> + </scons_example_file> <para> @@ -437,15 +471,11 @@ program using the F<build/foo.c> path name. </para> - <screen> - % <userinput>ls src</userinput> - SConscript hello.c - % <userinput>scons -Q</userinput> - cc -o build/hello.o -c build/hello.c - cc -o build/hello build/hello.o - % <userinput>ls build</userinput> - SConscript hello hello.c hello.o - </screen> + <scons_output example="separate_builddir_sconscript" suffix="1"> + <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> @@ -470,10 +500,26 @@ program using the F<build/foo.c> path name. </para> - <programlisting> - env = Environment() - env.Program('hello', Glob('*.c')) - </programlisting> + <scons_example name="separate_glob_builddir_sconscript"> + <file name="SConstruct"> +VariantDir('build', 'src') +SConscript('build/SConscript') + </file> + <file name="src/SConscript" printme="1"> +env = Environment() +env.Program('hello', Glob('*.c')) + </file> + <file name="src/f1.c"> +#include "f2.h" +int main() { printf(f2()); } + </file> + <file name="src/f2.c"> +const char * f2() { return("Hello, world!\n"); } + </file> + <file name="src/f2.h"> +const char * f2(); + </file> + </scons_example> <para> @@ -484,16 +530,11 @@ program using the F<build/foo.c> path name. </para> - <screen> - % <userinput>ls src</userinput> - SConscript f1.c f2.c f2.h - % <userinput>scons -Q</userinput> - cc -o build/f1.o -c build/f1.c - cc -o build/f2.o -c build/f2.c - cc -o build/hello build/f1.o build/f2.o - % <userinput>ls build</userinput> - SConscript f1.c f1.o f2.c f2.h f2.o hello - </screen> + <scons_output example="separate_glob_builddir_sconscript" suffix="1"> + <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> @@ -518,3 +559,5 @@ program using the F<build/foo.c> path name. </section> --> + +</chapter> diff --git a/doc/user/sideeffect.in b/doc/user/sideeffect.in deleted file mode 100644 index ece0300..0000000 --- a/doc/user/sideeffect.in +++ /dev/null @@ -1,216 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - If &SCons; is unaware that a build step produces an extra file, - the &SideEffect; method can be used to identify it, - so that the file can be used as a dependency in subsequent build steps. - However, the primary use for the &SideEffect; method - is to prevent two build steps from simultaneously modifying the same file. - - </para> - - TODO: currently doesn't work due to issue #2154: - http://scons.tigris.org/issues/show_bug.cgi?id=2154 - - <para> - - If more than one build step creates or manipulates the same file, - it can cause unpleasant results if both build steps are run at the same time. - The shared file is declared as a side-effect of building the primary targets - and &SCons; will prevent the two build steps from running in parallel. - - </para> - - <para> - - In this example, the <filename>SConscript</filename> uses - &SideEffect; to inform &SCons; about the additional output file. - - </para> - - <scons_example name="SideEffectSimple"> - <file name="SConstruct" printme="1"> - env = Environment() - f2 = env.Command('file2', 'log', Copy('$TARGET', '$SOURCE')) - f1 = env.Command('file1', [], - 'echo >$TARGET data1; echo >log updated file1')) - env.SideEffect('log', env.Command('file1', [], - 'echo >$TARGET data1; echo >log updated file1')) - </file> - </scons_example> - - <para> - - Even when run in parallel mode, &SCons; will run the two steps in order: - - </para> - - <scons_output example="SideEffectSimple"> - <scons_output_command>scons -Q --jobs=2</scons_output_command> - </scons_output> - - --> - - <para> - - Sometimes a program the you need to call - to build a target file - will also update another file, - such as a log file describing what the program - does while building the target. - For example, we the folowing configuration - would have &SCons; invoke a hypothetical - script named <application>build</application> - (in the local directory) - with command-line arguments that write - log information to a common - <filename>logfile.txt</filename> file: - - </para> - - <screen> - env = Environment() - env.Command('file1.out', 'file.in', - './build --log logfile.txt $SOURCE $TARGET') - env.Command('file2.out', 'file.in', - './build --log logfile.txt $SOURCE $TARGET') - <screen> - - <para> - - This can cause problems when running - the build in parallel if - &SCons; decides to update both targets - by running both program invocations at the same time. - The multiple program invocations - may interfere with each other - writing to the common log file, - leading at best to intermixed output in the log file, - and at worst to an actual failed build - (on a system like Windows, for example, - where only one process at a time can open the log file for writing). - - </para> - - <para> - - We can make sure that &SCons; does not - run these <application>build</application> - commands at the same time - by using the &SideEffect; function - to specify that updating - the <filename>logfile.txt</filename> file - is a side effect of building the specified - <filename>file1</filename> - and - <filename>file2</filename> - target files: - - </para> - - <scons_example name="SideEffectShared"> - <file name="SConstruct" printme="1"> - env = Environment() - f1 = env.Command('file1.out', 'file1.in', - './build --log logfile.txt $SOURCE $TARGET') - f2 = env.Command('file2.out', 'file2.in', - './build --log logfile.txt $SOURCE $TARGET') - env.SideEffect('logfile.txt', f1 + f2) - </file> - <file name="file1.in">file1.in</file> - <file name="file2.in">file2.in</file> - <file name="build" chmod="0755"> - cat - </file> - </scons_example> - - <para> - - </para> - - <para> - - This makes sure the the two - <application>./build</application> steps are run sequentially, - even withthe <filename>--jobs=2</filename> in the command line: - - </para> - - <scons_output example="SideEffectShared"> - <scons_output_command>scons -Q --jobs=2</scons_output_command> - </scons_output> - - <para> - - The &SideEffect; function can be called multiple - times for the same side-effect file. - Additionally, the name used as a &SideEffect; does not - even need to actually exist as a file on disk. - &SCons; will still make sure - that the relevant targets - will be executed sequentially, not in parallel: - - </para> - - <scons_example name="SideEffectParallel"> - <file name="SConstruct" printme="1"> - env = Environment() - f1 = env.Command('file1.out', [], 'echo >$TARGET data1') - env.SideEffect('not_really_updated', f1) - f2 = env.Command('file2.out', [], 'echo >$TARGET data2') - env.SideEffect('not_really_updated', f2) - </file> - </scons_example> - - <scons_output example="SideEffectParallel"> - <scons_output_command>scons -Q --jobs=2</scons_output_command> - </scons_output> - - <para> - - Note that it might be tempting to - use &SideEffect; for additional target files - that a command produces. - For example, versions the Microsoft Visual C/C++ compiler - produce a <filename>foo.ilk</filename> - alongside compiling <filename>foo.obj</filename> file. - Specifying <filename>foo.ilk</filename> as a - side-effect of <filename>foo.obj</filename> - is <emphasis>not</emphasis> a recommended use of &SideEffect;, - because &SCons; handle side-effect files - slightly differently in its analysis of the dependency graph. - When a command produces multiple output files, - they should be specified as multiple targets of - the call to the relevant builder function, - and the &SideEffect; function itself should really only be used - when it's important to ensure that commands are not executed in parallel, - such as when a "peripheral" file (such as a log file) - may actually updated by more than one command invocation. - - </para> diff --git a/doc/user/sideeffect.xml b/doc/user/sideeffect.xml index a656f9d..72af9cc 100644 --- a/doc/user/sideeffect.xml +++ b/doc/user/sideeffect.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-sideeffect" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Sideeffect files</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -23,8 +44,6 @@ --> - <!-- - <para> If &SCons; is unaware that a build step produces an extra file, @@ -35,9 +54,11 @@ </para> + <para> TODO: currently doesn't work due to issue #2154: http://scons.tigris.org/issues/show_bug.cgi?id=2154 - + </para> + <para> If more than one build step creates or manipulates the same file, @@ -54,14 +75,14 @@ </para> - <scons_example name="SideEffectSimple"> + <scons_example name="sideeffect_simple"> <file name="SConstruct" printme="1"> - env = Environment() - f2 = env.Command('file2', 'log', Copy('$TARGET', '$SOURCE')) - f1 = env.Command('file1', [], - 'echo >$TARGET data1; echo >log updated file1')) - env.SideEffect('log', env.Command('file1', [], - 'echo >$TARGET data1; echo >log updated file1')) +env = Environment() +f2 = env.Command('file2', 'log', Copy('$TARGET', '$SOURCE')) +f1 = env.Command('file1', [], + 'echo >$TARGET data1; echo >log updated file1')) +env.SideEffect('log', env.Command('file1', [], + 'echo >$TARGET data1; echo >log updated file1')) </file> </scons_example> @@ -71,12 +92,10 @@ </para> - <scons_output example="SideEffectSimple"> + <scons_output example="sideeffect_simple" suffix="1"> <scons_output_command>scons -Q --jobs=2</scons_output_command> </scons_output> - --> - <para> Sometimes a program the you need to call @@ -95,12 +114,12 @@ </para> <screen> - env = Environment() - env.Command('file1.out', 'file.in', - './build --log logfile.txt $SOURCE $TARGET') - env.Command('file2.out', 'file.in', - './build --log logfile.txt $SOURCE $TARGET') - <screen> +env = Environment() +env.Command('file1.out', 'file.in', + './build --log logfile.txt $SOURCE $TARGET') +env.Command('file2.out', 'file.in', + './build --log logfile.txt $SOURCE $TARGET') + </screen> <para> @@ -134,14 +153,21 @@ </para> - <programlisting> - env = Environment() - f1 = env.Command('file1.out', 'file1.in', - './build --log logfile.txt $SOURCE $TARGET') - f2 = env.Command('file2.out', 'file2.in', - './build --log logfile.txt $SOURCE $TARGET') - env.SideEffect('logfile.txt', f1 + f2) - </programlisting> + <scons_example name="sideeffect_shared"> + <file name="SConstruct" printme="1"> +env = Environment() +f1 = env.Command('file1.out', 'file1.in', + './build --log logfile.txt $SOURCE $TARGET') +f2 = env.Command('file2.out', 'file2.in', + './build --log logfile.txt $SOURCE $TARGET') +env.SideEffect('logfile.txt', f1 + f2) + </file> + <file name="file1.in">file1.in</file> + <file name="file2.in">file2.in</file> + <file name="build" chmod="0755"> +cat + </file> + </scons_example> <para> @@ -155,11 +181,9 @@ </para> - <screen> - % <userinput>scons -Q --jobs=2</userinput> - ./build --log logfile.txt file1.in file1.out - ./build --log logfile.txt file2.in file2.out - </screen> + <scons_output example="sideeffect_shared" suffix="1"> + <scons_output_command>scons -Q --jobs=2</scons_output_command> + </scons_output> <para> @@ -173,19 +197,19 @@ </para> - <programlisting> - env = Environment() - f1 = env.Command('file1.out', [], 'echo >$TARGET data1') - env.SideEffect('not_really_updated', f1) - f2 = env.Command('file2.out', [], 'echo >$TARGET data2') - env.SideEffect('not_really_updated', f2) - </programlisting> + <scons_example name="sideeffect_parallel"> + <file name="SConstruct" printme="1"> +env = Environment() +f1 = env.Command('file1.out', [], 'echo >$TARGET data1') +env.SideEffect('not_really_updated', f1) +f2 = env.Command('file2.out', [], 'echo >$TARGET data2') +env.SideEffect('not_really_updated', f2) + </file> + </scons_example> - <screen> - % <userinput>scons -Q --jobs=2</userinput> - echo > file1.out data1 - echo > file2.out data2 - </screen> + <scons_output example="sideeffect_parallel" suffix="1"> + <scons_output_command>scons -Q --jobs=2</scons_output_command> + </scons_output> <para> @@ -209,3 +233,6 @@ may actually updated by more than one command invocation. </para> + + </chapter> + diff --git a/doc/user/simple.in b/doc/user/simple.in deleted file mode 100644 index 76b044b..0000000 --- a/doc/user/simple.in +++ /dev/null @@ -1,517 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - In this chapter, - you will see several examples of - very simple build configurations using &SCons;, - which will demonstrate how easy - it is to use &SCons; to - build programs from several different programming languages - on different types of systems. - - </para> - - <section> - <title>Building Simple C / C++ Programs</title> - - <para> - - Here's the famous "Hello, World!" program in C: - - </para> - - <programlisting> - int - main() - { - printf("Hello, world!\n"); - } - </programlisting> - - <para> - - And here's how to build it using &SCons;. - Enter the following into a file named &SConstruct;: - - </para> - - <scons_example name="ex1"> - <file name="SConstruct" printme="1"> - Program('hello.c') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - This minimal configuration file gives - &SCons; two pieces of information: - what you want to build - (an executable program), - and the input file from - which you want it built - (the <filename>hello.c</filename> file). - &b-link-Program; is a <firstterm>builder_method</firstterm>, - a Python call that tells &SCons; that you want to build an - executable program. - - </para> - - <para> - - That's it. Now run the &scons; command to build the program. - On a POSIX-compliant system like Linux or UNIX, - you'll see something like: - - </para> - - <scons_output example="ex1" os="posix"> - <scons_output_command>scons</scons_output_command> - </scons_output> - - <para> - - On a Windows system with the Microsoft Visual C++ compiler, - you'll see something like: - - </para> - - <scons_output example="ex1" os="win32"> - <scons_output_command>scons</scons_output_command> - </scons_output> - - <para> - - First, notice that you only need - to specify the name of the source file, - and that &SCons; correctly deduces the names of - the object and executable files to be built - from the base of the source file name. - - </para> - - <para> - - Second, notice that the same input &SConstruct; file, - without any changes, - generates the correct output file names on both systems: - <filename>hello.o</filename> and <filename>hello</filename> - on POSIX systems, - <filename>hello.obj</filename> and <filename>hello.exe</filename> - on Windows systems. - This is a simple example of how &SCons; - makes it extremely easy to - write portable software builds. - - </para> - - <para> - - (Note that we won't provide duplicate side-by-side - POSIX and Windows output for all of the examples in this guide; - just keep in mind that, unless otherwise specified, - any of the examples should work equally well on both types of systems.) - - </para> - - </section> - - <section> - <title>Building Object Files</title> - - <para> - - 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 &b-link-Object; builder method, - which tells &SCons; to build an object file - from the specified source file: - - </para> - - <scons_example name="Object"> - <file name="SConstruct" printme="1"> - Object('hello.c') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <para> - - Now when you run the &scons; command to build the program, - it will build just the &hello_o; object file on a POSIX system: - - </para> - - <scons_output example="Object" os="posix"> - <scons_output_command>scons</scons_output_command> - </scons_output> - - <para> - - And just the &hello_obj; object file - on a Windows system (with the Microsoft Visual C++ compiler): - - </para> - - <scons_output example="Object" os="win32"> - <scons_output_command>scons</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Simple Java Builds</title> - - <para> - - &SCons; also makes building with Java extremely easy. - 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, - followed by the source directory - in which the <filename>.java</filename> files live: - - </para> - - <scons_example name="java"> - <file name="SConstruct" printme="1"> - Java('classes', 'src') - </file> - <file name="src/hello.java"> - public class Example1 - { - public static void main(String[] args) - { - System.out.println("Hello Java world!\n"); - } - } - </file> - </scons_example> - - <para> - - If the <filename>src</filename> directory - contains a single <filename>hello.java</filename> file, - then the output from running the &scons; command - would look something like this - (on a POSIX system): - - </para> - - <scons_output example="java" os="posix"> - <scons_output_command>scons</scons_output_command> - </scons_output> - - <para> - - We'll cover Java builds in more detail, - including building Java archive (<filename>.jar</filename>) - and other types of file, - in <xref linkend="chap-java"></xref>. - - </para> - - </section> - - <section> - <title>Cleaning Up After a Build</title> - - <para> - - When using &SCons;, it is unnecessary to add special - commands or target names to clean up after a build. - Instead, you simply use the - <literal>-c</literal> or <literal>--clean</literal> - option when you invoke &SCons;, - and &SCons; removes the appropriate built files. - So if we build our example above - and then invoke <literal>scons -c</literal> - afterwards, the output on POSIX looks like: - - </para> - - <scons_example name="clean"> - <file name="SConstruct"> - Program('hello.c') - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - </scons_example> - - <scons_output example="clean" os="posix"> - <scons_output_command>scons</scons_output_command> - <scons_output_command>scons -c</scons_output_command> - </scons_output> - - <para> - - And the output on Windows looks like: - - </para> - - <scons_output example="clean" os="win32"> - <scons_output_command>scons</scons_output_command> - <scons_output_command>scons -c</scons_output_command> - </scons_output> - - <para> - - Notice that &SCons; changes its output to tell you that it - is <literal>Cleaning targets ...</literal> and - <literal>done cleaning targets.</literal> - - </para> - - </section> - - <section> - <title>The &SConstruct; File</title> - - <para> - - If you're used to build systems like &Make; - you've already figured out that the &SConstruct; file - is the &SCons; equivalent of a &Makefile;. - That is, the &SConstruct; file is the input file - that &SCons; reads to control the build. - - </para> - - <section> - <title>&SConstruct; Files Are Python Scripts</title> - - <para> - - There is, however, an important difference between - an &SConstruct; file and a &Makefile;: - the &SConstruct; file is actually a Python script. - If you're not already familiar with Python, don't worry. - This User's Guide will introduce you step-by-step - to the relatively small amount of Python you'll - need to know to be able to use &SCons; effectively. - And Python is very easy to learn. - - </para> - - <para> - - One aspect of using Python as the - scripting language is that you can put comments - in your &SConstruct; file using Python's commenting convention; - that is, everything between a '#' and the end of the line - will be ignored: - - </para> - - <programlisting> - # Arrange to build the "hello" program. - Program('hello.c') # "hello.c" is the source file. - </programlisting> - - <para> - - You'll see throughout the remainder of this Guide - that being able to use the power of a - real scripting language - can greatly simplify the solutions - to complex requirements of real-world builds. - - </para> - - </section> - - <section> - <title>&SCons; Functions Are Order-Independent</title> - - <para> - - One important way in which the &SConstruct; - file is not exactly like a normal Python script, - and is more like a &Makefile;, - is that the order in which - the &SCons; functions are called in - the &SConstruct; file - does <emphasis>not</emphasis> - affect the order in which &SCons; - actually builds the programs and object files - you want it to build.<footnote> - <para>In programming parlance, - the &SConstruct; file is - <emphasis>declarative</emphasis>, - meaning you tell &SCons; what you want done - and let it figure out the order in which to do it, - rather than strictly <emphasis>imperative</emphasis>, - where you specify explicitly the order in - which to do things. - </para> - </footnote> - 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. - Instead, you're telling &SCons; to build the program - that you want, for example, - a program built from a file named &hello_c;, - and it's up to &SCons; to build that program - (and any other files) whenever it's necessary. - (We'll learn more about how - &SCons; decides when building or rebuilding a file - is necessary in <xref linkend="chap-depends"></xref>, below.) - - </para> - - <para> - - &SCons; reflects this distinction between - <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, - and when it's actually building the target files. - This is to make it clear when &SCons; is - executing the Python statements that make up the &SConstruct; file, - and when &SCons; is actually executing the - commands or other actions to - build the necessary files. - - </para> - - <para> - - Let's clarify this with an example. - 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 &b-Program; builder method: - - </para> - - <scons_example name="declarative"> - <file name="SConstruct" printme="1"> - print "Calling Program('hello.c')" - Program('hello.c') - print "Calling Program('goodbye.c')" - Program('goodbye.c') - print "Finished calling Program()" - </file> - <file name="hello.c"> - int main() { printf("Hello, world!\n"); } - </file> - <file name="goodbye.c"> - int main() { printf("Goodbye, world!\n"); } - </file> - </scons_example> - - <para> - - Then when we execute &SCons;, - we see the output from the <literal>print</literal> - statements in between the messages about - reading the &SConscript; files, - indicating that that is when the - Python statements are being executed: - - </para> - - <scons_output example="declarative" os="posix"> - <scons_output_command>scons</scons_output_command> - </scons_output> - - <para> - - Notice also that &SCons; built the &goodbye; program first, - even though the "reading &SConscript;" output - shows that we called <literal>Program('hello.c')</literal> - first in the &SConstruct; file. - - </para> - - </section> - - </section> - - <section> - <title>Making the &SCons; Output Less Verbose</title> - - <para> - - You've already seen how &SCons; prints - some messages about what it's doing, - surrounding the actual commands used to build the software: - - </para> - - <scons_output example="ex1" os="win32"> - <scons_output_command>scons</scons_output_command> - </scons_output> - - <para> - - These messages emphasize the - order in which &SCons; does its work: - all of the configuration files - (generically referred to as &SConscript; files) - are read and executed first, - and only then are the target files built. - Among other benefits, these messages help to distinguish between - errors that occur while the configuration files are read, - and errors that occur while targets are being built. - - </para> - - <para> - - One drawback, of course, is that these messages clutter the output. - Fortunately, they're easily disabled by using - the &Q; option when invoking &SCons;: - - </para> - - <scons_output example="ex1" os="win32"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - Because we want this User's Guide to focus - on what &SCons; is actually doing, - we're going to use the &Q; option - to remove these messages from the - output of all the remaining examples in this Guide. - - </para> - - </section> diff --git a/doc/user/simple.xml b/doc/user/simple.xml index 238e40c..3ddb0dc 100644 --- a/doc/user/simple.xml +++ b/doc/user/simple.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-simple" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Simple Builds</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -45,11 +66,11 @@ </para> <programlisting> - int - main() - { - printf("Hello, world!\n"); - } +int +main() +{ + printf("Hello, world!\n"); +} </programlisting> <para> @@ -59,9 +80,14 @@ </para> - <programlisting> - Program('hello.c') - </programlisting> + <scons_example name="simple_ex1"> + <file name="SConstruct" printme="1"> +Program('hello.c') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -86,15 +112,9 @@ </para> - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - cc -o hello.o -c hello.c - cc -o hello hello.o - scons: done building targets. - </screen> + <scons_output example="simple_ex1" os="posix" suffix="1"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -103,16 +123,9 @@ </para> - <screen> - C:\><userinput>scons</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - cl /Fohello.obj /c hello.c /nologo - link /nologo /OUT:hello.exe hello.obj - embedManifestExeCheck(target, source, env) - scons: done building targets. - </screen> + <scons_output example="simple_ex1" os="win32" suffix="2"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -164,9 +177,14 @@ </para> - <programlisting> - Object('hello.c') - </programlisting> + <scons_example name="simple_Object"> + <file name="SConstruct" printme="1"> +Object('hello.c') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> <para> @@ -175,14 +193,9 @@ </para> - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - cc -o hello.o -c hello.c - scons: done building targets. - </screen> + <scons_output example="simple_Object" os="posix" suffix="1"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -191,14 +204,9 @@ </para> - <screen> - C:\><userinput>scons</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - cl /Fohello.obj /c hello.c /nologo - scons: done building targets. - </screen> + <scons_output example="simple_Object" os="win32" suffix="2"> + <scons_output_command>scons</scons_output_command> + </scons_output> </section> @@ -218,9 +226,20 @@ </para> - <programlisting> - Java('classes', 'src') - </programlisting> + <scons_example name="simple_java"> + <file name="SConstruct" printme="1"> +Java('classes', 'src') + </file> + <file name="src/hello.java"> +public class Example1 +{ + public static void main(String[] args) + { + System.out.println("Hello Java world!\n"); + } +} + </file> + </scons_example> <para> @@ -232,14 +251,9 @@ </para> - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - javac -d classes -sourcepath src src/hello.java - scons: done building targets. - </screen> + <scons_output example="simple_java" os="posix" suffix="1"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -269,24 +283,19 @@ </para> - - - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - cc -o hello.o -c hello.c - cc -o hello hello.o - scons: done building targets. - % <userinput>scons -c</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Cleaning targets ... - Removed hello.o - Removed hello - scons: done cleaning targets. - </screen> + <scons_example name="simple_clean"> + <file name="SConstruct"> +Program('hello.c') + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + </scons_example> + + <scons_output example="simple_clean" os="posix" suffix="1"> + <scons_output_command>scons</scons_output_command> + <scons_output_command>scons -c</scons_output_command> + </scons_output> <para> @@ -294,23 +303,10 @@ </para> - <screen> - C:\><userinput>scons</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - cl /Fohello.obj /c hello.c /nologo - link /nologo /OUT:hello.exe hello.obj - embedManifestExeCheck(target, source, env) - scons: done building targets. - C:\><userinput>scons -c</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Cleaning targets ... - Removed hello.obj - Removed hello.exe - scons: done cleaning targets. - </screen> + <scons_output example="simple_clean" os="win32" suffix="2"> + <scons_output_command>scons</scons_output_command> + <scons_output_command>scons -c</scons_output_command> + </scons_output> <para> @@ -362,8 +358,8 @@ </para> <programlisting> - # Arrange to build the "hello" program. - Program('hello.c') # "hello.c" is the source file. +# Arrange to build the "hello" program. +Program('hello.c') # "hello.c" is the source file. </programlisting> <para> @@ -444,13 +440,21 @@ </para> - <programlisting> - print "Calling Program('hello.c')" - Program('hello.c') - print "Calling Program('goodbye.c')" - Program('goodbye.c') - print "Finished calling Program()" - </programlisting> + <scons_example name="simple_declarative"> + <file name="SConstruct" printme="1"> +print "Calling Program('hello.c')" +Program('hello.c') +print "Calling Program('goodbye.c')" +Program('goodbye.c') +print "Finished calling Program()" + </file> + <file name="hello.c"> +int main() { printf("Hello, world!\n"); } + </file> + <file name="goodbye.c"> +int main() { printf("Goodbye, world!\n"); } + </file> + </scons_example> <para> @@ -463,20 +467,9 @@ </para> - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - Calling Program('hello.c') - Calling Program('goodbye.c') - Finished calling Program() - scons: done reading SConscript files. - scons: Building targets ... - cc -o goodbye.o -c goodbye.c - cc -o goodbye goodbye.o - cc -o hello.o -c hello.c - cc -o hello hello.o - scons: done building targets. - </screen> + <scons_output example="simple_declarative" os="posix" suffix="1"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -502,16 +495,9 @@ </para> - <screen> - C:\><userinput>scons</userinput> - scons: Reading SConscript files ... - scons: done reading SConscript files. - scons: Building targets ... - cl /Fohello.obj /c hello.c /nologo - link /nologo /OUT:hello.exe hello.obj - embedManifestExeCheck(target, source, env) - scons: done building targets. - </screen> + <scons_output example="simple_ex1" os="win32" suffix="3"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -535,12 +521,9 @@ </para> - <screen> - C:\><userinput>scons -Q</userinput> - cl /Fohello.obj /c hello.c /nologo - link /nologo /OUT:hello.exe hello.obj - embedManifestExeCheck(target, source, env) - </screen> + <scons_output example="simple_ex1" os="win32" suffix="4"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -553,3 +536,5 @@ </para> </section> + +</chapter> diff --git a/doc/user/sourcecode.in b/doc/user/sourcecode.in deleted file mode 100644 index d3547fb..0000000 --- a/doc/user/sourcecode.in +++ /dev/null @@ -1,162 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - XXX - - </para> - - <section> - <title>Fetching Source Code From BitKeeper</title> - - <para> - - XXX - - </para> - - <scons_example name="ex_bitkeeper"> - <file name="SConstruct" printme="1"> - env = Environment() - env.SourceCode('.', env.BitKeeper()) - env.Program('hello.c') - </file> - <file name="s.hello.c"> - s.hello.c - </file> - </scons_example> - - <scons_output example="ex_bitkeeper"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Fetching Source Code From CVS</title> - - <para> - - XXX - - </para> - - <scons_example name="ex_cvs"> - <file name="SConstruct" printme="1"> - env = Environment() - env.SourceCode('.', env.CVS('/usr/local/CVS')) - env.Program('hello.c') - </file> - </scons_example> - - <scons_output example="ex_cvs"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Fetching Source Code From RCS</title> - - <para> - - XXX - - </para> - - <scons_example name="ex_rcs"> - <file name="SConstruct" printme="1"> - env = Environment() - env.SourceCode('.', env.RCS()) - env.Program('hello.c') - </file> - <file name="hello.c,v"> - hello.c,v - </file> - </scons_example> - - <scons_output example="ex_rcs"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Fetching Source Code From SCCS</title> - - <para> - - XXX - - </para> - - <scons_example name="ex_sccs"> - <file name="SConstruct" printme="1"> - env = Environment() - env.SourceCode('.', env.SCCS()) - env.Program('hello.c') - </file> - <file name="s.hello.c"> - s.hello.c - </file> - </scons_example> - - <scons_output example="ex_sccs"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - <!-- - - <section> - <title>Fetching Source Code From Subversion</title> - - <para> - - XXX - - </para> - - <scons_example name="ex_subversion"> - <file name="SConstruct" printme="1"> - env = Environment() - env.SourceCode('.', env.Subversion('XXX')) - env.Program('hello.c') - </file> - </scons_example> - - <scons_output example="ex_subversion"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - </section> - - --> diff --git a/doc/user/sourcecode.xml b/doc/user/sourcecode.xml index ae84ec9..a1234fc 100644 --- a/doc/user/sourcecode.xml +++ b/doc/user/sourcecode.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-sourcecode" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Fetching Files From Source Code Management Systems</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -42,18 +63,20 @@ </para> - <programlisting> - env = Environment() - env.SourceCode('.', env.BitKeeper()) - env.Program('hello.c') - </programlisting> + <scons_example name="sourcecode_bitkeeper"> + <file name="SConstruct" printme="1"> +env = Environment() +env.SourceCode('.', env.BitKeeper()) +env.Program('hello.c') + </file> + <file name="s.hello.c"> +s.hello.c + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - bk get hello.c - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="sourcecode_bitkeeper" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -66,18 +89,17 @@ </para> - <programlisting> - env = Environment() - env.SourceCode('.', env.CVS('/usr/local/CVS')) - env.Program('hello.c') - </programlisting> + <scons_example name="sourcecode_cvs"> + <file name="SConstruct" printme="1"> +env = Environment() +env.SourceCode('.', env.CVS('/usr/local/CVS')) +env.Program('hello.c') + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - cvs -d /usr/local/CVS co hello.c - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="sourcecode_cvs" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -90,18 +112,20 @@ </para> - <programlisting> - env = Environment() - env.SourceCode('.', env.RCS()) - env.Program('hello.c') - </programlisting> + <scons_example name="sourcecode_rcs"> + <file name="SConstruct" printme="1"> +env = Environment() +env.SourceCode('.', env.RCS()) +env.Program('hello.c') + </file> + <file name="hello.c,v"> +hello.c,v + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - co hello.c - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="sourcecode_rcs" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -114,18 +138,20 @@ </para> - <programlisting> - env = Environment() - env.SourceCode('.', env.SCCS()) - env.Program('hello.c') - </programlisting> + <scons_example name="sourcecode_sccs"> + <file name="SConstruct" printme="1"> +env = Environment() +env.SourceCode('.', env.SCCS()) +env.Program('hello.c') + </file> + <file name="s.hello.c"> +s.hello.c + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - sccs get hello.c - cc -o hello.o -c hello.c - cc -o hello hello.o - </screen> + <scons_output example="sourcecode_sccs" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </section> @@ -140,18 +166,20 @@ </para> - <scons_example name="ex_subversion"> + <scons_example name="sourcecode_subversion"> <file name="SConstruct" printme="1"> - env = Environment() - env.SourceCode('.', env.Subversion('XXX')) - env.Program('hello.c') +env = Environment() +env.SourceCode('.', env.Subversion('XXX')) +env.Program('hello.c') </file> </scons_example> - <scons_output example="ex_subversion"> + <scons_output example="sourcecode_subversion" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> </section> --> + +</chapter> diff --git a/doc/user/tasks.in b/doc/user/tasks.in deleted file mode 100644 index 54cdf22..0000000 --- a/doc/user/tasks.in +++ /dev/null @@ -1,146 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> -There is a common set of simple tasks that many build configurations rely -on as they become more complex. Most build tools have special -purpose constructs for performing these tasks, but since &SConscript; -files are &Python; scripts, you can use more flexible built-in &Python; -services to perform these tasks. This appendix lists a number of these -tasks and how to implement them in &Python; and &SCons;. -</para> - -<example> -<title>Wildcard globbing to create a list of filenames</title> -<programlisting> -files = Glob(wildcard) -</programlisting> -</example> - -<example> -<title>Filename extension substitution</title> -<programlisting> -import os.path -filename = os.path.splitext(filename)[0]+extension -</programlisting> -</example> - -<example> -<title>Appending a path prefix to a list of filenames</title> -<programlisting> -import os.path -filenames = [os.path.join(prefix, x) for x in filenames] -</programlisting> -</example> - -<example> -<title>Substituting a path prefix with another one</title> -<programlisting> -if filename.find(old_prefix) == 0: - filename = filename.replace(old_prefix, new_prefix) -</programlisting> -</example> - -<example> -<title>Filtering a filename list to exclude/retain only a specific set -of extensions</title> -<programlisting> -import os.path -filenames = [x for x in filenames if os.path.splitext(x)[1] in extensions] -</programlisting> -</example> - -<example> -<title>The "backtick function": run a shell command and capture the -output</title> -<programlisting>import os -output = os.popen(command).read() -</programlisting> -</example> - -<example> -<title>Generating source code: how code can be generated and used by SCons</title> - -<para> - -The Copy builders here could be any arbitrary shell or python function -that produces one or more files. This example shows how to create -those files and use them in &SCons;. - -</para> - -<scons_example name="ex1"> -<file name="SConstruct" printme="1"> -#### SConstruct -env = Environment() -env.Append(CPPPATH = "#") - -## Header example -env.Append(BUILDERS = - {'Copy1' : Builder(action = 'cat < $SOURCE > $TARGET', - suffix='.h', src_suffix='.bar')}) -env.Copy1('test.bar') # produces test.h from test.bar. -env.Program('app','main.cpp') # indirectly depends on test.bar - -## Source file example -env.Append(BUILDERS = - {'Copy2' : Builder(action = 'cat < $SOURCE > $TARGET', - suffix='.cpp', src_suffix='.bar2')}) -foo = env.Copy2('foo.bar2') # produces foo.cpp from foo.bar2. -env.Program('app2',['main2.cpp'] + foo) # compiles main2.cpp and foo.cpp into app2. -</file> - -<file name="main.cpp"> -#include "test.h" -</file> -<file name="test.bar"> -// nothing here -</file> -<file name="main2.cpp"> -//// main2.cpp -</file> -<file name="foo.bar2"> -// nothing here -</file> -</scons_example> - -<para> - -Where main.cpp looks like this: - -</para> - - <scons_example_file example="ex1" name="main.cpp"> - </scons_example_file> - -<para> -produces this: -</para> - - <scons_output example="ex1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - -</example> diff --git a/doc/user/tasks.xml b/doc/user/tasks.xml index b51b3b1..68112a1 100644 --- a/doc/user/tasks.xml +++ b/doc/user/tasks.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<appendix id="app-tasks" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Handling Common Tasks</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -91,25 +112,40 @@ those files and use them in &SCons;. </para> -<programlisting> +<scons_example name="tasks_ex1"> +<file name="SConstruct" printme="1"> #### SConstruct env = Environment() env.Append(CPPPATH = "#") ## Header example env.Append(BUILDERS = - {'Copy1' : Builder(action = 'cat < $SOURCE > $TARGET', + {'Copy1' : Builder(action = 'cat < $SOURCE > $TARGET', suffix='.h', src_suffix='.bar')}) env.Copy1('test.bar') # produces test.h from test.bar. env.Program('app','main.cpp') # indirectly depends on test.bar ## Source file example env.Append(BUILDERS = - {'Copy2' : Builder(action = 'cat < $SOURCE > $TARGET', + {'Copy2' : Builder(action = 'cat < $SOURCE > $TARGET', suffix='.cpp', src_suffix='.bar2')}) foo = env.Copy2('foo.bar2') # produces foo.cpp from foo.bar2. env.Program('app2',['main2.cpp'] + foo) # compiles main2.cpp and foo.cpp into app2. -</programlisting> +</file> + +<file name="main.cpp"> +#include "test.h" +</file> +<file name="test.bar"> +// nothing here +</file> +<file name="main2.cpp"> +//// main2.cpp +</file> +<file name="foo.bar2"> +// nothing here +</file> +</scons_example> <para> @@ -117,21 +153,17 @@ Where main.cpp looks like this: </para> - - <programlisting> -#include "test.h" -</programlisting> + <scons_example_file example="tasks_ex1" name="main.cpp"> + </scons_example_file> <para> produces this: </para> - <screen> - % <userinput>scons -Q</userinput> - cc -o app main.cpp - cat < foo.bar2 > foo.cpp - cc -o app2 main2.cpp foo.cpp - cat < test.bar > test.h - </screen> + <scons_output example="tasks_ex1" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> </example> + +</appendix> diff --git a/doc/user/titlepage/SConsBuildBricks_path.svg b/doc/user/titlepage/SConsBuildBricks_path.svg new file mode 100644 index 0000000..ed0c60d --- /dev/null +++ b/doc/user/titlepage/SConsBuildBricks_path.svg @@ -0,0 +1,320 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="636.73999" + height="80.330002" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.48.1 r9760" + version="1.0" + sodipodi:docname="SConsBuildBricks.svg" + inkscape:export-filename="Constructs-using-SCons.png" + inkscape:export-xdpi="100" + inkscape:export-ydpi="100"> + <defs + id="defs4" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.6603715" + inkscape:cx="80.565423" + inkscape:cy="53.016465" + inkscape:document-units="px" + inkscape:current-layer="layer2" + inkscape:window-width="942" + inkscape:window-height="667" + inkscape:window-x="52" + inkscape:window-y="25" + width="168px" + height="60px" + showgrid="false" + inkscape:window-maximized="0" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + <dc:date>2008-05-18</dc:date> + <dc:creator> + <cc:Agent> + <dc:title>Hartmut Goebel</dc:title> + </cc:Agent> + </dc:creator> + <dc:rights> + <cc:Agent> + <dc:title>Hartmut Goebel <h.goebel@goebel-consult.de></dc:title> + </cc:Agent> + </dc:rights> + <dc:language>en</dc:language> + <dc:subject> + <rdf:Bag> + <rdf:li>SCons</rdf:li> + <rdf:li>software build tool</rdf:li> + <rdf:li>software construction tool</rdf:li> + <rdf:li /> + </rdf:Bag> + </dc:subject> + <dc:contributor> + <cc:Agent> + <dc:title>Based on the pixeled SCons logo (author unknown).</dc:title> + </cc:Agent> + </dc:contributor> + <cc:license + rdf:resource="http://creativecommons.org/licenses/by-nc-sa/2.0/" /> + </cc:Work> + <cc:License + rdf:about="http://creativecommons.org/licenses/by-nc-sa/2.5/"> + <cc:permits + rdf:resource="http://web.resource.org/cc/Reproduction" /> + <cc:permits + rdf:resource="http://web.resource.org/cc/Distribution" /> + <cc:requires + rdf:resource="http://web.resource.org/cc/Notice" /> + <cc:requires + rdf:resource="http://web.resource.org/cc/Attribution" /> + <cc:prohibits + rdf:resource="http://web.resource.org/cc/CommercialUse" /> + <cc:permits + rdf:resource="http://web.resource.org/cc/DerivativeWorks" /> + <cc:requires + rdf:resource="http://web.resource.org/cc/ShareAlike" /> + </cc:License> + </rdf:RDF> + </metadata> + <g + inkscape:label="Ebene 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-264.3227,-503.6795)" + inkscape:export-filename="SCons.png" + style="display:inline" /> + <g + inkscape:groupmode="layer" + id="layer2" + inkscape:label="Constructs" + style="display:inline"> + <g + transform="translate(-264.04696,-505.06832)" + style="display:inline" + id="Brick-to-Brick-9" + inkscape:label="#g2189" + inkscape:export-filename="SCons-Bricks.png"> + <rect + y="552.24042" + x="296.28955" + height="8.3218126" + width="25.570662" + id="rect2170-4" + style="fill:#cf291c;fill-opacity:1;stroke:#000000;stroke-width:1.4000001;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + y="552.24042" + x="267.02267" + height="8.3218126" + width="25.570662" + id="rect3143-1" + style="fill:#cf291c;fill-opacity:1;stroke:#000000;stroke-width:1.4000001;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + y="540.14984" + x="267.02267" + height="8.3218126" + width="13.012291" + id="rect3145-9" + style="fill:#cf291c;fill-opacity:1;stroke:#000000;stroke-width:1.40000021;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + y="540.14984" + x="308.84793" + height="8.3218126" + width="13.012291" + id="rect3147-5" + style="fill:#cf291c;fill-opacity:1;stroke:#000000;stroke-width:1.40000021;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + transform="matrix(0.905934,0.423418,-0.423418,0.905934,0,0)" + y="335.94952" + x="480.29761" + height="8.3219995" + width="23" + id="rect3149-7" + style="fill:#cf291c;fill-opacity:1;stroke:#000000;stroke-width:1.4000001;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" /> + <g + id="g2185-4"> + <path + style="fill:none;stroke:#000000;stroke-width:4;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:1;stroke-opacity:1;stroke-dasharray:none;marker-start:none;marker-end:none" + d="m 297.75417,522.67403 c -3.0064,6.09106 -3.82029,6.65046 -3.12294,18.68449" + id="path3155-1" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <path + sodipodi:type="star" + style="fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:2.56573844;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:1;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path8218-2" + sodipodi:sides="3" + sodipodi:cx="269.17282" + sodipodi:cy="490.86679" + sodipodi:r1="14.074683" + sodipodi:r2="14.074683" + sodipodi:arg1="1.5922984" + sodipodi:arg2="-2.6531172" + inkscape:flatsided="false" + inkscape:rounded="0" + inkscape:randomized="0" + d="m 268.87021,504.93822 -12.12603,-20.6764 0.39373,-0.69281 23.9693,-0.16325 0.40313,0.68739 -11.84327,20.83964 z" + transform="matrix(0.370735,0,0,0.409743,194.6666,341.5009)" /> + </g> + </g> + <g + style="font-size:12.22589397px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans;-inkscape-font-specification:DejaVu Sans" + id="text1316-2" + transform="translate(0.27574335,-0.05632028)"> + <path + d="m 3.8227174,71.530541 0,3.265412 1.9341746,0 c 0.6486997,10e-7 1.1282631,-0.133322 1.4386916,-0.399969 0.3143968,-0.270623 0.4715981,-0.68253 0.4716043,-1.235722 C 7.6671817,72.603095 7.5099804,72.193178 7.1955836,71.930509 6.8851551,71.663867 6.4055917,71.530545 5.756892,71.530541 l -1.9341746,0 m 0,-3.665381 0,2.686354 1.7849327,0 c 0.5890032,5e-6 1.0267789,-0.109439 1.3133285,-0.328332 C 7.211497,70.00032 7.3567589,69.662038 7.3567648,69.208337 7.3567589,68.758629 7.211497,68.422337 6.9209786,68.199462 6.634429,67.976602 6.1966533,67.865168 5.6076501,67.86516 l -1.7849327,0 m -1.2058743,-0.990966 3.0803522,0 c 0.9193247,9e-6 1.6277254,0.191038 2.1252042,0.573089 0.497466,0.382067 0.7462022,0.925307 0.7462093,1.629721 -7.1e-6,0.545237 -0.1273601,0.979033 -0.3820592,1.301389 -0.2547126,0.322368 -0.6288118,0.523347 -1.1222988,0.602937 0.5929814,0.127358 1.0526459,0.394003 1.3789949,0.799937 0.3303146,0.401962 0.4954754,0.905404 0.495483,1.510328 -7.6e-6,0.795958 -0.2706325,1.410834 -0.8118758,1.844629 -0.5412567,0.433797 -1.311344,0.650695 -2.3102642,0.650695 l -3.1997456,0 0,-8.912725" + id="path3187" + inkscape:connector-curvature="0" /> + <path + d="m 10.837085,73.148322 0,-4.047439 1.09842,0 0,4.005652 c -2e-6,0.632787 0.123371,1.108371 0.37012,1.426752 0.246744,0.314404 0.616863,0.471605 1.110359,0.471604 0.592984,10e-7 1.060608,-0.189038 1.402874,-0.567119 0.346236,-0.378078 0.519356,-0.893459 0.519362,-1.546146 l 0,-3.790743 1.09842,0 0,6.686036 -1.09842,0 0,-1.026784 c -0.266651,0.405938 -0.577074,0.708401 -0.93127,0.90739 -0.350225,0.195009 -0.758152,0.292514 -1.223783,0.292514 -0.768101,0 -1.351138,-0.238787 -1.749115,-0.716361 -0.397979,-0.477573 -0.596968,-1.176024 -0.596967,-2.095356 m 2.763959,-4.20862 0,0" + id="path3189" + inkscape:connector-curvature="0" /> + <path + d="m 18.711086,69.100883 1.09842,0 0,6.686036 -1.09842,0 0,-6.686036 m 0,-2.602778 1.09842,0 0,1.390934 -1.09842,0 0,-1.390934" + id="path3191" + inkscape:connector-curvature="0" /> + <path + d="m 22.101862,66.498105 1.09842,0 0,9.288814 -1.09842,0 0,-9.288814" + id="path3193" + inkscape:connector-curvature="0" /> + <path + d="m 29.892286,70.115728 0,-3.617623 1.09842,0 0,9.288814 -1.09842,0 0,-1.002906 c -0.230833,0.397979 -0.523347,0.694473 -0.877543,0.889482 -0.350225,0.191029 -0.772081,0.286544 -1.265571,0.286544 -0.807898,0 -1.466552,-0.322362 -1.975962,-0.967087 -0.505433,-0.644724 -0.758149,-1.492417 -0.758149,-2.543082 0,-1.050658 0.252716,-1.898351 0.758149,-2.543081 0.50941,-0.644718 1.168064,-0.96708 1.975962,-0.967087 0.49349,7e-6 0.915346,0.09751 1.265571,0.292514 0.354196,0.191036 0.64671,0.485539 0.877543,0.883512 M 26.1493,72.44987 c -2e-6,0.807899 0.165159,1.442674 0.495483,1.904327 0.334299,0.457676 0.791973,0.686513 1.373025,0.686512 0.581044,10e-7 1.038718,-0.228836 1.373025,-0.686512 0.334296,-0.461653 0.501447,-1.096428 0.501453,-1.904327 -6e-6,-0.807891 -0.167157,-1.440676 -0.501453,-1.898356 -0.334307,-0.461649 -0.791981,-0.692477 -1.373025,-0.692482 -0.581052,5e-6 -1.038726,0.230833 -1.373025,0.692482 -0.330324,0.45768 -0.495485,1.090465 -0.495483,1.898356" + id="path3195" + inkscape:connector-curvature="0" /> + <path + d="m 39.927309,76.407765 c -0.310427,0.795955 -0.61289,1.315316 -0.90739,1.558085 -0.294507,0.242764 -0.688505,0.364148 -1.181996,0.36415 l -0.877542,0 0,-0.91933 0.644725,0 c 0.302461,-10e-7 0.537268,-0.07164 0.704421,-0.214908 0.167149,-0.143274 0.352208,-0.481555 0.55518,-1.014845 l 0.196999,-0.501453 -2.704262,-6.578581 1.164086,0 2.089386,5.229435 2.089387,-5.229435 1.164086,0 -2.93708,7.306882" + id="path3197" + inkscape:connector-curvature="0" /> + <path + d="m 46.971524,69.870971 c -0.589011,6e-6 -1.054645,0.230833 -1.396904,0.692482 -0.342263,0.45768 -0.513394,1.086485 -0.513392,1.886417 -2e-6,0.799939 0.169139,1.430734 0.507423,1.892387 0.342258,0.457676 0.809882,0.686514 1.402873,0.686513 0.585024,1e-6 1.048668,-0.230826 1.390934,-0.692482 0.342256,-0.461653 0.513387,-1.090458 0.513393,-1.886418 -6e-6,-0.791972 -0.171137,-1.418788 -0.513393,-1.880447 -0.342266,-0.465629 -0.80591,-0.698446 -1.390934,-0.698452 m 0,-0.931269 c 0.955144,7e-6 1.705332,0.310429 2.250568,0.931269 0.545223,0.620851 0.817838,1.480484 0.817845,2.578899 -7e-6,1.094443 -0.272622,1.954075 -0.817845,2.5789 -0.545236,0.620846 -1.295424,0.931269 -2.250568,0.931269 -0.95913,0 -1.711309,-0.310423 -2.256537,-0.931269 -0.541251,-0.624825 -0.811876,-1.484457 -0.811876,-2.5789 0,-1.098415 0.270625,-1.958048 0.811876,-2.578899 0.545228,-0.62084 1.297407,-0.931262 2.256537,-0.931269" + id="path3199" + inkscape:connector-curvature="0" /> + <path + d="m 51.741295,73.148322 0,-4.047439 1.09842,0 0,4.005652 c -2e-6,0.632787 0.123371,1.108371 0.37012,1.426752 0.246744,0.314404 0.616863,0.471605 1.110359,0.471604 0.592984,10e-7 1.060608,-0.189038 1.402874,-0.567119 0.346236,-0.378078 0.519356,-0.893459 0.519362,-1.546146 l 0,-3.790743 1.09842,0 0,6.686036 -1.09842,0 0,-1.026784 c -0.266651,0.405938 -0.577074,0.708401 -0.93127,0.90739 -0.350225,0.195009 -0.758152,0.292514 -1.223783,0.292514 -0.768101,0 -1.351138,-0.238787 -1.749115,-0.716361 -0.397979,-0.477573 -0.596968,-1.176024 -0.596967,-2.095356 m 2.763959,-4.20862 0,0" + id="path3201" + inkscape:connector-curvature="0" /> + <path + d="m 63.489616,70.127667 c -0.123378,-0.07163 -0.258691,-0.123368 -0.405938,-0.155212 -0.143277,-0.03581 -0.302468,-0.05372 -0.477574,-0.05373 -0.62085,6e-6 -1.098423,0.202975 -1.432722,0.608907 -0.330324,0.401963 -0.495485,0.981021 -0.495483,1.737176 l 0,3.522108 -1.10439,0 0,-6.686036 1.10439,0 0,1.038723 c 0.230825,-0.405932 0.531298,-0.706405 0.901421,-0.901421 0.370116,-0.198982 0.819831,-0.298476 1.349146,-0.298483 0.07561,7e-6 0.159187,0.006 0.250727,0.01791 0.09153,0.008 0.193014,0.0219 0.304453,0.04179 l 0.006,1.128269" + id="path3203" + inkscape:connector-curvature="0" /> + <path + d="m 72.808278,69.297882 0,1.038724 c -0.310428,-0.159186 -0.63279,-0.27858 -0.967087,-0.358181 -0.334306,-0.07959 -0.680547,-0.119388 -1.038723,-0.119393 -0.545234,5e-6 -0.955151,0.08358 -1.229753,0.250726 -0.270628,0.167156 -0.40594,0.417882 -0.405938,0.752179 -2e-6,0.254711 0.0975,0.45569 0.292514,0.602937 0.195007,0.143276 0.587015,0.280579 1.176026,0.411908 l 0.376089,0.08357 c 0.780033,0.167155 1.333223,0.403952 1.65957,0.710391 0.330316,0.302467 0.495477,0.726313 0.495483,1.271541 -6e-6,0.620848 -0.246752,1.11235 -0.74024,1.47451 -0.489518,0.36216 -1.16409,0.54324 -2.02372,0.54324 -0.358183,0 -0.732282,-0.03582 -1.122299,-0.107454 -0.38604,-0.06766 -0.793967,-0.171131 -1.223783,-0.310423 l 0,-1.134238 c 0.405937,0.210929 0.805905,0.370121 1.199905,0.477574 0.393996,0.103475 0.784014,0.155212 1.170056,0.155211 0.517368,10e-7 0.915346,-0.08755 1.193935,-0.262665 0.27858,-0.179089 0.417873,-0.429816 0.417877,-0.752179 -4e-6,-0.298482 -0.101489,-0.527319 -0.304453,-0.686513 -0.198994,-0.159189 -0.638759,-0.31241 -1.319298,-0.459665 l -0.38206,-0.08955 c -0.680544,-0.143269 -1.172047,-0.362157 -1.474509,-0.656664 -0.302465,-0.29848 -0.453696,-0.706407 -0.453695,-1.223784 -10e-7,-0.6288 0.222866,-1.114333 0.668603,-1.4566 0.445734,-0.342255 1.078519,-0.513385 1.898357,-0.513392 0.405934,7e-6 0.787993,0.02985 1.146177,0.08955 0.358176,0.0597 0.688498,0.149248 0.990966,0.268635" + id="path3205" + inkscape:connector-curvature="0" /> + <path + d="m 77.51238,69.870971 c -0.589011,6e-6 -1.054646,0.230833 -1.396904,0.692482 -0.342264,0.45768 -0.513394,1.086485 -0.513392,1.886417 -2e-6,0.799939 0.169139,1.430734 0.507422,1.892387 0.342259,0.457676 0.809883,0.686514 1.402874,0.686513 0.585023,1e-6 1.048668,-0.230826 1.390934,-0.692482 0.342256,-0.461653 0.513386,-1.090458 0.513392,-1.886418 -6e-6,-0.791972 -0.171136,-1.418788 -0.513392,-1.880447 -0.342266,-0.465629 -0.805911,-0.698446 -1.390934,-0.698452 m 0,-0.931269 c 0.955143,7e-6 1.705331,0.310429 2.250567,0.931269 0.545224,0.620851 0.817839,1.480484 0.817846,2.578899 -7e-6,1.094443 -0.272622,1.954075 -0.817846,2.5789 -0.545236,0.620846 -1.295424,0.931269 -2.250567,0.931269 -0.959131,0 -1.711309,-0.310423 -2.256537,-0.931269 -0.541252,-0.624825 -0.811877,-1.484457 -0.811876,-2.5789 -10e-7,-1.098415 0.270624,-1.958048 0.811876,-2.578899 0.545228,-0.62084 1.297406,-0.931262 2.256537,-0.931269" + id="path3207" + inkscape:connector-curvature="0" /> + <path + d="m 85.780384,66.498105 0,0.91336 -1.050663,0 c -0.394002,8e-6 -0.668607,0.0796 -0.823815,0.238787 -0.151235,0.159199 -0.22685,0.445743 -0.226848,0.859633 l 0,0.590998 1.808812,0 0,0.853663 -1.808812,0 0,5.832373 -1.10439,0 0,-5.832373 -1.050663,0 0,-0.853663 1.050663,0 0,-0.465635 c -10e-7,-0.744211 0.173119,-1.285461 0.519362,-1.623751 0.346239,-0.342253 0.895448,-0.513383 1.64763,-0.513392 l 1.038724,0" + id="path3209" + inkscape:connector-curvature="0" /> + <path + d="m 87.565311,67.202526 0,1.898357 2.262506,0 0,0.853663 -2.262506,0 0,3.629563 c -3e-6,0.545232 0.07362,0.895452 0.220878,1.050662 0.151229,0.155213 0.455682,0.232819 0.91336,0.232818 l 1.128268,0 0,0.91933 -1.128268,0 c -0.847696,0 -1.432724,-0.157202 -1.755084,-0.471605 -0.322364,-0.318382 -0.483545,-0.89545 -0.483544,-1.731205 l 0,-3.629563 -0.805906,0 0,-0.853663 0.805906,0 0,-1.898357 1.10439,0" + id="path3211" + inkscape:connector-curvature="0" /> + <path + d="m 90.639696,69.100883 1.09842,0 1.373026,5.217496 1.367055,-5.217496 1.29542,0 1.373025,5.217496 1.367055,-5.217496 1.098421,0 -1.749115,6.686036 -1.29542,0 -1.438691,-5.480162 -1.444662,5.480162 -1.295419,0 -1.749115,-6.686036" + id="path3213" + inkscape:connector-curvature="0" /> + <path + d="m 104.32219,72.425992 c -0.8875,3e-6 -1.50237,0.101487 -1.84463,0.304453 -0.34226,0.202972 -0.51339,0.549213 -0.51339,1.038724 0,0.39002 0.12735,0.700443 0.38206,0.931269 0.25868,0.226848 0.6089,0.340272 1.05066,0.340271 0.6089,10e-7 1.09643,-0.214907 1.46257,-0.644725 0.37011,-0.433794 0.55517,-1.008872 0.55518,-1.725236 l 0,-0.244756 -1.09245,0 m 2.19087,-0.453696 0,3.814623 -1.09842,0 0,-1.014845 c -0.25073,0.405938 -0.56314,0.706412 -0.93724,0.901421 -0.3741,0.191029 -0.83178,0.286544 -1.37302,0.286544 -0.68453,0 -1.22976,-0.191029 -1.6357,-0.573089 -0.40195,-0.386038 -0.60293,-0.901419 -0.60293,-1.546145 0,-0.752177 0.25072,-1.319295 0.75218,-1.701358 0.50543,-0.382055 1.2576,-0.573084 2.25653,-0.573088 l 1.54018,0 0,-0.107455 c -1e-5,-0.505427 -0.16716,-0.895446 -0.50145,-1.170056 -0.33033,-0.278579 -0.79596,-0.417871 -1.39691,-0.417877 -0.38206,6e-6 -0.75417,0.04577 -1.11633,0.137302 -0.36216,0.09154 -0.71039,0.228844 -1.04469,0.411908 l 0,-1.014845 c 0.40196,-0.155205 0.79198,-0.270618 1.17006,-0.346241 0.37807,-0.07959 0.7462,-0.119386 1.10439,-0.119393 0.96708,7e-6 1.68941,0.250733 2.16699,0.752179 0.47757,0.501458 0.71635,1.261596 0.71636,2.280415" + id="path3215" + inkscape:connector-curvature="0" /> + <path + d="m 112.65586,70.127667 c -0.12338,-0.07163 -0.25869,-0.123368 -0.40594,-0.155212 -0.14327,-0.03581 -0.30247,-0.05372 -0.47757,-0.05373 -0.62085,6e-6 -1.09842,0.202975 -1.43272,0.608907 -0.33033,0.401963 -0.49549,0.981021 -0.49549,1.737176 l 0,3.522108 -1.10439,0 0,-6.686036 1.10439,0 0,1.038723 c 0.23083,-0.405932 0.5313,-0.706405 0.90142,-0.901421 0.37012,-0.198982 0.81984,-0.298476 1.34915,-0.298483 0.0756,7e-6 0.15919,0.006 0.25073,0.01791 0.0915,0.008 0.19301,0.0219 0.30445,0.04179 l 0.006,1.128269" + id="path3217" + inkscape:connector-curvature="0" /> + <path + d="m 119.27622,72.169296 0,0.53727 -5.05034,0 c 0.0477,0.756162 0.2746,1.33323 0.68054,1.731206 0.40992,0.394 0.97903,0.590999 1.70733,0.590998 0.42185,1e-6 0.82978,-0.05174 1.22378,-0.155212 0.39797,-0.103473 0.79197,-0.258684 1.182,-0.465634 l 0,1.038723 c -0.39401,0.167151 -0.79795,0.294504 -1.21185,0.382059 -0.4139,0.08756 -0.83377,0.131333 -1.2596,0.131333 -1.06658,0 -1.91229,-0.310423 -2.53711,-0.931269 -0.62085,-0.620845 -0.93127,-1.460578 -0.93127,-2.519203 0,-1.094436 0.2945,-1.962028 0.88351,-2.602778 0.59299,-0.644718 1.39093,-0.96708 2.39384,-0.967087 0.89943,7e-6 1.60982,0.29053 2.13118,0.871572 0.52532,0.577074 0.78799,1.363081 0.78799,2.358022 m -1.09842,-0.322363 c -0.008,-0.600942 -0.1771,-1.080506 -0.50742,-1.438691 -0.32635,-0.358175 -0.76014,-0.537265 -1.30139,-0.537271 -0.61289,6e-6 -1.10439,0.173126 -1.47451,0.519362 -0.36614,0.346246 -0.57707,0.833769 -0.63278,1.46257 l 3.9161,-0.006" + id="path3219" + inkscape:connector-curvature="0" /> + <path + d="m 121.35964,74.270621 1.2596,0 0,1.026784 -0.97903,1.910296 -0.77008,0 0.48951,-1.910296 0,-1.026784" + id="path3221" + inkscape:connector-curvature="0" /> + <path + d="m 133.66315,72.44987 c -1e-5,-0.807891 -0.16716,-1.440676 -0.50146,-1.898356 -0.33032,-0.461649 -0.78601,-0.692477 -1.36705,-0.692482 -0.58105,5e-6 -1.03873,0.230833 -1.37303,0.692482 -0.33032,0.45768 -0.49548,1.090465 -0.49548,1.898356 0,0.807899 0.16516,1.442674 0.49548,1.904327 0.3343,0.457676 0.79198,0.686513 1.37303,0.686512 0.58104,10e-7 1.03673,-0.228836 1.36705,-0.686512 0.3343,-0.461653 0.50145,-1.096428 0.50146,-1.904327 m -3.73702,-2.334142 c 0.23082,-0.397973 0.52135,-0.692476 0.87157,-0.883512 0.3542,-0.195003 0.77606,-0.292507 1.26557,-0.292514 0.81187,7e-6 1.47053,0.322369 1.97596,0.967087 0.50941,0.64473 0.76412,1.492423 0.76412,2.543081 0,1.050665 -0.25471,1.898358 -0.76412,2.543082 -0.50543,0.644725 -1.16409,0.967087 -1.97596,0.967087 -0.48951,0 -0.91137,-0.09551 -1.26557,-0.286544 -0.35022,-0.195009 -0.64075,-0.491503 -0.87157,-0.889482 l 0,1.002906 -1.10439,0 0,-9.288814 1.10439,0 0,3.617623" + id="path3223" + inkscape:connector-curvature="0" /> + <path + d="m 142.34306,72.169296 0,0.53727 -5.05035,0 c 0.0478,0.756162 0.27461,1.33323 0.68055,1.731206 0.40991,0.394 0.97902,0.590999 1.70732,0.590998 0.42185,1e-6 0.82978,-0.05174 1.22379,-0.155212 0.39797,-0.103473 0.79197,-0.258684 1.18199,-0.465634 l 0,1.038723 c -0.394,0.167151 -0.79795,0.294504 -1.21184,0.382059 -0.41391,0.08756 -0.83377,0.131333 -1.2596,0.131333 -1.06659,0 -1.91229,-0.310423 -2.53712,-0.931269 -0.62084,-0.620845 -0.93127,-1.460578 -0.93127,-2.519203 0,-1.094436 0.29451,-1.962028 0.88352,-2.602778 0.59298,-0.644718 1.39093,-0.96708 2.39384,-0.967087 0.89942,7e-6 1.60981,0.29053 2.13117,0.871572 0.52533,0.577074 0.78799,1.363081 0.788,2.358022 m -1.09842,-0.322363 c -0.008,-0.600942 -0.17711,-1.080506 -0.50743,-1.438691 -0.32634,-0.358175 -0.76014,-0.537265 -1.30138,-0.537271 -0.61289,6e-6 -1.1044,0.173126 -1.47451,0.519362 -0.36615,0.346246 -0.57707,0.833769 -0.63279,1.46257 l 3.91611,-0.006" + id="path3225" + inkscape:connector-curvature="0" /> + <path + d="m 145.23238,67.202526 0,1.898357 2.26251,0 0,0.853663 -2.26251,0 0,3.629563 c 0,0.545232 0.0736,0.895452 0.22088,1.050662 0.15123,0.155213 0.45568,0.232819 0.91336,0.232818 l 1.12827,0 0,0.91933 -1.12827,0 c -0.8477,0 -1.43273,-0.157202 -1.75509,-0.471605 -0.32236,-0.318382 -0.48354,-0.89545 -0.48354,-1.731205 l 0,-3.629563 -0.80591,0 0,-0.853663 0.80591,0 0,-1.898357 1.10439,0" + id="path3227" + inkscape:connector-curvature="0" /> + <path + d="m 150.03199,67.202526 0,1.898357 2.2625,0 0,0.853663 -2.2625,0 0,3.629563 c -1e-5,0.545232 0.0736,0.895452 0.22087,1.050662 0.15123,0.155213 0.45569,0.232819 0.91336,0.232818 l 1.12827,0 0,0.91933 -1.12827,0 c -0.84769,0 -1.43272,-0.157202 -1.75508,-0.471605 -0.32236,-0.318382 -0.48355,-0.89545 -0.48354,-1.731205 l 0,-3.629563 -0.80591,0 0,-0.853663 0.80591,0 0,-1.898357 1.10439,0" + id="path3229" + inkscape:connector-curvature="0" /> + <path + d="m 159.46407,72.169296 0,0.53727 -5.05034,0 c 0.0478,0.756162 0.2746,1.33323 0.68054,1.731206 0.40992,0.394 0.97903,0.590999 1.70733,0.590998 0.42185,1e-6 0.82978,-0.05174 1.22378,-0.155212 0.39798,-0.103473 0.79197,-0.258684 1.182,-0.465634 l 0,1.038723 c -0.39401,0.167151 -0.79795,0.294504 -1.21185,0.382059 -0.4139,0.08756 -0.83376,0.131333 -1.2596,0.131333 -1.06658,0 -1.91228,-0.310423 -2.53711,-0.931269 -0.62085,-0.620845 -0.93127,-1.460578 -0.93127,-2.519203 0,-1.094436 0.29451,-1.962028 0.88351,-2.602778 0.59299,-0.644718 1.39094,-0.96708 2.39384,-0.967087 0.89943,7e-6 1.60982,0.29053 2.13118,0.871572 0.52532,0.577074 0.78799,1.363081 0.78799,2.358022 m -1.09842,-0.322363 c -0.008,-0.600942 -0.1771,-1.080506 -0.50742,-1.438691 -0.32634,-0.358175 -0.76014,-0.537265 -1.30139,-0.537271 -0.61289,6e-6 -1.10439,0.173126 -1.47451,0.519362 -0.36614,0.346246 -0.57707,0.833769 -0.63278,1.46257 l 3.9161,-0.006" + id="path3231" + inkscape:connector-curvature="0" /> + <path + d="m 165.14123,70.127667 c -0.12337,-0.07163 -0.25869,-0.123368 -0.40593,-0.155212 -0.14328,-0.03581 -0.30247,-0.05372 -0.47758,-0.05373 -0.62085,6e-6 -1.09842,0.202975 -1.43272,0.608907 -0.33032,0.401963 -0.49548,0.981021 -0.49548,1.737176 l 0,3.522108 -1.10439,0 0,-6.686036 1.10439,0 0,1.038723 c 0.23082,-0.405932 0.5313,-0.706405 0.90142,-0.901421 0.37012,-0.198982 0.81983,-0.298476 1.34915,-0.298483 0.0756,7e-6 0.15918,0.006 0.25072,0.01791 0.0915,0.008 0.19302,0.0219 0.30446,0.04179 l 0.006,1.128269" + id="path3233" + inkscape:connector-curvature="0" /> + <path + d="m 165.33823,74.270621 1.25961,0 0,1.516298 -1.25961,0 0,-1.516298" + id="path3235" + inkscape:connector-curvature="0" /> + </g> + <g + transform="matrix(1.0124967,0,0,0.98765755,0.27574335,-0.05632028)" + style="font-size:28.4279995px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:semi-condensed;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;display:inline;font-family:DejaVu Serif;-inkscape-font-specification:DejaVu Serif Bold Semi-Condensed" + id="text10160-1"> + <path + d="m 64.462518,55.550974 0,-4.913824 1.582418,0 c 0.249852,1.554661 0.823593,2.716025 1.721226,3.484096 0.897623,0.768075 2.142272,1.152112 3.733952,1.152111 1.286282,1e-6 2.267195,-0.272989 2.942742,-0.818971 0.675522,-0.545978 1.013289,-1.34644 1.013302,-2.401388 -1.3e-5,-0.832847 -0.23136,-1.480619 -0.694043,-1.943321 -0.453453,-0.462688 -1.39735,-0.892994 -2.831695,-1.29092 L 69.140368,48.05531 c -1.823025,-0.51821 -3.10469,-1.235387 -3.844998,-2.151533 -0.740315,-0.925379 -1.110471,-2.239432 -1.110469,-3.942164 -2e-6,-2.05435 0.610755,-3.650648 1.832273,-4.788896 1.230765,-1.147464 2.95199,-1.721206 5.16368,-1.721227 1.091951,2.1e-5 2.225553,0.101814 3.40081,0.305379 1.184487,0.203607 2.410628,0.508985 3.678428,0.916137 l 0,4.580683 -1.582418,0 c -0.249869,-1.425085 -0.781968,-2.466148 -1.596299,-3.123193 -0.814355,-0.666262 -1.975719,-0.999403 -3.484095,-0.999422 -1.230778,1.9e-5 -2.160794,0.240621 -2.790053,0.721805 -0.629271,0.471967 -0.943904,1.17989 -0.943899,2.123771 -5e-6,0.860629 0.217462,1.517656 0.652401,1.971082 0.434927,0.444202 1.494498,0.906897 3.178717,1.388086 l 2.803933,0.763447 c 1.730467,0.481215 2.98437,1.230781 3.761713,2.2487 0.777312,1.017938 1.165975,2.419904 1.165992,4.2059 -1.7e-5,2.091387 -0.64779,3.683057 -1.94332,4.775015 -1.295561,1.082708 -3.20649,1.62406 -5.732795,1.624061 -1.21227,-1e-6 -2.419903,-0.115674 -3.622904,-0.347022 -1.203012,-0.231347 -2.424527,-0.582995 -3.664547,-1.054945" + id="path3176" + inkscape:connector-curvature="0" /> + <path + d="m 100.03916,50.63715 c -0.490476,2.137656 -1.374224,3.724699 -2.651245,4.761135 -1.2678,1.036437 -2.975144,1.554655 -5.122037,1.554656 -3.15559,-1e-6 -5.649515,-0.962406 -7.481783,-2.887219 -1.823021,-1.934062 -2.73453,-4.552915 -2.734529,-7.856566 -10e-7,-3.312885 0.911508,-5.931738 2.734529,-7.856566 1.832268,-1.934047 4.326193,-2.901079 7.481783,-2.9011 1.101203,2.1e-5 2.253313,0.148084 3.456334,0.444188 1.202992,0.296145 2.470776,0.744959 3.803355,1.346443 l 0,5.094275 -1.582418,0 c -0.323903,-1.739718 -0.916152,-3.039891 -1.77675,-3.900521 -0.851373,-0.869848 -1.980349,-1.304782 -3.386929,-1.304801 -1.82303,1.9e-5 -3.174099,0.744958 -4.053211,2.234818 -0.879128,1.480641 -1.318688,3.761727 -1.318682,6.843264 -6e-6,3.081558 0.439554,5.362643 1.318682,6.843263 0.879112,1.480627 2.234808,2.220939 4.067092,2.220938 1.249264,1e-6 2.267193,-0.384036 3.053789,-1.152111 0.786566,-0.768071 1.355681,-1.929435 1.707345,-3.484096 l 2.484675,0" + id="path3178" + inkscape:connector-curvature="0" /> + <path + d="m 112.49029,55.273357 c 1.59166,1e-6 2.77153,-0.744937 3.53962,-2.234818 0.77731,-1.489874 1.16598,-3.766333 1.16599,-6.829383 -10e-6,-3.072283 -0.38868,-5.353369 -1.16599,-6.843264 -0.76809,-1.48986 -1.94796,-2.234799 -3.53962,-2.234818 -1.58243,1.9e-5 -2.7623,0.754212 -3.53962,2.26258 -0.77733,1.499149 -1.166,3.77098 -1.16599,6.815502 -10e-6,3.035288 0.38866,5.30712 1.16599,6.815502 0.77732,1.499135 1.95719,2.2487 3.53962,2.248699 m 0,1.679584 c -3.13708,-1e-6 -5.59862,-0.953152 -7.38462,-2.859457 -1.786,-1.9063 -2.679,-4.534407 -2.679,-7.884328 0,-3.3499 0.893,-5.978007 2.679,-7.884328 1.79526,-1.915538 4.25679,-2.873317 7.38462,-2.873338 3.13706,2.1e-5 5.59397,0.953173 7.37074,2.859457 1.78598,1.906321 2.67898,4.539055 2.679,7.898209 -2e-5,3.349921 -0.89302,5.978028 -2.679,7.884328 -1.78602,1.906305 -4.24293,2.859456 -7.37074,2.859457" + id="path3180" + inkscape:connector-curvature="0" /> + <path + d="m 124.74709,56.550396 0,-1.679584 2.38751,0 0,-17.364955 -2.38751,0 0,-1.679584 5.82996,0 11.25738,14.672068 0,-12.992484 -2.37363,0 0,-1.679584 6.524,0 0,1.679584 -2.38751,0 0,19.044539 -3.27588,0 -11.42395,-14.977447 0,13.297863 2.37363,0 0,1.679584 -6.524,0" + id="path3182" + inkscape:connector-curvature="0" /> + <path + d="m 148.96919,55.550974 0,-4.913824 1.58241,0 c 0.24986,1.554661 0.8236,2.716025 1.72123,3.484096 0.89762,0.768075 2.14227,1.152112 3.73395,1.152111 1.28628,1e-6 2.2672,-0.272989 2.94274,-0.818971 0.67553,-0.545978 1.01329,-1.34644 1.01331,-2.401388 -2e-5,-0.832847 -0.23136,-1.480619 -0.69405,-1.943321 -0.45345,-0.462688 -1.39735,-0.892994 -2.83169,-1.29092 l -2.79005,-0.763447 c -1.82303,-0.51821 -3.10469,-1.235387 -3.845,-2.151533 -0.74032,-0.925379 -1.11047,-2.239432 -1.11047,-3.942164 0,-2.05435 0.61075,-3.650648 1.83227,-4.788896 1.23077,-1.147464 2.95199,-1.721206 5.16368,-1.721227 1.09195,2.1e-5 2.22556,0.101814 3.40081,0.305379 1.18449,0.203607 2.41063,0.508985 3.67843,0.916137 l 0,4.580683 -1.58242,0 c -0.24987,-1.425085 -0.78197,-2.466148 -1.5963,-3.123193 -0.81435,-0.666262 -1.97572,-0.999403 -3.48409,-0.999422 -1.23078,1.9e-5 -2.1608,0.240621 -2.79006,0.721805 -0.62927,0.471967 -0.9439,1.17989 -0.94389,2.123771 -1e-5,0.860629 0.21746,1.517656 0.6524,1.971082 0.43492,0.444202 1.4945,0.906897 3.17871,1.388086 l 2.80394,0.763447 c 1.73046,0.481215 2.98437,1.230781 3.76171,2.2487 0.77731,1.017938 1.16598,2.419904 1.16599,4.2059 -1e-5,2.091387 -0.64779,3.683057 -1.94332,4.775015 -1.29556,1.082708 -3.20649,1.62406 -5.73279,1.624061 -1.21227,-1e-6 -2.41991,-0.115674 -3.62291,-0.347022 -1.20301,-0.231347 -2.42452,-0.582995 -3.66454,-1.054945" + id="path3184" + inkscape:connector-curvature="0" /> + </g> + <image + id="image1340" + height="80.018639" + width="465.43411" + sodipodi:absref="bricks.jpg" + xlink:href="bricks.jpg" + x="171.31058" + y="0.17131744" /> + </g> +</svg> diff --git a/doc/user/titlepage/SCons_path.svg b/doc/user/titlepage/SCons_path.svg new file mode 100644 index 0000000..ef580ee --- /dev/null +++ b/doc/user/titlepage/SCons_path.svg @@ -0,0 +1,196 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="167.9814" + height="58.247482" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.48.3.1 r9886" + version="1.0" + sodipodi:docname="SCons_path.svg" + inkscape:export-filename="Constructs-using-SCons.png" + inkscape:export-xdpi="100" + inkscape:export-ydpi="100"> + <title + id="title2996">SCons - Build your software, better (SCons Logo)</title> + <defs + id="defs4" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.6603715" + inkscape:cx="7.1635215" + inkscape:cy="31.742841" + inkscape:document-units="px" + inkscape:current-layer="layer2" + inkscape:window-width="868" + inkscape:window-height="789" + inkscape:window-x="210" + inkscape:window-y="24" + width="168px" + height="60px" + showgrid="false" + inkscape:window-maximized="0" + fit-margin-left="2" + fit-margin-top="2" + fit-margin-right="2" + fit-margin-bottom="2" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title>SCons - Build your software, better (SCons Logo)</dc:title> + <dc:date>2011-05-19</dc:date> + <dc:creator> + <cc:Agent> + <dc:title>Dirk Baechle</dc:title> + </cc:Agent> + </dc:creator> + <dc:rights> + <cc:Agent> + <dc:title>Dirk Baechle <dl9obn@darc.de></dc:title> + </cc:Agent> + </dc:rights> + <dc:language>en</dc:language> + <dc:subject> + <rdf:Bag> + <rdf:li>SCons</rdf:li> + <rdf:li>software build tool</rdf:li> + <rdf:li>software construction tool</rdf:li> + <rdf:li /> + </rdf:Bag> + </dc:subject> + <dc:contributor> + <cc:Agent> + <dc:title>Based on the SCons (Constructs using) logo by Hartmut Goebel <h.goebel@goebel-consult.de>.</dc:title> + </cc:Agent> + </dc:contributor> + <cc:license + rdf:resource="" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Ebene 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-264.32267,-503.68225)" + inkscape:export-filename="SCons.png" + style="display:inline" /> + <g + inkscape:groupmode="layer" + id="layer2" + inkscape:label="Constructs" + style="display:inline" + transform="translate(2.5546741e-5,-0.00274857)"> + <g + transform="translate(-264.3227,-505.012)" + style="display:inline" + id="Brick-to-Brick" + inkscape:label="#g2189" + inkscape:export-filename="SCons-Bricks.png"> + <rect + y="552.24042" + x="296.28955" + height="8.3218126" + width="25.570662" + id="rect2170" + style="fill:#cf291c;fill-opacity:1;stroke:#000000;stroke-width:1.4000001;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + y="552.24042" + x="267.02267" + height="8.3218126" + width="25.570662" + id="rect3143" + style="fill:#cf291c;fill-opacity:1;stroke:#000000;stroke-width:1.4000001;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + y="540.14984" + x="267.02267" + height="8.3218126" + width="13.012291" + id="rect3145" + style="fill:#cf291c;fill-opacity:1;stroke:#000000;stroke-width:1.40000021;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + y="540.14984" + x="308.84793" + height="8.3218126" + width="13.012291" + id="rect3147" + style="fill:#cf291c;fill-opacity:1;stroke:#000000;stroke-width:1.40000021;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" /> + <rect + transform="matrix(0.905934,0.423418,-0.423418,0.905934,0,0)" + y="335.94952" + x="480.29761" + height="8.3219995" + width="23" + id="rect3149" + style="fill:#cf291c;fill-opacity:1;stroke:#000000;stroke-width:1.4000001;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" /> + <g + id="g2185"> + <path + style="fill:none;stroke:#000000;stroke-width:4;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:1;stroke-opacity:1;stroke-dasharray:none;marker-start:none;marker-end:none" + d="m 297.75417,522.67403 c -3.0064,6.09106 -3.82029,6.65046 -3.12294,18.68449" + id="path3155" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <path + sodipodi:type="star" + style="fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:2.56573844;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:1;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path8218" + sodipodi:sides="3" + sodipodi:cx="269.17282" + sodipodi:cy="490.86679" + sodipodi:r1="14.074683" + sodipodi:r2="14.074683" + sodipodi:arg1="1.5922984" + sodipodi:arg2="-2.6531172" + inkscape:flatsided="false" + inkscape:rounded="0" + inkscape:randomized="0" + d="m 268.87021,504.93822 -12.12603,-20.6764 0.39373,-0.69281 23.9693,-0.16325 0.40313,0.68739 -11.84327,20.83964 z" + transform="matrix(0.370735,0,0,0.409743,194.6666,341.5009)" /> + </g> + </g> + <g + transform="scale(1.0124967,0.98765755)" + style="font-size:28.4279995px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:semi-condensed;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;display:inline;font-family:DejaVu Serif;-inkscape-font-specification:DejaVu Serif Bold Semi-Condensed" + id="text10160"> + <path + d="m 64.462518,55.550974 0,-4.913824 1.582418,0 c 0.249852,1.554661 0.823593,2.716025 1.721226,3.484096 0.897623,0.768075 2.142272,1.152112 3.733952,1.152111 1.286282,1e-6 2.267195,-0.272989 2.942742,-0.818971 0.675522,-0.545978 1.013289,-1.34644 1.013302,-2.401388 -1.3e-5,-0.832847 -0.23136,-1.480619 -0.694043,-1.943321 -0.453453,-0.462688 -1.39735,-0.892994 -2.831695,-1.29092 L 69.140368,48.05531 c -1.823025,-0.51821 -3.10469,-1.235387 -3.844998,-2.151533 -0.740315,-0.925379 -1.110471,-2.239432 -1.110469,-3.942164 -2e-6,-2.05435 0.610755,-3.650648 1.832273,-4.788896 1.230765,-1.147464 2.95199,-1.721206 5.16368,-1.721227 1.091951,2.1e-5 2.225553,0.101814 3.40081,0.305379 1.184487,0.203607 2.410628,0.508985 3.678428,0.916137 l 0,4.580683 -1.582418,0 c -0.249869,-1.425085 -0.781968,-2.466148 -1.596299,-3.123193 -0.814355,-0.666262 -1.975719,-0.999403 -3.484095,-0.999422 -1.230778,1.9e-5 -2.160794,0.240621 -2.790053,0.721805 -0.629271,0.471967 -0.943904,1.17989 -0.943899,2.123771 -5e-6,0.860629 0.217462,1.517656 0.652401,1.971082 0.434927,0.444202 1.494498,0.906897 3.178717,1.388086 l 2.803933,0.763447 c 1.730467,0.481215 2.98437,1.230781 3.761713,2.2487 0.777312,1.017938 1.165975,2.419904 1.165992,4.2059 -1.7e-5,2.091387 -0.64779,3.683057 -1.94332,4.775015 -1.295561,1.082708 -3.20649,1.62406 -5.732795,1.624061 -1.21227,-1e-6 -2.419903,-0.115674 -3.622904,-0.347022 -1.203012,-0.231347 -2.424527,-0.582995 -3.664547,-1.054945" + style="" + id="path3017" /> + <path + d="m 100.03916,50.63715 c -0.490476,2.137656 -1.374224,3.724699 -2.651245,4.761135 -1.2678,1.036437 -2.975144,1.554655 -5.122037,1.554656 -3.15559,-1e-6 -5.649515,-0.962406 -7.481783,-2.887219 -1.823021,-1.934062 -2.73453,-4.552915 -2.734529,-7.856566 -10e-7,-3.312885 0.911508,-5.931738 2.734529,-7.856566 1.832268,-1.934047 4.326193,-2.901079 7.481783,-2.9011 1.101203,2.1e-5 2.253313,0.148084 3.456334,0.444188 1.202992,0.296145 2.470776,0.744959 3.803355,1.346443 l 0,5.094275 -1.582418,0 c -0.323903,-1.739718 -0.916152,-3.039891 -1.77675,-3.900521 -0.851373,-0.869848 -1.980349,-1.304782 -3.386929,-1.304801 -1.82303,1.9e-5 -3.174099,0.744958 -4.053211,2.234818 -0.879128,1.480641 -1.318688,3.761727 -1.318682,6.843264 -6e-6,3.081558 0.439554,5.362643 1.318682,6.843263 0.879112,1.480627 2.234808,2.220939 4.067092,2.220938 1.249264,1e-6 2.267193,-0.384036 3.053789,-1.152111 0.786566,-0.768071 1.355681,-1.929435 1.707345,-3.484096 l 2.484675,0" + style="" + id="path3019" /> + <path + d="m 112.49029,55.273357 c 1.59166,1e-6 2.77153,-0.744937 3.53962,-2.234818 0.77731,-1.489874 1.16598,-3.766333 1.16599,-6.829383 -10e-6,-3.072283 -0.38868,-5.353369 -1.16599,-6.843264 -0.76809,-1.48986 -1.94796,-2.234799 -3.53962,-2.234818 -1.58243,1.9e-5 -2.7623,0.754212 -3.53962,2.26258 -0.77733,1.499149 -1.166,3.77098 -1.16599,6.815502 -10e-6,3.035288 0.38866,5.30712 1.16599,6.815502 0.77732,1.499135 1.95719,2.2487 3.53962,2.248699 m 0,1.679584 c -3.13708,-1e-6 -5.59862,-0.953152 -7.38462,-2.859457 -1.786,-1.9063 -2.679,-4.534407 -2.679,-7.884328 0,-3.3499 0.893,-5.978007 2.679,-7.884328 1.79526,-1.915538 4.25679,-2.873317 7.38462,-2.873338 3.13706,2.1e-5 5.59397,0.953173 7.37074,2.859457 1.78598,1.906321 2.67898,4.539055 2.679,7.898209 -2e-5,3.349921 -0.89302,5.978028 -2.679,7.884328 -1.78602,1.906305 -4.24293,2.859456 -7.37074,2.859457" + style="" + id="path3021" /> + <path + d="m 124.74709,56.550396 0,-1.679584 2.38751,0 0,-17.364955 -2.38751,0 0,-1.679584 5.82996,0 11.25738,14.672068 0,-12.992484 -2.37363,0 0,-1.679584 6.524,0 0,1.679584 -2.38751,0 0,19.044539 -3.27588,0 -11.42395,-14.977447 0,13.297863 2.37363,0 0,1.679584 -6.524,0" + style="" + id="path3023" /> + <path + d="m 148.96919,55.550974 0,-4.913824 1.58241,0 c 0.24986,1.554661 0.8236,2.716025 1.72123,3.484096 0.89762,0.768075 2.14227,1.152112 3.73395,1.152111 1.28628,1e-6 2.2672,-0.272989 2.94274,-0.818971 0.67553,-0.545978 1.01329,-1.34644 1.01331,-2.401388 -2e-5,-0.832847 -0.23136,-1.480619 -0.69405,-1.943321 -0.45345,-0.462688 -1.39735,-0.892994 -2.83169,-1.29092 l -2.79005,-0.763447 c -1.82303,-0.51821 -3.10469,-1.235387 -3.845,-2.151533 -0.74032,-0.925379 -1.11047,-2.239432 -1.11047,-3.942164 0,-2.05435 0.61075,-3.650648 1.83227,-4.788896 1.23077,-1.147464 2.95199,-1.721206 5.16368,-1.721227 1.09195,2.1e-5 2.22556,0.101814 3.40081,0.305379 1.18449,0.203607 2.41063,0.508985 3.67843,0.916137 l 0,4.580683 -1.58242,0 c -0.24987,-1.425085 -0.78197,-2.466148 -1.5963,-3.123193 -0.81435,-0.666262 -1.97572,-0.999403 -3.48409,-0.999422 -1.23078,1.9e-5 -2.1608,0.240621 -2.79006,0.721805 -0.62927,0.471967 -0.9439,1.17989 -0.94389,2.123771 -1e-5,0.860629 0.21746,1.517656 0.6524,1.971082 0.43492,0.444202 1.4945,0.906897 3.17871,1.388086 l 2.80394,0.763447 c 1.73046,0.481215 2.98437,1.230781 3.76171,2.2487 0.77731,1.017938 1.16598,2.419904 1.16599,4.2059 -1e-5,2.091387 -0.64779,3.683057 -1.94332,4.775015 -1.29556,1.082708 -3.20649,1.62406 -5.73279,1.624061 -1.21227,-1e-6 -2.41991,-0.115674 -3.62291,-0.347022 -1.20301,-0.231347 -2.42452,-0.582995 -3.66454,-1.054945" + style="" + id="path3025" /> + </g> + </g> +</svg> diff --git a/doc/user/titlepage/bricks.jpg b/doc/user/titlepage/bricks.jpg Binary files differnew file mode 100755 index 0000000..b2dc16b --- /dev/null +++ b/doc/user/titlepage/bricks.jpg diff --git a/doc/user/titlepage/mapnik_final_colors.svg b/doc/user/titlepage/mapnik_final_colors.svg new file mode 100644 index 0000000..23bb54a --- /dev/null +++ b/doc/user/titlepage/mapnik_final_colors.svg @@ -0,0 +1,6397 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + fill-opacity="1" + color-rendering="auto" + color-interpolation="auto" + stroke="black" + text-rendering="auto" + stroke-linecap="square" + width="600" + stroke-miterlimit="10" + stroke-opacity="1" + shape-rendering="auto" + fill="black" + stroke-dasharray="none" + font-weight="normal" + stroke-width="1" + height="701" + font-family="'Dialog'" + font-style="normal" + stroke-linejoin="miter" + font-size="12" + stroke-dashoffset="0" + image-rendering="auto" + id="svg8168" + version="1.1" + inkscape:version="0.48.3.1 r9886" + sodipodi:docname="mapnik_final_colors.svg"> + <title + id="title9830">SCons, Book titlepage background</title> + <metadata + id="metadata9828"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <cc:license + rdf:resource="" /> + <dc:title>SCons, Book titlepage background</dc:title> + <dc:date>2013-04-15</dc:date> + <dc:creator> + <cc:Agent> + <dc:title>Dirk Baechle</dc:title> + </cc:Agent> + </dc:creator> + <dc:rights> + <cc:Agent> + <dc:title>Dirk Baechle <dl9obn@darc.de></dc:title> + </cc:Agent> + </dc:rights> + <dc:language>en</dc:language> + <dc:subject> + <rdf:Bag> + <rdf:li>SCons</rdf:li> + <rdf:li>software build tool</rdf:li> + <rdf:li>software construction tool</rdf:li> + </rdf:Bag> + </dc:subject> + <dc:contributor> + <cc:Agent> + <dc:title>Based on a SCons dependency tree of the Mapnik project (www.mapnik.org)</dc:title> + </cc:Agent> + </dc:contributor> + </cc:Work> + </rdf:RDF> + </metadata> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="735" + inkscape:window-height="480" + id="namedview9826" + showgrid="false" + inkscape:zoom="0.33666191" + inkscape:cx="300" + inkscape:cy="350.5" + inkscape:window-x="85" + inkscape:window-y="99" + inkscape:window-maximized="0" + inkscape:current-layer="svg8168" /> + <!--Generated by ySVG--> + <defs + id="genericDefs" /> + <g + id="g8171"> + <defs + id="defs1"> + <clipPath + clipPathUnits="userSpaceOnUse" + id="clipPath1"> + <path + d="M0 0 L600 0 L600 701 L0 701 L0 0 Z" + id="path8175" /> + </clipPath> + <clipPath + clipPathUnits="userSpaceOnUse" + id="clipPath2"> + <path + d="M-871 -1293 L3138 -1293 L3138 3390.8484 L-871 3390.8484 L-871 -1293 Z" + id="path8178" /> + </clipPath> + </defs> + <g + fill="white" + transform="scale(0.1497,0.1497) translate(871,1293)" + stroke="white" + id="g8180"> + <rect + x="-871" + y="-1293" + clip-path="url(#clipPath2)" + width="4009" + height="4684" + stroke="none" + id="rect8182" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8184"> + <rect + x="1133.3896" + y="93" + clip-path="url(#clipPath2)" + width="142.2207" + height="30" + stroke="none" + id="rect8186" /> + <text + x="1140.3896" + y="112.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8188">./src/agg_renderer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8190"> + <rect + x="1133.3896" + y="93" + clip-path="url(#clipPath2)" + fill="none" + width="142.2207" + height="30" + id="rect8192" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8194"> + <rect + x="-44.5742" + y="1682.5" + clip-path="url(#clipPath2)" + width="69.1484" + height="30" + stroke="none" + id="rect8196" /> + <text + x="-37.5742" + y="1701.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8198">./agg/src</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8200"> + <rect + x="-44.5742" + y="1682.5" + clip-path="url(#clipPath2)" + fill="none" + width="69.1484" + height="30" + id="rect8202" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8204"> + <rect + x="1133.7031" + y="-665" + clip-path="url(#clipPath2)" + width="114.5938" + height="30" + stroke="none" + id="rect8206" /> + <text + x="1140.7031" + y="-645.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8208">./src/graphics.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8210"> + <rect + x="1133.7031" + y="-665" + clip-path="url(#clipPath2)" + fill="none" + width="114.5938" + height="30" + id="rect8212" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8214"> + <rect + x="1669.0742" + y="-63.5" + clip-path="url(#clipPath2)" + width="111.8516" + height="30" + stroke="none" + id="rect8216" /> + <text + x="1676.0742" + y="-44.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8218">./src/font_set.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8220"> + <rect + x="1669.0742" + y="-63.5" + clip-path="url(#clipPath2)" + fill="none" + width="111.8516" + height="30" + id="rect8222" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8224"> + <rect + x="-615.9639" + y="2086.5" + clip-path="url(#clipPath2)" + width="234.9277" + height="30" + stroke="none" + id="rect8226" /> + <text + x="-608.9639" + y="2105.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8228">./agg/src/agg_vcgen_markers_term.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8230"> + <rect + x="-615.9639" + y="2086.5" + clip-path="url(#clipPath2)" + fill="none" + width="234.9277" + height="30" + id="rect8232" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8234"> + <rect + x="2055.0605" + y="-148" + clip-path="url(#clipPath2)" + width="107.8789" + height="30" + stroke="none" + id="rect8236" /> + <text + x="2062.0605" + y="-128.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8238">./src/params.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8240"> + <rect + x="2055.0605" + y="-148" + clip-path="url(#clipPath2)" + fill="none" + width="107.8789" + height="30" + id="rect8242" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8244"> + <rect + x="-78.1094" + y="1848" + clip-path="url(#clipPath2)" + width="189.2188" + height="30" + stroke="none" + id="rect8246" /> + <text + x="-71.1094" + y="1867.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8248">./agg/src/agg_image_filters.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8250"> + <rect + x="-78.1094" + y="1848" + clip-path="url(#clipPath2)" + fill="none" + width="189.2188" + height="30" + id="rect8252" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8254"> + <rect + x="2427.3438" + y="1805" + clip-path="url(#clipPath2)" + width="258.3125" + height="30" + stroke="none" + id="rect8256" /> + <text + x="2434.3438" + y="1824.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8258">./bindings/python/mapnik_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8260"> + <rect + x="2427.3438" + y="1805" + clip-path="url(#clipPath2)" + fill="none" + width="258.3125" + height="30" + id="rect8262" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8264"> + <rect + x="1768.7578" + y="190" + clip-path="url(#clipPath2)" + width="112.4844" + height="30" + stroke="none" + id="rect8266" /> + <text + x="1775.7578" + y="209.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8268">./src/memory.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8270"> + <rect + x="1768.7578" + y="190" + clip-path="url(#clipPath2)" + fill="none" + width="112.4844" + height="30" + id="rect8272" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8274"> + <rect + x="1295.8389" + y="3348.5" + clip-path="url(#clipPath2)" + width="263.3223" + height="30" + stroke="none" + id="rect8276" /> + <text + x="1302.8389" + y="3367.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8278">./bindings/python/mapnik_font_engine.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8280"> + <rect + x="1295.8389" + y="3348.5" + clip-path="url(#clipPath2)" + fill="none" + width="263.3223" + height="30" + id="rect8282" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8284"> + <rect + x="644.1875" + y="440" + clip-path="url(#clipPath2)" + width="205.625" + height="30" + stroke="none" + id="rect8286" /> + <text + x="651.1875" + y="459.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8288">./plugins/input/shape/dbffile.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8290"> + <rect + x="644.1875" + y="440" + clip-path="url(#clipPath2)" + fill="none" + width="205.625" + height="30" + id="rect8292" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8294"> + <rect + x="141.2227" + y="1886.5" + clip-path="url(#clipPath2)" + width="196.5547" + height="30" + stroke="none" + id="rect8296" /> + <text + x="148.2227" + y="1905.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8298">./agg/src/agg_line_aa_basics.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8300"> + <rect + x="141.2227" + y="1886.5" + clip-path="url(#clipPath2)" + fill="none" + width="196.5547" + height="30" + id="rect8302" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8304"> + <rect + x="1837.5674" + y="-302.5" + clip-path="url(#clipPath2)" + width="121.8652" + height="30" + stroke="none" + id="rect8306" /> + <text + x="1844.5674" + y="-283.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8308">./src/save_map.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8310"> + <rect + x="1837.5674" + y="-302.5" + clip-path="url(#clipPath2)" + fill="none" + width="121.8652" + height="30" + id="rect8312" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8314"> + <rect + x="655.2578" + y="2799.5" + clip-path="url(#clipPath2)" + width="283.4844" + height="30" + stroke="none" + id="rect8316" /> + <text + x="662.2578" + y="2818.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8318">./bindings/python/mapnik_view_transform.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8320"> + <rect + x="655.2578" + y="2799.5" + clip-path="url(#clipPath2)" + fill="none" + width="283.4844" + height="30" + id="rect8322" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8324"> + <rect + x="1871.4453" + y="-160.5" + clip-path="url(#clipPath2)" + width="94.1094" + height="30" + stroke="none" + id="rect8326" /> + <text + x="1878.4453" + y="-141.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8328">./src/color.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8330"> + <rect + x="1871.4453" + y="-160.5" + clip-path="url(#clipPath2)" + fill="none" + width="94.1094" + height="30" + id="rect8332" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8334"> + <rect + x="94.7598" + y="1464" + clip-path="url(#clipPath2)" + width="98.4805" + height="30" + stroke="none" + id="rect8336" /> + <text + x="101.7598" + y="1483.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8338">./agg/libagg.a</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8340"> + <rect + x="94.7598" + y="1464" + clip-path="url(#clipPath2)" + fill="none" + width="98.4805" + height="30" + id="rect8342" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8344"> + <rect + x="1939.2666" + y="-928" + clip-path="url(#clipPath2)" + width="187.4668" + height="30" + stroke="none" + id="rect8346" /> + <text + x="1946.2666" + y="-908.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8348">./src/font_engine_freetype.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8350"> + <rect + x="1939.2666" + y="-928" + clip-path="url(#clipPath2)" + fill="none" + width="187.4668" + height="30" + id="rect8352" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8354"> + <rect + x="1924.2861" + y="152.5" + clip-path="url(#clipPath2)" + width="101.4277" + height="30" + stroke="none" + id="rect8356" /> + <text + x="1931.2861" + y="171.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8358">./src/stroke.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8360"> + <rect + x="1924.2861" + y="152.5" + clip-path="url(#clipPath2)" + fill="none" + width="101.4277" + height="30" + id="rect8362" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8364"> + <rect + x="1550.0732" + y="2624" + clip-path="url(#clipPath2)" + width="229.8535" + height="30" + stroke="none" + id="rect8366" /> + <text + x="1557.0732" + y="2643.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8368">./bindings/python/mapnik_image.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8370"> + <rect + x="1550.0732" + y="2624" + clip-path="url(#clipPath2)" + fill="none" + width="229.8535" + height="30" + id="rect8372" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8374"> + <rect + x="1955.9092" + y="-737" + clip-path="url(#clipPath2)" + width="125.1816" + height="30" + stroke="none" + id="rect8376" /> + <text + x="1962.9092" + y="-717.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8378">./src/image_util.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8380"> + <rect + x="1955.9092" + y="-737" + clip-path="url(#clipPath2)" + fill="none" + width="125.1816" + height="30" + id="rect8382" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8384"> + <rect + x="966.7939" + y="2852.5" + clip-path="url(#clipPath2)" + width="297.4121" + height="30" + stroke="none" + id="rect8386" /> + <text + x="973.7939" + y="2871.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8388">./bindings/python/mapnik_datasource_cache.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8390"> + <rect + x="966.7939" + y="2852.5" + clip-path="url(#clipPath2)" + fill="none" + width="297.4121" + height="30" + id="rect8392" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8394"> + <rect + x="-154.5957" + y="2476.5" + clip-path="url(#clipPath2)" + width="94.1914" + height="30" + stroke="none" + id="rect8396" /> + <text + x="-147.5957" + y="2495.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8398">./agg/include</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8400"> + <rect + x="-154.5957" + y="2476.5" + clip-path="url(#clipPath2)" + fill="none" + width="94.1914" + height="30" + id="rect8402" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8404"> + <rect + x="889.5508" + y="2446.5" + clip-path="url(#clipPath2)" + width="216.8984" + height="30" + stroke="none" + id="rect8406" /> + <text + x="896.5508" + y="2465.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8408">./bindings/python/mapnik_rule.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8410"> + <rect + x="889.5508" + y="2446.5" + clip-path="url(#clipPath2)" + fill="none" + width="216.8984" + height="30" + id="rect8412" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8414"> + <rect + x="270.4668" + y="1185.5" + clip-path="url(#clipPath2)" + width="174.0664" + height="30" + stroke="none" + id="rect8416" /> + <text + x="277.4668" + y="1204.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8418">./agg/src/agg_bezier_arc.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8420"> + <rect + x="270.4668" + y="1185.5" + clip-path="url(#clipPath2)" + fill="none" + width="174.0664" + height="30" + id="rect8422" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8424"> + <rect + x="1531.0332" + y="1589.5" + clip-path="url(#clipPath2)" + width="252.9336" + height="30" + stroke="none" + id="rect8426" /> + <text + x="1538.0332" + y="1608.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8428">./bindings/python/mapnik_featureset.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8430"> + <rect + x="1531.0332" + y="1589.5" + clip-path="url(#clipPath2)" + fill="none" + width="252.9336" + height="30" + id="rect8432" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8434"> + <rect + x="185.0576" + y="1689" + clip-path="url(#clipPath2)" + width="131.8848" + height="30" + stroke="none" + id="rect8436" /> + <text + x="192.0576" + y="1708.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8438">./agg/src/agg_arc.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8440"> + <rect + x="185.0576" + y="1689" + clip-path="url(#clipPath2)" + fill="none" + width="131.8848" + height="30" + id="rect8442" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8444"> + <rect + x="-166.7686" + y="540" + clip-path="url(#clipPath2)" + width="220.5371" + height="30" + stroke="none" + id="rect8446" /> + <text + x="-159.7686" + y="559.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8448">./plugins/input/shape/shapefile.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8450"> + <rect + x="-166.7686" + y="540" + clip-path="url(#clipPath2)" + fill="none" + width="220.5371" + height="30" + id="rect8452" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8454"> + <rect + x="-59.0459" + y="-1075.5" + clip-path="url(#clipPath2)" + width="271.0918" + height="30" + stroke="none" + id="rect8456" /> + <text + x="-52.0459" + y="-1056.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8458">./plugins/input/raster/raster_datasource.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8460"> + <rect + x="-59.0459" + y="-1075.5" + clip-path="url(#clipPath2)" + fill="none" + width="271.0918" + height="30" + id="rect8462" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8464"> + <rect + x="-712.333" + y="-443" + clip-path="url(#clipPath2)" + width="265.666" + height="30" + stroke="none" + id="rect8466" /> + <text + x="-705.333" + y="-423.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8468">./plugins/input/raster/raster_featureset.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8470"> + <rect + x="-712.333" + y="-443" + clip-path="url(#clipPath2)" + fill="none" + width="265.666" + height="30" + id="rect8472" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8474"> + <rect + x="1988.0195" + y="311.5" + clip-path="url(#clipPath2)" + width="110.9609" + height="30" + stroke="none" + id="rect8476" /> + <text + x="1995.0195" + y="330.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8478">./src/unicode.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8480"> + <rect + x="1988.0195" + y="311.5" + clip-path="url(#clipPath2)" + fill="none" + width="110.9609" + height="30" + id="rect8482" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8484"> + <rect + x="2889.043" + y="2261" + clip-path="url(#clipPath2)" + width="233.9141" + height="30" + stroke="none" + id="rect8486" /> + <text + x="2896.043" + y="2280.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8488">./bindings/python/mapnik/ogcserver</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8490"> + <rect + x="2889.043" + y="2261" + clip-path="url(#clipPath2)" + fill="none" + width="233.9141" + height="30" + id="rect8492" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8494"> + <rect + x="1957.6152" + y="1969" + clip-path="url(#clipPath2)" + width="219.7695" + height="30" + stroke="none" + id="rect8496" /> + <text + x="1964.6152" + y="1988.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8498">./bindings/python/mapnik_map.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8500"> + <rect + x="1957.6152" + y="1969" + clip-path="url(#clipPath2)" + fill="none" + width="219.7695" + height="30" + id="rect8502" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8504"> + <rect + x="1404.0469" + y="45" + clip-path="url(#clipPath2)" + width="97.9062" + height="30" + stroke="none" + id="rect8506" /> + <text + x="1411.0469" + y="64.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8508">./src/arrow.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8510"> + <rect + x="1404.0469" + y="45" + clip-path="url(#clipPath2)" + fill="none" + width="97.9062" + height="30" + id="rect8512" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8514"> + <rect + x="378.9629" + y="-617" + clip-path="url(#clipPath2)" + width="67.0742" + height="30" + stroke="none" + id="rect8516" /> + <text + x="385.9629" + y="-597.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8518">./plugins</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8520"> + <rect + x="378.9629" + y="-617" + clip-path="url(#clipPath2)" + fill="none" + width="67.0742" + height="30" + id="rect8522" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8524"> + <rect + x="-600.0176" + y="-904" + clip-path="url(#clipPath2)" + width="218.0352" + height="30" + stroke="none" + id="rect8526" /> + <text + x="-593.0176" + y="-884.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8528">./plugins/input/raster/raster.input</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8530"> + <rect + x="-600.0176" + y="-904" + clip-path="url(#clipPath2)" + fill="none" + width="218.0352" + height="30" + id="rect8532" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8534"> + <rect + x="504.8223" + y="1246.5" + clip-path="url(#clipPath2)" + width="199.3555" + height="30" + stroke="none" + id="rect8536" /> + <text + x="511.8223" + y="1265.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8538">./agg/src/agg_vcgen_contour.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8540"> + <rect + x="504.8223" + y="1246.5" + clip-path="url(#clipPath2)" + fill="none" + width="199.3555" + height="30" + id="rect8542" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8544"> + <rect + x="477.084" + y="1562.5" + clip-path="url(#clipPath2)" + width="239.832" + height="30" + stroke="none" + id="rect8546" /> + <text + x="484.084" + y="1581.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8548">./agg/src/agg_trans_warp_magnifier.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8550"> + <rect + x="477.084" + y="1562.5" + clip-path="url(#clipPath2)" + fill="none" + width="239.832" + height="30" + id="rect8552" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8554"> + <rect + x="1807.8203" + y="2883" + clip-path="url(#clipPath2)" + width="258.3594" + height="30" + stroke="none" + id="rect8556" /> + <text + x="1814.8203" + y="2902.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8558">./bindings/python/mapnik_datasource.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8560"> + <rect + x="1807.8203" + y="2883" + clip-path="url(#clipPath2)" + fill="none" + width="258.3594" + height="30" + id="rect8562" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8564"> + <rect + x="200.9756" + y="772" + clip-path="url(#clipPath2)" + width="267.0488" + height="30" + stroke="none" + id="rect8566" /> + <text + x="207.9756" + y="791.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8568">./plugins/input/shape/shape_featureset.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8570"> + <rect + x="200.9756" + y="772" + clip-path="url(#clipPath2)" + fill="none" + width="267.0488" + height="30" + id="rect8572" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8574"> + <rect + x="1338.8779" + y="-330.5" + clip-path="url(#clipPath2)" + width="121.2441" + height="30" + stroke="none" + id="rect8576" /> + <text + x="1345.8779" + y="-311.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8578">./src/load_map.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8580"> + <rect + x="1338.8779" + y="-330.5" + clip-path="url(#clipPath2)" + fill="none" + width="121.2441" + height="30" + id="rect8582" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8584"> + <rect + x="1635.1797" + y="2310" + clip-path="url(#clipPath2)" + width="294.6406" + height="30" + stroke="none" + id="rect8586" /> + <text + x="1642.1797" + y="2329.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8588">./bindings/python/mapnik_point_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8590"> + <rect + x="1635.1797" + y="2310" + clip-path="url(#clipPath2)" + fill="none" + width="294.6406" + height="30" + id="rect8592" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8594"> + <rect + x="1870.9814" + y="-498.5" + clip-path="url(#clipPath2)" + width="204.0371" + height="30" + stroke="none" + id="rect8596" /> + <text + x="1877.9814" + y="-479.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8598">./src/line_pattern_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8600"> + <rect + x="1870.9814" + y="-498.5" + clip-path="url(#clipPath2)" + fill="none" + width="204.0371" + height="30" + id="rect8602" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8604"> + <rect + x="2406.4492" + y="2209" + clip-path="url(#clipPath2)" + width="171.1016" + height="30" + stroke="none" + id="rect8606" /> + <text + x="2413.4492" + y="2228.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8608">./bindings/python/mapnik</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8610"> + <rect + x="2406.4492" + y="2209" + clip-path="url(#clipPath2)" + fill="none" + width="171.1016" + height="30" + id="rect8612" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8614"> + <rect + x="-228.4014" + y="-713.5" + clip-path="url(#clipPath2)" + width="143.8027" + height="30" + stroke="none" + id="rect8616" /> + <text + x="-221.4014" + y="-694.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8618">./plugins/input/raster</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8620"> + <rect + x="-228.4014" + y="-713.5" + clip-path="url(#clipPath2)" + fill="none" + width="143.8027" + height="30" + id="rect8622" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8624"> + <rect + x="1749.3877" + y="-581.5" + clip-path="url(#clipPath2)" + width="90.2246" + height="30" + stroke="none" + id="rect8626" /> + <text + x="1756.3877" + y="-562.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8628">./src/map.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8630"> + <rect + x="1749.3877" + y="-581.5" + clip-path="url(#clipPath2)" + fill="none" + width="90.2246" + height="30" + id="rect8632" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8634"> + <rect + x="1467.6729" + y="-572" + clip-path="url(#clipPath2)" + width="88.6543" + height="30" + stroke="none" + id="rect8636" /> + <text + x="1474.6729" + y="-552.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8638">./src/wkb.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8640"> + <rect + x="1467.6729" + y="-572" + clip-path="url(#clipPath2)" + fill="none" + width="88.6543" + height="30" + id="rect8642" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8644"> + <rect + x="-575.8799" + y="1522.5" + clip-path="url(#clipPath2)" + width="190.7598" + height="30" + stroke="none" + id="rect8646" /> + <text + x="-568.8799" + y="1541.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8648">./agg/src/agg_vcgen_stroke.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8650"> + <rect + x="-575.8799" + y="1522.5" + clip-path="url(#clipPath2)" + fill="none" + width="190.7598" + height="30" + id="rect8652" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8654"> + <rect + x="-133.5166" + y="1274" + clip-path="url(#clipPath2)" + width="163.0332" + height="30" + stroke="none" + id="rect8656" /> + <text + x="-126.5166" + y="1293.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8658">./agg/src/agg_gsv_text.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8660"> + <rect + x="-133.5166" + y="1274" + clip-path="url(#clipPath2)" + fill="none" + width="163.0332" + height="30" + id="rect8662" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8664"> + <rect + x="318.249" + y="-203.5" + clip-path="url(#clipPath2)" + width="202.502" + height="30" + stroke="none" + id="rect8666" /> + <text + x="325.249" + y="-184.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8668">./plugins/input/shape/shape.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8670"> + <rect + x="318.249" + y="-203.5" + clip-path="url(#clipPath2)" + fill="none" + width="202.502" + height="30" + id="rect8672" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8674"> + <rect + x="2219.1865" + y="1968" + clip-path="url(#clipPath2)" + width="74.627" + height="30" + stroke="none" + id="rect8676" /> + <text + x="2226.1865" + y="1987.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8678">./bindings</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8680"> + <rect + x="2219.1865" + y="1968" + clip-path="url(#clipPath2)" + fill="none" + width="74.627" + height="30" + id="rect8682" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8684"> + <rect + x="1558.8682" + y="-315.5" + clip-path="url(#clipPath2)" + width="41.2637" + height="30" + stroke="none" + id="rect8686" /> + <text + x="1565.8682" + y="-296.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8688">./src</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8690"> + <rect + x="1558.8682" + y="-315.5" + clip-path="url(#clipPath2)" + fill="none" + width="41.2637" + height="30" + id="rect8692" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8694"> + <rect + x="1371.5898" + y="1863" + clip-path="url(#clipPath2)" + width="221.8203" + height="30" + stroke="none" + id="rect8696" /> + <text + x="1378.5898" + y="1882.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8698">./bindings/python/mapnik_filter.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8700"> + <rect + x="1371.5898" + y="1863" + clip-path="url(#clipPath2)" + fill="none" + width="221.8203" + height="30" + id="rect8702" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8704"> + <rect + x="-483.2334" + y="1775.5" + clip-path="url(#clipPath2)" + width="196.4668" + height="30" + stroke="none" + id="rect8706" /> + <text + x="-476.2334" + y="1794.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8708">./agg/src/agg_vcgen_bspline.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8710"> + <rect + x="-483.2334" + y="1775.5" + clip-path="url(#clipPath2)" + fill="none" + width="196.4668" + height="30" + id="rect8712" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8714"> + <rect + x="1292.1309" + y="2653" + clip-path="url(#clipPath2)" + width="227.7383" + height="30" + stroke="none" + id="rect8716" /> + <text + x="1299.1309" + y="2672.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8718">./bindings/python/mapnik_coord.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8720"> + <rect + x="1292.1309" + y="2653" + clip-path="url(#clipPath2)" + fill="none" + width="227.7383" + height="30" + id="rect8722" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8724"> + <rect + x="1750.0254" + y="-805" + clip-path="url(#clipPath2)" + width="116.9492" + height="30" + stroke="none" + id="rect8726" /> + <text + x="1757.0254" + y="-785.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8728">./src/envelope.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8730"> + <rect + x="1750.0254" + y="-805" + clip-path="url(#clipPath2)" + fill="none" + width="116.9492" + height="30" + id="rect8732" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8734"> + <rect + x="-353.043" + y="2040.5" + clip-path="url(#clipPath2)" + width="229.0859" + height="30" + stroke="none" + id="rect8736" /> + <text + x="-346.043" + y="2059.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8738">./agg/src/agg_vpgen_segmentator.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8740"> + <rect + x="-353.043" + y="2040.5" + clip-path="url(#clipPath2)" + fill="none" + width="229.0859" + height="30" + id="rect8742" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8744"> + <rect + x="1707.3262" + y="1980.5" + clip-path="url(#clipPath2)" + width="222.3477" + height="30" + stroke="none" + id="rect8746" /> + <text + x="1714.3262" + y="1999.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8748">./bindings/python/mapnik_layer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8750"> + <rect + x="1707.3262" + y="1980.5" + clip-path="url(#clipPath2)" + fill="none" + width="222.3477" + height="30" + id="rect8752" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8754"> + <rect + x="1338.3086" + y="2945.5" + clip-path="url(#clipPath2)" + width="285.3828" + height="30" + stroke="none" + id="rect8756" /> + <text + x="1345.3086" + y="2964.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8758">./bindings/python/mapnik_line_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8760"> + <rect + x="1338.3086" + y="2945.5" + clip-path="url(#clipPath2)" + fill="none" + width="285.3828" + height="30" + id="rect8762" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8764"> + <rect + x="1750.2461" + y="396" + clip-path="url(#clipPath2)" + width="169.5078" + height="30" + stroke="none" + id="rect8766" /> + <text + x="1757.2461" + y="415.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8768">./src/shield_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8770"> + <rect + x="1750.2461" + y="396" + clip-path="url(#clipPath2)" + fill="none" + width="169.5078" + height="30" + id="rect8772" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8774"> + <rect + x="-414.9922" + y="992" + clip-path="url(#clipPath2)" + width="221.9844" + height="30" + stroke="none" + id="rect8776" /> + <text + x="-407.9922" + y="1011.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8778">./agg/src/agg_trans_double_path.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8780"> + <rect + x="-414.9922" + y="992" + clip-path="url(#clipPath2)" + fill="none" + width="221.9844" + height="30" + id="rect8782" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8784"> + <rect + x="1304.5332" + y="201.5" + clip-path="url(#clipPath2)" + width="123.9336" + height="30" + stroke="none" + id="rect8786" /> + <text + x="1311.5332" + y="220.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8788">./src/projection.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8790"> + <rect + x="1304.5332" + y="201.5" + clip-path="url(#clipPath2)" + fill="none" + width="123.9336" + height="30" + id="rect8792" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8794"> + <rect + x="1109.5029" + y="-329" + clip-path="url(#clipPath2)" + width="124.9941" + height="30" + stroke="none" + id="rect8796" /> + <text + x="1116.5029" + y="-309.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8798">./src/tiff_reader.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8800"> + <rect + x="1109.5029" + y="-329" + clip-path="url(#clipPath2)" + fill="none" + width="124.9941" + height="30" + id="rect8802" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8804"> + <rect + x="1684.8213" + y="3263.5" + clip-path="url(#clipPath2)" + width="281.3574" + height="30" + stroke="none" + id="rect8806" /> + <text + x="1691.8213" + y="3282.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8808">./bindings/python/mapnik_proj_transform.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8810"> + <rect + x="1684.8213" + y="3263.5" + clip-path="url(#clipPath2)" + fill="none" + width="281.3574" + height="30" + id="rect8812" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8814"> + <rect + x="1276.292" + y="1606" + clip-path="url(#clipPath2)" + width="221.416" + height="30" + stroke="none" + id="rect8816" /> + <text + x="1283.292" + y="1625.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8818">./bindings/python/mapnik_style.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8820"> + <rect + x="1276.292" + y="1606" + clip-path="url(#clipPath2)" + fill="none" + width="221.416" + height="30" + id="rect8822" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8824"> + <rect + x="1811.9736" + y="1677.5" + clip-path="url(#clipPath2)" + width="299.0527" + height="30" + stroke="none" + id="rect8826" /> + <text + x="1818.9736" + y="1696.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8828">./bindings/python/mapnik_shield_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8830"> + <rect + x="1811.9736" + y="1677.5" + clip-path="url(#clipPath2)" + fill="none" + width="299.0527" + height="30" + id="rect8832" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8834"> + <rect + x="1461.6602" + y="246" + clip-path="url(#clipPath2)" + width="143.6797" + height="30" + stroke="none" + id="rect8836" /> + <text + x="1468.6602" + y="265.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8838">./src/image_reader.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8840"> + <rect + x="1461.6602" + y="246" + clip-path="url(#clipPath2)" + fill="none" + width="143.6797" + height="30" + id="rect8842" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8844"> + <rect + x="-339.2471" + y="1384.5" + clip-path="url(#clipPath2)" + width="156.4941" + height="30" + stroke="none" + id="rect8846" /> + <text + x="-332.2471" + y="1403.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8848">./agg/src/agg_bspline.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8850"> + <rect + x="-339.2471" + y="1384.5" + clip-path="url(#clipPath2)" + fill="none" + width="156.4941" + height="30" + id="rect8852" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8854"> + <rect + x="-154.2881" + y="1504" + clip-path="url(#clipPath2)" + width="216.5762" + height="30" + stroke="none" + id="rect8856" /> + <text + x="-147.2881" + y="1523.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8858">./agg/src/agg_trans_single_path.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8860"> + <rect + x="-154.2881" + y="1504" + clip-path="url(#clipPath2)" + fill="none" + width="216.5762" + height="30" + id="rect8862" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8864"> + <rect + x="-451.9092" + y="-1278" + clip-path="url(#clipPath2)" + width="229.8184" + height="30" + stroke="none" + id="rect8866" /> + <text + x="-444.9092" + y="-1258.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8868">./plugins/input/raster/raster_info.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8870"> + <rect + x="-451.9092" + y="-1278" + clip-path="url(#clipPath2)" + fill="none" + width="229.8184" + height="30" + id="rect8872" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8874"> + <rect + x="58.041" + y="1120" + clip-path="url(#clipPath2)" + width="181.918" + height="30" + stroke="none" + id="rect8876" /> + <text + x="65.041" + y="1139.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8878">./agg/src/agg_vcgen_dash.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8880"> + <rect + x="58.041" + y="1120" + clip-path="url(#clipPath2)" + fill="none" + width="181.918" + height="30" + id="rect8882" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8884"> + <rect + x="2112.2607" + y="3055.5" + clip-path="url(#clipPath2)" + width="253.4785" + height="30" + stroke="none" + id="rect8886" /> + <text + x="2119.2607" + y="3074.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8888">./bindings/python/mapnik_projection.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8890"> + <rect + x="2112.2607" + y="3055.5" + clip-path="url(#clipPath2)" + fill="none" + width="253.4785" + height="30" + id="rect8892" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8894"> + <rect + x="1082.2676" + y="2091.5" + clip-path="url(#clipPath2)" + width="261.4648" + height="30" + stroke="none" + id="rect8896" /> + <text + x="1089.2676" + y="2110.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8898">./bindings/python/mapnik_image_view.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8900"> + <rect + x="1082.2676" + y="2091.5" + clip-path="url(#clipPath2)" + fill="none" + width="261.4648" + height="30" + id="rect8902" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8904"> + <rect + x="1584.8125" + y="86.5" + clip-path="url(#clipPath2)" + width="113.375" + height="30" + stroke="none" + id="rect8906" /> + <text + x="1591.8125" + y="105.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8908">./src/distance.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8910"> + <rect + x="1584.8125" + y="86.5" + clip-path="url(#clipPath2)" + fill="none" + width="113.375" + height="30" + id="rect8912" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8914"> + <rect + x="2103.0664" + y="-319" + clip-path="url(#clipPath2)" + width="167.8672" + height="30" + stroke="none" + id="rect8916" /> + <text + x="2110.0664" + y="-299.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8918">./src/datasource_cache.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8920"> + <rect + x="2103.0664" + y="-319" + clip-path="url(#clipPath2)" + fill="none" + width="167.8672" + height="30" + id="rect8922" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8924"> + <rect + x="2138.9033" + y="1613" + clip-path="url(#clipPath2)" + width="260.1934" + height="30" + stroke="none" + id="rect8926" /> + <text + x="2145.9033" + y="1632.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8928">./bindings/python/mapnik_parameters.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8930"> + <rect + x="2138.9033" + y="1613" + clip-path="url(#clipPath2)" + fill="none" + width="260.1934" + height="30" + id="rect8932" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8934"> + <rect + x="1284.1455" + y="-474" + clip-path="url(#clipPath2)" + width="101.709" + height="30" + stroke="none" + id="rect8936" /> + <text + x="1291.1455" + y="-454.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8938">./src/plugin.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8940"> + <rect + x="1284.1455" + y="-474" + clip-path="url(#clipPath2)" + fill="none" + width="101.709" + height="30" + id="rect8942" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8944"> + <rect + x="-543.7891" + y="1299" + clip-path="url(#clipPath2)" + width="175.5781" + height="30" + stroke="none" + id="rect8946" /> + <text + x="-536.7891" + y="1318.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8948">./agg/src/agg_arrowhead.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8950"> + <rect + x="-543.7891" + y="1299" + clip-path="url(#clipPath2)" + fill="none" + width="175.5781" + height="30" + id="rect8952" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8954"> + <rect + x="1817.1787" + y="2604.5" + clip-path="url(#clipPath2)" + width="235.6426" + height="30" + stroke="none" + id="rect8956" /> + <text + x="1824.1787" + y="2623.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8958">./bindings/python/mapnik_feature.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8960"> + <rect + x="1817.1787" + y="2604.5" + clip-path="url(#clipPath2)" + fill="none" + width="235.6426" + height="30" + id="rect8962" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8964"> + <rect + x="-855.123" + y="1614.5" + clip-path="url(#clipPath2)" + width="251.2461" + height="30" + stroke="none" + id="rect8966" /> + <text + x="-848.123" + y="1633.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8968">./agg/src/agg_embedded_raster_fonts.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8970"> + <rect + x="-855.123" + y="1614.5" + clip-path="url(#clipPath2)" + fill="none" + width="251.2461" + height="30" + id="rect8972" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8974"> + <rect + x="1669.6777" + y="-220" + clip-path="url(#clipPath2)" + width="122.6445" + height="30" + stroke="none" + id="rect8976" /> + <text + x="1676.6777" + y="-200.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8978">./src/libmapnik.so</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8980"> + <rect + x="1669.6777" + y="-220" + clip-path="url(#clipPath2)" + fill="none" + width="122.6445" + height="30" + id="rect8982" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8984"> + <rect + x="1039.1885" + y="-125.5" + clip-path="url(#clipPath2)" + width="165.623" + height="30" + stroke="none" + id="rect8986" /> + <text + x="1046.1885" + y="-106.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8988">./src/placement_finder.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g8990"> + <rect + x="1039.1885" + y="-125.5" + clip-path="url(#clipPath2)" + fill="none" + width="165.623" + height="30" + id="rect8992" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g8994"> + <rect + x="-165.1045" + y="1004.5" + clip-path="url(#clipPath2)" + width="178.209" + height="30" + stroke="none" + id="rect8996" /> + <text + x="-158.1045" + y="1023.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text8998">./agg/src/agg_sqrt_tables.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9000"> + <rect + x="-165.1045" + y="1004.5" + clip-path="url(#clipPath2)" + fill="none" + width="178.209" + height="30" + id="rect9002" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9004"> + <rect + x="221.5254" + y="1478" + clip-path="url(#clipPath2)" + width="227.9492" + height="30" + stroke="none" + id="rect9006" /> + <text + x="228.5254" + y="1497.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9008">./agg/src/agg_vpgen_clip_polyline.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9010"> + <rect + x="221.5254" + y="1478" + clip-path="url(#clipPath2)" + fill="none" + width="227.9492" + height="30" + id="rect9012" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9014"> + <rect + x="1468.9746" + y="1004" + clip-path="url(#clipPath2)" + width="298.0508" + height="30" + stroke="none" + id="rect9016" /> + <text + x="1475.9746" + y="1023.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9018">./bindings/python/mapnik_raster_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9020"> + <rect + x="1468.9746" + y="1004" + clip-path="url(#clipPath2)" + fill="none" + width="298.0508" + height="30" + id="rect9022" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9024"> + <rect + x="365.8027" + y="2029" + clip-path="url(#clipPath2)" + width="198.3945" + height="30" + stroke="none" + id="rect9026" /> + <text + x="372.8027" + y="2048.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9028">./agg/src/agg_line_profile_aa.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9030"> + <rect + x="365.8027" + y="2029" + clip-path="url(#clipPath2)" + fill="none" + width="198.3945" + height="30" + id="rect9032" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9034"> + <rect + x="915.209" + y="1764.5" + clip-path="url(#clipPath2)" + width="333.582" + height="30" + stroke="none" + id="rect9036" /> + <text + x="922.209" + y="1783.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9038">./bindings/python/mapnik_line_pattern_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9040"> + <rect + x="915.209" + y="1764.5" + clip-path="url(#clipPath2)" + fill="none" + width="333.582" + height="30" + id="rect9042" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9044"> + <rect + x="1297.1729" + y="1293" + clip-path="url(#clipPath2)" + width="223.6543" + height="30" + stroke="none" + id="rect9046" /> + <text + x="1304.1729" + y="1312.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9048">./bindings/python/mapnik_color.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9050"> + <rect + x="1297.1729" + y="1293" + clip-path="url(#clipPath2)" + fill="none" + width="223.6543" + height="30" + id="rect9052" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9054"> + <rect + x="1634.5938" + y="-394" + clip-path="url(#clipPath2)" + width="151.8125" + height="30" + stroke="none" + id="rect9056" /> + <text + x="1641.5938" + y="-374.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9058">./src/proj_transform.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9060"> + <rect + x="1634.5938" + y="-394" + clip-path="url(#clipPath2)" + fill="none" + width="151.8125" + height="30" + id="rect9062" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9064"> + <rect + x="1298.2715" + y="-145.5" + clip-path="url(#clipPath2)" + width="182.457" + height="30" + stroke="none" + id="rect9066" /> + <text + x="1305.2715" + y="-126.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9068">./src/memory_datasource.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9070"> + <rect + x="1298.2715" + y="-145.5" + clip-path="url(#clipPath2)" + fill="none" + width="182.457" + height="30" + id="rect9072" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9074"> + <rect + x="-194.8857" + y="-261" + clip-path="url(#clipPath2)" + width="103.7715" + height="30" + stroke="none" + id="rect9076" /> + <text + x="-187.8857" + y="-241.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9078">./plugins/input</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9080"> + <rect + x="-194.8857" + y="-261" + clip-path="url(#clipPath2)" + fill="none" + width="103.7715" + height="30" + id="rect9082" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9084"> + <rect + x="653.0186" + y="1857.5" + clip-path="url(#clipPath2)" + width="234.9629" + height="30" + stroke="none" + id="rect9086" /> + <text + x="660.0186" + y="1876.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9088">./bindings/python/mapnik_python.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9090"> + <rect + x="653.0186" + y="1857.5" + clip-path="url(#clipPath2)" + fill="none" + width="234.9629" + height="30" + id="rect9092" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9094"> + <rect + x="1588.6523" + y="-617" + clip-path="url(#clipPath2)" + width="130.6953" + height="30" + stroke="none" + id="rect9096" /> + <text + x="1595.6523" + y="-597.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9098">./src/png_reader.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9100"> + <rect + x="1588.6523" + y="-617" + clip-path="url(#clipPath2)" + fill="none" + width="130.6953" + height="30" + id="rect9102" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9104"> + <rect + x="1136.2529" + y="2381.5" + clip-path="url(#clipPath2)" + width="246.4941" + height="30" + stroke="none" + id="rect9106" /> + <text + x="1143.2529" + y="2400.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9108">./bindings/python/mapnik_envelope.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9110"> + <rect + x="1136.2529" + y="2381.5" + clip-path="url(#clipPath2)" + fill="none" + width="246.4941" + height="30" + id="rect9112" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9114"> + <rect + x="1007.5137" + y="1452.5" + clip-path="url(#clipPath2)" + width="230.9727" + height="30" + stroke="none" + id="rect9116" /> + <text + x="1014.5137" + y="1471.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9118">./bindings/python/mapnik_stroke.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9120"> + <rect + x="1007.5137" + y="1452.5" + clip-path="url(#clipPath2)" + fill="none" + width="230.9727" + height="30" + id="rect9122" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9124"> + <rect + x="262.791" + y="323.5" + clip-path="url(#clipPath2)" + width="219.418" + height="30" + stroke="none" + id="rect9126" /> + <text + x="269.791" + y="342.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9128">./plugins/input/shape/shape.input</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9130"> + <rect + x="262.791" + y="323.5" + clip-path="url(#clipPath2)" + fill="none" + width="219.418" + height="30" + id="rect9132" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9134"> + <rect + x="1963.374" + y="1315.5" + clip-path="url(#clipPath2)" + width="227.252" + height="30" + stroke="none" + id="rect9136" /> + <text + x="1970.374" + y="1334.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9138">./bindings/python/mapnik_query.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9140"> + <rect + x="1963.374" + y="1315.5" + clip-path="url(#clipPath2)" + fill="none" + width="227.252" + height="30" + id="rect9142" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9144"> + <rect + x="1342.4521" + y="-878.5" + clip-path="url(#clipPath2)" + width="165.0957" + height="30" + stroke="none" + id="rect9146" /> + <text + x="1349.4521" + y="-859.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9148">./src/point_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9150"> + <rect + x="1342.4521" + y="-878.5" + clip-path="url(#clipPath2)" + fill="none" + width="165.0957" + height="30" + id="rect9152" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9154"> + <rect + x="1478.75" + y="456.5" + clip-path="url(#clipPath2)" + width="138.5" + height="30" + stroke="none" + id="rect9156" /> + <text + x="1485.75" + y="475.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9158">./src/filter_factory.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9160"> + <rect + x="1478.75" + y="456.5" + clip-path="url(#clipPath2)" + fill="none" + width="138.5" + height="30" + id="rect9162" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9164"> + <rect + x="2050.8623" + y="2266.5" + clip-path="url(#clipPath2)" + width="311.2754" + height="30" + stroke="none" + id="rect9166" /> + <text + x="2057.8623" + y="2285.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9168">./bindings/python/mapnik_polygon_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9170"> + <rect + x="2050.8623" + y="2266.5" + clip-path="url(#clipPath2)" + fill="none" + width="311.2754" + height="30" + id="rect9172" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9174"> + <rect + x="-94.2109" + y="2225" + clip-path="url(#clipPath2)" + width="236.4219" + height="30" + stroke="none" + id="rect9176" /> + <text + x="-87.2109" + y="2244.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9178">./agg/src/agg_vcgen_smooth_poly1.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9180"> + <rect + x="-94.2109" + y="2225" + clip-path="url(#clipPath2)" + fill="none" + width="236.4219" + height="30" + id="rect9182" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9184"> + <rect + x="-372.2812" + y="106.5" + clip-path="url(#clipPath2)" + width="305.5625" + height="30" + stroke="none" + id="rect9186" /> + <text + x="-365.2812" + y="125.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9188">./plugins/input/shape/shape_index_featureset.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9190"> + <rect + x="-372.2812" + y="106.5" + clip-path="url(#clipPath2)" + fill="none" + width="305.5625" + height="30" + id="rect9192" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9194"> + <rect + x="833.4131" + y="2166" + clip-path="url(#clipPath2)" + width="220.1738" + height="30" + stroke="none" + id="rect9196" /> + <text + x="840.4131" + y="2185.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9198">./bindings/python/python_cairo.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9200"> + <rect + x="833.4131" + y="2166" + clip-path="url(#clipPath2)" + fill="none" + width="220.1738" + height="30" + id="rect9202" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9204"> + <rect + x="2146.6162" + y="-496" + clip-path="url(#clipPath2)" + width="128.7676" + height="30" + stroke="none" + id="rect9206" /> + <text + x="2153.6162" + y="-476.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9208">./src/symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9210"> + <rect + x="2146.6162" + y="-496" + clip-path="url(#clipPath2)" + fill="none" + width="128.7676" + height="30" + id="rect9212" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9214"> + <rect + x="1412.8066" + y="2339" + clip-path="url(#clipPath2)" + width="194.3867" + height="30" + stroke="none" + id="rect9216" /> + <text + x="1419.8066" + y="2358.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9218">./bindings/python/_mapnik.so</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9220"> + <rect + x="1412.8066" + y="2339" + clip-path="url(#clipPath2)" + fill="none" + width="194.3867" + height="30" + id="rect9222" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9224"> + <rect + x="179.0781" + y="2247.5" + clip-path="url(#clipPath2)" + width="182.8438" + height="30" + stroke="none" + id="rect9226" /> + <text + x="186.0781" + y="2266.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9228">./agg/src/agg_trans_affine.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9230"> + <rect + x="179.0781" + y="2247.5" + clip-path="url(#clipPath2)" + fill="none" + width="182.8438" + height="30" + id="rect9232" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9234"> + <rect + x="862.0352" + y="-594" + clip-path="url(#clipPath2)" + width="229.9297" + height="30" + stroke="none" + id="rect9236" /> + <text + x="869.0352" + y="-574.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9238">./src/polygon_pattern_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9240"> + <rect + x="862.0352" + y="-594" + clip-path="url(#clipPath2)" + fill="none" + width="229.9297" + height="30" + id="rect9242" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9244"> + <rect + x="2093.7627" + y="2629.5" + clip-path="url(#clipPath2)" + width="359.4746" + height="30" + stroke="none" + id="rect9246" /> + <text + x="2100.7627" + y="2648.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9248">./bindings/python/mapnik_polygon_pattern_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9250"> + <rect + x="2093.7627" + y="2629.5" + clip-path="url(#clipPath2)" + fill="none" + width="359.4746" + height="30" + id="rect9252" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9254"> + <rect + x="-258.3594" + y="1764.5" + clip-path="url(#clipPath2)" + width="151.7188" + height="30" + stroke="none" + id="rect9256" /> + <text + x="-251.3594" + y="1783.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9258">./agg/src/agg_curves.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9260"> + <rect + x="-258.3594" + y="1764.5" + clip-path="url(#clipPath2)" + fill="none" + width="151.7188" + height="30" + id="rect9262" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9264"> + <rect + x="1277.6055" + y="-635" + clip-path="url(#clipPath2)" + width="157.7891" + height="30" + stroke="none" + id="rect9266" /> + <text + x="1284.6055" + y="-615.5791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9268">./src/text_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9270"> + <rect + x="1277.6055" + y="-635" + clip-path="url(#clipPath2)" + fill="none" + width="157.7891" + height="30" + id="rect9272" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9274"> + <rect + x="1546.2705" + y="-843.5" + clip-path="url(#clipPath2)" + width="174.459" + height="30" + stroke="none" + id="rect9276" /> + <text + x="1553.2705" + y="-824.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9278">./src/scale_denominator.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9280"> + <rect + x="1546.2705" + y="-843.5" + clip-path="url(#clipPath2)" + fill="none" + width="174.459" + height="30" + id="rect9282" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9284"> + <rect + x="628.8291" + y="31.5" + clip-path="url(#clipPath2)" + width="219.3418" + height="30" + stroke="none" + id="rect9286" /> + <text + x="635.8291" + y="50.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9288">./plugins/input/shape/shape_io.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9290"> + <rect + x="628.8291" + y="31.5" + clip-path="url(#clipPath2)" + fill="none" + width="219.3418" + height="30" + id="rect9292" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9294"> + <rect + x="1505.0986" + y="-439.5" + clip-path="url(#clipPath2)" + width="92.8027" + height="30" + stroke="none" + id="rect9296" /> + <text + x="1512.0986" + y="-420.0791" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9298">./src/layer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9300"> + <rect + x="1505.0986" + y="-439.5" + clip-path="url(#clipPath2)" + fill="none" + width="92.8027" + height="30" + id="rect9302" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9304"> + <rect + x="-40.8408" + y="2038" + clip-path="url(#clipPath2)" + width="45.6816" + height="30" + stroke="none" + id="rect9306" /> + <text + x="-33.8408" + y="2057.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9308">./agg</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9310"> + <rect + x="-40.8408" + y="2038" + clip-path="url(#clipPath2)" + fill="none" + width="45.6816" + height="30" + id="rect9312" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9314"> + <rect + x="1874.2168" + y="-5.5" + clip-path="url(#clipPath2)" + width="151.5664" + height="30" + stroke="none" + id="rect9316" /> + <text + x="1881.2168" + y="13.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9318">./src/libxml2_loader.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9320"> + <rect + x="1874.2168" + y="-5.5" + clip-path="url(#clipPath2)" + fill="none" + width="151.5664" + height="30" + id="rect9322" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9324"> + <rect + x="-801.0898" + y="1201.5" + clip-path="url(#clipPath2)" + width="229.1797" + height="30" + stroke="none" + id="rect9326" /> + <text + x="-794.0898" + y="1220.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9328">./agg/src/agg_vpgen_clip_polygon.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9330"> + <rect + x="-801.0898" + y="1201.5" + clip-path="url(#clipPath2)" + fill="none" + width="229.1797" + height="30" + id="rect9332" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9334"> + <rect + x="151.7529" + y="97.5" + clip-path="url(#clipPath2)" + width="144.4941" + height="30" + stroke="none" + id="rect9336" /> + <text + x="158.7529" + y="116.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9338">./plugins/input/shape</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9340"> + <rect + x="151.7529" + y="97.5" + clip-path="url(#clipPath2)" + fill="none" + width="144.4941" + height="30" + id="rect9342" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9344"> + <rect + x="543.2588" + y="2286.5" + clip-path="url(#clipPath2)" + width="249.4824" + height="30" + stroke="none" + id="rect9346" /> + <text + x="550.2588" + y="2305.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9348">./bindings/python/mapnik_geometry.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9350"> + <rect + x="543.2588" + y="2286.5" + clip-path="url(#clipPath2)" + fill="none" + width="249.4824" + height="30" + id="rect9352" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9354"> + <rect + x="923.333" + y="1091.5" + clip-path="url(#clipPath2)" + width="287.334" + height="30" + stroke="none" + id="rect9356" /> + <text + x="930.333" + y="1110.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9358">./bindings/python/mapnik_text_symbolizer.os</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9360"> + <rect + x="923.333" + y="1091.5" + clip-path="url(#clipPath2)" + fill="none" + width="287.334" + height="30" + id="rect9362" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9364"> + <rect + x="433.3008" + y="1806" + clip-path="url(#clipPath2)" + width="191.3984" + height="30" + stroke="none" + id="rect9366" /> + <text + x="440.3008" + y="1825.4209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9368">./agg/src/agg_rounded_rect.o</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9370"> + <rect + x="433.3008" + y="1806" + clip-path="url(#clipPath2)" + fill="none" + width="191.3984" + height="30" + id="rect9372" /> + </g> + <g + fill="rgb(187,196,94)" + fill-opacity="0.098" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + stroke-opacity="0.098" + stroke="rgb(187,196,94)" + id="g9374"> + <rect + x="1541.252" + y="2065.5" + clip-path="url(#clipPath2)" + width="121.4961" + height="30" + stroke="none" + id="rect9376" /> + <text + x="1548.252" + y="2084.9209" + clip-path="url(#clipPath2)" + fill="rgb(86,95,145)" + font-family="sans-serif" + stroke="none" + xml:space="preserve" + id="text9378">./bindings/python</text> + </g> + <g + stroke-linecap="butt" + transform="matrix(0.1497,0,0,0.1497,130.3567,193.5146)" + fill-opacity="0.098" + fill="rgb(86,95,145)" + stroke="rgb(86,95,145)" + stroke-opacity="0.098" + stroke-miterlimit="1.45" + id="g9380"> + <rect + x="1541.252" + y="2065.5" + clip-path="url(#clipPath2)" + fill="none" + width="121.4961" + height="30" + id="rect9382" /> + <path + fill="none" + d="M2577.5508 2232.655 L2889.043 2264.1677" + clip-path="url(#clipPath2)" + id="path9384" /> + <path + fill="none" + d="M24.5742 1698.3611 L185.0576 1702.3578" + clip-path="url(#clipPath2)" + id="path9386" /> + <path + fill="none" + d="M-31.6769 1682.5 L-131.8263 1613.1986 L-307.8319 1479.7761 L-322.1423 1467.1691 L-335.9341 1453.8378 L-420.4944 1355.8801 L-431.8936 1341.8081 L-442.9968 1329" + clip-path="url(#clipPath2)" + id="path9388" /> + <path + fill="none" + d="M7.2593 1682.5 L170.8382 1540.3337 L183.5103 1528.4264 L195.0703 1515.1906 L203.2204 1499.588 L208.0298 1482.4165 L212.1165 1464.9495 L217.4223 1447.5245 L224.4582 1430.9707 L348.8411 1215.5" + clip-path="url(#clipPath2)" + id="path9390" /> + <path + fill="none" + d="M-30.3421 1682.5 L-117.9062 1617.9313 L-127.6741 1609.3701 L-136.938 1599.8932 L-145.2881 1589.3641 L-152.7591 1578.7178 L-251.9406 1414.5" + clip-path="url(#clipPath2)" + id="path9392" /> + <path + fill="none" + d="M-41.5549 1712.5 L-150.9451 1764.5" + clip-path="url(#clipPath2)" + id="path9394" /> + <path + fill="none" + d="M-44.5742 1694.2324 L-603.877 1641.3727" + clip-path="url(#clipPath2)" + id="path9396" /> + <path + fill="none" + d="M-0.4959 1682.5 L5.2959 1673.359 L54.5589 1589.4877 L61.0658 1576.5562 L66.893 1562.6425 L71.3597 1548.4495 L73.9725 1533.6312 L74.9174 1518.3745 L73.7647 1503.0833 L70.803 1487.9604 L65.953 1473.3381 L59.488 1459.3448 L52.1157 1446.1976 L-42.0651 1304" + clip-path="url(#clipPath2)" + id="path9398" /> + <path + fill="none" + d="M-7.5982 1712.5 L14.0982 1848" + clip-path="url(#clipPath2)" + id="path9400" /> + <path + fill="none" + d="M8.3456 1712.5 L221.1544 1886.5" + clip-path="url(#clipPath2)" + id="path9402" /> + <path + fill="none" + d="M24.5742 1709.7097 L224.8548 1780.4376 L274.5859 1796.1027 L290.3831 1803.1301 L305.0963 1812.2388 L317.8884 1823.064 L329.0148 1835.4955 L338.6302 1848.3523 L455.3114 2029" + clip-path="url(#clipPath2)" + id="path9404" /> + <path + fill="none" + d="M24.5742 1709.5155 L220.8472 1777.7257 L238.4817 1782.3004 L324.5341 1794.4855 L341.7867 1796.4042 L433.3008 1808.4272" + clip-path="url(#clipPath2)" + id="path9406" /> + <path + fill="none" + d="M-0.9936 1682.5 L50.1437 1597.332 L57.3786 1583.8605 L63.929 1570.2368 L69.2742 1555.1427 L72.9572 1539.9404 L74.755 1524.0978 L74.5616 1508.144 L69.7308 1462.8016 L67.2398 1448.1791 L46.6858 1301.0886 L40.6985 1270.2456 L36.1484 1254.5295 L30.1596 1239.6921 L-68.7682 1034.5" + clip-path="url(#clipPath2)" + id="path9408" /> + <path + fill="none" + d="M7.5011 1712.5 L84.9684 1778.8966 L97.4166 1792.4541 L107.5913 1806.808 L115.5777 1822.2261 L120.8528 1838.3977 L123.3011 1854.1149 L127.3981 1901.7179 L129.5949 1917.3544 L132.8063 1932.9053 L137.6825 1947.8722 L264.1679 2247.5" + clip-path="url(#clipPath2)" + id="path9410" /> + <path + fill="none" + d="M-30.3804 1682.5 L-109.8009 1624.0464 L-121.1156 1614.7283 L-132.1969 1604.0846 L-142.184 1592.3759 L-150.7367 1579.3018 L-157.7693 1565.1106 L-163.0598 1550.7333 L-165.983 1534.505 L-167.597 1518.8418 L-168.8886 1410.1838 L-169.9251 1394.0894 L-172.5114 1377.2661 L-176.7595 1361.7198 L-298.6194 1022" + clip-path="url(#clipPath2)" + id="path9412" /> + <path + fill="none" + d="M-13.0252 1682.5 L-42.9748 1534" + clip-path="url(#clipPath2)" + id="path9414" /> + <path + fill="none" + d="M24.5742 1687.3417 L211.2763 1632.4862 L230.4907 1627.6432 L250.3716 1624.6504 L328.7023 1621.3073 L348.4196 1619.7538 L368.0745 1617.4214 L510.9839 1592.5" + clip-path="url(#clipPath2)" + id="path9416" /> + <path + fill="none" + d="M-44.5742 1695.8385 L-164.7434 1690.0634 L-177.8356 1690.061 L-191.578 1690.8328 L-204.8772 1693.3619 L-217.7414 1697.4427 L-240.9324 1708.3999 L-358.6783 1775.5" + clip-path="url(#clipPath2)" + id="path9418" /> + <path + fill="none" + d="M7.529 1682.5 L138.9264 1570.0598 L148.6751 1560.6741 L158.7948 1552.2384 L178.7862 1533.6653 L188.7202 1523.3728 L197.5696 1511.4668 L203.8828 1497.4987 L207.8515 1482.9614 L211.1029 1467.9121 L215.285 1452.8943 L221.2153 1438.4976 L228.5741 1424.6746 L238.2442 1412.2913 L248.6876 1400.8505 L261.0592 1390.6781 L274.4546 1382.137 L288.1776 1374.8389 L315.8387 1363.2257 L561.9354 1276.5" + clip-path="url(#clipPath2)" + id="path9420" /> + <path + fill="none" + d="M-1.1162 1682.5 L53.6143 1590.0895 L61.9957 1573.4156 L68.9728 1555.3479 L73.5761 1536.5132 L76.2372 1517.584 L79.7695 1480.3877 L82.222 1461.5187 L145.9323 1150" + clip-path="url(#clipPath2)" + id="path9422" /> + <path + fill="none" + d="M-21.1026 1712.5 L-106.8676 1828.3712 L-116.5694 1839.3942 L-127.7954 1849.3232 L-139.8821 1858.0498 L-165.3045 1872.8499 L-284.2802 1934.2721 L-298.4405 1942.3529 L-312.5903 1951.3605 L-339.184 1971.7175 L-480.0865 2086.5" + clip-path="url(#clipPath2)" + id="path9424" /> + <path + fill="none" + d="M-19.2353 1712.5 L-60.2772 1779.1603 L-74.3468 1803.9298 L-80.6547 1816.9384 L-86.1567 1831.2423 L-89.365 1846.1083 L-90.6617 1861.1736 L-90.0964 1876.3617 L-86.5496 1891.6437 L-81.7927 1905.8558 L-74.9382 1919.4861 L-66.4475 1932.3898 L-47.7518 1955.9055 L9.8738 2025.3236 L17.6516 2039.1315 L21.1875 2054.6111 L23.7724 2225" + clip-path="url(#clipPath2)" + id="path9426" /> + <path + fill="none" + d="M-44.5742 1685.7426 L-436.3906 1552.5" + clip-path="url(#clipPath2)" + id="path9428" /> + <path + fill="none" + d="M-34.4191 1682.5 L-422.8861 1443.8751 L-438.5209 1435.4724 L-485.9133 1412.2606 L-501.7971 1403.8612 L-517.0173 1393.6337 L-530.9767 1381.8546 L-672.3918 1231.5" + clip-path="url(#clipPath2)" + id="path9430" /> + <path + fill="none" + d="M15.3423 1682.5 L310.1577 1508" + clip-path="url(#clipPath2)" + id="path9432" /> + <path + fill="none" + d="M-19.574 1712.5 L-228.926 2040.5" + clip-path="url(#clipPath2)" + id="path9434" /> + <path + fill="none" + d="M1705.7683 -190 L1229.7317 93" + clip-path="url(#clipPath2)" + id="path9436" /> + <path + fill="none" + d="M1792.3223 -207.5711 L1889.0596 -211.6272 L1904.3265 -213.2381 L1919.7518 -216.2674 L1934.6373 -220.1078 L2143.3914 -289.0011" + clip-path="url(#clipPath2)" + id="path9438" /> + <path + fill="none" + d="M1778.2689 -190 L1871.4453 -160.432" + clip-path="url(#clipPath2)" + id="path9440" /> + <path + fill="none" + d="M1737.709 -220 L1784.8777 -325.4607 L1792.1422 -343.3415 L1797.3993 -362.1091 L1798.9524 -381.2829 L1796.4418 -400.2448 L1791.0763 -418.4256 L1784.3788 -435.7887 L1742.769 -535.712 L1737.2317 -553.2609 L1736.0367 -571.5535 L1739.8428 -589.6634 L1745.2104 -606.9964 L1803.3124 -775" + clip-path="url(#clipPath2)" + id="path9442" /> + <path + fill="none" + d="M1722.7018 -190 L1671.9998 -98.3503 L1664.8926 -83.9824 L1658.9614 -68.4607 L1656.0035 -52.007 L1657.1727 -35.4369 L1662.0831 -19.4679 L1703.2703 67.3736 L1708.6812 82.8308 L1711.2114 99.089 L1709.9719 115.4139 L1705.568 131.1046 L1687.5476 173.7935 L1681.0388 187.5816 L1675.4331 201.3511 L1662.2848 228.414 L1555.0521 456.5" + clip-path="url(#clipPath2)" + id="path9444" /> + <path + fill="none" + d="M1737.8416 -220 L1790.4821 -335.4135 L1796.799 -350.5091 L1942.6581 -740.9563 L1956.9553 -771.0897 L2024.962 -898" + clip-path="url(#clipPath2)" + id="path9446" /> + <path + fill="none" + d="M1730.4249 -190 L1725.5751 -63.5" + clip-path="url(#clipPath2)" + id="path9448" /> + <path + fill="none" + d="M1715.6113 -220 L1609.3069 -323.6192 L1597.2324 -332.56 L1584.4562 -339.7423 L1534.261 -364.9576 L1521.441 -372.2469 L1509.2654 -381.3355 L1498.1863 -390.8954 L1395.7156 -491.3533 L1384.5231 -501.4753 L1372.7471 -511.0984 L1359.075 -518.9822 L1316.8344 -536.9285 L1302.9846 -545.2017 L1290.5354 -554.8357 L1278.8702 -565.0334 L1206.5126 -635" + clip-path="url(#clipPath2)" + id="path9450" /> + <path + fill="none" + d="M1721.9266 -190 L1674.641 -111.8283 L1585.7194 54.9422 L1578.7654 70.2131 L1572.662 85.898 L1536.8547 246" + clip-path="url(#clipPath2)" + id="path9452" /> + <path + fill="none" + d="M1737.8553 -220 L1793.4465 -341.6367 L1861.5244 -516.049 L1869.9036 -533.5408 L1879.9336 -550.3941 L1891.3851 -566.1861 L2006.2628 -707" + clip-path="url(#clipPath2)" + id="path9454" /> + <path + fill="none" + d="M1718.7335 -220 L1563.7665 -409.5" + clip-path="url(#clipPath2)" + id="path9456" /> + <path + fill="none" + d="M1743.1837 -220 L1839.7024 -338.8295 L1870.7987 -373.4109 L1959.0747 -468.5" + clip-path="url(#clipPath2)" + id="path9458" /> + <path + fill="none" + d="M1737.6589 -220 L1759.5264 -269.2584 L1789.1104 -333.3076 L1793.4485 -345.0605 L1797.1232 -357.1674 L1799.2274 -369.9363 L1800.329 -382.1035 L1800.6512 -394.3187 L1795.0359 -551.5" + clip-path="url(#clipPath2)" + id="path9460" /> + <path + fill="none" + d="M1686 -220 L1444.5 -300.5" + clip-path="url(#clipPath2)" + id="path9462" /> + <path + fill="none" + d="M1737.9821 -190 L1759.0538 -144.7306 L1763.9989 -132.3875 L1786.4437 -83.6733 L1791.2949 -70.4718 L1794.7535 -56.8085 L1823.2671 190" + clip-path="url(#clipPath2)" + id="path9464" /> + <path + fill="none" + d="M1792.3223 -205.6755 L1912.9915 -207.0047 L1925.9236 -205.9872 L1938.9326 -203.1653 L1962.4874 -194.9545 L2073.5273 -148" + clip-path="url(#clipPath2)" + id="path9466" /> + <path + fill="none" + d="M1669.6777 -210.6785 L1654.0314 -212.1274 L1634.9186 -214.42 L1615.7456 -215.458 L1429.9047 -232.3959 L1393.85 -234.3698 L1375.6881 -233.3309 L1359.0819 -229.8459 L1342.7466 -224.1006 L1327.733 -217.4407 L1150.8571 -125.5" + clip-path="url(#clipPath2)" + id="path9468" /> + <path + fill="none" + d="M1715.6975 -220 L1618.0374 -315.7292 L1606.6896 -325.8326 L1593.8826 -334.5842 L1498.2308 -379.2232 L1365.6914 -444" + clip-path="url(#clipPath2)" + id="path9470" /> + <path + fill="none" + d="M1719.4562 -220 L1647.702 -313.2364 L1639.4208 -324.8945 L1631.936 -337.4316 L1626.1655 -351.033 L1622.7638 -364.8717 L1621.6257 -379.3865 L1622.1956 -393.6915 L1651.7098 -587" + clip-path="url(#clipPath2)" + id="path9472" /> + <path + fill="none" + d="M1719.4407 -220 L1647.3424 -313.5588 L1638.4584 -326.7014 L1630.6166 -340.589 L1624.4246 -356.2978 L1621.1759 -371.7042 L1611.754 -432.9737 L1608.1443 -448.4993 L1571.5094 -565.6849 L1565.8434 -580.5214 L1432.4658 -848.5" + clip-path="url(#clipPath2)" + id="path9474" /> + <path + fill="none" + d="M1689.9011 -220 L1579.2606 -260.3808 L1562.4448 -268.2509 L1547.4619 -279.0468 L1453.738 -366.6343 L1438.5922 -377.8836 L1421.4435 -385.7967 L1403.1199 -389.4229 L1331.2155 -394.633 L1313.1571 -398.5897 L1296.312 -405.6636 L1004.6323 -564" + clip-path="url(#clipPath2)" + id="path9476" /> + <path + fill="none" + d="M1761.4546 -220 L1868.0454 -272.5" + clip-path="url(#clipPath2)" + id="path9478" /> + <path + fill="none" + d="M1737.8378 -190 L1782.3468 -92.3615 L1788.3433 -77.1847 L1792.8481 -60.652 L1794.0735 -43.5573 L1792.6171 -26.5087 L1758.4685 174.4238 L1756.068 191.6194 L1755.7196 208.9639 L1758.5198 225.972 L1763.705 241.887 L1786.6254 300.2224 L1792.8827 313.9514 L1798.786 328.3393 L1828.4285 396" + clip-path="url(#clipPath2)" + id="path9480" /> + <path + fill="none" + d="M1715.6499 -220 L1613.6167 -319.7058 L1600.3414 -330.6942 L1585.488 -339.5492 L1539.1113 -362.3184 L1523.2679 -371.3719 L1508.7147 -382.5849 L1496.9186 -396.8426 L1365.9385 -605" + clip-path="url(#clipPath2)" + id="path9482" /> + <path + fill="none" + d="M1669.6777 -211.4206 L1570.3632 -221.8192 L1552.5938 -223.1205 L1391.7688 -241.755 L1373.3782 -245.8518 L1216.3251 -299" + clip-path="url(#clipPath2)" + id="path9484" /> + <path + fill="none" + d="M1719.3217 -220 L1652.9008 -305.3127 L1637.6135 -327.1343 L1630.889 -339.1896 L1625.6447 -352.1444 L1622.0043 -365.6252 L1617.4021 -392.0246 L1616.0254 -404.7892 L1611.8835 -431.1289 L1608.2532 -444.5484 L1601.9314 -457.2315 L1593.8871 -468.5936 L1525.8938 -542" + clip-path="url(#clipPath2)" + id="path9486" /> + <path + fill="none" + d="M1719.7517 -190 L1512.821 85.951 L1501.3052 99.9877 L1488.329 112.7794 L1384.1188 201.5" + clip-path="url(#clipPath2)" + id="path9488" /> + <path + fill="none" + d="M1729.2328 -220 L1712.2672 -364" + clip-path="url(#clipPath2)" + id="path9490" /> + <path + fill="none" + d="M1722.5846 -190 L1681.4597 -116.6974 L1674.6794 -103.1759 L1667.4226 -89.8639 L1660.6564 -74.698 L1656.6792 -58.9427 L1653.626 -41.7401 L1651.9781 -24.6842 L1650.8036 -7.3245 L1649.0201 10.5424 L1642.7401 86.5" + clip-path="url(#clipPath2)" + id="path9492" /> + <path + fill="none" + d="M1719.2087 -220 L1694.7434 -251.1231 L1686.0302 -263.1407 L1649.7358 -309.5934 L1641.0094 -322.1074 L1632.9093 -335.3819 L1626.6534 -350.1132 L1622.9349 -365.8031 L1621.8632 -381.9264 L1623.8821 -397.968 L1628.7859 -413.585 L1635.8981 -428.3178 L1712.8442 -546.8633 L1721.0911 -560.9402 L1727.7742 -576.067 L1731.7117 -592.0207 L1732.0756 -608.6171 L1729.2048 -624.3967 L1717.8364 -653.6657 L1673.2709 -747.8106 L1666.1648 -761.2916 L1660.1403 -774.6749 L1640.9241 -813.5" + clip-path="url(#clipPath2)" + id="path9494" /> + <path + fill="none" + d="M1669.6777 -191.6222 L1458.2584 -145.5" + clip-path="url(#clipPath2)" + id="path9496" /> + <path + fill="none" + d="M1739.1447 -190 L1863.7595 39.5027 L1871.1771 51.7794 L1879.2983 64.0357 L1898.2384 86.2591 L1960.827 152.5" + clip-path="url(#clipPath2)" + id="path9498" /> + <path + fill="none" + d="M1743.6166 -220 L1839.2838 -333.7397 L1850.5449 -344.3013 L1863.4709 -352.6133 L1878.0291 -358.5926 L1893.3893 -361.687 L1968.7413 -367.1797 L1984.5386 -369.0039 L2000.3026 -372.444 L2016.0938 -377.015 L2030.8204 -383.4816 L2045.321 -390.3967 L2183.5708 -466" + clip-path="url(#clipPath2)" + id="path9500" /> + <path + fill="none" + d="M1715.2642 -190 L1468.7358 45" + clip-path="url(#clipPath2)" + id="path9502" /> + <path + fill="none" + d="M1738.1113 -190 L1823.2002 -10.5217 L1911.3304 184.7965 L1921.2964 202.1295 L1933.5916 217.8769 L2028.3225 311.5" + clip-path="url(#clipPath2)" + id="path9504" /> + <path + fill="none" + d="M1746.3147 -190 L1934.6853 -5.5" + clip-path="url(#clipPath2)" + id="path9506" /> + <path + fill="none" + d="M1719.8269 -189.9794 L1710.9945 -178.7845 L1516.5352 81.5281 L1506.3717 94.2074 L1495.1205 106.1388 L1481.5793 115.3665 L1466.39 121.0814 L1450.9139 124.6082 L1362.7417 139.9343 L1347.4766 143.7284 L1332.6359 149.6314 L1319.3198 158.2387 L1307.5835 169.312 L1287.3872 193.3884 L672.594 973.4279 L441.6343 1256.7087 L430.5662 1268.6992 L418.3392 1279.9236 L405.4018 1289.8066 L264.9038 1384.0872 L163.1076 1464" + clip-path="url(#clipPath2)" + id="path9508" /> + <path + fill="none" + d="M250.5503 127.5 L428.9006 228.2618 L462.1554 250.634 L726.0931 440" + clip-path="url(#clipPath2)" + id="path9510" /> + <path + fill="none" + d="M233.8562 127.5 L362.6438 323.5" + clip-path="url(#clipPath2)" + id="path9512" /> + <path + fill="none" + d="M233.7425 97.5 L409.7575 -173.5" + clip-path="url(#clipPath2)" + id="path9514" /> + <path + fill="none" + d="M225.5602 127.5 L249.045 353.2842 L331.5446 772" + clip-path="url(#clipPath2)" + id="path9516" /> + <path + fill="none" + d="M151.7529 113.9661 L-66.7188 118.3996" + clip-path="url(#clipPath2)" + id="path9518" /> + <path + fill="none" + d="M296.2471 103.2322 L628.8291 60.5686" + clip-path="url(#clipPath2)" + id="path9520" /> + <path + fill="none" + d="M214.4915 127.5 L-46.9915 540" + clip-path="url(#clipPath2)" + id="path9522" /> + <path + fill="none" + d="M2239.3679 1998 L2155.4436 2071.4805 L2143.0876 2080.9946 L2129.8374 2089.5989 L2115.9492 2096.5876 L2101.1887 2102.0188 L2086.0796 2105.4854 L2071.1526 2107.5623 L1841.6396 2119.9771 L1826.8549 2120.2129 L1811.7775 2119.8667 L1796.7798 2118.3806 L1662.748 2092.3142" + clip-path="url(#clipPath2)" + id="path9524" /> + <path + fill="none" + d="M1572.8621 -285.5 L1490.1808 -98.6625 L1481.3794 -82.0423 L1470.7261 -66.2432 L1457.8481 -52.605 L1443.4885 -41.2841 L1412.5255 -21.1364 L1228.6635 93" + clip-path="url(#clipPath2)" + id="path9526" /> + <path + fill="none" + d="M1574.2365 -285.5 L1458.2635 45" + clip-path="url(#clipPath2)" + id="path9528" /> + <path + fill="none" + d="M1600.1318 -297.875 L1738.1715 -280.3118 L1750.5458 -277.2058 L1762.5206 -272.6636 L1773.9989 -266.3214 L1784.2484 -258.9727 L1900.7533 -160.5" + clip-path="url(#clipPath2)" + id="path9530" /> + <path + fill="none" + d="M1600.1318 -298.6243 L1682.269 -291.1569 L1699.8048 -290.2136 L1717.6859 -290.6404 L1735.2581 -293.9877 L1751.9829 -299.9295 L1782.4274 -314.1314 L1796.3497 -321.4707 L1811.2347 -328.2465 L1839.545 -342.5801 L1868.8745 -355.7003 L1884.9718 -359.8295 L1900.8519 -361.6436 L1917.1348 -359.9464 L2114.6455 -319" + clip-path="url(#clipPath2)" + id="path9532" /> + <path + fill="none" + d="M1581.8135 -285.5 L1639.1865 86.5" + clip-path="url(#clipPath2)" + id="path9534" /> + <path + fill="none" + d="M1585.9137 -315.5 L1626.9812 -411.5464 L1635.4854 -427.641 L1709.5739 -541.4645 L1718.5413 -556.3099 L1726.7808 -571.8899 L1802.88 -775" + clip-path="url(#clipPath2)" + id="path9536" /> + <path + fill="none" + d="M1579.1661 -285.5 L1570.9286 84.607 L1571.356 101.6438 L1573.7692 118.6585 L1578.5906 135.3658 L1612.851 229.6021 L1617.0092 246.5683 L1617.9976 264.2934 L1615.7949 281.7931 L1611.1025 298.5992 L1553.4745 456.5" + clip-path="url(#clipPath2)" + id="path9538" /> + <path + fill="none" + d="M1585.9491 -315.5 L1628.7637 -415.0833 L1636.6608 -429.5917 L1716.1844 -549.9628 L1741.313 -592.6497 L1751.0687 -606.4507 L1761.7155 -618.8658 L2019.1653 -898" + clip-path="url(#clipPath2)" + id="path9540" /> + <path + fill="none" + d="M1588.1608 -285.5 L1716.3392 -63.5" + clip-path="url(#clipPath2)" + id="path9542" /> + <path + fill="none" + d="M1564.959 -315.5 L1392.1792 -493.7342 L1380.0123 -505.272 L1366.1857 -515.327 L1350.8662 -522.8212 L1319.0122 -536.3331 L1303.6681 -545.1216 L1289.8102 -555.9888 L1276.7415 -567.3019 L1252.1761 -591.2873 L1206.6294 -635" + clip-path="url(#clipPath2)" + id="path9544" /> + <path + fill="none" + d="M1578.2711 -285.5 L1534.7289 246" + clip-path="url(#clipPath2)" + id="path9546" /> + <path + fill="none" + d="M1585.9148 -315.5 L1623.9624 -404.4688 L1630.5997 -418.2294 L1638.6387 -431.1348 L1648.6869 -442.6392 L1660.5364 -452.3571 L1673.6339 -459.9249 L1687.4928 -466.009 L1797.6302 -504.2472 L1812.218 -509.8861 L1826.6222 -517.39 L1839.3597 -527.7557 L1862.4513 -551.5592 L1932.7964 -628.1892 L1945.5214 -641.296 L2004.9359 -707" + clip-path="url(#clipPath2)" + id="path9548" /> + <path + fill="none" + d="M1576.1129 -315.5 L1554.8871 -409.5" + clip-path="url(#clipPath2)" + id="path9550" /> + <path + fill="none" + d="M1600.1318 -287.4944 L1707.2042 -220" + clip-path="url(#clipPath2)" + id="path9552" /> + <path + fill="none" + d="M1589.1985 -285.5 L1661.0529 -174.3671 L1671.0265 -160.6411 L1682.8058 -148.7924 L1696.5781 -138.8818 L1710.4188 -131.841 L1753.0952 -113.1987 L1780.0155 -98.1506 L1926.3145 -5.5" + clip-path="url(#clipPath2)" + id="path9554" /> + <path + fill="none" + d="M1600.1318 -298.6609 L1686.9719 -290.92 L1702.6021 -290.1562 L1718.5648 -290.5393 L1734.2698 -293.5994 L1749.1108 -299.236 L1762.6196 -306.9124 L1786.0736 -324.64 L1955.3499 -468.5" + clip-path="url(#clipPath2)" + id="path9556" /> + <path + fill="none" + d="M1558.8682 -302.2193 L1460.1221 -310.4482" + clip-path="url(#clipPath2)" + id="path9558" /> + <path + fill="none" + d="M1585.8168 -315.5 L1625.8408 -410.543 L1631.3073 -420.9417 L1637.6289 -430.8379 L1645.0138 -440.2143 L1653.0944 -448.5581 L1669.6295 -463.5915 L1776.2988 -551.5" + clip-path="url(#clipPath2)" + id="path9560" /> + <path + fill="none" + d="M1583.7883 -285.5 L1651.3751 -49.0925 L1657.1646 -31.9459 L1664.5016 -14.997 L1674.2026 0.9056 L1813.9171 190" + clip-path="url(#clipPath2)" + id="path9562" /> + <path + fill="none" + d="M1562.7354 -285.5 L1406.2646 -145.5" + clip-path="url(#clipPath2)" + id="path9564" /> + <path + fill="none" + d="M1600.1318 -297.8126 L1735.9352 -280.1231 L1753.366 -275.8355 L1770.0992 -269.3911 L1786.1671 -261.7391 L1846.3505 -230.1474 L1862.1223 -222.5492 L1878.9531 -216.0268 L1896.1616 -211.8175 L1930.9523 -204.9131 L1948.24 -199.5791 L2072.7815 -148" + clip-path="url(#clipPath2)" + id="path9566" /> + <path + fill="none" + d="M1558.8682 -293.0663 L1433.3401 -247.8382 L1418.0536 -243.2349 L1402.4036 -239.6292 L1370.939 -233.1345 L1355.0715 -228.8596 L1340.0222 -222.6089 L1151.171 -125.5" + clip-path="url(#clipPath2)" + id="path9568" /> + <path + fill="none" + d="M1558.8682 -313.8748 L1358.1388 -444" + clip-path="url(#clipPath2)" + id="path9570" /> + <path + fill="none" + d="M1583.8586 -315.5 L1612.3093 -413.4114 L1650.684 -587" + clip-path="url(#clipPath2)" + id="path9572" /> + <path + fill="none" + d="M1566.2933 -315.5 L1514.8843 -373.89 L1504.1537 -387.4749 L1495.3708 -403.1423 L1489.4203 -419.789 L1460.8938 -520.2078 L1456.6606 -538.3257 L1453.6722 -556.3632 L1452.3645 -574.7655 L1449.7781 -629.4624 L1430.1891 -809.7579 L1428.8347 -827.6007 L1426.6023 -848.5" + clip-path="url(#clipPath2)" + id="path9574" /> + <path + fill="none" + d="M1558.8682 -312.1941 L1452.7843 -372.322 L1440.3207 -378.6023 L1427.2346 -384.2264 L1413.2999 -388.1193 L1399.0243 -390.3098 L1343.8071 -393.2482 L1329.5986 -394.5866 L1315.0881 -397.9596 L1301.3245 -402.9852 L1288.3081 -409.2307 L1004.5057 -564" + clip-path="url(#clipPath2)" + id="path9576" /> + <path + fill="none" + d="M1600.1318 -312.8633 L1685.4681 -364" + clip-path="url(#clipPath2)" + id="path9578" /> + <path + fill="none" + d="M1572.8585 -285.5 L1487.5991 -92.9386 L1478.4438 -76.6212 L1468.6229 -61.6985 L1402.7 22.2378 L1394.6174 38.8205 L1389.4469 56.8215 L1368.6556 201.5" + clip-path="url(#clipPath2)" + id="path9580" /> + <path + fill="none" + d="M1600.1318 -298.5135 L1693.5884 -289.5154 L1709.191 -288.7659 L1837.5674 -287.9075" + clip-path="url(#clipPath2)" + id="path9582" /> + <path + fill="none" + d="M1583.7517 -315.5 L1607.5015 -399.2886 L1610.8323 -416.8157 L1610.6674 -434.742 L1607.6373 -452.1016 L1580.8672 -566.9084 L1577.3993 -584.0591 L1575.7869 -601.7263 L1577.35 -619.4314 L1580.9305 -636.3984 L1614.8164 -764.4524 L1619.7084 -780.1863 L1624.0825 -796.5162 L1629.0833 -813.5" + clip-path="url(#clipPath2)" + id="path9584" /> + <path + fill="none" + d="M1583.8019 -285.5 L1652.9181 -44.5011 L1657.9495 -28.9759 L1664.0696 -13.6799 L1706.2524 72.6705 L1712.1622 88.0203 L1755.9924 223.5812 L1761.5636 238.7214 L1828.6061 396" + clip-path="url(#clipPath2)" + id="path9586" /> + <path + fill="none" + d="M1589.1637 -285.5 L1664.5575 -168.474 L1674.3359 -156.5337 L1685.8951 -145.9557 L1699.149 -137.4223 L1755.5259 -110.7229 L1769.1538 -101.467 L1780.8571 -89.4849 L1791.1833 -75.2934 L1809.1395 -47.7027 L1874.6827 57.0747 L1886.2128 72.1643 L1898.6288 86.4205 L1960.8711 152.5" + clip-path="url(#clipPath2)" + id="path9588" /> + <path + fill="none" + d="M1600.1318 -298.5899 L1680.4246 -291.1563 L1695.1542 -290.3194 L1710.582 -290.1999 L1726.1627 -291.7365 L1741.3241 -295.5708 L1755.6965 -301.1228 L1857.4005 -351.0461 L1870.8876 -356.5639 L1885.2015 -360.5438 L1899.5851 -362.6042 L1969.0137 -367.0708 L1983.0198 -368.654 L1997.3274 -370.9745 L2011.1989 -374.9344 L2024.6467 -380.273 L2049.2156 -392.3064 L2183.6387 -466" + clip-path="url(#clipPath2)" + id="path9590" /> + <path + fill="none" + d="M1566.01 -315.4926 L1563.0609 -318.6098 L1506.4263 -383.1129 L1498.4028 -393.4107 L1491.4194 -403.7922 L1366.5425 -604.9753" + clip-path="url(#clipPath2)" + id="path9592" /> + <path + fill="none" + d="M1558.8682 -293.1273 L1428.6742 -246.6027 L1414.7637 -243.1767 L1400.3463 -241.7605 L1385.8116 -243.0361 L1372.291 -245.7882 L1216.0447 -299" + clip-path="url(#clipPath2)" + id="path9594" /> + <path + fill="none" + d="M1589.1405 -285.5 L1662.5685 -171.2502 L1672.3359 -158.9074 L1684.024 -147.4209 L1697.4471 -138.3556 L1711.6204 -131.2945 L1739.769 -118.6583 L1753.9266 -111.6033 L1767.6046 -102.8544 L1779.1833 -91.2369 L1788.0878 -77.7131 L1910.2734 182.3812 L1918.0563 197.3588 L1928.0577 211.2185 L1939.489 224.0622 L2028.2697 311.5" + clip-path="url(#clipPath2)" + id="path9596" /> + <path + fill="none" + d="M1566.3265 -315.5 L1508.5015 -381.3427 L1499.0966 -395.045 L1493.3429 -410.4246 L1491.4697 -427.2559 L1492.8239 -443.7798 L1503.1702 -508.4587 L1509.2715 -542" + clip-path="url(#clipPath2)" + id="path9598" /> + <path + fill="none" + d="M389.0941 -587 L-119.5941 -261" + clip-path="url(#clipPath2)" + id="path9600" /> + <path + fill="none" + d="M128.5263 1464 L-36.5263 1304" + clip-path="url(#clipPath2)" + id="path9602" /> + <path + fill="none" + d="M144.218 1464 L148.782 1150" + clip-path="url(#clipPath2)" + id="path9604" /> + <path + fill="none" + d="M151.1333 1494 L243.8667 1689" + clip-path="url(#clipPath2)" + id="path9606" /> + <path + fill="none" + d="M193.2402 1482.5999 L221.5254 1484.6676" + clip-path="url(#clipPath2)" + id="path9608" /> + <path + fill="none" + d="M131.7539 1494 L55.0677 1587.9316 L42.7085 1601.2833 L29.2008 1613.6403 L14.6157 1624.2771 L-30.3586 1651.8414 L-44.221 1662.6852 L-54.3718 1676.7185 L-60.8013 1692.8674 L-91.1062 1788.2023 L-96.9305 1804.7229 L-104.2114 1820.9052 L-114.1318 1835.8052 L-126.848 1848.3961 L-141.6743 1858.7947 L-188.0667 1884.5151 L-282.5689 1933.7706 L-298.8415 1943.1725 L-314.7511 1953.4357 L-329.8501 1964.6443 L-400.5812 2021.3927 L-414.3242 2033.2428 L-480.0018 2086.5" + clip-path="url(#clipPath2)" + id="path9610" /> + <path + fill="none" + d="M136.8978 1464 L44.4644 1268.7787 L30.7535 1243.0776 L22.1897 1230.6184 L11.9742 1219.5244 L0.3747 1209.786 L-281.4855 1022" + clip-path="url(#clipPath2)" + id="path9612" /> + <path + fill="none" + d="M114.6057 1464 L19.7533 1415.5966 L5.1171 1409.1525 L-10.0416 1403.6228 L-25.3298 1399.9612 L-41.5699 1398.2047 L-57.5674 1398.7446 L-73.0805 1401.1993 L-88.2248 1405.7168 L-102.3748 1411.7216 L-115.7571 1419.2593 L-412.0113 1622.5936 L-426.6128 1631.0859 L-442.5374 1638.3893 L-459.532 1643.1439 L-477.3163 1645.5321 L-495.0157 1645.5688 L-530.7623 1644.0494 L-603.877 1638.6968" + clip-path="url(#clipPath2)" + id="path9614" /> + <path + fill="none" + d="M158.371 1494 L187.1266 1524.0143 L197.6006 1535.7157 L208.6994 1546.4695 L219.3031 1557.908 L242.3572 1579.9839 L254.935 1590.5386 L268.6319 1600.2789 L283.2219 1608.0371 L298.8794 1613.9297 L314.9249 1617.7449 L331.4337 1619.5149 L348.0342 1619.0803 L364.3559 1617.3861 L380.0265 1615.2402 L510.7629 1592.5" + clip-path="url(#clipPath2)" + id="path9616" /> + <path + fill="none" + d="M94.7598 1489.3663 L25.25 1504" + clip-path="url(#clipPath2)" + id="path9618" /> + <path + fill="none" + d="M155.4991 1464 L346.0009 1215.5" + clip-path="url(#clipPath2)" + id="path9620" /> + <path + fill="none" + d="M115.0461 1464 L39.6685 1424.9496 L8.9389 1410.5149 L-6.7761 1404.1628 L-84.1233 1378.9407 L-98.8205 1373.088 L-217.905 1317.8275 L-231.9918 1312.7723 L-246.5594 1309.5073 L-261.5918 1307.9351 L-317.872 1308.4144 L-368.2109 1310.45" + clip-path="url(#clipPath2)" + id="path9622" /> + <path + fill="none" + d="M136.8183 1464 L-68.8183 1034.5" + clip-path="url(#clipPath2)" + id="path9624" /> + <path + fill="none" + d="M139.0195 1494 L21.4805 1848" + clip-path="url(#clipPath2)" + id="path9626" /> + <path + fill="none" + d="M137.2531 1494 L45.4936 1698.0031 L38.4408 1711.5551 L30.6577 1724.6348 L20.0462 1735.8912 L7.5286 1744.2808 L-31.3456 1765.874 L-44.1084 1774.0631 L-55.9533 1783.681 L-66.6299 1794.6614 L-75.9345 1806.4084 L-228.7105 2040.5" + clip-path="url(#clipPath2)" + id="path9628" /> + <path + fill="none" + d="M131.8724 1494 L58.0749 1585.2761 L48.5865 1596.0686 L38.2552 1606.5284 L26.8 1616.1461 L14.9864 1624.6083 L-33.392 1653.4683 L-56.7115 1671.0442 L-165.1028 1764.5" + clip-path="url(#clipPath2)" + id="path9630" /> + <path + fill="none" + d="M145.7432 1494 L170.5621 1707.5676 L173.274 1721.3608 L176.9338 1735.2415 L233.8552 1886.5" + clip-path="url(#clipPath2)" + id="path9632" /> + <path + fill="none" + d="M143.1595 1494 L134.3284 1651.611 L125.1812 1858.2568 L123.4991 1875.0447 L120.446 1891.9172 L28.1562 2225" + clip-path="url(#clipPath2)" + id="path9634" /> + <path + fill="none" + d="M114.9596 1464 L32.9453 1421.6379 L-1.0743 1406.0146 L-18.5145 1399.7577 L-71.2901 1383.0033 L-88.9296 1376.5465 L-106.0097 1368.7263 L-238.8289 1302.1188 L-409.014 1224.1451 L-427.4155 1217.8203 L-446.496 1213.999 L-465.6518 1212.6815 L-571.9102 1214.5187" + clip-path="url(#clipPath2)" + id="path9636" /> + <path + fill="none" + d="M115.0747 1464 L26.8791 1418.2637 L1.6098 1407.1744 L-11.6988 1402.4895 L-25.5129 1399.5509 L-39.428 1397.7089 L-53.2746 1396.8475 L-182.7529 1398.5009" + clip-path="url(#clipPath2)" + id="path9638" /> + <path + fill="none" + d="M158.4073 1494 L233.2235 1571.894 L245.2775 1583.5159 L257.7588 1594.7755 L511.0151 1806" + clip-path="url(#clipPath2)" + id="path9640" /> + <path + fill="none" + d="M143.4499 1494 L128.6067 1898.7615 L129.6534 1916.7771 L133.5966 1934.4972 L144.7699 1967.9235 L264.0977 2247.5" + clip-path="url(#clipPath2)" + id="path9642" /> + <path + fill="none" + d="M157.9143 1494 L239.0956 1581.5155 L299.5429 1639.5773 L309.3708 1650.3474 L318.2313 1662.1793 L325.1808 1675.1222 L341.235 1713.9014 L459.376 2029" + clip-path="url(#clipPath2)" + id="path9644" /> + <path + fill="none" + d="M131.9298 1494 L59.0988 1584.5089 L39.4312 1605.1343 L27.9236 1614.6936 L15.4433 1623.2069 L1.9076 1630.1975 L-12.1443 1635.9338 L-196.2444 1689.7206 L-211.4697 1695.0406 L-226.6018 1701.6837 L-241.4386 1709.1649 L-358.5241 1775.5" + clip-path="url(#clipPath2)" + id="path9646" /> + <path + fill="none" + d="M115.1774 1464 L45.9922 1427.9943 L17.8225 1414.6093 L3.2932 1408.3326 L-12.0923 1402.9446 L-27.8721 1399.5634 L-43.8078 1398.2095 L-59.8553 1398.9216 L-75.4321 1401.8431 L-90.507 1406.4702 L-105.0128 1412.959 L-118.572 1420.2053 L-131.5067 1427.7472 L-143.8491 1435.9572 L-156.4999 1443.1549 L-208.0187 1474.8807 L-222.4372 1482.162 L-238.3481 1487.8889 L-269.2329 1495.8068 L-404.4922 1522.5" + clip-path="url(#clipPath2)" + id="path9648" /> + <path + fill="none" + d="M163.4566 1464 L246.2284 1400.1873 L260.1052 1390.4387 L274.5361 1381.6288 L289.8481 1374.1788 L320.3453 1361.8997 L350.8412 1351.5752 L365.7409 1345.8651 L562.049 1276.5" + clip-path="url(#clipPath2)" + id="path9650" /> + <path + fill="none" + d="M-182.8386 -713.5 L-464.6614 -874" + clip-path="url(#clipPath2)" + id="path9652" /> + <path + fill="none" + d="M-146.8453 -713.5 L66.8453 -1045.5" + clip-path="url(#clipPath2)" + id="path9654" /> + <path + fill="none" + d="M-179.9566 -683.5 L-556.0435 -443" + clip-path="url(#clipPath2)" + id="path9656" /> + <path + fill="none" + d="M-161.2963 -713.5 L-332.2037 -1248" + clip-path="url(#clipPath2)" + id="path9658" /> + <path + fill="none" + d="M-441.3644 -904 L26.8644 -1045.5" + clip-path="url(#clipPath2)" + id="path9660" /> + <path + fill="none" + d="M-493.8796 -874 L-576.6204 -443" + clip-path="url(#clipPath2)" + id="path9662" /> + <path + fill="none" + d="M-484.8235 -904 L-343.1765 -1248" + clip-path="url(#clipPath2)" + id="path9664" /> + <path + fill="none" + d="M1474.5735 2339 L1326.7584 2276.4133 L1308.9584 2269.8667 L1290.6266 2264.2744 L1271.7128 2260.5183 L1196.8739 2249.6672 L1177.7106 2246.0295 L1122.927 2232.1714 L996.0959 2196" + clip-path="url(#clipPath2)" + id="path9666" /> + <path + fill="none" + d="M1503.9481 2339 L1255.6714 1723.624 L1242.3505 1694.6458 L1130.8816 1482.5" + clip-path="url(#clipPath2)" + id="path9668" /> + <path + fill="none" + d="M1474.5431 2339 L1322.069 2274.4961 L1303.8984 2268.2122 L1285.0522 2263.4204 L1265.6094 2261.2283 L1246.234 2261.4336 L1227.1411 2263.3792 L978.9871 2301.2107 L960.8951 2303.2319 L942.4762 2304.3843 L906.9919 2304.9417 L792.7412 2303.2964" + clip-path="url(#clipPath2)" + id="path9670" /> + <path + fill="none" + d="M1518.1578 2369 L1656.8422 2624" + clip-path="url(#clipPath2)" + id="path9672" /> + <path + fill="none" + d="M1529.2338 2369 L1729.9617 2525.5437 L1741.25 2535.3298 L1752.4939 2545.8992 L1763.1542 2557.5071 L1772.4307 2570.2263 L1780.174 2583.7786 L1786.6165 2597.8826 L1797.2206 2626.0237 L1801.7369 2640.0129 L1812.5941 2668.3142 L1818.7988 2682.1631 L1928.7854 2883" + clip-path="url(#clipPath2)" + id="path9674" /> + <path + fill="none" + d="M1511.5278 2369 L1513.1466 2384.8933 L1514.204 2400.4846 L1537.4098 2649.1707 L1540.1097 2665.6206 L1544.6873 2681.5659 L1550.3002 2697.064 L1556.4666 2711.6733 L1818.3805 3263.5" + clip-path="url(#clipPath2)" + id="path9676" /> + <path + fill="none" + d="M1526.5431 2339 L1664.9104 2213.5396 L1676.3075 2204.0525 L1688.2982 2195.3054 L1701.2352 2186.9421 L1714.6727 2179.9111 L1728.8771 2174.0081 L1743.3738 2169.3315 L1772.5908 2162.6487 L2081.9709 2107.0034 L2096.4185 2103.4382 L2111.0107 2098.6389 L2124.6841 2092.2168 L2137.7759 2084.4053 L2149.7017 2074.8916 L2160.5408 2063.8689 L2169.6196 2051.8689 L2177.3831 2038.7415 L2183.9478 2025.1888 L2205.1951 1970.9033 L2211.8096 1957.5084 L2221.3857 1945.6956 L2233.8264 1936.7653 L2247.5352 1930.2933 L2514.4805 1835" + clip-path="url(#clipPath2)" + id="path9678" /> + <path + fill="none" + d="M1529.1042 2369 L1738.5509 2533.45 L1750.5435 2543.9087 L1761.3635 2555.615 L1771.2257 2568.3628 L1779.4089 2582.2319 L1786.0944 2596.5154 L1812.7916 2666.5 L1819.77 2680.5874 L1827.7897 2693.7729 L1837.3392 2705.9377 L1848.2404 2717.001 L1860.5529 2726.521 L1873.8605 2734.6018 L1887.8599 2741.093 L1902.7081 2746.1006 L1917.8242 2749.6072 L1962.748 2758.1482 L1977.8821 2762.0352 L1992.6849 2767.7485 L2007.0975 2774.7456 L2020.618 2783.7029 L2033.1394 2793.7778 L2044.6404 2805.4622 L2055.4875 2817.95 L2228.1003 3055.5" + clip-path="url(#clipPath2)" + id="path9680" /> + <path + fill="none" + d="M1493.432 2369 L1358.0886 2491.5347 L1344.4315 2502.6399 L1329.5942 2512.6628 L1313.6755 2520.7417 L1297.0505 2526.8035 L1279.6298 2530.5449 L1261.9062 2532.02 L1243.9521 2531.1667 L1226.3867 2528.6655 L1192.8405 2520.178 L1047.8075 2476.5" + clip-path="url(#clipPath2)" + id="path9682" /> + <path + fill="none" + d="M1493.3915 2369 L1351.8792 2496.8074 L1336.9489 2508.2498 L1321.3251 2518.696 L823.5881 2799.5" + clip-path="url(#clipPath2)" + id="path9684" /> + <path + fill="none" + d="M1504.6932 2339 L1339.462 1871.9652 L1287.3363 1714.5103 L1281.5391 1698.6304 L1271.3762 1666.3949 L1266.9104 1649.3513 L1263.7081 1632.1747 L1261.8214 1614.8285 L1252.174 1465.3066 L1249.6622 1448.1022 L1245.6331 1430.9169 L1239.6428 1414.2061 L1232.1565 1398.4878 L1224.3367 1383.3807 L1075.5237 1121.5" + clip-path="url(#clipPath2)" + id="path9686" /> + <path + fill="none" + d="M1505.0319 2369 L1410.9681 2653" + clip-path="url(#clipPath2)" + id="path9688" /> + <path + fill="none" + d="M1534.0114 2369 L1910.9886 2604.5" + clip-path="url(#clipPath2)" + id="path9690" /> + <path + fill="none" + d="M1501.9417 2339 L1342.1976 2041.6492 L1333.6259 2028.2693 L1324.1749 2015.4473 L1313.6296 2003.1354 L1097.5363 1794.5" + clip-path="url(#clipPath2)" + id="path9692" /> + <path + fill="none" + d="M1504.9796 2339 L1369.1797 1933.2559 L1364.5956 1917.7723 L1361.1023 1901.3207 L1359.2668 1884.6461 L1358.9624 1867.7823 L1364.918 1804.7361 L1385.1973 1636" + clip-path="url(#clipPath2)" + id="path9694" /> + <path + fill="none" + d="M1607.1934 2343.6565 L1641.5518 2340" + clip-path="url(#clipPath2)" + id="path9696" /> + <path + fill="none" + d="M1509.1334 2339 L1483.3666 1893" + clip-path="url(#clipPath2)" + id="path9698" /> + <path + fill="none" + d="M1535.9918 2369 L1686.6624 2455.9526 L1702.3188 2464.1128 L1718.441 2471.5791 L1735.4189 2477.6355 L1752.9897 2482.0723 L1770.8313 2484.4812 L1805.623 2486.6531 L1924.4827 2487.9512 L1942.2737 2489.0781 L1960.0562 2491.6494 L1977.8062 2496.248 L1994.6891 2502.8237 L2010.9612 2510.2305 L2244.1704 2629.5" + clip-path="url(#clipPath2)" + id="path9700" /> + <path + fill="none" + d="M1421.5883 2369 L1347.9117 2381.5" + clip-path="url(#clipPath2)" + id="path9702" /> + <path + fill="none" + d="M1510.9263 2339 L1526.5001 2086.7854 L1528.6637 2070.645 L1532.7749 2054.6072 L1539.1635 2039.5104 L1582.8965 1955.9016 L1589.814 1941.5165 L1596.3032 1926.5045 L1601.6031 1910.614 L1604.801 1894.145 L1605.9075 1877.3345 L1604.8375 1860.4043 L1601.4618 1844.0298 L1596.4197 1828.249 L1590.9009 1813.1063 L1584.6427 1798.0835 L1579.1389 1783.2101 L1530.6157 1664.5873 L1525.4736 1648.2223 L1521.2292 1631.2045 L1518.8718 1613.6608 L1518.7667 1596.1191 L1520.1587 1578.7006 L1615.3778 1034" + clip-path="url(#clipPath2)" + id="path9704" /> + <path + fill="none" + d="M1520.0275 2339 L1652.9227 2140.2031 L1661.5157 2125.8765 L1669.6093 2110.4673 L1674.8169 2093.8274 L1678.4438 2077.0471 L1692.2361 1993.3143 L1695.9932 1975.8687 L1700.5378 1958.3699 L1707.6724 1941.3625 L1716.8115 1925.3213 L1728.2234 1910.7318 L1740.7257 1897.5914 L1945.353 1707.5" + clip-path="url(#clipPath2)" + id="path9706" /> + <path + fill="none" + d="M1511.1052 2369 L1519.2036 2478.908 L1520.9386 2494.2686 L1532.0088 2648.5208 L1532.4585 2664.9966 L1531.5543 2681.3984 L1528.7942 2697.7139 L1523.9926 2713.2405 L1517.3701 2727.6858 L1508.618 2741.5935 L1498.5919 2754.0928 L1487.2609 2765.2034 L1475.011 2774.9775 L1400.5135 2826.1184 L1387.9414 2835.4861 L1376.0679 2845.9873 L1364.8727 2857.1089 L1355.0602 2869.5366 L1346.4813 2882.7495 L1339.2728 2896.8088 L1333.5167 2911.4705 L1329.4667 2926.6213 L1326.7267 2942.0088 L1325.672 2957.7959 L1326.2606 2973.5076 L1327.9357 2989.0308 L1330.9374 3004.3113 L1404.1639 3275.9639 L1407.5632 3290.6909 L1412.1721 3304.8933 L1423.5769 3348.5" + clip-path="url(#clipPath2)" + id="path9708" /> + <path + fill="none" + d="M1526.5193 2339 L1665.6112 2212.7002 L1689.0184 2194.4897 L1701.7162 2186.1914 L1714.7228 2178.7192 L1869.8474 2109.8154 L1882.8911 2102.8474 L1895.4789 2095.4939 L2044.3569 1999" + clip-path="url(#clipPath2)" + id="path9710" /> + <path + fill="none" + d="M1496.996 2369 L1385.6895 2497.3909 L1376.2972 2507.3276 L1322.2389 2568.2527 L1304.2604 2589.7803 L1125.6952 2852.5" + clip-path="url(#clipPath2)" + id="path9712" /> + <path + fill="none" + d="M1510.8751 2339 L1524.2369 2109.9836 L1527.4911 2077.0388 L1530.6801 2060.7397 L1536.7727 2044.8093 L1587.699 1945.4836 L1600.6235 1915.0745 L1605.15 1898.5553 L1608.6882 1882.624 L1654.8674 1619.5" + clip-path="url(#clipPath2)" + id="path9714" /> + <path + fill="none" + d="M1492 2339 L1231 2121.5" + clip-path="url(#clipPath2)" + id="path9716" /> + <path + fill="none" + d="M1511.2671 2369 L1511.5583 2372.4485 L1512.4863 2390.939 L1532.1252 2653.0818 L1532.3657 2673.238 L1530.3511 2693.1304 L1483.7687 2945.5" + clip-path="url(#clipPath2)" + id="path9718" /> + <path + fill="none" + d="M1519.9977 2339 L1653.2191 2139.1204 L1662.4175 2124.3665 L1670.4188 2108.1663 L1675.7124 2091.2019 L1696.2084 1972.2346 L1700.4777 1954.8425 L1732.6132 1855.5861 L1738.5227 1839.8522 L1743.5808 1823.199 L1800.3926 1658.3755 L1806.9249 1641.4769 L1814.4071 1624.5726 L1823.2809 1608.1635 L1833.8232 1592.6519 L1845.3483 1578.3093 L1857.2207 1564.7336 L1881.5801 1538.2433 L1893.6631 1525.9165 L2062.9272 1345.5" + clip-path="url(#clipPath2)" + id="path9720" /> + <path + fill="none" + d="M1536.2448 2369 L1700.8926 2463.1035 L1716.5065 2470.6301 L1732.8228 2476.7573 L1749.6938 2481.2634 L1766.9144 2483.8633 L1784.0165 2484.6411 L1801.1552 2483.6919 L1817.9308 2480.7009 L1834.475 2476.1997 L1850.3604 2470.1069 L1879.984 2456.0632 L2178.4429 2296.5" + clip-path="url(#clipPath2)" + id="path9722" /> + <path + fill="none" + d="M1522.908 2339 L1805.592 2010.5" + clip-path="url(#clipPath2)" + id="path9724" /> + <path + fill="none" + d="M1526.6202 2339 L1669.4025 2210.1367 L1681.7156 2200.2549 L1694.8494 2191.0376 L1708.5754 2182.6992 L1736.0583 2168.71 L1856.1318 2115.9321 L1869.5493 2109.1848 L1882.8529 2101.687 L1895.3044 2092.6658 L1906.7675 2082.3103 L1916.951 2070.5432 L1925.2897 2057.9207 L1932.2095 2044.2831 L1937.395 2029.8201 L1941.0835 2014.8721 L1942.8657 1999.6416 L1944.0657 1984.2588 L1945.8129 1968.6353 L1949.1118 1952.8204 L1954.0919 1937.6868 L1961.2629 1923.1643 L1970.3491 1909.4205 L1981.2208 1896.7792 L1993.2787 1884.9609 L2081.2905 1807.6135 L2253.324 1643" + clip-path="url(#clipPath2)" + id="path9726" /> + <path + fill="none" + d="M1475.3552 2339 L1375.7992 2295.8955 L1325.3004 2275.6824 L1307.8301 2269.3855 L1289.7203 2263.9866 L1271.4009 2260.2725 L1201.3519 2250.1917 L1183.7898 2246.8469 L1166.7448 2241.9495 L1150.2572 2235.1619 L1134.9137 2226.417 L1120.8173 2216.0547 L1108.2313 2204.0881 L1097.0183 2190.8472 L1086.9922 2176.9243 L1051.8983 2121.3184 L1042.0785 2107.6038 L1031.0328 2094.5808 L1018.9379 2082.5935 L981.7686 2049.2241 L968.8684 2038.6184 L956.4572 2027.4056 L788.5068 1887.5" + clip-path="url(#clipPath2)" + id="path9728" /> + <path + fill="none" + d="M1504.9901 2339 L1366.5494 1924.4966 L1362.4882 1908.5767 L1359.8616 1892.2843 L1359.1125 1875.623 L1360.5317 1859.0786 L1364.2106 1843.1631 L1369.8442 1827.4664 L1377.5298 1813.0808 L1386.8759 1799.7292 L1397.203 1787.4834 L1418.8458 1765.0261 L1472.7761 1711.0153 L1482.7151 1699.1749 L1491.9009 1685.959 L1499.3961 1671.5507 L1505.2434 1656.2231 L1508.5443 1640.9038 L1510.1094 1624.6781 L1509.5914 1608.5144 L1507.2157 1592.4027 L1503.3352 1577.2427 L1414.2556 1323" + clip-path="url(#clipPath2)" + id="path9730" /> + <path + fill="none" + d="M1510.9319 2339 L1526.4713 2088.8757 L1528.2183 2072.9792 L1531.8409 2057.2632 L1537.6543 2042.4523 L1544.4132 2028.5757 L1585.9958 1949.0065 L1592.6586 1935.08 L1598.5482 1920.4163 L1603.2426 1905.4922 L1605.3632 1889.2352 L1606.0835 1873.2714 L1604.3267 1857.3202 L1600.7614 1841.5823 L1590.5676 1811.7375 L1532.8832 1669.7617 L1527.2454 1654.2057 L1522.8604 1638.2473 L1519.7045 1621.5173 L1518.6511 1604.515 L1519.7151 1587.4683 L1522.7896 1570.5966 L1527.3335 1554.9121 L1533.6583 1539.2854 L1561.9587 1481.5208 L1599.4431 1410.3932 L1606.4193 1395.9069 L1755.7795 1107.7368 L1762.8444 1092.5857 L1769.0634 1076.776 L1774.2321 1060.2958 L1777.7761 1043.705 L1779.5951 1026.4392 L1780.0076 1009.2284 L1773.9335 912.5138 L1713.5631 108.591 L1711.499 94.9959 L1708.3801 80.2525 L1703.2778 66.8524 L1697.6584 54.3873 L1673.673 8.0907 L1662.9922 -15.4828 L1658.6643 -27.8628 L1656.0237 -41.0869 L1655.9708 -54.2819 L1658.2432 -67.2466 L1662.6152 -79.6855 L1667.8322 -91.0654 L1722.6837 -190" + clip-path="url(#clipPath2)" + id="path9732" /> + <path + fill="none" + d="M420.7189 353.5 L698.7811 440" + clip-path="url(#clipPath2)" + id="path9734" /> + <path + fill="none" + d="M373.8378 323.5 L418.1622 -173.5" + clip-path="url(#clipPath2)" + id="path9736" /> + <path + fill="none" + d="M371.2291 353.5 L335.7709 772" + clip-path="url(#clipPath2)" + id="path9738" /> + <path + fill="none" + d="M342.7771 353.5 L-26.7771 540" + clip-path="url(#clipPath2)" + id="path9740" /> + <path + fill="none" + d="M331.5783 323.5 L-178.5783 136.5" + clip-path="url(#clipPath2)" + id="path9742" /> + <path + fill="none" + d="M391.3014 323.5 L719.6986 61.5" + clip-path="url(#clipPath2)" + id="path9744" /> + <path + fill="none" + d="M-143.4475 -261 L-156.0525 -683.5" + clip-path="url(#clipPath2)" + id="path9746" /> + <path + fill="none" + d="M-127.6443 -231 L208.6443 97.5" + clip-path="url(#clipPath2)" + id="path9748" /> + <path + fill="none" + d="M-27.0049 2068 L-83.2198 2161.6406 L-90.3236 2174.7258 L-96.6365 2188.5735 L-101.5907 2203.1204 L-105.1204 2217.9927 L-107.1567 2232.9121 L-108.6474 2262.2935 L-107.5751 2476.5" + clip-path="url(#clipPath2)" + id="path9750" /> + <path + fill="none" + d="M-3.3147 2038 L88.2079 1944.5159 L98.9239 1931.85 L108.6347 1917.8579 L115.9706 1901.8237 L121.2358 1885.2582 L124.3123 1867.311 L143.2395 1494" + clip-path="url(#clipPath2)" + id="path9752" /> + <path + fill="none" + d="M-24.6663 2038 L-80.8903 1911.4879 L-85.1263 1899.4636 L-88.5606 1887.0404 L-90.5707 1874.1945 L-91.1801 1861.1097 L-90.1218 1848.1241 L-87.5325 1835.3932 L-83.6841 1822.7667 L-72.56 1799.5031 L-53.9055 1768.1414 L-19.3229 1712.5" + clip-path="url(#clipPath2)" + id="path9754" /> + <path + fill="none" + d="M1596.9543 2095.5 L1515.0457 2339" + clip-path="url(#clipPath2)" + id="path9756" /> + <path + fill="none" + d="M1662.748 2092.5029 L1764.6105 2112.6294 L1782.9017 2115.6848 L1801.8885 2118.3333 L1821.3508 2119.7209 L1840.4524 2120.2183 L1858.9543 2119.3088 L1877.6461 2119.5857 L2183.1145 2112.4343 L2200.6819 2112.6753 L2218.771 2113.5925 L2236.468 2115.9619 L2253.6194 2120.0029 L2270.5688 2125.4739 L2286.7974 2131.6306 L2458.6768 2209" + clip-path="url(#clipPath2)" + id="path9758" /> + <path + fill="none" + d="M1602.3943 2065.5 L1606.7793 1898.7041 L1606.4932 1881.5487 L1605.2306 1864.0957 L1601.9255 1846.7361 L1596.955 1829.9541 L1591.1913 1813.7092 L1533.9847 1674.6245 L1527.9525 1658.2727 L1522.3416 1641.5908 L1503.7571 1574.8905 L1420.4307 1339.3589 L1414.5142 1324.3173 L1414.069 1323" + clip-path="url(#clipPath2)" + id="path9760" /> + <path + fill="none" + d="M1603.0338 2095.5 L1619.5222 2334.7439 L1619.976 2349.6047 L1619.3141 2364.5964 L1616.8829 2379.4578 L1612.6283 2393.7292 L1606.6503 2407.0378 L1599.2849 2419.5703 L1533.5831 2509.7273 L1499.2429 2554.429 L1489.8187 2565.7656 L1418.298 2653" + clip-path="url(#clipPath2)" + id="path9762" /> + <path + fill="none" + d="M1603.1926 2095.5 L1621.6029 2327.0608 L1624.4425 2347.2661 L1628.7183 2366.9514 L1635.0629 2385.7578 L1643.6881 2403.5862 L1654.035 2420.3408 L1665.6207 2435.8164 L1758.1301 2550.2654 L1769.3726 2565.7361 L1779.1656 2582.3586 L1787.2401 2599.9016 L1814.0522 2669.9602 L1822.2802 2687.2004 L1928.8368 2883" + clip-path="url(#clipPath2)" + id="path9764" /> + <path + fill="none" + d="M1588.7958 2095.5 L1440.1951 2264.3108 L1421.9424 2287.5852 L1413.851 2300.9641 L1407.3724 2315.2051 L1402.7751 2330.5364 L1400.0977 2346.2444 L1394.8491 2410.0798 L1391.8948 2426.9863 L1386.8583 2443.4583 L1380.0405 2459.543 L1371.4266 2474.8496 L1352.7933 2504.1155 L1264.7759 2637.0266 L1255.2261 2652.488 L1155.7711 2805.2529 L1146.0284 2821.1672 L1135.6465 2836.3376 L1125.1975 2852.5" + clip-path="url(#clipPath2)" + id="path9766" /> + <path + fill="none" + d="M1585.7421 2095.5 L1275.7579 2381.5" + clip-path="url(#clipPath2)" + id="path9768" /> + <path + fill="none" + d="M1603.1949 2095.5 L1622.4318 2336.9685 L1624.5369 2352.1443 L1628.201 2367.3962 L1632.8905 2381.77 L1638.9683 2395.7341 L1646.1216 2408.7371 L1654.6532 2421.2065 L1664.1459 2432.8657 L1674.5833 2443.5085 L1686.1106 2453.272 L1697.5612 2462.1409 L1912.3665 2604.5" + clip-path="url(#clipPath2)" + id="path9770" /> + <path + fill="none" + d="M1603.7489 2065.5 L1655.7511 1619.5" + clip-path="url(#clipPath2)" + id="path9772" /> + <path + fill="none" + d="M1593.1482 2065.5 L1491.3518 1893" + clip-path="url(#clipPath2)" + id="path9774" /> + <path + fill="none" + d="M1603.0256 2095.5 L1619.4376 2335.5383 L1619.8356 2352.4175 L1618.8832 2369.4175 L1615.4667 2385.9312 L1610.9801 2401.5234 L1549.5068 2578.6951 L1544.7748 2594.0952 L1540.5493 2610.1763 L1538.3051 2626.9604 L1537.8387 2643.7305 L1539.5312 2660.8184 L1543.3848 2677.5637 L1548.2743 2693.5508 L1620.949 2887.3188 L1626.1494 2902.9475 L1630.7904 2919.1487 L1634.1757 2935.949 L1635.9564 2952.8755 L1635.8079 2970.0298 L1633.827 2987.1138 L1630.0143 3003.8672 L1624.4489 3020.2371 L1617.4717 3036.0044 L1609.7772 3051.0796 L1436.2516 3348.5" + clip-path="url(#clipPath2)" + id="path9776" /> + <path + fill="none" + d="M1570.7225 2095.5 L1288.5803 2230.8096 L1274.9982 2236.7656 L1260.8542 2242.2251 L1246.2103 2246.6372 L982.4409 2300.4243 L953.6058 2304.5635 L924.563 2305.3845 L792.7412 2303.3887" + clip-path="url(#clipPath2)" + id="path9778" /> + <path + fill="none" + d="M1603.1537 2095.5 L1620.8918 2326.1306 L1625.1042 2362.6926 L1662.8341 2624" + clip-path="url(#clipPath2)" + id="path9780" /> + <path + fill="none" + d="M1541.252 2084.5603 L1343.7324 2097.7622" + clip-path="url(#clipPath2)" + id="path9782" /> + <path + fill="none" + d="M1640.2059 2065.5 L1780.2941 2010.5" + clip-path="url(#clipPath2)" + id="path9784" /> + <path + fill="none" + d="M1572.6794 2065.5 L1434.8101 1994.9679 L1106.5612 1794.5" + clip-path="url(#clipPath2)" + id="path9786" /> + <path + fill="none" + d="M1603.0039 2095.5 L1619.616 2343.7134 L1619.334 2362.2961 L1616.5592 2380.8618 L1611.7566 2398.3032 L1606.5804 2414.9185 L1549.1158 2579.8984 L1544.0386 2597.4407 L1539.7373 2615.8103 L1536.9749 2634.4294 L1533.7061 2671.905 L1531.5634 2690.6077 L1483.8102 2945.5" + clip-path="url(#clipPath2)" + id="path9788" /> + <path + fill="none" + d="M1662.748 2092.4651 L1780.0096 2115.5613 L1796.447 2117.708 L1813.3804 2119.1421 L1830.0333 2118.6409 L1846.8956 2115.9663 L1862.7615 2110.9902 L1877.9795 2104.4839 L1905.5245 2089.0781 L2044.3778 1999" + clip-path="url(#clipPath2)" + id="path9790" /> + <path + fill="none" + d="M1612.9232 2065.5 L1705.944 1937.7614 L1717.1481 1923.3706 L1729.4146 1909.6766 L1743.266 1897.5363 L1758.9332 1887.454 L1775.6699 1879.6144 L1793.1348 1874.4734 L1811.5116 1871.0072 L1970.6 1855.2622 L1988.6428 1852.0848 L2006.829 1847.8024 L2024.3502 1841.5553 L2040.8623 1833.4706 L2056.6687 1823.6088 L2070.9719 1812.4393 L2084.522 1800.8351 L2252.9895 1643" + clip-path="url(#clipPath2)" + id="path9792" /> + <path + fill="none" + d="M1613.0736 2095.5 L1771.4264 2310" + clip-path="url(#clipPath2)" + id="path9794" /> + <path + fill="none" + d="M1639.7083 2095.5 L1842.3861 2176.1233 L1859.5131 2185.2539 L1876.282 2195.9019 L1891.6011 2208.3118 L1905.634 2221.8408 L1931.1401 2250.0837 L2260.4797 2629.5" + clip-path="url(#clipPath2)" + id="path9796" /> + <path + fill="none" + d="M1647.1119 2095.5 L2161.3879 2266.5" + clip-path="url(#clipPath2)" + id="path9798" /> + <path + fill="none" + d="M1603.1909 2095.5 L1621.691 2328.5208 L1623.5604 2343.7834 L1626.24 2359.3225 L1630.3749 2374.5793 L1636.0944 2389.2988 L1642.9762 2403.4038 L1651.1168 2416.8372 L1660.1671 2429.6006 L1758.1458 2550.04 L1768.1744 2563.7002 L1777.2103 2578.6135 L1784.3627 2594.6853 L1789.4128 2611.853 L1791.9921 2629.5588 L1793.291 2647.2483 L1792.9524 2895.9575 L1795.2501 2933.1309 L1824.1862 3263.5" + clip-path="url(#clipPath2)" + id="path9800" /> + <path + fill="none" + d="M1603.203 2095.5 L1621.8832 2328.4165 L1624.0609 2345.5154 L1627.2642 2362.4485 L1632.0743 2378.8948 L1638.6213 2394.3691 L1646.8019 2409.1277 L1656.0619 2422.8191 L1667.0085 2435.4368 L1679.0601 2446.8408 L1692.3024 2456.9438 L1706.4554 2465.6316 L1721.5145 2472.658 L1737.2064 2478.3113 L1753.2076 2482.2488 L1769.3447 2484.6384 L1785.3156 2486.0251 L1800.7511 2486.7747 L1920.0581 2487.4966 L1935.141 2488.1736 L1950.616 2489.679 L1966.2471 2492.644 L1980.7709 2497.282 L1994.8182 2503.7949 L2008.2539 2511.574 L2020.3892 2520.8616 L2031.2859 2531.5286 L2040.8636 2543.397 L2049.1069 2556.0459 L2055.8984 2570.1116 L2060.9514 2584.1262 L2065.0398 2598.769 L2071.573 2626.8027 L2083.4851 2682.906 L2087.3142 2697.304 L2091.7251 2711.4783 L2232.8469 3055.5" + clip-path="url(#clipPath2)" + id="path9802" /> + <path + fill="none" + d="M1555.4919 2065.5 L1263.2942 1971.259 L1245.3774 1966.6671 L1226.5901 1963.6918 L1207.9307 1962.2289 L1171.8567 1961.0642 L1081.4442 1960.0654 L1062.9497 1958.3174 L1044.2203 1954.9642 L1025.8896 1950.8408 L819.3997 1887.5" + clip-path="url(#clipPath2)" + id="path9804" /> + <path + fill="none" + d="M1608.9635 2065.5 L1809.4962 1633.5309 L1818.6376 1616.1558 L1829.1941 1599.274 L1841.2507 1583.3263 L2063.0132 1345.5" + clip-path="url(#clipPath2)" + id="path9806" /> + <path + fill="none" + d="M1602.3933 2065.5 L1606.7363 1899.8634 L1606.4586 1882.6648 L1605.2378 1865.1937 L1602.3794 1848.0233 L1597.3771 1831.3533 L1585.6033 1799.6447 L1528.9104 1659.5087 L1523.7875 1642.5001 L1520.1628 1624.7736 L1518.6923 1606.78 L1519.3666 1588.6658 L1521.3606 1571.0901 L1615.3744 1034" + clip-path="url(#clipPath2)" + id="path9808" /> + <path + fill="none" + d="M1571.2109 2095.5 L1261.994 2246.146 L1219.6743 2264.4104 L1205.4592 2271.2598 L1191.7346 2278.4478 L1178.4591 2287.1375 L1166.1311 2296.8726 L1154.6273 2306.9568 L1013.2023 2446.5" + clip-path="url(#clipPath2)" + id="path9810" /> + <path + fill="none" + d="M1612.9133 2065.5 L1708.3259 1934.3589 L1718.8427 1921.1146 L1730.2498 1907.9574 L1742.2875 1895.532 L1945.3046 1707.5" + clip-path="url(#clipPath2)" + id="path9812" /> + <path + fill="none" + d="M1572.9703 2065.5 L1444.6885 1999.2152 L1429.064 1990.3815 L1413.6222 1980.5148 L1399.3938 1969.1509 L1386.8495 1955.9407 L1376.3173 1941.3074 L1367.1516 1926.2937 L1215.7188 1635.2328 L1131.2916 1482.5" + clip-path="url(#clipPath2)" + id="path9814" /> + <path + fill="none" + d="M1602.3855 2065.5 L1606.9542 1887.743 L1606 1869.5469 L1602.9114 1851.5056 L1597.8892 1834.3082 L1590.2271 1818.0243 L1580.5396 1803.0505 L1569.3032 1789.5634 L1544.9924 1765.5038 L1403.4001 1636" + clip-path="url(#clipPath2)" + id="path9816" /> + <path + fill="none" + d="M1662.748 2092.4412 L1766.4723 2112.8303 L1800.2173 2118.0352 L1817.9073 2119.0618 L1835.2128 2118.0942 L1852.0842 2114.189 L1868.7249 2108.4495 L1883.6569 2100.4832 L1897.4779 2090.6223 L1909.8057 2078.9834 L1920.2412 2065.7119 L1928.7743 2051.3101 L1935.4041 2035.9259 L1939.7797 2019.7667 L1942.3596 2003.6836 L1945.6359 1971.5028 L1948.5076 1955.5732 L1953.2712 1940.0039 L1959.8096 1925.6807 L1968.1327 1912.3596 L1978.111 1900.3622 L1989.2583 1889.7343 L2001.7524 1880.6145 L2015.2451 1873.4164 L2029.7437 1867.4449 L2044.5986 1863.3865 L2059.4072 1860.6979 L2116.5818 1854.9585 L2130.5618 1854.0964 L2427.3464 1831.3152" + clip-path="url(#clipPath2)" + id="path9818" /> + <path + fill="none" + d="M1602.395 2065.5 L1606.7798 1898.9805 L1606.3993 1880.6311 L1604.8654 1862.1401 L1601.0284 1844.0854 L1594.6597 1826.991 L1585.889 1810.8241 L1574.9169 1796.2695 L1561.8469 1783.6718 L1547.1339 1773.0948 L1530.927 1764.6783 L1514.0385 1758.6746 L1496.0397 1755.1381 L1478.5284 1752.9952 L1377.3137 1744.3647 L1359.9923 1741.0127 L1343.1707 1736.0409 L1327.205 1728.5714 L1312.6506 1718.9408 L1299.2815 1707.3992 L1288.0135 1694.0232 L1278.6018 1679.4884 L1271.3124 1663.254 L1266.2087 1646.291 L1263.3679 1629.0929 L1251.9883 1463.8362 L1249.3915 1446.7079 L1245.1688 1429.4218 L1239.0171 1412.9744 L1231.691 1397.4093 L1158.1884 1265.8065 L1149.532 1251.7174 L1075.525 1121.5" + clip-path="url(#clipPath2)" + id="path9820" /> + <path + fill="none" + d="M1571.1819 2095.5 L1270.4301 2241.884 L1209.0909 2269.5261 L1193.9401 2277.4502 L1179.7173 2286.9822 L1166.2568 2298.0002 L1154.4349 2310.5815 L1144.4984 2324.4265 L1136.3844 2339.6184 L1130.1035 2355.6626 L1125.9659 2372.5798 L1123.5559 2389.3396 L1122.2933 2406.2454 L1120.1442 2455.5945 L1118.5703 2472.6367 L1115.6298 2489.781 L1110.2885 2506.1963 L1102.5222 2521.7383 L1093.292 2536.2493 L1081.7872 2549.6086 L1057.8158 2573.1782 L813.2117 2799.5" + clip-path="url(#clipPath2)" + id="path9822" /> + <path + fill="none" + d="M1570.7183 2095.5 L1288.796 2230.6855 L1274.8589 2236.5764 L1260.1879 2242.116 L1245.0063 2246.1299 L1229.2333 2248.7217 L1213.7101 2249.8647 L1198.0498 2249.1724 L1182.5889 2247.0691 L1153.3807 2240.5171 L996.3959 2196" + clip-path="url(#clipPath2)" + id="path9824" /> + </g> + </g> +</svg> diff --git a/doc/user/tools.in b/doc/user/tools.in deleted file mode 100644 index c049b8e..0000000 --- a/doc/user/tools.in +++ /dev/null @@ -1,38 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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 modules that are -available "out of the box" in this version of SCons. - -</para> - -<variablelist> - -&tools-gen; - -</variablelist> diff --git a/doc/user/tools.xml b/doc/user/tools.xml index c049b8e..351096d 100644 --- a/doc/user/tools.xml +++ b/doc/user/tools.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<appendix id="app-tools" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Tools</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -31,8 +52,6 @@ available "out of the box" in this version of SCons. </para> -<variablelist> - -&tools-gen; +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../generated/tools.gen"/> -</variablelist> +</appendix> diff --git a/doc/user/troubleshoot.in b/doc/user/troubleshoot.in deleted file mode 100644 index 7259ed3..0000000 --- a/doc/user/troubleshoot.in +++ /dev/null @@ -1,914 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - The experience of configuring any - software build tool to build a large code base - usually, at some point, - involves trying to figure out why - the tool is behaving a certain way, - and how to get it to behave the way you want. - &SCons; is no different. - This appendix contains a number of - different ways in which you can - get some additional insight into &SCons;' behavior. - - </para> - - <para> - - Note that we're always interested in trying to - improve how you can troubleshoot configuration problems. - If you run into a problem that has - you scratching your head, - and which there just doesn't seem to be a good way to debug, - odds are pretty good that someone else will run into - the same problem, too. - If so, please let the SCons development team know - (preferably by filing a bug report - or feature request at our project pages at tigris.org) - so that we can use your feedback - to try to come up with a better way to help you, - and others, get the necessary insight into &SCons; behavior - to help identify and fix configuration issues. - - </para> - - <section> - <title>Why is That Target Being Rebuilt? the &debug-explain; Option</title> - - <para> - - Let's look at a simple example of - a misconfigured build - that causes a target to be rebuilt - every time &SCons; is run: - - </para> - - <scons_example name="explain1"> - <file name="SConstruct" printme="1"> - # Intentionally misspell the output file name in the - # command used to create the file: - Command('file.out', 'file.in', 'cp $SOURCE file.oout') - </file> - <file name="file.in"> - file.in - </file> - </scons_example> - - <para> - - (Note to Windows users: The POSIX &cp; command - copies the first file named on the command line - to the second file. - In our example, it copies the &file_in; file - to the &file_out; file.) - - </para> - - <para> - - Now if we run &SCons; multiple times on this example, - we see that it re-runs the &cp; - command every time: - - </para> - - <scons_output example="explain1" os="posix"> - <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> - - In this example, - the underlying cause is obvious: - we've intentionally misspelled the output file name - in the &cp; command, - so the command doesn't actually - build the &file_out; file that we've told &SCons; to expect. - But if the problem weren't obvious, - it would be helpful - to specify the &debug-explain; option - on the command line - to have &SCons; tell us very specifically - why it's decided to rebuild the target: - - </para> - - <scons_output example="explain1" os="posix"> - <scons_output_command>scons -Q --debug=explain</scons_output_command> - </scons_output> - - <para> - - If this had been a more complicated example - involving a lot of build output, - having &SCons; tell us that - it's trying to rebuild the target file - because it doesn't exist - would be an important clue - that something was wrong with - the command that we invoked to build it. - - </para> - - <para> - - The &debug-explain; option also comes in handy - to help figure out what input file changed. - Given a simple configuration that builds - a program from three source files, - changing one of the source files - and rebuilding with the &debug-explain; - option shows very specifically - why &SCons; rebuilds the files that it does: - - </para> - - <scons_example name="explain2"> - <file name="SConstruct"> - Program('prog', ['file1.c', 'file2.c', 'file3.c']) - </file> - <file name="file1.c"> - file1.c - </file> - <file name="file2.c"> - file2.c - </file> - <file name="file3.c"> - file3.c - </file> - </scons_example> - - <scons_output example="explain2" os="posix"> - <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> - - This becomes even more helpful - in identifying when a file is rebuilt - due to a change in an implicit dependency, - such as an incuded <filename>.h</filename> file. - If the <filename>file1.c</filename> - and <filename>file3.c</filename> files - in our example - both included a &hello_h; file, - then changing that included file - and re-running &SCons; with the &debug-explain; option - will pinpoint that it's the change to the included file - that starts the chain of rebuilds: - - </para> - - <scons_example name="explain3"> - <file name="SConstruct"> - Program('prog', ['file1.c', 'file2.c', 'file3.c'], CPPPATH='.') - </file> - <file name="file1.c"> - #include <hello.h> - file1.c - </file> - <file name="file2.c"> - file2.c - </file> - <file name="file3.c"> - #include <hello.h> - file3.c - </file> - <file name="hello.h"> - #define string "world" - </file> - </scons_example> - - <scons_output example="explain3" os="posix"> - <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> - - <para> - - (Note that the &debug-explain; option will only tell you - why &SCons; decided to rebuild necessary targets. - It does not tell you what files it examined - when deciding <emphasis>not</emphasis> - to rebuild a target file, - which is often a more valuable question to answer.) - - </para> - - </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 set. - 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" printme="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. - Also note that we've massaged the example output above - to make the memory address of all objects a constant 0x700000. - In reality, you would see a different hexadecimal - number for each object. - - </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" printme="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> - - <section> - - <title>What Dependencies Does &SCons; Know About? the &tree; Option</title> - - <para> - - Sometimes the best way to try to figure out what - &SCons; is doing is simply to take a look at the - dependency graph that it constructs - based on your &SConscript; files. - The <literal>--tree</literal> option - will display all or part of the - &SCons; dependency graph in an - "ASCII art" graphical format - that shows the dependency hierarchy. - - </para> - - <para> - - For example, given the following input &SConstruct; file: - - </para> - - <scons_example name="tree1"> - <file name="SConstruct" printme="1"> - env = Environment(CPPPATH = ['.']) - env.Program('prog', ['f1.c', 'f2.c', 'f3.c']) - </file> - <file name="f1.c"> - #include "inc.h" - </file> - <file name="f2.c"> - #include "inc.h" - </file> - <file name="f3.c"> - #include "inc.h" - </file> - <file name="inc.h"> - inc.h - </file> - </scons_example> - - <para> - - Running &SCons; with the <literal>--tree=all</literal> - option yields: - - </para> - - <scons_output example="tree1"> - <scons_output_command>scons -Q --tree=all</scons_output_command> - </scons_output> - - <para> - - The tree will also be printed when the - <literal>-n</literal> (no execute) option is used, - which allows you to examine the dependency graph - for a configuration without actually - rebuilding anything in the tree. - - </para> - - <para> - - The <literal>--tree</literal> option only prints - the dependency graph for the specified targets - (or the default target(s) if none are specified on the command line). - So if you specify a target like <filename>f2.o</filename> - on the command line, - the <literal>--tree</literal> option will only - print the dependency graph for that file: - - </para> - - <scons_output example="tree1"> - <scons_output_command>scons -Q --tree=all f2.o</scons_output_command> - </scons_output> - - <para> - - This is, of course, useful for - restricting the output from a very large - build configuration to just a - portion in which you're interested. - Multiple targets are fine, - in which case a tree will be printed - for each specified target: - - </para> - - <scons_output example="tree1"> - <scons_output_command>scons -Q --tree=all f1.o f3.o</scons_output_command> - </scons_output> - - <para> - - The <literal>status</literal> argument may be used - to tell &SCons; to print status information about - each file in the dependency graph: - - </para> - - <scons_output example="tree1"> - <scons_output_command>scons -Q --tree=status</scons_output_command> - </scons_output> - - <para> - - Note that <literal>--tree=all,status</literal> is equivalent; - the <literal>all</literal> - is assumed if only <literal>status</literal> is present. - As an alternative to <literal>all</literal>, - you can specify <literal>--tree=derived</literal> - to have &SCons; only print derived targets - in the tree output, - skipping source files - (like <filename>.c</filename> and <filename>.h</filename> files): - - </para> - - <scons_output example="tree1"> - <scons_output_command>scons -Q --tree=derived</scons_output_command> - </scons_output> - - <para> - - You can use the <literal>status</literal> - modifier with <literal>derived</literal> as well: - - </para> - - <scons_output example="tree1"> - <scons_output_command>scons -Q --tree=derived,status</scons_output_command> - </scons_output> - - <para> - - Note that the order of the <literal>--tree=</literal> - arguments doesn't matter; - <literal>--tree=status,derived</literal> is - completely equivalent. - - </para> - - <para> - - The default behavior of the <literal>--tree</literal> option - is to repeat all of the dependencies each time the library dependency - (or any other dependency file) is encountered in the tree. - If certain target files share other target files, - such as two programs that use the same library: - - </para> - - <scons_example name="tree2"> - <file name="SConstruct" printme="1"> - env = Environment(CPPPATH = ['.'], - LIBS = ['foo'], - LIBPATH = ['.']) - env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) - env.Program('prog1.c') - env.Program('prog2.c') - </file> - <file name="prog1.c"> - #include "inc.h" - </file> - <file name="prog2.c"> - #include "inc.h" - </file> - <file name="f1.c"> - #include "inc.h" - </file> - <file name="f2.c"> - #include "inc.h" - </file> - <file name="f3.c"> - #include "inc.h" - </file> - <file name="inc.h"> - inc.h - </file> - </scons_example> - - <para> - - Then there can be a <emphasis>lot</emphasis> of repetition in the - <literal>--tree=</literal> output: - - </para> - - <scons_output example="tree2"> - <scons_output_command>scons -Q --tree=all</scons_output_command> - </scons_output> - - <para> - - In a large configuration with many internal libraries - and include files, - this can very quickly lead to huge output trees. - To help make this more manageable, - a <literal>prune</literal> modifier may - be added to the option list, - in which case &SCons; - will print the name of a target that has - already been visited during the tree-printing - in <literal>[square brackets]</literal> - as an indication that the dependencies - of the target file may be found - by looking farther up the tree: - - </para> - - <scons_output example="tree2"> - <scons_output_command>scons -Q --tree=prune</scons_output_command> - </scons_output> - - <para> - - Like the <literal>status</literal> keyword, - the <literal>prune</literal> argument by itself - is equivalent to <literal>--tree=all,prune</literal>. - - </para> - - </section> - - <section> - - <title>How is &SCons; Constructing the Command Lines It Executes? the &debug-presub; Option</title> - - <para> - - Sometimes it's useful to look at the - pre-substitution string - that &SCons; uses to generate - the command lines it executes. - This can be done with the &debug-presub; option: - - </para> - - <scons_example name="presub"> - <file name="SConstruct"> - env = Environment(CPPPATH = ['.']) - env.Program('prog', 'prog.c') - </file> - <file name="prog.c"> - prog.c - </file> - </scons_example> - - <!-- - - Have to capture output here, otherwise the - -debug=presub output - shows the Python functions from the sconsdoc.py execution wrapper - used to generate this manual, not the underlying command-line strings. - - <scons_output example="presub"> - <scons_output_command>scons -Q - -debug=presub</scons_output_command> - </scons_output> - - --> - - <screen> - % <userinput>scons -Q --debug=presub</userinput> - Building prog.o with action: - $CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCOMCOM $SOURCES - cc -o prog.o -c -I. prog.c - Building prog with action: - $SMART_LINKCOM - cc -o prog prog.o - </screen> - - </section> - - <section> - - <title>Where is &SCons; Searching for Libraries? the &debug-findlibs; Option</title> - - <para> - - To get some insight into what library names - &SCons; is searching for, - and in which directories it is searching, - Use the <literal>--debug=findlibs</literal> option. - Given the following input &SConstruct; file: - - </para> - - <scons_example name="findlibs"> - <file name="SConstruct" printme="1"> - env = Environment(LIBPATH = ['libs1', 'libs2']) - env.Program('prog.c', LIBS=['foo', 'bar']) - </file> - <file name="prog.c"> - prog.c - </file> - <file name="libs1/libfoo.a"> - libs1/libfoo.a - </file> - <file name="libs2/libbar.a"> - libs2/libbar.a - </file> - </scons_example> - - <para> - - And the libraries <filename>libfoo.a</filename> - and <filename>libbar.a</filename> - in <filename>libs1</filename> and <filename>libs2</filename>, - respectively, - use of the <literal>--debug=findlibs</literal> option yields: - - </para> - - <scons_output example="findlibs"> - <scons_output_command>scons -Q --debug=findlibs</scons_output_command> - </scons_output> - - </section> - - <!-- - - <section> - - <title>What Implicit Dependencies Did the &SCons; Scanner find? the &debug-includes; Option</title> - - <para> - - XXX explain the - - debug=includes option - - </para> - - <scons_example name="includes"> - <file name="SConstruct" printme="1"> - env = Environment(CPPPATH = ['inc1', 'inc2']) - env.Program('prog.c') - </file> - <file name="prog.c"> - #include "file1.h" - #include "file2.h" - prog.c - </file> - <file name="inc1/file1.h"> - inc1/file1.h - </file> - <file name="inc2/file2.h"> - inc2/file2.h - </file> - </scons_example> - - <scons_output example="includes"> - <scons_output_command>scons -Q - - debug=includes prog</scons_output_command> - </scons_output> - - </section> - - --> - - <section> - - <title>Where is &SCons; Blowing Up? the &debug-stacktrace; Option</title> - - <para> - - In general, &SCons; tries to keep its error - messages short and informative. - That means we usually try to avoid showing - the stack traces that are familiar - to experienced Python programmers, - since they usually contain much more - information than is useful to most people. - - </para> - - <para> - - For example, the following &SConstruct; file: - - </para> - - <scons_example name="stacktrace"> - <file name="SConstruct" printme="1"> - Program('prog.c') - </file> - </scons_example> - - <para> - - Generates the following error if the - <filename>prog.c</filename> file - does not exist: - - </para> - - <scons_output example="stacktrace"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - In this case, - the error is pretty obvious. - But if it weren't, - and you wanted to try to get more information - about the error, - the &debug-stacktrace; option - would show you exactly where in the &SCons; source code - the problem occurs: - - </para> - - <scons_output example="stacktrace"> - <scons_output_command>scons -Q --debug=stacktrace</scons_output_command> - </scons_output> - - <para> - - Of course, if you do need to dive into the &SCons; source code, - we'd like to know if, or how, - the error messages or troubleshooting options - could have been improved to avoid that. - Not everyone has the necessary time or - Python skill to dive into the source code, - and we'd like to improve &SCons; - for those people as well... - - </para> - - </section> - - <section> - - <title>How is &SCons; Making Its Decisions? the &taskmastertrace; Option</title> - - <para> - - The internal &SCons; subsystem that handles walking - the dependency graph - and controls the decision-making about what to rebuild - is the <literal>Taskmaster</literal>. - &SCons; supports a <literal>--taskmastertrace</literal> - option that tells the Taskmaster to print - information about the children (dependencies) - of the various Nodes on its walk down the graph, - which specific dependent Nodes are being evaluated, - and in what order. - - </para> - - <para> - - The <literal>--taskmastertrace</literal> option - takes as an argument the name of a file in - which to put the trace output, - with <filename>-</filename> (a single hyphen) - indicating that the trace messages - should be printed to the standard output: - - </para> - - <scons_example name="taskmastertrace"> - <file name="SConstruct" printme="1"> - env = Environment(CPPPATH = ['.']) - env.Program('prog.c') - </file> - <file name="prog.c"> - #include "inc.h" - prog.c - </file> - <file name="inc.h"> - #define STRING "one" - </file> - </scons_example> - - <scons_output example="taskmastertrace" os="posix"> - <scons_output_command>scons -Q --taskmastertrace=- prog</scons_output_command> - </scons_output> - - <para> - - The <literal>--taskmastertrace</literal> option - doesn't provide information about the actual - calculations involved in deciding if a file is up-to-date, - but it does show all of the dependencies - it knows about for each Node, - and the order in which those dependencies are evaluated. - This can be useful as an alternate way to determine - whether or not your &SCons; configuration, - or the implicit dependency scan, - has actually identified all the correct dependencies - you want it to. - - </para> - - </section> - - <section> - - <title>Watch &SCons; prepare targets for building: the &debug-prepare; Option</title> - - <para> - - Sometimes SCons doesn't build the target you want - and it's difficult to figure out why. You can use - the <literal>--debug=prepare</literal> option - to see all the targets &SCons; is considering, whether - they are already up-to-date or not. The message is - printed before &SCons; decides whether to build the target. - </para> - - </section> - - <section> - - <title>Why is a file disappearing? the --debug=duplicate Option</title> - - <para> - - When using the &Duplicate; option to create variant dirs, - sometimes you may find files not getting copied to where you - expect (or not at all), or files mysteriously disappearing. These - are usually because of a misconfiguration of some kind in the - SConstruct/SConscript, but they can be tricky to debug. The - --debug=duplicate option shows each time a variant file is - unlinked and relinked from its source (or copied, depending on - settings), and also shows a message for removing "stale" - variant-dir files that no longer have a corresponding source file. - It also prints a line for each target that's removed just before - building, since that can also be mistaken for the same thing. - - </para> - - </section> - - <!-- - - - <section> - - <title>Where Are My Build Bottlenecks? the &profile; Option</title> - - <para> - - XXX explain the - - profile= option - - </para> - - </section> - - --> - - <!-- - - <section> - <title>Troubleshooting Shared Caching: the &cache-debug; Option</title> - - <para> - - XXX describe the - - cache-debug option - XXX maybe point to the caching.in chapter? - - </para> - - </section> - - --> diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml index 51de8f2..183f9c4 100644 --- a/doc/user/troubleshoot.xml +++ b/doc/user/troubleshoot.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-troubleshooting" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Troubleshooting</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -69,11 +90,16 @@ </para> - <programlisting> - # Intentionally misspell the output file name in the - # command used to create the file: - Command('file.out', 'file.in', 'cp $SOURCE file.oout') - </programlisting> + <scons_example name="troubleshoot_explain1"> + <file name="SConstruct" printme="1"> +# Intentionally misspell the output file name in the +# command used to create the file: +Command('file.out', 'file.in', 'cp $SOURCE file.oout') + </file> + <file name="file.in"> +file.in + </file> + </scons_example> <para> @@ -93,14 +119,11 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cp file.in file.oout - % <userinput>scons -Q</userinput> - cp file.in file.oout - % <userinput>scons -Q</userinput> - cp file.in file.oout - </screen> + <scons_output example="troubleshoot_explain1" os="posix" suffix="1"> + <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> @@ -119,11 +142,9 @@ </para> - <screen> - % <userinput>scons -Q --debug=explain</userinput> - scons: building `file.out' because it doesn't exist - cp file.in file.oout - </screen> + <scons_output example="troubleshoot_explain1" os="posix" suffix="2"> + <scons_output_command>scons -Q --debug=explain</scons_output_command> + </scons_output> <para> @@ -139,6 +160,16 @@ </para> <para> + Note that you can also use --warn=target-not-built which checks + whether or not expected targets exist after a build rule is + executed. + </para> + + <scons_output example="troubleshoot_explain1" os="posix" suffix="3"> + <scons_output_command>scons -Q --warn=target-not-built</scons_output_command> + </scons_output> + + <para> The &debug-explain; option also comes in handy to help figure out what input file changed. @@ -151,22 +182,26 @@ </para> - + <scons_example name="troubleshoot_explain2"> + <file name="SConstruct"> +Program('prog', ['file1.c', 'file2.c', 'file3.c']) + </file> + <file name="file1.c"> +file1.c + </file> + <file name="file2.c"> +file2.c + </file> + <file name="file3.c"> +file3.c + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - cc -o file1.o -c file1.c - cc -o file2.o -c file2.c - cc -o file3.o -c file3.c - cc -o prog file1.o file2.o file3.o - % <userinput>edit file2.c</userinput> - [CHANGE THE CONTENTS OF file2.c] - % <userinput>scons -Q --debug=explain</userinput> - scons: rebuilding `file2.o' because `file2.c' changed - cc -o file2.o -c file2.c - scons: rebuilding `prog' because `file2.o' changed - cc -o prog file1.o file2.o file3.o - </screen> + <scons_output example="troubleshoot_explain2" os="posix" suffix="1"> + <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> @@ -185,26 +220,31 @@ </para> - + <scons_example name="troubleshoot_explain3"> + <file name="SConstruct"> +Program('prog', ['file1.c', 'file2.c', 'file3.c'], CPPPATH='.') + </file> + <file name="file1.c"> +#include <hello.h> +file1.c + </file> + <file name="file2.c"> +file2.c + </file> + <file name="file3.c"> +#include <hello.h> +file3.c + </file> + <file name="hello.h"> +#define string "world" + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - cc -o file1.o -c -I. file1.c - cc -o file2.o -c -I. file2.c - cc -o file3.o -c -I. file3.c - cc -o prog file1.o file2.o file3.o - % <userinput>edit hello.h</userinput> - [CHANGE THE CONTENTS OF hello.h] - % <userinput>scons -Q --debug=explain</userinput> - scons: rebuilding `file1.o' because `hello.h' changed - cc -o file1.o -c -I. file1.c - scons: rebuilding `file3.o' because `hello.h' changed - cc -o file3.o -c -I. file3.c - scons: rebuilding `prog' because: - `file1.o' changed - `file3.o' changed - cc -o prog file1.o file2.o file3.o - </screen> + <scons_output example="troubleshoot_explain3" os="posix" suffix="1"> + <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> <para> @@ -246,10 +286,12 @@ </para> - <programlisting> - env = Environment() - print env.Dump() - </programlisting> + <scons_example name="troubleshoot_Dump"> + <file name="SConstruct" printme="1"> +env = Environment() +print env.Dump() + </file> + </scons_example> <para> @@ -258,79 +300,9 @@ </para> - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - { 'BUILDERS': {'_InternalInstall': <function InstallBuilderWrapper at 0x700000>, '_InternalInstallAs': <function InstallAsBuilderWrapper at 0x700000>}, - 'CONFIGUREDIR': '#/.sconf_temp', - 'CONFIGURELOG': '#/config.log', - 'CPPSUFFIXES': [ '.c', - '.C', - '.cxx', - '.cpp', - '.c++', - '.cc', - '.h', - '.H', - '.hxx', - '.hpp', - '.hh', - '.F', - '.fpp', - '.FPP', - '.m', - '.mm', - '.S', - '.spp', - '.SPP', - '.sx'], - 'DSUFFIXES': ['.d'], - 'Dir': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'Dirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'ENV': { 'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'}, - 'ESCAPE': <function escape at 0x700000>, - 'File': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'HOST_ARCH': None, - 'HOST_OS': None, - 'IDLSUFFIXES': ['.idl', '.IDL'], - 'INSTALL': <function copyFunc at 0x700000>, - 'LIBPREFIX': 'lib', - 'LIBPREFIXES': ['$LIBPREFIX'], - 'LIBSUFFIX': '.a', - 'LIBSUFFIXES': ['$LIBSUFFIX', '$SHLIBSUFFIX'], - 'MAXLINELENGTH': 128072, - 'OBJPREFIX': '', - 'OBJSUFFIX': '.o', - 'PLATFORM': 'posix', - 'PROGPREFIX': '', - 'PROGSUFFIX': '', - 'PSPAWN': <function piped_env_spawn at 0x700000>, - 'RDirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'SCANNERS': [], - 'SHELL': 'sh', - 'SHLIBPREFIX': '$LIBPREFIX', - 'SHLIBSUFFIX': '.so', - 'SHOBJPREFIX': '$OBJPREFIX', - 'SHOBJSUFFIX': '$OBJSUFFIX', - 'SPAWN': <function spawnvpe_spawn at 0x700000>, - 'TARGET_ARCH': None, - 'TARGET_OS': None, - 'TEMPFILE': <class 'SCons.Platform.TempFileMunge'>, - 'TEMPFILEPREFIX': '@', - 'TOOLS': ['install', 'install'], - '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}', - '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)', - '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)', - '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}', - '__RPATH': '$_RPATH', - '_concat': <function _concat at 0x700000>, - '_defines': <function _defines at 0x700000>, - '_stripixes': <function _stripixes at 0x700000>} - scons: done reading SConscript files. - scons: Building targets ... - scons: `.' is up to date. - scons: done building targets. - </screen> + <scons_output example="troubleshoot_Dump" os="posix" tools="gcc" suffix="1"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -339,112 +311,9 @@ </para> - <screen> - C:\><userinput>scons</userinput> - scons: Reading SConscript files ... - { 'BUILDERS': {'_InternalInstall': <function InstallBuilderWrapper at 0x700000>, 'Object': <SCons.Builder.CompositeBuilder object at 0x700000>, 'PCH': <SCons.Builder.BuilderBase object at 0x700000>, 'RES': <SCons.Builder.BuilderBase object at 0x700000>, 'SharedObject': <SCons.Builder.CompositeBuilder object at 0x700000>, 'StaticObject': <SCons.Builder.CompositeBuilder object at 0x700000>, '_InternalInstallAs': <function InstallAsBuilderWrapper at 0x700000>}, - 'CC': 'cl', - 'CCCOM': <SCons.Action.FunctionAction object at 0x700000>, - 'CCFLAGS': ['/nologo'], - 'CCPCHFLAGS': ['${(PCH and "/Yu%s \\"/Fp%s\\""%(PCHSTOP or "",File(PCH))) or ""}'], - 'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'], - 'CFILESUFFIX': '.c', - 'CFLAGS': [], - 'CONFIGUREDIR': '#/.sconf_temp', - 'CONFIGURELOG': '#/config.log', - 'CPPDEFPREFIX': '/D', - 'CPPDEFSUFFIX': '', - 'CPPSUFFIXES': [ '.c', - '.C', - '.cxx', - '.cpp', - '.c++', - '.cc', - '.h', - '.H', - '.hxx', - '.hpp', - '.hh', - '.F', - '.fpp', - '.FPP', - '.m', - '.mm', - '.S', - '.spp', - '.SPP', - '.sx'], - 'CXX': '$CC', - 'CXXCOM': '${TEMPFILE("$CXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $CXXFLAGS $CCFLAGS $_CCCOMCOM")}', - 'CXXFILESUFFIX': '.cc', - 'CXXFLAGS': ['$(', '/TP', '$)'], - 'DSUFFIXES': ['.d'], - 'Dir': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'Dirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'ENV': { 'PATH': 'C:\\WINDOWS\\System32', - 'PATHEXT': '.COM;.EXE;.BAT;.CMD', - 'SystemRoot': 'C:\\WINDOWS'}, - 'ESCAPE': <function escape at 0x700000>, - 'File': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'HOST_ARCH': '', - 'HOST_OS': 'win32', - 'IDLSUFFIXES': ['.idl', '.IDL'], - 'INCPREFIX': '/I', - 'INCSUFFIX': '', - 'INSTALL': <function copyFunc at 0x700000>, - 'LIBPREFIX': '', - 'LIBPREFIXES': ['$LIBPREFIX'], - 'LIBSUFFIX': '.lib', - 'LIBSUFFIXES': ['$LIBSUFFIX'], - 'MAXLINELENGTH': 2048, - 'MSVC_SETUP_RUN': True, - 'OBJPREFIX': '', - 'OBJSUFFIX': '.obj', - 'PCHCOM': '$CXX /Fo${TARGETS[1]} $CXXFLAGS $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Yc$PCHSTOP /Fp${TARGETS[0]} $CCPDBFLAGS $PCHPDBFLAGS', - 'PCHPDBFLAGS': ['${(PDB and "/Yd") or ""}'], - 'PLATFORM': 'win32', - 'PROGPREFIX': '', - 'PROGSUFFIX': '.exe', - 'PSPAWN': <function piped_spawn at 0x700000>, - 'RC': 'rc', - 'RCCOM': <SCons.Action.FunctionAction object at 0x700000>, - 'RCFLAGS': [], - 'RCSUFFIXES': ['.rc', '.rc2'], - 'RDirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'SCANNERS': [], - 'SHCC': '$CC', - 'SHCCCOM': <SCons.Action.FunctionAction object at 0x700000>, - 'SHCCFLAGS': ['$CCFLAGS'], - 'SHCFLAGS': ['$CFLAGS'], - 'SHCXX': '$CXX', - 'SHCXXCOM': '${TEMPFILE("$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM")}', - 'SHCXXFLAGS': ['$CXXFLAGS'], - 'SHELL': None, - 'SHLIBPREFIX': '', - 'SHLIBSUFFIX': '.dll', - 'SHOBJPREFIX': '$OBJPREFIX', - 'SHOBJSUFFIX': '$OBJSUFFIX', - 'SPAWN': <function spawn at 0x700000>, - 'STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME': 1, - 'TARGET_ARCH': '', - 'TARGET_OS': 'win32', - 'TEMPFILE': <class 'SCons.Platform.TempFileMunge'>, - 'TEMPFILEPREFIX': '@', - 'TOOLS': ['msvc', 'install', 'install'], - '_CCCOMCOM': '$CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $CCPCHFLAGS $CCPDBFLAGS', - '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}', - '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)', - '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)', - '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}', - '_MSVC_OUTPUT_FLAG': <function msvc_output_flag at 0x700000>, - '_concat': <function _concat at 0x700000>, - '_defines': <function _defines at 0x700000>, - '_stripixes': <function _stripixes at 0x700000>} - scons: done reading SConscript files. - scons: Building targets ... - scons: `.' is up to date. - scons: done building targets. - </screen> + <scons_output example="troubleshoot_Dump" os="win32" tools="msvc" suffix="2"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -477,10 +346,12 @@ </para> - <programlisting> - env = Environment() - print env.Dump('ENV') - </programlisting> + <scons_example name="troubleshoot_Dump_ENV"> + <file name="SConstruct" printme="1"> +env = Environment() +print env.Dump('ENV') + </file> + </scons_example> <para> @@ -488,15 +359,9 @@ </para> - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - { 'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'} - scons: done reading SConscript files. - scons: Building targets ... - scons: `.' is up to date. - scons: done building targets. - </screen> + <scons_output example="troubleshoot_Dump_ENV" os="posix" suffix="1"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -504,17 +369,9 @@ </para> - <screen> - C:\><userinput>scons</userinput> - scons: Reading SConscript files ... - { 'PATH': 'C:\\WINDOWS\\System32', - 'PATHEXT': '.COM;.EXE;.BAT;.CMD', - 'SystemRoot': 'C:\\WINDOWS'} - scons: done reading SConscript files. - scons: Building targets ... - scons: `.' is up to date. - scons: done building targets. - </screen> + <scons_output example="troubleshoot_Dump_ENV" os="win32" suffix="2"> + <scons_output_command>scons</scons_output_command> + </scons_output> </section> @@ -542,10 +399,24 @@ </para> - <programlisting> - env = Environment(CPPPATH = ['.']) - env.Program('prog', ['f1.c', 'f2.c', 'f3.c']) - </programlisting> + <scons_example name="troubleshoot_tree1"> + <file name="SConstruct" printme="1"> +env = Environment(CPPPATH = ['.']) +env.Program('prog', ['f1.c', 'f2.c', 'f3.c']) + </file> + <file name="f1.c"> +#include "inc.h" + </file> + <file name="f2.c"> +#include "inc.h" + </file> + <file name="f3.c"> +#include "inc.h" + </file> + <file name="inc.h"> +inc.h + </file> + </scons_example> <para> @@ -554,38 +425,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=all</userinput> - cc -o f1.o -c -I. f1.c - cc -o f2.o -c -I. f2.c - cc -o f3.o -c -I. f3.c - cc -o prog f1.o f2.o f3.o - +-. - +-SConstruct - +-f1.c - +-f1.o - | +-f1.c - | +-inc.h - +-f2.c - +-f2.o - | +-f2.c - | +-inc.h - +-f3.c - +-f3.o - | +-f3.c - | +-inc.h - +-inc.h - +-prog - +-f1.o - | +-f1.c - | +-inc.h - +-f2.o - | +-f2.c - | +-inc.h - +-f3.o - +-f3.c - +-inc.h - </screen> + <scons_output example="troubleshoot_tree1" suffix="1"> + <scons_output_command>scons -Q --tree=all</scons_output_command> + </scons_output> <para> @@ -609,13 +451,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=all f2.o</userinput> - cc -o f2.o -c -I. f2.c - +-f2.o - +-f2.c - +-inc.h - </screen> + <scons_output example="troubleshoot_tree1" suffix="2"> + <scons_output_command>scons -Q --tree=all f2.o</scons_output_command> + </scons_output> <para> @@ -629,17 +467,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=all f1.o f3.o</userinput> - cc -o f1.o -c -I. f1.c - +-f1.o - +-f1.c - +-inc.h - cc -o f3.o -c -I. f3.c - +-f3.o - +-f3.c - +-inc.h - </screen> + <scons_output example="troubleshoot_tree1" suffix="3"> + <scons_output_command>scons -Q --tree=all f1.o f3.o</scons_output_command> + </scons_output> <para> @@ -649,49 +479,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=status</userinput> - cc -o f1.o -c -I. f1.c - cc -o f2.o -c -I. f2.c - cc -o f3.o -c -I. f3.c - cc -o prog f1.o f2.o f3.o - E = exists - R = exists in repository only - b = implicit builder - B = explicit builder - S = side effect - P = precious - A = always build - C = current - N = no clean - H = no cache - - [E b ]+-. - [E C ] +-SConstruct - [E C ] +-f1.c - [E B C ] +-f1.o - [E C ] | +-f1.c - [E C ] | +-inc.h - [E C ] +-f2.c - [E B C ] +-f2.o - [E C ] | +-f2.c - [E C ] | +-inc.h - [E C ] +-f3.c - [E B C ] +-f3.o - [E C ] | +-f3.c - [E C ] | +-inc.h - [E C ] +-inc.h - [E B C ] +-prog - [E B C ] +-f1.o - [E C ] | +-f1.c - [E C ] | +-inc.h - [E B C ] +-f2.o - [E C ] | +-f2.c - [E C ] | +-inc.h - [E B C ] +-f3.o - [E C ] +-f3.c - [E C ] +-inc.h - </screen> + <scons_output example="troubleshoot_tree1" suffix="4"> + <scons_output_command>scons -Q --tree=status</scons_output_command> + </scons_output> <para> @@ -707,21 +497,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=derived</userinput> - cc -o f1.o -c -I. f1.c - cc -o f2.o -c -I. f2.c - cc -o f3.o -c -I. f3.c - cc -o prog f1.o f2.o f3.o - +-. - +-f1.o - +-f2.o - +-f3.o - +-prog - +-f1.o - +-f2.o - +-f3.o - </screen> + <scons_output example="troubleshoot_tree1" suffix="5"> + <scons_output_command>scons -Q --tree=derived</scons_output_command> + </scons_output> <para> @@ -730,32 +508,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=derived,status</userinput> - cc -o f1.o -c -I. f1.c - cc -o f2.o -c -I. f2.c - cc -o f3.o -c -I. f3.c - cc -o prog f1.o f2.o f3.o - E = exists - R = exists in repository only - b = implicit builder - B = explicit builder - S = side effect - P = precious - A = always build - C = current - N = no clean - H = no cache - - [E b ]+-. - [E B C ] +-f1.o - [E B C ] +-f2.o - [E B C ] +-f3.o - [E B C ] +-prog - [E B C ] +-f1.o - [E B C ] +-f2.o - [E B C ] +-f3.o - </screen> + <scons_output example="troubleshoot_tree1" suffix="6"> + <scons_output_command>scons -Q --tree=derived,status</scons_output_command> + </scons_output> <para> @@ -776,14 +531,34 @@ </para> - <programlisting> - env = Environment(CPPPATH = ['.'], - LIBS = ['foo'], - LIBPATH = ['.']) - env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) - env.Program('prog1.c') - env.Program('prog2.c') - </programlisting> + <scons_example name="troubleshoot_tree2"> + <file name="SConstruct" printme="1"> +env = Environment(CPPPATH = ['.'], + LIBS = ['foo'], + LIBPATH = ['.']) +env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) +env.Program('prog1.c') +env.Program('prog2.c') + </file> + <file name="prog1.c"> +#include "inc.h" + </file> + <file name="prog2.c"> +#include "inc.h" + </file> + <file name="f1.c"> +#include "inc.h" + </file> + <file name="f2.c"> +#include "inc.h" + </file> + <file name="f3.c"> +#include "inc.h" + </file> + <file name="inc.h"> +inc.h + </file> + </scons_example> <para> @@ -792,79 +567,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=all</userinput> - cc -o f1.o -c -I. f1.c - cc -o f2.o -c -I. f2.c - cc -o f3.o -c -I. f3.c - ar rc libfoo.a f1.o f2.o f3.o - ranlib libfoo.a - cc -o prog1.o -c -I. prog1.c - cc -o prog1 prog1.o -L. -lfoo - cc -o prog2.o -c -I. prog2.c - cc -o prog2 prog2.o -L. -lfoo - +-. - +-SConstruct - +-f1.c - +-f1.o - | +-f1.c - | +-inc.h - +-f2.c - +-f2.o - | +-f2.c - | +-inc.h - +-f3.c - +-f3.o - | +-f3.c - | +-inc.h - +-inc.h - +-libfoo.a - | +-f1.o - | | +-f1.c - | | +-inc.h - | +-f2.o - | | +-f2.c - | | +-inc.h - | +-f3.o - | +-f3.c - | +-inc.h - +-prog1 - | +-prog1.o - | | +-prog1.c - | | +-inc.h - | +-libfoo.a - | +-f1.o - | | +-f1.c - | | +-inc.h - | +-f2.o - | | +-f2.c - | | +-inc.h - | +-f3.o - | +-f3.c - | +-inc.h - +-prog1.c - +-prog1.o - | +-prog1.c - | +-inc.h - +-prog2 - | +-prog2.o - | | +-prog2.c - | | +-inc.h - | +-libfoo.a - | +-f1.o - | | +-f1.c - | | +-inc.h - | +-f2.o - | | +-f2.c - | | +-inc.h - | +-f3.o - | +-f3.c - | +-inc.h - +-prog2.c - +-prog2.o - +-prog2.c - +-inc.h - </screen> + <scons_output example="troubleshoot_tree2" suffix="1"> + <scons_output_command>scons -Q --tree=all</scons_output_command> + </scons_output> <para> @@ -884,51 +589,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=prune</userinput> - cc -o f1.o -c -I. f1.c - cc -o f2.o -c -I. f2.c - cc -o f3.o -c -I. f3.c - ar rc libfoo.a f1.o f2.o f3.o - ranlib libfoo.a - cc -o prog1.o -c -I. prog1.c - cc -o prog1 prog1.o -L. -lfoo - cc -o prog2.o -c -I. prog2.c - cc -o prog2 prog2.o -L. -lfoo - +-. - +-SConstruct - +-f1.c - +-f1.o - | +-f1.c - | +-inc.h - +-f2.c - +-f2.o - | +-f2.c - | +-inc.h - +-f3.c - +-f3.o - | +-f3.c - | +-inc.h - +-inc.h - +-libfoo.a - | +-[f1.o] - | +-[f2.o] - | +-[f3.o] - +-prog1 - | +-prog1.o - | | +-prog1.c - | | +-inc.h - | +-[libfoo.a] - +-prog1.c - +-[prog1.o] - +-prog2 - | +-prog2.o - | | +-prog2.c - | | +-inc.h - | +-[libfoo.a] - +-prog2.c - +-[prog2.o] - </screen> + <scons_output example="troubleshoot_tree2" suffix="2"> + <scons_output_command>scons -Q --tree=prune</scons_output_command> + </scons_output> <para> @@ -954,7 +617,15 @@ </para> - + <scons_example name="troubleshoot_presub"> + <file name="SConstruct"> +env = Environment(CPPPATH = ['.']) +env.Program('prog', 'prog.c') + </file> + <file name="prog.c"> +prog.c + </file> + </scons_example> <!-- @@ -962,20 +633,20 @@ shows the Python functions from the sconsdoc.py execution wrapper used to generate this manual, not the underlying command-line strings. - <scons_output example="presub"> + <scons_output example="troubleshoot_presub" suffix="1"> <scons_output_command>scons -Q - -debug=presub</scons_output_command> </scons_output> --> <screen> - % <userinput>scons -Q --debug=presub</userinput> - Building prog.o with action: - $CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCOMCOM $SOURCES - cc -o prog.o -c -I. prog.c - Building prog with action: - $SMART_LINKCOM - cc -o prog prog.o +% <userinput>scons -Q --debug=presub</userinput> +Building prog.o with action: + $CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCOMCOM $SOURCES +cc -o prog.o -c -I. prog.c +Building prog with action: + $SMART_LINKCOM +cc -o prog prog.o </screen> </section> @@ -994,10 +665,21 @@ </para> - <programlisting> - env = Environment(LIBPATH = ['libs1', 'libs2']) - env.Program('prog.c', LIBS=['foo', 'bar']) - </programlisting> + <scons_example name="troubleshoot_findlibs"> + <file name="SConstruct" printme="1"> +env = Environment(LIBPATH = ['libs1', 'libs2']) +env.Program('prog.c', LIBS=['foo', 'bar']) + </file> + <file name="prog.c"> +prog.c + </file> + <file name="libs1/libfoo.a"> +libs1/libfoo.a + </file> + <file name="libs2/libbar.a"> +libs2/libbar.a + </file> + </scons_example> <para> @@ -1009,20 +691,9 @@ </para> - <screen> - % <userinput>scons -Q --debug=findlibs</userinput> - findlibs: looking for 'libfoo.a' in 'libs1' ... - findlibs: ... FOUND 'libfoo.a' in 'libs1' - findlibs: looking for 'libfoo.so' in 'libs1' ... - findlibs: looking for 'libfoo.so' in 'libs2' ... - findlibs: looking for 'libbar.a' in 'libs1' ... - findlibs: looking for 'libbar.a' in 'libs2' ... - findlibs: ... FOUND 'libbar.a' in 'libs2' - findlibs: looking for 'libbar.so' in 'libs1' ... - findlibs: looking for 'libbar.so' in 'libs2' ... - cc -o prog.o -c prog.c - cc -o prog prog.o -Llibs1 -Llibs2 -lfoo -lbar - </screen> + <scons_output example="troubleshoot_findlibs" suffix="1"> + <scons_output_command>scons -Q --debug=findlibs</scons_output_command> + </scons_output> </section> @@ -1038,25 +709,25 @@ </para> - <scons_example name="includes"> + <scons_example name="troubleshoot_includes"> <file name="SConstruct" printme="1"> - env = Environment(CPPPATH = ['inc1', 'inc2']) - env.Program('prog.c') +env = Environment(CPPPATH = ['inc1', 'inc2']) +env.Program('prog.c') </file> <file name="prog.c"> - #include "file1.h" - #include "file2.h" - prog.c +#include "file1.h" +#include "file2.h" +prog.c </file> <file name="inc1/file1.h"> - inc1/file1.h +inc1/file1.h </file> <file name="inc2/file2.h"> - inc2/file2.h +inc2/file2.h </file> </scons_example> - <scons_output example="includes"> + <scons_output example="troubleshoot_includes" suffix="1"> <scons_output_command>scons -Q - - debug=includes prog</scons_output_command> </scons_output> @@ -1086,9 +757,11 @@ </para> - <programlisting> - Program('prog.c') - </programlisting> + <scons_example name="troubleshoot_stacktrace"> + <file name="SConstruct" printme="1"> +Program('prog.c') + </file> + </scons_example> <para> @@ -1098,10 +771,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - scons: *** [prog.o] Source `prog.c' not found, needed by target `prog.o'. - </screen> + <scons_output example="troubleshoot_stacktrace" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1116,19 +788,9 @@ </para> - <screen> - % <userinput>scons -Q --debug=stacktrace</userinput> - scons: *** [prog.o] Source `prog.c' not found, needed by target `prog.o'. - scons: internal stack trace: - File "bootstrap/src/engine/SCons/Job.py", line 199, in start - task.prepare() - File "bootstrap/src/engine/SCons/Script/Main.py", line 168, in prepare - return SCons.Taskmaster.OutOfDateTask.prepare(self) - File "bootstrap/src/engine/SCons/Taskmaster.py", line 189, in prepare - executor.prepare() - File "bootstrap/src/engine/SCons/Executor.py", line 392, in prepare - raise SCons.Errors.StopError(msg % (s, self.batches[0].targets[0])) - </screen> + <scons_output example="troubleshoot_stacktrace" suffix="2"> + <scons_output_command>scons -Q --debug=stacktrace</scons_output_command> + </scons_output> <para> @@ -1175,74 +837,23 @@ </para> - <programlisting> - env = Environment(CPPPATH = ['.']) - env.Program('prog.c') - </programlisting> + <scons_example name="troubleshoot_taskmastertrace"> + <file name="SConstruct" printme="1"> +env = Environment(CPPPATH = ['.']) +env.Program('prog.c') + </file> + <file name="prog.c"> +#include "inc.h" +prog.c + </file> + <file name="inc.h"> +#define STRING "one" + </file> + </scons_example> - <screen> - % <userinput>scons -Q --taskmastertrace=- prog</userinput> - - Taskmaster: Looking for a node to evaluate - Taskmaster: Considering node <no_state 0 'prog'> and its children: - Taskmaster: <no_state 0 'prog.o'> - Taskmaster: adjusted ref count: <pending 1 'prog'>, child 'prog.o' - Taskmaster: Considering node <no_state 0 'prog.o'> and its children: - Taskmaster: <no_state 0 'prog.c'> - Taskmaster: <no_state 0 'inc.h'> - Taskmaster: adjusted ref count: <pending 1 'prog.o'>, child 'prog.c' - Taskmaster: adjusted ref count: <pending 2 'prog.o'>, child 'inc.h' - Taskmaster: Considering node <no_state 0 'prog.c'> and its children: - Taskmaster: Evaluating <pending 0 'prog.c'> - - Task.make_ready_current(): node <pending 0 'prog.c'> - Task.prepare(): node <up_to_date 0 'prog.c'> - Task.executed_with_callbacks(): node <up_to_date 0 'prog.c'> - Task.postprocess(): node <up_to_date 0 'prog.c'> - Task.postprocess(): removing <up_to_date 0 'prog.c'> - Task.postprocess(): adjusted parent ref count <pending 1 'prog.o'> - - Taskmaster: Looking for a node to evaluate - Taskmaster: Considering node <no_state 0 'inc.h'> and its children: - Taskmaster: Evaluating <pending 0 'inc.h'> - - Task.make_ready_current(): node <pending 0 'inc.h'> - Task.prepare(): node <up_to_date 0 'inc.h'> - Task.executed_with_callbacks(): node <up_to_date 0 'inc.h'> - Task.postprocess(): node <up_to_date 0 'inc.h'> - Task.postprocess(): removing <up_to_date 0 'inc.h'> - Task.postprocess(): adjusted parent ref count <pending 0 'prog.o'> - - Taskmaster: Looking for a node to evaluate - Taskmaster: Considering node <pending 0 'prog.o'> and its children: - Taskmaster: <up_to_date 0 'prog.c'> - Taskmaster: <up_to_date 0 'inc.h'> - Taskmaster: Evaluating <pending 0 'prog.o'> - - Task.make_ready_current(): node <pending 0 'prog.o'> - Task.prepare(): node <executing 0 'prog.o'> - Task.execute(): node <executing 0 'prog.o'> - cc -o prog.o -c -I. prog.c - Task.executed_with_callbacks(): node <executing 0 'prog.o'> - Task.postprocess(): node <executed 0 'prog.o'> - Task.postprocess(): removing <executed 0 'prog.o'> - Task.postprocess(): adjusted parent ref count <pending 0 'prog'> - - Taskmaster: Looking for a node to evaluate - Taskmaster: Considering node <pending 0 'prog'> and its children: - Taskmaster: <executed 0 'prog.o'> - Taskmaster: Evaluating <pending 0 'prog'> - - Task.make_ready_current(): node <pending 0 'prog'> - Task.prepare(): node <executing 0 'prog'> - Task.execute(): node <executing 0 'prog'> - cc -o prog prog.o - Task.executed_with_callbacks(): node <executing 0 'prog'> - Task.postprocess(): node <executed 0 'prog'> - - Taskmaster: Looking for a node to evaluate - Taskmaster: No candidate anymore. - </screen> + <scons_output example="troubleshoot_taskmastertrace" os="posix" suffix="1"> + <scons_output_command>scons -Q --taskmastertrace=- prog</scons_output_command> + </scons_output> <para> @@ -1332,3 +943,5 @@ </section> --> + +</chapter> diff --git a/doc/user/variables.in b/doc/user/variables.in deleted file mode 100644 index 1b959ff..0000000 --- a/doc/user/variables.in +++ /dev/null @@ -1,56 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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.xml b/doc/user/variables.xml index 1b959ff..644893b 100644 --- a/doc/user/variables.xml +++ b/doc/user/variables.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<appendix id="app-variables" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Construction Variables</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -49,8 +70,6 @@ where the name appears for each entry. </para> -<variablelist> - -&variables-gen; +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../generated/variables.gen"/> -</variablelist> +</appendix> diff --git a/doc/user/variants.in b/doc/user/variants.in deleted file mode 100644 index dc3315d..0000000 --- a/doc/user/variants.in +++ /dev/null @@ -1,151 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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. - ---> - -<!-- - -=head1 Variant builds - -=head2 Variations on a theme - -Other variations of this model are possible. For example, you might decide -that you want to separate out your include files into platform dependent and -platform independent files. In this case, you'd have to define an -alternative to C<$INCLUDE> for platform-dependent files. Most F<Conscript> -files, generating purely platform-independent include files, would not have -to change. - -You might also want to be able to compile your whole system with debugging -or profiling, for example, enabled. You could do this with appropriate -command line options, such as C<DEBUG=on>. This would then be translated -into the appropriate platform-specific requirements to enable debugging -(this might include turning off optimization, for example). You could -optionally vary the name space for these different types of systems, but, as -we'll see in the next section, it's not B<essential> to do this, since Cons -is pretty smart about rebuilding things when you change options. - ---> - - <para> - - The &variant_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 - build a program for both Windows and Linux platforms, - but that we want to build it in a shared directory - with separate side-by-side build directories - for the Windows and Linux versions of the program. - - </para> - - <scons_example name="ex_variants"> - <file name="SConstruct" printme="1"> - platform = ARGUMENTS.get('OS', Platform()) - - include = "#export/$PLATFORM/include" - lib = "#export/$PLATFORM/lib" - bin = "#export/$PLATFORM/bin" - - env = Environment(PLATFORM = platform, - BINDIR = bin, - INCDIR = include, - LIBDIR = lib, - CPPPATH = [include], - LIBPATH = [lib], - LIBS = 'world') - - Export('env') - - env.SConscript('src/SConscript', variant_dir='build/$PLATFORM') - </file> - <directory name="src"></directory> - <directory name="src/hello"></directory> - <directory name="src/world"></directory> - <file name="src/SConscript"> - Import('env') - SConscript('hello/SConscript') - SConscript('world/SConscript') - </file> - <file name="src/hello/SConscript"> - Import('env') - hello = env.Program('hello.c') - env.Install('$BINDIR', hello) - </file> - <file name="src/hello/hello.c"> - #include "world.h" - int main(int argc, char *argv[]) { printf "hello.c\n"; world(); } - </file> - <file name="src/world/SConscript"> - Import('env') - world = env.Library('world.c') - env.Install('$LIBDIR', world) - env.Install('$INCDIR', 'world.h') - </file> - <file name="src/world/world.h"> - #define STRING "world.h" - extern int world(); - </file> - <file name="src/world/world.c"> - int world() { printf "world.c\n"; } - </file> - </scons_example> - - <para> - - This SConstruct file, - when run on a Linux system, yields: - - </para> - - <scons_output example="ex_variants" os="posix"> - <scons_output_command>scons -Q OS=linux</scons_output_command> - </scons_output> - - <para> - - The same SConstruct file on Windows would build: - - </para> - - <scons_output example="ex_variants" os="win32"> - <scons_output_command>scons -Q OS=windows</scons_output_command> - </scons_output> - - <!-- - - <scons_example name="ex_var2"> - <file name="SConstruct" printme="1"> - env = Environment(OS = ARGUMENTS.get('OS')) - for os in ['newell', 'post']: - SConscript('src/SConscript', variant_dir='build/' + os) - </file> - </scons_example> - - <scons_output example="ex_var2"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - --> diff --git a/doc/user/variants.xml b/doc/user/variants.xml index b0d1096..7915dfd 100644 --- a/doc/user/variants.xml +++ b/doc/user/variants.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-variants" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Variant Builds</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -61,25 +82,57 @@ is pretty smart about rebuilding things when you change options. </para> - <programlisting> - platform = ARGUMENTS.get('OS', Platform()) + <scons_example name="variants_ex"> + <file name="SConstruct" printme="1"> +platform = ARGUMENTS.get('OS', Platform()) - include = "#export/$PLATFORM/include" - lib = "#export/$PLATFORM/lib" - bin = "#export/$PLATFORM/bin" +include = "#export/$PLATFORM/include" +lib = "#export/$PLATFORM/lib" +bin = "#export/$PLATFORM/bin" - env = Environment(PLATFORM = platform, - BINDIR = bin, - INCDIR = include, - LIBDIR = lib, - CPPPATH = [include], - LIBPATH = [lib], - LIBS = 'world') +env = Environment(PLATFORM = platform, + BINDIR = bin, + INCDIR = include, + LIBDIR = lib, + CPPPATH = [include], + LIBPATH = [lib], + LIBS = 'world') - Export('env') +Export('env') - env.SConscript('src/SConscript', variant_dir='build/$PLATFORM') - </programlisting> +env.SConscript('src/SConscript', variant_dir='build/$PLATFORM') + </file> + <directory name="src"></directory> + <directory name="src/hello"></directory> + <directory name="src/world"></directory> + <file name="src/SConscript"> +Import('env') +SConscript('hello/SConscript') +SConscript('world/SConscript') + </file> + <file name="src/hello/SConscript"> +Import('env') +hello = env.Program('hello.c') +env.Install('$BINDIR', hello) + </file> + <file name="src/hello/hello.c"> +#include "world.h" +int main(int argc, char *argv[]) { printf "hello.c\n"; world(); } + </file> + <file name="src/world/SConscript"> +Import('env') +world = env.Library('world.c') +env.Install('$LIBDIR', world) +env.Install('$INCDIR', 'world.h') + </file> + <file name="src/world/world.h"> +#define STRING "world.h" +extern int world(); + </file> + <file name="src/world/world.c"> +int world() { printf "world.c\n"; } + </file> + </scons_example> <para> @@ -88,17 +141,9 @@ is pretty smart about rebuilding things when you change options. </para> - <screen> - % <userinput>scons -Q OS=linux</userinput> - Install file: "build/linux/world/world.h" as "export/linux/include/world.h" - cc -o build/linux/hello/hello.o -c -Iexport/linux/include build/linux/hello/hello.c - cc -o build/linux/world/world.o -c -Iexport/linux/include build/linux/world/world.c - ar rc build/linux/world/libworld.a build/linux/world/world.o - ranlib build/linux/world/libworld.a - Install file: "build/linux/world/libworld.a" as "export/linux/lib/libworld.a" - cc -o build/linux/hello/hello build/linux/hello/hello.o -Lexport/linux/lib -lworld - Install file: "build/linux/hello/hello" as "export/linux/bin/hello" - </screen> + <scons_output example="variants_ex" os="posix" suffix="1"> + <scons_output_command>scons -Q OS=linux</scons_output_command> + </scons_output> <para> @@ -106,30 +151,24 @@ is pretty smart about rebuilding things when you change options. </para> - <screen> - C:\><userinput>scons -Q OS=windows</userinput> - Install file: "build/windows/world/world.h" as "export/windows/include/world.h" - cl /Fobuild\windows\hello\hello.obj /c build\windows\hello\hello.c /nologo /Iexport\windows\include - cl /Fobuild\windows\world\world.obj /c build\windows\world\world.c /nologo /Iexport\windows\include - lib /nologo /OUT:build\windows\world\world.lib build\windows\world\world.obj - Install file: "build/windows/world/world.lib" as "export/windows/lib/world.lib" - link /nologo /OUT:build\windows\hello\hello.exe /LIBPATH:export\windows\lib world.lib build\windows\hello\hello.obj - embedManifestExeCheck(target, source, env) - Install file: "build/windows/hello/hello.exe" as "export/windows/bin/hello.exe" - </screen> + <scons_output example="variants_ex" os="win32" suffix="2"> + <scons_output_command>scons -Q OS=windows</scons_output_command> + </scons_output> <!-- - <scons_example name="ex_var2"> + <scons_example name="variants_ex2"> <file name="SConstruct" printme="1"> - env = Environment(OS = ARGUMENTS.get('OS')) - for os in ['newell', 'post']: - SConscript('src/SConscript', variant_dir='build/' + os) +env = Environment(OS = ARGUMENTS.get('OS')) +for os in ['newell', 'post']: + SConscript('src/SConscript', variant_dir='build/' + os) </file> </scons_example> - <scons_output example="ex_var2"> + <scons_output example="variants_ex2" suffix="1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> --> + +</chapter> |
