Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Language 語言

Lexical Features 詞彙特徵
Targets 目標
Rules 規則
Flow-of-Control 控制流
Variables 變量
Modules 模塊

BJam has an interpreted, procedural language. Statements in bjam are rule (procedure) definitions, rule invocations, flow-of-control structures, variable assignments, and sundry language support.
BJam 有一個解釋性的過程語言。bjam 中的語句包括規則(過程)定義,規則調用,控制流結構,變量賦值和各種語言支持。

BJam treats its input files as whitespace-separated tokens, with two exceptions: double quotes (") can enclose whitespace to embed it into a token, and everything between the matching curly braces ({}) in the definition of a rule action is treated as a single string. A backslash (\) can escape a double quote, or any single whitespace character.
BJam 將它的輸入文件視為以空白分隔的記號,除了兩種例外:雙引號(")可以將空白包含在一個記號中,而在規則動作定義中位於一對大括號({})間的所有東西則被視為單個字符串。後斜槓(\)可以對雙引號或任一空白字符進行轉義。

BJam requires whitespace (blanks, tabs, or newlines) to surround all tokens, including the colon (:) and semicolon (;) tokens.
BJam 要求用空白(空格、製表符或換行符)來包圍所有記號,包括冒號(:)和分號(;)記號。

BJam keywords (an mentioned in this document) are reserved and generally must be quoted with double quotes (") to be used as arbitrary tokens, such as variable or target names.
BJam 的關鍵字(本文檔所提及的)是保留的,如果要作為記號使用,如變量名或目標名,則必須用雙引號(")引起來。

Comments start with the # character and extend until the end of line.
註釋以 # 字符開始,直至行末。

The essential bjam data entity is a target. Build targets are files to be updated. Source targets are the files used in updating built targets. Built targets and source targets are collectively referred to as file targets, and frequently built targets are source targets for other built targets. Pseudotargets are symbols which represent dependencies on other targets, but which are not themselves associated with any real file.
實質的 bjam 數據實體是一個目標。構建的目標是要更新的文件。源目標是在更新構建目標中使用的文件。構建目標和源目標都是文件目標,而且通常構建目標就是其它構建目標的源目標。偽目標是一些符號,用於表示與其它目標的依賴關係,但它們本身並沒有關聯到真實的文件。

A file target's identifier is generally the file's name, which can be absolutely rooted, relative to the directory of bjam's invocation, or simply local (no directory). Most often it is the last case, and the actual file path is bound using the $(SEARCH) and $(LOCATE) special variables. See SEARCH and LOCATE Variables below. A local filename is optionally qualified with grist, a string value used to assure uniqueness. A file target with an identifier of the form file(member) is a library member (usually an ar(1) archive on Unix).
一個文件目標的標識符通常就是文件的名字,可以是絕對路徑,或者是相對於調用 bjam 的目錄的相對路徑,或者就是本地(無目錄)。最常見的就是最後一種,真正的文件路徑使用 $(SEARCH)$(LOCATE) 變量來綁定。詳見後文的 SEARCH 和 LOCATE 變量。一個本地的文件名可以帶有 grist,即一個用於確保唯一性的字符串值。帶有形如 file(member) 的標識符的文件目標是一個庫成員(在 Unix 上通常是一個 ar(1) 存檔)。

Whenever a target is bound to a location in the filesystem, Boost Jam will look for a variable called BINDRULE (first "on" the target being bound, then in the global module). If non-empty, =$(BINDRULE[1])= names a rule which is called with the name of the target and the path it is being bound to. The signature of the rule named by =$(BINDRULE[1])= should match the following:
只要一個目標被綁定到文件系統的某個位置,Boost Jam 就會查找一個名為 BINDRULE (首先在被綁定目標上查找,然後在全局模塊中查找)的變量。如果非空,則 =$(BINDRULE[1])= 命名了一個規則,該規則會以目標名及所綁定的路徑來調用。由 =$(BINDRULE[1])= 命名的規則的簽名應符合:

rule bind-rule ( target : path )

This facility is useful for correct header file scanning, since many compilers will search for #include files first in the directory containing the file doing the #include directive. $(BINDRULE) can be used to make a record of that directory.
對於正確的頭文件掃瞄來說這一工具非常有用,因為許多編譯器會首先在包含了執行 #include 指令的文件的目錄中查找 #include 文件。$(BINDRULE) 可以用於對該目錄作一個記錄。

The basic bjam language entity is called a rule. A rule is defined in two parts: the procedure and the actions. The procedure is a body of jam statements to be run when the rule is invoked; the actions are the OS shell commands to execute when updating the built targets of the rule.
基本的 bjam 語言實體稱為規則。規則由兩部分定義:過程和動作。過程是一組 jam 語句,在規則被調用時運行;動作是一些 OS shell 命令,在更新該規則的構建目標時執行。

Rules can return values, which can be expanded into a list with "[ rule args ... ]". A rule's value is the value of its last statement, though only the following statements have values: 'if' (value of the leg chosen), 'switch' (value of the case chosen), set (value of the resulting variable), and 'return' (value of its arguments). Note that 'return' doesn't actually cause a return, i.e., is a no-op unless it is the last statement of the last block executed within rule body.
規則可以返回值,返回值可以被展開到一個帶 "[ rule args ... ]" 的列表中。規則的值為它的最後一條語句的值,只有以下語句具有值:'if' (被選分支的值), 'switch' (被選分支的值), set (結果變量的值), 和 'return' (其參數的值)。注意,'return' 並不是真的進行返回,即它只是一個空操作,除非它是在規則體中執行的最後一個塊的最後一條語句。

The bjam statements for defining and invoking rules are as follows:
用於定義和調用規則的 bjam 語句如下:

Define a rule's procedure, replacing any previous definition.
定義一個規則的過程,替換前面的定義。

rule rulename { statements }

Define a rule's updating actions, replacing any previous definition.
定義一個規則的更新動作,替換前面的定義。

actions [ modifiers ] rulename { commands }

Invoke a rule.
調用一個規則。

rulename field1 : field2 : ... : fieldN ;

Invoke a rule under the influence of target's specific variables..
在目標的特定變量的影響下調用規則..

on target rulename field1 : field2 : ... : fieldN ;

Used as an argument, expands to the return value of the rule invoked.
被用作一個參數,展開為規則調用的返回值。

[ rulename field1 : field2 : ... : fieldN ]
[ on target rulename field1 : field2 : ... : fieldN ]

A rule is invoked with values in field1 through fieldN. They may be referenced in the procedure's statements as $(1) through $(N) (9 max), and the first two only may be referenced in the action's commands as $(1) and $(2). $(<) and $(>) are synonymous with $(1) and $(2).
以從 field1fieldN 的值來調用規則。這些參數在過程語句中可以用 $(1)$(N) (最大為9)來引用,只有前兩個參數可以在動作的 命令 中用 $(1)$(2) 來引用。$(<)$(>) 分別是 $(1)$(2) 的別名。

Rules fall into two categories: updating rules (with actions), and pure procedure rules (without actions). Updating rules treat arguments $(1) and $(2) as built targets and sources, respectively, while pure procedure rules can take arbitrary arguments.
規則被分為兩類:更新規則(帶動作),和純過程規則(不帶動作)。更新規則將參數 $(1)$(2) 分別視為構建目標和源,而純過程規則可以接受任意多參數。

When an updating rule is invoked, its updating actions are added to those associated with its built targets ($(1)) before the rule's procedure is run. Later, to build the targets in the updating phase, commands are passed to the OS command shell, with $(1) and $(2) replaced by bound versions of the target names. See Binding above.
當一個更新規則被調用時,在規則的過程運行之前,它的更新動作被加上它的構建目標($(1))。然後,在更新階段構建這一目標,命令 被傳遞給 OS command shell,其中 $(1)$(2) 被替換為目標名的被綁定版本。請參見前面的"綁定"一節。

Rule invocation may be indirected through a variable:
規則可以通過一個變量來間接調用:

$(var) field1 : field2 : ... : fieldN ;

on target $(var) field1 : field2 : ... : fieldN ;

[ $(var) field1 : field2 : ... : fieldN ]
[ on target $(var) field1 : field2 : ... : fieldN ]

The variable's value names the rule (or rules) to be invoked. A rule is invoked for each element in the list of $(var)'s values. The fields field1 : field2 : ... are passed as arguments for each invokation. For the [ ... ] forms, the return value is the concatenation of the return values for all of the invocations.
該變量的值表示了被調用的規則(或多條規則)。對於在 $(var) 的值的列表中每個元素,調用對應的規則。字段 field1 : field2 : ... 被作為參數傳遞給每一次調用。對於 [ ... ] 形式,返回值為所有調用的返回值的串接。

The following action modifiers are understood:
以下是動作修改符:

actions bind vars

$(vars) will be replaced with bound values.
$(vars) 被替換為綁定值。

actions existing

$(>) includes only source targets currently existing.
$(>) 只包含當前已有的源目標。

actions ignore

The return status of the commands is ignored.
命令的返回狀態被忽略。

actions piecemeal

commands are repeatedly invoked with a subset of $(>) small enough to fit in the command buffer on this OS.
$(>) 的子集重複調用命令,每次調用的參數要足夠小以滿足 OS 的命令緩衝區。

actions quietly

The action is not echoed to the standard output.
該動作不在標準輸出上回顯。

actions together

The $(>) from multiple invocations of the same action on the same built target are glommed together.
將來自同一個構建目標上的同一個動作的多次調用的 $(>) 組合起來。

actions updated

$(>) includes only source targets themselves marked for updating.
$(>) 只包含被標記為更新的源目標本身。

You can describe the arguments accepted by a rule, and refer to them by name within the rule. For example, the following prints "I'm sorry, Dave" to the console:
你可以描述規則所接受的參數,並在規則內部通過名字來引用它們。例如,以下將在控制台上打印 "I'm sorry, Dave":

rule report ( pronoun index ? : state : names + )
{
local he.suffix she.suffix it.suffix = s ;
local I.suffix = m ;
local they.suffix you.suffix = re ;
ECHO $(pronoun)'$($(pronoun).suffix) $(state), $(names[$(index)]) ;
}
report I 2 : sorry : Joe Dave Pete ;

Each name in a list of formal arguments (separated by ":" in the rule declaration) is bound to a single element of the corresponding actual argument unless followed by one of these modifiers:
在形參列表中的每個名字(在規則聲明中以 ":" 分隔)被綁定到對應的實參中的一個元素,除非後跟以下修改符之一:

Symbol 符號

Semantics of preceding symbol 前述符號的語義

?

optional

可選

*

Bind to zero or more unbound elements of the actual argument. When * appears where an argument name is expected, any number of additional arguments are accepted. This feature can be used to implement "varargs" rules.

綁定到實參中零個或多個未綁定的元素。當 * 出現在參數名的位置上時,將接受任意數量的額外參數。該特性可用於實現 "varargs" 規則。

+

Bind to one or more unbound elements of the actual argument.

縮寫到實參中一個或多個未綁定的元素。

The actual and formal arguments are checked for inconsistencies, which cause Jam to exit with an error code:
實參和形參要檢查是否矛盾,矛盾將導致 Jam 以一個錯誤代碼退出:

### argument error
# rule report ( pronoun index ? : state : names + )
# called with: ( I 2 foo : sorry : Joe Dave Pete )
# extra argument foo
### argument error
# rule report ( pronoun index ? : state : names + )
# called with: ( I 2 : sorry )
# missing argument names

If you omit the list of formal arguments, all checking is bypassed as in "classic" Jam. Argument lists drastically improve the reliability and readability of your rules, however, and are strongly recommended for any new Jam code you write.
如果你省略了形參列表,則所有檢查將被跳過,和 "經典" Jam 一樣。但是,參數列表大大改進了你的規則的可靠性和可讀性,強烈建議在你新編寫的 Jam 代碼中使用。

BJam has a growing set of built-in rules, all of which are pure procedure rules without updating actions. They are in three groups: the first builds the dependency graph; the second modifies it; and the third are just utility rules.
BJam 有一組新增的內建規則,它們都是不帶更新動作的純過程規則。它們被分為三組:第一組構建依賴關係圖;第二組修改它;第三組是工具規則。

rule DEPENDS ( targets1 * : targets2 * )

Builds a direct dependency: makes each of targets1 depend on each of targets2. Generally, targets1 will be rebuilt if targets2 are themselves rebuilt are or are newer than targets1.
構建一個直接依賴關係:讓每個 targets1 依賴於每個 targets2。通常,如果 targets2 本身被重新構建或比 targets1 新,則重新構建 targets1

rule INCLUDES ( targets1 * : targets2 * )

Builds a sibling dependency: makes any target that depends on any of targets1 also depend on each of targets2. This reflects the dependencies that arise when one source file includes another: the object built from the source file depends both on the original and included source file, but the two sources files don't depend on each other. For example:
構建一個兄弟依賴關係:讓任何依賴於任一 targets1 的目標也依賴於每個 targets2。它反映了當一個源文件包含另一個文件時引起的依賴關係:從源文件所構建的對象同時依賴於原始文件和其中包含的源文件,但是這兩個源文件互不依賴。例如:

DEPENDS foo.o : foo.c ;
INCLUDES foo.c : foo.h ;

"foo.o" depends on "foo.c" and "foo.h" in this example.
在這個例子中,"foo.o" 依賴於 "foo.c" 和 "foo.h"。

The six rules ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, and TEMPORARY modify the dependency graph so that bjam treats the targets differently during its target binding phase. See Binding above. Normally, bjam updates a target if it is missing, if its filesystem modification time is older than any of its dependencies (recursively), or if any of its dependencies are being updated. This basic behavior can be changed by invoking the following rules:
有六個規則 ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, 和 TEMPORARY 會修改依賴關係圖,讓 bjam 在目標綁定階段特殊對待這些目標。參見前文中的"綁定"。通常,bjam 在一個目標不存在,或文件系統中的文件修改時間早於它的任一個依賴文件(遞歸地),或它的任一依賴文件被更新時更新該目標。這種基本行為可以通過調用以下規則來改變:

rule ALWAYS ( targets * )

Causes targets to be rebuilt regardless of whether they are up-to-date (they must still be in the dependency graph). This is used for the clean and uninstall targets, as they have no dependencies and would otherwise appear never to need building. It is best applied to targets that are also NOTFILE targets, but it can also be used to force a real file to be updated as well.
不論 targets 是否最新的,均重新構建(但目標必須是在依賴關係圖中的)。它用於乾淨和去安裝的目標,因為它們沒有依賴關係,不會出現在需要構建的目標中。它最適合用於 NOTFILE 的目標,不過也可以用於強迫更新一個真實文件。

rule LEAVES ( targets * )

Makes each of targets depend only on its leaf sources, and not on any intermediate targets. This makes it immune to its dependencies being updated, as the "leaf" dependencies are those without their own dependencies and without updating actions. This allows a target to be updated only if original source files change.
使得每個 targets 只依賴於它的葉子源文件,而不依賴於任何中間目標。這使得它不受依賴關係更新的影響,因為"葉子"依賴關係沒有本身的依賴關係和更新動作。它允許一個目標僅當其原始源文件變化時才更新。

rule NOCARE ( targets * )

Causes bjam to ignore targets that neither can be found nor have updating actions to build them. Normally for such targets bjam issues a warning and then skips other targets that depend on these missing targets. The HdrRule in Jambase uses NOCARE on the header file names found during header file scanning, to let bjam know that the included files may not exist. For example, if an #include is within an #ifdef, the included file may not actually be around.
bjam 忽略 targets,既不管是否能找到它們,也不管是否有更新動作來更新它們。通常對於這些目標,bjam 發出一個警告然後跳過其它依賴於這些不可用目標的目標。在 Jambase 中的 HdrRule 對那些在頭文件掃瞄期間找到的頭文件名使用 NOCARE,讓 bjam 知道這些頭文件可能會不存在。例如,如果一個 #include 是在 #ifdef 中的,那麼被包含的頭文件可能並不真實存在。

[Warning] Warning 警告

For targets with build actions: if their build actions exit with a nonzero return code, dependent targets will still be built.

對於帶有構建動作的目標:如果它們的構建動作以一個非零返回碼退出,則依賴它的目標仍會被構建。

rule NOTFILE ( targets * )

Marks targets as pseudotargets and not real files. No timestamp is checked, and so the actions on such a target are only executed if the target's dependencies are updated, or if the target is also marked with ALWAYS. The default bjam target "all" is a pseudotarget. In Jambase, NOTFILE is used to define several addition convenient pseudotargets.
targets 標記為偽目標和非真實文件。沒有時間戳可被檢查,所以在這種目標上的動作只有當目標的依賴對像被更新,或該目標同時被標記為 ALWAYS 時才會執行。缺省的 bjam 目標 "all" 就是一個偽目標。在 Jambase 中,NOTFILE 被用來定義了幾個另外的方便使用的偽目標。

rule NOUPDATE ( targets * )

Causes the timestamps on targets to be ignored. This has two effects: first, once the target has been created it will never be updated; second, manually updating target will not cause other targets to be updated. In Jambase, for example, this rule is applied to directories by the MkDir rule, because MkDir only cares that the target directory exists, not when it has last been updated.
使得 targets 的時間戳被忽略。這有兩個作用:首先,一旦該目標被創建就不會再被更新;其次,手工更新目標不會引起其它目標被更新。例如,在 Jambase 中,這個規則被 MkDir 規則應用於目錄,因為 MkDir 只關心目標目錄是否存在,而不關心目錄何時被最後更新。

rule TEMPORARY ( targets * )

Marks targets as temporary, allowing them to be removed after other targets that depend upon them have been updated. If a TEMPORARY target is missing, bjam uses the timestamp of the target's parent. Jambase uses TEMPORARY to mark object files that are archived in a library after they are built, so that they can be deleted after they are archived.
targets 標記為臨時的,允許在依賴於它們的其它目標完成更新後刪除它們。如果一個 TEMPORARY 目標不存在,bjam 就使用該目標的父目錄的時間戳。Jambase 使用 TEMPORARY 來對在構建後歸檔到庫中的文件進行標記,這樣在它們被歸檔後就可以刪除了。

rule FAIL_EXPECTED ( targets * )

For handling targets whose build actions are expected to fail (e.g. when testing that assertions or compile-time type checkin work properly), Boost Jam supplies the FAIL_EXPECTED rule in the same style as NOCARE, et. al. During target updating, the return code of the build actions for arguments to FAIL_EXPECTED is inverted: if it fails, building of dependent targets continues as though it succeeded. If it succeeds, dependent targets are skipped.
為了處理那些構建動作預期會失敗(如,在測試斷言或編譯期類型檢查是否正確工作時)的目標,Boost Jam 提供了 FAIL_EXPECTED 規則,它與 NOCARE 相似,只是在目標更新期間,對於 FAIL_EXPECTED 目標的構建動作的返回碼是相反的:如果失敗,相關目標的構建會繼續。而如果成功,則相關目標被跳過。

rule RMOLD ( targets * )

BJam removes any target files that may exist on disk when the rule used to build those targets fails. However, targets whose dependencies fail to build are not removed by default. The RMOLD rule causes its arguments to be removed if any of their dependencies fail to build.
BJam 在使用該規則構建目標失敗時將刪除可能留在磁盤上的目標文件。但是,那些依賴於構建失敗的對象的目標缺省並不刪除。RMOLD 規則導致其參數在它們所依賴的對象構建失敗時被刪除。

rule ISFILE ( targets * )

ISFILE marks targets as required to be files. This changes the way bjam searches for the target such that it ignores mathes for file system items that are not file, like directories. This makes it possible to avoid #include "exception" matching if one happens to have a directory named exception in the header search path.
ISFILE 將 targets 標記為要求目標必須是文件。這將改變 bjam 查找目標的方式,它將忽略那些被匹配到的但不是文件的文件系統項目,如目錄。這樣可以避免 #include "exception" 在恰好有一個名為 exception 的目錄位於頭文件查找路徑中時不會被匹配到。

[Warning] Warning 警告

This is currently not fully implemented.

當前尚未完全實現。

The two rules ECHO and EXIT are utility rules, used only in bjam's parsing phase.
ECHOEXIT 這兩個規則是工具規則,僅在 bjam 的分析階段使用。

rule ECHO ( args * )

Blurts out the message args to stdout.
將信息 args 輸出到 stdout。

rule EXIT ( message * : result-value ? )

Blurts out the message to stdout and then exits with a failure status if no result-value is given, otherwise it exits with the given result-value.
message 輸出到 stdout,然後如果沒有給出 result-value 則以一個失敗狀態退出,否則以給定的 result-value 退出。

"Echo", "echo", "Exit", and "exit" are accepted as aliases for ECHO and EXIT, since it is hard to tell that these are built-in rules and not part of the language, like "include".
"Echo", "echo", "Exit", 和 "exit" 均可作為 ECHOEXIT 的別名,因為很難說它們是內建規則而不是語言的一部分,像 "include"。

The GLOB rule does filename globbing.
GLOB 規則將文件名組合起來。

rule GLOB ( directories * : patterns * : downcase-opt ? )

Using the same wildcards as for the patterns in the switch statement. It is invoked by being used as an argument to a rule invocation inside of "[ ]". For example: "FILES = [ GLOB dir1 dir2 : *.c *.h ]" sets FILES to the list of C source and header files in dir1 and dir2. The resulting filenames are the full pathnames, including the directory, but the pattern is applied only to the file name without the directory. 
使用和在 switch 語句中的模式相同的通配符。它被用作一個在 "[ ]" 中的規則調用的參數。例如:"FILES = [ GLOB dir1 dir2 : *.c *.h ]" 將 FILES 設置為在 dir1dir2 中的C源文件和頭文件的列表。得到的文件名是全路徑名,包括所在的目錄,但所應用的模式只使用沒有目錄的文件名。

If downcase-opt is supplied, filenames are converted to all-lowercase before matching against the pattern; you can use this to do case-insensitive matching using lowercase patterns. The paths returned will still have mixed case if the OS supplies them. On Windows NT and Cygwin, filenames are always downcased before matching.
如果給出了 downcase-opt,則文件名在與模式匹配之前要轉換為小寫;你可以使用它來與小寫的模式進行大小寫不敏感的匹配。如果OS是支持大小寫敏感的,則返回的路徑名仍會具有大小寫。在 Windows NT 和 Cygwin 中,文件名在匹配前總是轉為小寫

The MATCH rule does pattern matching.
MATCH 規則進行模式匹配。

rule MATCH ( regexps + : list * )

Matches the egrep(1) style regular expressions regexps against the strings in list. The result is the concatenation of matching () subexpressions for each string in list, and for each regular expression in regexps. Only useful within the "[ ]" construct, to change the result into a list.
按 egrep(1) 風格的正規表達式 regexps 匹配 list 中的字符串。結果是這樣得到的,對 list 中的各個字符串按 regexps  中各個正規表達式進行匹配,與各個 () 子表達式相匹配的字符串串聯起來即為結果。它只在 "[ ]" 結構內部使用,用於將結果變為列表。

rule BACKTRACE ( )

Returns a list of quadruples: filename line module rulename..., describing each shallower level of the call stack. This rule can be used to generate useful diagnostic messages from Jam rules.
返回一個由四部分組成的列表:filename line module rulename...,表示調用棧的各層。該規則可用於從 Jam 規則生成有用的調試信息。

rule UPDATE ( targets * )

Classic jam treats any non-option element of command line as a name of target to be updated. This prevented more sophisticated handling of command line. This is now enabled again but with additional changes to the UPDATE rule to allow for the flexibility of changing the list of targets to update. The UPDATE rule has two effects:
經典的 jam 將命令行中任何非可選元素視為要更新的目標名。這防止了對命令行進行更為複雜的處理。現在也可以這樣做,不過已變為用 UPDATE 規則來允許對更新目標列表的靈活修改。UPDATE 規則有兩個作用:

  1. It clears the list of targets to update, and
    它清除更新目標列表,並
  2. Causes the specified targets to be updated.
    將特定目標列為更新。

If no target was specified with the UPDATE rule, no targets will be updated. To support changing of the update list in more usefull ways, the rule also returns the targets previously in the update list. This makes it possible to add targets as such:
如果在 UPDATE 規則中沒有指定目標,則沒有目標會被更新。為了以更有用的方式支持更新列表的修改,該規則還會返回之前在更新列表中的目標。這樣就可以像下面這樣來增加目標:

local previous-updates = [ UPDATE ] ;
UPDATE $(previous-updates) a-new-target ;
rule W32_GETREG ( path : data ? )

Defined only for win32 platform. It reads the registry of Windows. 'path' is the location of the information, and 'data' is the name of the value which we want to get. If 'data' is omitted, the default value of 'path' will be returned. The 'path' value must conform to MS key path format and must be prefixed with one of the predefined root keys. As usual,
僅對 win32 平台定義。它讀入 Windows 的註冊表。'path' 為所讀信息的位置,'data' 為所讀值的名字。如果沒有給出 'data',則返回 'path' 的缺省值。'path' 的值必須符合 MS 鍵值路徑格式,必須以某個預定義根鍵為前綴。通常,

  • 'HKLM' is equivalent to 'HKEY_LOCAL_MACHINE'.
    'HKLM' 等價於 'HKEY_LOCAL_MACHINE'.
  • 'HKCU' is equivalent to 'HKEY_CURRENT_USER'.
    'HKCU' 等價於 'HKEY_CURRENT_USER'.
  • 'HKCR' is equivalent to 'HKEY_CLASSES_ROOT'.
    'HKCR' 等價於 'HKEY_CLASSES_ROOT'.

Other predefined root keys are not supported.
不支持其它的預定義根鍵。

Currently supported data types : 'REG_DWORD', 'REG_SZ', 'REG_EXPAND_SZ', 'REG_MULTI_SZ'. The data with 'REG_DWORD' type will be turned into a string, 'REG_MULTI_SZ' into a list of strings, and for those with 'REG_EXPAND_SZ' type environment variables in it will be replaced with their defined values. The data with 'REG_SZ' type and other unsupported types will be put into a string without modification. If it can't receive the value of the data, it just return an empty list. For example,
當前支持的數據類型:'REG_DWORD', 'REG_SZ', 'REG_EXPAND_SZ', 'REG_MULTI_SZ'。'REG_DWORD' 類型的數據將被轉換為字符串,'REG_MULTI_SZ' 則轉換為字符串列表,'REG_EXPAND_SZ' 類型中的環境變量將被替換為它們的定義值。'REG_SZ' 類型和其它未支持類型的數據將被照原樣置於一個字符串中。如果不能接受數據的類型,則只返回一個空的列表。例如:

local PSDK-location =
[ W32_GETREG HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\MicrosoftSDK\\Directories : "Install Dir" ] ;
rule W32_GETREGNAMES ( path : result-type )

Defined only for win32 platform. It reads the registry of Windows. 'path' is the location of the information, and 'result-type' is either 'subkeys' or 'values'. For more information on 'path' format and constraints, please see W32_GETREG.
只對 win32 平台定義。它讀入 Windows 的註冊表。'path' 為所讀信息的位置,'result-type' 為 'subkeys' 或 'values'。有關 'path' 格式和約束的信息,請參見 W32_GETREG.

Depending on 'result-type', the rule returns one of the following:
取決於 'result-type',該規則返回以下之一:

subkeys

Names of all direct subkeys of 'path'.
'path' 所有直接子鍵的名字。

values

Names of values contained in registry key given by 'path'. The "default" value of the key appears in the returned list only if its value has been set in the registry.
由 'path' 給出的註冊表鍵中所包含值的名字。僅當某個鍵的值已經在註冊表中設置,該鍵的 "default" 缺省值才會出現在返回列表中。

If 'result-type' is not recognized, or requested data cannot be retrieved, the rule returns an empty list. Example:
如果 'result-type' 未經驗證,或者所請求的數據不可取得,則該規則返回一個空列表。例如:

local key = "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths" ;
local subkeys = [ W32_GETREGNAMES "$(key)" : subkeys ] ;
for local subkey in $(subkeys)
{
local values = [ W32_GETREGNAMES "$(key)\\$(subkey)" : values ] ;
for local value in $(values)
{
local data = [ W32_GETREG "$(key)\\$(subkey)" : "$(value)" ] ;
ECHO "Registry path: " $(key)\\$(subkey) ":" $(value) "=" $(data) ;
}
}
rule SHELL ( command : * )

SHELL executes command, and then returns the standard output of command. SHELL only works on platforms with a popen() function in the C library. On platforms without a working popen() function, SHELL is implemented as a no-op. SHELL works on Unix, MacOS X, and most Windows compilers. SHELL is a no-op on Metrowerks compilers under Windows. There is a variable set of allowed options as additional arguments:
SHELL 執行 command,然後返回 command 的標準輸出。SHELL 僅工作於在C庫中帶有 popen() 函數的平台上。在不帶有可用的 popen() 函數的平台上,SHELL 被實現為空操作。SHELL 可在 Unix, MacOS X, 和多數 Windows 編譯器上工作。SHELL 在 Windows 的 Metrowerks 編譯器上是空操作。有一個可選項的變量集作為參數:

exit-status

In addition to the output the result status of the executed command is returned as a second element of the result.
增加被執行命令的返回狀態作為結果的第二個元素返回。

no-output

Don't capture the output of the command. Instead an empty ("") string value is returned in place of the output.
不捕獲命令的輸出。以一個空字符串("")作為輸出的替換返回。

Because the Perforce/Jambase defines a SHELL rule which hides the builtin rule, COMMAND can be used as an alias for SHELL in such a case.
因為 Perforce/Jambase 定義了一個 SHELL 規則用於隱藏內建規則,所以在這種情況下可以用 COMMAND 作為 SHELL 的別名。

BJam has several simple flow-of-control statements:
BJam 有幾種簡單的控制流語句:

for var in list { statements }

Executes statements for each element in list, setting the variable var to the element value.
list 中的每個元素執行 statements,將變量 var 設置為各元素的值。

if cond { statements }
[ else { statements } ]

Does the obvious; the else clause is optional. cond is built of:
這很明顯;else 子句是可選的。cond 可由以下組成:

a

true if any a element is a non-zero-length string
如果任一 a 元素為非零長度的字符串,則為真

a = b

list a matches list b string-for-string
列表 a 的字符串與列表 b 的字符串相匹配

a != b

list a does not match list b
列表 a 不匹配列表 b

a < b

a[i] string is less than b[i] string, where i is first mismatched element in lists a and b
a[i] 字符串小於 b[i] 字符串,其中 i 為列表 ab 中的第一個不匹配元素

a <= b

every a string is less than or equal to its b counterpart
每個 a 字符串小於或等於 b 中的對應串

a > b

a[i] string is greater than b[i] string, where i is first mismatched element
a[i] 字符串大於 b[i] 字符串,其中 i 為第一個不匹配元素

a >= b

every a string is greater than or equal to its b counterpart
每個 a 字符串大於或等於 b 中的對應串

a in b

true if all elements of a can be found in b, or if a has no elements
如果 a 的所有元素都在 b 中或 a 沒有元素,則為真

! cond

condition not true
條件非真

cond && cond

conjunction
合取

cond || cond

disjunction
析取

( cond )

precedence grouping
優先級組

include file ;

Causes bjam to read the named file. The file is bound like a regular target (see Binding above) but unlike a regular target the include file cannot be built.
bjam 讀入 filefile 像一個普通目標那樣被綁定(見前文中的"綁定"),但不同的是,所包含的 file 不可構建。

The include file is inserted into the input stream during the parsing phase. The primary input file and all the included file(s) are treated as a single file; that is, jam infers no scope boundaries from included files.
包含的 file 在分析階段被插入到輸入流中。主輸入文件和所有包含文件被視為單個文件;即 jam 認為包含文件沒有作用域邊界。

local vars [ = values ] ;

Creates new vars inside to the enclosing {} block, obscuring any previous values they might have. The previous values for vars are restored when the current block ends. Any rule called or file included will see the local and not the previous value (this is sometimes called Dynamic Scoping). The local statement may appear anywhere, even outside of a block (in which case the previous value is restored when the input ends). The vars are initialized to values if present, or left uninitialized otherwise.
在所屬的 {} 塊中創建新變量 vars,掩蓋可能已具有的原值。vars 原有的值在當前塊結束的時候被恢復。任何規則調用或文件包含都將看到本地值而不是原有的值(有時這被稱為動態作用域)。local 語句可以出現在任何地方,甚至在塊的外面(這種情況下,原有的值在輸入結束時恢復)。如果提供了 values,則 vars 被初始化為 values,否則保持為未初始化。

return values ;

Within a rule body, the return statement sets the return value for an invocation of the rule. It does not cause the rule to return; a rule's value is actually the value of the last statement executed, so a return should be the last statement executed before the rule "naturally" returns.
在一個規則體的內部,return 語句為該規則的調用設置返回值。它並不引起該規則返回;規則的值其實是最後一條執行的語句的值,所以 return 應該是規則"自然地"返回之前的最後一條被執行的語句。

switch value
{
    case pattern1 : statements ;
case pattern2 : statements ;
...
}

The switch statement executes zero or one of the enclosed statements, depending on which, if any, is the first case whose pattern matches value. The pattern values are not variable-expanded. The pattern values may include the following wildcards:
switch 語句執行零個或一個內含的 statements,這取決於哪一個 pattern 首先匹配 valuepattern 的值不是可以按變量展開的。pattern 的值可以包含以下通配符:

?

match any single character
匹配任意單個字符

*

match zero or more characters
匹配零個或多個字符

[chars]

match any single character in chars
匹配 chars 中的任一字符

[^chars]

match any single character not in chars
匹配不在 chars 中的任一字符

\x

match x (escapes the other wildcards)
匹配 x (對其它通配符轉義)

while cond { statements }

Repeatedly execute statements while cond remains true upon entry. (See the description of cond expression syntax under if, above).
重複執行 statements,如果在入口處 cond 保持為真。(參見前文 if 一節中的對 cond 表達式的說明)。

BJam variables are lists of zero or more elements, with each element being a string value. An undefined variable is indistinguishable from a variable with an empty list, however, a defined variable may have one more elements which are null strings. All variables are referenced as $(variable).
BJam 變量是零個或多個元素的列表,每個元素是一個字符串值。一個未定義的變量與一個為空列表的變量是不可區別的,而一個有定義的變量可以有一個以上的元素為空字符串。所有變量用 $(variable) 引用。

Variables are either global or target-specific. In the latter case, the variable takes on the given value only during the updating of the specific target.
變量可以是全局的或特定目標的。在後一種情況下,變量僅在特定目標的更新期間具有給定的值。

A variable is defined with:
一個變量可以用以下方式定義:

variable = elements ;
variable += elements ;
variable on targets = elements ;
variable on targets += elements ;
variable default = elements ;
variable ?= elements ;

The first two forms set variable globally. The third and forth forms set a target-specific variable. The = operator replaces any previous elements of variable with elements; the += operation adds elements to variable's list of elements. The final two forms are synonymous: they set variable globally, but only if it was previously unset.
頭兩種形式將 variable 設為全局。第三和第四種形式則設置一個特定目標變量。= 操作符以 elements 替換 variable 原有的元素;+= 操作符則將 elements 增加到 variable 的元素列表中。後兩種形式是同義的:它們將 variable 設為全局,但僅當變量原來是未設置的情況下。

Variables referenced in updating commands will be replaced with their values; target-specific values take precedence over global values. Variables passed as arguments ($(1) and $(2)) to actions are replaced with their bound values; the "bind" modifier can be used on actions to cause other variables to be replaced with bound values. See Action Modifiers above.
在更新命令中所引用的變量將被替換為它們的值;特定目標變量優先於全局變量。以參數方式傳遞到動作中的變量($(1)$(2))被替換為它們的綁定值;"bind" 修改符可以在動作上用來讓其它變量被綁定值替換。請參見前文的"動作修改符"。

BJam variables are not re-exported to the environment of the shell that executes the updating actions, but the updating actions can reference bjam variables with $(variable).
BJam 變量不會被輸出到執行更新動作的 shell 的環境中,但是更新動作可以用 $(variable) 來引用 bjam 變量。

During parsing, bjam performs variable expansion on each token that is not a keyword or rule name. Such tokens with embedded variable references are replaced with zero or more tokens. Variable references are of the form $(v) or $(vm), where v is the variable name, and m are optional modifiers.
在分析階段,bjam 對每一個不是關鍵字和規則名的記號執行變量展開。這些嵌有變量引用的記號會被替換為零個或多個記號。變量引用的方式為 $(v)$(vm),其中 v 為變量名,m 為可選的修改符。

Variable expansion in a rule's actions is similar to variable expansion in statements, except that the action string is tokenized at whitespace regardless of quoting.
在規則動作中的變量展開類似於語句中的變量展開,除了動作字符串是以空格來分隔記號,它不管引號。

The result of a token after variable expansion is the product of the components of the token, where each component is a literal substring or a list substituting a variable reference. For example:
變量展開後所得的記號是記號的組成元素的 積product,即每個組成元素作為子串,或者用一個列表替換變量引用。例如:

$(X) -> a b c
t$(X) -> ta tb tc
$(X)z -> az bz cz
$(X)-$(X) -> a-a a-b a-c b-a b-b b-c c-a c-b c-c

The variable name and modifiers can themselves contain a variable reference, and this partakes of the product as well:
變量名和修改符本身也可以包含變量引用,而且要處理所有乘積:

$(X) -> a b c
$(Y) -> 1 2
$(Z) -> X Y
$($(Z)) -> a b c 1 2

Because of this product expansion, if any variable reference in a token is undefined, the result of the expansion is an empty list. If any variable element is a null string, the result propagates the non-null elements:
因為乘積也要展開,所以如果記號中有變量引用未定義,則展開的結果為空列表。如果有變量元素為空字符串,則結果只含非空元素:

$(X) -> a ""
$(Y) -> "" 1
$(Z) ->
-$(X)$(Y)- -> -a- -a1- -- -1-
-$(X)$(Z)- ->

A variable element's string value can be parsed into grist and filename-related components. Modifiers to a variable are used to select elements, select components, and replace components. The modifiers are:
變量元素的字符串值可以被分為 grist 和文件名相關組件。變量的修改符用於選擇元素,選擇組件和替換組件。修改符有:

[n]

Select element number n (starting at 1). If the variable contains fewer than n elements, the result is a zero-element list. n can be negative in which case the element number n from the last leftward is returned.
選擇第 n 個元素(從1開始)。如果變量中的元素少於 n 個,結果為一個不含元素的列表。n 可以為負,這時返回倒數第 n 個元素。

[n-m]

Select elements number n through m. n and m can be negative in which case they refer to elements counting from the last leftward.
選擇第 nm 個元素。nm 可以是負的,這時它們表示倒數的元素數量。

[n-]

Select elements number n through the last. n can be negative in which case it refers to the element counting from the last leftward.
選擇第 n 個到最後的元素。n 可以是負的,這時它表示倒數的元素數量。

:B

Select filename base.
選擇文件名的基名。

:S

Select (last) filename suffix.
選擇(最後的)文件名後綴。

:M

Select archive member name.
選擇存檔成員名。

:D

Select directory path.
選擇目錄路徑名。

:P

Select parent directory.
選擇父目錄名。

:G

Select grist.
選擇 grist。

:U

Replace lowercase characters with uppercase.
將小寫字符替換為大寫。

:L

Replace uppercase characters with lowercase.
將大寫字符替換為小寫。

:W

When invoking Windows-based tools from Cygwin it can be important to pass them true windows-style paths. The :W modifier, under Cygwin only, turns a cygwin path into a Win32 path using the cygwin_conv_to_win32_path function. On other platforms, the string is unchanged. For example
Cygwin 調用基於 Windows 的工具時,將真實的 windows 風格的路徑傳遞給它們可能是很重要的。:W 修改符僅用於 Cygwin,它使用 cygwin_conv_to_win32_path 函數將一個 cygwin 路徑轉換為 Win32 路徑。在其它平台上,字符串保持不變。例如:

x = "/cygdrive/c/Program Files/Borland" ; ECHO #(x:W) ;

prints "C:\Program Files\Borland" on Cygwin
在 Cygwin 上打印 "C:\Program Files\Borland"

:chars

Select the components listed in chars.
選擇列在 chars 中的組件。

:G=grist

Replace grist with grist.
grist 替換 grist。

:D=path

Replace directory with path.
path 替換目錄名。

:B=base

Replace the base part of file name with base.
base 替換文件名的基名部分。

:S=suf

Replace the suffix of file name with suf.
suf 替換文件名的後綴部分。

:M=mem

Replace the archive member name with mem.
mem 替換存檔成員名。

:R=root

Prepend root to the whole file name, if not already rooted.
root 添加到完整的文件名中,如果它未被根目錄化。

:E=value

Assign value to the variable if it is unset.
將 value 賦給變量,如果變量未設置。

:J=joinval

Concatentate list elements into single element, separated by joinval'.
將列表中各元素串接為一個元素,以 joinval 分隔。

On VMS, $(var:P) is the parent directory of $(var:D).
在 VMS 上,$(var:P)$(var:D) 的父目錄。

Boost Jam allows you to declare a local for loop control variable right in the loop:
Boost Jam 允許你聲明一個局部變量為循環控制變量,僅用於循環中:

x = 1 2 3 ;
y = 4 5 6 ;
for local y in $(x)
{
ECHO $(y) ; # prints "1", "2", or "3"
}
ECHO $(y) ; # prints "4 5 6"

During expansion of expressions bjam also looks for subexpressions of the form =@(filename:Efilecontents) and replaces the expression with filename after creating the given file with the contents set to filecontents. This is useful for creating compiler response files, and other "internal" files. The expansion works both during parsing and action execution. Hence it is possible to create files during any of the three build phases.
在表達式的展開期間,bjam 還會查找形如 =@(filename:Efilecontents) 的子表達式,並在以 filecontents 為內容創建給定文件後,將該表達式替換為 filename。這對於創建編譯器響應文件和其它"內部'文件非常有用。該展開在分析階段和動作階段均會進行。因此可以在三個構建階段中的任何階段創建文件。

This section discusses variables that have special meaning to bjam.
本節討論一些對於 bjam 具有特殊意義的變量。

These two variables control the binding of file target names to locations in the file system. Generally, $(SEARCH) is used to find existing sources while $(LOCATE) is used to fix the location for built targets.
這兩個變量控制如何將文件目標名綁定到文件系統中的位置。通常,$(SEARCH) 被用於查找已有的源文件,而 $(LOCATE) 被用於為內建目標修正位置。

Rooted (absolute path) file targets are bound as is. Unrooted file target names are also normally bound as is, and thus relative to the current directory, but the settings of $(LOCATE) and $(SEARCH) alter this:
根化的(絕對路徑的)文件目標也同樣綁定。非根化的文件目標名通常也同樣進行綁定,且相對於當前的目錄,不過 $(LOCATE)$(SEARCH) 的設置改變了這一點:

  • If $(LOCATE) is set then the target is bound relative to the first directory in $(LOCATE). Only the first element is used for binding.
    如果 $(LOCATE) 被設置,則目標被相對於 $(LOCATE) 中的第一個目錄進行綁定。只有第一個元素被用於綁定。
  • If $(SEARCH) is set then the target is bound to the first directory in $(SEARCH) where the target file already exists.
    如果 $(SEARCH) 被設置,則目標被綁定為 $(SEARCH) 中的第一個找到目標文件的目錄。
  • If the $(SEARCH) search fails, the target is bound relative to the current directory anyhow.
    如果在 $(SEARCH) 中查找失敗,則目標被相對於當前目錄進行綁定。

Both $(SEARCH) and $(LOCATE) should be set target-specific and not globally. If they were set globally, bjam would use the same paths for all file binding, which is not likely to produce sane results. When writing your own rules, especially ones not built upon those in Jambase, you may need to set $(SEARCH) or $(LOCATE) directly. Almost all of the rules defined in Jambase set $(SEARCH) and $(LOCATE) to sensible values for sources they are looking for and targets they create, respectively.
$(SEARCH)$(LOCATE) 都應被設置為特定目標變量而不是全局的。如果它們被設置為全局的,bjam 就會對所有文件綁定使用相同的路徑,這不太可能得到正確的結果。在編寫你自己的規則時,尤其是那些不是構建在 Jambase 規則之上的規則,你可能需要直接設置 $(SEARCH)$(LOCATE)。幾乎所有在 Jambase 中定義的規則都將 $(SEARCH)$(LOCATE) 分別設置為對它們所查找的源和它們所創建的目標可感知的值。

These two variables control header file scanning. $(HDRSCAN) is an egrep(1) pattern, with ()'s surrounding the file name, used to find file inclusion statements in source files. Jambase uses $(HDRPATTERN) as the pattern for $(HDRSCAN). $(HDRRULE) is the name of a rule to invoke with the results of the scan: the scanned file is the target, the found files are the sources. This is the only place where bjam invokes a rule through a variable setting.
這兩個變量控制頭文件的掃瞄。$(HDRSCAN) 是一個 egrep(1) 模版,用 () 包圍著文件名,用於在源文件中查找文件包含語句。Jambase 使用 $(HDRPATTERN) 作為 $(HDRSCAN) 的模版。$(HDRRULE) 是一個規則名,該規則會以掃瞄的結果來調用:被掃瞄的文件為目標,查找到的文件為源。這是 bjam 通過變量設置來調用規則的唯一地方。

Both $(HDRSCAN) and $(HDRRULE) must be set for header file scanning to take place, and they should be set target-specific and not globally. If they were set globally, all files, including executables and libraries, would be scanned for header file include statements.
為了進行頭文件掃瞄,$(HDRSCAN)$(HDRRULE) 都必須被設置,而且它們要被設置為特定目標的而不是全局的。如果它們被設置為全局的,那麼所有文件,包括可執行文件和庫文件,都會由於頭文件包含語句而被掃瞄。

The scanning for header file inclusions is not exact, but it is at least dynamic, so there is no need to run something like makedepend(GNU) to create a static dependency file. The scanning mechanism errs on the side of inclusion (i.e., it is more likely to return filenames that are not actually used by the compiler than to miss include files) because it can't tell if #include lines are inside #ifdefs or other conditional logic. In Jambase, HdrRule applies the NOCARE rule to each header file found during scanning so that if the file isn't present yet doesn't cause the compilation to fail, bjam won't care.
對頭文件包含的掃瞄並不是精確的,但是它至少是動態的,所以沒有必要運行一些像 makedepend(GNU) 這樣的東西去創建一個靜態依賴文件。該掃瞄機制可能會包含錯誤的文件(即,它更可能返回編譯器實際上並沒有使用的文件名,而不是漏掉某個文件),因為如果 #include 行是在 #ifdefs 或其它條件邏輯之中的,它並未被告知。在 Jambase 中,HdrRule 對在掃瞄期間找到的每個頭文件應用 NOCARE 規則,這樣如果該文件不存在也不會導致編譯失敗的話,bjam 就不會關注它。

Also, scanning for regular expressions only works where the included file name is literally in the source file. It can't handle languages that allow including files using variable names (as the Jam language itself does).
還有,對正規表達式的掃瞄只有當被包含的文件名在源文件中以字面方式存在時才可工作。它不能處理那些允許使用變量名來包含文件的語言(如 Jam 語言本身)。

It is sometimes desirable to disallow parallel execution of some actions. For example:
有時我們想要禁止某些動作的並發執行。例如:

  • Old versions of yacc use files with fixed names. So, running two yacc actions is dangerous.
    舊版本的 yacc 使用固定名字的文件。所以,同時運行兩個 yacc 動作是危險的。
  • One might want to perform parallel compiling, but not do parallel linking, because linking is i/o bound and only gets slower.
    你可能想執行並行編譯,但不可以並行鏈接,因為鏈接是 i/o 限制的,只會更慢。

Craig McPeeters has extended Perforce Jam to solve such problems, and that extension was integrated in Boost.Jam.
Craig McPeeters 已經對 Perforce Jam 進行了擴展以解決此類問題,而且該擴展已經集成到 Boost.Jam 中。

Any target can be assigned a semaphore, by setting a variable called SEMAPHORE on that target. The value of the variable is the semaphore name. It must be different from names of any declared target, but is arbitrary otherwise.
任何目標都可以被賦予一個 信號燈semaphore,方法是對該目標設置一個名為 SEMAPHORE 的變量。該變量的值為信號燈名。它必須不同於其它已聲明的目標,但可以是其它任意值。

The semantic of semaphores is that in a group of targets which have the same semaphore, only one can be updated at the moment, regardless of "-j" option.
信號燈的語義是,在一組具有相同信號燈的目標中,在同一時刻只有一個可以被更新,無論有否 "-j" 選項。

A number of Jam built-in variables can be used to identify runtime platform:
有一組 Jam 內建變量可用於標識運行期平台:

OS

OS identifier string
OS 標識符字符串

OSPLAT

Underlying architecture, when applicable
底層體系,在可用時

MAC

true on MAC platform
在 MAC 平台上為真

NT

true on NT platform
在 NT 平台上為真

OS2

true on OS2 platform
在 OS2 平台上為真

UNIX

true on Unix platforms
在 Unix 平台上為真

VMS

true on VMS platform
在 VMS 平台上為真

JAMDATE

Time and date at bjam start-up as an ISO-8601 UTC value.
bjam 啟動時的時間和日期,以 ISO-8601 UTC 值表示。

JAMUNAME

Ouput of uname(1) command (Unix only)
uname(1) 命令的輸出(僅用於 Unix)

JAMVERSION

bjam version, currently "3.1.16"
bjam 版本,當前為 "3.1.16"

JAM_VERSION

A predefined global variable with two elements indicates the version number of Boost Jam. Boost Jam versions start at "03" "00". Earlier versions of Jam do not automatically define JAM_VERSION.
一個帶兩個元素的預定義全局變量,表示 Boost Jam 版本數。Boost Jam 版本從 "03" "00" 開始。更早期的 Jam 版本沒有自動定義 JAM_VERSION.

When bjam executes a rule's action block, it forks and execs a shell, passing the action block as an argument to the shell. The invocation of the shell can be controlled by $(JAMSHELL). The default on Unix is, for example:
bjam 執行一個規則動作塊時,它分叉並執行一個 shell,將動作塊作為參數傳遞給 shell。shell 的調用可以通過 $(JAMSHELL) 來控制。例如,在 Unix 上的缺省值為:

JAMSHELL = /bin/sh -c % ;

The % is replaced with the text of the action block.
% 將被動作塊的文本替換。

BJam does not directly support building in parallel across multiple hosts, since that is heavily dependent on the local environment. To build in parallel across multiple hosts, you need to write your own shell that provides access to the multiple hosts. You then reset $(JAMSHELL) to reference it.
BJam 不直接支持在多個主機上並行構建,因為這非常依賴於本地環境。要在多個主機上並行構建,你需要編寫自己的 shell 來提供對多個主機的訪問。然後將 $(JAMSHELL) 重設為引向它。

Just as bjam expands a % to be the text of the rule's action block, it expands a ! to be the multi-process slot number. The slot number varies between 1 and the number of concurrent jobs permitted by the -j flag given on the command line. Armed with this, it is possible to write a multiple host shell. For example:
正如 bjam 會將 % 展開為規則動作塊的文本,它也會將 ! 展開為多進程插槽數。該插槽數在 1 到命令行中給定的 -j 選項所允許的並發數之間變化。有了這個,就可以編寫一個多主機的 shell。例如:

#!/bin/sh

# This sample JAMSHELL uses the SunOS on(1) command to execute a
# command string with an identical environment on another host.

# Set JAMSHELL = jamshell ! %
#
# where jamshell is the name of this shell file.
#
# This version handles up to -j6; after that they get executed
# locally.

case $1 in
1|4) on winken sh -c "$2";;
2|5) on blinken sh -c "$2";;
3|6) on nod sh -c "$2";;
*) eval "$2";;
esac

