source: downloads/boost_1_34_1/tools/build/v2/kernel/modules.jam @ 45

# 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 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 via __test__ rule
.untested ?= ;

# A list of modules which have been tested via __test__
.tested ?= ;

# meant to be invoked from import when no __test__ rule is defined in a given
# module
local rule no-test-defined
{
    import modules ;
    if ! ( --quiet in [ modules.peek : ARGV ] )
    {
        ECHO warning: no __test__ rule defined in module $(__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) ] ;
    }
}

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

# 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 don't try to load it recursively
        .loaded += $(module-name) ;
        
        # 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's 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)
        {
            # 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@) ;
            
            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 "couldn't find module" $(module-name) in $(search) ;
        }
        
        # Pop the loading stack. Must happen before testing or we'll find 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)
            {
                if ( ! $(m) in $(.tested) )    # avoid recursive test invocations
                   && ( ( --debug in $(argv) ) || ( --debug-module=$(m) in $(argv) ) )
                {
                    .tested += $(m) ;
                    if ! ( --quiet in $(argv) )
                    {
                        ECHO testing module $(m)... ;
                    }
                    
                    # Import m's rules into __test-$(m)__ for easy access
                    IMPORT $(m) : [ RULENAMES $(m) ] : __test-$(m)__ : [ RULENAMES $(m) ] ;
                    
                    # execute the module's __test__ rule in its own module to
                    # eliminate the inadvertent effects of testing
                    # module dependencies (such as assert) on the module itself.
                    IMPORT $(m) : __test__ : __test-$(m)__ : __test__ : LOCALIZE ;
                    
                    module __test-$(m)__
                    {
                        # set up the name of the module we're testing
                        # so that no-test-defined can find it.
                        __module__ = $(1) ; 
                        __test__ ;
                    }
                }
            }
            .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'm not sure of that,
# I don't understand it, and I'm 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) 
    {
        if $(rename-opt)
        {
            errors.error "rule aliasing is only available for explicit imports." ;
        }
    }
    
    if $(module-names[2]) && ( $(rules-opt) || $(rename-opt) )
    {
        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)
    {
        if ! $(m) in $(.loaded)
        {           
            # if the importing module isn't already in the BOOST_BUILD_PATH,
            # prepend it to the path.  We don't 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) ;
            }
                        
            load $(m) : : $(search) ;
        }
        
        IMPORT_MODULE $(m) : $(caller) ;
                    
        if $(rules-opt)
        {
            local source-names ;
            if $(rules-opt) = *
            {
                local all-rules = [ RULENAMES $(m) ] ;
                source-names = $(all-rules) ;
            }
            else
            {
                source-names = $(rules-opt) ;
            }
            local target-names = $(rename-opt) ;
            target-names ?= $(source-names) ;
            IMPORT $(m) : $(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 rules = [ RULENAMES $(source-module) ] ;
    
    IMPORT $(source-module) : $(rules) : $(target-module) : $(rules) : LOCALIZE ;
    EXPORT $(target-module) : $(rules) ;
    IMPORT $(target-module) : $(rules) : : $(target-module).$(rules) ;
}

# 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) ;

local 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/.. ;
}