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:

• The user is passing the -v global option to run verbosely.
• The user requests to run task build1 with task parameters "--build1-opt=val1" and "--flag".
• The user requests to run task build2 with no task parameters.

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:

• Parse the command line.
  • This is the last step if --help, --version, or --show-failure is specified.
• Load the build script.
  • This is the last step if --tasks is specified.
• Configure the project by running the configure task if necessary (the project has not yet been configured, autoconf is set to true, and the user is requesting to execute a task that is marked with autoconf set to true)
• Execute user-requested tasks.