Builtin modules

modules
path
regex
sequence
type

This section describes the modules that are provided by Boost.Build. The import rule allows rules from one module to be used in another module or Jamfile.

modules

The modules module defines basic functionality for handling modules.

A module defines a number of rules that can be used in other modules. Modules can contain code at the top level to initialize the module. This code is executed the first time the module is loaded.

Note

A Jamfile is a special kind of module which is managed by the build system. Although they cannot be loaded directly by users, the other features of modules are still useful for Jamfiles.

Each module has its own namespaces for variables and rules. If two modules A and B both use a variable named X, each one gets its own copy of X. They won't interfere with each other in any way. Similarly, importing rules into one module has no effect on any other module.

Every module has two special variables. $(__file__) contains the name of the file that the module was loaded from and $(__name__) contains the name of the module.

Note

$(__file__) does not contain the full path to the file. If you need this, use modules.binding.

rule binding ( module-name )
Returns the filesystem binding of the given module.

For example, a module can get its own location with:
```
me = [ modules.binding $(__name__) ] ;
```
rule poke ( module-name ? : variables + : value * )
Sets the module-local value of a variable.

For example, to set a variable in the global module:
```
modules.poke : ZLIB_INCLUDE : /usr/local/include ;
```
rule peek ( module-name ? : variables + )
Returns the module-local value of a variable.

For example, to read a variable from the global module:
```
local ZLIB_INCLUDE = [ modules.peek : ZLIB_INCLUDE ] ;
```
rule call-in ( module-name ? : rule-name args * : * )
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

rules called this way may accept at most 8 parameters.

Example:
```
rule filter ( f : values * )
{
    local m = [ CALLER_MODULE ] ;
    local result ;
    for v in $(values)
    {
        if [ modules.call-in $(m) : $(f) $(v) ]
        {
            result += $(v) ;
        }
    }
    return result ;
}
```
rule load ( module-name : filename ? : search * )
Load the indicated module if it is not already loaded.

module-name

Name of module to load.

filename

(partial) path to file; Defaults to $(module-name).jam

search

Directories in which to search for filename. Defaults to $(BOOST_BUILD_PATH).
rule import ( module-names + : rules-opt * : rename-opt * )
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.

Note

The import rule is available without qualification in all modules.

Examples:
```
import path ;
import path : * ;
import path : join ;
import path : native make : native-path make-path ;
```
rule clone-rules ( source-module target-module )
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).

path

Performs various path manipulations. Paths are always in a 'normalized' representation. In it, a path may be either:

'.', or
['/'] [ ( '..' '/' )* (token '/')* token ]

In plain english, a path can be rooted, '..' elements are allowed only at the beginning, and it never ends in slash, except for the path consisting of slash only.

rule make ( native )
Converts the native path into normalized form.
rule native ( path )
Builds the native representation of the path.
rule is-rooted ( path )
Tests if a path is rooted.
rule has-parent ( path )
Tests if a path has a parent.
rule basename ( path )
Returns the path without any directory components.
rule parent ( path )
Returns the parent directory of the path. If no parent exists, an error is issued.
rule reverse ( path )
Returns path2 such that [ join path path2 ] = ".". The path may not contain ".." element or be rooted.
rule join ( elements + )
Concatenates the passed path elements. Generates an error if any element other than the first one is rooted. Skips any empty or undefined path elements.
rule root ( path root )
If path is relative, it is rooted at root. Otherwise, it is unchanged.
rule pwd ( )
Returns the current working directory.
rule glob ( dirs * : patterns + : exclude-patterns * )
Returns the list of files matching the given pattern in the specified directory. Both directories and patterns are supplied as portable paths. Each pattern should be a non-absolute path, and can't contain "." or ".." elements. Each slash separated element of a pattern can contain the following special characters:
- '?' matches any character
- '*' matches an arbitrary number of characters
A file $(d)/e1/e2/e3 (where 'd' is in $(dirs)) matches the pattern p1/p2/p3 if and only if e1 matches p1, e2 matches p2 and so on. For example:
```
[ glob . : *.cpp ]
[ glob . : */build/Jamfile ]
```
rule glob-tree ( roots * : patterns + : exclude-patterns * )
Recursive version of glob. Builds the glob of files while also searching in the subdirectories of the given roots. An optional set of exclusion patterns will filter out the matching entries from the result. The exclusions also apply to the subdirectory scanning, such that directories that match the exclusion patterns will not be searched.
rule exists ( file )
Returns true if the specified file exists.
rule all-parents ( path : upper_limit ? : cwd ? )
Find out the absolute name of path and return the list of all the parents, starting with the immediate one. Parents are returned as relative names. If upper_limit is specified, directories above it will be pruned.
rule glob-in-parents ( dir : patterns + : upper-limit ? )
Search for patterns in parent directories of dir, up to and including upper_limit, if it is specified, or till the filesystem root otherwise.
rule relative ( child parent : no-error ? )
Assuming child is a subdirectory of parent, return the relative path from parent to child.
rule relative-to ( path1 path2 )
Returns the minimal path to path2 that is relative path1.
rule programs-path ( )
Returns the list of paths which are used by the operating system for looking up programs.
rule makedirs ( path )
Creates a directory and all parent directories that do not already exist.

regex

Contains rules for string processing using regular expressions.

