We're using Boost-Build to build our software. To help facilitate this, we've written a library of rules and actions. Boost-Build allows passing in command line arguments and will pass along any argument prefixed with --. Currently, to get a hold of the arguments and check for flags we're doing something like:
import modules ;
local args = [ modules.peek : ARGV ] ;
# or like this
if "--my-flag" in [ modules.peek : ARGV ]
Which works to get and check values. However, developers that use Boost-Build and our jam libraries have no idea that these flags are available and would like to see some help on these flags whenever they run either bjam -h or bjam --help. I see that BB has a help module, but I don't see any way to register arguments with the help system.
Is there a way to register command line flags, complete with short documentation, that the help system will pick up?
In response to my own question, I have added the very feature that I was asking about: https://github.com/boostorg/build/pull/23
It uses the existing options plugin system. Whenever you want to create a new command-line option create a new module within the options directory. Within that new module, create a variable that holds a value or is empty. Above the variable create a comment. The comment is used as the command-line documentation and the value (if given) is used to describe the default value of that variable.
Create a process rule within the new module and register your option with the system. This allows importing the option module and getting the value from a single source. This requires that each variable name is prefixed with the name of the module.
Create a variable named .option-description. Its value is the section separator and its comment is the description of the section.
For example:
# within options/cool.jam
# These are the options for the Cool option plugin
.option-description = Cool Options
# This enables option1
.option.--cool-option1 ?= ;
# This enables something cool
.option.--cool-default-option ?= "my default value" ;
rule process (
command # The option.
: values * # The values, starting after the "=".
)
{
option.set $(command) : $(values) ;
}
When running bjam with the --help-options flag, it will output all modules that follow the above patterns within the options directory. It will have an output similar to the following:
Boost.Build Usage:
b2 [ options... ] targets...
* -a; Build all targets, even if they are current.
* -fx; Read 'x' as the Jamfile for building instead of searching for the
Boost.Build system.
* -jx; Run up to 'x' commands concurrently.
* -n; Do not execute build commands. Instead print out the commands as they
would be executed if building.
* -ox; Output the used build commands to file 'x'.
* -q; Quit as soon as a build failure is encountered. Without this option
Boost.Jam will continue building as many targets as it can.
* -sx=y; Sets a Jam variable 'x' to the value 'y', overriding any value that
variable would have from the environment.
* -tx; Rebuild the target 'x', even if it is up-to-date.
* -v; Display the version of b2.
* --x; Any option not explicitly handled by Boost.Build remains available to
build scripts using the 'ARGV' variable.
* --abbreviate-paths; Use abbreviated paths for targets.
* --hash; Shorten target paths by using an MD5 hash.
* -dn; Enables output of diagnostic messages. The debug level 'n' and all
below it are enabled by this option.
* -d+n; Enables output of diagnostic messages. Only the output for debug
level 'n' is enabled.
Debug Levels:
Each debug level shows a different set of information. Usually with higher
levels producing more verbose information. The following levels are supported:
* 0; Turn off all diagnostic output. Only errors are reported.
* 1; Show the actions taken for building targets, as they are executed.
* 2; Show quiet actions and display all action text, as they are executed.
* 3; Show dependency analysis, and target/source timestamps/paths.
* 4; Show arguments of shell invocations.
* 5; Show rule invocations and variable expansions.
* 6; Show directory/header file/archive scans, and attempts at binding to
targets.
* 7; Show variable settings.
* 8; Show variable fetches, variable expansions, and evaluation of 'if'
expressions.
* 9; Show variable manipulation, scanner tokens, and memory usage.
* 10; Show execution times for rules.
* 11; Show parsing progress of Jamfiles.
* 12; Show graph for target dependencies.
* 13; Show changes in target status (fate).
Cool Options:
These are the options for the Cool option plugin
* --cool-option1: This enables option1. Default is disabled.
* --cool-default-option: This enables something cool. "my default value".
Later on in your own Jam code, you can then get a hold of values from the registered options by doing:
import option ;
option1 = option.get '--cool-option1' ;
if $(option1) {
# do_something ;
}