Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Common tasks 常見任務

Programs 程序
Libraries 庫
Alias 別名
Installing 安裝
Testing 測試
Custom commands 定制命令
Precompiled Headers 預編譯頭文件
Generated headers 生成頭文件

This section describes main targets types that Boost.Build supports out-of-the-box. Unless otherwise noted, all mentioned main target rules have the common signature, described in the section called 「Declaring Targets」.
這一章講述 Boost.Build 缺省支持的主目標類型。除非另有說明,否則所有提到的主目標規則都具有公用簽名,如 「聲明目標」一節 所述。

Programs 程序

Programs are created using the exe rule, which follows the common syntax. For example:
程序通過 exe 規則來創建,它遵守 公用語法。例如:

exe hello : hello.cpp some_library.lib /some_project//library
: <threading>multi
;

This will create an executable file from the sources -- in this case, one C++ file, one library file present in the same directory, and another library that is created by Boost.Build. Generally, sources can include C and C++ files, object files and libraries. Boost.Build will automatically try to convert targets of other types.
這將從源文件構建一個可執行文件 -- 在此例中,源文件是一個 C++ 文件,一個在同一目錄下的庫文件,和另外一個由 Boost.Build 創建的庫文件。通常,源文件可以包括 C 和 C++ 文件,目標文件和庫文件。Boost.Build 會自動嘗試轉換其它類型的目標。

[Tip] Tip 提示

On Windows, if an application uses dynamic libraries, and both the application and the libraries are built by Boost.Build, its not possible to immediately run the application, because the PATH environment variable should include the path to the libraries. It means you have to either add the paths manually, or place the application and the libraries to the same directory. See the section called 「Installing」.

在 Windows 上,如果一個應用程序使用了動態庫,而且這個應用程序和庫都是用 Boost.Build 構建的,那麼就不能馬上運行該應用程序,因為 PATH 環境變量要包含這個庫的路徑。這意味著你必須要麼手工添加這個路徑,要麼將應用程序和庫放在同一個目錄中。請見 「安裝」一節

Libraries 庫

Libraries are created using the lib rule, which follows the common syntax. For example:
庫通過 lib 規則來創建,它遵守 公用語法。例如:

lib helpers : helpers.cpp : <include>boost : : <include>. ;

In the most common case, the lib creates a library from the specified sources. Depending on the value of <link> feature the library will be either static or shared. There are two other cases. First is when the library is installed somewhere in compiler's search paths, and should be searched by the compiler (typically, using the -l option). The second case is where the library is available as a prebuilt file and the full path is known.
在多數情況下,lib 從指定的源創建一個庫。根據 <link> 特性的值,庫被創建為靜態或共享的。有兩種例外的情形。第一個是,庫被安裝在編譯器的查找路徑中的某個位置,並且可被編譯器查找到(通常是使用 -l 選項)。第二個情形是,庫是作為預構建文件已經存在,並且知道完整的路徑。

The syntax for these case is given below:
這種情形下的語法給出如下:

lib z : : <name>z <search>/home/ghost ;
lib compress : : <file>/opt/libs/compress.a ;

The name property specifies the name that should be passed to the -l option, and the file property specifies the file location. The search feature specifies paths in which to search for the library. That feature can be specified several times, or it can be omitted, in which case only default compiler paths will be searched.
屬性 name 指明傳遞給 -l 選項的名字,而屬性 file 則指明文件位置。屬性 search 指明在哪些路徑查找該庫。這個特性可以多次指定,或者省略,省略的話則只查找缺省的編譯器路徑。

The difference between using the file feature as opposed to the name feature together with the search feature is that file is more precise. A specific file will be used. On the other hand, the search feature only adds a library path, and the name feature gives the basic name of the library. The search rules are specific to the linker. For example, given these definition:
使用 file 特性和使用 name 特性加 search 特性的差別在於,file 更加精確。它會使用一個指定的文件。另一方面,search 特性只是增加一個庫路徑,而 name 特性則給出庫的基本名。查找的規則由鏈接器來定。例如,給出以下定義:

lib a : : <variant>release <file>/pool/release/a.so ;
lib a : : <variant>debug <file>/pool/debug/a.so ;
lib b : : <variant>release <file>/pool/release/b.so ;
lib b : : <variant>debug <file>/pool/debug/b.so ;

