This section will describe the basics of the Boost.Jam language—just enough for writing Jamfiles. For more information, please see the Boost.Jam documentation.
本節描述 Boost.Jam 語言的基礎—僅夠用於編寫 Jamfiles。更多的信息，請參見 Boost.Jam 文檔。

Boost.Jam has an interpreted, procedural language. On the lowest level, a Boost.Jam program consists of variables and rules (the Jam term for function). They are grouped in modules—there's one global module and a number of named modules. Besides that, a Boost.Jam program contains classes and class instances.
Boost.Jam 有一個解釋性的過程語言。在最底層，Boost.Jam 程序由變量和 規則 ("函數"一詞在 Jam 中的術語)組成。它們組成各個模塊—有一個全局模塊和多個命名模塊。此外，Boost.Jam 程序還包含類和類實例。

Syntantically, a Boost.Jam program consists of two kind of elements—keywords (which have a special meaning to Boost.Jam) and literals. Consider this code:
在語法上，Boost.Jam 程序由兩類元素組成—關鍵字(對於 Boost.Jam 來說具有特殊的意義) 和普通文字。考慮以下代碼：

a = b ;

which assigns the value b to the variable a. Here, = and ; are keywords, while a and b are literals.
它將值 b 賦給變量 a。這裡，= 和 ; 是關鍵字，而 a 和 b 是普通文字。

	Warning 警告
	All syntax elements, even keywords, must be separated by spaces. For example, omitting the space character before ; will lead to a syntax error. 所有語法元素，包括關鍵字，都必須用空格分隔。例如，省略 ; 前面的空格將導致語法錯誤。

If you want to use a literal value that is the same as some keyword, the value can be quoted:
如果你想使用一個與某個關鍵字相同的文字，就要把它用引號引起來：

a = "=" ;

All variables in Boost.Jam have the same type—list of strings. To define a variable one assigns a value to it, like in the previous example. An undefined variable is the same as a variable with an empty value. Variables can be accessed using the $(variable) syntax. For example:
在 Boost.Jam 中的所有變量都具有相同的類型—字符串列表。要定義一個變量同時賦值給它，就像前面的例子那樣。一個未定義的變量和一個具有空值的變量一樣。變量可以用 $(variable) 語法來訪問。例如：

a = $(b) $(c) ;

Rules are defined by specifying the rule name, the parameter names, and the allowed size of the list value for each parameter.
規則通過指定規則名、參數名及各個參數所允許的列表值大小來定義。

rule example
     (
         parameter1 :
         parameter2 ? :
         parameter3 + :
         parameter4 *
     )
     {
        // body
     }

When this rule is called, the list passed as the first argument must have exactly one value. The list passed as the second argument can either have one value of be empty. The two remaining arguments can be arbitrarily long, but the third argument may not be empty.
在調用這個規則時，傳入的第一個參數的列表必須剛好包含一個值。第二個參數的列表則可以有一個值或者為空。其餘兩個參數可以是變長的，但第三個參數不能為空。

The overview of Boost.Jam language statements is given below:
以下是 Boost.Jam 語言的語句的一個概覽：

helper 1 : 2 : 3 ;
x = [ helper 1 : 2 : 3 ] ;

This code calls the named rule with the specified arguments. When the result of the call must be used inside some expression, you need to add brackets around the call, like shown on the second line.
這段代碼以給定的參數調用命名規則。當調用的結果要在某個表達式中使用時，你必須用方括號把調用括起來，就像前面第二行語句那樣。

if cond { statements } [ else { statements } ]

This is a regular if-statement. The condition is composed of:
這是一個普通的 if-語句。條件由以下組成：

for var in list { statements }

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

while cond { statements }

Repeatedly execute statements while cond remains true upon entry.
當 cond 在每次進入時保持為真時重複執行 statements。

return values ;
      

This statement should be used only inside a rule and assigns values to the return value of the rule.
這個語句只應在某個規則的內部使用，它將 values 賦為該規則的返回值。

	Warning 警告
	The return statement does not exit the rule. For example: return 語句不會退出規則。例如： rule test ( ) { if 1 = 1 { return "reasonable" ; } return "strange" ; } will return strange, not reasonable. 將返回 strange, 而不是 reasonable.

import module ;
import module : rule ;

The first form imports the specified bjam module. All rules from that module are made available using the qualified name: module.rule. The second form imports the specified rules only, and they can be called using unqualified names.
第一種形式導入指定的 bjam 模塊。該模塊的所有規則都可以通過限定名稱 module.rule 使用。第二種形式僅導入指定的規則，該規則可以通過非限定名稱調用。

