|
本節描述 Boost.Build 提供的模組。import 規則允許在另一個模組或 Jamfile 中使用來自一個模組的規則。
modules 模組定義了處理模組的基本功能。
一個模組定義了許多可以在其他模組中使用的規則。模組可以在頂層包含程式碼來初始化模組。這段程式碼會在模組第一次載入時執行。
Jamfile 是一種由建置系統管理的特殊模組。雖然它們不能由使用者直接載入，但模組的其他功能仍然對 Jamfile 很有用。
每個模組都有自己的變數和規則命名空間。如果兩個模組 A 和 B 都使用名為 X 的變數，則每個模組都會獲得自己的 X 副本。它們不會以任何方式互相干擾。同樣，將規則匯入一個模組不會影響任何其他模組。
每個模組都有兩個特殊的變數。$(__file__) 包含載入模組的檔案名稱，而 $(__name__) 包含模組的名稱。
$(__file__) 不包含檔案的完整路徑。如果您需要這個，請使用 modules.binding。
rule binding ( 模組名稱 )返回指定模組的檔案系統繫結。
例如，一個模組可以使用以下方式取得其自身的位置：
me = [ modules.binding $(__name__) ] ;
rule poke ( 模組名稱 ? : 變數 + : 值 * )設定模組區域變數的值。
例如，要在全域模組中設定一個變數：
modules.poke : ZLIB_INCLUDE : /usr/local/include ;
rule peek ( 模組名稱 ? : 變數 + )返回模組區域變數的值。
例如，要從全域模組讀取一個變數：
local ZLIB_INCLUDE = [ modules.peek : ZLIB_INCLUDE ] ;
rule call-in ( 模組名稱 ? : 規則名稱 參數 * : * ) 在指定的模組中局部呼叫指定的規則。將此用於接受規則名稱作為參數的規則，以便可以在規則呼叫者的上下文中呼叫傳遞的規則（例如，如果規則存取模組全域變數或是一個局部規則）。
以這種方式呼叫的規則最多可以接受 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).jam
搜尋路徑搜尋檔案名稱的目錄。預設為 $(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 ] = "."。路徑不能包含 ".." 元素或為根目錄。
規則 join ( elements + )連接傳入的路徑元素。如果第一個元素以外的任何元素是根路徑，則會產生錯誤。會略過任何空的路徑元素或未定義的路徑元素。
規則 root ( path root )如果 path 是相對路徑，則會以 root 作為根目錄。否則，它將保持不變。
規則 pwd ( )返回目前的工作目錄。
規則 glob ( dirs * : patterns + : exclude-patterns * )返回指定目錄中符合給定模式的檔案列表。目錄和模式都以可攜式路徑的形式提供。每個模式都應該是相對路徑，且不能包含「.」或「..」元素。模式中每個以斜線分隔的元素可以包含以下特殊字元：
「?」 匹配任何單一字元
「*」 匹配任意數量的字元
檔案 $(d)/e1/e2/e3（其中 'd' 位於 $(dirs) 中）匹配模式 p1/p2/p3 的條件是 e1 匹配 p1，e2 匹配 p2，依此類推。例如：
[ glob . : *.cpp ] [ glob . : */build/Jamfile ]
規則 glob-tree ( roots * : patterns + : exclude-patterns * )glob 的遞迴版本。在建立檔案 glob 的同時，也會搜尋給定根目錄的子目錄。一組選用的排除模式會從結果中篩選出匹配的項目。排除也適用於子目錄掃描，因此不會搜尋符合排除模式的目錄。
規則 exists ( file )如果指定的檔案存在，則返回 true。
規則 all-parents ( path : upper_limit ? : cwd ? )找出路徑的絕對名稱，並返回所有父目錄的列表，從直接父目錄開始。父目錄以相對名稱返回。如果指定了 upper_limit，則會修剪其上方的目錄。
規則 glob-in-parents ( dir : patterns + : upper-limit ? )在 dir 的父目錄中搜尋 patterns，直到包含 upper-limit（如果已指定），否則直到檔案系統根目錄。
規則 relative ( child parent : no-error ? )假設 child 是 parent 的子目錄，返回從 parent 到 child 的相對路徑。
規則 relative-to ( path1 path2 )返回相對於 path1 的 path2 的最短路徑。
規則 programs-path ( )返回作業系統用於查找程式的路徑清單。
規則 makedirs ( 路徑 )建立一個目錄以及所有尚不存在的父目錄。
包含使用正規表達式處理字串的規則。
"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" 並擷取它。
"^" 匹配字串的開頭。
"$" 匹配字串的結尾。
"\<" 匹配單字的開頭。
"\>" 匹配單字的結尾。
規則 split ( 字串 分隔符號 )返回以下子字串的清單：
從開頭到 分隔符號 的第一次出現或到結尾，
分隔符號 的每次出現與下一次出現之間，
從 分隔符號 的最後一次出現到結尾。
如果沒有分隔符號，結果將只包含一個元素。
規則 split-list ( 清單 * : 分隔符號 )返回使用分隔符號模式將 regex.split 套用到清單中每個元素的串接結果。
規則 match ( 模式 : 字串 :: 索引 * )將 字串 與 模式 進行比對，並返回 索引 指示的元素。
規則 transform ( 清單 * : 模式 :: 索引 * )將 清單 的所有元素與 模式 進行比對，並返回所有成功比對的 索引 指示的元素清單。如果省略 索引，則返回所有成功比對的第一個括號群組的清單。
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 * )返回一個新的序列，由 $(sequence) 中每個元素 e 的 [ $(function) $(e) ] 組成。
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 * )查找任何序列的長度。
規則 unique ( 清單 * : stable ? )從 清單 中移除重複的元素。如果傳入 stable 參數，則元素的順序將保持不變。
規則 max-element ( 元素 + : ordered ? )返回 元素 中的最大值。使用 ordered 進行比較，如果未提供則使用 numbers.less。
規則 select-highest-ranked ( 元素 * : 排名 * )返回所有 元素 中，對應於平行清單 排名 中的元素等於 排名 中最大值的元素。
處理目標類型宣告，並定義支援類型化目標的目標類別。
規則 register ( 類型 : 後綴 * : 基礎類型 ? )註冊一個目標類型，可能衍生自 基礎類型。在此提供後綴清單是分別呼叫 register-suffixes 規則（使用給定的後綴）和 set-generated-target-suffix 規則（使用第一個給定的後綴）的捷徑。
規則 register-suffixes ( 後綴 + : 類型 )指定具有 後綴 中後綴的檔案將被識別為 類型 類型的目標。如果已為任何後綴指定了不同的類型，則會發出錯誤。
規則 registered ( 類型 )若且唯若類型已註冊，則返回 true。
規則 validate ( 類型 )如果 類型 未知，則發出錯誤。
規則 set-scanner ( 類型 : 掃描器 )設定將用於此類型的掃描器類別。
規則 get-scanner ( 類型 : 屬性集 )返回適用於 類型 和 屬性集 的掃描器實例。
規則 base ( 類型 )返回給定類型的基礎類型，如果給定類型不是衍生類型，則不返回任何內容。
規則 all-bases ( 類型 )按照與類型距離的順序返回給定類型及其所有基礎類型。
規則 all-derived ( 類型 )傳回給定的類型及其所有衍生類型，並按照它們與給定類型的距離排序。
規則 is-derived ( 類型 基底類型 )如果 類型 等於 基底類型 或具有 基底類型 作為其直接或間接基底，則傳回 true。
規則 set-generated-target-suffix ( 類型 : 屬性 * : 後綴 )設定在使用指定屬性產生 類型 的目標時要使用的檔案後綴。如果尚未為 類型 指定後綴，則可以在沒有屬性的情況下呼叫。 後綴 參數可以是空字串 ("") 表示不應使用後綴。
請注意，這不會導致具有 後綴 的檔案被自動識別為 類型。兩種不同的類型可以對其產生的檔案使用相同的後綴，但對於具有該後綴的檔案，只能自動偵測一種類型。使用者應使用 register-suffixes 規則明確指定要使用的類型。
規則 change-generated-target-suffix ( 類型 : 屬性 * : 後綴 )變更先前為此類型/屬性組合註冊的後綴。如果尚未指定後綴，則設定它。
規則 generated-target-suffix ( 類型 : 屬性集 )傳回在使用給定屬性產生 類型 的檔案時使用的後綴。
規則 set-generated-target-prefix ( 類型 : 屬性 * : 前綴 )設定在產生具有指定屬性的 類型 的目標時應使用的目標前綴。如果尚未為 類型 指定前綴，則可以在沒有屬性的情況下呼叫。
前綴 參數可以是空字串 ("")，表示不應使用前綴。
使用範例：在 Unix 系統上，程式庫名稱使用 "lib" 前綴。
規則 change-generated-target-prefix ( 類型 : 屬性 * : 前綴 )變更先前為此類型/屬性組合註冊的前綴。如果尚未指定前綴，則設定它。
規則 generated-target-prefix ( 類型 : 屬性集 )傳回在使用給定屬性產生 類型 的檔案時使用的前綴。
rule type ( filename )傳回指定檔名的檔案類型。若檔名中有多個點號，則會嘗試每個後綴。例如，對於檔名 "file.so.1.2"，將會嘗試後綴 "2"、"1" 和 "so"。