Table of Contents

1 Overview
1.1 Design Principles
1.1.1 Build Correctness
1.1.2 Build Flexibility
1.1.3 Build Efficiency
1.1.4 Build Directory
1.2 Getting Started
2 Installation
2.1 Version Control Setup
3 Command-Line Operation
3.1 Rscons Operation Phases
4 The Build Script
4.1 Tasks
4.1.1 Task Parameters
4.1.2 Tasks with Special Meaning
4.1.2.1 Configure Task
4.1.2.2 Default Task
4.1.2.3 Clean Task
4.1.2.4 Distclean Task
4.1.2.5 Install Task
4.1.2.6 Uninstall Task
4.2 Configuring the Project
4.2.1 Checking for a Compiler
4.2.2 Checking for a Header File
4.2.2.1 Options
4.2.2.1.1 :check_cpppath
4.2.3 Checking for a D Import
4.2.3.1 Options
4.2.3.1.1 :check_d_import_path
4.2.4 Checking for a Library
4.2.4.1 Options
4.2.4.1.1 :check_libpath
4.2.4.1.2 :use
4.2.5 Checking for a Program
4.2.6 Checking for a Package Configuration
4.2.6.1 Options
4.2.6.1.1 :package
4.2.6.1.2 :program
4.2.6.1.3 :use
4.2.7 Custom Configuration Checks
4.2.8 Global Configuration Check Options
4.2.8.1 :fail
4.2.8.2 :on_fail
4.2.8.3 :set_define
4.3 Building Targets
4.3.1 Environments
4.3.2 Construction Variables
4.3.2.1 Construction Variable Naming
4.3.3 Builders
4.3.3.1 The Command Builder
4.3.3.2 The CFile Builder
4.3.3.3 The Copy Builder
4.3.3.4 The Directory Builder
4.3.3.5 The Disassemble Builder
4.3.3.6 The Install Builder
4.3.3.7 The InstallDirectory Builder
4.3.3.8 The Library Builder
4.3.3.9 The Object Builder
4.3.3.10 The Preprocess Builder
4.3.3.11 The Program Builder
4.3.3.11.1 Direct Mode
4.3.3.12 The SharedLibrary Builder
4.3.3.12.1 Direct Mode
4.3.3.13 The SharedObject Builder
4.3.3.14 The Size Builder
4.3.4 Phony Targets
4.3.5 Explicit Dependencies
4.3.6 Build Hooks
4.3.7 Barriers
4.4 Variants
4.4.1 Variant Groups
4.5 Build Script Methods
4.5.1 Finding Files: The glob Method
4.5.2 Downloading Files: The download Method
4.5.3 PATH Management
4.5.4 Using Subsidiary Build Scripts: The rscons Method
4.5.5 Executing Commands: The sh Method
4.6 Extending Rscons
4.6.1 Adding New Languages
4.6.2 Adding Custom Builders
4.6.2.1 Adding a Custom Builder to an Environment
4.6.2.2 Builder Name
4.6.2.3 Custom Builder Constructor
4.6.2.4 Custom Builder Operation
4.6.2.4.1 Return Value
4.6.2.4.2 Printing Build Status
4.6.2.4.3 Custom Builder Cache Usage - Only Rebuild When Necessary
4.6.2.4.4 Custom Builder Parallelization
4.6.2.4.4.1 Using a Ruby Thread to Parallelize a Builder
4.6.2.4.4.2 Executing a Subcommand from a Custom Builder
4.6.2.5 Simple custom builders added with add_builder
5 Appendix
5.1 Default Construction Variables
5.2 Example Build Scripts
5.2.1 Example: Building a C Program
5.2.2 Example: Building a D Program
5.2.3 Example: Cloning an Environment
5.2.4 Example: Custom Builder
5.2.5 Example: Using different compilation flags for some sources
5.2.6 Example: Creating a static library
5.2.7 Example: Creating a C++ parser source from a Yacc/Bison input file
5.2.8 Example: GCC Cross Compiler
5.3 ./configure && make
5.4 YARD API Documentation
6 License
7 Contributing
8 Change Log

1 Overview

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

At its core, Rscons is mainly an engine to:

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:

Rscons is written in Ruby. The only requirement to run Rscons is that the system has a Ruby interpreter installed.

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:

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:

  1. Install the rscons script in your project (See Installation).
  2. Write the Rsconscript build script for your project (See The Build Script).
  3. Use the rscons command in your project (See Command-Line Operation).

2 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 requirement to run Rscons is that the system has 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) and mark it executable.

2.1 Version Control Setup

The following files should be added to source control:

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

/.rscons*
/build/

3 Command-Line Operation

Rscons is typically invoked from the command-line as ./rscons.

Usage: ./rscons [global options] [[task] [task options] ...]

Global options:
  -A, --all
    Show all tasks (even those without descriptions) in task list. Use in
    conjunction with the -T argument.

  -b BUILD, --build=BUILD
    Set build directory (default: build).

  -e VS, --variants=VS
    Enable or disable variants. VS is a comma-separated list of variant
    entries. If the entry begins with "-" the variant is disabled instead of
    enabled. If the full list begins with "+" or "-" then it modifies the
    variants that are enabled by default by only enabling or disabling the
    listed variants. Otherwise, the enabled set of variants is as given and
    any variants not listed are disabled. The set of enabled variants is
    remembered from when the project is configured.

  -f FILE
    Use FILE as Rsconscript.

  -F, --show-failure
    Show failed command log from previous build and exit (does not load build
    script).

  -h, --help
    Show rscons help and exit (does not load build script).

  -j N, --nthreads=N
    Set number of threads (local default: 16).

  -r COLOR, --color=COLOR
    Set color mode (off, auto, force).

  -T, --tasks
    Show task list and parameters and exit (loads build script). By default
    only tasks with a description are listed. Use -AT to show all tasks whether
    they have a description or not.

  -v, --verbose
    Run verbosely. This causes Rscons to print the full build command used by
    each builder.

  --version
    Show rscons version and exit (does not load build script).

The user can list any number of tasks on the command line. Any parameters beginning with a "-" that follow a task are interpreted as task arguments until another parameter is seen that does not begin with "-". For example:

./rscons -v build1 --build1-opt=val1 --flag build2

The above command line is interpreted as follows:

If no tasks are specified on the command line, Rscons executes the default task.

If a task fails due to a command failure (e.g. compilation or linking failed), Rscons will log the failed commands. By default Rscons does not print the failed commands to the console so that it is easier for the user to focus on the actual compiler failure messages rather than the compilation command itself. The user can run ./rscons -F to see the command that failed on the prior Rscons execution. The user can also invoke Rscons with the -v global command-line option which will cause Rscons to print each command it is executing.

3.1 Rscons Operation Phases

When Rscons executes, it performs the following phases:

4 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:

env do |env|
  env.Program("myprog.exe", glob("src/**/*.c"))
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.

4.1 Tasks

Tasks are a high-level user interface for performing functionality in a build script. Tasks can create Environments that perform compilation/linking steps. Tasks can also execute arbitrary commands or perform any miscellaneous logic.

Tasks can have dependencies, which are specified as names of other tasks that should be executed before this task executes.

Tasks can have action blocks. When a task is executed, all of its action blocks are called in the order in which they were added.

Example:

task "build" do
  env do |env|
    env.Program("^^/proj.elf", glob("src/**/*.c"))
  end
end

task "flash", deps: "build" do
  sh "nrfjprog", "-f", "NRF52", "--program", env.expand("^^/proj.elf")
end

In this example, the flash task depends on the build task. So if the project had not yet been built, and the user executes ./rscons flash, the project would first be built and then flashed to the target.

