Appendix B. Builders
Prev |  | Next

## Appendix B. Builders

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 specified. 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.

  ### Note

  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 installation behavior 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 portability, it's best if the encoding is hard-coded, so that the compilation works when run 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",
      )

  ### Note

  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 is set up by the `msgfmt` tool. The builder compiles `PO` files to `MO` files. `MOFiles` is a single-source builder. The `source` parameter can also be omitted if `$LINGUAS_FILE` is set.

  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=True)

  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=True)

  Example 4. Compile files for languages defined in `LINGUAS` file (another version):

      env['LINGUAS_FILE'] = True
      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.

  ### Note

  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 hard-coded 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.

  In addition to the mandatory arguments above, the following optional values may be specified as keyword arguments:

  `auto_filter_projects`

    Under certain circumstances, solution file names or solution file nodes may be present in the `projects` argument list. When solution file names or nodes are present in the `projects` argument list, the generated solution file may contain erroneous Project records resulting in VS IDE error messages when opening the generated solution file. By default, an exception is raised when a solution file name or solution file node is detected in the `projects` argument list.

    The accepted values for `auto_filter_projects` are:

    `None`

      An exception is raised when a solution file name or solution file node is detected in the `projects` argument list.

      `None` is the default value.

    `True or evaluates True`

      Automatically remove solution file names and solution file nodes from the `projects` argument list.

    `False or evaluates False`

      Leave the solution file names and solution file nodes in the `projects` argument list. An exception is not raised.

      When opening the generated solution file with the VS IDE, the VS IDE will likely report that there are erroneous Project records that are not supported or that need to be modified.

  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.

  ### Note

  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 `$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 Manager 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]

  ### Note

  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. `PDF` is a single-source builder. 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 is set up by the `msginit` tool. The builder initializes missing `PO` file(s) if `$POAUTOINIT` is set. If `$POAUTOINIT` is not set (the default), `POInit` prints instruction for the user (such as 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. `POInit` is a single-source builder. The `source` parameter can also be omitted if `$LINGUAS_FILE` is set.

  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 the `$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=True)  # 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=True)

  Example 6. You may preconfigure your environment first, and then initialize `PO` files:

      env['POAUTOINIT'] = True
      env['LINGUAS_FILE'] = True
      env['POTDOMAIN'] = 'foo'
      env.POInit()

  which has same efect as:

      env.POInit(POAUTOINIT=True, LINGUAS_FILE=True, 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. `PostScript` is a single-source builder. 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 is set up by the `xgettext` tool, part of the `gettext` toolset. The builder updates the target `POT` file if exists or creates it if it doesn't. The target node is not selected for building by default (e.g. `scons .`), but only on demand (i.e. when the given `POT` file is required or when special alias is invoked). This builder adds its target 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).

  ### Note

  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:

      $ scons             # Does not create foo.pot nor bar.pot
      $ scons foo.pot     # Updates or creates foo.pot
      $ scons pot-update  # Updates or creates foo.pot and bar.pot
      $ scons -c          # Does not clean foo.pot nor bar.pot.

  the results shall be as the comments above say.

  Example 2. The `target` argument can be omitted, in which case the default target name `messages.pot` is used. The target may also be overridden by setting the `$POTDOMAIN` construction variable or providing it as an override to the `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 `source` parameter may also be omitted, if it is specified in a 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 can use `$XGETTEXTPATH` to define the 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 like this:

      # 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 as 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 is set up by the `msgmerge` tool. part of the `gettext` toolset. The builder updates `PO` files with msgmerge(1), or initializes missing `PO` files as described in the documentation of the `msginit` tool and the `POInit` builder (see also `$POAUTOINIT`). `POUpdate` is a single-source builder. The `source` parameter can also be omitted if `$LINGUAS_FILE` is set.

  The target nodes are not selected for building by default (e.g. `scons .`). 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`. Note that `POUpdate` does not add its targets to the `po-create` alias as `POInit` does.

  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=True)  # needs 'LINGUAS' file

  Example 5. Same as above, but update from `foo.pot` template:

      env.POUpdate(LINGUAS_FILE=True, 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=True)

  Example 7. Use `$POAUTOINIT` to automatically initialize `PO` file if it doesn't exist:

      env.POUpdate(LINGUAS_FILE=True, POAUTOINIT=True)

  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'] = True
      env['LINGUAS_FILE'] = True
      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 for the `StaticObject` builder method. 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. `SharedObject` is a single-source builder. Examples:

      env.SharedObject(target='ddd', source='ddd.c')
      env.SharedObject(target='eee.o', source='eee.cpp')
      env.SharedObject(target='fff.obj', source='fff.for')
      env.SharedObject(source=Glob('*.c'))

  On some platforms building a shared object requires additional compiler option(s) (e.g. `-fPIC` for gcc) in addition to those needed to build a normal (static) object. If shared and static objects differ, SCons will allow only shared objects to be linked into a shared library, and will use a different suffix for shared objects to help indicate and track the difference.

  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. The file extension mapping is shown in the table:

  `
  .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 (empty string 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. `StaticObject` is a single-source builder. Examples:

      env.StaticObject(target='aaa', source='aaa.c')
      env.StaticObject(target='bbb.o', source='bbb.c++')
      env.StaticObject(target='ccc.obj', source='ccc.f')
      env.StaticObject(source=Glob('*.c'))

  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 substitution, 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 further 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 wrapping 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 is part of the `gettext` toolset. The builder extracts internationalized messages from source files, updates the `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 account 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'] = True
      env.Translate(['en', 'pl'], ['../a.cpp', '../b.cpp'])

  Example 2. If you wish, you may also stick to the conventional style known from autotools, i.e. using `POTFILES.in` and `LINGUAS` files to specify the targets and sources:

      # LINGUAS
      en pl
      # end

      # POTFILES.in
      a.cpp
      b.cpp
      # end

      # SConscript
      env = Environment(tools=["default", "gettext"])
      env['POAUTOINIT'] = True
      env['XGETTEXTPATH'] = ['../']
      env.Translate(LINGUAS_FILE=True, 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). Additionally, 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 the variant directory. Write the top-level `SConstruct` script as follows

      # SConstruct
      env = Environment(tools=["default", "gettext"])
      VariantDir('build', 'src', duplicate=False)
      env['POAUTOINIT'] = True
      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=True, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])

  and the `src/po/SConscript`

      # src/po/SConscript
      Import('env')
      env.MOFiles(LINGUAS_FILE=True)

  Such a setup produces `POT` and `PO` files under the source tree in `src/po/` and binary `MO` files under the 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).

  ### Note

  In the above example, the `PO` files are not updated, nor created automatically when you issue the command `scons .`. 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')

Prev |  | Next
Appendix A. Construction Variables | Home | Appendix C. Tools