doc.jam

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

# Copyright 2002, 2005 Dave Abrahams
# Copyright 2002, 2003, 2006 Rene Rivera
# Copyright 2003 Vladimir Prus
# Distributed under the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)

# Documentation system, handles --help requests.
# It defines rules that attach documentation to modules, rules, and variables.
# Collects and generates documentation for the various parts of the build
# system. The documentation is collected from comments integrated into the code.

import modules ;
import print ;
import set ;
import container ;
import "class" ;
import sequence ;
import path ;


# The type of output to generate.
# "console" is formated text echoed to the console (the default);
# "text" is formated text appended to the output file;
# "html" is HTML output to the file.
#
help-output = console ;


# The file to output documentation to when generating "text" or "html" help.
# This is without extension as the extension is determined by the type of
# output.
#
help-output-file = help ;

# Whether to include local rules in help output.
#
.option.show-locals ?= ;

# When showing documentation for a module, whether to also generate
# automatically the detailed docs for each item in the module.
#
.option.detailed ?= ;

# Generate debug output as the help is generated and modules are parsed.
#
.option.debug ?= ;

# Enable or disable a documentation option.
#
local rule set-option (
    option  # The option name.
    : value ?  # Enabled (non-empty), or disabled (empty)
)
{
    .option.$(option) = $(value) ;
}


# Set the type of output.
#
local rule set-output ( type )
{
    help-output = $(type) ;
}


# Set the output to a file.
#
local rule set-output-file ( file )
{
    help-output-file = $(file) ;
}


# Extracts the brief comment from a complete comment. The brief comment is the
# first sentence.
#
local rule brief-comment (
    docs *  # The comment documentation.
)
{
    local d = $(docs:J=" ") ;
    local p = [ MATCH ".*([.])$" : $(d) ] ;
    if ! $(p) { d = $(d)"." ; }
    d = $(d)" " ;
    local m = [ MATCH "^([^.]+[.])(.*)" : $(d) ] ;
    local brief = $(m[1]) ;
    while $(m[2]) && [ MATCH "^([^ ])" : $(m[2]) ]
    {
        m = [ MATCH "^([^.]+[.])(.*)" : $(m[2]) ] ;
        brief += $(m[1]) ;
    }
    return $(brief:J="") ;
}


# Specifies the documentation for the current module.
#
local rule set-module-doc (
    module-name ?  # The name of the module to document.
    : docs *  # The documentation for the module.
)
{
    module-name ?= * ;

    $(module-name).brief = [ brief-comment $(docs) ] ;
    $(module-name).docs = $(docs) ;

    if ! $(module-name) in $(documented-modules)
    {
        documented-modules += $(module-name) ;
    }
}


# Specifies the documentation for the current module.
#
local rule set-module-copyright (
    module-name ?  # The name of the module to document.
    : copyright *  # The copyright for the module.
)
{
    module-name ?= * ;

    $(module-name).copy-brief = [ brief-comment $(copyright) ] ;
    $(module-name).copy-docs = $(docs) ;

    if ! $(module-name) in $(documented-modules)
    {
        documented-modules += $(module-name) ;
    }
}


# Specifies the documentation for a rule in the current module. If called in the
# global module, this documents a global rule.
#
local rule set-rule-doc (
    name  # The name of the rule.
    module-name ?  # The name of the module to document.
    is-local ?  # Whether the rule is local to the module.
    : docs *  # The documentation for the rule.
)
{
    module-name ?= * ;

    $(module-name).$(name).brief = [ brief-comment $(docs) ] ;
    $(module-name).$(name).docs = $(docs) ;
    $(module-name).$(name).is-local = $(is-local) ;

    if ! $(name) in $($(module-name).rules)
    {
        $(module-name).rules += $(name) ;
    }
}


# Specify a class, will turn a rule into a class.
#
local rule set-class-doc (
    name  # The name of the class.
    module-name ?  # The name of the module to document.
    : super-name ?  # The super class name.
)
{
    module-name ?= * ;

    $(module-name).$(name).is-class = true ;
    $(module-name).$(name).super-name = $(super-name) ;
    $(module-name).$(name).class-rules =
        [ MATCH "^($(name)[.].*)" : $($(module-name).rules) ] ;
    $(module-name).$($(module-name).$(name).class-rules).is-class-rule = true ;

    $(module-name).classes += $(name) ;
    $(module-name).class-rules += $($(module-name).$(name).class-rules) ;
    $(module-name).rules =
        [ set.difference $($(module-name).rules) :
            $(name) $($(module-name).$(name).class-rules) ] ;
}