Sometimes, you'd need to specify the actual command lines to be used when creating targets. In jam language, you use named actions to do this. For example:
有時候，你需要在構建目標時指定真實的命令行。在 jam 語言中，你可以用命名動作來實現。例如：

actions create-file-from-another
{
    create-file-from-another $(<) $(>)
}

This specifies a named action called create-file-from-another. The text inside braces is the command to invoke. The $(<) variable will be expanded to a list of generated files, and the $(>) variable will be expanded to a list of source files.
它指定了一個名為 create-file-from-another 的命名動作。在大括號中的文本是要調用的命令。變量 $(<) 將被展開為被生成文件的列表，而變量 $(>) 則被展開為源文件的列表。

To flexibly adjust command line, you can define a rule with the same name as the action, and taking three parameters -- targets, sources and properties. For example:
為了靈活調整命令行，你可以定義一個和該動作同名的規則，它接受三個參數 -- 目標、源和屬性。例如：

rule create-file-from-another ( targets * : sources * : properties * )
{
   if <variant>debug in $(properties)
   {
       OPTIONS on $(targets) = --debug ;
   }
}
actions create-file-from-another
{
    create-file-from-another $(OPTIONS) $(<) $(>)
}

In this example, the rule checks if certain build property is specified. If so, it sets variable OPIONS that is then used inside the action. Note that the variables set "on a target" will be visible only inside actions building that target, not globally. Were they set globally, using variable named OPTIONS in two unrelated actions would be impossible.
在這個例子中，規則會檢查是否指定了特定的構建屬性。如果有，則設置變量 OPIONS 然後在動作中使用它。注意，被設置"在特定目標上"的變量僅在構建該目標的動作內可見，而不是全局的。如果它被設為全局的，那麼在兩個無關的動作中使用名為 OPTIONS 的變量就不可能了。

More details can be found in Jam reference, the section called 「 Rules」
更多細節可以在 Jam 參考手冊的 「規則」一節 中找到

The Boost.Build configuration is specified in the file user-config.jam. You can edit the one in the top-level directory of Boost.Build installation or create a copy in your home directory and edit that. (See Table 28.2, 「Search paths for configuration files」 for the exact search paths.) The primary function of that file is to declare which compilers and other tools are available. The simplest syntax to configure a tool is:
Boost.Build 的配置是在文件 user-config.jam 中指定的。你可以編輯位於 Boost.Build 安裝的頂層目錄中的那個文件，或者在你的主目錄中創建一個拷貝並編輯它。(精確的查找路徑請見 表 28.2, 「配置文件的查找路徑」)。該文件的主要功能是聲明有哪些編譯器和工具可用。配置一個工具的最簡單語法是：

using tool-name ;

The using rule is given a name of tool, and will make that tool available to Boost.Build. For example, using gcc ; will make the gcc compiler available.
規則 using 給定工具的名字，並使得該工具對 Boost.Build 可用。例如，using gcc ; 將使得 gcc 編譯器可用。

Since nothing but a tool name is specified, Boost.Build will pick some default settings. For example, it will use the gcc executable found in the PATH, or look in some known installation locations. In most cases, this strategy works automatically. In case you have several versions of a compiler, it's installed in some unusual location, or you need to tweak its configuration, you'll need to pass additional parameters to the using rule. The parameters to using can be different for each tool. You can obtain specific documentation for any tool's configuration parameters by invoking
由於只給出了工具名，所以 Boost.Build 將選取一些缺省的設置。例如，它將使用在 PATH 或某些已知的安裝位置中找到的 gcc 可執行文件。多數情況下，這一策略可自動工作。如果你有某個編譯器的多個版本，它們被安裝在某個與眾不同的位置，或者你想要優化編譯器的配置，那麼你就需要傳遞其它參數給 using 規則。給 using 的參數可以對每個工具各不一樣。你可以通過調用以下命令獲得關於任一工具的配置參數的文檔：

bjam --help tool-name.init

That said, for all the compiler toolsets Boost.Build supports out-of-the-box, the list of parameters to using is the same: toolset-name, version, invocation-command, and options.
即是說，對於 Boost.Build 缺省配置就支持的所有編譯器工具集，給 using 的參數列表都是一樣的：toolset-name, version, invocation-command, 和 options.