The __TIMING_RULE__ and __ACTION_RULE__ can be set to the name of a rule for bjam to call after an action completes for a target. They both give diagnostic information about the action that completed. For __TIMING_RULE__ the rule is called as:
__TIMING_RULE____ACTION_RULE__ 可被設置為一個規則名,bjam 將在一個目標的動作完成後調用該規則。它們兩個都給出了關於已完成規則的診斷信息。對於 __TIMING_RULE__,規則這樣調用:

rule timing-rule ( args * : target : start end user system )

And __ACTION_RULE__ is called as:
而對於 __ACTION_RULE__ 則如下調用:

rule action-rule ( args * : target : command status start end user system : output ? )

The arguments for both are:
兩者的參數是:

args

Any values following the rule name in the __TIMING_RULE__ or __ACTION_RULE__ are passed along here.
__TIMING_RULE____ACTION_RULE__ 中跟在規則名後的任意值被傳遞到這裡。

target

The bjam target that was built.
被構建的 bjam 目標。

command

The text of the executed command in the action body.
在動作體中被執行命令的文本。

status

The integer result of the executed command.
被執行命令的整數結果。

start

The starting timestamp of the executed command as a ISO-8601 UTC value.
被執行命令的開始時間戳,以 ISO-8601 TUC 值表示。

