Builders

SCons User Guide 0.98.0
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')

`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')

`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')

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

      env.Install('/usr/local/bin', source = ['foo', 'bar'])

`InstallAs()`, `env.InstallAs()`

  Installs one or more source files or directories to specific names, allowing changing a file or directory name as part of the installation. It is an error if the target and source arguments list different numbers of files or directories.

      env.InstallAs(target = '/usr/local/bin/foo',
                    source = 'foo_debug')
      env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
                    source = ['libFOO.a', 'libBAR.a'])

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

  Example:

      env.Java(target = 'classes', source = 'src')
      env.Java(target = 'classes', source = ['src1', 'src2'])
      env.Java(target = 'classes', source = ['File1.java', 'File2.java'])

`JavaH()`, `env.JavaH()`

  Builds C header and source files for implementing Java native methods. The target can be either a directory in which the header files will be written, or a header file name which will contain all of the definitions. The source can be the names of `.class` files, the names of `.java` files to be compiled into `.class` files by calling the `Java` builder method, or the objects returned from the `Java` builder method.

  If the construction variable `$JAVACLASSDIR` is set, either in the environment or in the call to the `JavaH` builder method itself, then the value of the variable will be stripped from the beginning of any `.class` file names.

  Examples:

      # builds java_native.h
      classes = env.Java(target = 'classdir', source = 'src')
      env.JavaH(target = 'java_native.h', source = classes)

      # builds include/package_foo.h and include/package_bar.h
      env.JavaH(target = 'include',
                source = ['package/foo.class', 'package/bar.class'])

      # builds export/foo.h and export/bar.h
      env.JavaH(target = 'export',
                source = ['classes/foo.class', 'classes/bar.class'],
                JAVACLASSDIR = 'classes')

`Library()`, `env.Library()`

  A synonym for the `StaticLibrary` builder method.

`LoadableModule()`, `env.LoadableModule()`

  On most systems, this is the same as `SharedLibrary`. On Mac OS X (Darwin) platforms, this creates a loadable module bundle.

`M4()`, `env.M4()`

  Builds an output file from an M4 input file. This uses a default `$M4FLAGS` value of `-E`, which considers all warnings to be fatal and stops on the first warning when using the GNU version of m4. Example:

      env.M4(target = 'foo.c', source = 'foo.c.m4')

`Moc()`, `env.Moc()`

  Builds an output file from a moc input file. Moc input files are either header files or cxx files. This builder is only available after using the tool 'qt'. See the `$QTDIR` variable for more information. Example:

      env.Moc('foo.h') # generates moc_foo.cc
      env.Moc('foo.cpp') # generates foo.moc

`MSVSProject()`, `env.MSVSProject()`

  Builds a Microsoft Visual Studio project file, and by default builds a solution file as well.

  This builds a Visual Studio project file, based on the version of Visual Studio that is configured (either the latest installed version, or the version specified by `$MSVS_VERSION` in the Environment constructor). For Visual Studio 6, it will generate a `.dsp` file. For Visual Studio 7 (.NET) and later versions, it will generate a `.vcproj` file.

  By default, this also generates a solution file for the specified project, a `.dsw` file for Visual Studio 6 or a `.sln` file for Visual Studio 7 (.NET). This behavior may be disabled by specifying `auto_build_solution=0` when you call `MSVSProject`, in which case you presumably want to build the solution file(s) by calling the `MSVSSolution` Builder (see below).

  It takes several lists of filenames to be placed into the project file. These are currently limited to `srcs`, `incs`, `localincs`, `resources`, and `misc`. These are pretty self-explanatory, but it should be noted that these lists are added to the `$SOURCES` construction variable as strings, NOT as SCons File Nodes. This is because they represent file names to be added to the project file, not the source files used to build the project file.

  The above filename lists are all optional, although at least one must be specified for the resulting project file to be non-empty.

  In addition to the above lists of values, the following values may be specified:

  `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. For Visual Studio 7 projects, this can also be a list of variant names. These are typically things like "Debug" or "Release", but really can be anything you want. For Visual Studio 7 projects, they may also specify a target platform separated from the variant name by a `|` (vertical pipe) character: `Debug|Xbox`. The default target platform is Win32. Multiple calls to `MSVSProject` with different variants are allowed; all variants will be added to the project file with their appropriate build targets and sources.

  `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 resutling Visual Studio project file. If this is not specified, the default is the same as the specified `buildtarget` value.

  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)

      env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
                      srcs = barsrcs,
                      incs = barincs,
                      localincs = barlocalincs,
                      resources = barresources,
                      misc = barmisc,
                      buildtarget = dll,
                      variant = 'Release')