It's possible to use release version of a and debug version of b. Had we used the name and search features, the linker would always pick either release or debug versions.
這樣可以同時使用 a 的發佈版本和 b 的調試版本。如果我們使用 namesearch 特性,則鏈接器總是使用發佈版本或總是使用調試版本。

For convenience, the following syntax is allowed:
為方便起見,以下語法是允許的:

lib z ;
lib gui db aux ;

and is does exactly the same as:
它們與下面的寫法是完全一樣的:

lib z : : <name>z ;
lib gui : : <name>gui ;
lib db : : <name>db ;
lib aux : : <name>aux ;

When a library uses another library you should put that other library in the list of sources. This will do the right thing in all cases. For portability, you should specify library dependencies even for searched and prebuilt libraries, othewise, static linking on Unix will not work. For example:
當一個庫使用了另一個庫時,你應該將另一個庫列入源列表中。這在任何情況下都是正確的。為了移植性,你應該對查找的庫和預構建的庫都指明庫的依賴關係,否則 在 Unix 上靜態鏈接將不能工作。例如:

lib z ;
lib png : z : <name>png ;

[Note] Note 說明

When a library (say, a), that has another library, (say, b) is linked dynamically, the b library will be incorporated in a. (If b is dynamic library as well, then a will only refer to it, and not include any extra code.) When the a library is linked statically, Boost.Build will assure that all executables that link to a will also link to b.

當一個庫(稱為 a),它帶有另一個庫(稱為 b) ,被動態鏈接時,庫 b 將與 a 合成一體。(如果 b 也是動態鏈接的,則 a 只是引用它而不包含任何額外代碼)。當庫 a 被靜態鏈接時,Boost.Build 將保證所有鏈接 a 的可執行文件都鏈接了 b

One feature of Boost.Build that is very important for libraries is usage requirements. For example, if you write:
Boost.Build 中一個對於庫而言非常重要的特性就是使用要求。例如,如果你寫了:

lib helpers : helpers.cpp : : : <include>. ;

then the compiler include path for all targets that use helpers will contain the directory where the target is defined.path to "helpers.cpp". The user only needs to add helpers to the list of sources, and needn't consider the requirements its use imposes on a dependent target. This feature greatly simplifies Jamfiles.
那麼對於所有使用了 helpers 的目標來說,編譯器包含路徑將包含該目標的定義目錄和 "helpers.cpp" 的路徑。用戶只需要將 helpers 加到源列表中即可,無需考慮由被依賴目標所施加的要求。這一特性極大地簡化了 Jamfiles.

[Note] Note 說明

If you don't want shared libraries to include all libraries that are specified in sources (especially statically linked ones), you'd need to use the following:

如果你不希望共享庫包含在源中指定的所有庫(尤其是靜態鏈接的庫),你需要使用以下方法:

lib b : a.cpp ;
lib a : a.cpp : <use>b : : <library>b ;

This specifies that a uses b, and causes all executables that link to a also link to b. In this case, even for shared linking, the a library won't even refer to b.
這指明 a 使用 b,導致鏈接 a 的所有可執行文件也鏈接 b。在這種情況下,即使是共享鏈接,庫 a 也不會引向 b.

Alias 別名

The alias rule gives an alternative name to a group of targets. For example, to give the name core to a group of three other targets with the following code:
規則 alias 為一組目標給定一個別名。例如,以下代碼為由三個目標組成的組給定名字 core

alias core : im reader writer ;

Using core on the command line, or in the source list of any other target is the same as explicitly using im, reader, and writer, but it is just more convenient.
在命令行或其它目標的源列表中使用 core,和使用 im, reader, 及 writer 是一樣的,只不過更方便些。

Another use of the alias rule is to change build properties. For example, if you always want static linking for a specific C++ Boost library, you can write the following:
alias 規則的另一個用途是改變構建屬性。例如,如果你希望對某個特定的 C++ Boost 庫總是採用靜態鏈接,你可以這樣寫:

alias threads : /boost/thread//boost_thread : <link>static ;

and use only the threads alias in your Jamfiles.
然後在你的 Jamfiles 中只需要用 threads 別名就行了。