If the task method is called again with the name of an already existing task, the task is not overwritten, but rather modified. Any newly specified dependencies are added to the current dependencies. Any action block is appended to the task's list of action blocks to execute when the task is executed.

Note that for a simple project, the build script may not need to define any tasks at all and could just make use of the Rscons built-in default task (see Default Task).

4.1.1 Task Parameters

Tasks can accept parameters. Parameters are defined by the build script author, and have default values. The user can override parameter values on the command line.

Task parameters are defined by passing a parameter constructed with the Rscons param() method to the :params argument of the task() method. The signature of the param method is:

def param(name, value, takes_arg, description)

For example:

task "build", params: [
  param("myparam", "defaultvalue", true, "My special parameter"),
  param("xyz", nil, false, "Enable the xyz feature"),
] do |task, params|
  env do |env|
    env["CPPDEFINES"] << "SOMEMACRO=#{params["myparam"]}"
    if params["flag"]
      env["CPPDEFINES"] << "ENABLE_FEATURE_XYZ"
    end
  end
end

With the above Rsconscript, the user could invoke Rscons as:

./rscons build --myparam=pvalue --xyz

This would pass in "pvalue" as the value to the "myparam" parameter, and a truthy value ("--xyz") as the value of the "xyz" parameter.

As seen above, task parameter values can be accessed within a task's action block by using the second parameter (params) to the action block. Task parameter values can also be accessed with the Task#[] method on any task object. This allows accessing the parameter values of any task object, not just the task owning the action block being executed.

Example:

task "one", params: param("flag", nil, false, "Enable a flag")

task "two" do
  puts "Task one's flag #{Task["one"]["flag"] ? "is" : "is not"} set"
end

Task parameters can also be referenced via construction variables. Each task parameter is stored in a construction variable. The name for the construction variable is created by joining the task name and the parameter name with a ":" character. For example:

task "build", params: [
  param("heap-size", "1024", true, "Set heap size"),
] do
  env["CPPDEFINES"] << "HEAP_SIZE=${build:heap-size}"
  env.Program("^/myprog", glob("src/**/*.c"))
  env.Install("${configure:prefix}/bin/myprog", "^/myprog")
end

4.1.2 Tasks with Special Meaning

Rscons recognizes special meaning for a few tasks:

For each of these tasks, a shortcut method of the same name as the task is provided which is equivalent to calling the task() method with the first argument (task name) automatically filled in by the shortcut method. For example:

default deps: "unpack_compiler" do
  puts "default task"
end

is equivalent to:

task "default", deps: "unpack_compiler" do
  puts "default task"
end

4.1.2.1 Configure Task

The configure task allows Rscons to perform any one-time setup operations required by a project, for example locating compilers and setting any initial construction variable values based on the host environment in use. It will also perform any configuration checks requested by the build script. Such configuration checks can include:

The configure task is implicitly a dependency of every other task unless that task is configured with its autoconf option set to false.

The global build script autoconf setting can also be set to false to disable automatic invocation of the configure task. For example:

autoconf false

configure do
  puts "configure"
end

default do
  puts "default"
end

With the above Rsconscript, even if the project has not yet been configured, a configure operation would not take place when the default task is executed. The user would have to explicitly request the configure task from the command line.

The build script method project_name can be used to set the project name which will be reported to the user during a configure operation. For example:

project_name "My awesome project"

configure do
  check_d_compiler
end

See Configuring the Project for more details on how to make use of the configuration functionality that Rscons provides.

Configure blocks must be defined in the Rsconscript file before any environments are created.

4.1.2.2 Default Task

The default task is special in that Rscons will execute it if no other task has been requested by the user on the command line.

The default task can also be used to declare a dependency on another task that would effectively become the default. For example:

task "build" do
  ...
end

task "flash" do
  ...
end

default deps: "build"

Then when the user runs ./rscons the "build" task will be executed.

4.1.2.3 Clean Task

The clean task is built-in to Rscons. It removes all built target files. It will not remove items installed by an Install builder. It will not remove the cached configuration options.

4.1.2.4 Distclean Task

The distclean task is built-in to Rscons. It removes 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 or checked out, before any configuration or build operations took place. It will not remove items installed by an Install builder.

4.1.2.5 Install Task

The install task is not built-in to Rscons but rather is just a convention for the build script author to use. The suggested use is for the install task to invoke any Install or InstallDirectory builders to install items into the specified installation directory.

The install shortcut method can be used. For example:

install do
  env.Install("${prefix}/bin", "app.exe")
  env.Install("${prefix}/share", "share")
end

4.1.2.6 Uninstall Task

The uninstall task is built-in to Rscons. It removes any items installed by an Install builder. It will not remove all built target files, just the installed copies.

4.2 Configuring the Project

Configure task actions can be used to perform various checks and setup operations for a project. Example configure action block:

configure do
  check_cxx_compiler
  check_c_header "getopt.h"
end

If any configure task action blocks are present, they will be execute when the configure operation is performed. This happens if the user requests the configure task from the command line. It also happens if all of the following are true:

See Configure Task for more information about autoconf.

4.2.1 Checking for a Compiler

The following methods can be used within a configure block to check for a working compiler:

Each of these methods can take an optional list of compilers to check for. If such a list is supplied, the compilers are tested in the order listed. The first compiler option found which passes a compilation test is used.

Here are example calls which also show the default compiler list for each supported language:

configure do
  check_c_compiler "gcc", "clang"
  check_cxx_compiler "g++", "clang++"
  check_d_compiler "gdc", "ldc2"
end

Global configuration options may be supplied to the compiler checks as well. Example:

configure do
  check_c_compiler "x86_64-elf-gcc", on_fail: "Install x86_64-elf cross toolchain first!"
end

4.2.2 Checking for a Header File

The following methods can be used to check for the presence of a header file:

Each of these methods take the name of the header file to check for as the first argument, and take an optional Hash of arguments as the second argument.

Example calls:

configure do
  check_c_header "getopt.h", set_define: "HAVE_GETOPT_H"
  check_c_header "FreeType2.h"
  check_cxx_header "memory"
end

4.2.2.1 Options

4.2.2.1.1 :check_cpppath

Optionally specifies an array of paths to look for the header file in.

4.2.3 Checking for a D Import

The check_d_import method can be used to check for the presence of D import.

This method takes the name of the import to check for as the first argument.

Example calls:

configure do
  check_d_import "std.stdio"
  check_d_import "std.numeric"
end

4.2.3.1 Options

4.2.3.1.1 :check_d_import_path

Optionally specifies an array of paths to look for the module in.

4.2.4 Checking for a Library

The check_lib method can be used to check for the presence of a library.

This method takes the name of the library to check for as the first argument, and take an optional Hash of arguments as the second argument.

Example calls:

configure do
  check_lib "kpty", fail: false, set_define: "HAVE_LIBKPTY"
  check_lib "GL"
end

4.2.4.1 Options

4.2.4.1.1 :check_libpath

Optionally specifies an array of paths to look for the library in.

4.2.4.1.2 :use

If not set, the library will be used by default in all Environment objects. If set, the library will only be used in Environment objects that have a matching :use flag set.

4.2.5 Checking for a Program

The check_program method can check for the existence of an executable in the host operating system environment.

Example call:

configure do
  check_program "xxd"
end

4.2.6 Checking for a Package Configuration

The check_cfg method can be used to check for the existence of a package as well as import any build options (e.g. include path, defines, libraries to link against, etc...) required to use the package.

This method takes a Hash of options as its only argument.

Example calls:

configure do
  check_cfg package: "zlib"
  check_cfg program: "freetype-config", fail: false, set_define: "HAVE_FREETYPE"
end

4.2.6.1 Options

4.2.6.1.1 :package

If the :package option is set to a value, the pkg-config program will be used to look for package configuration flags for the specified package.

4.2.6.1.2 :program

If the :program option is given, the program specified will be used to look for configuration flags.

4.2.6.1.3 :use

If not set, the library will be used by default in all Environment objects. If set, the library will only be used in Environment objects that have a matching :use flag set.

4.2.7 Custom Configuration Checks

The Rsconscript author can add custom configuration checks to be performed during the rscons configure operation.

Here is an example from build_tests/configure/custom_config_check.rb showing a custom configuration check:

configure do
  custom_check("Checking 'grep' version") do |op|
    stdout, stderr, status = op.log_and_test_command(%w[grep --version])
    should_fail = true
    if status != 0
      fail_message = "error executing grep"
    elsif stdout =~ /^grep \(GNU grep\) 1\./
      fail_message = "too old!"
      status = 1
    elsif stdout =~ /^grep \(GNU grep\) 2\./
      fail_message = "we'll work with it but you should upgrade"
      status = 1
      should_fail = false
      op.store_merge("CPPDEFINES" => "GREP_WORKAROUND")
    else
      op.store_append("CPPDEFINES" => "GREP_FULL")
    end
    op.complete(status, success_message: "good!", fail_message: fail_message, fail: should_fail)
  end
  custom_check("Checking sed -E flag") do |op|
    stdout, stderr, status = op.log_and_test_command(%w[sed -E -e s/ab+/rep/], stdin: "abbbc")
    op.complete(stdout =~ /repc/ ? 0 : 1, success_message: "good", fail_message: "fail")
  end
end

env do |env|
  puts env["CPPDEFINES"]
end

A custom configuration check is created by calling the custom_check method and passing a block. The contents of the block should perform the custom configuration checking logic. This logic can include executing a test command or other arbitrary operations. An argument op is passed to the block. This object is an instance of the ConfigureOp class class and provides several methods that can be used to aid with the custom configuration check. The log_and_test_command method can be used to execute a test command and retrieve its results. The command and its output are also logged to the config.log file. The store_merge, store_append, and store_parse methods can be used to store construction variables to be used in Environments created later. Finally, the complete method can be used to complete the configuration check and indicate a success or failure.

While performing a custom configuration check, it can sometimes be useful to be able to construct an Environment to use the set of default construction variables as defined so far in the configuration block, for example to expand construction variables to build a test command. The normal Environment class cannot be used within the configure block, however the BasicEnvironment class can be used for such a purpose.

For example, to expand the current ${CCCMD} value:

configure do
  custom_check("Checking something to do with CCCMD") do
    command = BasicEnvironment.new.expand_varref("${CCCMD}")
    # ...
  end
end

4.2.8 Global Configuration Check Options

4.2.8.1 :fail

If the :fail option is set to false, then the absence of the package or program requested will not result in the configure option failing. The :fail option defaults to true if the :set_define option is not defined, and defaults to false if the :set_define option is defined.

4.2.8.2 :on_fail

The :on_fail option can be set to a String or a Proc object. If the configuration operation fails (or would fail), the given message is printed or the Proc is called.

Examples:

configure do
  check_c_compiler "special-gcc", on_fail: "First install special gcc!"
end

configure do
  package_hint = lambda do
    puts "The following packages must be installed to build this project:"
    puts "- libsdl2-dev"
    puts "- libsdl2-image-dev"
    puts "- libsdl2-net-dev"
  end
  check_lib "SDL2", on_fail: package_hint
  check_lib "SDL2_image", on_fail: package_hint
  check_lib "SDL2_net", on_fail: package_hint
end

4.2.8.3 :set_define

If set, a build define of the specified String will be added to the CPPDEFINES construction variable array if the requested package is found.

4.3 Building Targets

Building target files is accomplished by using Environments. Environments can be created at the top level of the build script, or from within a task action block.

Environments are created with the env build script method. Here is an example build script that creates an Environment and registers a Program build target:

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

This Rsconscript would build an executable called myprog.exe from all C source files found recursively under the src directory.

4.3.1 Environments

An Environment includes:

All build targets must be registered within an Environment. If the user does not specify a name for the environment, a name will be automatically generated based on the Environment's internal ID, for example "e.1". The Environment's build root is a directory with the same name as the Environment, created within the top-level Rscons build directory. By default it holds all intermediate files generated by Rscons that are needed to produce a user-specified build target. For example, for the Rsconscript:

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

Rscons will place an object file and dependency file corresponding to each C source file under the Environment's build root. Assuming a top-level build directory of "build", the Environment's build root would be "build/myproj". This keeps the intermediate generated build artifacts separate from the source files. Source and target paths passed to a Builder (e.g. Program) can begin with "^/" to indicate that Rscons should expand those paths to be relative to the Environment's build root. If a source or target path passed to a Builder begins with "^^/", it is expanded to be relative to the Rscons top-level build directory (but outside the Environment's build root).

4.3.2 Construction Variables

Construction variables are values assigned to keys within an Environment. Construction variables are used by Builders to produce output files. See Default Construction Variables for a reference of all built-in construction variables.

Example:

env do |env|
  env["CCFLAGS"] += %w[-O2 -Wall]
  env["LIBS"] += %w[m]
end

This example modifies the CCFLAGS construction variable to add -O2 and -Wall to the compilation commands used for C and C++ source files. It also instructs the linker to link against the m library.

4.3.2.1 Construction Variable Naming

4.3.3 Builders

Rscons uses builder objects to produce target output files from source input files. A build target to be built using a builder is registered by calling a method on the Environment object that matches the builder's name. For example, a Program build target is registered by calling the env.Program method.

The general syntax for registering a build target using a builder is:

env.BuilderName(target, sources, vars = {})

The target parameter is the path to the output file or directory. The sources parameter is the path or paths to the input file(s) to be used by the builder. In the target and sources parameters, the user can explicitly refer to a path within the Environment's build root by beginning the path with "^/", or to a path within the Rscons top-level built directory by beginning with "^^/". The vars parameter is an optional Hash which can include construction variables to be used for this build target. Any construction variable values specified in this parameter will override those assigned to the Environment.

There are several default builders that are built-in to Rscons:

4.3.3.1 The Command Builder

env.Command(target, sources, "CMD" => command)
# Example
env.Command("user_guide.html", "user_guide.md",
  "CMD" => ["pandoc", "-fmarkdown", "-thtml", "-o${_TARGET}", "${_SOURCES}"],
  "CMD_DESC" => "Generating user guide:")

The Command builder executes a user-defined command in order to produce the desired target file based on the provided source files.

The Command builder supports the following construction variables:

4.3.3.2 The CFile Builder

env.CFile(target, source)
# Example
env.CFile("^/parser/parser.c", "parser.y")

The CFile builder will generate a C or C++ source file from a lex (.l, .ll) or yacc (.y, .yy) input file.

4.3.3.3 The Copy Builder

env.Copy(destination, sources)
# Example
env.Copy("mytests", "^/mytests")
env.Copy("^/dist/share", "share")

The Copy builder can copy files or directories to a target location.

4.3.3.4 The Directory Builder

env.Directory(target)
# Example
env.Directory("^/tests")

The Directory builder can be used to explicitly create a directory. This can also disambiguate whether the target for a subsequent builder (e.g. Copy) refers to a file path or directory path.

4.3.3.5 The Disassemble Builder