`MSVSSolution()`, `env.MSVSSolution()`

  Builds a Microsoft Visual Studio solution file.

  This builds a Visual Studio solution file, based on the version of Visual Studio that is configured (either the latest installed version, or the version specified by `$MSVS_VERSION` in the construction environment). For Visual Studio 6, it will generate a `.dsw` file. For Visual Studio 7 (.NET), it will generate a `.sln` file.

  The following values must be specified:

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

  (NOTE: Currently only one project is supported per solution.)

  Example Usage:

      env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
                       projects = ['bar' + env['MSVSPROJECTSUFFIX']],
                       variant = 'Release')

`Object()`, `env.Object()`

  A synonym for the `StaticObject` builder method.

`Package()`, `env.Package()`

  Builds software distribution packages. Packages consist of files to install and packaging information. The former may be specified with the `source` parameter and may be left out, in which case the `FindInstalledFiles` function will collect all files that have an `Install` or `InstallAs` Builder attached. If the `target`, is not specified it will be deduced from additional information given to this Builder.

  The packaging information is specified with the help of construction variables documented below. This information is called a tag to stress that some of them can also be attached to files with the `Tag` function. The mandatory ones will complain if they were not specified. They vary depending on chosen target packager.

  The target packager may be selected with the "PACKAGETYPE" command line option or with the `$PACKAGETYPE` construction variable. Currently the following packagers available:

  * msi - Microsoft Installer * rpm - Redhat Package Manger * ipkg - Itsy Package Management System * tarbz2 - compressed tar * targz - compressed tar * zip - zip file * src_tarbz2 - compressed tar source * src_targz - compressed tar source * src_zip - zip file source

  An updated list is always available under the "package_type" option when running "scons --help" on a project that has packaging activated.

      env = Environment(tools=['default', 'packaging'])
      env.Install('/bin/', 'my_program')
      env.Package( NAME           = 'foo',
                   VERSION        = '1.2.3',
                   PACKAGEVERSION = 0,
                   PACKAGETYPE    = 'rpm',
                   LICENSE        = 'gpl',
                   SUMMARY        = 'balalalalal',
                   DESCRIPTION    = 'this should be really really long',
                   X_RPM_GROUP    = 'Application/fu',
                   SOURCE_URL     = 'http://foo.org/foo-1.2.3.tar.gz'
              )

`PCH()`, `env.PCH()`

  Builds a Microsoft Visual C++ precompiled header. Calling this builder method returns a list of two targets: the PCH as the first element, and the object file as the second element. Normally the object file is ignored. This builder method is only provided when Microsoft Visual C++ is being used as the compiler. The PCH builder method is generally used in conjuction with the PCH construction variable to force object files to use the precompiled header:

      env['PCH'] = env.PCH('StdAfx.cpp')[0]

`PDF()`, `env.PDF()`

  Builds a `.pdf` file from a `.dvi` input file (or, by extension, a `.tex`, `.ltx`, or `.latex` input file). The suffix specified by the `$PDFSUFFIX` construction variable (`.pdf` by default) is added automatically to the target if it is not already present. Example:

      # builds from aaa.tex
      env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
      # builds bbb.pdf from bbb.dvi
      env.PDF(target = 'bbb', source = 'bbb.dvi')

`PostScript()`, `env.PostScript()`

  Builds a `.ps` file from a `.dvi` input file (or, by extension, a `.tex`, `.ltx`, or `.latex` input file). The suffix specified by the `$PSSUFFIX` construction variable (`.ps` by default) is added automatically to the target if it is not already present. Example:

      # builds from aaa.tex
      env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
      # builds bbb.ps from bbb.dvi
      env.PostScript(target = 'bbb', source = 'bbb.dvi')

