build/src/kernel/modules.jam

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

# Essentially an include guard; ensures that no module is loaded multiple times.
.loaded ?= ;

# A list of modules currently being loaded for error reporting of circular
# dependencies.
.loading ?= ;

# A list of modules needing to be tested using their __test__ rule.
.untested ?= ;

# A list of modules which have been tested using their __test__ rule.
.tested ?= ;


# Runs internal Boost Build unit tests for the specified module. The module's
# __test__ rule is executed in its own module to eliminate any inadvertent
# effects of testing module dependencies (such as assert) on the module itself.
#
local rule run-module-test ( m )
{
    local tested-modules = [ modules.peek modules : .tested ] ;

    if ( ! $(m) in $(tested-modules) )  # Avoid recursive test invocations.
        && ( ( --debug in $(argv) ) || ( --debug-module=$(m) in $(argv) ) )
    {
        modules.poke modules : .tested : $(tested-modules) $(m) ;

        if ! ( __test__ in [ RULENAMES $(m) ] )
        {
            local argv = [ peek : ARGV ] ;
            if ! ( --quiet in $(argv) ) && ( --debug-tests in $(argv) )
            {
                ECHO warning: no __test__ rule defined in module $(m) ;
            }
        }
        else
        {
            if ! ( --quiet in $(argv) )
            {
                ECHO testing module $(m)... ;
            }

            local test-module = __test-$(m)__ ;
            IMPORT $(m) : [ RULENAMES $(m) ] : $(test-module) : [ RULENAMES $(m)
                ] ;
            IMPORT $(m) : __test__ : $(test-module) : __test__ : LOCALIZE ;
            module $(test-module)
            {
                __test__ ;
            }
        }
    }
}


# Return the binding of the given module.
#
rule binding ( module )
{
    return $($(module).__binding__) ;
}


# Sets the module-local value of a variable. This is the most reliable way to
# set a module-local variable in a different module; it eliminates issues of
# name shadowing due to dynamic scoping.
#
rule poke ( module-name ? : variables + : value * )
{
    module $(<)
    {
        $(>) = $(3) ;
    }
}


# Returns the module-local value of a variable. This is the most reliable way to
# examine a module-local variable in a different module; it eliminates issues of
# name shadowing due to dynamic scoping.
#
rule peek ( module-name ? : variables + )
{
    module $(<)
    {
        return $($(>)) ;
    }
}


# Call the given rule locally in the given module. Use this for rules accepting
# rule names as arguments, so that the passed rule may be invoked in the context
# of the rule's caller (for example, if the rule accesses module globals or is a
# local rule). Note that rules called this way may accept at most 18 parameters.
#
rule call-in ( module-name ? : rule-name args * : * )
{
    module $(module-name)
    {
        return [ $(2) : $(3) : $(4) : $(5) : $(6) : $(7) : $(8) : $(9) : $(10) :
            $(11) : $(12) : $(13) : $(14) : $(15) : $(16) : $(17) : $(18) :
            $(19) ] ;
    }
}


# Given a possibly qualified rule name and arguments, remove any initial module
# qualification from the rule and invoke it in that module. If there is no
# module qualification, the rule is invoked in the global module. Note that
# rules called this way may accept at most 18 parameters.
#
rule call-locally ( qualified-rule-name args * : * )
{
    local module-rule = [ MATCH (.*)\\.(.*) : $(qualified-rule-name) ] ;
    local rule-name = $(module-rule[2]) ;
    rule-name ?= $(qualified-rule-name) ;
    #   We pass only 18 parameters here since Boost Jam allows at most 19 rule
    # parameter positions and the call-in rule already uses up the initial
    # position for the module name.
    return [ call-in $(module-rule[1]) : $(rule-name) $(args) : $(2) : $(3) :
        $(4) : $(5) : $(6) : $(7) : $(8) : $(9) : $(10) : $(11) : $(12) : $(13)
        $(14) : $(15) : $(16) : $(17) : $(18) : $(19) ] ;
}


# Load the indicated module if it is not already loaded.
#
rule load (
      module-name  # Name of module to load. Rules will be defined in this
                   # module.
    : filename ?   # (partial) path to file; Defaults to $(module-name).jam.
    : search *     # Directories in which to search for filename. Defaults to
                   # $(BOOST_BUILD_PATH).
)
{
    # Avoid loading modules twice.
    if ! ( $(module-name) in $(.loaded) )
    {
        filename ?= $(module-name).jam ;

        # Mark the module loaded so we do not try to load it recursively.
        .loaded += $(module-name:B) ;

        # Suppress tests if any module loads are already in progress.
        local suppress-test = $(.loading[1]) ;

        # Push this module on the loading stack.
        .loading += $(module-name) ;

        # Remember that it is untested.
        .untested += $(module-name) ;

        # Insert the new module's __name__ and __file__ globals.
        poke $(module-name) : __name__ : $(module-name) ;
        poke $(module-name) : __file__ : $(filename) ;

        module $(module-name)
        {
            # Add some grist so that the module will have a unique target name.
            local module-target = $(__file__:G=module@) ;

            local search = $(3) ;
            search ?= [ modules.peek : BOOST_BUILD_PATH ] ;
            SEARCH on $(module-target) = $(search) ;
            BINDRULE on $(module-target) = modules.record-binding ;

            include $(module-target) ;

            # Allow the module to see its own names with full qualification.
            local rules = [ RULENAMES $(__name__) ] ;
            IMPORT $(__name__) : $(rules) : $(__name__) : $(__name__).$(rules) ;
        }

        if $(module-name) != modules && ! [ binding $(module-name) ]
        {
            import errors ;
            errors.error "Could not find module" $(module-name) in $(search) ;
        }

        # Pop the loading stack. Must happen before testing or we will run into
        # a circular loading dependency.
        .loading = $(.loading[1--2]) ;

        # Run any pending tests if this is an outer load.
        if ! $(suppress-test)
        {
            local argv = [ peek : ARGV ] ;
            for local m in $(.untested)
            {
                run-module-test $(m) ;
            }
            .untested = ;
        }
    }
    else if $(module-name) in $(.loading)
    {
        import errors ;
        errors.error loading \"$(module-name)\"
            : circular module loading dependency:
            : $(.loading)" ->" $(module-name) ;
    }
}