The version parameter identifies the toolset version, in case you have several installed. It can have any form you like, but it is recommended that you use a numeric identifier like 7.1.
參數 version 標識了工具集的版本，如果你安裝了多個版本。它可以有你喜歡的任意格式，不過建議你使用數字標識，如 7.1.

The invocation-command parameter is the command that must be executed to run the compiler. This parameter can usually be omitted if the compiler executable
參數 invocation-command 是運行該編譯器所必須執行的命令。該參數通常可以省略，如果編譯器的可執行文件

For example:
例如：

using msvc : 7.1 ;
using gcc ;

If the compiler can be found in the PATH but only by a nonstandard name, you can just supply that name:
如果編譯器可以在 PATH 中找到，但是用了一個非標準的名字，那麼你只要給定這個名字就行了：

using gcc : : g++-3.2 ;

Otherwise, it might be necessary to supply the complete path to the compiler executable:
否則，就可能需要提供這個編譯器的可執行文件的完整路徑：

using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ;

Some Boost.Build toolsets will use that path to take additional actions required before invoking the compiler, such as calling vendor-supplied scripts to set up its required environment variables. When compiler executables for C and C++ are different, path to the C++ compiler executable must be specified. The 「invocation command」 can be any command allowed by the operating system. For example:
有些 Boost.Build 工具集要在調用編譯器之前用這個路徑來進行其它必要的動作，如調用一個廠家提供的腳本來設置所需的環境變量。如果用於 C 和 C++ 的編譯程序是不同的，那麼必須指定 C++ 編譯程序的路徑。「invocation command」可以是操作系統允許的任何命令。例如：

using msvc : : echo Compiling && foo/bar/baz/cl ;

will work.
也可以工作。

To configure several versions of a toolset, simply invoke the using rule multiple times:
要配置一個工具集的多個版本，只要多次調用 using 規則即可。

using gcc : 3.3 ;
using gcc : 3.4 : g++-3.4 ;
using gcc : 3.2 : g++-3.2 ;

Note that in the first call to using, the compiler found in the PATH will be used, and there's no need to explicitly specify the command.
注意，在調用第一個 using 時，會使用在 PATH 中找到的編譯器，無需明確指定相關命令。

As shown above, both the version and invocation-command parameters are optional, but there's an important restriction: if you configure the same toolset more than once, you must pass the version parameter every time. For example, the following is not allowed:
如上所示，參數 version 和 invocation-command 都是可選的，但是有一個重要的限制：如果你超過一次配置同一個工具集，你必須在每次傳遞 version 參數。例如，以下是不可以的：

using gcc ;
using gcc : 3.4 : g++-3.4 ;

because the first using call does not specify a version.
因為第一個 using 調用沒有指定 version.

The options parameter is used to fine-tune the configuration. All of Boost.Build's standard compiler toolsets accept properties of the four builtin features cflags, cxxflags, compileflags and linkflags as options specifying flags that will be always passed to the corresponding tools. Values of the cflags feature are passed directly to the C compiler, values of the cxxflags feature are passed directly to the C++ compiler, and values of the compileflags feature are passed to both. For example, to configure a gcc toolset so that it always generates 64-bit code you could write:
參數 options 用於對配置進行調整。所有 Boost.Build 的標準編譯器工具集都用 options 接受四個內建特性 cflags, cxxflags, compileflags 和 linkflags 的屬性，以指定傳遞給對應工具的選項。cflags 特性的值會直接傳遞給 C 編譯器，cxxflags 特性的值則直接傳遞給 C++ 編譯器，而 compileflags 特性的值則傳給兩者。例如，要將 gcc 工具集進行配置以使之一直生成64位代碼，你可以寫：

using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ;

This section describes how invoke Boost.Build from the command line
本節描述如何從命令行調用 Boost.Build。

To build all targets defined in Jamfile in the current directory with default properties, run:
要以缺省屬性構建當前目錄的 Jamfile 中的所有目標，運行：

bjam

To build specific targets, specify them on the command line:
要構建特定目標，則在命令行中指定它們：

bjam lib1 subproject//lib2

To request a certain value for some property, add property=value to the command line:
要為某些屬性指定特定值，則在命令行中加入 property=value ：

bjam toolset=gcc variant=debug optimization=space

For often used features, like toolset and variant you can omit the feature name, so the above can be written as:
對於經常使用的特性，如 toolset 和 variant，你可以省略特性名，所以上例也可以寫成：

bjam optimization=space