`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'])

`RES()`, `env.RES()`

  Builds a Microsoft Visual C++ resource file. This builder method is only provided when Microsoft Visual C++ or MinGW is being used as the compiler. The `.res` (or `.o` for MinGW) suffix is added to the target name if no other suffix is given. The source file is scanned for implicit dependencies as though it were a C file. Example:

      env.RES('resource.rc')

`RMIC()`, `env.RMIC()`

  Builds stub and skeleton class files for remote objects from Java `.class` files. The target is a directory relative to which the stub and skeleton class files will be written. The source can be the names of `.class` files, or the objects return from the `Java` builder method.

  If the construction variable `$JAVACLASSDIR` is set, either in the environment or in the call to the `RMIC` builder method itself, then the value of the variable will be stripped from the beginning of any `.class` file names.

      classes = env.Java(target = 'classdir', source = 'src')
      env.RMIC(target = 'outdir1', source = classes)

      env.RMIC(target = 'outdir2',
               source = ['package/foo.class', 'package/bar.class'])

      env.RMIC(target = 'outdir3',
               source = ['classes/foo.class', 'classes/bar.class'],
               JAVACLASSDIR = 'classes')

`RPCGenClient()`, `env.RPCGenClient()`

  Generates an RPC client stub (`_clnt.c`) file from a specified RPC (`.x`) source file. Because rpcgen only builds output files in the local directory, the command will be executed in the source file's directory by default.

      # Builds src/rpcif_clnt.c
      env.RPCGenClient('src/rpcif.x')

`RPCGenHeader()`, `env.RPCGenHeader()`

  Generates an RPC header (`.h`) file from a specified RPC (`.x`) source file. Because rpcgen only builds output files in the local directory, the command will be executed in the source file's directory by default.

      # Builds src/rpcif.h
      env.RPCGenHeader('src/rpcif.x')

`RPCGenService()`, `env.RPCGenService()`

  Generates an RPC server-skeleton (`_svc.c`) file from a specified RPC (`.x`) source file. Because rpcgen only builds output files in the local directory, the command will be executed in the source file's directory by default.

      # Builds src/rpcif_svc.c
      env.RPCGenClient('src/rpcif.x')

`RPCGenXDR()`, `env.RPCGenXDR()`

  Generates an RPC XDR routine (`_xdr.c`) file from a specified RPC (`.x`) source file. Because rpcgen only builds output files in the local directory, the command will be executed in the source file's directory by default.

      # Builds src/rpcif_xdr.c
      env.RPCGenClient('src/rpcif.x')

`SharedLibrary()`, `env.SharedLibrary()`

  Builds a shared library (`.so` on a POSIX system, `.dll` on Windows) given one or more object files or C, C++, D or Fortran source files. If any source files are given, then they will be automatically compiled to object files. The static library prefix and suffix (if any) are automatically added to the target. The target library file prefix (specified by the `$SHLIBPREFIX` construction variable; by default, `lib` on POSIX systems, nothing on Windows systems) and suffix (specified by the `$SHLIBSUFFIX` construction variable; by default, `.dll` on Windows systems, `.so` on POSIX systems) are automatically added to the target if not already present. Example:

      env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])

  On Windows systems, the `SharedLibrary` builder method will always build an import (`.lib`) library in addition to the shared (`.dll`) library, adding a `.lib` library with the same basename if there is not already a `.lib` file explicitly listed in the targets.

  Any object files listed in the `source` must have been built for a shared library (that is, using the `SharedObject` builder method). scons will raise an error if there is any mismatch.

  On Windows systems, specifying `register=1` will cause the `.dll` to be registered after it is built using REGSVR32. The command that is run ("regsvr32" by default) is determined by `$REGSVR` construction variable, and the flags passed are determined by `$REGSVRFLAGS`. By default, `$REGSVRFLAGS` includes the `/s` option, to prevent dialogs from popping up and requiring user attention when it is run. If you change `$REGSVRFLAGS`, be sure to include the `/s` option. For example,

      env.SharedLibrary(target = 'bar',
                        source = ['bar.cxx', 'foo.obj'],
                        register=1)

  will register `bar.dll` as a COM object when it is done linking it.

`SharedObject()`, `env.SharedObject()`

  Builds an object file for inclusion in a shared library. Source files must have one of the same set of extensions specified above for the `StaticObject` builder method. On some platforms building a shared object requires additional compiler option (e.g. `-fPIC` for gcc) in addition to those needed to build a normal (static) object, but on some platforms there is no difference between a shared object and a normal (static) one. When there is a difference, SCons will only allow shared objects to be linked into a shared library, and will use a different suffix for shared objects. On platforms where there is no difference, SCons will allow both normal (static) and shared objects to be linked into a shared library, and will use the same suffix for shared and normal (static) objects. The target object file prefix (specified by the `$SHOBJPREFIX` construction variable; by default, the same as `$OBJPREFIX`) and suffix (specified by the `$SHOBJSUFFIX` construction variable) are automatically added to the target if not already present. Examples:

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

  Note that the source files will be scanned according to the suffix mappings in the `SourceFileScanner` object. See the section "Scanner Objects," below, for a more information.

`StaticLibrary()`, `env.StaticLibrary()`

  Builds a static library given one or more object files or C, C++, D or Fortran source files. If any source files are given, then they will be automatically compiled to object files. The static library prefix and suffix (if any) are automatically added to the target. The target library file prefix (specified by the `$LIBPREFIX` construction variable; by default, `lib` on POSIX systems, nothing on Windows systems) and suffix (specified by the `$LIBSUFFIX` construction variable; by default, `.lib` on Windows systems, `.a` on POSIX systems) are automatically added to the target if not already present. Example:

      env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])

  Any object files listed in the `source` must have been built for a static library (that is, using the `StaticObject` builder method). scons will raise an error if there is any mismatch.

`StaticObject()`, `env.StaticObject()`

  Builds a static object file from one or more C, C++, D, or Fortran source files. Source files must have one of the following extensions:

        .asm    assembly language file
        .ASM    assembly language file
        .c      C file
        .C      Windows:  C file
                POSIX:  C++ file
        .cc     C++ file
        .cpp    C++ file
        .cxx    C++ file
        .cxx    C++ file
        .c++    C++ file
        .C++    C++ file
        .d      D file
        .f      Fortran file
        .F      Windows:  Fortran file
                POSIX:  Fortran file + C pre-processor
        .for    Fortran file
        .FOR    Fortran file
        .fpp    Fortran file + C pre-processor
        .FPP    Fortran file + C pre-processor
        .m      Object C file
        .mm     Object C++ file
        .s      assembly language file
        .S      Windows:  assembly language file
                POSIX:  assembly language file + C pre-processor
        .spp    assembly language file + C pre-processor
        .SPP    assembly language file + C pre-processor

  The target object file prefix (specified by the `$OBJPREFIX` construction variable; nothing by default) and suffix (specified by the `$OBJSUFFIX` construction variable; `.obj` on Windows systems, `.o` on POSIX systems) are automatically added to the target if not already present. Examples:

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

  Note that the source files will be scanned according to the suffix mappings in `SourceFileScanner` object. See the section "Scanner Objects," below, for a more information.

`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')