# This helper is used by load (above) to record the binding (path) of each
# loaded module.
#
rule record-binding ( module-target : binding )
{
    $(.loading[-1]).__binding__ = $(binding) ;
}


# Transform each path in the list, with all backslashes converted to forward
# slashes and all detectable redundancy removed. Something like this is probably
# needed in path.jam, but I am not sure of that, I do not understand it, and I
# am not ready to move all of path.jam into the kernel.
#
local rule normalize-raw-paths ( paths * )
{
    local result ;
    for p in $(paths:T)
    {
        result += [ NORMALIZE_PATH $(p) ] ;
    }
    return $(result) ;
}


.cwd = [ PWD ] ;


# Load the indicated module and import rule names into the current module. Any
# members of rules-opt will be available without qualification in the caller's
# module. Any members of rename-opt will be taken as the names of the rules in
# the caller's module, in place of the names they have in the imported module.
# If rules-opt = '*', all rules from the indicated module are imported into the
# caller's module. If rename-opt is supplied, it must have the same number of
# elements as rules-opt.
#
rule import ( module-names + : rules-opt * : rename-opt * )
{
    if ( $(rules-opt) = * || ! $(rules-opt) ) && $(rename-opt)
    {
        import errors ;
        errors.error "Rule aliasing is only available for explicit imports." ;
    }

    if $(module-names[2]) && ( $(rules-opt) || $(rename-opt) )
    {
        import errors ;
        errors.error "When loading multiple modules, no specific rules or"
            "renaming is allowed" ;
    }

    local caller = [ CALLER_MODULE ] ;

    # Import each specified module
    for local m in $(module-names)
    {
        local module-name = $(m:B) ;
        if ! $(module-name) in $(.loaded)
        {
            # If the importing module is not already in the BOOST_BUILD_PATH,
            # prepend it to the path.  We do not want to invert the search order
            # of modules that are already there.

            local caller-location ;
            if $(caller)
            {
                caller-location = [ binding $(caller) ] ;
                caller-location = $(caller-location:D) ;
                caller-location = [ normalize-raw-paths
                    $(caller-location:R=$(.cwd)) ] ;
            }

            local search = [ peek : BOOST_BUILD_PATH ] ;
            search = [ normalize-raw-paths $(search:R=$(.cwd)) ] ;

            if $(caller-location) && ! $(caller-location) in $(search)
            {
                search = $(caller-location) $(search) ;
            }
            
            if $(m:D)
            {
                search = $(caller-location)/$(m:D) $(search)/$(m:D) $(search) ;
            }

            load $(module-name) : : $(search) ;
        }

        IMPORT_MODULE $(module-name) : $(caller) ;

        if $(rules-opt)
        {
            local source-names ;
            if $(rules-opt) = *
            {
                local all-rules = [ RULENAMES $(module-name) ] ;
                source-names = $(all-rules) ;
            }
            else
            {
                source-names = $(rules-opt) ;
            }
            local target-names = $(rename-opt) ;
            target-names ?= $(source-names) ;
            IMPORT $(module-name) : $(source-names) : $(caller) : $(target-names) ;
        }
    }
}


# Define exported copies in $(target-module) of all rules exported from
# $(source-module). Also make them available in the global module with
# qualification, so that it is just as though the rules were defined originally
# in $(target-module).
#
rule clone-rules ( source-module target-module )
{
    local r = [ RULENAMES $(source-module) ] ;
    IMPORT $(source-module) : $(r) : $(target-module) : $(r) : LOCALIZE ;
    EXPORT $(target-module) : $(r) ;
    IMPORT $(target-module) : $(r) : : $(target-module).$(r) ;
}


# These rules need to be available in all modules to implement module loading
# itself and other fundamental operations.
local globalize = peek poke record-binding ;
IMPORT modules : $(globalize) : : modules.$(globalize) ;


rule __test__ ( )
{
    import assert ;
    import modules : normalize-raw-paths ;

    module modules.__test__
    {
        foo = bar ;
    }

    assert.result bar : peek modules.__test__ : foo ;

    poke modules.__test__ : foo : bar baz ;
    assert.result bar baz : peek modules.__test__ : foo ;

    assert.result c:/foo/bar : normalize-raw-paths c:/x/../foo/./xx/yy/../../bar ;
    assert.result .          : normalize-raw-paths .                             ;
    assert.result ..         : normalize-raw-paths ..                            ;
    assert.result ../..      : normalize-raw-paths ../..                         ;
    assert.result ..         : normalize-raw-paths ./..                          ;
    assert.result / /        : normalize-raw-paths / \\                          ;
    assert.result a          : normalize-raw-paths a                             ;
    assert.result a          : normalize-raw-paths a/                            ;
    assert.result /a         : normalize-raw-paths /a/                           ;
    assert.result /          : normalize-raw-paths /a/..                         ;
}