env.Disassemble(target, source)
# Example
env.Disassemble("module.dis", "module.o")

The Disassemble builder generates a disassembly listing using objdump from and object file.

4.3.3.6 The Install Builder

env.Install(destination, sources)
# Example
env.Install("${prefix}/bin", "app.exe")
env.Install("${prefix}/share", "share")

The Install builder can install files or directories to their installation target location. It functions almost identically to the Copy builder. The only difference relates to the clean and uninstall tasks. The clean task removes targets created by the Copy builder but not by the Install builder. The uninstall task removes targets created by the Install builder but not by the Copy builder.

4.3.3.7 The InstallDirectory Builder

env.InstallDirectory(target)
# Example
env.InstallDirectory("${prefix}/share")

The InstallDirectory builder can be used to explicitly create a directory in an installation location. This can also disambiguate whether the target for a subsequent builder (e.g. Install) refers to a file path or directory path.

It functions almost identically to the Directory builder. The only difference relates to the clean and uninstall tasks. The clean task removes targets created by the Directory builder but not by the InstallDirectory builder. The uninstall task removes targets created by the InstallDirectory builder but not by the Directory builder.

4.3.3.8 The Library Builder

env.Library(target, sources)
# Example
env.Library("lib.a", Rscons.glob("src/**/*.c"))

The Library builder creates a static library archive from the given source files.

4.3.3.9 The Object Builder

env.Object(target, sources)
# Example
env.Object("module.o", "module.c")

The Object builder compiles the given sources to an object file. Although it can be called explicitly, it is more commonly implicitly called by the Program builder.

4.3.3.10 The Preprocess Builder

env.Preprocess(target, source)
# Example
env.Preprocess("module-preprocessed.cc", "module.cc")

The Preprocess builder invokes either ${CC} or ${CXX} (depending on if the source contains an extension in ${CXXSUFFIX} or not) and writes the preprocessed output to the target file.

4.3.3.11 The Program Builder

env.Program(target, sources)
# Example
env.Program("myprog", Rscons.glob("src/**/*.cc"))

The Program builder compiles and links the given sources to an executable file. Object files, static library files, or source files can be given as sources. A platform-dependent program suffix will be appended to the target name if one is not specified. This can be controlled with the PROGSUFFIX construction variable.

4.3.3.11.1 Direct Mode

The Program builder supports a "direct" mode which is activated by specifying the :direct option. In the direct mode, all source files are passed directly to the compiler together and compiled and linked in one step, rather than being individually compiled to separate object files first. This mode allows taking advantage of any multi-file compilation capabilities of the compiler. However, it also requires recompiling all source files when any one of them has changed.

Example use:

env.Program("myprog", Rscons.glob("src/**/*.c"), direct: true)

4.3.3.12 The SharedLibrary Builder

env.SharedLibrary(target, sources)
# Example
env.SharedLibrary("mydll", Rscons.glob("src/**/*.cc"))

The SharedLibrary builder compiles and links the given sources to a dynamically loadable library. Object files or source files can be given as sources. A platform-dependent prefix and suffix will be appended to the target name if they are not specified by the user. These values can be controlled by overriding the SHLIBPREFIX and SHLIBSUFFIX construction variables.

4.3.3.12.1 Direct Mode

The SharedLibrary builder supports a "direct" mode which is activated by specifying the :direct option. In the direct mode, all source files are passed directly to the compiler together and compiled and linked in one step, rather than being individually compiled to separate object files first. This mode allows taking advantage of any multi-file compilation capabilities of the compiler. However, it also requires recompiling all source files when any one of them has changed.

Example use:

env.SharedLibrary("mydll", Rscons.glob("src/**/*.c"), direct: true)

4.3.3.13 The SharedObject Builder

env.SharedObject(target, sources)
# Example
env.SharedObject("lib_module.o", "lib_module.c")

The SharedObject builder compiles the given sources to an object file. Any compilation flags necessary to build the object file in a manner that allows it to be used to create a shared library are added. Although it can be called explicitly, it is more commonly implicitly called by the SharedLibrary builder.

4.3.3.14 The Size Builder

env.Size(target, sources)
# Example
env.Program("program.exe", glob("*.c"))
env.Size("program.size", "program.exe")

The Size builder runs the "size" executable on the given source file and stores its output in the target file. The size executable can be specified with the SIZE construction variable, and flags can be specified with SIZEFLAGS.

4.3.4 Phony Targets

Rscons supports phony build targets. Normally, a builder produces an output file, and executes whenever the input files or command have changed. A phony build target can be used to register a builder that does not produce an output file. A custom builder can take some action when the input files change even if it does not produce an output file. Such a builder could perform verification or run a test on its source files, possibly failing if some conditions are not met. It could also simply output something to the console, such as an analysis of the source file, whenever it changes. A phony target is signified by passing a Symbol instead of a String as the first parameter (target) to a builder method.

4.3.5 Explicit Dependencies

A target can be marked as depending on another file that Rscons would not otherwise know about via the Environment#depends function. For example, to force the linker to re-link a Program output when a linker script changes:

env.Program("a.out", "foo.c", "LDFLAGS" => %w[-T linker_script.ld])
env.depends("a.out", "linker_script.ld")

You can pass multiple dependency files to Environment#depends:

env.depends("my_app", "config/link.ld", "README.txt", *glob("assets/**/*"))

4.3.6 Build Hooks

A build hook is a Ruby block that is called whenever Rscons is about to invoke a builder to produce a build target. Rscons also supports post-build hooks which are called after the builder has produced the build target. A build hook can be used to modify construction variables depending on the build target or source file names.

Example:

env do |env|
  env["CFLAGS"] << "-Wall"
  env.add_build_hook do |builder|
    # Compile sources from under src/tests without the -Wall flag.
    if builder.sources.first =~ %r{src/tests/}
      builder.vars["CFLAGS"] -= %w[-Wall]
    end
  end
  env.Program("program.exe", glob("src/**/*.c"))
end

This example script would compile all C sources under the src directory with the -Wall flag except for sources under the src/tests directory.

A post-build hook can be added with env.add_post_build_hook. Post-build hooks are only invoked if the build step was a success.

Build hooks and post-build hooks can register new build targets.

4.3.7 Barriers

Normally Rscons will parallelize all builders executed within an Environment. A barrier can be used to separate sets of build targets. All build targets registered before the barrier is created will be built before Rscons will schedule any build targets after the barrier. In other words, build targets are not parallelized across a barrier.

env.barrier

4.4 Variants

Rscons supports build variants. Variants can be used to built multiple variations of the same item with a specific change. For example, a desktop application with the same sources could be built to target KDE or GNOME using build variants. It is up to the build script author to define the variants and what effect they have on the build.

This build script defines "kde" and "gnome" variants:

variant "kde"
variant "gnome"

with_variants do
  env "prog" do |env|
    if variant "kde"
      env["CPPDEFINES"] << "KDE"
    end
    if variant "gnome"
      env["CPPDEFINES"] << "GNOME"
    end
    env.Program("^/prog.exe", "src/**/*.cpp")
  end
end

The variant build script method has two uses:

The with_variants build script method allows the power of variants to be harnessed. It iterates through each enabled variant and calls the given block. In this example, the block would be called twice, once with the "kde" variant active, and the second time with the "gnome" variant active.

Each env() call creates an Environment, so two environments are created. When an Environment is created within a with_variants block, the Environment's name has the active variant(s) appended to the given Environment name (if any), and separated by a "-".

In this example, a "prog-kde" Environment would be created with build root build/prog-kde and -DKDE would be passed to the compiler when compiling each source. Next a "prog-gnome" Environment would be created with build root build/prog-gnome and -DGNOME would be passed to the compiler when compiling the sources.

Variants are enabled by default, but can be disabled by passing a false value to the :default option of the variant method. For example:

variant "debug", default: false
variant "release"

with_variants do
  env "prog" do |env|
    env.Program("^/prog.exe", "prog.c")
  end
end

The rscons command line interface provides a -e/--variants argument which allows the user to enable a different set of variants from those enabled by default according to the build script author. This argument accepts a comma-separated list of variants to enable. Each entry in the list can begin with "-" to disable the variant instead of enable it. If the list begins with "+" or "-", then the entire given list modifies the defaults given in the build script. Otherwise, it exactly specifies which variants should be enabled, and any variant not listed is disabled.

When the project is configured, the set of enabled variants is recorded and remembered for later Rscons invocations. This way, a user working on a single variant of a project does not need to specify the -e/--variants option on each build operation.

The variant_enabled? build script method can be called to query whether the given variant is enabled.

4.4.1 Variant Groups

Variants may be grouped, which allows the build script author to define multiple combinations of desired variations to build with. For example:

variant_group "desktop-environment" do
  variant "kde"
  variant "gnome"
end

variant_group "debug" do
  variant "debug"
  variant "release"
end

with_variants do
  env "prog" do |env|
    if variant("kde")
      env["CPPDEFINES"] << "KDE"
    end
    if variant("gnome")
      env["CPPDEFINES"] << "GNOME"
    end
    if variant("debug")
      env["CPPDEFINES"] << "DEBUG"
    end
    if variant("release")
      env["CPPDEFINES"] << "NDEBUG"
    end
    env.Program("^/prog.exe", "prog.c")
  end
end

This build script executes the block given to with_variants four times and results in four Environments being created:

The command ./rscons -e-debug would build just "prog-kde-release" and "prog-gnome-release". The command ./rscons --variants kde,release would build just "prog-kde-release".

4.5 Build Script Methods

rscons provides several methods that a build script can use.

Additionally, the following methods from the Ruby FileUtils module are made available for the build script to call directly:

4.5.1 Finding Files: The glob Method

The glob method can be used to find files matching the patterns specified. It supports a syntax similar to the Ruby Dir.glob method but operates more deterministically (results are ordered based on file names rather than file system directory ordering).

Example use:

env do |env|
  env.Program("mytests", glob("src/**/*.cc", "test/**/*.cc"))
end

This example would build the mytests executable from all .cc source files found recursively under the src or test directory.

4.5.2 Downloading Files: The download Method

The download method can be used to download a file from a given URL.

Example use:

default do
  download "https://ftp.gnu.org/gnu/gcc/gcc-#{gcc_version}/gcc-#{gcc_version}.tar.xz",
    "#{build_dir}/gcc-#{gcc_version}.tar.xz",
    sha256_sum: gcc_checksum
end

The download method downloads the file specified by the URL in the first parameter, and writes it to the local file specified by the second parameter. If the :sha256sum option is given, this causes two changes to the default behavior:

4.5.3 PATH Management

rscons provides methods for management of the PATH environment variable.

The path_append and path_prepend methods can be used to append or prepend a path to the PATH environment variable.

path_prepend "i686-elf-gcc/bin"

The path_set method sets the PATH environment variable to the given Array or String.

The path_components method returns an Array of the components in the PATH environment variable.

4.5.4 Using Subsidiary Build Scripts: The rscons Method

The rscons build script method can be used to invoke an rscons subprocess using a subsidiary rscons build script. This can be used, for example, when a subproject is imported and a top-level configure or build task should also perform the same task in the subproject directory.

The first argument to the rscons method specifies either a directory name, or the path to the subsidiary Rsconscript file to execute. Any additional arguments are passed to rscons when it executes the subsidiary script. rscons will change working directories to the directory containing the subsidiary script when executing it.

For example:

configure do
  rscons "subproject", "configure"
end

task "build" do
  rscons "subproject/Rsconscript", "build"
end

It is also perfectly valid to perform different task(s) in the subsidiary script from the one being performed in the top-level script. For example, in a project that requires a particular cross compiler, the top-level configure script could build the necessary cross compiler using a subsidiary build script. This could look something like:

configure do
  rscons "cross/Rsconscript"
  check_c_compiler "i686-elf-gcc"
end

This would build, and if necessary first configure, using the cross/Rsconscript subsidiary build script. Subsidiary build scripts are executed from within the directory containing the build script.

4.5.5 Executing Commands: The sh Method

The sh build script method can be used to directly execute commands. The sh method accepts either a single String argument or an Array of Strings. When an Array is given, if the array length is greater than 1, then the command will not be executed and interpreted by the system shell. Otherwise, it will be executed and interpreted by the system shell.

For example:

default do
  # Run "make" in imported "subcomponent" directory.
  sh "cd subcomponent; make"
  # Move a file around.
  sh "mv", "subcomponent/file with spaces.txt", "new_name.txt"
end

If the command fails, rscons will normally print the error and terminate execution. If the :continue option is set, then rscons will not terminate execution. For example:

default do
  # This command will fail and a message will be printed.
  sh "false", continue: true
  # However, due to the :continue option being set, execution will continue.
  sh "echo hi"
end

Options that Ruby's spawn method accepts can also be passed in to the sh method. For example, to execute the given command with a different working directory, the :chdir option can be specified:

default do
  # Execute 'ls' from within the 'src' directory:
  sh "ls", chdir: "src"
end

4.6 Extending Rscons

4.6.1 Adding New Languages