`TypeLibrary()`, `env.TypeLibrary()`

  Builds a Windows type library (`.tlb`) file from an input IDL file (`.idl`). In addition, it will build the associated inteface stub and proxy source files, naming them according to the base name of the `.idl` file. For example,

      env.TypeLibrary(source="foo.idl")

  Will create `foo.tlb`, `foo.h`, `foo_i.c`, `foo_p.c` and `foo_data.c` files.

`Uic()`, `env.Uic()`

  Builds a header file, an implementation file and a moc file from an ui file. and returns the corresponding nodes in the above order. This builder is only available after using the tool 'qt'. Note: you can specify `.ui` files directly as source files to the `Program`, `Library` and `SharedLibrary` builders without using this builder. Using this builder lets you override the standard naming conventions (be careful: prefixes are always prepended to names of built files; if you don't want prefixes, you may set them to ``). See the `$QTDIR` variable for more information. Example:

      env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
      env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
              source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']

`Zip()`, `env.Zip()`

  Builds a zip archive of the specified files and/or directories. Unlike most builder methods, the `Zip` builder method may be called multiple times for a given target; each additional call adds to the list of entries that will be built into the archive. Any source directories will be scanned for changes to any on-disk files, regardless of whether or not scons knows about them from other Builder or function calls.

      env.Zip('src.zip', 'src')

      # Create the stuff.zip file.
      env.Zip('stuff', ['subdir1', 'subdir2'])
      # Also add "another" to the stuff.tar file.
      env.Zip('stuff', 'another')

Prev | Home | Next
Construction Variables |  | Tools