diff options
| author | Luca Falavigna <dktrkranz@debian.org> | 2011-09-10 11:25:53 +0200 |
|---|---|---|
| committer | Luca Falavigna <dktrkranz@debian.org> | 2011-09-10 11:25:53 +0200 |
| commit | ba4425ab5227fd9597fccd368bffff6bf1032149 (patch) | |
| tree | b286bf4e65900f6a7604c001dc2ad94fec12e768 /doc/user | |
| parent | 84c6f9729dbbc175431874957d0654310410bd6f (diff) | |
Imported Upstream version 2.1.0upstream/2.1.0
Diffstat (limited to 'doc/user')
96 files changed, 651 insertions, 253 deletions
diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST index ef273d3..0994f2b 100644 --- a/doc/user/MANIFEST +++ b/doc/user/MANIFEST @@ -17,6 +17,7 @@ errors.xml example.xml factories.xml file-removal.xml +functions.xml hierarchy.xml install.xml java.xml diff --git a/doc/user/README b/doc/user/README index 773fbc2..7ebdb93 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 The SCons Foundation +# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation When adding a new file, add it to main.xml and MANIFEST. diff --git a/doc/user/actions.in b/doc/user/actions.in index 06dcd63..6634a0d 100644 --- a/doc/user/actions.in +++ b/doc/user/actions.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/actions.xml b/doc/user/actions.xml index 7231a70..a3cce98 100644 --- a/doc/user/actions.xml +++ b/doc/user/actions.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/add-method.in b/doc/user/add-method.in index a9595a9..815e0a7 100644 --- a/doc/user/add-method.in +++ b/doc/user/add-method.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml index 46f858d..6cb1a93 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -113,6 +113,7 @@ 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> <para> diff --git a/doc/user/alias.in b/doc/user/alias.in index c17d76a..1fb7e30 100644 --- a/doc/user/alias.in +++ b/doc/user/alias.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/alias.xml b/doc/user/alias.xml index fed201f..8888f77 100644 --- a/doc/user/alias.xml +++ b/doc/user/alias.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/ant.in b/doc/user/ant.in index d39207d..2cc83a3 100644 --- a/doc/user/ant.in +++ b/doc/user/ant.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/ant.xml b/doc/user/ant.xml index d39207d..2cc83a3 100644 --- a/doc/user/ant.xml +++ b/doc/user/ant.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/build-install.in b/doc/user/build-install.in index 8d1c005..aad4a44 100644 --- a/doc/user/build-install.in +++ b/doc/user/build-install.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -121,9 +121,10 @@ <para> - &SCons; will work with any version of Python from 2.4 or later. + &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 Python version available. + we recommend using the most recent 2.x Python version available. Newer Pythons have significant improvements that help speed up the performance of &SCons;. @@ -198,7 +199,7 @@ </para> <screen> - # <userinput>rpm -Uvh scons-2.0.1-1.noarch.rpm</userinput> + # <userinput>rpm -Uvh scons-2.1.0-1.noarch.rpm</userinput> </screen> <para> @@ -260,7 +261,7 @@ &SCons; provides a Windows installer that makes installation extremely easy. - Download the <filename>scons-2.0.1.win32.exe</filename> + Download the <filename>scons-2.1.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 @@ -370,8 +371,8 @@ <para> The first step is to download either the - <filename>scons-2.0.1.tar.gz</filename> - or <filename>scons-2.0.1.zip</filename>, + <filename>scons-2.1.0.tar.gz</filename> + or <filename>scons-2.1.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>. @@ -384,7 +385,7 @@ on Linux or UNIX, or <application>WinZip</application> on Windows. This will create a directory called - <filename>scons-2.0.1</filename>, + <filename>scons-2.1.0</filename>, usually in your local directory. Then change your working directory to that directory and install &SCons; by executing the following commands: @@ -392,7 +393,7 @@ </para> <screen> - # <userinput>cd scons-2.0.1</userinput> + # <userinput>cd scons-2.1.0</userinput> # <userinput>python setup.py install</userinput> </screen> @@ -460,9 +461,9 @@ This will install the &SCons; build engine in the - <filename>/usr/lib/scons-2.0.1</filename> + <filename>/usr/lib/scons-2.1.0</filename> or - <filename>C:\Python25\scons-2.0.1</filename> + <filename>C:\Python25\scons-2.1.0</filename> directory, for example. </para> @@ -519,7 +520,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.0.1</filename>. + <filename>/opt/scons/lib/scons-2.1.0</filename>. </para> diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml index 8d1c005..aad4a44 100644 --- a/doc/user/build-install.xml +++ b/doc/user/build-install.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -121,9 +121,10 @@ <para> - &SCons; will work with any version of Python from 2.4 or later. + &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 Python version available. + we recommend using the most recent 2.x Python version available. Newer Pythons have significant improvements that help speed up the performance of &SCons;. @@ -198,7 +199,7 @@ </para> <screen> - # <userinput>rpm -Uvh scons-2.0.1-1.noarch.rpm</userinput> + # <userinput>rpm -Uvh scons-2.1.0-1.noarch.rpm</userinput> </screen> <para> @@ -260,7 +261,7 @@ &SCons; provides a Windows installer that makes installation extremely easy. - Download the <filename>scons-2.0.1.win32.exe</filename> + Download the <filename>scons-2.1.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 @@ -370,8 +371,8 @@ <para> The first step is to download either the - <filename>scons-2.0.1.tar.gz</filename> - or <filename>scons-2.0.1.zip</filename>, + <filename>scons-2.1.0.tar.gz</filename> + or <filename>scons-2.1.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>. @@ -384,7 +385,7 @@ on Linux or UNIX, or <application>WinZip</application> on Windows. This will create a directory called - <filename>scons-2.0.1</filename>, + <filename>scons-2.1.0</filename>, usually in your local directory. Then change your working directory to that directory and install &SCons; by executing the following commands: @@ -392,7 +393,7 @@ </para> <screen> - # <userinput>cd scons-2.0.1</userinput> + # <userinput>cd scons-2.1.0</userinput> # <userinput>python setup.py install</userinput> </screen> @@ -460,9 +461,9 @@ This will install the &SCons; build engine in the - <filename>/usr/lib/scons-2.0.1</filename> + <filename>/usr/lib/scons-2.1.0</filename> or - <filename>C:\Python25\scons-2.0.1</filename> + <filename>C:\Python25\scons-2.1.0</filename> directory, for example. </para> @@ -519,7 +520,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.0.1</filename>. + <filename>/opt/scons/lib/scons-2.1.0</filename>. </para> diff --git a/doc/user/builders-built-in.in b/doc/user/builders-built-in.in index f7da806..d16e8c3 100644 --- a/doc/user/builders-built-in.in +++ b/doc/user/builders-built-in.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml index 3d47f5c..39e0533 100644 --- a/doc/user/builders-built-in.xml +++ b/doc/user/builders-built-in.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -160,6 +160,7 @@ 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> <para> diff --git a/doc/user/builders-commands.in b/doc/user/builders-commands.in index af3aec8..1082058 100644 --- a/doc/user/builders-commands.in +++ b/doc/user/builders-commands.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -72,7 +72,7 @@ <scons_example name="ex1"> <file name="SConstruct" printme="1"> env = Environment() - env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET") + env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET") </file> <file name="foo.in"> foo.in diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml index 7e48660..e3066c6 100644 --- a/doc/user/builders-commands.xml +++ b/doc/user/builders-commands.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in index 0bf6971..addc837 100644 --- a/doc/user/builders-writing.in +++ b/doc/user/builders-writing.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -823,7 +823,6 @@ This functionality could be invoked as in the following example: <file name="my_command" chmod="0755"> cat </file> - </file> </scons_example> @@ -842,7 +841,6 @@ This functionality could be invoked as in the following example: MY_EMITTER = modify2) env1.Foo('file1') env2.Foo('file2') - </file> </sconstruct> <para> @@ -899,8 +897,8 @@ This functionality could be invoked as in the following example: <para> - The <filename>site_scons</filename> directory gives you a place to - put Python modules you can import into your &SConscript; files + 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>), @@ -912,11 +910,21 @@ This functionality could be invoked as in the following example: <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, the + 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 file containing two functions, + an &Environment; or a Python module or package containing two functions, <function>exists()</function> and <function>generate()</function>. </para> @@ -931,7 +939,7 @@ This functionality could be invoked as in the following example: </para> <scons_example name="site1"> - <file name="site_scons/site_init.py" printme=1> + <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', @@ -975,16 +983,23 @@ This functionality could be invoked as in the following example: --> <para> - Similarly, a more full-fledged tool with + A more full-fledged tool with <function>exists()</function> and <function>generate()</function> - methods can be installed in - <filename>site_scons/site_tools/toolname.py</filename>. 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, site_scons gives you the - hook you need. + 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> @@ -998,7 +1013,7 @@ This functionality could be invoked as in the following example: </para> <scons_example name="site2"> - <file name="site_scons/my_utils.py" printme=1> + <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)""" @@ -1047,13 +1062,15 @@ This functionality could be invoked as in the following example: <para> - If you have a machine-wide site dir you'd like to use instead of - <filename>./site_scons</filename>, use the - <literal>--site-dir</literal> option to point to your dir. + 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. + To avoid using a <filename>site_scons</filename> dir at all, + even if it exists, use the <literal>--no-site-dir</literal> + option. </para> diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index f364e27..d9bda79 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -703,7 +703,6 @@ This functionality could be invoked as in the following example: import os env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() - </programlisting> @@ -722,7 +721,6 @@ This functionality could be invoked as in the following example: MY_EMITTER = modify2) env1.Foo('file1') env2.Foo('file2') - </programlisting> <para> @@ -781,8 +779,8 @@ This functionality could be invoked as in the following example: <para> - The <filename>site_scons</filename> directory gives you a place to - put Python modules you can import into your &SConscript; files + 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>), @@ -794,11 +792,21 @@ This functionality could be invoked as in the following example: <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, the + 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 file containing two functions, + an &Environment; or a Python module or package containing two functions, <function>exists()</function> and <function>generate()</function>. </para> @@ -848,16 +856,23 @@ This functionality could be invoked as in the following example: --> <para> - Similarly, a more full-fledged tool with + A more full-fledged tool with <function>exists()</function> and <function>generate()</function> - methods can be installed in - <filename>site_scons/site_tools/toolname.py</filename>. 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, site_scons gives you the - hook you need. + 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> @@ -913,13 +928,15 @@ This functionality could be invoked as in the following example: <para> - If you have a machine-wide site dir you'd like to use instead of - <filename>./site_scons</filename>, use the - <literal>--site-dir</literal> option to point to your dir. + 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. + To avoid using a <filename>site_scons</filename> dir at all, + even if it exists, use the <literal>--no-site-dir</literal> + option. </para> diff --git a/doc/user/builders.in b/doc/user/builders.in index 9e9b647..f2bf36d 100644 --- a/doc/user/builders.in +++ b/doc/user/builders.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/builders.xml b/doc/user/builders.xml index 9e9b647..f2bf36d 100644 --- a/doc/user/builders.xml +++ b/doc/user/builders.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/caching.in b/doc/user/caching.in index e5e2742..d60f067 100644 --- a/doc/user/caching.in +++ b/doc/user/caching.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/caching.xml b/doc/user/caching.xml index 5a64e7d..c3dae0a 100644 --- a/doc/user/caching.xml +++ b/doc/user/caching.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/command-line.in b/doc/user/command-line.in index cd5ead6..52a61ac 100644 --- a/doc/user/command-line.in +++ b/doc/user/command-line.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -221,7 +221,7 @@ </para> - <sconstruct) + <sconstruct> if not GetOption('help'): SConscript('src/SConscript', export='env') </sconstruct> @@ -2195,7 +2195,7 @@ Second, the contents of the &DEFAULT_TARGETS; list change - in response to calls to the &Default: function, + in response to calls to the &Default; function, as you can see from the following &SConstruct; file: </para> diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index 8bc72bb..f06442e 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -214,7 +214,10 @@ </para> - <programlisting></programlisting> + <programlisting> + if not GetOption('help'): + SConscript('src/SConscript', export='env') + </programlisting> <para> @@ -1252,7 +1255,7 @@ <screen> % <userinput>scons -Q COLOR=magenta foo.o</userinput> - scons: *** Invalid value for option COLOR: magenta + scons: *** Invalid value for option COLOR: magenta. Valid values are: ('red', 'green', 'blue') File "/home/my/project/SConstruct", line 5, in <module> </screen> @@ -1308,15 +1311,15 @@ <screen> % <userinput>scons -Q COLOR=Red foo.o</userinput> - scons: *** Invalid value for option COLOR: Red + 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 + 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 + scons: *** Invalid value for option COLOR: nAvY. Valid values are: ('red', 'green', 'blue') File "/home/my/project/SConstruct", line 5, in <module> </screen> @@ -2107,7 +2110,7 @@ Second, the contents of the &DEFAULT_TARGETS; list change - in response to calls to the &Default;: function, + in response to calls to the &Default; function, as you can see from the following &SConstruct; file: </para> diff --git a/doc/user/copyright.in b/doc/user/copyright.in index 8b90dbc..19689fe 100644 --- a/doc/user/copyright.in +++ b/doc/user/copyright.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/copyright.xml b/doc/user/copyright.xml index 8b90dbc..19689fe 100644 --- a/doc/user/copyright.xml +++ b/doc/user/copyright.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/depends.in b/doc/user/depends.in index 69bb242..190670c 100644 --- a/doc/user/depends.in +++ b/doc/user/depends.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -386,7 +386,7 @@ <para> - So configured, &SCons will still behave like + So configured, &SCons; will still behave like it does when using <literal>Decider('MD5')</literal>: </para> @@ -487,7 +487,7 @@ 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 done with a custom + This could be done with a custom &Decider; function that might look something like this: </para> @@ -591,6 +591,59 @@ </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 got created and no + <filename>.sconsign</filename> DB file exists yet. + So, it is recommended to 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> @@ -861,7 +914,7 @@ </section> - <section> + <section id="sect-implicit-dependencies"> <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> <para> diff --git a/doc/user/depends.xml b/doc/user/depends.xml index 430e64a..5b19220 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -488,7 +488,7 @@ 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 done with a custom + This could be done with a custom &Decider; function that might look something like this: </para> @@ -587,6 +587,59 @@ </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 got created and no + <filename>.sconsign</filename> DB file exists yet. + So, it is recommended to 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> + + <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> + </section> <section> @@ -850,7 +903,7 @@ </section> - <section> + <section id="sect-implicit-dependencies"> <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> <para> @@ -989,6 +1042,7 @@ 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> </section> diff --git a/doc/user/environments.in b/doc/user/environments.in index 9ce5568..ecfea8a 100644 --- a/doc/user/environments.in +++ b/doc/user/environments.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -347,7 +347,7 @@ environment, of directory names, suffixes, etc. The <literal>external environment</literal> is the set of variables in the user's environment - at the time the user runs &SCons. + 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. @@ -406,7 +406,7 @@ environment, of directory names, suffixes, etc. Unlike &Make;, &SCons; does not automatically copy or import values between different environments - (with the exception of explicit clones of &consenvs, + (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, @@ -638,7 +638,7 @@ environment, of directory names, suffixes, etc. for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']: print "key = %s, value = %s" % (key, dict[key]) </file> - </scons_Example> + </scons_example> <para> @@ -779,18 +779,20 @@ environment, of directory names, suffixes, etc. 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<-' ) + 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 @@ -810,7 +812,7 @@ environment, of directory names, suffixes, etc. <file name="SConstruct" printme="1"> AllowSubstExceptions() env = Environment() - print "value is:", env.subst( '->$MISSING<-' ) + print "value is:", env.subst( '->$MISSING<-' ) </file> </scons_example> @@ -830,7 +832,7 @@ environment, of directory names, suffixes, etc. <file name="SConstruct" printme="1"> AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) env = Environment() - print "value is:", env.subst( '->${1 / 0}<-' ) + print "value is:", env.subst( '->${1 / 0}<-' ) </file> </scons_example> @@ -1093,7 +1095,7 @@ environment, of directory names, suffixes, etc. </section> - <section> + <section id="sect-clone-environments"> <title>Making Copies of &ConsEnvs;: the &Clone; Method</title> <para> diff --git a/doc/user/environments.xml b/doc/user/environments.xml index 5bb1089..81f43a4 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -779,7 +779,8 @@ environment, of directory names, suffixes, etc. 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> + <programlisting> env = Environment() print "value is:", env.subst( '->$MISSING<-' ) @@ -790,7 +791,8 @@ environment, of directory names, suffixes, etc. value is: -><- scons: `.' is up to date. </screen> - + + <para> This default behaviour can be changed using the &AllowSubstExceptions; function. When a problem occurs with a variable expansion it generates @@ -1087,7 +1089,7 @@ environment, of directory names, suffixes, etc. </section> - <section> + <section id="sect-clone-environments"> <title>Making Copies of &ConsEnvs;: the &Clone; Method</title> <para> diff --git a/doc/user/errors.in b/doc/user/errors.in index ad4c2ef..7e33118 100644 --- a/doc/user/errors.in +++ b/doc/user/errors.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/errors.xml b/doc/user/errors.xml index ad4c2ef..7e33118 100644 --- a/doc/user/errors.xml +++ b/doc/user/errors.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/example.in b/doc/user/example.in index ad4c2ef..7e33118 100644 --- a/doc/user/example.in +++ b/doc/user/example.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/example.xml b/doc/user/example.xml index ad4c2ef..7e33118 100644 --- a/doc/user/example.xml +++ b/doc/user/example.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/factories.in b/doc/user/factories.in index c0f524d..da92082 100644 --- a/doc/user/factories.in +++ b/doc/user/factories.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -209,7 +209,7 @@ <para> Of course, like all of these &Action; factories, - the &Delete factory also expands + the &Delete; factory also expands &cv-link-TARGET; and &cv-link-SOURCE; variables appropriately. For example: diff --git a/doc/user/factories.xml b/doc/user/factories.xml index 6a92b0c..7f51c8d 100644 --- a/doc/user/factories.xml +++ b/doc/user/factories.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/file-removal.in b/doc/user/file-removal.in index 1b12d35..b664ba0 100644 --- a/doc/user/file-removal.in +++ b/doc/user/file-removal.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/file-removal.xml b/doc/user/file-removal.xml index 92c1c0d..47b081a 100644 --- a/doc/user/file-removal.xml +++ b/doc/user/file-removal.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/functions.in b/doc/user/functions.in new file mode 100644 index 0000000..7c96c54 --- /dev/null +++ b/doc/user/functions.in @@ -0,0 +1,38 @@ +<!-- + + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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 new file mode 100644 index 0000000..7c96c54 --- /dev/null +++ b/doc/user/functions.xml @@ -0,0 +1,38 @@ +<!-- + + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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/hierarchy.in b/doc/user/hierarchy.in index 16d9389..950bc8a 100644 --- a/doc/user/hierarchy.in +++ b/doc/user/hierarchy.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -478,7 +478,7 @@ make no difference to the build. </section> - <section> + <section id="sect-sharing-environments"> <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title> <para> @@ -688,7 +688,7 @@ make no difference to the build. Sometimes, you would like to be able to use information from a subsidiary - &SConscript file in some way. + &SConscript; file in some way. For example, suppose that you want to create one library from source files diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml index bc4073e..6691e70 100644 --- a/doc/user/hierarchy.xml +++ b/doc/user/hierarchy.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -442,7 +442,7 @@ make no difference to the build. </section> - <section> + <section id="sect-sharing-environments"> <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title> <para> diff --git a/doc/user/install.in b/doc/user/install.in index 8f9498e..131fc6a 100644 --- a/doc/user/install.in +++ b/doc/user/install.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/install.xml b/doc/user/install.xml index f119b00..6b49ae8 100644 --- a/doc/user/install.xml +++ b/doc/user/install.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/java.in b/doc/user/java.in index 290cd43..bad5c34 100644 --- a/doc/user/java.in +++ b/doc/user/java.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -390,7 +390,7 @@ 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. + There are several ways of using the &JavaH; Builder. One typical invocation might look like: </para> @@ -636,7 +636,7 @@ 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: + to &rmic;: </para> diff --git a/doc/user/java.xml b/doc/user/java.xml index a0544f7..f277558 100644 --- a/doc/user/java.xml +++ b/doc/user/java.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/less-simple.in b/doc/user/less-simple.in index cccad83..d717014 100644 --- a/doc/user/less-simple.in +++ b/doc/user/less-simple.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml index 24b45e6..e269490 100644 --- a/doc/user/less-simple.xml +++ b/doc/user/less-simple.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -102,6 +102,7 @@ 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> </section> @@ -193,6 +194,7 @@ 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> </section> diff --git a/doc/user/libraries.in b/doc/user/libraries.in index 5b449e7..a56f2c3 100644 --- a/doc/user/libraries.in +++ b/doc/user/libraries.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/libraries.xml b/doc/user/libraries.xml index 3eed3cc..6909758 100644 --- a/doc/user/libraries.xml +++ b/doc/user/libraries.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -206,6 +206,7 @@ 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> <para> @@ -288,6 +289,7 @@ 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> <para> @@ -412,6 +414,7 @@ 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> <!-- The link command is too wide in the PDF version. There are some other examples of this throughout the document. --> diff --git a/doc/user/main.in b/doc/user/main.in index fbc28df..feb8c25 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -1,7 +1,7 @@ <?xml version="1.0"?> <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -37,6 +37,9 @@ <!ENTITY % builders-mod SYSTEM "builders.mod"> %builders-mod; + <!ENTITY % functions-mod SYSTEM "functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "tools.mod"> %tools-mod; @@ -61,6 +64,7 @@ <!ENTITY example SYSTEM "example.xml"> <!ENTITY factories SYSTEM "factories.xml"> <!ENTITY file-removal SYSTEM "file-removal.xml"> + <!ENTITY functions SYSTEM "functions.xml"> <!ENTITY hierarchy SYSTEM "hierarchy.xml"> <!ENTITY java SYSTEM "java.xml"> <!ENTITY install SYSTEM "install.xml"> @@ -89,6 +93,7 @@ <!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"> @@ -177,18 +182,35 @@ &environments; </chapter> - <!-- These next three sections should be combined into one chapter --> - <chapter id="chap-mergeflags"> - <title>Merging Options into the Environment: the &MergeFlags; Function</title> - &mergeflags; - </chapter> - <chapter id="chap-parseflags"> - <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title> - &parseflags; - </chapter> - <chapter id="chap-parseconfig"> - <title>Finding Installed Library Information: the &ParseConfig; Function</title> - &parseconfig; + <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"> @@ -341,6 +363,11 @@ &tools; </appendix> + <appendix id="app-functions"> + <title>Functions and Environment Methods</title> + &functions; + </appendix> + <appendix id="app-tasks"> <title>Handling Common Tasks</title> &tasks; diff --git a/doc/user/main.xml b/doc/user/main.xml index fbc28df..feb8c25 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 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -37,6 +37,9 @@ <!ENTITY % builders-mod SYSTEM "builders.mod"> %builders-mod; + <!ENTITY % functions-mod SYSTEM "functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "tools.mod"> %tools-mod; @@ -61,6 +64,7 @@ <!ENTITY example SYSTEM "example.xml"> <!ENTITY factories SYSTEM "factories.xml"> <!ENTITY file-removal SYSTEM "file-removal.xml"> + <!ENTITY functions SYSTEM "functions.xml"> <!ENTITY hierarchy SYSTEM "hierarchy.xml"> <!ENTITY java SYSTEM "java.xml"> <!ENTITY install SYSTEM "install.xml"> @@ -89,6 +93,7 @@ <!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"> @@ -177,18 +182,35 @@ &environments; </chapter> - <!-- These next three sections should be combined into one chapter --> - <chapter id="chap-mergeflags"> - <title>Merging Options into the Environment: the &MergeFlags; Function</title> - &mergeflags; - </chapter> - <chapter id="chap-parseflags"> - <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title> - &parseflags; - </chapter> - <chapter id="chap-parseconfig"> - <title>Finding Installed Library Information: the &ParseConfig; Function</title> - &parseconfig; + <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"> @@ -341,6 +363,11 @@ &tools; </appendix> + <appendix id="app-functions"> + <title>Functions and Environment Methods</title> + &functions; + </appendix> + <appendix id="app-tasks"> <title>Handling Common Tasks</title> &tasks; diff --git a/doc/user/make.in b/doc/user/make.in index c17b047..7102557 100644 --- a/doc/user/make.in +++ b/doc/user/make.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/make.xml b/doc/user/make.xml index c17b047..7102557 100644 --- a/doc/user/make.xml +++ b/doc/user/make.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/mergeflags.in b/doc/user/mergeflags.in index 58d437c..086d042 100644 --- a/doc/user/mergeflags.in +++ b/doc/user/mergeflags.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/mergeflags.xml b/doc/user/mergeflags.xml index ab10e54..f0bc2b6 100644 --- a/doc/user/mergeflags.xml +++ b/doc/user/mergeflags.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/misc.in b/doc/user/misc.in index 87b5db4..fef1b8f 100644 --- a/doc/user/misc.in +++ b/doc/user/misc.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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,7 +36,7 @@ <para> Although the &SCons; code itself will run - on any Python version 2.4 or later, + 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) @@ -82,7 +82,7 @@ <para> - And then &SCons will exit with the following error + And then &SCons; will exit with the following error message when a user runs it with an unsupported earlier version of Python: @@ -151,7 +151,7 @@ <para> - And then &SCons will exit with the following error + And then &SCons; will exit with the following error message when a user runs it with an unsupported earlier version of &SCons;: @@ -274,13 +274,13 @@ </file> <directory name="src"></directory> <directory name="src/include"></directory> - </file> <file name="src/include/private.h"> exists - <directory name="include"></directory> </file> + <directory name="include"></directory> <file name="include/dist.h"> exists + </file> </scons_example> <scons_output example="FindFile1b" os="posix"> diff --git a/doc/user/misc.xml b/doc/user/misc.xml index f79f1cc..069f94b 100644 --- a/doc/user/misc.xml +++ b/doc/user/misc.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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,7 +36,7 @@ <para> Although the &SCons; code itself will run - on any Python version 2.4 or later, + 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) @@ -263,7 +263,7 @@ headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] for hdr in headers: print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes) -</programlisting> + </programlisting> <screen> % <userinput>scons -Q</userinput> diff --git a/doc/user/nodes.in b/doc/user/nodes.in index c65a2ad..7799d3f 100644 --- a/doc/user/nodes.in +++ b/doc/user/nodes.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml index 71ac7c1..fe8e167 100644 --- a/doc/user/nodes.xml +++ b/doc/user/nodes.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -131,6 +131,7 @@ 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> <para> @@ -275,6 +276,7 @@ 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> <para> diff --git a/doc/user/output.in b/doc/user/output.in index e456026..d2823d0 100644 --- a/doc/user/output.in +++ b/doc/user/output.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -490,7 +490,7 @@ over how to print each evaluated node by passing a Python function (or other Python callable) - to the &Progress function. + to the &Progress; function. Your function will be called for each evaluated node, allowing you to diff --git a/doc/user/output.xml b/doc/user/output.xml index 297e6f8..6910b59 100644 --- a/doc/user/output.xml +++ b/doc/user/output.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/parseconfig.in b/doc/user/parseconfig.in index 667601f..5eb990c 100644 --- a/doc/user/parseconfig.in +++ b/doc/user/parseconfig.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/parseconfig.xml b/doc/user/parseconfig.xml index 534ea3d..409abfe 100644 --- a/doc/user/parseconfig.xml +++ b/doc/user/parseconfig.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/parseflags.in b/doc/user/parseflags.in index 2f4bea5..6e72c18 100644 --- a/doc/user/parseflags.in +++ b/doc/user/parseflags.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml index fd15de7..7350831 100644 --- a/doc/user/parseflags.xml +++ b/doc/user/parseflags.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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,6 +91,7 @@ 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> <para> diff --git a/doc/user/preface.in b/doc/user/preface.in index a60beab..e82ee3b 100644 --- a/doc/user/preface.in +++ b/doc/user/preface.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -104,7 +104,7 @@ <para> There are a few overriding principles - we try to live up to in designing and implementing &SCons: + we try to live up to in designing and implementing &SCons;: </para> @@ -418,7 +418,7 @@ <para> - If you want to receive announcements about &SCons, + If you want to receive announcements about &SCons;, join the low-volume &scons-announce; mailing list. </para> diff --git a/doc/user/preface.xml b/doc/user/preface.xml index db2031d..e82ee3b 100644 --- a/doc/user/preface.xml +++ b/doc/user/preface.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/python.in b/doc/user/python.in index 18679e4..c3ea5fe 100644 --- a/doc/user/python.in +++ b/doc/user/python.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/python.xml b/doc/user/python.xml index 18679e4..c3ea5fe 100644 --- a/doc/user/python.xml +++ b/doc/user/python.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/repositories.in b/doc/user/repositories.in index 531aa8a..5ba9090 100644 --- a/doc/user/repositories.in +++ b/doc/user/repositories.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -210,9 +210,9 @@ 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; + our previous example includes the &hello_h; in its current directory, - and the &hello.h; only exists in the repository: + and the &hello_h; only exists in the repository: </para> diff --git a/doc/user/repositories.xml b/doc/user/repositories.xml index 6400b23..219dbaf 100644 --- a/doc/user/repositories.xml +++ b/doc/user/repositories.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -193,9 +193,9 @@ 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; + our previous example includes the &hello_h; in its current directory, - and the &hello;.h; only exists in the repository: + and the &hello_h; only exists in the repository: </para> diff --git a/doc/user/run.in b/doc/user/run.in index 761f37c..8d47b27 100644 --- a/doc/user/run.in +++ b/doc/user/run.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/run.xml b/doc/user/run.xml index 761f37c..8d47b27 100644 --- a/doc/user/run.xml +++ b/doc/user/run.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/scanners.in b/doc/user/scanners.in index db3170a..e8bdff7 100644 --- a/doc/user/scanners.in +++ b/doc/user/scanners.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -171,10 +171,21 @@ over the file scanning rather than being called for each input line: def kfile_scan(node, env, path, arg): contents = node.get_text_contents() - return include_re.findall(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 @@ -283,7 +294,7 @@ over the file scanning rather than being called for each input line: def kfile_scan(node, env, path): contents = node.get_text_contents() includes = include_re.findall(contents) - return includes + return env.File(includes) kscan = Scanner(function = kfile_scan, skeys = ['.k']) diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml index 2aba7d2..7862265 100644 --- a/doc/user/scanners.xml +++ b/doc/user/scanners.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -171,10 +171,21 @@ over the file scanning rather than being called for each input line: def kfile_scan(node, env, path, arg): contents = node.get_text_contents() - return include_re.findall(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 @@ -282,7 +293,7 @@ over the file scanning rather than being called for each input line: def kfile_scan(node, env, path): contents = node.get_text_contents() includes = include_re.findall(contents) - return includes + return env.File(includes) kscan = Scanner(function = kfile_scan, skeys = ['.k']) diff --git a/doc/user/sconf.in b/doc/user/sconf.in index 94a455e..52fe132 100644 --- a/doc/user/sconf.in +++ b/doc/user/sconf.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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,7 +31,7 @@ figuring out what libraries or header files are available on the local system. This section describes how to use - this &SCons feature. + this &SCons; feature. </para> @@ -446,7 +446,7 @@ when removing targets doesn't hurt anything, it's usually unnecessary. You can avoid this by using the - &GetOption(); method to + &GetOption; method to check whether the <option>-c</option> (clean) option has been invoked on the command line: diff --git a/doc/user/sconf.xml b/doc/user/sconf.xml index 35f4367..460c3d1 100644 --- a/doc/user/sconf.xml +++ b/doc/user/sconf.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -446,7 +446,7 @@ when removing targets doesn't hurt anything, it's usually unnecessary. You can avoid this by using the - &GetOption;(); method to + &GetOption; method to check whether the <option>-c</option> (clean) option has been invoked on the command line: diff --git a/doc/user/separate.in b/doc/user/separate.in index 8c08cbe..932c285 100644 --- a/doc/user/separate.in +++ b/doc/user/separate.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/separate.xml b/doc/user/separate.xml index 2c6f97b..7df53e9 100644 --- a/doc/user/separate.xml +++ b/doc/user/separate.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/sideeffect.in b/doc/user/sideeffect.in index 3356d6c..852f99a 100644 --- a/doc/user/sideeffect.in +++ b/doc/user/sideeffect.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/sideeffect.xml b/doc/user/sideeffect.xml index f6055f3..35e026f 100644 --- a/doc/user/sideeffect.xml +++ b/doc/user/sideeffect.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/simple.in b/doc/user/simple.in index b4802f8..0d15f12 100644 --- a/doc/user/simple.in +++ b/doc/user/simple.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -297,7 +297,7 @@ </section> - <section> + <section id="sect-sconstruct-file"> <title>The &SConstruct; File</title> <para> @@ -353,14 +353,14 @@ </section> - <section> + <section id="sect-order-independent"> <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, + and is more like a &Makefile;, is that the order in which the &SCons; functions are called in the &SConstruct; file @@ -453,7 +453,7 @@ <para> Notice also that &SCons; built the &goodbye; program first, - even though the "reading &SConscript" output + even though the "reading &SConscript;" output shows that we called <literal>Program('hello.c')</literal> first in the &SConstruct; file. diff --git a/doc/user/simple.xml b/doc/user/simple.xml index 54f6b56..49b8805 100644 --- a/doc/user/simple.xml +++ b/doc/user/simple.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -110,6 +110,7 @@ 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> @@ -300,6 +301,7 @@ 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 ... @@ -320,7 +322,7 @@ </section> - <section> + <section id="sect-sconstruct-file"> <title>The &SConstruct; File</title> <para> @@ -376,7 +378,7 @@ </section> - <section> + <section id="sect-order-independent"> <title>&SCons; Functions Are Order-Independent</title> <para> @@ -507,6 +509,7 @@ 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> @@ -536,6 +539,7 @@ C:\><userinput>scons -Q</userinput> cl /Fohello.obj /c hello.c /nologo link /nologo /OUT:hello.exe hello.obj + embedManifestExeCheck(target, source, env) </screen> <para> diff --git a/doc/user/sourcecode.in b/doc/user/sourcecode.in index 5a9637e..e4fc5be 100644 --- a/doc/user/sourcecode.in +++ b/doc/user/sourcecode.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/sourcecode.xml b/doc/user/sourcecode.xml index 73c2490..6642d0f 100644 --- a/doc/user/sourcecode.xml +++ b/doc/user/sourcecode.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/tasks.in b/doc/user/tasks.in index 8842dcd..aa6a12e 100644 --- a/doc/user/tasks.in +++ b/doc/user/tasks.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -99,14 +99,14 @@ 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. diff --git a/doc/user/tasks.xml b/doc/user/tasks.xml index 2b2eb0b..ada4de5 100644 --- a/doc/user/tasks.xml +++ b/doc/user/tasks.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/tools.in b/doc/user/tools.in index 16228e7..9dd71df 100644 --- a/doc/user/tools.in +++ b/doc/user/tools.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/tools.xml b/doc/user/tools.xml index 16228e7..9dd71df 100644 --- a/doc/user/tools.xml +++ b/doc/user/tools.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/troubleshoot.in b/doc/user/troubleshoot.in index 97df351..615d677 100644 --- a/doc/user/troubleshoot.in +++ b/doc/user/troubleshoot.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 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,7 +34,7 @@ &SCons; is no different. This appendix contains a number of different ways in which you can - get some additional insight into &SCons' behavior. + get some additional insight into &SCons;' behavior. </para> @@ -410,12 +410,12 @@ <para> - The <literaL>--tree</literal> option only prints + 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 + the <literal>--tree</literal> option will only print the dependency graph for that file: </para> @@ -722,7 +722,7 @@ <para> - For example, the following &SConstruct file: + For example, the following &SConstruct; file: </para> @@ -842,8 +842,47 @@ </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> diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml index 468af92..1f32a35 100644 --- a/doc/user/troubleshoot.xml +++ b/doc/user/troubleshoot.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -282,7 +282,8 @@ '.mm', '.S', '.spp', - '.SPP'], + '.SPP', + '.sx'], 'DSUFFIXES': ['.d'], 'Dir': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, 'Dirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, @@ -345,7 +346,7 @@ 'CC': 'cl', 'CCCOM': <SCons.Action.FunctionAction object at 0x700000>, 'CCFLAGS': ['/nologo'], - 'CCPCHFLAGS': ['${(PCH and "/Yu%s /Fp%s"%(PCHSTOP or "",File(PCH))) or ""}'], + 'CCPCHFLAGS': ['${(PCH and "/Yu%s \\"/Fp%s\\""%(PCHSTOP or "",File(PCH))) or ""}'], 'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'], 'CFILESUFFIX': '.c', 'CFLAGS': [], @@ -371,9 +372,10 @@ '.mm', '.S', '.spp', - '.SPP'], + '.SPP', + '.sx'], 'CXX': '$CC', - 'CXXCOM': '$CXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $CXXFLAGS $CCFLAGS $_CCCOMCOM', + 'CXXCOM': '${TEMPFILE("$CXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $CXXFLAGS $CCFLAGS $_CCCOMCOM")}', 'CXXFILESUFFIX': '.cc', 'CXXFLAGS': ['$(', '/TP', '$)'], 'DSUFFIXES': ['.d'], @@ -415,7 +417,7 @@ 'SHCCFLAGS': ['$CCFLAGS'], 'SHCFLAGS': ['$CFLAGS'], 'SHCXX': '$CXX', - 'SHCXXCOM': '$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM', + 'SHCXXCOM': '${TEMPFILE("$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM")}', 'SHCXXFLAGS': ['$CXXFLAGS'], 'SHELL': None, 'SHLIBPREFIX': '', @@ -1120,9 +1122,9 @@ 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 167, in 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 187, in prepare + 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])) @@ -1260,8 +1262,47 @@ </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> diff --git a/doc/user/variables.in b/doc/user/variables.in index bf8be1b..9b8afc1 100644 --- a/doc/user/variables.in +++ b/doc/user/variables.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/variables.xml b/doc/user/variables.xml index bf8be1b..9b8afc1 100644 --- a/doc/user/variables.xml +++ b/doc/user/variables.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/variants.in b/doc/user/variants.in index d94e3f3..5050306 100644 --- a/doc/user/variants.in +++ b/doc/user/variants.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/variants.xml b/doc/user/variants.xml index bca84c8..e096eed 100644 --- a/doc/user/variants.xml +++ b/doc/user/variants.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -114,6 +114,7 @@ is pretty smart about rebuilding things when you change options. 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> |