The Object and SharedObject builders that ship with Rscons have an API that allows the user to register extra languages that can be suppored by the builders. In fact, the built-in support for assembly, C, C++, and D compilation all make use of this built-in API. To see an example of how this API is used, see the lib/rscons/builders/lang/*.rb files in the Rscons source repository. For example, here is how the C++ language is registered:

Rscons::Builders::Object.register(command: "${CXXCMD}", direct_command: "${CXXCMD:direct}", suffix: "${CXXSUFFIX}", preferred_ld: "${CXX}")
Rscons::Builders::SharedObject.register(command: "${SHCXXCMD}", direct_command: "${SHCXXCMD:direct}", suffix: "${CXXSUFFIX}", preferred_ld: "${SHCXX}")

There are also default construction variables registered to go along with the language registration as specified above. New default construction variables can be registered globally by assigning to the Rscons::DEFAULT_CONSTRUCTION_VARIABLES Hash. For example:

Rscons::DEFAULT_CONSTRUCTION_VARIABLES["CXXCMD"] = %w[${CXX} -c -o ${_TARGET} ${CXXDEPGEN} ${INCPREFIX}${CPPPATH} ${CPPFLAGS} ${CXXFLAGS} ${CCFLAGS} ${_SOURCES}]

4.6.2 Adding Custom Builders

It is also possible to extend Rscons with new builders. This is the most flexible method to extend Rscons. Builders can execute a command line program, call another builder, or just use plain Ruby code to produce an output file.

A builder is a class that inherits from the Rscons::Builder base class. Rscons provides a Rscons::Builders namespacing module which contains the built-in builder classes. User-provided custom builder classes can also reside in the Rscons::Builders namespacing module, but this is not required.

4.6.2.1 Adding a Custom Builder to an Environment

The user can add a builder class to an Environment with the env.add_builder method. For example:

class Rscons::Builders::Mine < Rscons::Builder
end

default do
  env do |env|
    env.add_builder(Rscons::Builders::Mine)
  end
end

Alternatively, the builder author can add the name of the custom builder to the Rscons::DEFAULT_BUILDERS array and then Rscons will automatically add the custom builder to every Environment. This method only works if the custom builder class is contained within the Rscons::Builders namespacing module. For example:

#SpecialBuilder.rb
class Rscons::Builders::Special < Rscons::Builder
end
Rscons::DEFAULT_BUILDERS << :Special

#Rsconscript
load "SpecialBuilder.rb"

default do
  env do |env|
    # A build target using the "Special" builder can be registered.
    env.Special("target", "source")
  end
end

4.6.2.2 Builder Name

By default, the builder name is taken from the last component of the class name. For example, a class called Rscons::Builders::Mine would be usable in the Rsconscript with env.Mine(). A builder author can override the builder name by defining a class method within the builder class called name. For example, with the following builder definition:

class Rscons::Builders::MySpecialBuilder < Rscons::Builder
  def self.name
    "Special"
  end
end

This builder would be registered in the Rsconscript with env.Special().

4.6.2.3 Custom Builder Constructor

It is optional for a custom builder to provide an initialize method. If an initialize method is provided, it must call super to invoke the base Rscons::Builder class's constructor. A single Hash parameter is passed to the builder constructor. This Hash contains many parameters describing how the build target was registered by the user. The base constructor will set several instance attributes within the builder:

4.6.2.4 Custom Builder Operation

In order for a builder to run, the builder class must implement a the Builder#run() method. Generally, the run() method will use the source file(s) to produce the target file. Here is an example of a trivial builder:

class Rscons::Builders::Custom < Rscons::Builder
  def run(options)
    File.open(@target, "w") do |fh|
      fh.write("Target file created.")
    end
    true
  end
end
4.6.2.4.1 Return Value

If the builder has completed and failed, the run method should return false. In this case, generally the command executed or the builder itself would be expected to output something to $stderr indicating the reason for the build failure. If the builder has completed successfully, the run method should return true. If the builder is not yet complete and is waiting on other steps, the run method should return the return value from the Builder#wait_for method. See Custom Builder Parallelization.

4.6.2.4.2 Printing Build Status

A builder should print a status line when it produces a build target. The Builder#print_run_message method can be used to print the builder status line. This method supports a limited markup syntax to identify and color code the build target and/or source(s). Here is our Custom builder example extended to print its status:

class Rscons::Builders::Custom < Rscons::Builder
  def run(options)
    print_run_message("Creating <target>#{@target}<reset> from Custom builder", nil)
    File.open(@target, "w") do |fh|
      fh.write("Target file created.")
    end
    true
  end
end
4.6.2.4.3 Custom Builder Cache Usage - Only Rebuild When Necessary

Whenever possible, a builder should keep track of information necessary to know whether the target file(s) need to be rebuilt. The Rscons::Cache object is the mechanism by which to keep track of this information. The Cache object provides two methods: #up_to_date? and #register_build which can be used to check if a built file is still up-to-date, and to register build information for a subsequent check. Here is a Custom builder which combines its source files similar to what the cat command would do:

class Rscons::Builders::Custom < Rscons::Builder
  def run(options)
    unless @cache.up_to_date?(@target, nil, @sources, @env)
      print_run_message("Combining <source>#{Util.short_format_paths(@sources)}<reset> => <target>#{@target}<reset>", nil)
      File.open(@target, "wb") do |fh|
        @sources.each do |source|
          fh.write(File.read(source, mode: "rb"))
        end
      end
      @cache.register_build(@target, nil, @sources, @env)
    end
    true
  end
end

This builder would rebuild the target file and print its run message if the target file or any of the source file(s) were changed, but otherwise would be silent and not re-combine the source files.

Note that generally the same arguments should be passed to @cache.register_build and @cache.up_to_date?.

4.6.2.4.4 Custom Builder Parallelization

The Rscons scheduler can parallelize builders to take advantage of multiple processor cores. Taking advantage of this ability to parallelize requires the builder author to author the builder in a particular way. The #run() method of each builder is called from Rscons in the main program thread. However, the builder may execute a subcommand, spawn a thread, or register other builders to execute as a part of doing its job. In any of these cases, the builder's run method should make use of Builder#wait_for to "sleep" until one of the items being waited for has completed.

4.6.2.4.4.1 Using a Ruby Thread to Parallelize a Builder

Here is an example of using a Ruby thread to parallelize a builder:

class MyBuilder < Rscons::Builder
  def run(options)
    if @thread
      true
    else
      print_run_message("#{name} #{target}", nil)
      @thread = Thread.new do
        sleep 2
        FileUtils.touch(@target)
      end
      wait_for(@thread)
    end
  end
end

env do |env|
  env.add_builder(MyBuilder)
  env.MyBuilder("foo")
end

It is up to the author of the thread logic to only perform actions that are thread-safe. It is not safe to call other Rscons methods, for example, registering other builders or using the Cache, from a thread other than the one that calls the #run() method.

4.6.2.4.4.2 Executing a Subcommand from a Custom Builder

It is a very common case that a builder will execute a subcommand which produces the build target. This is how most of the built-in Rscons builders execute. A low-level way to handle this is for the builder to construct an instance of the Rscons::Command class and then wait_for the Command object. However, this is a common enough case that Rscons provides a few convenience methods to handle this:

The register_command helper method can be used to create a Command object and wait for it to complete. The standard_command helper does the same thing as register_command but additionally checks the @cache for the target being up to date. The finalize_command helper can be used in conjunction with either of the previous helper methods.

The built-in Rscons builders Command and Disassemble show examples of how to use the standard_command and finalize_command helper methods.

Example (built-in Command builder):

module Rscons
  module Builders
    # A builder to execute an arbitrary command that will produce the given
    # target based on the given sources.
    #
    # Example:
    #   env.Command("docs.html", "docs.md",
    #               CMD => %w[pandoc -fmarkdown -thtml -o${_TARGET} ${_SOURCES}])
    class Command < Builder

      # Run the builder to produce a build target.
      def run(options)
        if @command
          finalize_command
        else
          @vars["_TARGET"] = @target
          @vars["_SOURCES"] = @sources
          command = @env.build_command("${CMD}", @vars)
          cmd_desc = @vars["CMD_DESC"] || "Command"
          options = {}
          if @vars["CMD_STDOUT"]
            options[:stdout] = @env.expand_varref("${CMD_STDOUT}", @vars)
          end
          standard_command("#{cmd_desc} <target>#{@target}<reset>", command, options)
        end
      end

    end
  end
end

Example (built-in Disassemble builder):

module Rscons
  module Builders
    # The Disassemble builder produces a disassembly listing of a source file.
    class Disassemble < Builder

      # Run the builder to produce a build target.
      def run(options)
        if @command
          finalize_command
        else
          @vars["_SOURCES"] = @sources
          command = @env.build_command("${DISASM_CMD}", @vars)
          standard_command("Disassembling <source>#{Util.short_format_paths(@sources)}<reset> => <target>#{target}<reset>", command, stdout: @target)
        end
      end

    end
  end
end

4.6.2.5 Simple custom builders added with add_builder

The add_builder method of the Environment class optionally allows you to define and register a builder by providing a name and action block. This can be useful if the builder you are trying to define is easily expressed as a short ruby procedure. When add_builder is called in this manner a new builder will be registered with the environment with the given name. When this builder is used it will call the provided block in order to build the target.

Example:

env do |env|
  require 'json'
  require 'yaml'
  env.add_builder(:JsonToYaml) do |params|
    unless @cache.up_to_date?(@target, :JsonToYaml, @sources, @env)
      print_run_message("JsonToYaml #{@target}", nil)
      @cache.mkdir_p(File.dirname(@target))
      File.open(@target, 'w') do |f|
        f.write(YAML.dump(JSON.load(IO.read(@sources.first))))
      end
      @cache.register_build(@target, :JsonToYaml, @sources, @env)
    end
    true
  end
  env.JsonToYaml('foo.yml', 'foo.json')
end

5 Appendix

5.1 Default Construction Variables

module Rscons

  on_windows = RUBY_PLATFORM =~ /mingw|msys|cygwin/
  pic_flags = on_windows ? [] : %w[-fPIC]

  # Default Rscons construction variables.
  DEFAULT_CONSTRUCTION_VARIABLES = {
    "AR" => "ar",
    "ARCMD" => %w[${AR} ${ARFLAGS} ${_TARGET} ${_SOURCES}],
    "ARFLAGS" => %w[rcs],
    "AS" => "${CC}",
    "ASCMD" => %w[${AS} -c -o ${_TARGET} ${ASDEPGEN} ${INCPREFIX}${ASPPPATH} ${ASPPFLAGS} ${ASFLAGS} ${_SOURCES}],
    "ASCMD:direct" => %w[${AS} -o ${_TARGET} ${ASDEPGEN} ${INCPREFIX}${ASPPPATH} ${ASPPFLAGS} ${ASFLAGS} ${LDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
    "ASDEPGEN" => %w[-MMD -MF ${_DEPFILE}],
    "ASFLAGS" => [],
    "ASPPFLAGS" => "${CPPFLAGS}",
    "ASPPPATH" => "${CPPPATH}",
    "ASSUFFIX" => %w[.S],
    "CC" => "gcc",
    "CCCMD" => %w[${CC} -c -o ${_TARGET} ${CCDEPGEN} ${INCPREFIX}${CPPPATH} ${CPPFLAGS} ${CFLAGS} ${CCFLAGS} ${_SOURCES}],
    "CCCMD:direct" => %w[${CC} -o ${_TARGET} ${CCDEPGEN} ${INCPREFIX}${CPPPATH} ${CPPFLAGS} ${CFLAGS} ${CCFLAGS} ${LDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
    "CCDEPGEN" => %w[-MMD -MF ${_DEPFILE}],
    "CCFLAGS" => [],
    "CFLAGS" => [],
    "CPPDEFINES" => [],
    "CPPDEFPREFIX" => "-D",
    "CPPFLAGS" => %w[${CPPDEFPREFIX}${CPPDEFINES}],
    "CPPPATH" => [],
    "CPP_CMD" => %w[${_PREPROCESS_CC} -E ${_PREPROCESS_DEPGEN} -o ${_TARGET} ${INCPREFIX}${CPPPATH} ${CPPFLAGS} ${_SOURCES}],
    "CSUFFIX" => %w[.c],
    "CXX" => "g++",
    "CXXCMD" => %w[${CXX} -c -o ${_TARGET} ${CXXDEPGEN} ${INCPREFIX}${CPPPATH} ${CPPFLAGS} ${CXXFLAGS} ${CCFLAGS} ${_SOURCES}],
    "CXXCMD:direct" => %w[${CXX} -o ${_TARGET} ${CXXDEPGEN} ${INCPREFIX}${CPPPATH} ${CPPFLAGS} ${CXXFLAGS} ${CCFLAGS} ${LDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
    "CXXDEPGEN" => %w[-MMD -MF ${_DEPFILE}],
    "CXXFLAGS" => [],
    "CXXSUFFIX" => %w[.cc .cpp .cxx .C],
    "DC" => "gdc",
    "DCCMD" => %w[${DC} -c -o ${_TARGET} ${DDEPGEN} ${INCPREFIX}${D_IMPORT_PATH} ${DFLAGS} ${_SOURCES}],
    "DCCMD:direct" => %w[${DC} -o ${_TARGET} ${DDEPGEN} ${INCPREFIX}${D_IMPORT_PATH} ${DFLAGS} ${LDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
    "DDEPGEN" => %w[-MMD -MF ${_DEPFILE}],
    "DEPFILESUFFIX" => ".mf",
    "DFLAGS" => [],
    "DISASM_CMD" => %w[${OBJDUMP} ${DISASM_FLAGS} ${_SOURCES}],
    "DISASM_FLAGS" => %w[--disassemble --source],
    "DSUFFIX" => %w[.d],
    "D_IMPORT_PATH" => [],
    "INCPREFIX" => "-I",
    "LD" => nil,
    "LDCMD" => %w[${LD} -o ${_TARGET} ${LDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
    "LDFLAGS" => [],
    "LEX" => "flex",
    "LEXSUFFIX" => %w[.l .ll],
    "LEX_CMD" => %w[${LEX} ${LEX_FLAGS} -o ${_TARGET} ${_SOURCES}],
    "LEX_FLAGS" => [],
    "LIBDIRPREFIX" => "-L",
    "LIBLINKPREFIX" => "-l",
    "LIBPATH" => [],
    "LIBS" => [],
    "LIBSUFFIX" => ".a",
    "OBJDUMP" => "objdump",
    "OBJSUFFIX" => %w[.o],
    "PROGSUFFIX" => on_windows ? ".exe" : "",
    "SHCC" => "${CC}",
    "SHCCCMD" => %w[${SHCC} -c -o ${_TARGET} ${CCDEPGEN} ${INCPREFIX}${CPPPATH} ${CPPFLAGS} ${SHCFLAGS} ${SHCCFLAGS} ${_SOURCES}],
    "SHCCCMD:direct" => %w[${SHCC} -o ${_TARGET} ${CCDEPGEN} ${INCPREFIX}${CPPPATH} ${CPPFLAGS} ${SHCFLAGS} ${SHCCFLAGS} ${SHLDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
    "SHCCFLAGS" => %w[${CCFLAGS}] + pic_flags,
    "SHCFLAGS" => %w[${CFLAGS}],
    "SHCXX" => "${CXX}",
    "SHCXXCMD" => %w[${SHCXX} -c -o ${_TARGET} ${CXXDEPGEN} ${INCPREFIX}${CPPPATH} ${CPPFLAGS} ${SHCXXFLAGS} ${SHCCFLAGS} ${_SOURCES}],
    "SHCXXCMD:direct" => %w[${SHCXX} -o ${_TARGET} ${CXXDEPGEN} ${INCPREFIX}${CPPPATH} ${CPPFLAGS} ${SHCXXFLAGS} ${SHCCFLAGS} ${SHLDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
    "SHCXXFLAGS" => %w[${CXXFLAGS}],
    "SHDC" => "gdc",
    "SHDCCMD" => %w[${SHDC} -c -o ${_TARGET} ${INCPREFIX}${D_IMPORT_PATH} ${SHDFLAGS} ${_SOURCES}],
    "SHDCCMD:direct" => %w[${SHDC} -o ${_TARGET} ${INCPREFIX}${D_IMPORT_PATH} ${SHDFLAGS} ${SHLDFLAGS} ${_SOURCES} ${LIBDIRPREFIX}${LIBPATH} ${LIBLINKPREFIX}${LIBS}],
    "SHDFLAGS" => %w[${DFLAGS}] + pic_flags,
    "SHLD" => nil,
    "SHLDCMD" => %w[${SHLD} -o ${_TARGET} ${SHLDFLAGS} ${_SOURCES} ${SHLIBDIRPREFIX}${LIBPATH} ${SHLIBLINKPREFIX}${LIBS}],
    "SHLDFLAGS" => %w[${LDFLAGS} -shared],
    "SHLIBDIRPREFIX" => "-L",
    "SHLIBLINKPREFIX" => "-l",
    "SHLIBPREFIX" => on_windows ? "" : "lib",
    "SHLIBSUFFIX" => on_windows ? ".dll" : ".so",
    "SIZE" => "size",
    "SIZECMD" => %w[${SIZE} ${SIZEFLAGS} ${_SOURCES}],
    "SIZEFLAGS" => [],
    "YACC" => "bison",
    "YACCSUFFIX" => %w[.y .yy],
    "YACC_CMD" => %w[${YACC} ${YACC_FLAGS} -o ${_TARGET} ${_SOURCES}],
    "YACC_FLAGS" => %w[-d],
  }

end

5.2 Example Build Scripts

5.2.1 Example: Building a C Program

env do |env|
  env["CFLAGS"] << "-Wall"
  env.Program("program", glob("src/**/*.c"))
end

5.2.2 Example: Building a D Program

env do |env|
  env["DFLAGS"] << "-Wall"
  env.Program("program", glob("src/**/*.d"))
end

5.2.3 Example: Cloning an Environment

main_env = env do |env|
  env["CFLAGS"] = ["-fshort-enums", "-O3"]
  env["CPPDEFINES"] << "SOME_DEFINE"
  env["LIBS"] = ["SDL"]
  env.Program("program", glob("src/**/*.cc"))
end

test_env = main_env.clone do |env|
  env["CFLAGS"] -= ["-O3"]
  env["CFLAGS"] += ["-g", "-O0"]
  env["CPPDEFINES"] = "ENABLE_TESTS"
  env.Program("program-test", glob("src/**/*.cc"))
end

5.2.4 Example: Custom Builder

class GenerateFoo < Builder
  def run(options)
    target, cache = options.values_at(:target, :cache)
    cache.mkdir_p(File.dirname(target))
    File.open(target, "w") do |fh|
      fh.puts <<EOF
#define GENERATED 42
EOF
    end
    target
  end
end

env do |env|
  env.add_builder(GenerateFoo)
  env.GenerateFoo("foo.h", [])
  env.Program("a.out", glob("*.c"))
end

5.2.5 Example: Using different compilation flags for some sources

env do |env|
  env["CFLAGS"] = ["-O3", "-Wall"]
  env.add_build_hook do |builder|
    if builder.sources.first =~ %r{src/third-party/}
      build_op[:vars]["CFLAGS"] -= ["-Wall"]
    end
  end
  env.Program("program", glob("**/*.cc"))
end

5.2.6 Example: Creating a static library

env do |env|
  env.Library("mylib.a", glob("src/**/*.c"))
end

5.2.7 Example: Creating a C++ parser source from a Yacc/Bison input file

env do |env|
  env.CFile("^/parser.tab.cc", "parser.yy")
end

5.2.8 Example: GCC Cross Compiler

binutils_version = "2.35"
binutils_checksum = "1b11659fb49e20e18db460d44485f09442c8c56d5df165de9461eb09c8302f85"
gcc_version = "10.2.0"
gcc_checksum = "b8dd4368bb9c7f0b98188317ee0254dd8cc99d1e3a18d0ff146c855fe16c1d8c"
install_path = File.expand_path("i686-elf-gcc")
target = "i686-elf"
path_prepend "#{install_path}/bin"

configure do
  check_c_compiler "gcc"
  check_program "make"
  check_program "bison"
  check_program "flex"
  check_program "texi2any", on_fail: "Install the texinfo package"
  check_program "wget"
  check_lib "gmp", on_fail: "Install the libgmp-dev package"
  check_lib "mpc", on_fail: "Install the libmpc-dev package"
  check_lib "mpfr", on_fail: "Install the libmpfr-dev package"
end

default do
  unless Dir.exist?(install_path)

    # Download archives.
    download "https://ftp.gnu.org/gnu/binutils/binutils-#{binutils_version}.tar.xz",
      "#{build_dir}/binutils-#{binutils_version}.tar.xz",
      sha256sum: binutils_checksum

    download "https://ftp.gnu.org/gnu/gcc/gcc-#{gcc_version}/gcc-#{gcc_version}.tar.xz",
      "#{build_dir}/gcc-#{gcc_version}.tar.xz",
      sha256sum: gcc_checksum

    # Extract archives.
    sh "tar", "xJf", "binutils-#{binutils_version}.tar.xz",
      chdir: build_dir

    sh "tar", "xJf", "gcc-#{gcc_version}.tar.xz",
      chdir: build_dir

    # Build binutils.
    rm_rf "#{build_dir}/build-binutils"
    mkdir_p "#{build_dir}/build-binutils"
    cd "#{build_dir}/build-binutils" do
      sh %W[../binutils-#{binutils_version}/configure
        --target=#{target} --prefix=#{install_path} --with-sysroot --disable-nls
        --disable-werror]
      sh "make"
      sh "make install"
    end

    # Build gcc.
    rm_rf "#{build_dir}/build-gcc"
    mkdir_p "#{build_dir}/build-gcc"
    cd "#{build_dir}/build-gcc" do
      sh %W[../gcc-#{gcc_version}/configure
        --target=#{target} --prefix=#{install_path} --disable-nls
        --enable-languages=c,c++ --without-headers]
      sh "make all-gcc"
      sh "make all-target-libgcc"
      sh "make install-gcc"
      sh "make install-target-libgcc"
    end
  end
end

clean do
  rm_f "#{build_dir}/binutils-#{binutils_version}.tar.xz"
  rm_rf "#{build_dir}/binutils-#{binutils_version}"
  rm_rf "#{build_dir}/build-binutils"
  rm_f "#{build_dir}/gcc-#{gcc_version}.tar.xz"
  rm_rf "#{build_dir}/gcc-#{gcc_version}"
  rm_rf "#{build_dir}/build-gcc"
end

distclean do
  rm_rf install_path
end

5.3 ./configure && make

You can make your Rscons-based project more familiar to users of autoconf-generated projects by creating a configure script and a Makefile for the user. Such users may be used to executing:

./configure
make

to build a project. To do this, create a configure script with contents similar to the following:

#!/bin/sh
exec "$(dirname "$0")"/rscons configure "$@"

and make it executable with chmod +x configure.

If you want your users to be able to build/clean a project with make but still make use of Rscons under the hood, you can create a Makefile with contents something like this:

.PHONY: all
all:
    ./rscons build

.PHONY: clean
clean:
    ./rscons clean

5.4 YARD API Documentation

See here for Rscons YARD API Documentation.

6 License

Rscons is licensed under the terms of the MIT License:

Copyright (c) 2013-2022 Josh Holtrop

MIT License

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

7 Contributing

Rscons is developed on github.

Issues may be submitted to https://github.com/holtrop/rscons/issues.

Pull requests may be submitted as well:

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

8 Change Log

v3.0.2

Fixes

v3.0.1

Fixes

v3.0.0

v2.3.0

New Features

Fixes

v2.2.0

New Features

v2.1.0

New Features

v2.0.2

Fixes

v2.0.1

Fixes

v2.0.0

v1.17.0

New Features

v1.16.0

New Features

Fixes

v1.15.0

v1.14.0

New Features

Fixes

v1.13.0

New Features

v1.12.0

New Features

Fixes

v1.11.1

Fixes

v1.11.0

New Features

Fixes

v1.10.0

New Features

Fixes

v1.9.3

v1.9.2

v1.9.1

v1.9.0

New Features

Fixes

v1.8.1

v1.8.0

v1.7.0

v1.6.1

v1.6.0

v1.5.0

v1.4.3

v1.4.2

v1.4.1

v1.4.0

v1.3.0

v1.2.0

v1.1.0