Miscellaneous

In addition to generic error messages, bjam may emit one of the following:
除了通常的錯誤信息，bjam 可能還會發出以下信息：

warning: unknown rule X

A rule was invoked that has not been defined with an "actions" or "rule" statement.
表示被調用的規則沒有用 "actions" 或 "rule" 語句定義。

using N temp target(s)

Targets marked as being temporary (but nonetheless present) have been found.
找到標記為臨時的(但卻是存在的)目標。

updating N target(s)

Targets are out-of-date and will be updated.
目標過期，將被更新。

can't find N target(s)

Source files can't be found and there are no actions to create them.
不能找到源文件，且沒有動作創建它們。

can't make N target(s)

Due to sources not being found, other targets cannot be made.
由於源文件未找到，其它目標不能構建。

warning: X depends on itself

A target depends on itself either directly or through its sources.
目標直接或通過它的源依賴於它自己本身。

don't know how to make X

A target is not present and no actions have been defined to create it.
目標不存在且沒有定義動作來創建它。

X skipped for lack of Y

A source failed to build, and thus a target cannot be built.
源文件構建失敗，因此目標不能構建。

warning: using independent target X

A target that is not a dependency of any other target is being referenced with $(<) or $(>).
某個被 $(<) 或 $(>) 引用的目標不是其它目標的依賴物。

X removed

BJam removed a partially built target after being interrupted.
BJam 在中斷後刪除了一部分構建目標。

Bugs, Limitations 缺陷和限制

For parallel building to be successful, the dependencies among files must be properly spelled out, as targets tend to get built in a quickest-first ordering. Also, beware of un-parallelizable commands that drop fixed-named files into the current directory, like yacc(1) does.
為了成功進行並發構建，文件的依賴關係必須正確說明，以使目標以盡可能快的順序進行構建。另外，小心留意不可並發的命令，它們會刪除當前目錄中的固定名字的文件，像 yacc(1) 所做的。

A poorly set $(JAMSHELL) is likely to result in silent failure.
對 $(JAMSHELL) 設置得不好很可能會導致無聲無息的失敗。

Fundamentals 基本原理

This section is derived from the official Jam documentation and from experience using it and reading the Jambase rules. We repeat the information here mostly because it is essential to understanding and using Jam, but is not consolidated in a single place. Some of it is missing from the official documentation altogether. We hope it will be useful to anyone wishing to become familiar with Jam and the Boost build system.
本章源自於 Jam 的官方文檔和使用它的經驗以及對 Jambase 規則的閱讀。我們在此重複這些信息，主要是因為它們對於理解和使用 Jam 是必需的，但它們並未被整理到一起。其中有些還是官方文檔中沒有的。我們希望它們對那些希望熟練掌握 Jam 和 Boost build 系統的用戶有所幫助。

Jam "rules" are actually simple procedural entities. Think of them as functions. Arguments are separated by colons.
Jam "rules" 實際上是簡單的程序實體。將它們視為函數。參數以冒號分隔。
A Jam target is an abstract entity identified by an arbitrary string. The build-in DEPENDS rule creates a link in the dependency graph between the named targets.
Jam 目標是一個由任意字符串標識的抽像實體。內建的 DEPENDS 規則在依賴關係圖中創建命名目標之間的鏈接。
Note that the original Jam documentation for the built-in INCLUDES rule is incorrect: INCLUDES targets1 : targets2 causes everything that depends on a member of targets1 to depend on all members of targets2. It does this in an odd way, by tacking targets2 onto a special tail section in the dependency list of everything in targets1. It seems to be OK to create circular dependencies this way; in fact, it appears to be the "right thing to do" when a single build action produces both targets1 and targets2.
注意，舊的 Jam 文檔對於內建的 INCLUDES 規則的描述是不正確的：INCLUDES targets1 : targets2 會導致依賴於 targets1 某一成員的任何東西依賴於 targets2 的所有成員。它是以一種奇特的方式來實現的，通過將 targets2 作為一個特殊尾節增加到 targets1 各個成員的依賴關係列表中。以這種方法創建循環依賴關係似乎是OK的；事實上，當單個構建動作同時生成 targets1 和 targets2 時，它看來是"做了正確的事情"。
When a rule is invoked, if there are actions declared with the same name as the rule, the actions are added to the updating actions for the target identified by the rule's first argument. It is actually possible to invoke an undeclared rule if corresponding actions are declared: the rule is treated as empty.
在一個規則被調用時，如果存在與該規則同名的 actions，則該動作會被增加到由規則的第一個參數所標識的目標的更新動作中。如果相應的動作被聲明，實際上就有可能會調用一個未聲明的規則：該規則被視為空規則。
Targets (other than NOTFILE targets) are associated with paths in the file system through a process called binding. Binding is a process of searching for a file with the same name as the target (sans grist), based on the settings of the target-specific SEARCH and LOCATE variables.
目標(除了 NOTFILE 目標以外)被通過一個稱為綁定的過程關聯至文件系統中的路徑。綁定是查找一個與目標具有相同名字的文件(無 grist)的過程，它基於特定目標的 SEARCH 和 LOCATE 變量。
In addition to local and global variables, jam allows you to set a variable on a target. Target-specific variable values can usually not be read, and take effect only in the following contexts:
除了局部變量和全局變量，jam 還允許你在一個目標上設置變量。特定目標變量的值通常不能被讀出，僅在以下上下文中生效：
- In updating actions, variable values are first looked up on the target named by the first argument (the target being updated). Because Jam builds its entire dependency tree before executing actions, Jam rules make target-specific variable settings as a way of supplying parameters to the corresponding actions.
  在更新動作中，變量的值首先在由第一個參數所給出的名字的目標(被更新的目標)上進行查找。因為 Jam 在執行動作之前構建完整的依賴關係樹，Jam 的規則將特定目標變量作為為相應動作提供參數的方法。
- Binding is controlled entirely by the target-specific setting of the SEARCH and LOCATE variables, as described here.
  綁定完全是由特定目標所設置的 SEARCH 和 LOCATE 變量所控制的，如上所述。
- In the special rule used for header file scanning, variable values are first looked up on the target named by the rule's first argument (the source file being scanned).
  在用於頭文件掃瞄的特殊規則中，變量的值首先在由規則的第一個參數所給出的名字的目標(被掃瞄的源文件)上進行查找。
The "bound value" of a variable is the path associated with the target named by the variable. In build actions, the first two arguments are automatically replaced with their bound values. Target-specific variables can be selectively replaced by their bound values using the bind action modifier.
一個變量的"綁定值"即與該變量所命名的目標相關聯的路徑。在構建動作中，頭兩個參數會自動替換為它們的綁定值。特定目標變量可以用 bind 動作修改符可選擇地替換為它們的綁定值。
Note that the term "binding" as used in the Jam documentation indicates a phase of processing that includes three sub-phases: binding (yes!), update determination, and header file scanning. The repetition of the term "binding" can lead to some confusion. In particular, the Modifying Binding section in the Jam documentation should probably be titled "Modifying Update Determination".
注意，術語"綁定"和在 Jam 文檔中所使用的一樣，表示一個包含三個子階段的處理階段，這三個子階段是：綁定(沒錯!)、更新決定和頭文件掃瞄。重複使用術語"綁定"可能會引起一些混亂。特別地，Jam 文檔中的"修改綁定"一節的標題可以改為"修改更新決定"。
"Grist" is just a string prefix of the form <characters>. It is used in Jam to create unique target names based on simpler names. For example, the file name "test.exe" may be used by targets in separate subprojects, or for the debug and release variants of the "same" abstract target. Each distinct target bound to a file called "test.exe" has its own unique grist prefix. The Boost build system also takes full advantage of Jam's ability to divide strings on grist boundaries, sometimes concatenating multiple gristed elements at the beginning of a string. Grist is used instead of identifying targets with absolute paths for two reasons:
"Grist" 只是一個形如 <characters> 的字符串前綴。在 Jam 中它被用來基於簡單的名字創建唯一的目標名。例如，文件名 "test.exe" 可能在單獨的子項目中被用作目標，或者用作"同一個"抽像目標的調試版和發佈版。每一個綁定到 "test.exe" 文件的特定目標都有唯一的 grist 前綴以。Boost build 系統還充分利用了 Jam 的功能，將字符串按 grist 邊界劃分，有時則將多個 gristed 元素連接在字符串的開始。Grist 被用於替代絕對路徑標識目標有兩個原因：
1. The location of targets cannot always be derived solely from what the user puts in a Jamfile, but sometimes depends also on the binding process. Some mechanism to distinctly identify targets with the same name is still needed.
  目標的位置並不總是可以從用戶在 Jamfile 中輸入的字符串單獨獲得，不過有時也依賴於綁定過程。還是需要一些機制來用相同的名字清楚地標識目標。
