rscons/doc/user_guide.md

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, and OS X
• colorized output with build progress
• build hooks

At its core, Rscons is mainly an engine to:

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

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

Rscons is written in Ruby, and is inspired by SCons and waf.

Design Principles

Build Correctness

The number one design principle in Rscons is build correctness. This means that a build operation will be performed 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, which can lead to an incorrect decision being made to not rebuild when a rebuild is necessary.

Build Flexibility

Rscons supports multiple configurations of compilation flags or build options across multiple environments 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.

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 operation in as little time as possible. As development occurs and build operations are executed, Rscons makes use of a cache file in order to avoid rebuilding a target when it is already up to date.

Build Directory

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

Installation

Rscons is designed to be distributed as a stand-alone single file script that can be copied into and versioned in a project's source tree. The only dependency required to run Rscons is to have a Ruby interpreter installed. The latest release can be downloaded from https://github.com/holtrop/rscons/releases. Simply copy the rscons executable script into the desired location within the project to be built (typically the root of the repository).

Version Control Setup

The following files should be added to source control:

• rscons
• Rsconscript

Add the following line to .gitignore (or the equivalent thereof for different version control systems):

/.rscons*
/build/

The Build Script

Rscons looks for instructions for what to build by reading a build script file called Rsconscript (or Rsconscript.rb). Here is a simple example Rsconscript file:

build do
  Environment.new do |env|
    env.Program("myprog.exe", glob("src/**/*.c"))
  end
end

This Rsconscript file would instruct Rscons to produce a Program target called myprog.exe which is to be built from all C source files found (recursively) under the src directory.

The Rsconscript file is a Ruby script.

Command-Line Operation

Rscons is typically invoked from the command-line as ./rscons. Rscons supports several build operations:

• configure
• build
• clean
• distclean
• install
• uninstall

Configure Operation

The configure operation will initialize the Rscons cache file and build directory. It will also perform any configuration checks requested by the build script. Such configuration checks can include:

• verifying operation of a compiler
• loading compilation/linker flags from a config program (e.g. pkg-config)
• verifying presence of a C/C++ header file
• verifying presence of a D import
• verifying presence of a library
• verifying presence of an executable

Build Operation

If a build operation is requested and a configure operation has not yet been performed, a configure operation will be automatically invoked.

The build operation will execute all builders registered to produce build targets.

Clean Operation

A clean operation will remove all built target files. It will not remove items installed by an install operation. It will not remove the cached configuration options.

Distclean Operation

A distclean operation will remove all built target files and all cached configuration options. Generally it will get the project directory back to the state it was in when unpacked before any configuration or build operations took place. It will not removed items installed by an install operation.

Install Operation

An install operation will perform a build (and if necessary, first a configure as well). In addition it will execute any Install or InstallDirectory builders to install items into the specified install directory.

Uninstall Operation

An uninstall operation will remove any items installed by an install operation. It will not remove all built target files, just the installed copies.

Build Script Authoring

License

Rscons is licensed under the terms of the MIT License.

Change Log

[TODO]