diff options
Diffstat (limited to 'doc/user')
| -rw-r--r-- | doc/user/java.xml | 4 | ||||
| -rw-r--r-- | doc/user/separate.in | 74 | ||||
| -rw-r--r-- | doc/user/separate.xml | 74 | ||||
| -rw-r--r-- | doc/user/troubleshoot.xml | 12 | ||||
| -rw-r--r-- | doc/user/variants.in | 6 | ||||
| -rw-r--r-- | doc/user/variants.xml | 6 |
6 files changed, 100 insertions, 76 deletions
diff --git a/doc/user/java.xml b/doc/user/java.xml index 1876916..402d037 100644 --- a/doc/user/java.xml +++ b/doc/user/java.xml @@ -231,8 +231,8 @@ % <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 classes/Example1.class classes/Example2.class - jar cf prog2.jar classes/Example3.class classes/Example4.class + 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> </section> diff --git a/doc/user/separate.in b/doc/user/separate.in index 08bb986..be7e6c5 100644 --- a/doc/user/separate.in +++ b/doc/user/separate.in @@ -114,34 +114,46 @@ program using the F<build/foo.c> path name. It's often useful to keep any built files completely separate from the source files. - This is usually done by creating one or more separate - <emphasis>build directories</emphasis> + 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 of build. + 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 &BuildDir; function. + 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 Build Directory as Part of an &SConscript; Call</title> + <title>Specifying a Variant Directory Tree as Part of an &SConscript; Call</title> <para> - The most straightforward way to establish a build directory + 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 &build_dir; argument to the + 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', build_dir='build') + SConscript('src/SConscript', variant_dir='build') </file> <file name="src/SConscript"> env = Environment() @@ -192,11 +204,11 @@ program using the F<build/foo.c> path name. </section> <section> - <title>Why &SCons; Duplicates Source Files in a Build Directory</title> + <title>Why &SCons; Duplicates Source Files in a Variant Directory Tree</title> <para> - &SCons; duplicates source files in build directories + &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, @@ -209,14 +221,14 @@ program using the F<build/foo.c> path name. <para> The most direct reason to duplicate source files - in build directories + in variant directories is simply that some tools (mostly older vesions) 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 build directory, - or to duplicate the source files in the build directory. + and move it to the variant directory, + or to duplicate the source files in the variant directory. </para> @@ -226,7 +238,7 @@ program using the F<build/foo.c> path name. relative references between files can cause problems if we don't just duplicate the hierarchy of source files - in the build directory. + 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: @@ -251,7 +263,7 @@ program using the F<build/foo.c> path name. 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 build directory, + 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. @@ -264,14 +276,14 @@ program using the F<build/foo.c> path name. it <emphasis>can</emphasis> usually be safely disabled. The next section describes how you can disable the duplication of source files - in the build directory. + in the variant directory. </para> </section> <section> - <title>Telling &SCons; to Not Duplicate Source Files in the Build Directory</title> + <title>Telling &SCons; to Not Duplicate Source Files in the Variant Directory Tree</title> <para> @@ -287,15 +299,15 @@ program using the F<build/foo.c> path name. </para> <sconstruct> - SConscript('src/SConscript', build_dir='build', duplicate=0) + SConscript('src/SConscript', variant_dir='build', duplicate=0) </sconstruct> <para> When this flag is specified, - &SCons; uses the build directory + &SCons; uses the variant directory like most people expect--that is, - the output files are placed in the build directory + the output files are placed in the variant directory while the source files stay in the source directory: </para> @@ -315,11 +327,11 @@ program using the F<build/foo.c> path name. </section> <section> - <title>The &BuildDir; Function</title> + <title>The &VariantDir; Function</title> <para> - Use the &BuildDir; function to establish that target + Use the &VariantDir; function to establish that target files should be built in a separate directory from the source files: @@ -327,7 +339,7 @@ program using the F<build/foo.c> path name. <scons_example name="ex_builddir"> <file name="SConstruct" printme="1"> - BuildDir('build', 'src') + VariantDir('build', 'src') env = Environment() env.Program('build/hello.c') </file> @@ -350,9 +362,9 @@ program using the F<build/foo.c> path name. <para> - When using the &BuildDir; function directly, + When using the &VariantDir; function directly, &SCons; still duplicates the source files - in the build directory by default: + in the variant directory by default: </para> @@ -371,7 +383,7 @@ program using the F<build/foo.c> path name. <scons_example name="ex_duplicate_0"> <file name="SConstruct" printme="1"> - BuildDir('build', 'src', duplicate=0) + VariantDir('build', 'src', duplicate=0) env = Environment() env.Program('build/hello.c') </file> @@ -396,11 +408,11 @@ program using the F<build/foo.c> path name. </section> <section> - <title>Using &BuildDir; With an &SConscript; File</title> + <title>Using &VariantDir; With an &SConscript; File</title> <para> - Even when using the &BuildDir; function, + Even when using the &VariantDir; function, it's much more natural to use it with a subsidiary &SConscript; file. For example, if the @@ -411,7 +423,7 @@ program using the F<build/foo.c> path name. <scons_example name="example_builddir_sconscript"> <file name="SConstruct"> - BuildDir('build', 'src') + VariantDir('build', 'src') SConscript('build/SConscript') </file> <file name="src/SConscript" printme="1"> @@ -457,11 +469,11 @@ program using the F<build/foo.c> path name. <!-- <section> - <title>Why You'd Want to Call &BuildDir; Instead of &SConscript;</title> + <title>Why You'd Want to Call &VariantDir; Instead of &SConscript;</title> <para> - XXX why call BuildDir() instead of SConscript(build_dir=) + XXX why call VariantDir() instead of SConscript(variant_dir=) </para> diff --git a/doc/user/separate.xml b/doc/user/separate.xml index 57acd48..57ade04 100644 --- a/doc/user/separate.xml +++ b/doc/user/separate.xml @@ -114,33 +114,45 @@ program using the F<build/foo.c> path name. It's often useful to keep any built files completely separate from the source files. - This is usually done by creating one or more separate - <emphasis>build directories</emphasis> + 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 of build. + 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 &BuildDir; function. + 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 Build Directory as Part of an &SConscript; Call</title> + <title>Specifying a Variant Directory Tree as Part of an &SConscript; Call</title> <para> - The most straightforward way to establish a build directory + 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 &build_dir; argument to the + If you then pass a &variant_dir; argument to the &SConscript; function call: </para> <programlisting> - SConscript('src/SConscript', build_dir='build') + SConscript('src/SConscript', variant_dir='build') </programlisting> <para> @@ -187,11 +199,11 @@ program using the F<build/foo.c> path name. </section> <section> - <title>Why &SCons; Duplicates Source Files in a Build Directory</title> + <title>Why &SCons; Duplicates Source Files in a Variant Directory Tree</title> <para> - &SCons; duplicates source files in build directories + &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, @@ -204,14 +216,14 @@ program using the F<build/foo.c> path name. <para> The most direct reason to duplicate source files - in build directories + in variant directories is simply that some tools (mostly older vesions) 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 build directory, - or to duplicate the source files in the build directory. + and move it to the variant directory, + or to duplicate the source files in the variant directory. </para> @@ -221,7 +233,7 @@ program using the F<build/foo.c> path name. relative references between files can cause problems if we don't just duplicate the hierarchy of source files - in the build directory. + 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: @@ -246,7 +258,7 @@ program using the F<build/foo.c> path name. 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 build directory, + 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. @@ -259,14 +271,14 @@ program using the F<build/foo.c> path name. it <emphasis>can</emphasis> usually be safely disabled. The next section describes how you can disable the duplication of source files - in the build directory. + in the variant directory. </para> </section> <section> - <title>Telling &SCons; to Not Duplicate Source Files in the Build Directory</title> + <title>Telling &SCons; to Not Duplicate Source Files in the Variant Directory Tree</title> <para> @@ -282,15 +294,15 @@ program using the F<build/foo.c> path name. </para> <programlisting> - SConscript('src/SConscript', build_dir='build', duplicate=0) + SConscript('src/SConscript', variant_dir='build', duplicate=0) </programlisting> <para> When this flag is specified, - &SCons; uses the build directory + &SCons; uses the variant directory like most people expect--that is, - the output files are placed in the build directory + the output files are placed in the variant directory while the source files stay in the source directory: </para> @@ -310,18 +322,18 @@ program using the F<build/foo.c> path name. </section> <section> - <title>The &BuildDir; Function</title> + <title>The &VariantDir; Function</title> <para> - Use the &BuildDir; function to establish that target + Use the &VariantDir; function to establish that target files should be built in a separate directory from the source files: </para> <programlisting> - BuildDir('build', 'src') + VariantDir('build', 'src') env = Environment() env.Program('build/hello.c') </programlisting> @@ -340,9 +352,9 @@ program using the F<build/foo.c> path name. <para> - When using the &BuildDir; function directly, + When using the &VariantDir; function directly, &SCons; still duplicates the source files - in the build directory by default: + in the variant directory by default: </para> @@ -364,7 +376,7 @@ program using the F<build/foo.c> path name. </para> <programlisting> - BuildDir('build', 'src', duplicate=0) + VariantDir('build', 'src', duplicate=0) env = Environment() env.Program('build/hello.c') </programlisting> @@ -389,11 +401,11 @@ program using the F<build/foo.c> path name. </section> <section> - <title>Using &BuildDir; With an &SConscript; File</title> + <title>Using &VariantDir; With an &SConscript; File</title> <para> - Even when using the &BuildDir; function, + Even when using the &VariantDir; function, it's much more natural to use it with a subsidiary &SConscript; file. For example, if the @@ -415,7 +427,7 @@ program using the F<build/foo.c> path name. <programlisting> - BuildDir('build', 'src') + VariantDir('build', 'src') SConscript('build/SConscript') </programlisting> @@ -448,11 +460,11 @@ program using the F<build/foo.c> path name. <!-- <section> - <title>Why You'd Want to Call &BuildDir; Instead of &SConscript;</title> + <title>Why You'd Want to Call &VariantDir; Instead of &SConscript;</title> <para> - XXX why call BuildDir() instead of SConscript(build_dir=) + XXX why call VariantDir() instead of SConscript(variant_dir=) </para> diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml index ca5ace8..dc90622 100644 --- a/doc/user/troubleshoot.xml +++ b/doc/user/troubleshoot.xml @@ -261,7 +261,7 @@ <screen> % <userinput>scons</userinput> scons: Reading SConscript files ... - { 'BUILDERS': {'InstallAs': <function InstallAsBuilderWrapper at 0x700000>, 'Install': <function InstallBuilderWrapper at 0x700000>}, + { 'BUILDERS': {'_InternalInstall': <function InstallBuilderWrapper at 0x700000>, '_InternalInstallAs': <function InstallAsBuilderWrapper at 0x700000>}, 'CONFIGUREDIR': '#/.sconf_temp', 'CONFIGURELOG': '#/config.log', 'CPPSUFFIXES': [ '.c', @@ -293,7 +293,7 @@ 'INSTALL': <function copyFunc at 0x700000>, 'LATEXSUFFIXES': ['.tex', '.ltx', '.latex'], 'LIBPREFIX': 'lib', - 'LIBPREFIXES': '$LIBPREFIX', + 'LIBPREFIXES': ['$LIBPREFIX'], 'LIBSUFFIX': '.a', 'LIBSUFFIXES': ['$LIBSUFFIX', '$SHLIBSUFFIX'], 'MAXLINELENGTH': 128072, @@ -338,7 +338,7 @@ <screen> C:\><userinput>scons</userinput> scons: Reading SConscript files ... - { 'BUILDERS': {'RES': <SCons.Builder.BuilderBase instance at 0x700000>, 'Object': <SCons.Builder.CompositeBuilder instance at 0x700000>, 'InstallAs': <function InstallAsBuilderWrapper at 0x700000>, 'PCH': <SCons.Builder.BuilderBase instance at 0x700000>, 'Install': <function InstallBuilderWrapper at 0x700000>, 'SharedObject': <SCons.Builder.CompositeBuilder instance at 0x700000>, 'StaticObject': <SCons.Builder.CompositeBuilder instance at 0x700000>}, + { 'BUILDERS': {'_InternalInstall': <function InstallBuilderWrapper at 0x700000>, 'Object': <SCons.Builder.CompositeBuilder instance at 0x700000>, 'PCH': <SCons.Builder.BuilderBase instance at 0x700000>, 'RES': <SCons.Builder.BuilderBase instance at 0x700000>, 'SharedObject': <SCons.Builder.CompositeBuilder instance at 0x700000>, 'StaticObject': <SCons.Builder.CompositeBuilder instance at 0x700000>, '_InternalInstallAs': <function InstallAsBuilderWrapper at 0x700000>}, 'CC': 'cl', 'CCCOM': <SCons.Action.FunctionAction instance at 0x700000>, 'CCCOMFLAGS': '$CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo$TARGET $CCPCHFLAGS $CCPDBFLAGS', @@ -1115,10 +1115,10 @@ % <userinput>scons -Q --debug=stacktrace</userinput> scons: *** Source `prog.c' not found, needed by target `prog.o'. Stop. scons: internal stack trace: - File "bootstrap/src/engine/SCons/Job.py", line 114, in start - File "bootstrap/src/engine/SCons/Script/Main.py", line 157, in prepare + File "bootstrap/src/engine/SCons/Job.py", line 131, in start + File "bootstrap/src/engine/SCons/Script/Main.py", line 169, in prepare File "bootstrap/src/engine/SCons/Taskmaster.py", line 169, in prepare - File "bootstrap/src/engine/SCons/Node/FS.py", line 2568, in prepare + File "bootstrap/src/engine/SCons/Node/FS.py", line 2551, in prepare File "bootstrap/src/engine/SCons/Node/__init__.py", line 349, in prepare </screen> diff --git a/doc/user/variants.in b/doc/user/variants.in index 2bdc394..9980b1d 100644 --- a/doc/user/variants.in +++ b/doc/user/variants.in @@ -49,7 +49,7 @@ is pretty smart about rebuilding things when you change options. <para> - The &build_dir; keyword argument of + 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;. @@ -79,7 +79,7 @@ is pretty smart about rebuilding things when you change options. Export('env') - env.SConscript('src/SConscript', build_dir='build/$PLATFORM') + env.SConscript('src/SConscript', variant_dir='build/$PLATFORM') </file> <directory name="src"></directory> <directory name="src/hello"></directory> @@ -140,7 +140,7 @@ is pretty smart about rebuilding things when you change options. <file name="SConstruct" printme="1"> env = Environment(OS = ARGUMENTS.get('OS')) for os in ['newell', 'post']: - SConscript('src/SConscript', build_dir='build/' + os) + SConscript('src/SConscript', variant_dir='build/' + os) </file> </scons_example> diff --git a/doc/user/variants.xml b/doc/user/variants.xml index 6727859..3b570cd 100644 --- a/doc/user/variants.xml +++ b/doc/user/variants.xml @@ -49,7 +49,7 @@ is pretty smart about rebuilding things when you change options. <para> - The &build_dir; keyword argument of + 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;. @@ -78,7 +78,7 @@ is pretty smart about rebuilding things when you change options. Export('env') - env.SConscript('src/SConscript', build_dir='build/$PLATFORM') + env.SConscript('src/SConscript', variant_dir='build/$PLATFORM') </programlisting> <para> @@ -123,7 +123,7 @@ is pretty smart about rebuilding things when you change options. <file name="SConstruct" printme="1"> env = Environment(OS = ARGUMENTS.get('OS')) for os in ['newell', 'post']: - SConscript('src/SConscript', build_dir='build/' + os) + SConscript('src/SConscript', variant_dir='build/' + os) </file> </scons_example> |