diff --git a/doc/SConscript b/doc/SConscript
index 5f3d559a9c..28d1807727 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -574,7 +574,7 @@ else:
e = os.path.join('#src', 'engine')
manifest_in = File(os.path.join(e, 'MANIFEST.in')).rstr()
sources = bootstrap.parseManifestLines(e, open(manifest_in).readlines())
- sources = [x for x in sources if x.find('Platform') == -1]
+# sources = [x for x in sources if x.find('Platform') == -1]
sources = [x for x in sources if x.find('Tool') == -1]
# XXX
sources = [x for x in sources if x.find('Options') == -1]
diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen
index 680f72f655..6f8c7e9cdf 100644
--- a/doc/generated/builders.gen
+++ b/doc/generated/builders.gen
@@ -1,4 +1,4 @@
-
+
%scons;
@@ -12,7 +12,7 @@
%variables-mod;
]>
-
+CFile()
@@ -20,18 +20,17 @@
env.CFile()
-
-
+
Builds a C source file given a lex (.l)
or yacc (.y) input file.
-The suffix specified by the $CFILESUFFIX construction variable
+The suffix specified by the $CFILESUFFIX construction variable
(.c by default)
is automatically added to the target
if it is not already present.
Example:
-
+
# builds foo.c
env.CFile(target = 'foo.c', source = 'foo.l')
# builds bar.c
@@ -46,13 +45,12 @@ env.CFile(target = 'bar', source = 'bar.y')
env.Command()
-
-
-The Command "Builder" is actually implemented
+
+The Command "Builder" is actually implemented
as a function that looks like a Builder,
but actually takes an additional argument of the action
from which the Builder should be made.
-See the Command function description
+See the Command function description
for the calling syntax and details.
@@ -64,19 +62,18 @@ for the calling syntax and details.
env.CXXFile()
-
-
+
Builds a C++ source file given a lex (.ll)
or yacc (.yy)
input file.
-The suffix specified by the $CXXFILESUFFIX construction variable
+The suffix specified by the $CXXFILESUFFIX construction variable
(.cc by default)
is automatically added to the target
if it is not already present.
Example:
-
+
# builds foo.cc
env.CXXFile(target = 'foo.cc', source = 'foo.ll')
# builds bar.cc
@@ -91,20 +88,19 @@ env.CXXFile(target = 'bar', source = 'bar.yy')
env.DocbookEpub()
-
-
+
A pseudo-Builder, providing a Docbook toolchain for EPUB output.
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookEpub('manual.epub', 'manual.xml')
-
+
or simply
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookEpub('manual')
@@ -117,17 +113,16 @@ env.DocbookEpub('manual')
env.DocbookHtml()
-
-
+
A pseudo-Builder, providing a Docbook toolchain for HTML output.
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookHtml('manual.html', 'manual.xml')
-
+
or simply
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookHtml('manual')
@@ -139,35 +134,34 @@ env.DocbookHtml('manual')
env.DocbookHtmlChunked()
-
-
+
A pseudo-Builder, providing a Docbook toolchain for chunked HTML output.
It supports the base.dir parameter. The
chunkfast.xsl file (requires "EXSLT") is used as the
default stylesheet. Basic syntax:
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookHtmlChunked('manual')
-
+
where manual.xml is the input file.
-If you use the root.filename
+If you use the root.filename
parameter in your own stylesheets you have to specify the new target name.
This ensures that the dependencies get correct, especially for the cleanup via scons -c:
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookHtmlChunked('mymanual.html', 'manual', xsl='htmlchunk.xsl')
-Some basic support for the base.dir is provided. You
+Some basic support for the base.dir is provided. You
can add the base_dir keyword to your Builder
call, and the given prefix gets prepended to all the created filenames:
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookHtmlChunked('manual', xsl='htmlchunk.xsl', base_dir='output/')
-Make sure that you don't forget the trailing slash for the base folder, else
+Make sure that you don't forget the trailing slash for the base folder, else
your files get renamed only!
@@ -179,35 +173,34 @@ your files get renamed only!
env.DocbookHtmlhelp()
-
-
+
A pseudo-Builder, providing a Docbook toolchain for HTMLHELP output.
Its basic syntax is:
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookHtmlhelp('manual')
-
+
where manual.xml is the input file.
-If you use the root.filename
+If you use the root.filename
parameter in your own stylesheets you have to specify the new target name.
This ensures that the dependencies get correct, especially for the cleanup via scons -c:
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookHtmlhelp('mymanual.html', 'manual', xsl='htmlhelp.xsl')
-Some basic support for the base.dir parameter
+Some basic support for the base.dir parameter
is provided. You can add the base_dir keyword to
your Builder call, and the given prefix gets prepended to all the
created filenames:
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/')
-Make sure that you don't forget the trailing slash for the base folder, else
+Make sure that you don't forget the trailing slash for the base folder, else
your files get renamed only!
@@ -220,16 +213,15 @@ your files get renamed only!
env.DocbookMan()
-
-
+
A pseudo-Builder, providing a Docbook toolchain for Man page output.
Its basic syntax is:
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookMan('manual')
-
+
where manual.xml is the input file. Note, that
you can specify a target name, but the actual output names are automatically
set from the refname entries in your XML source.
@@ -243,20 +235,19 @@ set from the refname entries in your XML source.
env.DocbookPdf()
-
-
+
A pseudo-Builder, providing a Docbook toolchain for PDF output.
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookPdf('manual.pdf', 'manual.xml')
-
+
or simply
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookPdf('manual')
@@ -269,33 +260,32 @@ env.DocbookPdf('manual')
env.DocbookSlidesHtml()
-
-
+
A pseudo-Builder, providing a Docbook toolchain for HTML slides output.
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookSlidesHtml('manual')
-If you use the titlefoil.html parameter in
+If you use the titlefoil.html parameter in
your own stylesheets you have to give the new target name. This ensures
that the dependencies get correct, especially for the cleanup via
scons -c:
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookSlidesHtml('mymanual.html','manual', xsl='slideshtml.xsl')
-Some basic support for the base.dir parameter
+Some basic support for the base.dir parameter
is provided. You
can add the base_dir keyword to your Builder
call, and the given prefix gets prepended to all the created filenames:
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookSlidesHtml('manual', xsl='slideshtml.xsl', base_dir='output/')
-Make sure that you don't forget the trailing slash for the base folder, else
+Make sure that you don't forget the trailing slash for the base folder, else
your files get renamed only!
@@ -308,20 +298,19 @@ your files get renamed only!
env.DocbookSlidesPdf()
-
-
+
A pseudo-Builder, providing a Docbook toolchain for PDF slides output.
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookSlidesPdf('manual.pdf', 'manual.xml')
-
+
or simply
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookSlidesPdf('manual')
@@ -333,12 +322,11 @@ env.DocbookSlidesPdf('manual')
env.DocbookXInclude()
-
-
+
A pseudo-Builder, for resolving XIncludes in a separate processing step.
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')
@@ -350,16 +338,15 @@ env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')
env.DocbookXslt()
-
-
+
A pseudo-Builder, applying a given XSL transformation to the input file.
-env = Environment(tools=['docbook'])
+env = Environment(tools=['docbook'])
env.DocbookXslt('manual_transformed.xml', 'manual.xml', xsl='transform.xslt')
-Note, that this builder requires the xsl parameter
+Note, that this builder requires the xsl parameter
to be set.
@@ -371,41 +358,40 @@ to be set.
env.DVI()
-
-
+
Builds a .dvi file
from a .tex,
.ltx or .latex input file.
If the source file suffix is .tex,
-scons
+scons
will examine the contents of the file;
if the string
\documentclass
or
\documentstyle
is found, the file is assumed to be a LaTeX file and
-the target is built by invoking the $LATEXCOM command line;
-otherwise, the $TEXCOM command line is used.
+the target is built by invoking the $LATEXCOM command line;
+otherwise, the $TEXCOM command line is used.
If the file is a LaTeX file,
the
-DVI
+DVI
builder method will also examine the contents
of the
.aux
-file and invoke the $BIBTEX command line
+file and invoke the $BIBTEX command line
if the string
bibdata
is found,
-start $MAKEINDEX to generate an index if a
+start $MAKEINDEX to generate an index if a
.ind
file is found
and will examine the contents
.log
-file and re-run the $LATEXCOM command
+file and re-run the $LATEXCOM command
if the log file says it is necessary.
-
+
The suffix .dvi
(hard-coded within TeX itself)
is automatically added to the target
@@ -413,7 +399,7 @@ if it is not already present.
Examples:
-
+
# builds from aaa.tex
env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
# builds bbb.dvi
@@ -430,14 +416,13 @@ env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
env.Gs()
-
-
+
A Builder for explicitly calling the gs executable.
Depending on the underlying OS, the different names gs,
gsos2 and gswin32c
are tried.
-env = Environment(tools=['gs'])
+env = Environment(tools=['gs'])
env.Gs('cover.jpg','scons-scons.pdf',
GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -q')
)
@@ -451,8 +436,7 @@ env.Gs('cover.jpg','scons-scons.pdf',
env.Install()
-
-
+
Installs one or more source files or directories
in the specified target,
which must be a directory.
@@ -462,7 +446,7 @@ sources may be given as a string or as a node returned by
a builder.
-
+
env.Install('/usr/local/bin', source = ['foo', 'bar'])
@@ -474,8 +458,7 @@ env.Install('/usr/local/bin', source = ['foo', 'bar'])
env.InstallAs()
-
-
+
Installs one or more source files or directories
to specific names,
allowing changing a file or directory name
@@ -487,7 +470,7 @@ source
arguments list different numbers of files or directories.
-
+
env.InstallAs(target = '/usr/local/bin/foo',
source = 'foo_debug')
env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
@@ -503,13 +486,12 @@ env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
env.InstallVersionedLib()
-
-
+
Installs a versioned shared library. The symlinks appropriate to the
architecture will be generated based on symlinks of the source library.
-
+
env.InstallVersionedLib(target = '/usr/local/bin/foo',
source = 'libxyz.1.5.2.so')
@@ -522,41 +504,40 @@ env.InstallVersionedLib(target = '/usr/local/bin/foo',
env.Jar()
-
-
+
Builds a Java archive (.jar) file
from the specified list of sources.
Any directories in the source list
will be searched for .class files).
Any .java files in the source list
will be compiled to .class files
-by calling the Java Builder.
+by calling the Java Builder.
-
-If the $JARCHDIR value is set, the
-jar
+
+If the $JARCHDIR value is set, the
+jar
command will change to the specified directory using the
option.
-If $JARCHDIR is not set explicitly,
-SCons will use the top of any subdirectory tree
+If $JARCHDIR is not set explicitly,
+SCons will use the top of any subdirectory tree
in which Java .class
-were built by the Java Builder.
+were built by the Java Builder.
-
+
If the contents any of the source files begin with the string
Manifest-Version,
the file is assumed to be a manifest
and is passed to the
-jar
+jar
command with the
option set.
-
+
env.Jar(target = 'foo.jar', source = 'classes')
env.Jar(target = 'bar.jar',
@@ -571,8 +552,7 @@ env.Jar(target = 'bar.jar',
env.Java()
-
-
+
Builds one or more Java class files.
The sources may be any combination of explicit
.java
@@ -581,7 +561,7 @@ env.Jar(target = 'bar.jar',
for .java files.
-
+
SCons will parse each source .java file
to find the classes
(including inner classes)
@@ -592,7 +572,7 @@ env.Jar(target = 'bar.jar',
the specified target directory.
-
+
SCons will also search each Java file
for the Java package name,
which it assumes can be found on a line
@@ -615,17 +595,17 @@ env.Jar(target = 'bar.jar',
class file.
-
+
Examples:
-
+
env.Java(target = 'classes', source = 'src')
env.Java(target = 'classes', source = ['src1', 'src2'])
env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
-
+
Java source files can use the native encoding for the underlying OS.
Since SCons compiles in simple ASCII mode by default,
the compiler will generate warnings about unmappable characters,
@@ -638,7 +618,7 @@ env.Jar(target = 'bar.jar',
with a different encoding.
-
+
env = Environment()
env['ENV']['LANG'] = 'en_GB.UTF-8'
@@ -651,8 +631,7 @@ env.Jar(target = 'bar.jar',
env.JavaH()
-
-
+
Builds C header and source files for
implementing Java native methods.
The target can be either a directory
@@ -662,29 +641,29 @@ will contain all of the definitions.
The source can be the names of .class files,
the names of .java files
to be compiled into .class files
-by calling the Java builder method,
+by calling the Java builder method,
or the objects returned from the
-Java
+Java
builder method.
-
+
If the construction variable
-$JAVACLASSDIR
+$JAVACLASSDIR
is set, either in the environment
or in the call to the
-JavaH
+JavaH
builder method itself,
then the value of the variable
will be stripped from the
beginning of any .class file names.
-
+
Examples:
-
+
# builds java_native.h
classes = env.Java(target = 'classdir', source = 'src')
env.JavaH(target = 'java_native.h', source = classes)
@@ -707,10 +686,9 @@ env.JavaH(target = 'export',
env.Library()
-
-
+
A synonym for the
-StaticLibrary
+StaticLibrary
builder method.
@@ -722,11 +700,10 @@ builder method.
env.LoadableModule()
-
-
+
On most systems,
this is the same as
-SharedLibrary.
+SharedLibrary.
On Mac OS X (Darwin) platforms,
this creates a loadable module bundle.
@@ -739,10 +716,9 @@ this creates a loadable module bundle.
env.M4()
-
-
+
Builds an output file from an M4 input file.
-This uses a default $M4FLAGS value of
+This uses a default $M4FLAGS value of
,
which considers all warnings to be fatal
and stops on the first warning
@@ -750,7 +726,7 @@ when using the GNU version of m4.
Example:
-
+
env.M4(target = 'foo.c', source = 'foo.c.m4')
@@ -762,15 +738,14 @@ env.M4(target = 'foo.c', source = 'foo.c.m4')
env.Moc()
-
-
+
Builds an output file from a moc input file. Moc input files are either
header files or cxx files. This builder is only available after using the
-tool 'qt'. See the $QTDIR variable for more information.
+tool 'qt'. See the $QTDIR variable for more information.
Example:
-
+
env.Moc('foo.h') # generates moc_foo.cc
env.Moc('foo.cpp') # generates foo.moc
@@ -783,48 +758,47 @@ env.Moc('foo.cpp') # generates foo.moc
env.MOFiles()
-
-
-This builder belongs to msgfmt tool. The builder compiles
+
+This builder belongs to msgfmt tool. The builder compiles
PO files to MO files.
-
+Example 1.
Create pl.mo and en.mo by compiling
pl.po and en.po:
-
+
# ...
env.MOFiles(['pl', 'en'])
-
+Example 2.
Compile files for languages defined in LINGUAS file:
-
+
# ...
env.MOFiles(LINGUAS_FILE = 1)
-
+Example 3.
Create pl.mo and en.mo by compiling
pl.po and en.po plus files for
languages defined in LINGUAS file:
-
+
# ...
env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1)
-
+Example 4.
Compile files for languages defined in LINGUAS file
(another version):
-
+
# ...
env['LINGUAS_FILE'] = 1
env.MOFiles()
@@ -838,39 +812,39 @@ Compile files for languages defined in LINGUAS file
env.MSVSProject()
- Builds a Microsoft Visual Studio project
-file, and by default builds a solution file as well. This
+ Builds a Microsoft Visual Studio project
+file, and by default builds a solution file as well. This
builds a Visual Studio project file, based on the version of Visual Studio
that is configured (either the latest installed version, or the version
-specified by $MSVS_VERSION in the Environment constructor). For
+specified by $MSVS_VERSION in the Environment constructor). For
Visual Studio 6, it will generate a .dsp file. For Visual
Studio 7 (.NET) and later versions, it will generate a
-.vcproj file. By default, this also
+.vcproj file. By default, this also
generates a solution file for the specified project, a
.dsw file for Visual Studio 6 or a
.sln file for Visual Studio 7 (.NET). This behavior may
be disabled by specifying auto_build_solution=0 when you
-call MSVSProject, in which case you presumably want to build the solution
-file(s) by calling the MSVSSolution Builder (see below).
-The MSVSProject builder takes several lists of filenames to be placed into
+call MSVSProject, in which case you presumably want to build the solution
+file(s) by calling the MSVSSolution Builder (see below).
+The MSVSProject builder takes several lists of filenames to be placed into
the project file. These are currently limited to srcs,
incs, localincs,
resources, and misc. These are pretty
self-explanatory, but it should be noted that these lists are added to the
-$SOURCES construction variable as strings, NOT as SCons File Nodes.
+$SOURCES construction variable as strings, NOT as SCons File Nodes.
This is because they represent file names to be added to the project file, not
-the source files used to build the project file. The above
+the source files used to build the project file. The above
filename lists are all optional, although at least one must be specified for
-the resulting project file to be non-empty. In addition to the
+the resulting project file to be non-empty. In addition to the
above lists of values, the following values may be specified:
-
+targetThe name of the target .dsp or
.vcproj file. The correct suffix for the version
- of Visual Studio must be used, but the $MSVSPROJECTSUFFIX
+ of Visual Studio must be used, but the $MSVSPROJECTSUFFIX
construction variable will be defined to the correct value (see
example below).
@@ -886,7 +860,7 @@ above lists of values, the following values may be specified:
you want. For Visual Studio 7 projects, they may also specify a target
platform separated from the variant name by a |
(vertical pipe) character: Debug|Xbox. The default
- target platform is Win32. Multiple calls to MSVSProject with
+ target platform is Win32. Multiple calls to MSVSProject with
different variants are allowed; all variants will be added to the
project file with their appropriate build targets and
sources.
@@ -928,16 +902,16 @@ above lists of values, the following values may be specified:
specified buildtarget value.
- Note that because SCons always executes its build
-commands from the directory in which the SConstruct file is located, if you
-generate a project file in a different directory than the SConstruct
+ Note that because SCons always executes its build
+commands from the directory in which the SConstruct file is located, if you
+generate a project file in a different directory than the SConstruct
directory, users will not be able to double-click on the file name in
compilation error messages displayed in the Visual Studio console output
window. This can be remedied by adding the Visual C/C++ /FC
-compiler option to the $CCFLAGS variable so that the compiler will
+compiler option to the $CCFLAGS variable so that the compiler will
print the full path name of any files that cause compilation errors.
- Example usage:
-
+ Example usage:
+
barsrcs = ['bar.cpp']
barincs = ['bar.h']
barlocalincs = ['StdAfx.h']
@@ -956,10 +930,10 @@ env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
buildtarget = buildtarget,
variant = 'Release')
-Starting with version 2.4 of
+Starting with version 2.4 of
SCons it's also possible to specify the optional argument
DebugSettings, which creates files for debugging under
-Visual Studio:
+Visual Studio:DebugSettings
@@ -972,14 +946,14 @@ Visual Studio:
give only one, it will be propagated to all variants.
- Currently, only Visual Studio v9.0 and Visual Studio
+ Currently, only Visual Studio v9.0 and Visual Studio
version v11 are implemented, for other versions no file is generated. To
generate the user file, you just need to add a
DebugSettings dictionary to the environment with the
right parameters for your MSVS version. If the dictionary is empty, or does
-not contain any good value, no file will be generated.Following
+not contain any good value, no file will be generated.Following
is a more contrived example, involving the setup of a project for variants and
-DebugSettings:# Assuming you store your defaults in a file
+DebugSettings:# Assuming you store your defaults in a file
vars = Variables('variables.py')
msvcver = vars.args.get('vc', '9')
@@ -1101,21 +1075,21 @@ env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
env.MSVSSolution()
- Builds a Microsoft Visual Studio solution
-file. This builds a Visual Studio solution file, based on the
+ Builds a Microsoft Visual Studio solution
+file. This builds a Visual Studio solution file, based on the
version of Visual Studio that is configured (either the latest installed
-version, or the version specified by $MSVS_VERSION in the
+version, or the version specified by $MSVS_VERSION in the
construction environment). For Visual Studio 6, it will generate a
.dsw file. For Visual Studio 7 (.NET), it will generate a
-.sln file. The following values must be
-specified:
+.sln file. The following values must be
+specified: targetThe name of the target .dsw or .sln file. The correct
suffix for the version of Visual Studio must be used, but the value
- $MSVSSOLUTIONSUFFIX will be defined to the correct value (see
+ $MSVSSOLUTIONSUFFIX will be defined to the correct value (see
example below).
@@ -1137,7 +1111,7 @@ specified: A list of project file names, or Project nodes returned by
- calls to the MSVSProject Builder, to be placed into the solution
+ calls to the MSVSProject Builder, to be placed into the solution
file. It should be noted that these file names are NOT added to the
$SOURCES environment variable in form of files, but rather as strings.
This is because they represent file names to be added to the solution
@@ -1145,7 +1119,7 @@ specified:
file.
- Example Usage:
+ Example Usage:
env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'], projects = ['bar'
+ env['MSVSPROJECTSUFFIX']], variant = 'Release')
@@ -1157,10 +1131,9 @@ env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'], projects = ['bar'
env.Object()
-
-
+
A synonym for the
-StaticObject
+StaticObject
builder method.
@@ -1172,41 +1145,39 @@ builder method.
env.Package()
-
-
+
Builds a Binary Package of the given source files.
-
+
env.Package(source = FindInstalledFiles())
-
-
+
Builds software distribution packages.
Packages consist of files to install and packaging information.
-The former may be specified with the source parameter and may be left out,
-in which case the FindInstalledFiles function will collect
-all files that have an Install or InstallAs Builder attached.
-If the target is not specified
+The former may be specified with the source parameter and may be left out,
+in which case the FindInstalledFiles function will collect
+all files that have an Install or InstallAs Builder attached.
+If the target is not specified
it will be deduced from additional information given to this Builder.
-
+
The packaging information is specified
with the help of construction variables documented below.
This information is called a tag to stress that
-some of them can also be attached to files with the Tag function.
+some of them can also be attached to files with the Tag function.
The mandatory ones will complain if they were not specified.
They vary depending on chosen target packager.
-
+
The target packager may be selected with the "PACKAGETYPE" command line
-option or with the $PACKAGETYPE construction variable. Currently
+option or with the $PACKAGETYPE construction variable. Currently
the following packagers available:
-
+
* msi - Microsoft Installer
* rpm - RPM Package Manger
* ipkg - Itsy Package Management System
@@ -1220,11 +1191,11 @@ the following packagers available:
* src_zip - zip file source
-
+
An updated list is always available under the "package_type" option when
running "scons --help" on a project that has packaging activated.
-
+
env = Environment(tools=['default', 'packaging'])
env.Install('/bin/', 'my_program')
env.Package( NAME = 'foo',
@@ -1247,8 +1218,7 @@ env.Package( NAME = 'foo',
env.PCH()
-
-
+
Builds a Microsoft Visual C++ precompiled header.
Calling this builder method
returns a list of two targets: the PCH as the first element, and the object
@@ -1260,7 +1230,7 @@ conjunction with the PCH construction variable to force object files to use
the precompiled header:
-
+
env['PCH'] = env.PCH('StdAfx.cpp')[0]
@@ -1272,21 +1242,20 @@ env['PCH'] = env.PCH('StdAfx.cpp')[0]
env.PDF()
-
-
+
Builds a .pdf file
from a .dvi input file
(or, by extension, a .tex,
.ltx,
or
.latex input file).
-The suffix specified by the $PDFSUFFIX construction variable
+The suffix specified by the $PDFSUFFIX construction variable
(.pdf by default)
is added automatically to the target
if it is not already present. Example:
-
+
# builds from aaa.tex
env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
# builds bbb.pdf from bbb.dvi
@@ -1301,100 +1270,99 @@ env.PDF(target = 'bbb', source = 'bbb.dvi')
env.POInit()
-
-
-This builder belongs to msginit tool. The builder initializes missing
-PO file(s) if $POAUTOINIT is set. If
-$POAUTOINIT is not set (default), POInit prints instruction for
+
+This builder belongs to msginit tool. The builder initializes missing
+PO file(s) if $POAUTOINIT is set. If
+$POAUTOINIT is not set (default), POInit prints instruction for
user (that is supposed to be a translator), telling how the
PO file should be initialized. In normal projects
-you should not use POInit and use POUpdate
-instead. POUpdate chooses intelligently between
-msgmerge(1) and msginit(1). POInit
+you should not use POInit and use POUpdate
+instead. POUpdate chooses intelligently between
+msgmerge(1) and msginit(1). POInit
always uses msginit(1) and should be regarded as builder for
special purposes or for temporary use (e.g. for quick, one time initialization
of a bunch of PO files) or for tests.
-
-Target nodes defined through POInit are not built by default (they're
+
+Target nodes defined through POInit are not built by default (they're
Ignored from '.' node) but are added to
special Alias ('po-create' by default).
-The alias name may be changed through the $POCREATE_ALIAS
+The alias name may be changed through the $POCREATE_ALIAS
construction variable. All PO files defined through
-POInit may be easily initialized by scons po-create.
+POInit may be easily initialized by scons po-create.
-
+Example 1.
Initialize en.po and pl.po from
messages.pot:
-
+
# ...
env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po]
-
+Example 2.
Initialize en.po and pl.po from
foo.pot:
-
+
# ...
env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po]
-
+Example 3.
Initialize en.po and pl.po from
-foo.pot but using $POTDOMAIN construction
+foo.pot but using $POTDOMAIN construction
variable:
-
+
# ...
env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po]
-
+Example 4.
Initialize PO files for languages defined in
LINGUAS file. The files will be initialized from template
messages.pot:
-
+
# ...
env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
-
+Example 5.
Initialize en.po and pl.plPO files plus files for languages defined in
LINGUAS file. The files will be initialized from template
messages.pot:
-
+
# ...
env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
-
+Example 6.
You may preconfigure your environment first, and then initialize
PO files:
-
+
# ...
env['POAUTOINIT'] = 1
env['LINGUAS_FILE'] = 1
env['POTDOMAIN'] = 'foo'
env.POInit()
-
+
which has same efect as:
-
+
# ...
env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
@@ -1407,21 +1375,20 @@ which has same efect as:
env.PostScript()
-
-
+
Builds a .ps file
from a .dvi input file
(or, by extension, a .tex,
.ltx,
or
.latex input file).
-The suffix specified by the $PSSUFFIX construction variable
+The suffix specified by the $PSSUFFIX construction variable
(.ps by default)
is added automatically to the target
if it is not already present. Example:
-
+
# builds from aaa.tex
env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
# builds bbb.ps from bbb.dvi
@@ -1436,24 +1403,23 @@ env.PostScript(target = 'bbb', source = 'bbb.dvi')
env.POTUpdate()
-
-
-The builder belongs to xgettext tool. The builder updates target
+
+The builder belongs to xgettext tool. The builder updates target
POT file if exists or creates one if it doesn't. The node is
not built by default (i.e. it is Ignored from
'.'), but only on demand (i.e. when given
POT file is required or when special alias is invoked). This
builder adds its targe node (messages.pot, say) to a
special alias (pot-update by default, see
-$POTUPDATE_ALIAS) so you can update/create them easily with
+$POTUPDATE_ALIAS) so you can update/create them easily with
scons pot-update. The file is not written until there is no
real change in internationalized messages (or in comments that enter
POT file).
-
+You may see xgettext(1) being invoked by the
-xgettext tool even if there is no real change in internationalized
+xgettext tool even if there is no real change in internationalized
messages (so the POT file is not being updated). This
happens every time a source file has changed. In such case we invoke
xgettext(1) and compare its output with the content of
@@ -1461,38 +1427,38 @@ happens every time a source file has changed. In such case we invoke
not.
-
+Example 1.
Let's create po/ directory and place following
SConstruct script there:
-
+
# SConstruct in 'po/' subdir
env = Environment( tools = ['default', 'xgettext'] )
env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
-
+
Then invoke scons few times:
-
+
user@host:$ scons # Does not create foo.pot nor bar.pot
user@host:$ scons foo.pot # Updates or creates foo.pot
user@host:$ scons pot-update # Updates or creates foo.pot and bar.pot
user@host:$ scons -c # Does not clean foo.pot nor bar.pot.
-
+
the results shall be as the comments above say.
-
+Example 2.
-The POTUpdate builder may be used with no target specified, in which
+The POTUpdate builder may be used with no target specified, in which
case default target messages.pot will be used. The
-default target may also be overridden by setting $POTDOMAIN construction
-variable or providing it as an override to POTUpdate builder:
+default target may also be overridden by setting $POTDOMAIN construction
+variable or providing it as an override to POTUpdate builder:
-
+
# SConstruct script
env = Environment( tools = ['default', 'xgettext'] )
env['POTDOMAIN'] = "foo"
@@ -1500,49 +1466,49 @@ variable or providing it as an override to
-
+Example 3.
The sources may be specified within separate file, for example
POTFILES.in:
-
+
# POTFILES.in in 'po/' subdirectory
../a.cpp
../b.cpp
# end of file
-
+
The name of the file (POTFILES.in) containing the list of
-sources is provided via $XGETTEXTFROM:
+sources is provided via $XGETTEXTFROM:
-
+
# SConstruct file in 'po/' subdirectory
env = Environment( tools = ['default', 'xgettext'] )
env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
-
+Example 4.
-You may use $XGETTEXTPATH to define source search path. Assume, for
+You may use $XGETTEXTPATH to define source search path. Assume, for
example, that you have files a.cpp,
b.cpp, po/SConstruct,
po/POTFILES.in. Then your POT-related
files could look as below:
-
+
# POTFILES.in in 'po/' subdirectory
a.cpp
b.cpp
# end of file
-
+
# SConstruct file in 'po/' subdirectory
env = Environment( tools = ['default', 'xgettext'] )
env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
-
+Example 5.
Multiple search directories may be defined within a list, i.e.
XGETTEXTPATH = ['dir1', 'dir2', ...]. The order in the list
@@ -1550,48 +1516,48 @@ determines the search order of source files. The path to the first file found
is used.
-
+
Let's create 0/1/po/SConstruct script:
-
+
# SConstruct file in '0/1/po/' subdirectory
env = Environment( tools = ['default', 'xgettext'] )
env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
-
+
and 0/1/po/POTFILES.in:
-
+
# POTFILES.in in '0/1/po/' subdirectory
a.cpp
# end of file
-
+
Write two *.cpp files, the first one is
0/a.cpp:
-
+
/* 0/a.cpp */
gettext("Hello from ../../a.cpp")
-
+
and the second is 0/1/a.cpp:
-
+
/* 0/1/a.cpp */
gettext("Hello from ../a.cpp")
-
+
then run scons. You'll obtain 0/1/po/messages.pot with the
message "Hello from ../a.cpp". When you reverse order in
$XGETTEXTFOM, i.e. when you write SConscript as
-
+
# SConstruct file in '0/1/po/' subdirectory
env = Environment( tools = ['default', 'xgettext'] )
env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
-
+
then the messages.pot will contain
msgid "Hello from ../../a.cpp" line and not
msgid "Hello from ../a.cpp".
@@ -1606,107 +1572,106 @@ then the messages.pot will contain
env.POUpdate()
-
-
-The builder belongs to msgmerge tool. The builder updates
+
+The builder belongs to msgmerge tool. The builder updates
PO files with msgmerge(1), or initializes
missing PO files as described in documentation of
-msginit tool and POInit builder (see also
-$POAUTOINIT). Note, that POUpdatedoes not add its
-targets to po-create alias as POInit
+msginit tool and POInit builder (see also
+$POAUTOINIT). Note, that POUpdatedoes not add its
+targets to po-create alias as POInit
does.
-
-Target nodes defined through POUpdate are not built by default
+
+Target nodes defined through POUpdate are not built by default
(they're Ignored from '.' node). Instead,
they are added automatically to special Alias
('po-update' by default). The alias name may be changed
-through the $POUPDATE_ALIAS construction variable. You can easily
+through the $POUPDATE_ALIAS construction variable. You can easily
update PO files in your project by scons
po-update.
-
+Example 1.
Update en.po and pl.po from
-messages.pot template (see also $POTDOMAIN),
+messages.pot template (see also $POTDOMAIN),
assuming that the later one exists or there is rule to build it (see
-POTUpdate):
+POTUpdate):
-
+
# ...
env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po]
-
+Example 2.
Update en.po and pl.po from
foo.pot template:
-
+
# ...
env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.pl]
-
+Example 3.
Update en.po and pl.po from
foo.pot (another version):
-
+
# ...
env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl]
-
+Example 4.
Update files for languages defined in LINGUAS file. The
files are updated from messages.pot template:
-
+
# ...
env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
-
+Example 5.
Same as above, but update from foo.pot template:
-
+
# ...
env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
-
+Example 6.
Update en.po and pl.po plus files for
languages defined in LINGUAS file. The files are updated
from messages.pot template:
-
+
# produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1)
-
+Example 7.
-Use $POAUTOINIT to automatically initialize PO file
+Use $POAUTOINIT to automatically initialize PO file
if it doesn't exist:
-
+
# ...
env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
-
+Example 8.
Update PO files for languages defined in
LINGUAS file. The files are updated from
foo.pot template. All necessary settings are
pre-configured via environment.
-
+
# ...
env['POAUTOINIT'] = 1
env['LINGUAS_FILE'] = 1
@@ -1723,29 +1688,28 @@ pre-configured via environment.
env.Program()
-
-
+
Builds an executable given one or more object files
or C, C++, D, or Fortran source files.
If any C, C++, D or Fortran source files are specified,
then they will be automatically
compiled to object files using the
-Object
+Object
builder method;
see that builder method's description for
a list of legal source file suffixes
and how they are interpreted.
The target executable file prefix
-(specified by the $PROGPREFIX construction variable; nothing by default)
+(specified by the $PROGPREFIX construction variable; nothing by default)
and suffix
-(specified by the $PROGSUFFIX construction variable;
+(specified by the $PROGSUFFIX construction variable;
by default, .exe on Windows systems,
nothing on POSIX systems)
are automatically added to the target if not already present.
Example:
-
+
env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
@@ -1757,67 +1721,64 @@ env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
env.ProgramAllAtOnce()
-
-
+
Builds an executable from D sources without first creating individual
objects for each file.
-
+
D sources can be compiled file-by-file as C and C++ source are, and
- D is integrated into the scons Object and Program builders for
+ D is integrated into the scons Object and Program builders for
this model of build. D codes can though do whole source
meta-programming (some of the testing frameworks do this). For this
it is imperative that all sources are compiled and linked in a single call of
the D compiler. This builder serves that purpose.
-
+
env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])
-
+
This command will compile the modules mod_a, mod_b, and mod_c in a
single compilation process without first creating object files for
the modules. Some of the D compilers will create executable.o others
will not.
-
-
+
Builds an executable from D sources without first creating individual
objects for each file.
-
+
D sources can be compiled file-by-file as C and C++ source are, and
- D is integrated into the scons Object and Program builders for
+ D is integrated into the scons Object and Program builders for
this model of build. D codes can though do whole source
meta-programming (some of the testing frameworks do this). For this
it is imperative that all sources are compiled and linked in a single call of
the D compiler. This builder serves that purpose.
-
+
env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])
-
+
This command will compile the modules mod_a, mod_b, and mod_c in a
single compilation process without first creating object files for
the modules. Some of the D compilers will create executable.o others
will not.
-
-
+
Builds an executable from D sources without first creating individual
objects for each file.
-
+
D sources can be compiled file-by-file as C and C++ source are, and
- D is integrated into the scons Object and Program builders for
+ D is integrated into the scons Object and Program builders for
this model of build. D codes can though do whole source
meta-programming (some of the testing frameworks do this). For this
it is imperative that all sources are compiled and linked in a single call of
the D compiler. This builder serves that purpose.
-
+
env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])
-
+
This command will compile the modules mod_a, mod_b, and mod_c in a
single compilation process without first creating object files for
the modules. Some of the D compilers will create executable.o others
@@ -1832,8 +1793,7 @@ env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
env.RES()
-
-
+
Builds a Microsoft Visual C++ resource file.
This builder method is only provided
when Microsoft Visual C++ or MinGW is being used as the compiler. The
@@ -1846,7 +1806,7 @@ file is scanned for implicit dependencies as though it were a C file.
Example:
-
+
env.RES('resource.rc')
@@ -1858,8 +1818,7 @@ env.RES('resource.rc')
env.RMIC()
-
-
+
Builds stub and skeleton class files
for remote objects
from Java .class files.
@@ -1868,16 +1827,16 @@ relative to which the stub
and skeleton class files will be written.
The source can be the names of .class files,
or the objects return from the
-Java
+Java
builder method.
-
+
If the construction variable
-$JAVACLASSDIR
+$JAVACLASSDIR
is set, either in the environment
or in the call to the
-RMIC
+RMIC
builder method itself,
then the value of the variable
will be stripped from the
@@ -1885,7 +1844,7 @@ beginning of any .class
file names.
-
+
classes = env.Java(target = 'classdir', source = 'src')
env.RMIC(target = 'outdir1', source = classes)
@@ -1905,8 +1864,7 @@ env.RMIC(target = 'outdir3',
env.RPCGenClient()
-
-
+
Generates an RPC client stub (_clnt.c) file
from a specified RPC (.x) source file.
Because rpcgen only builds output files
@@ -1915,7 +1873,7 @@ the command will be executed
in the source file's directory by default.
-
+
# Builds src/rpcif_clnt.c
env.RPCGenClient('src/rpcif.x')
@@ -1928,8 +1886,7 @@ env.RPCGenClient('src/rpcif.x')
env.RPCGenHeader()
-
-
+
Generates an RPC header (.h) file
from a specified RPC (.x) source file.
Because rpcgen only builds output files
@@ -1938,7 +1895,7 @@ the command will be executed
in the source file's directory by default.
-
+
# Builds src/rpcif.h
env.RPCGenHeader('src/rpcif.x')
@@ -1951,8 +1908,7 @@ env.RPCGenHeader('src/rpcif.x')
env.RPCGenService()
-
-
+
Generates an RPC server-skeleton (_svc.c) file
from a specified RPC (.x) source file.
Because rpcgen only builds output files
@@ -1961,7 +1917,7 @@ the command will be executed
in the source file's directory by default.
-
+
# Builds src/rpcif_svc.c
env.RPCGenClient('src/rpcif.x')
@@ -1974,8 +1930,7 @@ env.RPCGenClient('src/rpcif.x')
env.RPCGenXDR()
-
-
+
Generates an RPC XDR routine (_xdr.c) file
from a specified RPC (.x) source file.
Because rpcgen only builds output files
@@ -1984,7 +1939,7 @@ the command will be executed
in the source file's directory by default.
-
+
# Builds src/rpcif_xdr.c
env.RPCGenClient('src/rpcif.x')
@@ -1997,8 +1952,7 @@ env.RPCGenClient('src/rpcif.x')
env.SharedLibrary()
-
-
+
Builds a shared library
(.so on a POSIX system,
.dll on Windows)
@@ -2010,24 +1964,24 @@ compiled to object files.
The static library prefix and suffix (if any)
are automatically added to the target.
The target library file prefix
-(specified by the $SHLIBPREFIX construction variable;
+(specified by the $SHLIBPREFIX construction variable;
by default, lib on POSIX systems,
nothing on Windows systems)
and suffix
-(specified by the $SHLIBSUFFIX construction variable;
+(specified by the $SHLIBSUFFIX construction variable;
by default, .dll on Windows systems,
.so on POSIX systems)
are automatically added to the target if not already present.
Example:
-
+
env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
-
+
On Windows systems, the
-SharedLibrary
+SharedLibrary
builder method will always build an import
(.lib) library
in addition to the shared (.dll) library,
@@ -2036,9 +1990,9 @@ if there is not already a .lib file explicitly
listed in the targets.
-
+
On Cygwin systems, the
-SharedLibrary
+SharedLibrary
builder method will always build an import
(.dll.a) library
in addition to the shared (.dll) library,
@@ -2047,36 +2001,36 @@ if there is not already a .dll.a file explicitly
listed in the targets.
-
+
Any object files listed in the
source
must have been built for a shared library
(that is, using the
-SharedObject
+SharedObject
builder method).
-scons
+scons
will raise an error if there is any mismatch.
-
+
On some platforms, there is a distinction between a shared library
(loaded automatically by the system to resolve external references)
and a loadable module (explicitly loaded by user action).
-For maximum portability, use the LoadableModule builder for the latter.
+For maximum portability, use the LoadableModule builder for the latter.
-
-When the $SHLIBVERSION construction variable is defined a versioned
-shared library is created. This modifies the $SHLINKFLAGS as required,
+
+When the $SHLIBVERSION construction variable is defined a versioned
+shared library is created. This modifies the $SHLINKFLAGS as required,
adds the version number to the library name, and creates the symlinks that
are needed.
-
+
env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
-
+
On a POSIX system, versions with a single token create exactly one symlink:
libbar.so.6 would have symlinks libbar.so only.
On a POSIX system, versions with two or more
@@ -2085,28 +2039,28 @@ libbar.so and libbar.so.2; on a Darwin (OSX) system the library would be
libbar.2.3.1.dylib and the link would be libbar.dylib.
-
+
On Windows systems, specifying
register=1
will cause the .dll to be
registered after it is built using REGSVR32.
The command that is run
-("regsvr32" by default) is determined by $REGSVR construction
-variable, and the flags passed are determined by $REGSVRFLAGS. By
-default, $REGSVRFLAGS includes the option,
+("regsvr32" by default) is determined by $REGSVR construction
+variable, and the flags passed are determined by $REGSVRFLAGS. By
+default, $REGSVRFLAGS includes the option,
to prevent dialogs from popping
up and requiring user attention when it is run. If you change
-$REGSVRFLAGS, be sure to include the option.
+$REGSVRFLAGS, be sure to include the option.
For example,
-
+
env.SharedLibrary(target = 'bar',
source = ['bar.cxx', 'foo.obj'],
register=1)
-
+
will register bar.dll as a COM object
when it is done linking it.
@@ -2119,13 +2073,12 @@ when it is done linking it.
env.SharedObject()
-
-
+
Builds an object file for
inclusion in a shared library.
Source files must have one of the same set of extensions
specified above for the
-StaticObject
+StaticObject
builder method.
On some platforms building a shared object requires additional
compiler option
@@ -2140,21 +2093,21 @@ and shared objects to be linked into a
shared library, and will use the same suffix for shared and normal
(static) objects.
The target object file prefix
-(specified by the $SHOBJPREFIX construction variable;
-by default, the same as $OBJPREFIX)
+(specified by the $SHOBJPREFIX construction variable;
+by default, the same as $OBJPREFIX)
and suffix
-(specified by the $SHOBJSUFFIX construction variable)
+(specified by the $SHOBJSUFFIX construction variable)
are automatically added to the target if not already present.
Examples:
-
+
env.SharedObject(target = 'ddd', source = 'ddd.c')
env.SharedObject(target = 'eee.o', source = 'eee.cpp')
env.SharedObject(target = 'fff.obj', source = 'fff.for')
-
+
Note that the source files will be scanned
according to the suffix mappings in the
SourceFileScanner
@@ -2171,8 +2124,7 @@ below, for more information.
env.StaticLibrary()
-
-
+
Builds a static library given one or more object files
or C, C++, D or Fortran source files.
If any source files are given,
@@ -2181,29 +2133,29 @@ compiled to object files.
The static library prefix and suffix (if any)
are automatically added to the target.
The target library file prefix
-(specified by the $LIBPREFIX construction variable;
+(specified by the $LIBPREFIX construction variable;
by default, lib on POSIX systems,
nothing on Windows systems)
and suffix
-(specified by the $LIBSUFFIX construction variable;
+(specified by the $LIBSUFFIX construction variable;
by default, .lib on Windows systems,
.a on POSIX systems)
are automatically added to the target if not already present.
Example:
-
+
env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
-
+
Any object files listed in the
source
must have been built for a static library
(that is, using the
-StaticObject
+StaticObject
builder method).
-scons
+scons
will raise an error if there is any mismatch.
@@ -2215,14 +2167,13 @@ will raise an error if there is any mismatch.
env.StaticObject()
-
-
+
Builds a static object file
from one or more C, C++, D, or Fortran source files.
Source files must have one of the following extensions:
-
+
.asm assembly language file
.ASM assembly language file
.c C file
@@ -2253,24 +2204,24 @@ Source files must have one of the following extensions:
.SPP assembly language file + C pre-processor
-
+
The target object file prefix
-(specified by the $OBJPREFIX construction variable; nothing by default)
+(specified by the $OBJPREFIX construction variable; nothing by default)
and suffix
-(specified by the $OBJSUFFIX construction variable;
+(specified by the $OBJSUFFIX construction variable;
.obj on Windows systems,
.o on POSIX systems)
are automatically added to the target if not already present.
Examples:
-
+
env.StaticObject(target = 'aaa', source = 'aaa.c')
env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
-
+
Note that the source files will be scanned
according to the suffix mappings in
SourceFileScanner
@@ -2287,28 +2238,27 @@ below, for more information.
env.Substfile()
-
-
-The Substfile builder creates a single text file from another file or set of
-files by concatenating them with $LINESEPARATOR and replacing text
-using the $SUBST_DICT construction variable. Nested lists of source files
-are flattened. See also Textfile.
+
+The Substfile builder creates a single text file from another file or set of
+files by concatenating them with $LINESEPARATOR and replacing text
+using the $SUBST_DICT construction variable. Nested lists of source files
+are flattened. See also Textfile.
-
+
If a single source file is present with an .in suffix,
the suffix is stripped and the remainder is used as the default target name.
-
-The prefix and suffix specified by the $SUBSTFILEPREFIX
-and $SUBSTFILESUFFIX construction variables
+
+The prefix and suffix specified by the $SUBSTFILEPREFIX
+and $SUBSTFILESUFFIX construction variables
(the null string by default in both cases)
are automatically added to the target if they are not already present.
-
-If a construction variable named $SUBST_DICT is present,
+
+If a construction variable named $SUBST_DICT is present,
it may be either a Python dictionary or a sequence of (key,value) tuples.
If it is a dictionary it is converted into a list of tuples in an arbitrary order,
so if one key is a prefix of another key
@@ -2316,7 +2266,7 @@ or if one substitution could be further expanded by another subsitition,
it is unpredictable whether the expansion will occur.
-
+
Any occurrences of a key in the source
are replaced by the corresponding value,
which may be a Python callable function or a string.
@@ -2325,7 +2275,7 @@ Strings are subst-expanded
and the result replaces the key.
-
+
env = Environment(tools = ['default', 'textfile'])
env['prefix'] = '/usr/bin'
@@ -2377,13 +2327,12 @@ subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
env.Tar()
-
-
+
Builds a tar archive of the specified files
and/or directories.
Unlike most builder methods,
the
-Tar
+Tar
builder method may be called multiple times
for a given target;
each additional call
@@ -2393,11 +2342,11 @@ Any source directories will
be scanned for changes to
any on-disk files,
regardless of whether or not
-scons
+scons
knows about them from other Builder or function calls.
-
+
env.Tar('src.tar', 'src')
# Create the stuff.tar file.
@@ -2423,29 +2372,28 @@ env.Tar('foo')
env.Textfile()
-
-
-The Textfile builder generates a single text file.
+
+The Textfile builder generates a single text file.
The source strings constitute the lines;
nested lists of sources are flattened.
-$LINESEPARATOR is used to separate the strings.
+$LINESEPARATOR is used to separate the strings.
-
-If present, the $SUBST_DICT construction variable
+
+If present, the $SUBST_DICT construction variable
is used to modify the strings before they are written;
-see the Substfile description for details.
+see the Substfile description for details.
-
-The prefix and suffix specified by the $TEXTFILEPREFIX
-and $TEXTFILESUFFIX construction variables
+
+The prefix and suffix specified by the $TEXTFILEPREFIX
+and $TEXTFILESUFFIX construction variables
(the null string and .txt by default, respectively)
are automatically added to the target if they are not already present.
Examples:
-
+
# builds/writes foo.txt
env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])
@@ -2494,50 +2442,49 @@ blob.txt
env.Translate()
-
-
-This pseudo-builder belongs to gettext toolset. The builder extracts
+
+This pseudo-builder belongs to gettext toolset. The builder extracts
internationalized messages from source files, updates POT
template (if necessary) and then updates PO translations (if
-necessary). If $POAUTOINIT is set, missing PO files
+necessary). If $POAUTOINIT is set, missing PO files
will be automatically created (i.e. without translator person intervention).
-The variables $LINGUAS_FILE and $POTDOMAIN are taken into
-acount too. All other construction variables used by POTUpdate, and
-POUpdate work here too.
+The variables $LINGUAS_FILE and $POTDOMAIN are taken into
+acount too. All other construction variables used by POTUpdate, and
+POUpdate work here too.
-
+Example 1.
The simplest way is to specify input files and output languages inline in
-a SCons script when invoking Translate
+a SCons script when invoking Translate
-
+
# SConscript in 'po/' directory
env = Environment( tools = ["default", "gettext"] )
env['POAUTOINIT'] = 1
env.Translate(['en','pl'], ['../a.cpp','../b.cpp'])
-
+Example 2.
If you wish, you may also stick to conventional style known from
autotools, i.e. using
POTFILES.in and LINGUAS files
-
+
# LINGUAS
en pl
#end
-
+
# POTFILES.in
a.cpp
b.cpp
# end
-
+
# SConscript
env = Environment( tools = ["default", "gettext"] )
env['POAUTOINIT'] = 1
@@ -2545,7 +2492,7 @@ env['XGETTEXTPATH'] = ['../']
env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in')
-
+
The last approach is perhaps the recommended one. It allows easily split
internationalization/localization onto separate SCons scripts, where a script
in source tree is responsible for translations (from sources to
@@ -2562,11 +2509,11 @@ so the source tree looks familiar to translators, and they may work with the
project in their usual way.
-
+Example 3.
Let's prepare a development tree as below
-
+
project/
+ SConstruct
+ build/
@@ -2577,11 +2524,11 @@ Let's prepare a development tree as below
+ POTFILES.in
+ LINGUAS
-
+
with build being variant directory. Write the top-level
SConstruct script as follows
-
+
# SConstruct
env = Environment( tools = ["default", "gettext"] )
VariantDir('build', 'src', duplicate = 0)
@@ -2589,23 +2536,23 @@ with build being variant directory. Write the top-level
SConscript('src/po/SConscript.i18n', exports = 'env')
SConscript('build/po/SConscript', exports = 'env')
-
+
the src/po/SConscript.i18n as
-
+
# src/po/SConscript.i18n
Import('env')
env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
-
+
and the src/po/SConscript
-
+
# src/po/SConscript
Import('env')
env.MOFiles(LINGUAS_FILE = 1)
-
+
Such setup produces POT and PO files
under source tree in src/po/ and binary
MO files under variant tree in
@@ -2615,7 +2562,7 @@ not be committed back to source repositories (e.g. MO
files).
-
+In above example, the PO files are not updated,
nor created automatically when you issue scons '.' command.
The files must be updated (created) by hand via scons
@@ -2632,8 +2579,7 @@ running scons '.'.env.TypeLibrary()
-
-
+
Builds a Windows type library (.tlb)
file from an input IDL file (.idl).
In addition, it will build the associated interface stub and
@@ -2642,11 +2588,11 @@ naming them according to the base name of the .idl file.
For example,
-
+
env.TypeLibrary(source="foo.idl")
-
+
Will create foo.tlb,
foo.h,
foo_i.c,
@@ -2664,22 +2610,21 @@ files.
env.Uic()
-
-
+
Builds a header file, an implementation file and a moc file from an ui file.
and returns the corresponding nodes in the above order.
This builder is only available after using the tool 'qt'. Note: you can
specify .ui files directly as source
-files to the Program,
-Library and SharedLibrary builders
+files to the Program,
+Library and SharedLibrary builders
without using this builder. Using this builder lets you override the standard
naming conventions (be careful: prefixes are always prepended to names of
built files; if you don't want prefixes, you may set them to ``).
-See the $QTDIR variable for more information.
+See the $QTDIR variable for more information.
Example:
-
+
env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
@@ -2693,13 +2638,12 @@ env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
env.Zip()
-
-
+
Builds a zip archive of the specified files
and/or directories.
Unlike most builder methods,
the
-Zip
+Zip
builder method may be called multiple times
for a given target;
each additional call
@@ -2709,11 +2653,11 @@ Any source directories will
be scanned for changes to
any on-disk files,
regardless of whether or not
-scons
+scons
knows about them from other Builder or function calls.
-
+
env.Zip('src.zip', 'src')
# Create the stuff.zip file.
diff --git a/doc/generated/examples/EnumVariable_map_1.xml b/doc/generated/examples/EnumVariable_map_1.xml
index 4380be0621..758405abf7 100644
--- a/doc/generated/examples/EnumVariable_map_1.xml
+++ b/doc/generated/examples/EnumVariable_map_1.xml
@@ -1,4 +1,4 @@
-
-% scons -Q COLOR=navy foo.o
+
+% scons -Q COLOR=navy foo.o
cc -o foo.o -c -DCOLOR="blue" foo.c
diff --git a/doc/generated/examples/addmethod_ex1_1.xml b/doc/generated/examples/addmethod_ex1_1.xml
index 84dfd20ae9..0d2c88ac5e 100644
--- a/doc/generated/examples/addmethod_ex1_1.xml
+++ b/doc/generated/examples/addmethod_ex1_1.xml
@@ -1,5 +1,5 @@
-
-% scons -Q /
+
+% scons -Q /
cc -o hello.o -c hello.c
cc -o hello hello.o
Install file: "hello" as "/usr/bin/hello"
diff --git a/doc/generated/examples/addmethod_ex2_1.xml b/doc/generated/examples/addmethod_ex2_1.xml
index 3930341f9f..3bcb3e985d 100644
--- a/doc/generated/examples/addmethod_ex2_1.xml
+++ b/doc/generated/examples/addmethod_ex2_1.xml
@@ -1,5 +1,5 @@
-
-% scons -Q
+
+% scons -Q
cc -o test_stuff.o -c test_stuff.c
cc -o tests/test_stuff test_stuff.o
diff --git a/doc/generated/examples/addmethod_ex2_2.xml b/doc/generated/examples/addmethod_ex2_2.xml
index 15ae6e09da..973e212a62 100644
--- a/doc/generated/examples/addmethod_ex2_2.xml
+++ b/doc/generated/examples/addmethod_ex2_2.xml
@@ -1,5 +1,5 @@
-
-C:\>scons -Q
+
+C:\>scons -Q
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
diff --git a/doc/generated/examples/alias_ex1_1.xml b/doc/generated/examples/alias_ex1_1.xml
index 3ee3f1b585..21ddc8f527 100644
--- a/doc/generated/examples/alias_ex1_1.xml
+++ b/doc/generated/examples/alias_ex1_1.xml
@@ -1,5 +1,5 @@
-
-% scons -Q install
+
+% scons -Q install
cc -o hello.o -c hello.c
cc -o hello hello.o
Install file: "hello" as "/usr/bin/hello"
diff --git a/doc/generated/examples/alias_ex2_1.xml b/doc/generated/examples/alias_ex2_1.xml
index 3fa7dfdd11..170bdf9f85 100644
--- a/doc/generated/examples/alias_ex2_1.xml
+++ b/doc/generated/examples/alias_ex2_1.xml
@@ -1,5 +1,5 @@
-
-% scons -Q install-bin
+
+% scons -Q install-bin
cc -o foo.o -c foo.c
cc -o foo foo.o
Install file: "foo" as "/usr/bin/foo"
diff --git a/doc/generated/examples/buildersbuiltin_ex1_1.xml b/doc/generated/examples/buildersbuiltin_ex1_1.xml
index 74cc779323..7704588234 100644
--- a/doc/generated/examples/buildersbuiltin_ex1_1.xml
+++ b/doc/generated/examples/buildersbuiltin_ex1_1.xml
@@ -1,5 +1,5 @@
-
-% scons -Q .
+
+% scons -Q .
tar -c -f out1.tar file1 file2
tar -c -f out2.tar directory
diff --git a/doc/generated/examples/buildersbuiltin_ex2_1.xml b/doc/generated/examples/buildersbuiltin_ex2_1.xml
index 6c66d7bd06..a86c8a6cfe 100644
--- a/doc/generated/examples/buildersbuiltin_ex2_1.xml
+++ b/doc/generated/examples/buildersbuiltin_ex2_1.xml
@@ -1,4 +1,4 @@
-
-% scons -Q .
+
+% scons -Q .
tar -c -z -f out.tar.gz directory
diff --git a/doc/generated/examples/buildersbuiltin_ex3_1.xml b/doc/generated/examples/buildersbuiltin_ex3_1.xml
index 4d281e5533..fc838c25a1 100644
--- a/doc/generated/examples/buildersbuiltin_ex3_1.xml
+++ b/doc/generated/examples/buildersbuiltin_ex3_1.xml
@@ -1,4 +1,4 @@
-
-% scons -Q .
+
+% scons -Q .
tar -c -z -f out.tgz directory
diff --git a/doc/generated/examples/buildersbuiltin_ex4_1.xml b/doc/generated/examples/buildersbuiltin_ex4_1.xml
index 856f024a91..eb6ae9de15 100644
--- a/doc/generated/examples/buildersbuiltin_ex4_1.xml
+++ b/doc/generated/examples/buildersbuiltin_ex4_1.xml
@@ -1,4 +1,4 @@
-
-% scons -Q .
+
+% scons -Q .
zip(["out.zip"], ["file1", "file2"])
diff --git a/doc/generated/examples/buildersbuiltin_libs_1.xml b/doc/generated/examples/buildersbuiltin_libs_1.xml
index 8e1ee49916..7f3b620410 100644
--- a/doc/generated/examples/buildersbuiltin_libs_1.xml
+++ b/doc/generated/examples/buildersbuiltin_libs_1.xml
@@ -1,5 +1,5 @@
-
-% scons -Q
+
+% scons -Q
cc -o goodbye.o -c goodbye.c
cc -o hello.o -c hello.c
cc -o hello hello.o goodbye.o -L/usr/dir1 -Ldir2 -lfoo1 -lfoo2
diff --git a/doc/generated/examples/buildersbuiltin_libs_2.xml b/doc/generated/examples/buildersbuiltin_libs_2.xml
index 41a9c1ee0f..24038fca47 100644
--- a/doc/generated/examples/buildersbuiltin_libs_2.xml
+++ b/doc/generated/examples/buildersbuiltin_libs_2.xml
@@ -1,5 +1,5 @@
-
-C:\>scons -Q
+
+C:\>scons -Q
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
diff --git a/doc/generated/examples/builderscommands_ex1_1.xml b/doc/generated/examples/builderscommands_ex1_1.xml
index 8782773e49..314b8a5976 100644
--- a/doc/generated/examples/builderscommands_ex1_1.xml
+++ b/doc/generated/examples/builderscommands_ex1_1.xml
@@ -1,4 +1,4 @@
-
-% scons -Q
+
+% scons -Q
sed 's/x/y/' < foo.in > foo.out
diff --git a/doc/generated/examples/builderscommands_ex2_1.xml b/doc/generated/examples/builderscommands_ex2_1.xml
index 3fc1dde7b5..6c3aef2725 100644
--- a/doc/generated/examples/builderscommands_ex2_1.xml
+++ b/doc/generated/examples/builderscommands_ex2_1.xml
@@ -1,4 +1,4 @@
-
-% scons -Q
+
+% scons -Q
build(["foo.out"], ["foo.in"])
diff --git a/doc/generated/examples/builderswriting_MY_EMITTER_1.xml b/doc/generated/examples/builderswriting_MY_EMITTER_1.xml
index 0c17d0e383..6cac375c7d 100644
--- a/doc/generated/examples/builderswriting_MY_EMITTER_1.xml
+++ b/doc/generated/examples/builderswriting_MY_EMITTER_1.xml
@@ -1,5 +1,5 @@
-
-% scons -Q
+
+% scons -Q
./my_command file1.input modify1.in > file1.foo
./my_command file2.input modify2.in > file2.foo
diff --git a/doc/generated/examples/builderswriting_ex1_1.xml b/doc/generated/examples/builderswriting_ex1_1.xml
index cefcfa2bdd..b16a41bd2b 100644
--- a/doc/generated/examples/builderswriting_ex1_1.xml
+++ b/doc/generated/examples/builderswriting_ex1_1.xml
@@ -1,4 +1,4 @@
-
-% scons -Q
+
+% scons -Q
foobuild < file.input > file.foo
diff --git a/doc/generated/examples/builderswriting_ex2_1.xml b/doc/generated/examples/builderswriting_ex2_1.xml
index 445dfb080b..66bacd5acc 100644
--- a/doc/generated/examples/builderswriting_ex2_1.xml
+++ b/doc/generated/examples/builderswriting_ex2_1.xml
@@ -1,5 +1,5 @@
-
-% scons -Q
+
+% scons -Q
AttributeError: 'SConsEnvironment' object has no attribute 'Program':
File "/home/my/project/SConstruct", line 4:
env.Program('hello.c')
diff --git a/doc/generated/examples/builderswriting_ex3_1.xml b/doc/generated/examples/builderswriting_ex3_1.xml
index 2d8bcac86f..a2d7d4f4d7 100644
--- a/doc/generated/examples/builderswriting_ex3_1.xml
+++ b/doc/generated/examples/builderswriting_ex3_1.xml
@@ -1,5 +1,5 @@
-
-% scons -Q
+
+%