|
本节介绍 Boost.Build 提供的模块。import 规则允许将一个模块的规则用于另一个模块或 Jamfile 中。
modules 模块定义了用于处理模块的基本功能。
模块定义了一些可以在其他模块中使用的规则。模块可以在顶层包含代码以初始化模块。此代码在模块首次加载时执行。
Jamfile 是一种由构建系统管理的特殊模块。虽然用户无法直接加载它们，但模块的其他功能对于 Jamfile 仍然有用。
每个模块都有自己的变量和规则命名空间。如果两个模块 A 和 B 都使用名为 X 的变量，则每个模块都会获得 X 的副本。它们不会以任何方式相互干扰。类似地，将规则导入一个模块不会影响任何其他模块。
每个模块都有两个特殊变量。$(__file__) 包含加载模块的文件的名称，$(__name__) 包含模块的名称。
$(__file__) 不包含文件的完整路径。如果需要此路径，请使用 modules.binding。
rule binding ( module-name )返回给定模块的文件系统绑定。
例如，模块可以使用以下方法获取其自己的位置：
me = [ modules.binding $(__name__) ] ;
rule poke ( module-name ? : variables + : value * )设置变量的模块本地值。
例如，要在全局模块中设置变量：
modules.poke : ZLIB_INCLUDE : /usr/local/include ;
rule peek ( module-name ? : variables + )返回变量的模块本地值。
例如，要从全局模块中读取变量：
local ZLIB_INCLUDE = [ modules.peek : ZLIB_INCLUDE ] ;
rule call-in ( module-name ? : rule-name args * : * ) 在给定模块中本地调用给定规则。对于接受规则名称作为参数的规则，使用此规则，以便传入的规则可以在规则的调用方上下文中调用（例如，如果规则访问模块全局变量或是一个本地规则）。
以这种方式调用的规则最多可以接受 8 个参数。
示例
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 * )如果未加载指示的模块，则加载它。
module-name要加载的模块的名称。
filename(部分) 文件路径；默认为 $(module-name).jam
search搜索 filename 的目录。默认为 $(BOOST_BUILD_PATH)。
rule import ( module-names + : rules-opt * : rename-opt * )加载指示的模块并将规则名称导入当前模块。rules-opt 的任何成员都可以在调用方的模块中无限定义地使用。rename-opt 的任何成员都将被视为调用方的模块中规则的名称，以代替它们在导入模块中的名称。如果 rules-opt = '*'，则从指示的模块导入的所有规则都将被导入到调用方的模块中。如果提供 rename-opt，则它必须与 rules-opt 具有相同数量的元素。
import 规则在所有模块中都无需限定地可用。
示例
import path ; import path : * ; import path : join ; import path : native make : native-path make-path ;
rule clone-rules ( source-module target-module )在 $(target-module) 中定义从 $(source-module) 导出的所有规则的导出副本。还使它们在全局模块中可以使用限定符，因此就好像这些规则最初是在 $(target-module) 中定义的一样。
执行各种路径操作。路径始终以“规范化”表示形式表示。其中，路径可以是
'.'，或者
['/'] [ ( '..' '/' )* (token '/')* token ]
简单来说，路径可以是根路径，'..' 元素仅允许出现在开头，并且永远不会以斜杠结尾，除了仅由斜杠组成的路径。
rule make ( native )将本机路径转换为规范化形式。
rule native ( path )构建路径的本机表示形式。
rule is-rooted ( path )测试路径是否为根路径。
rule has-parent ( path )测试路径是否具有父级。
rule basename ( path )返回没有目录组件的路径。
rule parent ( path )返回路径的父目录。如果不存在父目录，则会发出错误。
rule reverse ( path )返回 path2，使得 [ join path path2 ] = "."。路径可能不包含 ".." 元素或为根路径。
rule join ( elements + )连接传递的路径元素。如果除了第一个元素之外的任何元素都是根路径，则会生成错误。跳过任何空路径元素或未定义路径元素。
rule root ( path root )如果 path 是相对路径，则它以 root 为根路径。否则，它保持不变。
rule pwd ( )返回当前工作目录。
rule glob ( dirs * : patterns + : exclude-patterns * )返回指定目录中与给定模式匹配的文件列表。目录和模式都以可移植路径的形式提供。每个模式都应为非绝对路径，并且不能包含“.”或“..”元素。模式的每个以斜杠分隔的元素都可以包含以下特殊字符
'?' 匹配任何字符
'*' 匹配任意数量的字符
文件 $(d)/e1/e2/e3（其中“d”位于 $(dirs) 中）与模式 p1/p2/p3 匹配当且仅当 e1 与 p1 匹配、e2 与 p2 匹配等等。例如
[ glob . : *.cpp ] [ glob . : */build/Jamfile ]
rule glob-tree ( roots * : patterns + : exclude-patterns * )glob 的递归版本。在构建文件 glob 的同时，还在给定根路径的子目录中搜索。可选的一组排除模式将从结果中过滤掉匹配的条目。排除也适用于子目录扫描，因此与排除模式匹配的目录将不会被搜索。
rule exists ( file )如果指定的文件存在，则返回 true。
rule all-parents ( path : upper_limit ? : cwd ? )找出路径的绝对名称并返回所有父级的列表，从直接父级开始。父级以相对名称的形式返回。如果指定了 upper_limit，则其上方的目录将被修剪。
rule glob-in-parents ( dir : patterns + : upper-limit ? )在 dir 的父目录中搜索 patterns，一直到并包括 upper_limit（如果指定），否则一直到文件系统根目录。
rule relative ( child parent : no-error ? )假设 child 是 parent 的子目录，则返回从 parent 到 child 的相对路径。
rule relative-to ( path1 path2 )返回相对于 path1 的 path2 的最小路径。
rule programs-path ( )返回操作系统用于查找程序的路径列表。
rule makedirs ( path )创建目录以及所有尚不存在的父目录。
包含使用正则表达式的字符串处理规则。
"x*" 匹配模式 "x" 零次或多次。
"x+" 匹配 "x" 一次或多次。
"x?" 匹配 "x" 零次或一次。
"[abcd]" 匹配任何字符 "a"、"b"、"c" 和 "d"。字符范围，例如 "[a-z]"，匹配 "a" 和 "z" 之间的任何字符。 "[^abc]" 匹配任何不是 "a"、"b" 或 "c" 的字符。
"x|y" 匹配模式 "x" 或模式 "y"。
(x) 匹配 "x" 并捕获它。
"^" 匹配字符串的开头。
"$" 匹配字符串的结尾。
"\<" 匹配单词的开头。
"\>" 匹配单词的结尾。
rule split ( string separator )返回以下子字符串的列表
从开头到 separator 的第一次出现，或到结尾。
在 separator 的每次出现和下一次出现之间。
从 separator 的最后一次出现到结尾。
如果不存在分隔符，结果将只包含一个元素。
rule split-list ( list * : separator )返回对列表中每个元素应用 regex.split 的结果的连接。
rule match ( pattern : string : indices * )将 string 与 pattern 匹配，并返回由 indices 指示的元素。
rule transform ( list * : pattern : indices * )将 list 的所有元素与 pattern 匹配，并返回由 indices 指示的所有成功匹配的元素列表。 如果省略了 indices，则返回所有成功匹配的第一个带括号的组的列表。
rule escape ( string : symbols : escape-symbol )使用转义符号 escape-symbol 为给定字符串转义 symbols 中的所有字符，并返回转义后的字符串。
rule replace ( string match replacement )用给定字符串中的匹配字符串替换匹配字符串的出现次数，并返回新的字符串。匹配字符串可以是正则表达式。
rule replace-list ( list * : match : replacement )用给定字符串列表中匹配字符串的出现次数替换匹配字符串的出现次数，并返回新的字符串列表。匹配字符串可以是正则表达式。
另请参阅：MATCH
各种有用的列表函数。请注意，此模块中的算法主要在调用者的模块命名空间中执行，因此局部规则可以用作函数对象。另请注意，大多数谓词可以是多元素列表。在这种情况下，除第一个元素之外的所有元素都将追加到第一个参数，该参数传递给由第一个元素命名的规则。
rule filter ( predicate + : sequence * )返回 $(sequence) 中的元素 e，对于这些元素 [ $(predicate) e ] 具有非空值。
rule transform ( function + : sequence * )返回一个新的序列，该序列由 [ $(function) $(e) ] 组成，其中每个元素 e 都是 $(sequence) 的元素。
rule reverse ( s * )以相反的顺序返回 s 的元素。
rule insertion-sort ( s * : ordered * )使用二元谓词 ordered 对 s 进行插入排序。
rule merge ( s1 * : s2 * : ordered * )使用二元谓词 ordered 合并两个有序序列。
rule join ( s * : joint ? )将 s 的元素连接成一个长字符串。如果提供了 joint，则它用作分隔符。
rule length ( s * )查找任何序列的长度。
rule unique ( list * : stable ? )从 list 中删除重复项。如果传递了 stable，则元素的顺序将保持不变。
rule max-element ( elements + : ordered ? )返回 elements 中的最大值。使用 ordered 进行比较，或者如果未提供则使用 numbers.less。
rule select-highest-ranked ( elements * : ranks * )返回所有 elements，其中平行列表 rank 中的相应元素等于 rank 中的最大值。
处理目标类型声明，并定义支持类型化目标的目标类。
rule register ( type : suffixes * : base-type ? )注册目标类型，可能派生自 base-type。在此处提供一个后缀列表是分别调用 register-suffixes 规则（使用给定的后缀）和 set-generated-target-suffix 规则（使用第一个给定的后缀）的快捷方式。
rule register-suffixes ( suffixes + : type )指定 suffixes 中的后缀的文件将被识别为类型 type 的目标。如果对任何后缀已经指定了不同的类型，则会发出错误。
rule registered ( type )如果类型已注册，则返回 true。否则返回 false。
rule validate ( type )如果 type 未知，则会发出错误。
rule set-scanner ( type : scanner )设置将用于此类型的扫描器类。
rule get-scanner ( type : property-set )返回适合 type 和 property-set 的扫描器实例。
rule base ( type )返回给定类型的基类型，或者在给定类型未派生时返回空值。
rule all-bases ( type )按它们与类型的距离顺序返回给定类型及其所有基类型。
rule all-derived ( type )按它们与类型的距离顺序返回给定类型及其所有派生类型。
rule is-derived ( type base )如果 type 等于 base 或具有 base 作为其直接或间接基类型，则返回 true。否则返回 false。
rule set-generated-target-suffix ( type : properties * : suffix )设置生成具有指定属性的 type 的目标时要使用的文件后缀。如果还没有为 type 指定后缀，则可以不带属性调用它。 suffix 参数可以是空字符串 ("")，以指示不应使用后缀。
请注意，这不会导致带有 suffix 后缀的文件自动识别为 type 类型。两种不同类型可以使用相同的后缀来生成文件，但对于具有该后缀的文件，只能自动检测到一种类型。用户应使用 register-suffixes 规则显式指定哪一个。
rule change-generated-target-suffix ( type : properties * : suffix )更改先前为该类型/属性组合注册的后缀。如果尚未指定后缀，则设置它。
rule generated-target-suffix ( type : property-set )返回使用给定属性生成 type 类型文件时使用的后缀。
rule set-generated-target-prefix ( type : properties * : prefix )设置生成具有指定属性的 type 类型目标时应使用的目标前缀。如果尚未为 type 指定前缀，则可以调用它，并使用空属性。
prefix 参数可以为空字符串 ("")，表示不应使用任何前缀。
使用示例：库名称在 unix 上使用 "lib" 前缀。
rule change-generated-target-prefix ( type : properties * : prefix )更改先前为该类型/属性组合注册的前缀。如果尚未指定前缀，则设置它。
rule generated-target-prefix ( type : property-set )返回使用给定属性生成 type 类型文件时使用的前缀。
rule type ( filename )返回给定文件名的文件类型。如果文件名中有多个点，则尝试每个后缀。例如，对于“file.so.1.2”的文件名，将尝试后缀“2”、“1”和“so”。