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
()
There is actually no Builder named Command
,
rather the term "Command Builder" refers to
a function which, on each call, creates and calls
an anonymous Builder.
This is useful for "one-off" builds
where a full Builder is not needed.
Since the anonymous Builder is never hooked
into the standard Builder framework,
an Action must always be specfied.
See the Command
function description
for the calling syntax and details.
CompilationDatabase
(), env
.CompilationDatabase
()
CompilationDatabase
is a special builder which
adds a target to create a JSON formatted
compilation database compatible with
clang
tooling
(see the
LLVM specification).
This database is suitable for consumption by various
tools and editors who can use it to obtain build and
dependency information which otherwise would be
internal to SCons.
The builder does not require any source files to be specified,
rather it arranges to emit information about all
of the C, C++ and assembler source/output pairs
identified in the build that are not excluded by the
optional filter $COMPILATIONDB_PATH_FILTER
.
The target is subject to the usual SCons target
selection rules.
If called with no arguments,
the builder will default to a target name of
compile_commands.json
.
If called with a single positional argument, scons will "deduce" the target name from that source argument, giving it the same name, and then ignore the source. This is the usual way to call the builder if a non-default target name is wanted.
If called with either the target=
or source=
keyword arguments,
the value of the argument is taken as the target name.
If called with both, the target=
value is used and source=
is ignored.
If called with multiple sources,
the source list will be ignored,
since there is no way to deduce what the intent was;
in this case the default target name will be used.
You must load the compilation_db
tool prior to specifying
any part of your build or some source/output
files will not show up in the compilation database.
Available since scons 4.0.
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
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.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(target='/usr/local/bin', source=['foo', 'bar'])
Note that if target paths chosen for the
Install
builder (and the related InstallAs
and
InstallVersionedLib
builders) are outside the
project tree, such as in the example above,
they may not be selected for "building" by default,
since in the absence of other instructions
scons builds targets that are underneath the top directory
(the directory that contains the SConstruct
file,
usually the current directory).
Use command line targets or the Default
function
in this case.
If the --install-sandbox
command line
option is given, the target directory will be prefixed
by the directory path specified.
This is useful to test installs without installing to
a "live" location in the system.
See also FindInstalledFiles
.
For more thoughts on installation, see the User Guide
(particularly the section on Command-Line Targets
and the chapters on Installing Files and on Alias Targets).
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'])
See the note under Install
.
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')
See the note under Install
.
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", )
Java versions starting with 10.0 no longer use the
javah command for generating JNI
headers/sources, and indeed have removed the command entirely
(see Java Enhancement Proposal
JEP 313),
making this tool harder to use for that purpose.
SCons may autodiscover a javah
belonging to an older release if there are multiple Java
versions on the system, which will lead to incorrect results.
To use with a newer Java, override the default values of $JAVAH
(to contain the path to the javac)
and $JAVAHFLAGS
(to contain at least a -h
flag) and note that generating headers with
javac requires supplying source
.java
files only,
not .class
files.
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 C++ files.
This builder is only available after using the
tool qt3
. See the $QT3DIR
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
()Build a Microsoft Visual C++ project file and solution file.
Builds a Microsoft Visual C++ project file based on the
version of Visual Studio (or to be more precise, of
MSBuild)
that is configured: either the latest installed version,
or the version specified by
$MSVC_VERSION
in the current construction environment.
For Visual Studio 6.0 a .dsp
file is generated.
For Visual Studio versions 2002-2008,
a .vcproj
file is generated.
For Visual Studio 2010 and later a .vcxproj
file is generated.
Note there are multiple versioning schemes involved in
the Microsoft compilation environment -
see the description of $MSVC_VERSION
for equivalences.
Note SCons does not know how to construct project files for
other languages (e.g. .csproj
for C#,
.vbproj
for Visual Basic or
.pyproject
for Python).
For the .vcxproj
file, the underlying
format is the MSBuild XML Schema, and the details conform to:
https://learn.microsoft.com/en-us/cpp/build/reference/vcxproj-file-structure.
The generated solution file enables Visual Studio to
understand the project structure, and allows building it
using MSBuild to call back to SCons.
The project file encodes a toolset version that has been
selected by SCons as described above. Since recent Visual
Studio versions support multiple concurrent toolsets,
use $MSVC_VERSION
to select the desired one if
it does not match the SCons default.
The project file also includes entries which describe
how to call SCons to build the project from within Visual Studio
(or from an MSBuild command line).
In some situations SCons may generate this incorrectly -
notably when using the scons-local
distribution, which is not installed in a way that that
matches the default invocation line.
If so, the $SCONS_HOME
construction variable can be used to describe
the right way to locate the SCons code so that it can be imported.
By default, a matching solution file for the project is also generated.
This behavior may be disabled by
specifying auto_build_solution=0
to the MSVSProject
builder.
The solution file can also be independently
generated by calling the MSVSSolution
builder,
such as in the case where a solution should describe
multiple projects.
See the MSVSSolution
description for further information.
The MSVSProject
builder accepts several keyword arguments
describing lists of filenames to be placed into the project file.
Currently,
srcs
,
incs
,
localincs
,
resources
,
and misc
are recognized.
The names are intended to be self-explanatory, but note that the
filenames need to be specified as strings, not
as SCons File Nodes
(for example if you generate files for inclusion by using the
Glob
function, the results should be converted to
a list of strings before passing them to MSVSProject
).
This is because Visual Studio and
MSBuild know nothing about SCons
Node types.
Each of the filename lists are individually optional, but at
least one list 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 as keyword arguments:
target
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).
variant
The name of this particular variant. Except for Visual Studio 6
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.
cmdargs
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.
cppdefines
Preprocessor definitions for the different variants.
The number of cppdefines
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. If you don't give this parameter, SCons
will use the invoking environment's
$CPPDEFINES
entry for all variants.
cppflags
Compiler flags for the different variants.
If a /std:c++
flag is found then
/Zc:__cplusplus
is appended to the
flags if not already found, this ensures that Intellisense
uses the /std:c++
switch.
The number of cppflags
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. If you don't give this parameter, SCons
will combine the invoking environment's
$CCFLAGS
, $CXXFLAGS
,
$CPPFLAGS
entries for all variants.
cpppaths
Compiler include paths for the different variants.
The number of cpppaths
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. If you don't give this parameter, SCons
will use the invoking environment's
$CPPPATH
entry for all variants.
buildtarget
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.
runfile
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 Microsoft Visual C++ project file. If this is not
specified, the default is the same as the specified
buildtarget
value.
SCons and Microsoft Visual Studio understand projects in different ways, and the mapping is sometimes imperfect:
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 directory of the SConstruct
file, 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 Microsoft Visual 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.
If the project file is only used to teach the Visual Studio project browser about the file layout there should be no issues, However, Visual Studio should not be used to make changes to the project structure, build options, etc. as these will (a) not feed back to the SCons description of the project and (b) be lost if SCons regenerates the project file. The SConscript files should remain the definitive description of the build.
If the project file is used to drive
MSBuild (such as selecting
"build" from the Visual Studio interface) you lose the direct
control of target selection and command-line options you would
have if launching the build directly from SCons,
because these will be hardcoded in the project file to the
values specified in the MSVSProject
call.
You can regain some of this control by defining multiple variants,
using multiple MSVSProject
calls to arrange different build
targets, arguments, defines, flags and paths for different variants.
If the build is divided into a solution with multiple
MSBuild
projects the mapping is further strained. In this case,
it is important not to set Visual Studio to do parallel builds,
as it will then launch the separate project builds in parallel,
and SCons does not work well if called that way.
Instead you can set up the SCons build for parallel building -
see the SetOption
function for how to do this with
num_jobs
.
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', )
DebugSettings
A dictionary of debug settings that get written
to the .vcproj.user
or the
.vcxproj.user
file, depending on the
version installed. As for cmdargs
,
you can specify a DebugSettings
dictionary per variant. If you give only one, it will
be propagated to all variants.
Changed in version 2.4:
Added the optional DebugSettings
parameter.
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 C++ project 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=f'vc={msvcver}', DebugSettings=(dbgSettings, {}), )
MSVSSolution
(), env
.MSVSSolution
()Build a Microsoft Visual Studio Solution file.
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
$MSVC_VERSION
in the construction environment. For
Visual Studio 6, a .dsw
file is generated.
For Visual Studio .NET 2002 and later,
it will generate a .sln
file.
Note there are multiple versioning schemes involved in
the Microsoft compilation environment -
see the description of $MSVC_VERSION
for equivalences.
The solution file is a container for one or more projects, and follows the format described at https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file.
The following values must be specified:
target
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).
variant
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.
projects
A list of project file names, or Project nodes returned
by calls to the MSVSProject
Builder, to be placed
into the solution file.
Note that these filenames need to be specified as strings,
NOT as SCons File Nodes.
This is because the solution file will be interpreted by
MSBuild
and by Visual Studio, which know nothing about SCons Node types.
Example Usage:
env.MSVSSolution( target="Bar" + env["MSVSSOLUTIONSUFFIX"], projects=["bar" + env["MSVSPROJECTSUFFIX"]], variant="Release", )
Ninja
(), env
.Ninja
()A special builder which adds a target to create a Ninja build file. The builder does not require any source files to be specified.
This is an experimental feature. To enable it you must use one of the following methods
# On the command line --experimental=ninja # Or in your SConstruct SetOption('experimental', 'ninja')
This functionality is subject to change and/or removal without deprecation cycle.
To use this tool you need to install the Python ninja package,
as the tool by default depends on being able to do an
import
of the package
This can be done via:
python -m pip install ninja
If called with no arguments,
the builder will default to a target name of
ninja.build
.
If called with a single positional argument, scons will "deduce" the target name from that source argument, giving it the same name, and then ignore the source. This is the usual way to call the builder if a non-default target name is wanted.
If called with either the
target=
or source=
keyword arguments,
the value of the argument is taken as the target name.
If called with both, the
target=
value is used and source=
is ignored.
If called with multiple sources,
the source list will be ignored,
since there is no way to deduce what the intent was;
in this case the default target name will be used.
Available since scons 4.2.
Object
(), env
.Object
()
A synonym for the
StaticObject
builder method.
Package
(), env
.Package
()
Builds software distribution packages.
A package is a container format which
includes files to install along with metadata.
Packaging is optional, and must be enabled by specifying
the packaging
tool. For example:
env = Environment(tools=['default', 'packaging'])
SCons can build packages in a number of well known packaging formats.
The target package type may be selected with the
the $PACKAGETYPE
construction variable
or the --package-type
command line option.
The package type may be a list, in which case SCons will attempt
to build packages for each type in the list. Example:
env.Package(PACKAGETYPE=['src_zip', 'src_targz'], ...other args...
)
The currently supported packagers are:
msi | Microsoft Installer package |
rpm | RPM Package Manger package |
ipkg | Itsy Package Management package |
tarbz2 | bzip2-compressed tar file |
targz | gzip-compressed tar file |
tarxz | xz-compressed tar file |
zip | zip file |
src_tarbz2 | bzip2-compressed tar file suitable as source to another packager |
src_targz | gzip-compressed tar file suitable as source to another packager |
src_tarxz | xz-compressed tar file suitable as source to another packager |
src_zip | zip file suitable as source to another packager |
The file list to include in the package may be specified with
the source
keyword argument. If omitted,
the FindInstalledFiles
function is called behind the scenes
to select all files that have an Install
, InstallAs
or InstallVersionedLib
Builder attached.
If the target
keyword argument is omitted, the target name(s)
will be deduced from the package type(s).
The metadata comes partly from attributes of the files to be packaged,
and partly from packaging tags.
Tags can be passed as keyword arguments
to the Package
builder call,
and may also be attached to files
(or more accurately, Nodes representing files)
with the Tag
function.
Some package-level tags are mandatory, and will lead to errors if omitted.
The mandatory tags vary depending on the package type.
While packaging, the builder uses a temporary location named
by the value of the $PACKAGEROOT
variable -
the package sources are copied there before packaging.
Packaging example:
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="https://foo.org/foo-1.2.3.tar.gz", )
In this example, the target /bin/my_program
created by the Install
call would not be built by default
since it is not under the project top directory.
However, since no source
is specified to the Package
builder,
it is selected for packaging by the default sources rule.
Since packaging is done using $PACKAGEROOT
, no write is
actually done to the system's /bin
directory,
and the target will be selected since
after rebasing to underneath $PACKAGEROOT
it is now under
the top directory of the project.
PCH
(), env
.PCH
()
Builds a Microsoft Visual C++ precompiled header.
Calling this builder
returns a list of two target nodes: the PCH as the first element,
and the object file as the second element.
Normally the object file is ignored.
The PCH
builder 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]
This builder is specific to the PCH implementation in Microsoft Visual C++.
Other compiler chains also implement precompiled header support,
but PCH
does not work with them at this time.
As a result, the builder is only generated into the
construction environment when
Microsoft Visual C++ is being used as the compiler.
The builder only works correctly in a C++ project. The Microsoft implementation distinguishes between precompiled headers from C and C++. Use of the builder will cause the PCH generation to happen with a flag that tells cl.exe all of the files are C++ files; if that PCH file is then supplied when compiling a C source file, cl.exe will fail the build with a compatibility violation.
If possible, arrange the project so that a
C++ source file passed to the PCH
builder
is not also included in the list of sources
to be otherwise compiled in the project.
SCons will correctly track that file in the dependency tree
as a result of the PCH
call,
and (for MSVC 11.0 and greater) automatically add the
corresponding object file to the link line.
If the source list is automatically generated,
for example using the Glob
function,
it may be necessary to remove that file from the list.
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 to 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
given one or more object files
and/or C, C++, D or Fortran source files.
Any source files listed in the
source
parameter
will be automatically
compiled to object files suitable
for use in a shared library.
Any object files listed in the
source
parameter
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.
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 (if not already present)
to the target name to make up the library filename.
On a POSIX system, if the $SHLIBVERSION
construction variable is set,
it is appended (following a period) to the resulting library name.
Example:
env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'])
On Windows systems, the
SharedLibrary
builder method will always build an import library
(.lib
)
in addition to the shared library (.dll
),
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 library
(.dll.a
)
in addition to the shared library (.dll
),
adding a .dll.a
library with the same basename
if there is not already a .dll.a
file explicitly
listed in the targets.
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.
If $SHLIBVERSION
is defined, a versioned
shared library is created. This modifies $SHLINKFLAGS
as required,
adds the version number to the library name, and creates any
symbolic links that are needed.
env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
On a POSIX system, supplying a simple version string (no dots)
creates exactly one symbolic link: SHLIBVERSION="1"
would create (for example) library libbar.so.1
and symbolic link libbar.so
.
Supplying a dotted version string will create two symbolic links
(irrespective of the number of segments in the version):
SHLIBVERSION="1.5.2"
for the same library
would create library libbar.so.1.5.2
and symbolic links libbar.so
and
libbar.so.1
. A Darwin (OSX)
system creates one symlink in either case,
for the second example the library would be
libbar.1.5.2.dylib
and the link would be libbar.dylib
.
On Windows systems, specifying the
register=1
keyword argument
will cause the .dll
to be
registered after it is built.
The command that is run is determined by the $REGSVR
construction variable
(regsvr32 by default),
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 intended 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 manpage section "Scanner Objects"
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 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 the
SourceFileScanner
object.
See the manpage section "Scanner Objects"
for more information.
Substfile
(), env
.Substfile
()
The Substfile
builder creates a single text file from
a template consisting of a file or set of files (or nodes),
replacing text using the $SUBST_DICT
construction variable (if set).
If a set, they are concatenated into the target file
using the value of the
$LINESEPARATOR
construction variable as a separator between contents;
the separator is not emitted after the contents of the last file.
Nested lists of source files
are flattened. See also Textfile
.
By default the target file encoding is "utf-8" and can be changed by $FILE_ENCODING
Examples:
If a single source file name is specified and has a .in
suffix,
the suffix is stripped and the remainder of the name is used as the default target name.
The prefix and suffix specified by the $SUBSTFILEPREFIX
and $SUBSTFILESUFFIX
construction variables
(an empty 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
with unspecified 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']) 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 from
a template consisting of a list of strings, replacing text
using the $SUBST_DICT
construction variable (if set) -
see Substfile
for a description of replacement.
The strings will be separated in the target file using the
value of the
$LINESEPARATOR
construction variable;
the line separator is not emitted after the last string.
Nested lists of source strings
are flattened.
Source strings need not literally be Python strings:
they can be Nodes or Python objects that convert cleanly
to Value
nodes.
The prefix and suffix specified by the $TEXTFILEPREFIX
and $TEXTFILESUFFIX
construction variables
(by default an empty string and .txt
, respectively)
are automatically added to the target if they are not already present.
By default the target file encoding is "utf-8" and can be changed by $FILE_ENCODING
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:
foo.txt
Goethe 42 Schiller
bar.txt
lalala|*tanteratei
blob.txt
lalala Goethe 42 Schiller tanteratei
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 that order.
This builder is only available after using the tool qt3
.
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 $QT3DIR
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')