This appendix contains descriptions of all of the Builders that are potentially available "out of the box" in this version of SCons.
CFile()
,
env.CFile()
Builds a C source file given a lex (.l
)
or yacc (.y
) input file.
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 env.CFile(target = 'bar', source = 'bar.y')
Command()
,
env.Command()
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
for the calling syntax and details.
CXXFile()
,
env.CXXFile()
Builds a C++ source file given a lex (.ll
)
or yacc (.yy
)
input file.
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 env.CXXFile(target = 'bar', source = 'bar.yy')
DocbookEpub()
,
env.DocbookEpub()
A pseudo-Builder, providing a Docbook toolchain for EPUB output.
env = Environment(tools=['docbook']) env.DocbookEpub('manual.epub', 'manual.xml')
or simply
env = Environment(tools=['docbook']) env.DocbookEpub('manual')
DocbookHtml()
,
env.DocbookHtml()
A pseudo-Builder, providing a Docbook toolchain for HTML output.
env = Environment(tools=['docbook']) env.DocbookHtml('manual.html', 'manual.xml')
or simply
env = Environment(tools=['docbook']) env.DocbookHtml('manual')
DocbookHtmlChunked()
,
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.DocbookHtmlChunked('manual')
where manual.xml
is the input file.
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.DocbookHtmlChunked('mymanual.html', 'manual', xsl='htmlchunk.xsl')
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.DocbookHtmlChunked('manual', xsl='htmlchunk.xsl', base_dir='output/')
Make sure that you don't forget the trailing slash for the base folder, else your files get renamed only!
DocbookHtmlhelp()
,
env.DocbookHtmlhelp()
A pseudo-Builder, providing a Docbook toolchain for HTMLHELP output. Its basic syntax is:
env = Environment(tools=['docbook']) env.DocbookHtmlhelp('manual')
where manual.xml
is the input file.
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.DocbookHtmlhelp('mymanual.html', 'manual', xsl='htmlhelp.xsl')
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.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/')
Make sure that you don't forget the trailing slash for the base folder, else your files get renamed only!
DocbookMan()
,
env.DocbookMan()
A pseudo-Builder, providing a Docbook toolchain for Man page output. Its basic syntax is:
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.
DocbookPdf()
,
env.DocbookPdf()
A pseudo-Builder, providing a Docbook toolchain for PDF output.
env = Environment(tools=['docbook']) env.DocbookPdf('manual.pdf', 'manual.xml')
or simply
env = Environment(tools=['docbook']) env.DocbookPdf('manual')
DocbookSlidesHtml()
,
env.DocbookSlidesHtml()
A pseudo-Builder, providing a Docbook toolchain for HTML slides output.
env = Environment(tools=['docbook']) env.DocbookSlidesHtml('manual')
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.DocbookSlidesHtml('mymanual.html','manual', xsl='slideshtml.xsl')
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.DocbookSlidesHtml('manual', xsl='slideshtml.xsl', base_dir='output/')
Make sure that you don't forget the trailing slash for the base folder, else your files get renamed only!
DocbookSlidesPdf()
,
env.DocbookSlidesPdf()
A pseudo-Builder, providing a Docbook toolchain for PDF slides output.
env = Environment(tools=['docbook']) env.DocbookSlidesPdf('manual.pdf', 'manual.xml')
or simply
env = Environment(tools=['docbook']) env.DocbookSlidesPdf('manual')
DocbookXInclude()
,
env.DocbookXInclude()
A pseudo-Builder, for resolving XIncludes in a separate processing step.
env = Environment(tools=['docbook']) env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')
DocbookXslt()
,
env.DocbookXslt()
A pseudo-Builder, applying a given XSL transformation to the input file.
env = Environment(tools=['docbook']) env.DocbookXslt('manual_transformed.xml', 'manual.xml', xsl='transform.xslt')
Note, that this builder requires the xsl
parameter
to be set.
DVI()
,
env.DVI()
Builds a .dvi
file
from a .tex
,
.ltx
or .latex
input file.
If the source file suffix is .tex
,
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.
If the file is a LaTeX file,
the
DVI
builder method will also examine the contents
of the
.aux
file and invoke the $BIBTEX
command line
if the string
bibdata
is found,
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
if the log file says it is necessary.
The suffix .dvi
(hard-coded within TeX itself)
is automatically added to the target
if it is not already present.
Examples:
# builds from aaa.tex env.DVI(target = 'aaa.dvi', source = 'aaa.tex') # builds bbb.dvi env.DVI(target = 'bbb', source = 'bbb.ltx') # builds from ccc.latex env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
Gs()
,
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.Gs('cover.jpg','scons-scons.pdf', GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -q') )
Install()
,
env.Install()
Installs one or more source files or directories in the specified target, which must be a directory. The names of the specified source files or directories remain the same within the destination directory. The sources may be given as a string or as a node returned by a builder.
env.Install('/usr/local/bin', source = ['foo', 'bar'])
InstallAs()
,
env.InstallAs()
Installs one or more source files or directories to specific names, allowing changing a file or directory name as part of the installation. It is an error if the target and 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'], source = ['libFOO.a', 'libBAR.a'])
InstallVersionedLib()
,
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')
Jar()
,
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.
If the $JARCHDIR
value is set, the
jar
command will change to the specified directory using the
-C
option.
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.
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
command with the
m
option set.
env.Jar(target = 'foo.jar', source = 'classes') env.Jar(target = 'bar.jar', source = ['bar1.java', 'bar2.java'])
Java()
,
env.Java()
Builds one or more Java class files.
The sources may be any combination of explicit
.java
files,
or directory trees which will be scanned
for .java
files.
SCons will parse each source .java
file
to find the classes
(including inner classes)
defined within that file,
and from that figure out the
target .class
files that will be created.
The class files will be placed underneath
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
beginning with the string
package
in the first column;
the resulting .class
files
will be placed in a directory reflecting
the specified package name.
For example,
the file
Foo.java
defining a single public
Foo
class and
containing a package name of
sub.dir
will generate a corresponding
sub/dir/Foo.class
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,
which may lead to errors as the file is processed further.
In this case, the user must specify the LANG
environment variable to tell the compiler what encoding is used.
For portibility, it's best if the encoding is hard-coded
so that the compile will work if it is done on a system
with a different encoding.
env = Environment() env['ENV']['LANG'] = 'en_GB.UTF-8'
JavaH()
,
env.JavaH()
Builds C header and source files for
implementing Java native methods.
The target can be either a directory
in which the header files will be written,
or a header file name which
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,
or the objects returned from the
Java
builder method.
If the construction variable
$JAVACLASSDIR
is set, either in the environment
or in the call to the
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) # builds include/package_foo.h and include/package_bar.h env.JavaH(target = 'include', source = ['package/foo.class', 'package/bar.class']) # builds export/foo.h and export/bar.h env.JavaH(target = 'export', source = ['classes/foo.class', 'classes/bar.class'], JAVACLASSDIR = 'classes')
Library()
,
env.Library()
A synonym for the
StaticLibrary
builder method.
LoadableModule()
,
env.LoadableModule()
On most systems,
this is the same as
SharedLibrary
.
On Mac OS X (Darwin) platforms,
this creates a loadable module bundle.
M4()
,
env.M4()
Builds an output file from an M4 input file.
This uses a default $M4FLAGS
value of
-E
,
which considers all warnings to be fatal
and stops on the first warning
when using the GNU version of m4.
Example:
env.M4(target = 'foo.c', source = 'foo.c.m4')
Moc()
,
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.
Example:
env.Moc('foo.h') # generates moc_foo.cc env.Moc('foo.cpp') # generates foo.moc
MOFiles()
,
env.MOFiles()
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()
MSVSProject()
,
env.MSVSProject()
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
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
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
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.
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 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 above lists of values, the following values may be specified:
The name of the target .dsp
or
.vcproj
file. The correct suffix for the version
of Visual Studio must be used, but the $MSVSPROJECTSUFFIX
construction variable will be defined to the correct value (see
example below).
The name of this particular variant. For Visual Studio 7
projects, this can also be a list of variant names. These are
typically things like "Debug" or "Release", but really can be anything
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
different variants are allowed; all variants will be added to the
project file with their appropriate build targets and
sources.
Additional command line arguments for the different
variants. The number of cmdargs
entries must match
the number of variant
entries, or be empty (not
specified). If you give only one, it will automatically be propagated
to all variants.
An optional string, node, or list of strings or nodes (one
per build variant), to tell the Visual Studio debugger what output
target to use in what build variant. The number of
buildtarget
entries must match the number of
variant
entries.
The name of the file that Visual Studio 7 and later will
run and debug. This appears as the value of the
Output
field in the resulting Visual Studio project
file. If this is not specified, the default is the same as the
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
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
print the full path name of any files that cause compilation errors.
Example usage:
barsrcs = ['bar.cpp'] barincs = ['bar.h'] barlocalincs = ['StdAfx.h'] barresources = ['bar.rc','resource.h'] barmisc = ['bar_readme.txt'] dll = env.SharedLibrary(target = 'bar.dll', source = barsrcs) buildtarget = [s for s in dll if str(s).endswith('dll')] env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'], srcs = barsrcs, incs = barincs, localincs = barlocalincs, resources = barresources, misc = barmisc, buildtarget = buildtarget, variant = 'Release')
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:
A dictionary of debug settings that get written to the
.vcproj.user
or the
.vcxproj.user
file, depending on the version
installed. As it is done for cmdargs (see above), you can specify a
DebugSettings
dictionary per variant. If you
give only one, it will be propagated to all variants.
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 is a more contrived example, involving the setup of a project for variants and DebugSettings:
# Assuming you store your defaults in a file vars = Variables('variables.py') msvcver = vars.args.get('vc', '9') # Check command args to force one Microsoft Visual Studio version if msvcver == '9' or msvcver == '11': env = Environment(MSVC_VERSION=msvcver+'.0', MSVC_BATCH=False) else: env = Environment() AddOption('--userfile', action='store_true', dest='userfile', default=False, help="Create Visual Studio Project user file") # # 1. Configure your Debug Setting dictionary with options you want in the list # of allowed options, for instance if you want to create a user file to launch # a specific application for testing your dll with Microsoft Visual Studio 2008 (v9): # V9DebugSettings = { 'Command':'c:\\myapp\\using\\thisdll.exe', 'WorkingDirectory': 'c:\\myapp\\using\\', 'CommandArguments': '-p password', # 'Attach':'false', # 'DebuggerType':'3', # 'Remote':'1', # 'RemoteMachine': None, # 'RemoteCommand': None, # 'HttpUrl': None, # 'PDBPath': None, # 'SQLDebugging': None, # 'Environment': '', # 'EnvironmentMerge':'true', # 'DebuggerFlavor': None, # 'MPIRunCommand': None, # 'MPIRunArguments': None, # 'MPIRunWorkingDirectory': None, # 'ApplicationCommand': None, # 'ApplicationArguments': None, # 'ShimCommand': None, # 'MPIAcceptMode': None, # 'MPIAcceptFilter': None, } # # 2. Because there are a lot of different options depending on the Microsoft # Visual Studio version, if you use more than one version you have to # define a dictionary per version, for instance if you want to create a user # file to launch a specific application for testing your dll with Microsoft # Visual Studio 2012 (v11): # V10DebugSettings = { 'LocalDebuggerCommand': 'c:\\myapp\\using\\thisdll.exe', 'LocalDebuggerWorkingDirectory': 'c:\\myapp\\using\\', 'LocalDebuggerCommandArguments': '-p password', # 'LocalDebuggerEnvironment': None, # 'DebuggerFlavor': 'WindowsLocalDebugger', # 'LocalDebuggerAttach': None, # 'LocalDebuggerDebuggerType': None, # 'LocalDebuggerMergeEnvironment': None, # 'LocalDebuggerSQLDebugging': None, # 'RemoteDebuggerCommand': None, # 'RemoteDebuggerCommandArguments': None, # 'RemoteDebuggerWorkingDirectory': None, # 'RemoteDebuggerServerName': None, # 'RemoteDebuggerConnection': None, # 'RemoteDebuggerDebuggerType': None, # 'RemoteDebuggerAttach': None, # 'RemoteDebuggerSQLDebugging': None, # 'DeploymentDirectory': None, # 'AdditionalFiles': None, # 'RemoteDebuggerDeployDebugCppRuntime': None, # 'WebBrowserDebuggerHttpUrl': None, # 'WebBrowserDebuggerDebuggerType': None, # 'WebServiceDebuggerHttpUrl': None, # 'WebServiceDebuggerDebuggerType': None, # 'WebServiceDebuggerSQLDebugging': None, } # # 3. Select the dictionary you want depending on the version of visual Studio # Files you want to generate. # if not env.GetOption('userfile'): dbgSettings = None elif env.get('MSVC_VERSION', None) == '9.0': dbgSettings = V9DebugSettings elif env.get('MSVC_VERSION', None) == '11.0': dbgSettings = V10DebugSettings else: dbgSettings = None # # 4. Add the dictionary to the DebugSettings keyword. # barsrcs = ['bar.cpp', 'dllmain.cpp', 'stdafx.cpp'] barincs = ['targetver.h'] barlocalincs = ['StdAfx.h'] barresources = ['bar.rc','resource.h'] barmisc = ['ReadMe.txt'] dll = env.SharedLibrary(target = 'bar.dll', source = barsrcs) env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'], srcs = barsrcs, incs = barincs, localincs = barlocalincs, resources = barresources, misc = barmisc, buildtarget = [dll[0]] * 2, variant = ('Debug|Win32', 'Release|Win32'), cmdargs = 'vc=%s' % msvcver, DebugSettings = (dbgSettings, {}))
MSVSSolution()
,
env.MSVSSolution()
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
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:
The 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
example below).
The name of this particular variant, or a list of variant names (the latter is only supported for MSVS 7 solutions). These are typically things like "Debug" or "Release", but really can be anything you want. For MSVS 7 they may also specify target platform, like this "Debug|Xbox". Default platform is Win32.
A list of project file names, or Project nodes returned by
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
file, not the source files used to build the solution
file.
Example Usage:
env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'], projects = ['bar' + env['MSVSPROJECTSUFFIX']], variant = 'Release')
Object()
,
env.Object()
A synonym for the
StaticObject
builder method.
Package()
,
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
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.
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
the following packagers available:
* msi - Microsoft Installer * rpm - Redhat Package Manger * ipkg - Itsy Package Management System * tarbz2 - compressed tar * targz - compressed tar * zip - zip file * src_tarbz2 - compressed tar source * src_targz - compressed tar source * 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', VERSION = '1.2.3', PACKAGEVERSION = 0, PACKAGETYPE = 'rpm', LICENSE = 'gpl', SUMMARY = 'balalalalal', DESCRIPTION = 'this should be really really long', X_RPM_GROUP = 'Application/fu', SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz' )
PCH()
,
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 file as the second element. Normally the object file is ignored. This builder method is only provided when Microsoft Visual C++ is being used as the compiler. The PCH builder method is generally used in conjunction with the PCH construction variable to force object files to use the precompiled header:
env['PCH'] = env.PCH('StdAfx.cpp')[0]
PDF()
,
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
(.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 env.PDF(target = 'bbb', source = 'bbb.dvi')
POInit()
,
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
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
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
Ignore
d from '.'
node) but are added to
special Alias
('po-create'
by default).
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.
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
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.pl
PO
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')
PostScript()
,
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
(.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 env.PostScript(target = 'bbb', source = 'bbb.dvi')
POTUpdate()
,
env.POTUpdate()
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 Ignore
d 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
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
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
POT
file to decide whether the file should be updated or
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
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:
# SConstruct script env = Environment( tools = ['default', 'xgettext'] ) env['POTDOMAIN'] = "foo" env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ... env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
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
:
# 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
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
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"
.
POUpdate()
,
env.POUpdate()
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 POUpdate
does not add its
targets to po-create
alias as POInit
does.
Target nodes defined through POUpdate
are not built by default
(they're Ignore
d 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
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
),
assuming that the later one exists or there is rule to build it (see
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
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 env['POTDOMAIN'] = 'foo' env.POUpdate()
Program()
,
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
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)
and suffix
(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'])
ProgramAllAtOnce()
,
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
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
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
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.
RES()
,
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
.res
(or
.o
for MinGW) suffix is added to the target name if no other suffix is given.
The source
file is scanned for implicit dependencies as though it were a C file.
Example:
env.RES('resource.rc')
RMIC()
,
env.RMIC()
Builds stub and skeleton class files
for remote objects
from Java .class
files.
The target is a directory
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
builder method.
If the construction variable
$JAVACLASSDIR
is set, either in the environment
or in the call to the
RMIC
builder method itself,
then the value of the variable
will be stripped from the
beginning of any .class
file names.
classes = env.Java(target = 'classdir', source = 'src') env.RMIC(target = 'outdir1', source = classes) env.RMIC(target = 'outdir2', source = ['package/foo.class', 'package/bar.class']) env.RMIC(target = 'outdir3', source = ['classes/foo.class', 'classes/bar.class'], JAVACLASSDIR = 'classes')
RPCGenClient()
,
env.RPCGenClient()
Generates an RPC client stub (_clnt.c
) file
from a specified RPC (.x
) source file.
Because rpcgen only builds output files
in the local directory,
the command will be executed
in the source file's directory by default.
# Builds src/rpcif_clnt.c env.RPCGenClient('src/rpcif.x')
RPCGenHeader()
,
env.RPCGenHeader()
Generates an RPC header (.h
) file
from a specified RPC (.x
) source file.
Because rpcgen only builds output files
in the local directory,
the command will be executed
in the source file's directory by default.
# Builds src/rpcif.h env.RPCGenHeader('src/rpcif.x')
RPCGenService()
,
env.RPCGenService()
Generates an RPC server-skeleton (_svc.c
) file
from a specified RPC (.x
) source file.
Because rpcgen only builds output files
in the local directory,
the command will be executed
in the source file's directory by default.
# Builds src/rpcif_svc.c env.RPCGenClient('src/rpcif.x')
RPCGenXDR()
,
env.RPCGenXDR()
Generates an RPC XDR routine (_xdr.c
) file
from a specified RPC (.x
) source file.
Because rpcgen only builds output files
in the local directory,
the command will be executed
in the source file's directory by default.
# Builds src/rpcif_xdr.c env.RPCGenClient('src/rpcif.x')
SharedLibrary()
,
env.SharedLibrary()
Builds a shared library
(.so
on a POSIX system,
.dll
on Windows)
given one or more object files
or C, C++, D or Fortran source files.
If any source files are given,
then they will be automatically
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;
by default, lib
on POSIX systems,
nothing on Windows systems)
and suffix
(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
builder method will always build an import
(.lib
) library
in addition to the shared (.dll
) library,
adding a .lib
library with the same basename
if there is not already a .lib
file explicitly
listed in the targets.
On Cygwin systems, the
SharedLibrary
builder method will always build an import
(.dll.a
) library
in addition to the shared (.dll
) library,
adding a .dll.a
library with the same basename
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
builder method).
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.
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 tokens create exactly two symlinks: libbar.so.2.3.1 would have symlinks 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 /s
option,
to prevent dialogs from popping
up and requiring user attention when it is run. If you change
$REGSVRFLAGS
, be sure to include the /s
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.
SharedObject()
,
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
builder method.
On some platforms building a shared object requires additional
compiler option
(e.g. -fPIC
for gcc)
in addition to those needed to build a
normal (static) object, but on some platforms there is no difference between a
shared object and a normal (static) one. When there is a difference, SCons
will only allow shared objects to be linked into a shared library, and will
use a different suffix for shared objects. On platforms where there is no
difference, SCons will allow both normal (static)
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
)
and suffix
(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
object.
See the section "Scanner Objects,"
below, for more information.
StaticLibrary()
,
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,
then they will be automatically
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;
by default, lib
on POSIX systems,
nothing on Windows systems)
and suffix
(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
builder method).
scons
will raise an error if there is any mismatch.
StaticObject()
,
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 .C Windows: C file POSIX: C++ file .cc C++ file .cpp C++ file .cxx C++ file .cxx C++ file .c++ C++ file .C++ C++ file .d D file .f Fortran file .F Windows: Fortran file POSIX: Fortran file + C pre-processor .for Fortran file .FOR Fortran file .fpp Fortran file + C pre-processor .FPP Fortran file + C pre-processor .m Object C file .mm Object C++ file .s assembly language file .S Windows: assembly language file ARM: CodeSourcery Sourcery Lite .sx assembly language file + C pre-processor POSIX: assembly language file + C pre-processor .spp assembly language file + C pre-processor .SPP assembly language file + C pre-processor
The target object file prefix
(specified by the $OBJPREFIX
construction variable; nothing by default)
and suffix
(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
object.
See the section "Scanner Objects,"
below, for more information.
Substfile()
,
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
.
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 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,
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
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. If the value is a callable, it is called with no arguments to get a string. Strings are subst-expanded and the result replaces the key.
env = Environment(tools = ['default', 'textfile']) env['prefix'] = '/usr/bin' script_dict = {'@prefix@': '/bin', '@exec_prefix@': '$prefix'} env.Substfile('script.in', SUBST_DICT = script_dict) conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'} env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict) # UNPREDICTABLE - one key is a prefix of another bad_foo = {'$foo': '$foo', '$foobar': '$foobar'} env.Substfile('foo.in', SUBST_DICT = bad_foo) # PREDICTABLE - keys are applied longest first good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')] env.Substfile('foo.in', SUBST_DICT = good_foo) # UNPREDICTABLE - one substitution could be futher expanded bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'} env.Substfile('bar.in', SUBST_DICT = bad_bar) # PREDICTABLE - substitutions are expanded in order good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye')) env.Substfile('bar.in', SUBST_DICT = good_bar) # the SUBST_DICT may be in common (and not an override) substutions = {} subst = Environment(tools = ['textfile'], SUBST_DICT = substitutions) substitutions['@foo@'] = 'foo' subst['SUBST_DICT']['@bar@'] = 'bar' subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm1.in" ]) subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm2.in" ])
Tar()
,
env.Tar()
Builds a tar archive of the specified files
and/or directories.
Unlike most builder methods,
the
Tar
builder method may be called multiple times
for a given target;
each additional call
adds to the list of entries
that will be built into the archive.
Any source directories will
be scanned for changes to
any on-disk files,
regardless of whether or not
scons
knows about them from other Builder or function calls.
env.Tar('src.tar', 'src') # Create the stuff.tar file. env.Tar('stuff', ['subdir1', 'subdir2']) # Also add "another" to the stuff.tar file. env.Tar('stuff', 'another') # Set TARFLAGS to create a gzip-filtered archive. env = Environment(TARFLAGS = '-c -z') env.Tar('foo.tar.gz', 'foo') # Also set the suffix to .tgz. env = Environment(TARFLAGS = '-c -z', TARSUFFIX = '.tgz') env.Tar('foo')
Textfile()
,
env.Textfile()
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.
If present, the $SUBST_DICT
construction variable
is used to modify the strings before they are written;
see the Substfile
description for details.
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']) # builds/writes bar.txt env.Textfile(target = 'bar', source = ['lalala', 'tanteratei'], LINESEPARATOR='|*') # nested lists are flattened automatically env.Textfile(target = 'blob', source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei']) # files may be used as input by wraping them in File() env.Textfile(target = 'concat', # concatenate files with a marker between source = [File('concat1'), File('concat2')], LINESEPARATOR = '====================\n') Results are: foo.txt ....8<---- Goethe 42 Schiller ....8<---- (no linefeed at the end) bar.txt: ....8<---- lalala|*tanteratei ....8<---- (no linefeed at the end) blob.txt ....8<---- lalala Goethe 42 Schiller tanteratei ....8<---- (no linefeed at the end)
Translate()
,
env.Translate()
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
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.
Example 1.
The simplest way is to specify input files and output languages inline in
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 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
PO
files) and script(s) under variant directories are
responsible for compilation of PO
to MO
files to and for installation of MO
files. The "gluing
factor" synchronizing these two scripts is then the content of
LINGUAS
file. Note, that the updated
POT
and PO
files are usually going to be
committed back to the repository, so they must be updated within the source
directory (and not in variant directories). Additionaly, the file listing of
po/
directory contains LINGUAS
file,
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/ + src/ + po/ + SConscript + SConscript.i18n + 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) env['POAUTOINIT'] = 1 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
build/po/
. This way the POT
and
PO
files are separated from other output files, which must
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
po-update and then MO
files can be compiled by
running scons '.'.
TypeLibrary()
,
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
proxy source files,
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
,
foo_p.c
and
foo_data.c
files.
Uic()
,
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
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.
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']
Zip()
,
env.Zip()
Builds a zip archive of the specified files
and/or directories.
Unlike most builder methods,
the
Zip
builder method may be called multiple times
for a given target;
each additional call
adds to the list of entries
that will be built into the archive.
Any source directories will
be scanned for changes to
any on-disk files,
regardless of whether or not
scons
knows about them from other Builder or function calls.
env.Zip('src.zip', 'src') # Create the stuff.zip file. env.Zip('stuff', ['subdir1', 'subdir2']) # Also add "another" to the stuff.tar file. env.Zip('stuff', 'another')