The scons-gnu-arguments package is an extension to SCons which provides SCons with several command-line variables and options defined by GNU standards.

Many open-source projects use autotools and make to build software. These tools provide a set of standard command-line options and variables such as --prefix or CC. Their users may easily configure project with a custom installation prefix (./configure --prefix=/usr/bin) or chose specific compiler via command-line variables (make CC=clang). All these options are very mature and well-known to open-source developers and package maintainers. They are not avaiable in SCons, however, because SCons is not make nor automake. This is understandable, but also frustrates some developers and package mainainers that are used to GNU tools. As for the moment, there is no cheap and easy way to add the multitude of existing GNU comman-line options to scons. This package tries to change this.

WIth scons-gnu-arguments you may add groups of predefined GNU command line options/variables to SCons with just a few lines of code.

The package only works in pair with scons-arguments, so scons-arguments must be installed along with scons-gnu-arguments in a project that uses GNU arguments.

It's recommended to also take a look at the scons-arguments package, as some functions appearing in the following examples are explained in that package's documentation.

As a quick example, let us write a simple SConstruct file which installs a shell script in an appropriate installation directory, as defined by GNU standards (in $bindir, if you know what I mean). The installation path shall be configurable via command-line variables prefix, exec_prefix and bindir as it usually happens in projects based on autotools.

#! /bin/sh
echo 'hello world!'

# SConstruct
import SConsGnuArguments.InstallDirs

env = Environment()                                   # SCons environment, you should know it
var = Variables()                                     # container for SCons CLI variables

decls = SConsGnuArguments.InstallDirs.Declarations() # declare arguments
args  = decls.Commit(env, var, True)                  # say "no more arguments" to scons
args.Postprocess(env, var, True)                      # transfer CLI arguments to env

# The rest is quite usual
hello_i = env.InstallAs("${bindir}/hello", 'hello')   # NOTE the ${bindir}

env.Alias('install', hello_i)
env.AlwaysBuild('install')

ptomulik@barakus:$ scons -Q install prefix=preinst/usr
Install file: "hello" as "preinst/usr/bin/hello"

If you wonder what just happened, let's define appropriate help option to document our CLI variables we've just created

# SConstruct
import SConsGnuArguments.InstallDirs

env = Environment()                                   # SCons environment, you should know it
var = Variables()                                     # container for SCons CLI variables

decls = SConsGnuArguments.InstallDirs.Declarations() # declare arguments
args  = decls.Commit(env, var, True)                  # say "no more arguments" to scons
args.Postprocess(env, var, True)                      # transfer CLI arguments to env

# The following adds --help-variables option which documents CLI variables.
AddOption( '--help-variables', dest='help_variables', action='store_true',
         help='print help for CLI variables' )
if GetOption('help_variables'):
  print args.GenerateVariablesHelpText(var, env)
  Exit(0)

# The rest is quite usual
hello_i = env.InstallAs("${bindir}/hello", 'hello')   # NOTE the ${bindir}

env.Alias('install', hello_i)
env.AlwaysBuild('install')

ptomulik@barakus:$ scons -Q --help-variables

docdir: The directory for installing documentation files (other than Info) for this package.
    default: ${datarootdir}/doc/${install_package}
    actual: /usr/local/share/doc/
<... lot of output here ...>
prefix: Installation prefix
    default: /usr/local
    actual: /usr/local
<... lot of output ...>
prefix: Installation prefix
    default: /usr/local
    actual: /usr/local
<... lot of output ...>
bindir: The directory for installing executable programs that users can run.
    default: ${exec_prefix}/bin
    actual: /usr/local/bin

In the above example, we have used arguments from the submodule InstallDirs, which defines variables for GNU installation directories. The package SConsGnuArguments contains several submodules, each providing some subset of standarized GNU command-line arguments. They will be discussed in next sections.

There are several submodules in the SConsGnuArguments, each providing a subset of predefined GNU command-line arguments. For example, GNU directory variables are defined in a module named SConsGnuArguments.InstallDirs. Each relevant submodule provides two public functions

We'll focus only on the second function, the first one shall be quite obvious. The simplest use is to declare all the arguments predefined by a submodule

import SConsGnuArguments.<Submodule>
decls = SConsGnuArguments.<Submodule>.Declarations()

This declares all arguments predefined in the <Submodule> (substitute <Submodule> with an actual submodule name). The full list of arguments predefined by particular submodules may be found in API documentation. If you want only some of them, you may define special filter to allow only particular arguments. Currently filters are supported that use argument names. Most generic approach is to create a callable object (lambda, function, whatever) and pass it as a name_filter keyword argument to Declarations().

allowed = ['prefix', 'exec_prefix', 'bindir']
decls = SConsGnuArguments.<Submodule>.Declarations(name_filter = lambda s : s in allowed)

The name_filter should be a callable which takes a string (argument's name) and returns True (to include argument) or False (to exclude argument). The above example may be made simpler, because sequences may also be used as a name filter, so the same may be achieved with

decls = SConsGnuArguments.<Submodule>.Declarations(name_filter = [ 'prefix', 'exec_prefix', 'bindir' ])

Arguments declared with SConsGnuArguments.<Submodule>.Declarations() may create a command-line variables (scons variable=value) and/or command-line options (scons --option=value). For example, the submodule InstallDirs only creates command-line variables. This may be changed, for example you may wish to have command-line options generated by InstallDirs (or you may want to have both, CLI variables and options, it's not a problem). To enable command-line options and disable variables, manipulate var_key_transform and opt_key_transform parameters as follows.

decls = SConsGnuArguments.<Submodule>.Declarations(var_key_transform = False, opt_key_transform = True)

This should generate command-line options such as --prefix or --exec-prefix and prevent from generating command-line variables such as prefix and exec_prefix. Note that command-line options can't be saved to a file by using scons-arguments API, whereas command-line variables may be saved easily.

By default construction variables, command-line variables and command-line options inherit their names directly from their arguments. That is, if we have an argument named prefix, then its corresponding construction variable will be named prefix as well as command-line variable and command-line option (note, that command-line options get lowercased by default). This may be changed easily, for example there is a very quick and easy way to add prefixes/suffixes to the generated names. For example, we may want to add "GNU_" prefix to corresponding construction variables, such that argument, like bindir, will be seen as GNU_bindir in SCons environment. This may be achieved with env_key_prefix parameter as follows.

decls = SConsGnuArguments.<Submodule>.Declarations(env_key_prefix = 'GNU_')

The possible arguments that allow to customize name generation for construction variables, command-line variables and command-line options are summarized in the following table

The following subsections describe shortly submodules found in the SConsGnuArguments package and list arguments they define.

decls = SConsGnuArguments.InstallDirs.Declarations(...)

decls = SConsGnuArguments.AltPrograms.Declarations(...)