%scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]> CFile() env.CFile() Builds a C source file given a lex (.l) or yacc (.y) input file. The suffix specified by the &cv-link-CFILESUFFIX; &consvar; (.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 &b-Command; "Builder" is actually a function that looks like a Builder, but takes a required third argument, which is the action to take to construct the target from the source, used for "one-off" builds where a full builder is not needed. Thus it does not follow the builder calling rules described at the start of this section. See instead the &f-link-Command; function description for the calling syntax and details. CompilationDatabase() env.CompilationDatabase() &b-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 &cv-link-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 &t-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 &cv-link-CXXFILESUFFIX; &consvar; (.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 &cv-link-LATEXCOM; command line; otherwise, the &cv-link-TEXCOM; command line is used. If the file is a LaTeX file, the &b-DVI; builder method will also examine the contents of the .aux file and invoke the &cv-link-BIBTEX; command line if the string bibdata is found, start &cv-link-MAKEINDEX; to generate an index if a .ind file is found and will examine the contents .log file and re-run the &cv-link-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 &b-link-Java; Builder. If the &cv-link-JARCHDIR; value is set, the &jar; command will change to the specified directory using the -C option. If &cv-JARCHDIR; is not set explicitly, &SCons; will use the top of any subdirectory tree in which Java .class were built by the &b-link-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 &b-link-Java; builder method, or the objects returned from the &b-Java; builder method. If the construction variable &cv-link-JAVACLASSDIR; is set, either in the environment or in the call to the &b-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 &b-StaticLibrary; builder method. LoadableModule() env.LoadableModule() On most systems, this is the same as &b-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 &cv-link-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 &cv-link-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 &t-link-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 &cv-link-MSVS_VERSION; in the Environment constructor). For Visual Studio 6, it will generate a .dsp file. For Visual Studio 7, 8, and 9, it will generate a .vcproj file. For Visual Studio 10 and later, it will generate a .vcxproj 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 and later. This behavior may be disabled by specifying auto_build_solution=0 when you call &b-MSVSProject;, in which case you presumably want to build the solution file(s) by calling the &b-MSVSSolution; Builder (see below). The &b-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 &cv-link-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: target The name of the target .dsp or .vcproj file. The correct suffix for the version of Visual Studio must be used, but the &cv-link-MSVSPROJECTSUFFIX; construction variable will be defined to the correct value (see example below). variant 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 &b-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 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 &cv-link-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 is also possible to specify the optional argument DebugSettings, which creates files for debugging under Visual Studio: DebugSettings 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 &cv-link-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: 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 &cv-link-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 &b-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 &b-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 &t-link-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 &cv-link-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: msiMicrosoft Installer package rpmRPM Package Manger package ipkgItsy Package Management package tarbz2bzip2-compressed tar file targzgzip-compressed tar file tarxzxz-compressed tar file zipzip file src_tarbz2bzip2-compressed tar file suitable as source to another packager src_targzgzip-compressed tar file suitable as source to another packager src_tarxzxz-compressed tar file suitable as source to another packager src_zipzip 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 &f-link-FindInstalledFiles; function is called behind the scenes to select all files that have an &b-link-Install;, &b-link-InstallAs; or &b-link-InstallVersionedLib; Builder attached. If the ⌖ 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 &b-Package; builder call, and may also be attached to files (or more accurately, Nodes representing files) with the &f-link-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 &cv-link-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="http://foo.org/foo-1.2.3.tar.gz", ) In this example, the target /bin/my_program created by the &b-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 &b-Package; builder, it is selected for packaging by the default sources rule. Since packaging is done using &cv-PACKAGEROOT;, no write is actually done to the system's /bin directory, and the target will be selected since after rebasing to underneath &cv-PACKAGEROOT; it is now under the top directory of the project. 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 &cv-link-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 &t-link-msginit; tool. The builder initializes missing PO file(s) if &cv-link-POAUTOINIT; is set. If &cv-link-POAUTOINIT; is not set (default), &b-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 &b-POInit; and use &b-link-POUpdate; instead. &b-link-POUpdate; chooses intelligently between msgmerge(1) and msginit(1). &b-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 &b-POInit; are not built by default (they're Ignored from '.' node) but are added to special Alias ('po-create' by default). The alias name may be changed through the &cv-link-POCREATE_ALIAS; construction variable. All PO files defined through &b-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 &cv-link-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 &cv-link-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 &t-link-xgettext; tool. The builder updates target POT file if exists or creates one if it doesn't. The node is not built by default (i.e. it is Ignored from '.'), but only on demand (i.e. when given POT file is required or when special alias is invoked). This builder adds its targe node (messages.pot, say) to a special alias (pot-update by default, see &cv-link-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 &t-link-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 &b-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 &cv-link-POTDOMAIN; construction variable or providing it as an override to &b-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 &cv-link-XGETTEXTFROM;: # SConstruct file in 'po/' subdirectory env = Environment( tools = ['default', 'xgettext'] ) env.POTUpdate(XGETTEXTFROM = 'POTFILES.in') Example 4. You may use &cv-link-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 &t-link-msgmerge; tool. The builder updates PO files with msgmerge(1), or initializes missing PO files as described in documentation of &t-link-msginit; tool and &b-link-POInit; builder (see also &cv-link-POAUTOINIT;). Note, that &b-POUpdate; does not add its targets to po-create alias as &b-link-POInit; does. Target nodes defined through &b-POUpdate; are not built by default (they're Ignored from '.' node). Instead, they are added automatically to special Alias ('po-update' by default). The alias name may be changed through the &cv-link-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 &cv-link-POTDOMAIN;), assuming that the later one exists or there is rule to build it (see &b-link-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 &cv-link-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 &b-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 &cv-link-PROGPREFIX; &consvar; (nothing by default), and suffix, specified by the &cv-link-PROGSUFFIX; &consvar; (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 &b-Java; builder method. If the construction variable &cv-link-JAVACLASSDIR; is set, either in the environment or in the call to the &b-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 target library file prefix, specified by the &cv-link-SHLIBPREFIX; &consvar; (by default, lib on POSIX systems, nothing on Windows systems), and suffix, specified by the &cv-link-SHLIBSUFFIX; &consvar; (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 &b-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 &b-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. Any object files listed in the source must have been built for a shared library (that is, using the &b-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 &b-link-LoadableModule; builder for the latter. When the &cv-link-SHLIBVERSION; &consvar; is defined, a versioned shared library is created. This modifies &cv-link-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, versions with a single token create exactly one symlink: libbar.so.6 would have symlink 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. The command that is run is determined by the &cv-link-REGSVR; &consvar; (regsvr32 by default), and the flags passed are determined by &cv-link-REGSVRFLAGS;. By default, &cv-link-REGSVRFLAGS; includes the /s option, to prevent dialogs from popping up and requiring user attention when it is run. If you change &cv-link-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 &b-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 &cv-link-SHOBJPREFIX; &consvar; (by default, the same as &cv-link-OBJPREFIX;), and suffix, specified by the &cv-link-SHOBJSUFFIX; &consvar;, 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 file prefix, specified by the &cv-link-LIBPREFIX; &consvar; (by default, lib on POSIX systems, nothing on Windows systems), and suffix, specified by the &cv-link-LIBSUFFIX; &consvar; (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 &b-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 &cv-link-OBJPREFIX; &consvar; (nothing by default), and suffix, specified by the &cv-link-OBJSUFFIX; &consvar; (.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 section "Scanner Objects," below, for more information. Substfile() env.Substfile() The &b-Substfile; builder creates a single text file from a template consisting of a file or set of files (or nodes), replacing text using the &cv-link-SUBST_DICT; &consvar; (if set). If a set, they are concatenated into the target file using the value of the &cv-link-LINESEPARATOR; &consvar; 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 &b-link-Textfile;. 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 &cv-link-SUBSTFILEPREFIX; and &cv-link-SUBSTFILESUFFIX; &consvars; (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 &cv-link-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 &b-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 &b-Textfile; builder generates a single text file from a template consisting of a list of strings, replacing text using the &cv-link-SUBST_DICT; &consvar; (if set) - see &b-link-Substfile; for a description of replacement. The strings will be separated in the target file using the value of the &cv-link-LINESEPARATOR; &consvar;; 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 &f-link-Value; nodes The prefix and suffix specified by the &cv-link-TEXTFILEPREFIX; and &cv-link-TEXTFILESUFFIX; &consvars; (by default an empty string and .txt, 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: foo.txt Goethe 42 Schiller bar.txt lalala|*tanteratei blob.txt lalala Goethe 42 Schiller tanteratei Translate() env.Translate() This pseudo-builder belongs to &t-link-gettext; toolset. The builder extracts internationalized messages from source files, updates POT template (if necessary) and then updates PO translations (if necessary). If &cv-link-POAUTOINIT; is set, missing PO files will be automatically created (i.e. without translator person intervention). The variables &cv-link-LINGUAS_FILE; and &cv-link-POTDOMAIN; are taken into acount too. All other construction variables used by &b-link-POTUpdate;, and &b-link-POUpdate; work here too. Example 1. The simplest way is to specify input files and output languages inline in a SCons script when invoking &b-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 &b-Program;, &b-Library; and &b-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 &cv-link-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 &b-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')