build/modules.jam

#  (C) Copyright David Abrahams 2001. Permission to copy, use, modify, sell and
#  distribute this software is granted provided this copyright notice appears in
#  all copies. This software is provided "as is" without express or implied
#  warranty, and with no claim as to its suitability for any purpose.

# Keep a record so that no module is included multiple times
loaded-modules ?= ;
loading-modules ?= ;
untested ?= ;

# meant to be invoked from import when no __test__ rule is defined in a given
# module
local rule no_test_defined
{
    ECHO warning: no __test__ rule defined in module [ CALLER_MODULE ] ;
}

# 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
# which accept 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).
rule call-in ( module-name ? : rule-name args * : * )
{
    module $(module-name)
    {
        return [ $(2) : $(3) : $(4) : $(5) : $(6) : $(7) : $(8) : $(9) ] ;
    }
}

# load the indicated module if it is not already loaded.
rule load ( module-name : filename ? : search * )
{
    filename ?= $(module-name).jam ;
    if ! ( $(module-name) in $(loaded-modules) )
    {
        loaded-modules += $(module-name) ;
        loading-modules += $(module-name) ;
        local suppress-test = $(untested[1]) ; # suppress tests until all recursive loads are complete.
        untested += $(module-name) ; # add the module to the stack of untested modules
        
        poke $(module-name) : __name__ : $(module-name) ;
        poke $(module-name) : __file__ : $(filename) ;
        
        module $(module-name)
        {
            # Prepare a default behavior, in case no __test__ is defined.
            IMPORT modules : no_test_defined : $(__name__) : __test__ ;

            # Add some grist so that the module will have a unique target name
            local module-target = $(__file__:G=module@) ;
            
            search = $(3) ;
            search ?= [ modules.peek : BOOST_BUILD_PATH ] ;
            SEARCH on $(module-target) = $(search) ;
            BINDRULE on $(module-target) = modules.record-binding ;
            include $(module-target) ;
        }
        loading-modules = $(loading-modules[1--2]) ;
        
        local argv = [ peek : ARGV ] ;
        if ! $(suppress-test)
        {
            # run any pending tests
            for local m in $(untested)
            {
                if ( --debug in $(argv) ) || ( --debug-module=$(m) in $(argv) )
                {
                    ECHO testing module $(m)... ;
                    module $(m)
                    {
                        __test__ ;
                    }
                }
            }
            untested = ;
        }
    }
    else if $(module-name) in $(loading-modules)
    {
        ECHO loading \"$(module-name)\" ;
        ECHO circular module loading dependency: ;
        EXIT $(loading-modules) $(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-modules[-1]).__binding__ = $(binding) ;
}

# 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-name : rules-opt * : rename-opt * )
{
    load $(module-name) ;
    
    local source-names = $(rules-opt) ;
    if $(rules-opt) = *
    {
        source-names = [ RULENAMES $(module-name) ] ;
    }
    
    local target-names = $(rename-opt) ;
    target-names ?= $(source-names) ;
    IMPORT $(module-name) : $(source-names) : [ CALLER_MODULE ] : $(target-names) ;
}

# Localize the rules of one module into another.
#
rule localize (
    module-name # The module to localize from.
    export # Do we export the rules from the callee module.
    : rules-opt * # Optional list of rules to localize.
    : rename-opt * # Optional list of names to use instead of rules-opt.
    )
{
    local source-names = $(rules-opt) ;
    if $(rules-opt) = *
    {
        source-names = [ RULENAMES $(module-name) ] ;
    }
    
    local target-names = $(rename-opt) ;
    target-names ?= $(source-names) ;
    local caller-module = [ CALLER_MODULE ] ;
    IMPORT $(module-name) : $(source-names) : $(caller-module) : $(target-names) : LOCALIZE ;
    if $(export)
    {
        EXPORT $(caller-module) : $(target-names) ;
        IMPORT $(caller-module) : $(target-names) : : $(caller-module).$(target-names) ;
    }
}

local rule __test__ ( )
{
    import assert ;
    
    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 ;
}