Monday, December 22, 2008

由 configure 所產生的檔案

3.2 Files generated by configure / 由 configure 所產生的檔案

After you have invoked `configure', you will discover a number of generated files in your build tree. The build directory structure created by `configure' and the number of files will vary from package to package. Each of the generated files are described below and their relationships are shown in C. Generated File Dependencies:

在執行 `configure' 之後,你會發現有一些檔案在你的建置資料夾中被產生出來。在不同的套件中,由 `configure' 在建置資料夾所建立的資料夾結構以及檔案的數量會稍有不同。以下簡述所產生的檔案的功能,這些檔案間的關係則在 C. 所產出檔案間的相依性中描述:

`config.cache'

`configure' can cache the results of system tests that have been performed to speed up subsequent tests. This file contains the cache data and is a plain text file that can be hand-modified or removed if desired.

`configure' 可以藉由儲存系統測試程式的結果,來縮短後續測試所耗的時間。所儲存的快取資訊會以純文字的形式存放在這個檔案中,如果有需要的話,可以手動編修或移除這個檔案。

`config.log'

As `configure' runs, it outputs a message describing each test it performs and the result of each test. There is substantially more output produced by the shell and utilities that `configure' invokes, but it is hidden from the user to keep the output understandable. The output is instead redirected to `config.log'. This file is the first place to look when `configure' goes hay-wire or a test produces a nonsense result. A common scenario is that `configure', when run on a Solaris system, will tell you that it was unable to find a working C compiler. An examination of `config.log' will show that Solaris' default `/usr/ucb/cc' is a program that informs the user that the optional C compiler is not installed.

在 `configure' 執行時,會印出一些訊息來描述正在執行的測試,以及測試的結果。實際上,由 shell 以及 `configure' 所執行的工具程式會送出更多的訊息,但是為了讓印到輸出畫面的資訊較容易被使用者理解,這些額外的訊息不會被送到輸出畫面上。所有額外的訊息會被導向到 `config.log' 檔案中,當 `configure' 程式作出怪異的行為或是產生莫名奇妙的測試結果時,這個檔案是第一個該看看的地方。一個常見的例子是,在 Solaris 系統上執行 `configure' 時顯示找不到可以使用的編譯器的訊息。在檢視 `config.log' 後就會發現,在 Solaris 上所預先安裝的 `/usr/ucb/cc' 是一個顯示 C 編譯器尚未安裝的程式,並非是一個可用的編譯器。

`config.status'

`configure' generates a shell script called `config.status' that may be used to recreate the current configuration. That is, all generated files will be regenerated. This script can also be used to re-run `configure' if the `--recheck' option is given.

`configure' 會產生一個稱為 `config.status' 的 shell 指令稿,這個指令稿可以用來重新建立目前的組態環境。換言之,這個指令稿會重新產生所有 `configure' 所產生的檔案。另外,只要在執行時給定 `--recheck' 的選項,也可以透過這個指令稿來重新執行 `configure' 程式。

`config.h'

Many packages that use `configure' are written in C or C++. Some of the tests that `configure' runs involve examining variability in the C and C++ programming languages and implementations thereof. So that source code can programmatically deal with these differences, #define preprocessor directives can be optionally placed in a config header, usually called `config.h', as `configure' runs. Source files may then include the `config.h' file and act accordingly:

許多使用 `configure' 的套件是由 C 或 C++ 所撰寫的,有許多 `configure' 所執行的測試正是用來檢驗執行建置程序的 C/C++ 編譯器所提供的語言實作細節,以及檢驗諸如函式庫的版本或存在與否等編譯環境所提供支援的程度。測試所得的結果可以由 #define 前置處理指引的方式表現出來,通常會存放到檔名為 `config.h ' 的設定標頭檔中。在程式的原始碼中就可以引入 `config.h' 並且針對各個狀況來撰寫特定的程式碼片段分別處理,比如:

#if HAVE_CONFIG_H # include #endif /* HAVE_CONFIG_H */ #if HAVE_UNISTD_H # include #endif /* HAVE_UNISTD_H */

We recommend always using a config header.

我們建議所有的專案都應該使用設定標頭檔

`Makefile'

One of the common functions of `configure' is to generate `Makefile's and other files. As it has been stressed, a `Makefile' is just a file often generated by `configure' from a corresponding input file (usually called `Makefile.in'). The following section will describe how you can use make to process this `Makefile'. There are other cases where generating files in this way can be helpful. For instance, a Java developer might wish to make use of a `defs.java' file generated from `defs.java.in'.

其中一個 `configure' 常被用到的功能是產生 `Makefile' 檔,或是其他有用的檔案。正如同之前所提到的,一個 `Makefile' 檔通常會是一個由 `configure' 分析一個對應的輸入檔 (通常會是 `Makefile.in') 所產生,接下來的章節會描述如何執行 make 來使用 `Makefile' 檔案。類似的方法也可以用在其他場合來產生有用的檔案,比如,一個 Java 程式設計師可能會想從一個 `defs.java.in' 來產生出 `defs.java' 檔。

進行組態

3.1 Configuring / 進行組態

A `configure' script takes a large number of command line options. The set of options can vary from one package to the next, although a number of basic options are always present. The available options can be discovered by running `configure' with the `--help' option. Although many of these options are esoteric, it's worthwhile knowing of their existence when configuring packages with special installation requirements. Each option will be briefly described below:

`configure' 指令稿接受一大堆的命令列選項,不同的套件所能夠接受的選項會不太一樣,有一些基本的選項在所有套件中都可以找到,各套件所可以接受的選項可以透過執行 `configure' 時加上 `--help' 選項取得。雖然有不少的選項通常不會被用到,但有特殊的需求時,知道一下這些選項的存在會很有幫助。以下簡述在所有套件中都能找到的基本選項:

`--cache-file=file'

`configure' runs tests on your system to determine the availability of features (or bugs!). The results of these tests can be stored in a cache file to speed up subsequent invocations of configure. The presence of a well primed cache file makes a big improvement when configuring a complex tree which has `configure' scripts in each subtree.

`configure' 會在你的系統執行測試程式以檢查系統所能提供的功能 (或是系統的錯誤與漏洞),測試的結果會被存在一個快取檔案中,以縮短未來執行 configure 所耗用的時間。一些複雜的專案的原始碼樹在每個子資掉夾都有各自的 `configure' 指令稿,在這個情況下,可以透過留置快取檔案來大幅縮減組態所耗用的時間。

`--help'

Outputs a help message. Even experienced users of `configure' need to use `--help' occasionally, as complex projects will include additional options for per-project configuration. For example, `configure' in the GCC package allows you to control whether the GNU assembler will be built and used by GCC in preference to a vendor's assembler.

輸出說明訊息,因為一些複雜的專案會在 `configure' 中加入一些額外的選項,因此即使是有經驗的使用者偶而也需要使用 `--help' 選項。比如,在 GCC 套件的 `configure' 中就可以讓你控制是不是要建置 GNU 組譯器並讓 GCC 使用,或是要使用其他廠商所提供的組譯器。

`--no-create'

One of the primary functions of `configure' is to generate output files. This option prevents `configure' from generating such output files. You can think of this as a kind of dry run, although the cache will still be modified.

`configure' 的主要功能之一是產生用來建置套件的檔案,給定這個選項會讓 `configure' 不產生那些檔案,但快取檔仍會被修改,你可以將這個功能視為進行測試用的功能。

`--quiet'
`--silent'

As `configure' runs its tests, it outputs brief messages telling the user what the script is doing. This was done because `configure' can be slow. If there was no such output, the user would be left wondering what is happening. By using this option, you too can be left wondering!

在 `configure' 進行測試時,他會輸出一些簡單的訊息告訴使用者指令稿正在做什麼。因為 `configure' 的執行會花很多時間,如果沒有輸出這些東西,使用者只能在旁邊瞎猜現在的狀況。只要給定了這個選項,你就可以重新加入大家來瞎猜的行列。

`--version'

Prints the version of Autoconf that was used to generate the `configure' script.

印出產生這個 `configure' 指令稿的 Autoconf 版本。

`--prefix=prefix'

The --prefix option is one of the most frequently used. If generated `Makefile's choose to observe the argument you pass with this option, it is possible to entirely relocate the architecture-independent portion of a package when it is installed. For example, when installing a package like Emacs, the following command line will cause the Emacs Lisp files to be installed in `/opt/gnu/share':

--prefix 是經常被使用的一個選項,如果所產生的 `Makefile' 會嚴格遵守你隨著這個選項所傳入的參數,那麼就可以把整個套件中與硬體平台無關的部分安裝到預設路徑外的地方去。比如說,利用以下的指令安裝 Emacs 套件,會讓 Emacs 的 Lisp 檔案安裝到 `/opt/gnu/share' 之下:

$ ./configure --prefix=/opt/gnu

It is important to stress that this behavior is dependent on the generated files making use of this information. For developers writing these files, Automake simplifies this process a great deal. Automake is introduced in 7. Introducing GNU Automake.

很重要的一點是,所產生的檔案必須要會使用這項資訊。對於撰寫設定檔的開發者,使用 Automake 可以大幅簡化這個步驟,我們會在 7. GNU Automake 簡介中介紹 Automake。

`--exec-prefix=eprefix'

Similar to `--prefix', except that it sets the location of installed files which are architecture-dependent. The compiled `emacs' binary is such a file. If this option is not given, the default `exec-prefix' value inserted into generated files is set to the same value as the `prefix'.

這個選項與 `--prefix' 類似,但所指定的路徑位址是給與硬體平台相關的檔案使用的,比如所編譯出來的 `emacs' 執行檔。如果這個選項沒有給定,預設的 `exec-prefix' 值會被設定為 `prefix' 的值。

`--bindir=dir'

Specifies the location of installed binary files. While there may be other generated files which are binary in nature, binary files here are defined to be programs that are run directly by users.

給定要安裝執行檔的路徑位置,套件建置可能會產生很多各式各樣的執行檔,但這個選項所指的執行檔僅包含會被使用者直接執行的程式。

`--sbindir=dir'

Specifies the location of installed superuser binary files. These are programs which are usually only run by the superuser.

給定要安裝管理員用執行檔的路徑位置,這些程式通常只由系統管理員使用。

`--libexecdir=dir'

Specifies the location of installed executable support files. Contrasted with `binary files', these files are never run directly by users, but may be executed by the binary files mentioned above.

給定要安裝可執行的支援檔案的路徑位置,與上面所提及的 `執行檔' 所不同,被這個選項所指的檔案不會被使用者直接的執行,但可能會被上面所說的執行檔所執行。

`--datadir=dir'

Specifies the location of generic data files.

給定要安裝一般性的資料檔的路徑位置。

`--sysconfdir=dir'

Specifies the location of read-only data used on a single machine.

給定在單一機器上的設定資料的路徑位置,這些設定資料對一般使用者是唯讀的,且一般而言不同的機器會有不同的設定。

`--sharedstatedir=dir'

Specifies the location of data which may be modified, and which may be shared across several machines.

給定共用可讀寫資料的路徑位置,這些資料檔可以被使用者所更改,並且可能會在數臺不同的機器所共享。

`--localstatedir=dir'

Specifies the location of data which may be modified, but which is specific to a single machine.

給定專屬可讀寫資料的路徑位置,這些資料檔可以被使用者所更改,但只會由一臺機器存取使用。

`--libdir=dir'

Specifies where object code library should be installed.

給定安裝函式庫目的碼的路徑位置。

`--includedir=dir'

Specifies where C header files should be installed. Header files for other languages such as C++ may be installed here also.

給定安裝 C 標頭檔案的路徑位置,如 C++ 等其他語言所使用的標頭檔也可能會被安裝在這個選項所指定的路徑下。

`--oldincludedir=dir'

Specifies where C header files should be installed for compilers other than GCC.

給定安裝給非 GCC 的其他編譯器所使用的 C 標頭檔案的路徑位置。

`--infodir=dir'

Specifies where Info format documentation files should be installed. Info is the documentation format used by the GNU project.

給定安裝 Info 格式文件檔的路徑位置,Info 是被 GNU 計畫所使用的文件檔案格式。

`--mandir=dir'

Specifies where manual pages should be installed.

給定安裝使用手冊的路徑位置。

`--srcdir=dir'

This option does not affect installation. Instead, it tells `configure' where the source files may be found. It is normally not necessary to specify this, since the configure script is normally in the same directory as the source files.

這個選項不會影響到安裝,但可以裡用這個選項告訴 `configure' 套件原始碼所在位置。通常並不需要設定這個選項,因為 configure 指令稿通常會與原始碼放在一樣的資料夾內。

`--program-prefix=prefix'

Specifies a prefix which should be added to the name of a program when installing it. For example, using `--program-prefix=g' when configuring a program normally named `tar' will cause the installed program to be named `gtar' instead. As with the other installation options, this `configure' option only works if it is utilized by the `Makefile.in' file.

給定要在安裝個別執行檔時接到預設程式檔名之前的前置字串,比如,在組態 tar 套件時使用 `--program-prefix=g' 會讓正常情況下稱為 `tar' 的程式被更名為 `gtar'。就像其他的安裝選項,這個 `configure' 選項只在 `Makefile.in' 有使用到這個設定時才有效。

`--program-suffix=suffix'

Specifies a suffix which should be appended to the name of a program when installing it.

給定要在安裝個別執行檔時接到預設程式檔名之後的後置字串。

`--program-transform-name=program'

Here, program is a sed script. When a program is installed, its name will be run through `sed -e script' to produce the installed name.

在這裡的 program 是一個 sed 指令稿,在安裝個別執行檔時,預設的執行檔名會送進 `sed -e script' 以產生各執行檔的檔名。

`--build=build'

Specifies the type of system on which the package will be built. If not specified, the default will be the same configuration name as the host.

給定執行套件建置的系統平台名稱,如果這個選項沒有給定,預設將會使用與 host 相同的值。

`--host=host'

Specifies the type of system on which the package will run--or be hosted. If not specified, the host triplet is determined by executing `config.guess'.

給定將執行或安裝套件程式的系統平台名稱,如果這個選項沒有給定,預設將會執行 `config.guess' 來取得系統平台名稱。

`--target=target'

Specifies the type of system which the package is to be targeted to. This makes the most sense in the context of programming language tools like compilers and assemblers. If not specified, the default will be the same configuration name as the host.

給定套件的目標系統平台,這個選項在建置如編譯器或組譯器等程式語言工具時會較有意義。如果這個選項沒有給定,預設將會使用與 host 相同的值。

`--disable-feature'

Some packages may choose to provide compile-time configurability for large-scale options such as using the Kerberos authentication system or an experimental compiler optimization pass. If the default is to provide such features, they may be disabled with `--disable-feature', where feature is the feature's designated name. For example:

有些套件會讓使用者在編譯時期決定是不是要將像 Kerberos 認証系統之類較龐大的額外功能,或是實驗性的編譯時期最佳化選項納入建置。如果這些額外的功能預設是開啟的,那麼可以利用 `--disable-feature' 來將他們關閉,在這邊 feature 應代換為功能的代稱,例如:

$ ./configure --disable-gui
`--enable-feature[=arg]'

Conversely, some packages may provide features which are disabled by default. To enable them, use `--enable-feature', where feature is the feature's designated name. A feature may accept an optional argument. For example:

相反的,有些套件會將額外的功能預設為關閉。使用 `--enable-feature' 可以啟用這些額外的功能,在這邊 feature 應代換為功能的代稱。有些功能可以接受額外的參數,例如:

$ ./configure --enable-buffers=128

Using `--enable-feature=no' is synonymous with `--disable-feature', described above.

使用 `--enable-feature=no' 跟使用上面提到的 `--disable-feature' 會有相同的效果。

`--with-package[=arg]'

In the free software community, there is a healthy tendency to reuse existing packages and libraries where possible. At the time when a source tree is configured by `configure', it is possible to provide hints about other installed packages. For example, the BLT widget toolkit relies on Tcl and Tk. To configure BLT, it may be necessary to give `configure' some hints about where you have installed Tcl and Tk:

儘可能利用既有的套件與函式庫是自由軟體社群中一項健康的潮流,當利用 `configure' 對原始碼樹進行組態時,這個選項可以用來提供一些系統既有套件的資訊。例如 BLT widget toolkit 需要 Tcl 與 Tk 事先安裝在系統上,在組態時可能需要給 `configure' 一些關於 Tcl 與 Tk 安裝位置的提示:

$ ./configure --with-tcl=/usr/local --with-tk=/usr/local

Using `--with-package=no' is synonymous with `--without-package' which is described below.

使用 `--with-package=no' 與使用將在下面提到的 `--without-package' 會有相同的效果。

`--without-package'

Sometimes you may not want your package to inter-operate with some pre-existing package installed on your system. For example, you might not want your new compiler to use GNU ld. You can prevent this by using an option such as:

有時候你可能會不希望你建置的套件程式去使用系統內已安裝的套件,比如說,你可能不想讓新的編譯器使用 GNU ld 來連結程式。你可以用像下面這樣的選項來達到這個目的:

$ ./configure --without-gnu-ld
`--x-includes=dir'

This option is really a specific instance of a `--with-package' option. At the time when Autoconf was initially being developed, it was common to use `configure' to build programs to run on the X Window System as an alternative to Imake. The `--x-includes' option provides a way to guide the configure script to the directory containing the X11 header files.

這個選項其實是 `--with-package' 的一個特例。在 Autoconf 的開發初期, `configure' 常被用來作為 Imake 外的另一個建置 X Window System 應用程式的選擇。透過 `--x-includes' 選項,使用者可以告知 configure 指令稿 X11 的標頭檔所在的資料夾。

`--x-libraries=dir'

Similarly, the --x-libraries option provides a way to guide `configure' to the directory containing the X11 libraries.

與前項相似,透過 `--x-libraries' 選項,使用者可以告知 configure 指令稿 X11 函式庫檔所在的資料夾。

It is unnecessary, and often undesirable, to run `configure' from within the source tree. Instead, a well-written `Makefile' generated by `configure' will be able to build packages whose source files reside in another tree. The advantages of building derived files in a separate tree to the source code are fairly obvious: the derived files, such as object files, would clutter the source tree. This would also make it impossible to build those same object files on a different system or with a different configuration. Instead, it is recommended to use three trees: a source tree, a build tree and an install tree. Here is a closing example of how to build the GNU malloc package in this way:

在原始碼樹中執行 `configure' 是不必要也不被建議的,到原始碼樹之外的資料夾中執行 `configure' 來產生 `Makefile' 檔案並建置套件會比較好。在與原始碼樹分離的資料夾建置套件的優點是顯而易見的: 諸如目的檔等由建置程序所產生的檔案,將不會混雜到原始碼樹之中。此外,也可以在與原始碼樹分離的數個資料夾中分別進行建置動作,如此一來能讓一套原始碼可同時用來建置出給不同系統使用的執行檔,或是針對不同的組態分別進行建置作業。因此,我們建議的做法是在每次的建置作業中使用到三個不同的資料夾: 原始碼樹建置資料夾以及安裝資料夾。以下是一個使用這個方法來建置 GNU malloc 套件的例子:

$ gtar zxf mmalloc-1.0.tar.gz $ mkdir build && cd build $ ../mmalloc-1.0/configure creating cache ./config.cache checking for gcc... gcc checking whether the C compiler (gcc ) works... yes checking whether the C compiler (gcc ) is a cross-compiler... no checking whether we are using GNU C... yes checking whether gcc accepts -g... yes checking for a BSD compatible install... /usr/bin/install -c checking host system type... i586-pc-linux-gnu checking build system type... i586-pc-linux-gnu checking for ar... ar checking for ranlib... ranlib checking how to run the C preprocessor... gcc -E checking for unistd.h... yes checking for getpagesize... yes checking for working mmap... yes checking for limits.h... yes checking for stddef.h... yes updating cache ../config.cache creating ./config.status

Now that this build tree is configured, it is possible to go on and build the package and install it into the default location of `/usr/local':

現在,建置資料夾已經組態完成,接下來就可以使用以下指令來進行建置作業,並將成品安裝到預設的安裝資料夾 `/usr/local' 中:

$ make all && make install