Boost C++ Libraries Home Libraries People FAQ More


Using BJam 使用 BJam

Options 選項
Operation 操作

If target is provided on the command line, bjam builds target; otherwise bjam builds the target all.
如果在命令行中提供了 targetbjam 將構建 target;否則 bjam 構建目標 all

bjam ( -option [value] | target ) *

Options are either singular or have an accompanying value. When a value is allowed, or required, it can be either given as an argument following the option argument, or it can be given immediately after the option as part of the option argument. The allowed options are:


Build all targets anyway, even if they are up-to-date.

-d n

Enable cummulative debugging levels from 1 to n. Values are:

  1. Show the actions taken for building targets, as they are executed (the default).
  2. Show "quiet" actions and display all action text, as they are executed.
  3. Show dependency analysis, and target/source timestamps/paths.
  4. Show arguments and timming of shell invocations.
    顯示 shell 調用的參數和時間。
  5. Show rule invocations and variable expansions.
  6. Show directory/header file/archive scans, and attempts at binding to targets.
  7. Show variable settings.
  8. Show variable fetches, variable expansions, and evaluation of '"if"' expressions.
  9. Show variable manipulation, scanner tokens, and memory usage.
  10. Show profile information for rules, both timing and memory.
  11. Show parsing progress of Jamfiles.
    顯示 Jamfiles 的分析過程。
  12. Show graph of target dependencies.
  13. Show change target status (fate).

-d +n

Enable debugging level n.
打開調試級別 n

-d 0

Turn off all debugging levels. Only errors are reported.

-f Jambase

Read Jambase instead of using the built-in Jambase. Only one -f flag is permitted, but the Jambase may explicitly include other files. A Jambase name of "-" is allowed, in which case console input is read until it is closed, at which point the input is treated as the Jambase.
讀入 Jambase 以替換內建的 Jambase。只允許有一個 -f 標誌,但 Jambase 可以顯式包含其它文件。可以使用名為 "-" 的 Jambase,這樣將讀入控制台輸入直至關閉,將輸入作為 Jambase。

-j n

Run up to n shell commands concurrently (UNIX and NT only). The default is 1.
並發運行最多 n 個 shell 命令(僅用於 UNIX 和 NT)。缺省為1。

-l n

Limit actions to running for n number of seconds, after which they are stopped. Note: Windows only.
限制各動作只能運行 n 秒,超時者將被停止。註:僅用於 Windows。


Don't actually execute the updating actions, but do everything else. This changes the debug level default to -d 2.
不實際執行更新動作,但執行其它動作。這將使缺省的調試級別變為 -d 2.

-o file

Write the updating actions to the specified file instead of running them.


Quit quickly (as if an interrupt was received) as soon as any target fails.

-s var=value

Set the variable var to value, overriding both internal variables and variables imported from the environment.
將變量 var 設為 value,覆蓋內部變量和從環境變量導入的變量。

-t target

Rebuild target and everything that depends on it, even if it is up-to-date.
重新構建 target 以及所有依賴於它的東西,即使它是最新的。

-- value

The option and value is ignored, but is available from the $(ARGV) variable.
該選項與 value 被忽略,但可以從 $(ARGV) 變量獲得。


Print the version of bjam and exit.
打印 bjam 的版本信息並退出。

Classic Jam had an odd behavior with respect to command-line variable (-s...) and environment variable settings which made it impossible to define an arbitrary variable with spaces in the value. Boost Jam remedies that by treating all such settings as a single string if they are surrounded by double-quotes. Uses of this feature can look interesting, since shells require quotes to keep characters separated by whitespace from being treated as separate arguments:
經典的 Jam 對於命令行變量(-s...) 和環境變量設置有一個怪異的行為,使得它不能定義一個其值中帶有空格的變量。Boost Jam 通過將所有由雙引號括起來的設置視為單個字符串來解決這一問題。該特性的使用看起來可以會很奇怪,因為 shells 要求引號要通過空格與視為獨立參數的字符分隔:

jam -sMSVCNT="\"\"C:\Program Files\Microsoft Visual C++\VC98\"\"" ...