end

The completion timestamp of the executed command as a ISO-8601 UTC value.
被執行命令的完成時間戳,以 ISO-8601 TUC 值表示。

user

The number of user CPU seconds the executed command spent as a floating point value.
被執行命令的用戶 CPU 秒數,表示為浮點值。

system

The number of system CPU seconds the executed command spent as a floating point value.
被執行命令的系統 CPU 秒數,表示為浮點值。

output

The output of the command as a single string. The content of the output reflects the use of the -pX option.
以單個字符串表示的命令的輸出。輸出的內容反映了 -pX 選項的使用。

[Note] Note 說明

If both variables are set for a target both are called, first __TIMING_RULE__ then __ACTION_RULE__.

如果對一個目標設置了兩個變量,則兩個均被調用,首先是 __TIMING_RULE__ 然後 __ACTION_RULE__.

Boost Jam introduces support for modules, which provide some rudimentary namespace protection for rules and variables. A new keyword, "module" was also introduced. The features described in this section are primitives, meaning that they are meant to provide the operations needed to write Jam rules which provide a more elegant module interface.
Boost Jam 引入了對模塊的支持,它為規則和變量提供了一些根本的名字空間保護。引入了一個新的關鍵字 "module"。本節中所描述的特性是最基本的,即它們的目的是提供編寫更優雅的模塊接口的 Jam 規則所需的操作。