You can also specify usage requirements for the alias target. If you write the following:
你也可以為 alias 目標指定使用要求。如果你這樣寫:

alias header_only_library : : : :  <include>/usr/include/header_only_library ;

then using header_only_library in sources will only add an include path. Also note that when an alias has sources, their usage requirements are propagated as well. For example:
那麼在源文件中使用 header_only_library 只需要加一個包含路徑。還要注意,如果一個別名也具有源,則源的使用要求也會被傳播。例如:

lib library1 : library1.cpp : : : <include>/library/include1 ;
lib library2 : library2.cpp : : : <include>/library/include2 ;
alias static_libraries : library1 library2 : <link>static ;
exe main : main.cpp static_libraries ;

will compile main.cpp with additional includes required for using the specified static libraries.
將以額外的包含要求並使用指定的靜態庫來編譯 main.cpp

Installing 安裝

This section describes various ways to install built target and arbitrary files.
本節講述安裝構建目標及任意文件的幾種方法。

Basic install 基本安裝

For installing a built target you should use the install rule, which follows the common syntax. For example:
要安裝一個構建目標,你要使用 install 規則,它遵守 公用語法。例如:

install dist : hello helpers ;

will cause the targets hello and helpers to be moved to the dist directory, relative to Jamfile's directory. The directory can be changed with the location property:
將導致目標 hellohelpers 被移動至相對於 Jamfile 目錄的 dist 目錄中。該目錄可以用 location 屬性來修改:

install dist : hello helpers : <location>/usr/bin ;

While you can achieve the same effect by changing the target name to /usr/bin, using the location property is better, because it allows you to use a mnemonic target name.
雖然你也可以通過將目標名改為 /usr/bin 來得到相同效果,但是使用 location 屬性更好一些,因為它允許你使用更易記的目標名。

The location property is especially handy when the location is not fixed, but depends on build variant or environment variables:
當位置不是固定的而是由構建體或環境變量決定時,屬性 location 尤其方便:

install dist : hello helpers : <variant>release:<location>dist/release
<variant>debug:<location>dist/debug ;
install dist2 : hello helpers : <location>$(DIST) ;

See also conditional properties and environment variables
請參見 條件屬性環境變量

Installing with all dependencies 安裝所有依賴物

Specifying the names of all libraries to install can be boring. The install allows you to specify only the top-level executable targets to install, and automatically install all dependencies:
指定要安裝的所有庫的名字會很令人厭煩。install 允許你只指定要安裝的頂層可執行目標,並自動安裝所有依賴物:

install dist : hello
: <install-dependencies>on <install-type>EXE
<install-type>LIB
;

will find all targets that hello depends on, and install all of those which are either executables or libraries. More specifically, for each target, other targets that were specified as sources or as dependency properties, will be recursively found. One exception is that targets referred with the use feature are not considered, because that feature is typically used to refer to header-only libraries. If the set of target types is specified, only targets of that type will be installed, otherwise, all found target will be installed.
這將查找 hello 所依賴的所有目標,並安裝所有目標的可執行文件或庫文件。具體地說,對於每一個目標,被指定為源或依賴屬性的其它目標都會被遞歸查找。一個例外是,那些以 use 特性指定的目標不被考慮,因為這個特性是專門用於指定只含頭文件的庫的。如果指定了目標類型集,則只有該類型的目標被安裝,否則,所有目標都被安裝。

Preserving Directory Hierarchy 保留目錄層次

By default, the install rules will stip paths from it's sources. So, if sources include a/b/c.hpp, the a/b part will be ignored. To make the install rule preserve the directory hierarchy you need to use the install-source-root feature to specify the root of the hierarchy you are installing. Relative paths from that root will be preserved. For example, if you write:
缺省地,install 規則會修改來源的路徑。即,如果源中包含有 a/b/c.hpp,則 a/b 部分將被忽略。如果要讓 install 規則保留目錄的層次,你就需要使用 install-source-root 特性來指定你要安裝的目錄層次的根。從根起的相對路徑將被保留。例如,如果你寫:

install headers
: a/b/c.h
: <location>/tmp <install-source-root>a
;

