summaryrefslogtreecommitdiff
path: root/jam-files/boost-build/kernel/modules.jam
blob: 1f75354fc2f4372c8e618323bf0bf165fdddc0f5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
# 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 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 8 parameters.
#
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. Note that
# rules called this way may accept at most 8 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 8 parameters here since Boost Jam allows at most 9 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) ] ;
}


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

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


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