# Set the argument call signature of a rule.
#
local rule set-rule-arguments-signature (
    name  # The name of the rule.
    module-name ?  # The name of the module to document.
    : signature *  # The arguments signature.
)
{
    module-name ?= * ;

    $(module-name).$(name).signature = $(signature) ;
}


# Specifies the documentation for an argument of a rule.
#
local rule set-argument-doc (
    name  # The name of the argument.
    qualifier  # Argument syntax qualifier, "*", "+", etc.
    rule-name  # The name of the rule.
    module-name ?  # THe optional name of the module.
    : docs *  # The documentation.
)
{
    module-name ?= * ;

    $(module-name).$(rule-name).args.$(name).qualifier = $(qualifier) ;
    $(module-name).$(rule-name).args.$(name).docs = $(docs) ;

    if ! $(name) in $($(module-name).$(rule-name).args)
    {
        $(module-name).$(rule-name).args += $(name) ;
    }
}


# Specifies the documentation for a variable in the current module. If called in
# the global module, the global variable is documented.
#
local rule set-variable-doc (
    name  # The name of the variable.
    default  # The default value.
    initial  # The initial value.
    module-name ?  # The name of the module to document.
    : docs *  # The documentation for the variable.
)
{
    module-name ?= * ;

    $(module-name).$(name).brief = [ brief-comment $(docs) ] ;
    $(module-name).$(name).default = $(default) ;
    $(module-name).$(name).initial = $(initial) ;
    $(module-name).$(name).docs = $(docs) ;

    if ! $(name) in $($(module-name).variables)
    {
        $(module-name).variables += $(name) ;
    }
}


# Generates a general description of the documentation and help system.
#
local rule print-help-top ( )
{
    print.section "General command line usage" ;

    print.text "    bjam [options] [properties] [targets]

  Options, properties and targets can be specified in any order.
      " ;

    print.section "Important Options" ;

    print.list-start ;
    print.list-item "--clean Remove targets instead of building" ;
    print.list-item "-a Rebuild everything" ;
    print.list-item "-n Don't execute the commands, only print them" ;
    print.list-item "-d+2 Show commands as they are executed" ;
    print.list-item "-d0 Supress all informational messages" ;
    print.list-item "-q Stop at first error" ;
    print.list-item "--debug-configuration Diagnose configuration" ;
    print.list-item "--debug-building Report which targets are built with what properties" ;
    print.list-item "--debug-generator Diagnose generator search/execution" ;
    print.list-end ;

    print.section "Further Help"
        The following options can be used to obtain additional documentation.
      ;

    print.list-start ;
    print.list-item "--help-options Print more obscure command line options." ;
    print.list-item "--help-internal Boost.Build implementation details." ;
    print.list-item "--help-doc-options Implementation details doc formatting." ;
    print.list-end ;
}


# Generate Jam/Boost.Jam command usage information.
#
local rule print-help-usage ( )
{
    print.section "Boost.Jam Usage"
        "bjam [ options... ] targets..."
        ;
    print.list-start ;
    print.list-item -a;
        Build all targets, even if they are current. ;
    print.list-item -fx;
        Read '"x"' as the Jamfile for building instead of searching for the
        Boost.Build system. ;
    print.list-item -jx;
        Run up to '"x"' commands concurrently. ;
    print.list-item -n;
        Do not execute build commands. Instead print out the commands as they
        would be executed if building. ;
    print.list-item -ox;
        Output the used build commands to file '"x"'. ;
    print.list-item -q;
        Quit as soon as a build failure is encountered. Without this option
        Boost.Jam will continue building as many targets as it can.
    print.list-item -sx=y;
        Sets a Jam variable '"x"' to the value '"y"', overriding any value that
        variable would have from the environment. ;
    print.list-item -tx;
        Rebuild the target '"x"', even if it is up-to-date. ;
    print.list-item -v;
        Display the version of bjam. ;
    print.list-item --x;
        Any option not explicitly handled by Boost.Jam remains available to
        build scripts using the '"ARGV"' variable. ;
    print.list-item -dn;
        Enables output of diagnostic messages. The debug level '"n"' and all
        below it are enabled by this option. ;
    print.list-item -d+n;
        Enables output of diagnostic messages. Only the output for debug level
        '"n"' is enabled. ;
    print.list-end ;
    print.section "Debug Levels"
        Each debug level shows a different set of information. Usually with
        higher levels producing more verbose information. The following levels
        are supported: ;
    print.list-start ;
    print.list-item 0;
        Turn off all diagnostic output. Only errors are reported. ;
    print.list-item 1;
        Show the actions taken for building targets, as they are executed. ;
    print.list-item 2;
        Show "quiet" actions and display all action text, as they are executed. ;
    print.list-item 3;
        Show dependency analysis, and target/source timestamps/paths. ;
    print.list-item 4;
        Show arguments of shell invocations. ;
    print.list-item 5;
        Show rule invocations and variable expansions. ;
    print.list-item 6;
        Show directory/header file/archive scans, and attempts at binding to targets. ;
    print.list-item 7;
        Show variable settings. ;
    print.list-item 8;
        Show variable fetches, variable expansions, and evaluation of '"if"' expressions. ;
    print.list-item 9;
        Show variable manipulation, scanner tokens, and memory usage. ;
    print.list-item 10;
        Show execution times for rules. ;
    print.list-item 11;
        Show parsing progress of Jamfiles. ;
    print.list-item 12;
        Show graph for target dependencies. ;
    print.list-item 13;
        Show changes in target status (fate). ;
    print.list-end ;
}


