1 Overview

Rscons is an open-source build system for developers. It supports the following features:

• multi-threaded job execution
• auto-configuration
• built-in builders for several common operations
• out-of-the-box support for C, C++, and D languages
• extensibility for other languages or custom builders
• compatible with Windows, Linux, OS X, and FreeBSD
• colorized output with build progress
• build hooks
• user-defined tasks with dependencies and custom parameters
• build variants

At its core, Rscons is mainly an engine to:

• determine the proper order to perform build steps,
• determine whether each build target is up to date or in need of rebuild, and
• schedule those build steps across multiple threads as efficiently as possible.

Along the way, Rscons provides a concise syntax for specifying common types of build steps, but also provides an extensible framework for performing custom build operations as well.

Rscons takes inspiration from:

1.1 Design Principles

1.1.1 Build Correctness

The number one design principle in Rscons is build correctness. This means that a target will be built when Rscons cannot determine that a build target is already up-to-date. A build target will be built whenever:

• the target file has been removed or changed since it was last built
• the command to build the target file is different from the previous command used to build it
• any of the target file's dependency files have changed since the last time the target was built

Importantly, Rscons uses the content of a source (dependency) file to determine whether a rebuild is necessary, not simply the timestamp of the file. This is because relying solely on the timestamp of the file can lead to an incorrect decision being made to not rebuild when a rebuild is necessary.

1.1.2 Build Flexibility

Rscons supports multiple configurations of compilation flags or build options across multiple environments or build variants to build output files in different ways according to the user's desire. For example, the same source files can be built into a release executable, but also compiled with different compilation flags or build options into a test executable. Rscons also supports build hooks, which allow the user to further fine-tune the build system's operation. A build hook, for example, can be used to set a build option for only source files coming from a particular source directory.

1.1.3 Build Efficiency

Rscons will automatically determine the number of threads to use based on the host CPU configuration, and will schedule jobs as efficiently as possible across the available threads in order to complete the build in as little time as possible. As development occurs and builders are executed, Rscons makes use of a cache file in order to avoid rebuilding a target when it is already up to date.

1.1.4 Build Directory

Rscons was designed to store temporary build artifacts (for example, object files, dependency files, etc...) and build system metadata in a "build directory". This keeps files generated by the build cleanly separated from user-controlled source files.

In contrast to other build systems or build system generators, rscons executes from the project base directory (up to the user) rather than executing from within the build directory. This keeps any file paths printed by compilers (such as in warning or error messages) accurate relative to the project directory, so that the user does not need to translate any paths to the correct path within a terminal or editor application, for example.

By default a build directory named "build" is used, but this can be overridden by the user by using the -b/--build command-line option.

1.2 Getting Started

To use Rscons on your project, you must: