Rscons

Rscons is a software construction framework inspired by SCons and implemented
in Ruby.

Installation

$ gem install rscons

Usage

Standalone

Rscons provides a standalone executable ("rscons") with a command-line
interface. The rscons executable will read a build script (by default named
Rsconsfile or Rsconsfile.rb) and execute its contents.

With Rake

Rscons can be used with rake as well. The same content that would be written
in Rsconsfile can be placed in a Rakefile. It could be placed within a rake
task block or split among multiple tasks.

Example: Custom Builder

Custom builders are implemented as classes which extend from Rscons::Builder.
The builder must have a run method which is called to invoke the builder.
The run method should return the name of the target built on success, and
false on failure.

Example: Custom Builder Using Builder#standard_build()

The standard_build method from the Rscons::Builder base class can be used
when the builder needs to execute a system command to produce the target file.
The standard_build method will return the correct value so its return value
can be used as the return value from the run method.

Example: Custom Builder Using Environment#add_builder()

The add_builder method of the Rscons::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: Creating a C++ parser source from a Yacc/Bison input file

Details

Environments

The Environment is the main top-level object that Rscons operates with. An
Environment must be created by the user in order to build anything. All build
targets are registered within an Environment. In many cases only a single
Environment will be needed, but more than one can be created (either from
scratch or by cloning another existing Environment) if needed.

An Environment consists of:

a collection of builders

a collection of construction variables used by those builders

a mapping of build directories from source directories

a default build root to apply if no specific build directories are matched

a collection of user-defined build targets

a collection of user-defined build hooks

When cloning an environment, by default the construction variables, builders,
build hooks, build directories, and build root are cloned, but the new
environment does not inherit any of the registered build targets.

The set of environment attributes that are cloned is controllable via the
:clone option to the #clone method.
For example, env.clone(clone: [:variables, :builders]) will include
construction variables, and builders but not build hooks, build directories, or
the build root.

Program

The Program builder compiles and links the given sources to an executable file.
Object 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.

SharedLibrary

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.

SharedObject

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.

Construction Variables

Construction variables are used to define the toolset and any build options
that Rscons will use to build a project. The default construction variable
values are configured to build applications using gcc. However, all
construction variables can be overridden by the user.

Build Hooks

Environments can have build hooks which are added with env.add_build_hook().
Build hooks are invoked immediately before a builder executes.
Build hooks can modify the construction variables in use for the build
operation.
They can also register new build targets.

Environments can also have post-build hooks added with env.add_post_build_hook().
Post-build hooks are only invoked if the build operation was a success.
Post-build hooks can invoke commands using the newly-built files, or register
new build targets.

Each build hook block will be invoked for every build operation, so the block
should test the target or sources if its action should only apply to some
subset of build targets or source files.

Example build hook:

Rscons::Environment.newdo|env|# Build third party sources without -Wall
env.add_build_hookdo|build_op|ifbuild_op[:builder].name=="Object"andbuild_op[:sources].first=~%r{src/third-party}build_op[:vars]["CFLAGS"]-=["-Wall"]endendend

The build_op parameter to the build hook block is a Hash describing the
build operation with the following keys:

:builder - Builder instance in use

:env - Environment calling the build hook; note that this may be
different from the Environment that the build hook was added to in the case
that the original Environment was cloned with build hooks!

:target - String name of the target file

:sources - Array of the source files

:vars - Rscons::VarSet containing the construction variables to use.
The build hook can overwrite entries in build_op[:vars] to alter the
construction variables in use for this specific build operation.

Phony Targets

A build target name given as a Symbol instead of a String is interpreted as a
"phony" target.
Phony targets operate similarly to normal build targets, except that a file is
not expected to be produced by the builder.
Phony targets will still be "rebuilt" if any source or the command is out of
date.

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: