187 lines
6.3 KiB
Markdown
187 lines
6.3 KiB
Markdown
# 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](https://scons.org/) and [waf](https://waf.io/).
|
|
|
|
## 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.
|
|
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.
|
|
|
|
### 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](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]
|