# Generates description of options controlling the help system. This
# automatically reads the options as all variables in the doc module of the form
# ".option.*".
#
local rule print-help-options (
    module-name  # The doc module.
)
{
    print.section "Help Options"
        These are all the options available for enabling or disabling to control
        the help system in various ways. Options can be enabled or disabled with
        '"--help-enable-<option>"', and "'--help-disable-<option>'"
        respectively.
        ;
    local options-to-list = [ MATCH ^[.]option[.](.*) : $($(module-name).variables) ] ;
    if $(options-to-list)
    {
        print.list-start ;
        for local option in [ sequence.insertion-sort $(options-to-list) ]
        {
            local def = disabled ;
            if $($(module-name)..option.$(option).default) != "(empty)"
            {
                def = enabled ;
            }
            print.list-item $(option): $($(module-name)..option.$(option).docs)
                Default is $(def). ;
        }
        print.list-end ;
    }
}


# Generate brief documentation for all the known items in the section for a
# module. Possible sections are: "rules", and "variables".
#
local rule print-help-module-section (
    module  # The module name.
    section  # rules or variables.
    : section-head  # The title of the section.
    section-description *  # The detailed description of the section.
)
{
    if $($(module).$(section))
    {
        print.section $(section-head) $(section-description) ;
        print.list-start ;
        for local item in [ sequence.insertion-sort $($(module).$(section)) ]
        {
            local show = ;
            if ! $($(module).$(item).is-local)
            {
                show = yes ;
            }
            if $(.option.show-locals)
            {
                show = yes ;
            }
            if $(show)
            {
                print.list-item $(item): $($(module).$(item).brief) ;
            }
        }
        print.list-end ;
    }
}


# Generate documentation for all possible modules. We attempt to list all known
# modules together with a brief description of each.
#
local rule print-help-all (
    ignored  # Usually the module name, but is ignored here.
)
{
    print.section "Modules"
        "These are all the known modules. Use --help <module> to get more"
        "detailed information."
        ;
    if $(documented-modules)
    {
        print.list-start ;
        for local module-name in [ sequence.insertion-sort $(documented-modules) ]
        {
            # The brief docs for each module.
            print.list-item $(module-name): $($(module-name).brief) ;
        }
        print.list-end ;
    }
    # The documentation for each module when details are requested.
    if $(documented-modules) && $(.option.detailed)
    {
        for local module-name in [ sequence.insertion-sort $(documented-modules) ]
        {
            # The brief docs for each module.
            print-help-module $(module-name) ;
        }
    }
}


# Generate documentation for a module. Basic information about the module is
# generated.
#
local rule print-help-module (
    module-name  # The module to generate docs for.
)
{
    # Print the docs.
    print.section "Module '$(module-name)'" $($(module-name).docs) ;

    # Print out the documented classes.
    print-help-module-section $(module-name) classes : "Module '$(module-name)' classes"
        Use --help $(module-name).<class-name> to get more information. ;

    # Print out the documented rules.
    print-help-module-section $(module-name) rules : "Module '$(module-name)' rules"
        Use --help $(module-name).<rule-name> to get more information. ;

    # Print out the documented variables.
    print-help-module-section $(module-name) variables : "Module '$(module-name)' variables"
        Use --help $(module-name).<variable-name> to get more information. ;

    # Print out all the same information but indetailed form.
    if $(.option.detailed)
    {
        print-help-classes $(module-name) ;
        print-help-rules $(module-name) ;
        print-help-variables $(module-name) ;
    }
}


# Generate documentation for a set of rules in a module.
#
local rule print-help-rules (
    module-name  # Module of the rules.
    : name *  # Optional list of rules to describe.
)
{
    name ?= $($(module-name).rules) ;
    if [ set.intersection $(name) : $($(module-name).rules) $($(module-name).class-rules) ]
    {