the a file named /tmp/b/c.h will be created.
那麼將創建一個名為 /tmp/b/c.h 的文件。

The glob-tree rule can be used to find all files below a given directory, making it easy to install entire directory tree.
規則 glob-tree 可以用於查找位於給定目錄之下的所有文件,這使得安裝整個目錄樹變得容易。

Installing into Several Directories 安裝到多個目錄

The alias rule can be used when targets must be installed into several directories:
alias 規則可用於將目標安裝到多個目錄中:

alias install : install-bin install-lib ;
install install-bin : applications : /usr/bin ;
install install-lib : helper : /usr/lib ;

Because the install rule just copies targets, most free features [8] have no effect when used in requirements of the install rule. The only two which matter are dependency and, on Unix, dll-path.
因為 install 規則只是複製目標,在 install 規則的要求中使用的多數自由特性[8]都是沒有作用的。有用的只有兩個,dependency 和 Unix 上的 dll-path.

[Note] Note 說明

(Unix specific). On Unix, executables built with Boost.Build typically contain the list of paths to all used dynamic libraries. For installing, this is not desired, so Boost.Build relinks the executable with an empty list of paths. You can also specify additional paths for installed executables with the dll-path feature.
(專用於Unix)。在 Unix 上,用 Boost.Build 構建的可執行文件通常包含有所有被使用的動態庫的路徑列表。對於安裝而言,這些不是想要的,所以 Boost.Build 重新用空的路徑列表來鏈接可執行文件。你也可以用 dll-path 特性來為安裝的可執行文件指定其它路徑。

Testing 測試

Boost.Build has convenient support for running unit tests. The simplest way is the unit-test rule, which follows the common syntax. For example:
Boost.Build 對於單元測試的運行有很方便的支持。最簡單的方法是 unit-test 規則,它遵守 公用語法。例如:

unit-test helpers_test : helpers_test.cpp helpers ;

The unit-test rule behaves like the exe rule, but after the executable is created it is run. If the executable returns an error code, the build system will also return an error and will try running the executable on the next invocation until it runs successfully. This behaviour ensures that you can't miss a unit test failure.
unit-test 規則很像 exe 規則,不過在可執行文件創建之後將運行它。如果可執行文件返回一個錯誤代碼,構建系統也將返回一個錯誤,並且在下一次調用時再嘗試運行這個可執行文件,直至運行成功。這一行為確保了你不可能遺漏任一個單元測試失敗。

By default, the executable is run directly. Sometimes, it's desirable to run the executable using some helper command. You should use the testing.launcher property to specify the name of the helper command. For example, if you write:
缺省地,可執行文件是直接運行的。有時,你會想要用一些輔助命令來運行這個可執行文件。你可以使用 testing.launcher 屬性來指定輔助命令的名稱。例如,如果你這樣寫:

unit-test helpers_test
: helpers_test.cpp helpers
: <testing.launcher>valgrind ;

The command used to run the executable will be:
則用於運行可執行文件的命令將是:

valgrind bin/$toolset/debug/helpers_test

There are few specialized testing rules, listed below:
有幾個特殊的測試規則,列出如下:

rule compile ( sources : requirements * : target-name ? )
rule compile-fail ( sources : requirements * : target-name ? )
rule link ( sources + : requirements * : target-name ? )
rule link-fail ( sources + : requirements * : target-name ? )

They are are given a list of sources and requirements. If the target name is not provided, the name of the first source file is used instead. The compile* tests try to compile the passed source. The link* rules try to compile and link an application from all the passed sources. The compile and link rules expect that compilation/linking succeeds. The compile-fail and link-fail rules, on the opposite, expect that the compilation/linking fails.
它們被給定一個源列表和要求列表。如果目標名未提供,則用第一個源文件的名字代替。compile* 測試會嘗試編譯傳入的源文件。而 link* 規則則嘗試從所有傳入的源文件編譯並鏈接一個應用程序。compile 規則和 link 規則預期編譯/鏈接可以成功。而 compile-fail 規則和 link-fail 規則則相反,它們預期編譯/鏈接將失敗。

There are two specialized rules for running applications, which are more powerful than the unit-test rule. The run rule has the following signature:
還有兩個運行應用程序的特殊規則,比 unit-test 規則更強大。run 規則具有以下簽名:

rule run ( sources + : args * : input-files * : requirements * : target-name ?
: default-build * )

The rule builds application from the provided sources and runs it, passing args and input-files as command-line arguments. The args parameter is passed verbatim and the values of the input-files parameter are treated as paths relative to containing Jamfile, and are adjusted if bjam is invoked from a different directory. The run-fail rule is identical to the run rule, except that it expects that the run fails.
這個規則從給定的源文件構建應用程序並運行它,傳入 argsinput-files 作為命令行參數。參數 args 是逐個字傳遞的,而 input-files 參數的值則被視為相對於包含 Jamfile 的目錄的路徑,如果你是從另一個目錄調用 bjam 的,則該路徑還將被調整。run-fail 規則和 run 規則相同,除了它預期運行將失敗以外。

All rules described in this section, if executed successfully, create a special manifest file to indicate that the test passed. For the unit-test rule the files is named target-name.passed and for the other rules it is called target-name.test. The run* rules also capture all output from the program, and store it in a file named target-name.output.
在本節所講述的所有規則,如果執行成功,則創建一個特定的證明文件來表示測試通過。對於 unit-test 規則,證明文件被命名為 target-name.passed,而對於其它規則,則名為 target-name.testrun* 規則還會從程序捕獲所有輸出,並將它保存在一個名為 target-name.output 的文件中。

The run and the run-fail rules, if the test passes, automatically delete the linked executable, to save space. This behaviour can be suppressed by passing the --preserve-test-targets command line option.
如果測試通過,run 規則和 run-fail 規則將自動刪除鏈接的可執行文件,以節省空間。這一行為可以通過傳入 --preserve-test-targets 命令行選項來禁止。

It is possible to print the list of all test targets (except for unit-test) declared in your project, by passing the --dump-tests command-line option. The output will consist of lines of the form:
你可以通過傳入 --dump-tests 命令行選項來打印在你的工程中聲明的所有測試目標的列表(除了 unit-test)。輸出將由以下格式的行組成:

boost-test(test-type) path : sources
      

It is possible to process the list of tests, the output of bjam during command run, and the presense / absense of the *.test files created when test passes into human-readable status table of tests. Such processing utilities are not included in Boost.Build.
你可以對測試列表、命令運行期間的 bjam 輸出,以及 *.test 文件的存在與否進行處理,形成人工可讀的測試狀態表。這些處理工具並不包含在 Boost.Build 中。

Custom commands 定制命令

When you use most of main target rules, Boost.Build automatically figures what commands to run and it what order. As soon as you want to use new file types, or support new tools, one approach is to extend Boost.Build to smoothly support them, as documented in the section called 「Extender Manual」. However, if there's a single place where the new tool is used, it might be easier to just explicitly specify the commands to run.
當你使用多數主目標規則時,Boost.Build 會自動推算出運行哪些命令以及以命令的順序。一旦你想使用新的文件類型,或者支持新的工具,一個方法就是,擴展 Boost.Build 以平滑地支持它們,正如在 「擴展手冊」一節 中所介紹的。但是,如果新工具只在一個地方使用,就可以更容易解決,你只要明確指出運行的命令即可。

Three main target rules can be used for that. The make rule allows you to construct a single file from any number of source file, by running a command you specify. The notfile rule allows you to run an arbitrary command, without creating any files. And finaly, the generate rule allows you to describe transformation using Boost.Build's virtual targets. This is higher-level than file names that the make rule operates with and allows you to create more than one target, create differently named targets depending on properties or use more than one tool.
有三個主目標規則可以用於此。make 規則允許你從任意數量的源文件,通過運行你指定的命令,來構造一個文件。notfile 規則允許你運行一個任意命令,而不創建任何文件。最後,generate 規則允許你使用 Boost.Build 的虛擬目標來描述轉換。make 規則所操作的對象比文件名更高級,你可以創建一個以上的目標,可以根據屬性或使用更多工具來創建不同的命名目標。

The make rule is used when you want to create one file from a number of sources using some specific command. The notfile is used to unconditionally run a command.
make 規則在你要使用特定命令從多個源文件創建一個文件時使用。notfile 則用於無條件運行一個命令。

