References:

我們將采用out-of-source外部構(gòu)建，約定的構(gòu)建目錄是工程目錄下的build目錄。

本小節(jié)的任務是讓前面的Hello World更像一個工程，我們需要作的是：

• 為工程添加一個子目錄src，用來放置工程源代碼;
• 添加一個子目錄doc，用來放置這個工程的文檔hello.txt
• 在工程目錄添加文本文件COPYRIGHT, README；
• 在工程目錄添加一個runhello.sh腳本，用來調(diào)用hello二進制
• 將構(gòu)建后的目標文件放入構(gòu)建目錄的bin子目錄；
• 最終安裝這些文件：將hello二進制與runhello.sh安裝至/usr/bin，將doc目錄的內(nèi)容以及COPYRIGHT/README安裝到/usr/share/doc/cmake/t2，

1，準備工作：

在/home/ccj/CMakeDemo/目錄下建立t2目錄。將t1工程的main.c和CMakeLists.txt拷貝到t2目錄中。

2，添加子目錄src：

mkdir src

mv main.c src

現(xiàn)在的工程看起來是這個樣子：

上一節(jié)我們提到，需要為任何子目錄建立一個CMakeLists.txt，

進入子目錄src，編寫CMakeLists.txt如下：

# t2/src/CMakeLists.txt

ADD_EXECUTABLE(hello main.c)

將t2工程的CMakeLists.txt修改為：

# t2/CMakeLists.txt

PROJECT(HELLO)

ADD_SUBDIRECTORY(src bin)

然后建立build目錄，進入build目錄進行外部編譯。

cmake ..

make

結(jié)果如下：

構(gòu)建完成后，你會發(fā)現(xiàn)生成的目標文件hello位于build/bin目錄中:

語法解釋：

ADD_SUBDIRECTORY指令：

ADD_SUBDIRECTORY(source_dir [binary_dir] [EXCLUDE_FROM_ALL])

這個指令用于向當前工程添加存放源文件的子目錄，并可以指定中間二進制和目標二進制存放的位置。EXCLUDE_FROM_ALL參數(shù)的含義是將這個目錄從編譯過程中排除，比如，工程的example，可能就需要工程構(gòu)建完成后，再進入example目錄單獨進行構(gòu)建(當然，你也可以通過定義依賴來解決此類問題)。

上面的例子定義了將src子目錄加入工程，并指定編譯輸出(包含編譯中間結(jié)果)路徑為bin目錄。如果不進行bin目錄的指定，那么編譯結(jié)果(包括中間結(jié)果)都將存放在build/src目錄(即在build下自動創(chuàng)建一個src目錄，這個目錄跟原有的src目錄對應)，指定bin目錄后，相當于在編譯時將src重命名為bin，所有的中間結(jié)果和目標二進制都將存放在build/bin目錄。

這里需要提一下的是SUBDIRS指令，使用方法是：SUBDIRS(dir1 dir2...)，但是這個指令已經(jīng)不推薦使用。它可以一次添加多個子目錄，并且，即使外部編譯，子目錄體系仍然會被保存。如果我們在上面的例子中將ADD_SUBDIRECTORY (src bin)修改為SUBDIRS(src)。那么在build目錄中將出現(xiàn)一個src目錄，生成的目標代碼hello將存放在src目錄中。

3，換個地方保存目標二進制文件

不論是SUBDIRS還是ADD_SUBDIRECTORY指令(不論是否指定編譯輸出目錄)，我們都可以通過SET指令重新定義EXECUTABLE_OUTPUT_PATH和LIBRARY_OUTPUT_PATH變量來指定最終的目標二進制的位置（指最終生成的hello或者最終的共享庫，不包含編譯生成的中間文件）

SET(EXECUTABLE_OUTPUT_PATH ${PROJECT_BINARY_DIR}/bin)

SET(LIBRARY_OUTPUT_PATH ${PROJECT_BINARY_DIR}/lib)

在上一個blog中，我們提到了<projectname>_BINARY_DIR和PROJECT_BINARY_DIR變量，它們指的是編譯發(fā)生的當前目錄，如果是內(nèi)部編譯(in-source build)， PROJECT_BINARY_DIR =PROJECT_SOURCE_DIR =工程代碼所在目錄，i.e., /home/ccj/CMakeDemo/t2;如果是外部編譯(out-of-source build)，PROJECT_BINARY_DIR指的是外部編譯所在目錄，也就是本例中的/home/ccj/CMakeDemo/t2/build目錄。所以，上面兩個指令分別定義了：

