初用CMake或者對其瞭解不太深的人，可能經常會被路徑包含、庫搜尋路徑、連結路徑、RPath這些問題所絆倒，因為這些東西在手工執行gcc或者編寫makefile的時候是很輕而易舉的任務。

其實我當初也有不少疑惑，不過通過較長時間的實踐和閱讀manual，總算有了個相對很清晰的認識。

• 如何使用其manual

cmake的幫助組織的還是很有規律的，瞭解了其規律，找自己想要的東西就會很簡單，所以個人覺得這一點可能是最重要的。其help系統大概是這麼幾類：

• command

這個是實用過程中最長用到的，相當於一般腳步語言中的基本語法，包括定義變數，foreach，string，if，builtin command都在這裡。

可以用如下這些命令獲取幫助：

cmake --help-commands 

這個命令將給出所有cmake內建的命令的詳細幫助，一般不知道自己要找什麼或者想隨機翻翻得時候，可以用這個。

我一般更常用的方法是將其重定向到less裡邊，然後在編輯器裡邊搜尋關鍵字。

 

另外也可以用如下的辦法層層縮小搜尋範圍：

cmake --help-command-list

cmake --help-command-list | grep find

skyscribe@skyscribe:~/program/ltesim/bld$ cmake --help-command-list | grep find
find_file
find_library
find_package
find_path
find_program

cmake --help-command find_library

cmake version 2.6-patch 4
------------------------------------------------------------------------------
SingleItem

  find_library
       Find a library.

          find_library(<VAR> name1 [path1 path2 ...])

       This is the short-hand signature for the command that is sufficient in
       many cases.  It is the same as find_library(<VAR> name1 [PATHS path1
       path2 ...])

          find_library(
                    <VAR>
                    name | NAMES name1 [name2 ...]
                    [HINTS path1 [path2 ... ENV var]]
                    [PATHS path1 [path2 ... ENV var]]
                    [PATH_SUFFIXES suffix1 [suffix2 ...]]
                    [DOC "cache documentation string"]
                    [NO_DEFAULT_PATH]
                    [NO_CMAKE_ENVIRONMENT_PATH]
                    [NO_CMAKE_PATH]
                    [NO_SYSTEM_ENVIRONMENT_PATH]
                    [NO_CMAKE_SYSTEM_PATH]
                    [CMAKE_FIND_ROOT_PATH_BOTH |
                     ONLY_CMAKE_FIND_ROOT_PATH |
                     NO_CMAKE_FIND_ROOT_PATH]
                   )

• variable

和command的幫助比較類似，只不過這裡可以查詢cmake自己定義了那些變數你可以直接使用，譬如OSName，是否是Windows，Unix等。

我最常用的一個例子：

cmake --help-variable-list | grep CMAKE | grep HOST 

CMAKE_HOST_APPLE

CMAKE_HOST_SYSTEM

CMAKE_HOST_SYSTEM_NAME

CMAKE_HOST_SYSTEM_PROCESSOR

CMAKE_HOST_SYSTEM_VERSION

CMAKE_HOST_UNIX

CMAKE_HOST_WIN32

這裡查詢所有CMake自己定義的builtin變數；一般和系統平臺相關。

如果希望將所有生成的可執行檔案、庫放在同一的目錄下，可以如此做：

這裡的target_dir是一個實現設定好的絕對路徑。（CMake裡邊絕對路徑比相對路徑更少出問題，如果可能儘量用絕對路徑）

# Targets directory 

set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${target_dir}/lib)

set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${target_dir}/lib)

set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${target_dir}/bin)

• property

Property一般很少需要直接改動，除非你想修改一些預設的行為，譬如修改生成的動態庫檔案的soname等。

譬如需要在同一個目錄下既生成動態庫，也生成靜態庫，那麼預設的情況下，cmake根據你提供的target名字自動生成類似的libtarget.so, libtarget.a，但是同一個project只能同時有一個，因為target必須唯一。

這時候，就可以通過修改taget對應的檔名，從而達到既生成動態庫也產生靜態庫的目的。

譬如：

cmake --help-property-list | grep NAME 

GENERATOR_FILE_NAME

IMPORTED_SONAME

IMPORTED_SONAME_<CONFIG>

INSTALL_NAME_DIR

OUTPUT_NAME

VS_SCC_PROJECTNAME

skyscribe@skyscribe:~$ cmake --help-property OUTPUT_NAME

cmake version 2.6-patch 4

------------------------------------------------------------------------------

SingleItem

  OUTPUT_NAME

       Sets the real name of a target when it is built.

       Sets the real name of a target when it is built and can be used to

       help create two targets of the same name even though CMake requires

       unique logical target names.  There is also a <CONFIG>_OUTPUT_NAME

       that can set the output name on a per-configuration basis.

• module

用於查詢常用的模組，譬如boost，bzip2, python等。通過簡單的include命令包含預定義的模組，就可以得到一些模組執行後定義好的變數，非常方便。

譬如常用的boost庫，可以通過如下方式：

# Find boost 1.40 

INCLUDE(FindBoost)

find_package(Boost 1.40.0 COMPONENTS thread unit_test_framework)

if(NOT Boost_FOUND)

    message(STATUS "BOOST not found, test will not succeed!")

endif()

一般開頭部分的解釋都相當有用，可滿足80%需求：

cmake --help-module FindBoost | head -40

cmake version 2.6-patch 4

------------------------------------------------------------------------------