module expression { ... }

Code within the { ... } executes within the module named by evaluating expression. Rule definitions can be found in the module's own namespace, and in the namespace of the global module as module-name.rule-name, so within a module, other rules in that module may always be invoked without qualification:
{ ... } 中的代碼在對表達式求值後得到名字的模塊的內部執行。規則的定義可以在模塊自己的名字空間和全局模塊的名字空間中找到,形如 module-name.rule-name,在一個模塊內部,該模塊的其它規則可以無需限定符來調用:

module my_module
{
    rule salute ( x ) { ECHO $(x), world ; }
    rule greet ( ) { salute hello ; }
    greet ;
}
my_module.salute goodbye ;

When an invoked rule is not found in the current module's namespace, it is looked up in the namespace of the global module, so qualified calls work across modules:
當一個被調用的規則不能在當前模塊的名字空間中找到時,就會在全局模塊的名字空間中查找,所以限定調用可以跨模塊使用:

module your_module
{
rule bedtime ( ) { my_module.salute goodnight ; }
}

Each module has its own set of dynamically nested variable scopes. When execution passes from module A to module B, all the variable bindings from A become unavailable, and are replaced by the bindings that belong to B. This applies equally to local and global variables:
每個模塊都有它自己的動態嵌套變量作用域。當執行從模塊A傳遞到模塊B時,所有從A綁定的變量都變成不可用的,並被屬於B的綁定所替換。這一點對於局部變量和全局變量同樣適用:

module A
{
x = 1 ;
rule f ( )
{
local y = 999 ; # becomes visible again when B.f calls A.g
B.f ;
}
rule g ( )
{
ECHO $(y) ; # prints "999"
}
}
module B
{
y = 2 ;
rule f ( )
{
ECHO $(y) ; # always prints "2"
A.g ;
}
}

The only way to access another module's variables is by entering that module:
訪問其它模塊的變量的唯一方法是,進入該模塊:

rule peek ( module-name ? : variables + )
{
module $(module-name)
{
return $($(>)) ;
}
}

Note that because existing variable bindings change whenever a new module scope is entered, argument bindings become unavailable. That explains the use of "$(>)" in the peek rule above.
注意,由於在進入一個新的模塊作用域時,退出變量的綁定會改變,所以參數綁定變為不可用。這解釋了為何在上面的 peek 規則中使用 "$(>)"。

local rule rulename...

The rule is declared locally to the current module. It is not entered in the global module with qualification, and its name will not appear in the result of:
該規則被聲明為局部在當前模塊中。它不能在全局模塊中以限定方式進入,而且它的名字不會出現在以下的結果中:

[ RULENAMES module-name ]
rule RULENAMES ( module ? )

Returns a list of the names of all non-local rules in the given module. If module is omitted, the names of all non-local rules in the global module are returned.
返回給定模塊中所有非本地規則名字的列表。如果 module 未給出,則返回全局模塊中所有非本地規則的名字。