Suppose you want to create file file.out from file file.in by running command in2out. Here is how you would do this in Boost.Build:
假設你想運行命令 in2out 從文件 file.in 創建文件 file.out。以下是你在 Boost.Build 中要做的:

make file.out : file.in : @in2out ;
actions in2out
{
in2out $(<) $(>)
}

If you run bjam and file.out does not exist, Boost.Build will run the in2out command to create that file. For more details on specifying actions, see the section called 「Boost.Jam Language」.
如果你運行 bjamfile.out 不存在,則 Boost.Build 會運行 in2out 命令來創建這一文件。有關特定動作的細節,請見 「Boost.Jam 語言」一節

It could be that you just want to run some command unconditionally, and that command does not create any specific files. For that you can use the notfile rule. For example:
有可能你只是想無條件地運行一些命令,而這些命令並不創建任何特定的文件。你可以使用 notfile 規則。例如:

notfile echo_something : @echo ;
actions echo
{
echo "something"
}

The only difference from the make rule is that the name of the target is not considered a name of a file, so Boost.Build will unconditionally run the action.
它與 make 規則的差別只在於目標的名字不被認為是一個文件名,所以 Boost.Build 將無條件運行該動作。

The generate rule is used when you want to express transformations using Boost.Build's virtual targets, as opposed to just filenames. The generate rule has the standard main target rule signature, but you are required to specify the generating-rule property. The value of the property should be in the form @rule-name, the named rule should have the following signature:
規則 generate 在你想用 Boost.Build 虛擬目標來表示一種轉換時使用。generate 規則具有標準的主目標規則簽名,不過你要指定 generating-rule 屬性。該屬性的值應該形如 @rule-name,這個命名規則應具有以下簽名:

rule generating-rule ( project name : property-set : sources * )

and will be called with an instance of the project-target class, the name of the main target, an instance of the property-set class containing build properties, and the list of instances of the virtual-target class corresponding to sources. The rule must return a list of virtual-target instances. The interface of the virtual-target class can be learned by looking at the build/virtual-target.jam file. The generate example contained in the Boost.Build distribution illustrates how the generate rule can be used.
而且該規則將被以一個 project-target 類的實例、主目標名、一個包含構建屬性的 property-set 類的實例,以及與源目標相對應的 virtual-target 類實例的列表來調用。該規則必須返回一個 virtual-target 實例列表。virtual-target 類的接口可以從 build/virtual-target.jam 文件中看到。包含在 Boost.Build 分發包中的 generate 例子示範了如何使用 generate 規則。

Precompiled Headers 預編譯頭文件

Precompiled headers is a mechanism to speed up compilation by creating a partially processed version of some header files, and then using that version during compilations rather then repeatedly parsing the original headers. Boost.Build supports precompiled headers with gcc and msvc toolsets.
預編譯頭文件是一種加快編譯速度的機制,它創建一些頭文件的部分處理版本,然後在編譯期間使用這些版本,而不用對原始的頭文件進行重複分析。Boost.Build 支持 gcc 和 msvc 工具集的預編譯頭文件。

To use precompiled headers, follow the following steps:
要使用預編譯頭文件,請按以下步驟:

  1. Create a header that includes headers used by your project that you want precompiled. It is better to include only headers that are sufficiently stable — like headers from the compiler and external libraries. Please wrap the header in #ifdef BOOST_BUILD_PCH_ENABLED, so that the potentially expensive inclusion of headers is not done when PCH is not enabled. Include the new header at the top of your source files.
    創建一個頭文件,其中包含你在工程中想要預編譯的頭文件。最好只包含那些足夠穩定的頭文件 — 如來自於編譯器和外部庫的頭文件。將這個新建的頭文件用 #ifdef BOOST_BUILD_PCH_ENABLED 包圍起來,這樣在 PCH 未打開時就不會有頭文件包含的潛在代價。然後,在你的源文件的頂部包含這個新的頭文件。

  2. Declare a new Boost.Build target for the precompiled header and add that precompiled header to the sources of the target whose compilation you want to speed up:
    為預編譯頭文件聲明一個新的 Boost.Build 目標,並將預編譯頭文件增加到你想要加速編譯的目標的源中:

    cpp-pch pch : pch.hpp ;
    exe main : main.cpp pch ;

    You can use the c-pch rule if you want to use the precompiled header in C programs.
    如果你想在 C 程序中使用預編譯頭文件,可以使用 c-pch 規則。