SingleItem

  FindBoost

       Try to find Boost include dirs and libraries

       Usage of this module as follows:

       == Using Header-Only libraries from within Boost: ==

          find_package( Boost 1.36.0 )

          if(Boost_FOUND)

             include_directories(${Boost_INCLUDE_DIRS})

             add_executable(foo foo.cc)

          endif()

       == Using actual libraries from within Boost: ==

          set(Boost_USE_STATIC_LIBS   ON)

          set(Boost_USE_MULTITHREADED ON)

          find_package( Boost 1.36.0 COMPONENTS date_time filesystem system ... )

          if(Boost_FOUND)

             include_directories(${Boost_INCLUDE_DIRS})

             add_executable(foo foo.cc)

             target_link_libraries(foo ${Boost_LIBRARIES})

          endif()

       The components list needs to contain actual names of boost libraries

• 如何根據其生成的中間檔案檢視一些關鍵資訊

CMake相比較於autotools的一個優勢就在於其生成的中間檔案組織的很有序，並且清晰易懂，不像autotools會生成天書一樣的龐然大物（10000+的不鮮見）。

一般CMake對應的Makefile都是有層級結構的，並且會根據你的CMakeLists.txt間的相對結構在binary directory裡邊生成相應的目錄結構。

譬如對於某一個target，一般binary tree下可以找到一個資料夾:  CMakeFiles/<targentName>.dir/,比如：

skyscribe@skyscribe:~/program/ltesim/bld/dev/simcluster/CMakeFiles/SIMCLUSTER.dir$ ls -l 

total 84 

-rw-r--r-- 1 skyscribe skyscribe 52533 2009-12-12 12:20 build.make 

-rw-r--r-- 1 skyscribe skyscribe 1190 2009-12-12 12:20 cmake_clean.cmake 

-rw-r--r-- 1 skyscribe skyscribe 4519 2009-12-12 12:20 DependInfo.cmake 

-rw-r--r-- 1 skyscribe skyscribe 94 2009-12-12 12:20 depend.make 

-rw-r--r-- 1 skyscribe skyscribe 573 2009-12-12 12:20 flags.make 

-rw-r--r-- 1 skyscribe skyscribe 1310 2009-12-12 12:20 link.txt 

-rw-r--r-- 1 skyscribe skyscribe 406 2009-12-12 12:20 progress.make 

drwxr-xr-x 2 skyscribe skyscribe 4096 2009-12-12 12:20 src 

這裡，每一個檔案都是個很短小的文字檔案，內容相當清晰明瞭。build.make一般包含中間生成檔案的依賴規則，DependInfo.cmake一般包含原始碼檔案自身的依賴規則。

比較重要的是flags.make和link.txt，前者一般包含了類似於GCC的-I的相關資訊，如搜尋路徑，巨集定義等；後者則包含了最終生成target時候的linkage資訊，庫搜尋路徑等。

這些資訊在出現問題的時候是個很好的輔助除錯手段。

• 檔案查詢、路徑相關
  • include

一般常用的是：

include_directories（）用於新增標頭檔案的包含搜尋路徑 

cmake --help-command include_directories

cmake version 2.6-patch 4

------------------------------------------------------------------------------

SingleItem

  include_directories

       Add include directories to the build.

         include_directories([AFTER|BEFORE] [SYSTEM] dir1 dir2 ...)

       Add the given directories to those searched by the compiler for

       include files.  By default the directories are appended onto the

       current list of directories.  This default behavior can be changed by

       setting CMAKE_include_directories_BEFORE to ON.  By using BEFORE or

       AFTER you can select between appending and prepending, independent

       from the default.  If the SYSTEM option is given the compiler will be

       told that the directories are meant as system include directories on

       some platforms.

link_directories()用於新增查詢庫檔案的搜尋路徑

cmake --help-command link_directories

cmake version 2.6-patch 4

------------------------------------------------------------------------------

SingleItem

  link_directories

       Specify directories in which the linker will look for libraries.

         link_directories(directory1 directory2 ...)

       Specify the paths in which the linker should search for libraries.

       The command will apply only to targets created after it is called.

       For historical reasons, relative paths given to this command are

       passed to the linker unchanged (unlike many CMake commands which

       interpret them relative to the current source directory).

• library search

一般外部庫的link方式可以通過兩種方法來做，一種是顯示新增路徑，採用link_directories()， 一種是通過find_library()去查詢對應的庫的絕對路徑。

後一種方法是更好的，因為它可以減少不少潛在的衝突。

        一般find_library會根據一些預設規則來搜尋檔案，如果找到，將會set傳入的第一個變數引數、否則，對應的引數不被定義，並且有一個xxx-NOTFOUND被定義；可以通過這種方式來除錯庫搜尋是否成功。

        對於庫檔案的名字而言，動態庫搜尋的時候會自動搜尋libxxx.so (xxx.dll),靜態庫則是libxxx.a（xxx.lib），對於動態庫和靜態庫混用的情況，可能會出現一些混亂，需要格外小心；一般儘量做匹配連線。

• rpath

所謂的rpath是和動態庫的載入執行相關的。我一般採用如下的方式取代預設新增的rpath：

# RPATH and library search setting 

SET(CMAKE_SKIP_BUILD_RPATH  FALSE)

SET(CMAKE_BUILD_WITH_INSTALL_RPATH FALSE) 

SET(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/nesim/lib")

SET(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)