Boost.Build recognizes the following command line options.
Boost.Build 使用以下命令行選項：

For complete specification of command line syntax, see the section called 「Command line arguments」
命令行語法的完整說明，請見 「命令行參數」一節

A Main target is a user-defined named entity that can be built, for example an executable file. Declaring a main target is usually done using one of the main target rules described in the section called 「Builtin rules」. The user can also declare custom main target rules as shown in the section called 「Main target rules」.
主目標 是指用戶定義的一個可構建的命名實體，例如一個可執行文件。主目標通常是通過使用在 「內建規則」一節 中描述的主目標規則之一來聲明的。用戶也可以像在 「主目標規則」一節 中所說的那樣聲明定制的主目標規則。

Most main target rules in Boost.Build have the same common signature:
Boost.Build 中多數主目標規則都具有相同的公用簽名：

rule rule-name (
     main-target-name :
     sources + :
     requirements * :
     default-build * :
     usage-requirements * )

Some main target rules have a different list of parameters as explicitly stated in their documentation.
有些主目標規則具有不同的參數列表，將在它們的文檔中明確說明。

The actual requirements for a target are obtained by refining requirements of the project where a target is declared with the explicitly specified requirements. The same is true for usage-requirements. More details can be found in the section called 「Property refinement」
一個目標的實際要求是通過對聲明該目標的工程的要求和顯式指定的要求一起精化而得到的。對於 usage-requirements 也一樣。更多細節可以在 「屬性精化」一節 中找到。

obj test.release : test.cpp : <variant>release ;
obj test.debug : test.cpp : <variant>debug ;

exe a : a.cpp ;           # a.cpp is the only source file  a.cpp 是唯一的源文件
exe b : [ glob *.cpp ] ;  # all .cpp files in this directory are sources 目錄中所有 .cpp 文件都是源

lib helper : helper.cpp ;
exe a : a.cpp helper ;
# Since all project ids start with slash, ".." is directory name.
exe b : b.cpp ..//utils ;
exe c : c.cpp /boost/program_options//program_options ;

exe hello : hello.cpp : <include>/opt/boost <define>MY_DEBUG ;

lib util : util.cpp : <link>static ;
obj main : main.cpp : <optimization>off ;

lib network : network.cpp
    : <link>shared:<define>NEWORK_LIB_SHARED
     <variant>release:<define>EXTRA_FAST
    ;

lib network : network.cpp
    : <toolset>gcc,<optimization>speed:<define>USE_INLINE_ASSEMBLER
    ;

lib network : network.cpp
    : <conditional>@my-rule
    ;
rule my-rule ( properties * )
{
    local result ;
    if <toolset>gcc <optimization>speed in $(properties)
    {
        result += <define>USE_INLINE_ASSEMBLER ;
    }
    return $(result) ;
}

exe main : main.cpp : -<define>UNNECESSARY_DEFINE ;

project test : requirements <threading>multi ;
exe test1 : test1.cpp ;
exe test2 : test2.cpp : <threading>single ;
exe test3 : test3.cpp : -<threading>multi ;

exe hello : hello.cpp : : <threading>multi ;

lib demangler : dummy_demangler.cpp ;                      # alternative 1
lib demangler : demangler_gcc.cpp : <toolset>gcc ;   # alternative 2
lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3

exe hello : hello.cpp
    [ obj helpers : helpers.cpp : <optimization>off ] ;

explicit install_programs ;

As mentioned before, targets are grouped into projects, and each Jamfile is a separate project. Projects are useful because they allow us to group related targets together, define properties common to all those targets, and assign a symbolic name to the project that can be used in referring to its targets.
如前所述，目標是被組織到工程中的，每一個 Jamfile 是一個獨立的工程。工程是非常有用的，因為它允許我們將相關聯的目標組織在一起，定義對所有目標通用的屬性，並賦予目標一個符號名稱，以便用於對其目標的引用。

Projects are named using the project rule, which has the following syntax:
工程是用 project 規則來命名的，具有以下語法：

project id : attributes ;

Here, attributes is a sequence of rule arguments, each of which begins with an attribute-name and is followed by any number of build properties. The list of attribute names along with its handling is also shown in the table below. For example, it is possible to write:
這裡的 attributes 是一個規則參數列表，其中每一個都是以屬性名開頭，後跟任意數量的構建屬性。屬性名列表及其處理在後文的表中列出。例如，你可以寫：

project tennis
    : requirements <threading>multi
    : default-build release
    ;