可執(zhí)行二進制的輸出路徑為build/bin，以及庫的輸出路徑為build/lib.

本節(jié)我們沒有提到共享庫和靜態(tài)庫的構(gòu)建，所以，你可以不考慮第二條指令。但有個問題，我們應該把這兩條指令寫在工程的CMakeLists.txt里，還是src目錄下的 CMakeLists.txt里呢？把握一個簡單的原則，在哪里ADD_EXECUTABLE 或 ADD_LIBRARY，如果需要改變目標存放路徑，就在哪里加入上述的定義。

在這個例子里，當然就是指 src下的CMakeLists.txt了，即：

# src/CMakeLists.txt

ADD_EXECUTABLE(hello main.cpp)

SET(EXECUTABLE_OUTPUT_PATH ${PROJECT_BINARY_DIR}/)

Run make之后，會將binary file hello放在 t2/build下，即t2/build/hello

我們可以改變一下目錄, 如下：

# src/CMakeLists.txt

ADD_EXECUTABLE(hello main.cpp)

SET(EXECUTABLE_OUTPUT_PATH ${PROJECT_BINARY_DIR}/bin)

Run make之后，會將binary file hello放在 t2/build/bin下，即t2/build/bin/hello

4，如何安裝。

安裝的需要有兩種，一種是從代碼編譯后直接make install安裝，另一種是打包時的指定目錄安裝。

所以，即使最簡單的手工編寫的Makefile，看起來也是這個樣子的：

DESTDIR=

install:

mkdir -p $(DESTDIR)/usr/bin

install -m 755 hello $(DESTDIR)/usr/bin

（Note： -m 755 表示文件的權(quán)限為 -rwxr--r--, 可參考linux的chmod 指令，詳見下圖：

）

言歸正傳，回到CMake，你可以通過:

make install

將hello直接安裝到/usr/bin目錄，也可以通過make installDESTDIR=/tmp/test ，將其安裝在/tmp/test/usr/bin目錄，打包時這個方式經(jīng)常被使用。

稍微復雜一點的是還需要定義PREFIX，一般autotools工程，會運行這樣的指令:

./configure --prefix=/usr或者 ./configure --prefix=/usr/local 來指定PREFIX。

比如上面的Makefile就可以改寫成:

DESTDIR=

PREFIX=/usr

install:

mkdir -p $(DESTDIR)/$(PREFIX)/bin

install -m 755 hello $(DESTDIR)/$(PREFIX)/bin

那么我們的HelloWorld應該怎么進行安裝呢？這里需要引入一個新的cmake 中的指令 INSTALL和一個非常有用的變量CMAKE_INSTALL_PREFIX。

CMAKE_INSTALL_PREFIX變量類似于configure腳本的 –prefix，常見的使用方法看起來是這個樣子：

cmake -DCMAKE_INSTALL_PREFIX=/usr .

INSTALL指令用于定義安裝規(guī)則，安裝的內(nèi)容可以包括目標二進制、動態(tài)庫、靜態(tài)庫以及文件、目錄、腳本等。INSTALL指令包含了各種安裝類型，我們需要一個一個地加以解釋：

1）目標文件的安裝：

INSTALL(TARGETS targets...

[ [ARCHIVE|LIBRARY|RUNTIME]

[DESTINATION <dir>]

[PERMISSIONS permissions...]

[CONFIGURATIONS [Debug|Release|...]]

[COMPONENT <component>]

[OPTIONAL]

] [...])

參數(shù)中的TARGETS后面跟的就是我們通過ADD_EXECUTABLE或者ADD_LIBRARY定義的目標文件，可能是可執(zhí)行二進制、動態(tài)庫、靜態(tài)庫。目標類型也就相對應的有三種，ARCHIVE特指靜態(tài)庫，LIBRARY特指動態(tài)庫，RUNTIME特指可執(zhí)行目標二進制。DESTINATION定義了安裝的路徑，如果路徑以/開頭，那么指的是絕對路徑，這時候CMAKE_INSTALL_PREFIX其實就無效了。如果你希望使用CMAKE_INSTALL_PREFIX 來定義安裝路徑，就要寫成相對路徑，即不要以 “/ ”開頭，那么安裝后的路徑就是：${CMAKE_INSTALL_PREFIX}/<DESTINATION定義的路徑>；

舉個簡單的例子：

INSTALL(TARGETS myrun mylib mystaticlib

RUNTIME DESTINATION bin

LIBRARY DESTINATION lib

ARCHIVE DESTINATION libstatic

)

上面的例子會將：

可執(zhí)行二進制myrun安裝到${CMAKE_INSTALL_PREFIX}/bin目錄;

動態(tài)庫libmylib安裝到${CMAKE_INSTALL_PREFIX}/lib目錄;

靜態(tài)庫libmystaticlib安裝到${CMAKE_INSTALL_PREFIX}/libstatic目錄;

特別注意的是你不需要關心TARGETS具體生成的路徑，只需要寫上TARGETS名稱就可以了，即只寫"myrun" "mylib" "mystaticlib",而不用加具體的路徑。

2）普通文件的安裝：

INSTALL(FILES files... DESTINATION <dir>

[PERMISSIONS permissions...]

[CONFIGURATIONS [Debug|Release|...]]

[COMPONENT <component>]

[RENAME <name>] [OPTIONAL])

可用于安裝一般文件，并可以指定訪問權(quán)限，文件名是此指令所在路徑下的相對路徑。

如果默認不定義權(quán)限PERMISSIONS，安裝后的權(quán)限為：

OWNER_WRITE, OWNER_READ, GROUP_READ,和WORLD_READ，即644 (-rw-r--r--)權(quán)限。

3）非目標文件的可執(zhí)行程序安裝(比如腳本之類)：

INSTALL(PROGRAMS files... DESTINATION <dir>

[PERMISSIONS permissions...]

[CONFIGURATIONS [Debug|Release|...]]

[COMPONENT <component>]

[RENAME <name>] [OPTIONAL])

跟上面的FILES指令使用方法一樣，唯一的不同是安裝后權(quán)限為:

OWNER_EXECUTE, GROUP_EXECUTE, 和WORLD_EXECUTE，即755 (-rwxrw-rw-)權(quán)限

4）目錄的安裝：

INSTALL(DIRECTORY dirs... DESTINATION <dir>

[FILE_PERMISSIONS permissions...]

[DIRECTORY_PERMISSIONS permissions...]

[USE_SOURCE_PERMISSIONS]

[CONFIGURATIONS [Debug|Release|...]]

[COMPONENT <component>]

[[PATTERN <pattern> | REGEX <regex>]

[EXCLUDE] [PERMISSIONS permissions...]] [...])

這里主要介紹其中的DIRECTORY、PATTERN以及PERMISSIONS參數(shù)。

DIRECTORY后面連接的是所在Source目錄的相對路徑，但務必注意：abc和abc/是有很大區(qū)別的。如果目錄名不以/結(jié)尾，那么這個目錄將被安裝為目標路徑下的abc；

如果目錄名以/結(jié)尾，代表將這個目錄中的內(nèi)容安裝到目標路徑，但不包括這個目錄本身。

PATTERN用于使用正則表達式進行過濾，PERMISSIONS用于指定PATTERN過濾后的文件權(quán)限。

我們來看一個例子:

INSTALL(DIRECTORY icons scripts/ DESTINATION share/myproj

PATTERN "CVS" EXCLUDE

PATTERN "scripts/*"

PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_EXECUTE GROUP_READ)

這條指令的執(zhí)行結(jié)果是：

將icons目錄安裝到 <prefix>/share/myproj，將scripts/中的內(nèi)容安裝到<prefix>/share/myproj 不包含目錄名為CVS的目錄，對于scripts/*文件指定權(quán)限為 OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_EXECUTE GROUP_READ.

安裝時CMAKE腳本的執(zhí)行：

INSTALL([[SCRIPT <file>] [CODE <code>]] [...])

SCRIPT參數(shù)用于在安裝時調(diào)用cmake腳本文件（也就是<abc>.cmake文件）

CODE參數(shù)用于執(zhí)行CMAKE指令，必須以雙引號括起來。比如：

INSTALL(CODE "MESSAGE(/"Sample install message./")")

安裝還有幾個被標記為過時的指令，比如INSTALL_FILES等，這些指令已經(jīng)不再推薦使用，所以，這里就不再贅述了。

下面，我們就來改寫我們的工程文件，讓他來支持各種文件的安裝，并且，我們要使用

CMAKE_INSTALL_PREFIX指令。

5，修改Helloworld支持安裝

在本節(jié)開頭我們定義了本節(jié)的任務如下：

• 為工程添加一個子目錄src，用來存儲源代碼;
• 添加一個子目錄doc，用來存儲這個工程的文檔hello.txt
• 在工程目錄添加文本文件COPYRIGHT, README；
• 在工程目錄添加一個runhello.sh腳本，用來調(diào)用hello二進制
• 將構(gòu)建后的目標文件放入構(gòu)建目錄的bin子目錄；
• 最終安裝這些文件：將hello二進制與runhello.sh安裝至/<prefix>/bin，將doc目錄中的hello.txt以及COPYRIGHT/README安裝到/<prefix>/share/doc/cmake/t2，

1)首先我們先添加上訴文件:

• 添加doc目錄及文件:

cd /backup/cmake/t2

mkdir doc

vimdoc/hello.txt # 隨便填寫一些內(nèi)容并保存

• 在工程目錄添加runhello.sh腳本，用來調(diào)用hello二進制，所以其內(nèi)容為：hello
• 添加工程目錄中的COPYRIGHT和README: touch COPYRIGHT; touch README

2)下面改寫各目錄的CMakeLists.txt文件，以實現(xiàn)以下目標：

將hello二進制與runhello.sh安裝至/<prefix>/bin，將doc目錄中的hello.txt以及COPYRIGHT/README安裝到/<prefix>/share/doc/cmake/t2

• 安裝COPYRIGHT/README，直接修改主工程文件CMakelists.txt，加入以下指令：

INSTALL(FILES COPYRIGHT README DESTINATION share/doc/cmake/t2) #將COPYRIGHT/README安裝到/<prefix>/share/doc/cmake/t2

• 安裝runhello.sh，直接修改主工程文件CMakeLists.txt，加入如下指令：

INSTALL(PROGRAMS runhello.sh DESTINATION bin) # 將runhello.sh安裝到/<prefix>/bin

• 安裝hello 可執(zhí)行文件, 修改t2/src/CMakeLists.txt, 加入如下指令：

INSTALL(TARGETS hello RUNTIME DESTINATION bin) #將hello二進制安裝至/<prefix>/bin

• 安裝doc中的hello.txt，這里有兩種方式：一是通過在doc目錄建立CMakeLists.txt，并將doc目錄通過ADD_SUBDIRECTORY加入工程來完成。另一種方法是直接在工程目錄通過INSTALL(DIRECTORY …)來完成，前者比較簡單，各位可以根據(jù)興趣自己完成，我們來嘗試后者，即在主工程文件CMakeLists.txt做修改。因為hello.txt要安裝到/<prefix>/share/doc/cmake/t2，所以我們不能直接安裝整個doc目錄，這里采用的方式是安裝doc目錄中的內(nèi)容，也就是使用" doc/ "在工程文件CMakelists.txt中添加:

INSTALL(DIRECTORY doc/ DESTINATION share/doc/cmake/t2) #將doc目錄中的hello.txt安裝到/<prefix>/share/doc/cmake/t2

6，嘗試我們修改的結(jié)果：

現(xiàn)在進入build目錄進行外部編譯，注意使用CMAKE_INSTALL_PREFIX參數(shù)，這里我們

將它安裝到了/tmp/t2/usr目錄：

cmake -DCMAKE_INSTALL_PREFIX=/tmp/t2/usr .. （注： .. 表示build目錄的上一層目錄）

然后運行

make

make install

This result will be shown as below:

讓我們進入/tmp/t2目錄看一下安裝結(jié)果：

Now we can run the binary file – hello， in two different directories, and we can get the same results.

此外，我們發(fā)現(xiàn)，運行 ./hello 和運行 ./runhello.sh 回得到同一個效果， 因為runhello.sh文件的內(nèi)容就是"hello", 而且二進制文件hello和runhello.sh 在同一個目錄下，因此可以實現(xiàn)其效果。

如果你要直接安裝到系統(tǒng)，可以使用如下指令：

cmake -DCMAKE_INSTALL_PREFIX=/usr ..

Note: 一個疑問

如果我沒有定義CMAKE_INSTALL_PREFIX會安裝到什么地方？

你可以嘗試以下，cmake ..; make; sudo make install，你會發(fā)現(xiàn)CMAKE_INSTALL_PREFIX的默認定義是/usr/local， 如下圖：

7，清理構(gòu)建結(jié)果（See Ref 2）

以下是來自stackoverflow論壇的一個問題：

Question：Just asmake cleandeletes all the files that a makefile has produced, I would like to do the same with CMake. All too often I find myself manually going through directories removing files likecmake_install.cmakeandCMakeCache.txt, and theCMakeFilesfolders.Is there a command likecmake cleanwhich will remove all these files automatically? Ideally this should follow the recursive structure defined within the current directory'sCMakeLists.txtfile.

Best Answer:

8，小結(jié)：

本小節(jié)主要描述了如何在工程中使用多目錄、各種安裝指令以及CMAKE_INSTALL_PREFIX變量。