2. Grist allows us to use a uniform abstract identifier for each built target, regardless of target file location (as allowed by setting ALL_LOCATE_TARGET.
  Grist 允許我們對每個構建目標使用統一的抽像標識符，而不管目標文件的位置(就像通過設置 ALL_LOCATE_TARGET 那樣)。
When grist is extracted from a name with $(var:G), the result includes the leading and trailing angle brackets. When grist is added to a name with $(var:G=expr), existing grist is first stripped. Then, if expr is non-empty, leading <s and trailing >s are added if necessary to form an expression of the form <expr2>; <expr2> is then prepended.
當從一個帶有 $(var:G) 的名字中取出 grist 時，結果將包含開始和結尾的尖括號。當 grist 被增加到一個帶有 $(var:G=expr) 的名字中時，首先去掉已有的 grist。然後，如果 expr 為非空，則當需要時將開始的 <s 和結尾的 >s 加入，形成一個形如 <expr2> 的表達式；<expr2> 就是所要的。
When Jam is invoked it imports all environment variable settings into corresponding Jam variables, followed by all command-line (-s...) variable settings. Variables whose name ends in PATH, Path, or path are split into string lists on OS-specific path-list separator boundaries (e.g. ":" for UNIX and ";" for Windows). All other variables are split on space (" ") boundaries. Boost Jam modifies that behavior by allowing variables to be quoted.
當 Jam 被調用時，它導入所有環境變量並設置到相應的 Jam 變量中，然後是所有的命令行(-s...)變量設置。那些名字以 PATH, Path, 或 path 結尾的變量被按照OS的路徑列表分隔符(如 UNIX 為 ":"，而 Windows 為 ";")分解為字符串列表。所有其它變量被按照空格(" ")分解。Boost Jam 修改了這一行為，允許變量用引號引起來。
A variable whose value is an empty list or which consists entirely of empty strings has a negative logical value. Thus, for example, code like the following allows a sensible non-empty default which can easily be overridden by the user:
一個值為空列表或由多個空串組成的變量具有否定的邏輯值。例如，以下代碼使得一個非空的缺省值可以很容易地被用戶覆寫：
```
MESSAGE ?\= starting jam... ;
if #(MESSAGE) { ECHO The message is: #(MESSAGE) ; }
```
If the user wants a specific message, he invokes jam with "-sMESSAGE=message text". If he wants no message, he invokes jam with -sMESSAGE= and nothing at all is printed.
如果用戶想要一個特殊的信息，可以用 "-sMESSAGE=message text" 來調用 jam。如果想不要信息，則以 -sMESSAGE= 調用 jam，這樣就沒有東西打印出來了。
The parsing of command line options in Jam can be rather unintuitive, with regards to how other Unix programs accept options. There are two variants accepted as valid for an option:
在 Jam 中的命令行選項分析可能有點違反直覺，與其它的 Unix 程序接受選項的方式相比。對於一個選項，以下兩種變體都是有效的：
1. -xvalue, 和
2. -x value.

Miscellaneous 雜項

Diagnostics 診斷

Bugs, Limitations 缺陷和限制

Fundamentals 基本原理