The outer quote is for the shell. The middle quote is for Jam, to tell it to take everything within those quotes literally, and the inner quotes are for the shell again when paths are passed as arguments to build actions. Under NT, it looks a lot more sane to use environment variables before invoking jam when you have to do this sort of quoting:
外層的引號是給 shell 用的。中間的引號是給 Jam 用的,告訴它將引號所引內容按字面處理,最裡面的引號還是給 shell 用的,其中的路徑被作為參數傳遞給 build 動作。在 NT 下,在調用 jam 前使用帶引號的環境變量的方法顯得更清晰一些:

set MSVCNT=""C:\Program Files\Microsoft Visual C++\VC98\""

BJam has four phases of operation: start-up, parsing, binding, and updating.
BJam 有四個操作階段:開始,分析,綁定和更新。

Upon start-up, bjam imports environment variable settings into bjam variables. Environment variables are split at blanks with each word becoming an element in the variable's list of values. Environment variables whose names end in PATH are split at $(SPLITPATH) characters (e.g., ":" for Unix).
在開始階段,bjam 將環境變量設置導入到 bjam 變量中。環境變量被以空白分拆,每個單詞成為變量的值列表中的一個元素。名字以 PATH 結尾的環境變量則以 $(SPLITPATH) 字符(如在 Unix 下的 ":" )分拆。

To set a variable's value on the command line, overriding the variable's environment value, use the -s option. To see variable assignments made during bjam's execution, use the -d+7 option.
要在命令行中設置一個變量的值,以覆蓋環境變量中的值,請使用 -s 選項。要查看在 bjam 的執行過程中的變量賦值情況,請使用 -d+7 選項。

The Boost.Build v2 initialization behavior has been implemented. This behavior only applies when the executable being invoked is called "bjam" or, for backward-compatibility, when the BOOST_ROOT variable is set.
Boost.Build v2 已實現了初始化行為。該行為僅當被調用的可執行文件名為 "bjam" 時,或者當 BOOST_ROOT 變量被設置時被應用,後一種情況是為了後向兼容。

  1. We attempt to load "boost-build.jam" by searching from the current invocation directory up to the root of the file system. This file is expected to invoke the boost-build rule to indicate where the Boost.Build system files are, and to load them.
    我們會從當前的執行目錄向上直至文件系統根目錄查找並嘗試裝載 "boost-build.jam"。該文件應執行 boost-build 規則來表示 Boost.Build 系統文件位於何處,然後裝載它們。
  2. If boost-build.jam is not found we error and exit, giving brief instructions on possible errors. As a backward-compatibility measure for older versions of Boost.Build, when the BOOST_ROOT variable is set, we first search for boost-build.jam in $(BOOST_ROOT)/tools/build and $(BOOST_BUILD_PATH). If found, it is loaded and initialization is complete.
    如果無法找到 boost-build.jam,我們就報錯並退出,給出可能錯誤的主要指示。為了與舊版本的 Boost.Build 兼容,當 BOOST_ROOT 變量被設置時,我們首先在 $(BOOST_ROOT)/tools/build$(BOOST_BUILD_PATH) 中查找 boost-build.jam。如果可以找到,則裝入它且初始化結束。
  3. The boost-build rule adds its (optional) argument to the front of BOOST_BUILD_PATH, and attempts to load bootstrap.jam from those directories. If a relative path is specified as an argument, it is treated as though it was relative to the boost-build.jam file.
    boost-build 規則將它的(可選的)參數加入到 BOOST_BUILD_PATH 的前面,並嘗試從這些目錄裝載 bootstrap.jam。如果參數指定的是一個相對路徑,則將它視為與 boost-build.jam 文件的相對路徑。
  4. If the bootstrap.jam file was not found, we print a likely error message and exit.
    如果無法找到 bootstrap.jam 文件,我們打印一個類似的錯誤信息並退出。

In the parsing phase, bjam reads and parses the Jambase file, by default the built-in one. It is written in the jam language. The last action of the Jambase is to read (via the "include" rule) a user-provided file called "Jamfile".
在分析階段,bjam 讀入並分析 Jambase 文件,缺省是內建的文件。它是用 jam 語言 編寫的。Jambase 的最後一個動作是(通過 "include" 規則)讀入一個用戶提供的名為 "Jamfile" 的文件。