rule VARNAMES ( module ? )

Returns a list of the names of all variable bindings in the given module. If module is omitted, the names of all variable bindings in the global module are returned.
返回給定模塊中所有變量綁定的名字的列表。如果 module 未給出,則返回全局模塊中所有變量綁定的名字。

[Note] Note 說明

This includes any local variables in rules from the call stack which have not returned at the time of the VARNAMES invocation.

它包含了規則中在調用 VARNAMES 時尚未從調用棧返回的所有局部變量。

IMPORT allows rule name aliasing across modules:
IMPORT 允許規則名跨模塊使用別名:

rule IMPORT ( source_module ? : source_rules *
: target_module ? : target_rules * )

The IMPORT rule copies rules from the source_module into the target_module as local rules. If either source_module or target_module is not supplied, it refers to the global module. source_rules specifies which rules from the source_module to import; target_rules specifies the names to give those rules in target_module. If source_rules contains a name which doesn't correspond to a rule in source_module, or if it contains a different number of items than target_rules, an error is issued. For example,
IMPORT 規則將規則從 source_module 複製到 target_module 並作為本地規則。如果 source_moduletarget_module 未給出,則代表全局模塊。source_rules 指定了從 source_module 引入哪一個規則;target_rules 指定了在 target_module 中的規則名。如果 source_rules 包含的某個名字不能對應到 source_module 中的規則,或者它包含的元素數量與 target_rules 不等,則引發一個錯誤。例如:

# import m1.rule1 into m2 as local rule m1-rule1.
IMPORT m1 : rule1 : m2 : m1-rule1 ;
# import all non-local rules from m1 into m2
IMPORT m1 : [ RULENAMES m1 ] : m2 : [ RULENAMES m1 ] ;

EXPORT allows rule name aliasing across modules:
EXPORT 允許規則名跨模塊使用別名:

rule EXPORT ( module ? : rules * )

The EXPORT rule marks rules from the source_module as non-local (and thus exportable). If an element of rules does not name a rule in module, an error is issued. For example, 
EXPORT 規則將 source_module 中的 rules 標記為非本地規則(即可導出的)。如果 rules 中的某個元素不是 module 中的規則名,則引發一個錯誤。例如:

module X {
local rule r { ECHO X.r ; }
}
IMPORT X : r : : r ; # error - r is local in X
EXPORT X : r ;
IMPORT X : r : : r ; # OK.
rule CALLER_MODULE ( levels ? )

CALLER_MODULE returns the name of the module scope enclosing the call to its caller (if levels is supplied, it is interpreted as an integer number of additional levels of call stack to traverse to locate the module). If the scope belongs to the global module, or if no such module exists, returns the empty list. For example, the following prints "{Y} {X}":
CALLER_MODULE 返回包含了調用其調用者的模塊作用域的名字(如果給出了 levels,則解釋為在調用棧中定位該模塊所增加的層數)。如果該作用域屬於全局模塊,或者不存在這樣的模塊,則返回空列表。例如,下面將打印 "{Y} {X}":