The pch example in Boost.Build distribution can be used as reference.
在 Boost.Build 分發包中的 pch 例子可以作為參考。

Please note the following:
請注意以下事項:

  • The inclusion of the precompiled header must be the first thing in a source file, before any code or preprocessor directives.
    預編譯頭文件的包含必須是源文件中的第一件事,在任何代碼或預處理指令之前。

  • The build properties used to compile the source files and the precompiled header must be the same. Consider using project requirements to assure this.
    用於編譯源文件和預編譯頭文件的構建屬性必須一致。可以考慮使用工程要求來確保這一點。

  • Precompiled headers must be used purely as a way to improve compilation time, not to save the number of #include statements. If a source file needs to include some header, explicitly include it in the source file, even if the same header is included from the precompiled header. This makes sure that your project will build even if precompiled headers are not supported.
    預編譯頭文件必須純粹用作一種減少編譯時間的方法,而不是為了節約 #include 語句的數量。如果一個源文件需要包含某些頭文件,就明確地在源文件中包含它,即使這些頭文件已經在預編譯頭文件中包含。這樣可以確保即使在不支持預編譯頭文件的情況下,你的工程也可以正確構建。

  • On the gcc compiler, the name of the header being precompiled must be equal to the name of the cpp-pch target. This is a gcc requirement.
    在 gcc 編譯器上,被預編譯的頭文件名必須與 cpp-pch 目標的名稱相同。這是 gcc 的一個要求。

  • Prior to version 4.2, the gcc compiler did not allow anonymous namespaces in precompiled headers, which limits their utility. See the bug report for details.
    在版本 4.2 之前,gcc 編譯器不允許在預編譯頭文件中有匿名名字空間,這限制了它的工具。詳細請見 缺陷報告

Generated headers 生成頭文件

Usually, Boost.Build handles implicit dependendies completely automatically. For example, for C++ files, all #include statements are found and handled. The only aspect where user help might be needed is implicit dependency on generated files.
通常,Boost.Build 完全自動地處理隱式的依賴關係。例如,對於 C++ 文件,所有 #include 語句將被查找和處理。唯一可能需要用戶幫助的是,在生成頭文件上的隱式依賴關係。

By default, Boost.Build handles such dependencies within one main target. For example, assume that main target "app" has two sources, "app.cpp" and "parser.y". The latter source is converted into "parser.c" and "parser.h". Then, if "app.cpp" includes "parser.h", Boost.Build will detect this dependency. Moreover, since "parser.h" will be generated into a build directory, the path to that directory will automatically added to include path.
缺 省情況下,Boost.Build 在一個主目標的內部處理這類依賴關係。例如,假設主目標 "app" 有兩個源:"app.cpp" 和 "parser.y"。後一個源被轉化為 "parser.c" 和 "parser.h"。那麼,如果 "app.cpp" 包含了 "parser.h",則 Boost.Build 將檢測到這個依賴關係。此外,因為 "parser.h" 將被生成到一個構建目錄中,所以該目錄的路徑將被自動加入到包含路徑中。

Making this mechanism work across main target boundaries is possible, but imposes certain overhead. For that reason, if there's implicit dependency on files from other main targets, the <implicit-dependency> [ link ] feature must be used, for example:
讓這種機制跨主目標工作也是可以的,不過需要很大的代價。為此,如果一個文件存在對其它主目標的隱式依賴關係,必須使用 <implicit-dependency> [ link ] 特性,例如:

lib parser : parser.y ;
exe app : app.cpp : <implicit-dependency>parser ;

The above example tells the build system that when scanning all sources of "app" for implicit-dependencies, it should consider targets from "parser" as potential dependencies.
上述例子告訴構建系統,在掃瞄 "app" 的所有源文件的隱式依賴關係時,應該將來自 "parser" 的目標也作為潛在的依賴關係考慮。



[8] see the definition of "free" in the section called 「Feature Attributes」.
請見 「特性的屬性」一節 中關於"自由"的定義。


PrevUpHomeNext