The methods in the build engine API described so far merely establish associations that describe file dependencies, how a file should be scanned, etc. Since the real point is to actually build files, SCons also has methods that actually direct the build engine to build, or otherwise manipulate, target files.
One or more targets may be built as follows:
env.Build(target = ['foo', 'bar'])
Note that specifying a directory (or other collective object) will cause all subsidiary/dependent objects to be built as well:
env.Build(target = '.') env.Build(target = 'builddir')
By default, SCons explicitly removes a target file before invoking the underlying function or command(s) to build it.
A "cleanup" operation of removing generated (target) files is performed as follows:
env.Clean(target = ['foo', 'bar'])
Like the Build
method, the Clean
method may be passed a
directory or other collective object, in which case the subsidiary
target objects under the directory will be removed:
env.Clean(target = '.') env.Clean(target = 'builddir')
(The directories themselves are not removed.)
By default, SCons explicitly removes all build-targets
when invoked to perform "cleanup". Files that should not be
removed during "cleanup" can be specified via the
NoClean
method:
env.Library(target = 'libfoo.a', source = ['aaa.c', 'bbb.c', 'ccc.c']) env.NoClean('libfoo.a')
The NoClean operation has precedence over the Clean operation. A target that is specified as both Clean and NoClean, will not be removed during a clean. In the following example, target 'foo' will not be removed during "cleanup":
env.Clean(target = 'foo') env.NoClean('foo')
As mentioned, by default, SCons explicitly removes a target
file before invoking the underlying function or command(s) to build
it. Files that should not be removed before rebuilding can be
specified via the Precious
method:
env.Library(target = 'libfoo.a', source = ['aaa.c', 'bbb.c', 'ccc.c']) env.Precious('libfoo.a')
The user may specify default targets that will be built if there are no targets supplied on the command line:
env.Default('install', 'src')
Multiple calls to the Default
method (typically one per SConscript
file) append their arguments to the list of default targets.
Files may be installed in a destination directory:
env.Install('/usr/bin', 'program1', 'program2')
Files may be renamed on installation:
env.InstallAs('/usr/bin/xyzzy', 'xyzzy.in')
Multiple files may be renamed on installation by specifying equal-length lists of target and source files:
env.InstallAs(['/usr/bin/foo', '/usr/bin/bar'], ['foo.in', 'bar.in'])
In order to provide convenient "shortcut" target names that expand to a specified list of targets, aliases may be established:
env.Alias(alias = 'install', targets = ['/sbin', '/usr/lib', '/usr/share/man'])
In this example, specifying a target of install
will cause all the files in the associated directories to be built
(that is, installed).
An Alias
may include one or more other Aliases
in its list:
env.Alias(alias = 'libraries', targets = ['lib']) env.Alias(alias = 'programs', targets = ['libraries', 'src'])