module X {
rule get-caller { return [ CALLER_MODULE ] ; }
rule get-caller's-caller { return [ CALLER_MODULE 1 ] ; }
rule call-Y { return Y.call-X2 ; }
}
module Y {
rule call-X { return X.get-caller ; }
rule call-X2 { return X.get-caller's-caller ; }
}
callers = [ X.get-caller ] [ Y.call-X ] [ X.call-Y ] ;
ECHO {$(callers)} ;
rule DELETE_MODULE ( module ? )

DELETE_MODULE removes all of the variable bindings and otherwise-unreferenced rules from the given module (or the global module, if no module is supplied), and returns their memory to the system.
DELETE_MODULE 從給定模塊(或全局模塊,如果模塊未給出)刪除所有變量綁定和其它未引用規則,並將它們的內存返回給系統。

[Note] Note 說明

Though it won't affect rules that are currently executing until they complete, DELETE_MODULE should be used with extreme care because it will wipe out any others and all variable (including locals in that module) immediately. Because of the way dynamic binding works, variables which are shadowed by locals will not be destroyed, so the results can be really unpredictable.

雖然在當前規則執行完成前,不會受到影響,但是 DELETE_MODULE 還是要極為小心地使用,因為它會立即銷毀所有其它規則和所有變量(包括模塊中的局部變量)。因為動態綁定的工作方式,被局部遮蔽的變量不會被銷毀,所以結果真的不可預知。


PrevUpHomeNext