Collectively, the purpose of the Jambase and the Jamfile is to name build targets and source files, construct the dependency graph among them, and associate build actions with targets. The Jambase defines boilerplate rules and variable assignments, and the Jamfile uses these to specify the actual relationship among the target and source files.
總的來說,JambaseJamfile 的目的是給出要構建的目標文件和源文件,構造它們的依賴關係圖,將構建動作關聯到目標。Jambase 定義了樣板規則和變量賦值,而 Jamfile 則使用這些規則來指定目標文件和源文件的實際關係。

After parsing, bjam recursively descends the dependency graph and binds every file target with a location in the filesystem. If bjam detects a circular dependency in the graph, it issues a warning.
完成分析後,bjam 對依賴關係圖進行向下遞歸,將各個文件目標綁定到文件系統中的某個位置。如果 bjam 在圖中檢測到循環依賴關係,則發出一個警告。

File target names are given as absolute or relative path names in the filesystem. If the path name is absolute, it is bound as is. If the path name is relative, it is normally bound as is, and thus relative to the current directory. This can be modified by the settings of the $(SEARCH) and $(LOCATE) variables, which enable jam to find and build targets spread across a directory tree. See SEARCH and LOCATE Variables below.
文件目標名是以文件系統中的絕對或相對路徑名給定的。如果路徑名是絕對的,就照原樣綁定。如果路徑名是相對的,則通常是相對於當前目錄按路徑名進行綁定。但是這一行為可以通過對 $(SEARCH)$(LOCATE) 變量的設置來改變,該變量可以讓 jam 通過一個目錄樹進行目標的查找和構建。請參見後文的 SEARCH 和 LOCATE 變量

After binding each target, bjam determines whether the target needs updating, and if so marks the target for the updating phase. A target is normally so marked if it is missing, it is older than any of its sources, or any of its sources are marked for updating. This behavior can be modified by the application of special built-in rules, ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, and TEMPORARY. See Modifying Binding below.
完成了各個目標的綁定後,bjam 將確定哪些目標需要更新,並對要更新的目標進行標記。一個目標文件如果不存在,或者比它的源文件舊,或者它的任何一個源文件被標記為更新,則該目標文件就要被標記。這一行為可以通過特定內建規則,ALWAYS, LEAVES, NOCARE, NOTFILE, NOUPDATE, 和 TEMPORARY 的應用來改變。請參數後文的 修改綁定

During the binding phase, bjam also performs header file scanning, where it looks inside source files for the implicit dependencies on other files caused by C's #include syntax. This is controlled by the special variables $(HDRSCAN) and $(HDRRULE). The result of the scan is formed into a rule invocation, with the scanned file as the target and the found included file names as the sources. Note that this is the only case where rules are invoked outside the parsing phase. See HDRSCAN and HDRRULE Variables below.
在綁定階段,bjam 還要執行頭文件掃瞄,它查看源文件的內部,查找由 C 的 #include 語法所引起的對其它文件的隱式依賴關係。這是由特定變量 $(HDRSCAN) 和 $(HDRRULE) 來控制的。掃瞄的結果形成一個規則調用,以被掃瞄文件為目標,以所找到的被包含文件名為源。注意,這是在分析階段以外進行規則調用的唯一情況。請參見後文 的 HDRSCAN 和 HDRRULE 變量

After binding, bjam again recursively descends the dependency graph, this time executing the update actions for each target marked for update during the binding phase. If a target's updating actions fail, then all other targets which depend on that target are skipped. 
在完成綁定後,bjam 再次對依賴關係圖進行向下遞歸,這次是對每一個在綁定階段被標記為更新的目標執行更新動作。如果某個目標的更新動作失敗,則所有其它依賴於此目標的目標均被跳過。

The -j flag instructs bjam to build more than one target at a time. If there are multiple actions on a single target, they are run sequentially.
-j 選項指示 bjam 同一時間構建一個以上的目標。如果同一個目標有多個動作,這些動作會順序執行。