The possible attributes are listed below.
可用的屬性列出如下：

Project id is a short way to denote a project, as opposed to the Jamfile's pathname. It is a hierarchical path, unrelated to filesystem, such as "boost/thread". Target references make use of project ids to specify a target.
Project id 是表示工程的一個縮寫，與 Jamfile 的路徑名相反。它是一個分級路徑，與文件系統無關，例如 "boost/thread"。目標引用 使用 project id 來指定一個目標。

Source location specifies the directory where sources for the project are located.
Source location 指定該工程的源文件所在的目錄。

Project requirements are requirements that apply to all the targets in the projects as well as all subprojects.
Project requirements 是應用於該工程及所有子工程的所有目標的要求。

Default build is the build request that should be used when no build request is specified explicitly.
Default build 是在未明確指定構建請求時使用的構建請求。

The default values for those attributes are given in the table below.
這些屬性的缺省值在下表中給出。

Besides defining projects and main targets, Jamfiles often invoke various utility rules. For the full list of rules that can be directly used in Jamfile see the section called 「Builtin rules」.
除了定義工程和主目標之外，Jamfiles 通常還調用一些工具規則。有關可以在 Jamfile 中直接使用的規則的完整列表，請見 「內建規則」一節。

Each subproject inherits attributes, constants and rules from its parent project, which is defined by the nearest Jamfile in an ancestor directory above the subproject. The top-level project is declared in a file called Jamroot rather than Jamfile. When loading a project, Boost.Build looks for either Jamroot or Jamfile. They are handled identically, except that if the file is called Jamroot, the search for a parent project is not performed.
各子工程會繼承來自於父工程的屬性、常量和規則，它們是由子工程的一個最近的父目錄的 Jamfile 所定義的。頂層的工程由一個名為 Jamroot 的文件聲明，而不是 Jamfile。在裝入一個工程時，Boost.Build 查找 Jamroot 或 Jamfile。它們的處理方式是一樣的，除了一點，如果文件名為 Jamroot，則不再查找父工程。

Even when building in a subproject directory, parent project files are always loaded before those of their subprojects, so that every definition made in a parent project is always available to its children. The loading order of any other projects is unspecified. Even if one project refers to another via the use-project or a target reference, no specific order should be assumed.
即使是在一個子工程目錄中進行構建，父工程的文件也會在裝入子工程文件之前被裝入，這樣在父工程中的每個定義對於子工程來說都是可用的。而其它工程的裝入順序則是未指定的。即便一個工程通過 use-project 或目標引用來引用了另一個工程，也不能假定某個特定順序。

	Note 說明
	Giving the root project the special name 「Jamroot」 ensures that Boost.Build won't misinterpret a directory above it as the project root just because the directory contains a Jamfile. 為根工程給定一個特殊的名稱 「Jamroot」，可以確保 Boost.Build 不會由於更上一層的目錄中含有 Jamfile 而誤以為上層的目錄才是工程的根。

When you've described your targets, you want Boost.Build to run the right tools and create the needed targets. This section will describe two things: how you specify what to build, and how the main targets are actually constructed.
當你完成了對目標的描述，你就會希望 Boost.Build 可以運行正確的工具來創建所需的目標。這一節將講述兩件事：你如何指定要構建什麼，以及主目標實際上是如何被構造的。

The most important thing to note is that in Boost.Build, unlike other build tools, the targets you declare do not correspond to specific files. What you declare in a Jamfile is more like a 「metatarget.」 Depending on the properties you specify on the command line, each metatarget will produce a set of real targets corresponding to the requested properties. It is quite possible that the same metatarget is built several times with different properties, producing different files.
要 留意的最重要的事情是，在 Boost.Build 中，和其它構建工具不同，你所聲明的目標並不對應於特定的文件。你在  Jamfile 中所聲明的東西類似於一個「元目標」。根據你在命令行中指定的屬性，各元目標會生成一組與請求屬性相對應的真實目標。同一個元目標很有可能被按不同的屬性 多次構建，生成不同的文件。

	Tip 提示
	This means that for Boost.Build, you cannot directly obtain a build variant from a Jamfile. There could be several variants requested by the user, and each target can be built with different properties. 這意味著，對於 Boost.Build，你不能從一個 Jamfile 直接得到一個構建體。用戶可以請示多個構建體，各個目標可以按不同屬性構建。

bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full

bjam app1 lib1//lib1 gcc debug optimization=full

explicit hello_test ;