"x*" matches the pattern "x" zero or more times.
"x+" matches "x" one or more times.
"x?" matches "x" zero or one time.
"[abcd]" matches any of the characters, "a", "b", "c", and "d". A character range such as "[a-z]" matches any character between "a" and "z". "[^abc]" matches any character which is not "a", "b", or "c".
"x|y" matches either pattern "x" or pattern "y"
(x) matches "x" and captures it.
"^" matches the beginning of the string.
"$" matches the end of the string.
"\<" matches the beginning of a word.
"\>" matches the end of a word.

rule split ( string separator )
Returns a list of the following substrings:
1. from beginning till the first occurrence of separator or till the end,
2. between each occurrence of separator and the next occurrence,
3. from the last occurrence of separator till the end.
If no separator is present, the result will contain only one element.
rule split-list ( list * : separator )
Returns the concatenated results of applying regex.split to every element of the list using the separator pattern.
rule match ( pattern : string : indices * )
Match string against pattern, and return the elements indicated by indices.
rule transform ( list * : pattern : indices * )
Matches all elements of list against the pattern and returns a list of elements indicated by indices of all successful matches. If indices is omitted returns a list of first parenthesized groups of all successful matches.
rule escape ( string : symbols : escape-symbol )
Escapes all of the characters in symbols using the escape symbol escape-symbol for the given string, and returns the escaped string.
rule replace ( string match replacement )
Replaces occurrences of a match string in a given string and returns the new string. The match string can be a regex expression.
rule replace-list ( list * : match : replacement )
Replaces occurrences of a match string in a given list of strings and returns a list of new strings. The match string can be a regex expression.

sequence

Various useful list functions. Note that algorithms in this module execute largely in the caller's module namespace, so that local rules can be used as function objects. Also note that most predicates can be multi-element lists. In that case, all but the first element are prepended to the first argument which is passed to the rule named by the first element.

rule filter ( predicate + : sequence * )
Return the elements e of $(sequence) for which [ $(predicate) e ] has a non-null value.
rule transform ( function + : sequence * )
Return a new sequence consisting of [ $(function) $(e) ] for each element e of $(sequence).
rule reverse ( s * )
Returns the elements of s in reverse order.
rule insertion-sort ( s * : ordered * )
Insertion-sort s using the BinaryPredicate ordered.
rule merge ( s1 * : s2 * : ordered * )
Merge two ordered sequences using the BinaryPredicate ordered.
rule join ( s * : joint ? )
Join the elements of s into one long string. If joint is supplied, it is used as a separator.
rule length ( s * )
Find the length of any sequence.
rule unique ( list * : stable ? )
Removes duplicates from list. If stable is passed, then the order of the elements will be unchanged.
rule max-element ( elements + : ordered ? )
Returns the maximum number in elements. Uses ordered for comparisons or numbers.less if none is provided.
rule select-highest-ranked ( elements * : ranks * )
Returns all of elements for which the corresponding element in the parallel list rank is equal to the maximum value in rank.

type

Deals with target type declaration and defines target class which supports typed targets.

rule register ( type : suffixes * : base-type ? )
Registers a target type, possible derived from a base-type. Providing a list of suffixes here is a shortcut for separately calling the register-suffixes rule with the given suffixes and the set-generated-target-suffix rule with the first given suffix.
rule register-suffixes ( suffixes + : type )
Specifies that files with suffix from suffixes be recognized as targets of type type. Issues an error if a different type is already specified for any of the suffixes.
rule registered ( type )
Returns true iff type has been registered.
rule validate ( type )
Issues an error if type is unknown.
rule set-scanner ( type : scanner )
Sets a scanner class that will be used for this type.
rule get-scanner ( type : property-set )
Returns a scanner instance appropriate to type and property-set.
rule base ( type )
Returns a base type for the given type or nothing in case the given type is not derived.
rule all-bases ( type )
Returns the given type and all of its base types in order of their distance from type.
rule all-derived ( type )
Returns the given type and all of its derived types in order of their distance from type.
rule is-derived ( type base )
Returns true if type is equal to base or has base as its direct or indirect base.
rule set-generated-target-suffix ( type : properties * : suffix )
Sets a file suffix to be used when generating a target of type with the specified properties. Can be called with no properties if no suffix has already been specified for the type. The suffix parameter can be an empty string ("") to indicate that no suffix should be used.

Note that this does not cause files with suffix to be automatically recognized as being of type. Two different types can use the same suffix for their generated files but only one type can be auto-detected for a file with that suffix. User should explicitly specify which one using the register-suffixes rule.
rule change-generated-target-suffix ( type : properties * : suffix )
Change the suffix previously registered for this type/properties combination. If suffix is not yet specified, sets it.
rule generated-target-suffix ( type : property-set )
Returns the suffix used when generating a file of type with the given properties.
rule set-generated-target-prefix ( type : properties * : prefix )
Sets a target prefix that should be used when generating targets of type with the specified properties. Can be called with empty properties if no prefix for type has been specified yet.

The prefix parameter can be empty string ("") to indicate that no prefix should be used.

Usage example: library names use the "lib" prefix on unix.
rule change-generated-target-prefix ( type : properties * : prefix )
Change the prefix previously registered for this type/properties combination. If prefix is not yet specified, sets it.
rule generated-target-prefix ( type : property-set )
Returns the prefix used when generating a file of type with the given properties.
rule type ( filename )
Returns file type given its name. If there are several dots in filename, tries each suffix. E.g. for name of "file.so.1.2" suffixes "2", "1", and "so" will be tried.