CMake 基本用法--写CMakeList.txt

http://techbase.kde.org/Development/Tutorials/CMake_(zh_CN)

http://www.cmake.org/Wiki/CMake



这一章将从软件开发人员的角度来描写叙述怎样有用CMake。也就是说。假设你的目标是用CMake来管理你的生成过程，请阅读这一章。



CMake的输入



COMMAND(args)



这里的 COMMAND 是命令行的名称。args是用空格切割的參数列表。典型的，对与每个项目的文件夹存在一个CMakeLists.txt。 以下我们将从一个简单的Hello world样例開始介绍, 它的源码树形文件包括这些文件：



Hello.c CMakeLists.txt



CMakeLists.txt将包括以下两行：



PROJECT（Hello)

ADD_EXECUTABLE(Hello Hello.c）



为了生成Hello的可运行程序。你仅仅需按照上面CMake运行的过程描写叙述来生成makefiles文件。 PROJECT 命令表明了产生的工作空间的名称。 ADD_EXECUTABLE命令加入可运行的目标到生成程序。这个简单的程序就仅仅须要这些设置。

如歌你的项目须要一些文件才干编译也非常easy，仅仅想改动ADD_EXECUTABLE命令行例如以下：



ADD_EXECUTABLE（Hello Hello.c File2.c File3.c File4.c)



ADD_EXECUTABLE仅仅是非常多CMake命令中的一种。比方更复杂的例如以下：



PROJECT(HELLO)

SET(HELLO_SRCS Hell.c File2.c File3.c)

IF(WIN32)

  SET(HELLO_SRCS ${HELLO_SRCS} WinSupport.c)

ELSE (WIN32)

  SET(HELLO_SRCS ${HELLO_SRCS} UnixSupport.c)

ENDIF (WIN32)



ADD_EXECUTABLE (Hello ${HELLO_SRCS})



#look for the Tcl library

FIND_LIBRARY(TCL_LIBRARY NAMES tcl tc184 tc183 tc 182 tc 180

  PATHS /usr/lib /usr/local/lib)

IF (TCL_LIBRARY)

  TARGET_ADD_LIBRARY (Hello TCL_LIBRARY)

ENDIF(TCL_LIBRARY)



在这个样例中 SET 命令用于将源文件组成一个列表。

IF 命令用于添加WinSupport.c或者UnixSupport.c到列表中。 最后 ADD_EXECUTABLE 命令用于 採用源文件列表HELLO_SRCS中列出的文件 生成可运行文件。FIND_LIBRARY命令用于寻找在一些指定文件夹下的特定的Tcl库文件。

假设找到了，就将他们加入到Hello可运行程序的链接命令。 #行为凝视行。

CMake 是会定义一些使用的变量在CMakeList文件里。 比方。WIN32总是会在windows系统中被定义。而UNIX

总是在UNIX系统中被定义。



生成目标：（Build Targets)



SET()

SUBDIRS()

ADD_LIBRARY()

  这里生成静态链接文件，比如ADD_LIBRARY(Whole ${HELLO_SRC}),就会生成一个libWhole.a可供链接



ADD_EXECUTABLE()

AUX_SOURCE_DIRECTORY()

PROJECT()



CMake会循环的查找从当前文件夹到SUBDIRS列出的不论什么子文件夹的文件。SET命令用于设定一个变量。ADD_LIBRARY将加入一个库到目标之中。 ADD_EXECUTABLE加入一个可运行程序到目标列表中。（Note:编译器运行的顺序是先编译源文件，然后生成库文件，最后生成可运行文件）。

AUX_SOURCE_DIRECTORY表示一个不在当前文件夹的包括源文件的文件夹。

这些源码将插入当前的库（LIBRARY）中。全部在AUX_SOURCE_DIRECTORY的文件将被编译（如，*.c,*.cxx,*.cpp等等）。PROJECT（ProjectName）是一个用在MSVC中的特殊变量。用于为编译器生成项目。

他也为CMAKE定义连个实用的变量:ProjectName_SOURCE_DIR和ProjectName_BINARY_DIR.



编译的标示和选项。

除了上面列出的命令外。CMakeLists.txt还包括例如以下的命令：

INCLUDE_DIRECTORIES()

LINK_DIRECTORIES()

LINK_LIBRARIES()

TARGET_LINK_LIBRARIES()



这些命令定义了用于编译源码和生成可运行程序的文件夹和库。

上面列出的文件夹的一个非常重要的特性是它们会被不论什么子文件夹继承。也就是说。CMake按照文件夹的分层结构来承袭这些命令。在每次遇到对这些命令的描写叙述的时候都会被展开一次。比方说。假设在顶层的CMakeLists文件里有定义INCLUDE_DIRECTORIES(/usr/include)和SUBDIRS（./subdir1),而且在./subdir1/CMakeLists.txt有INCLUDE_DIRECTORIES(/tmp/foobar),于是最后网状的结果是

INCLUDE_DIRECTORIES(/usr/include /tmp/foobar)



CMake会定义很多的模块来查找一般会用到的包。比方OpenGL或Java。 这些模块为你节省了非常多的时间来编写这些查找包。这些模块能够像这样加到你的CMakeList文件里。例如以下：



INCLUDE(${CMAKE_ROOT}/Modules/FindTCL.cmake)



CMAKE_ROOT 总是定义在CMake中，用于指向CMake安装的路径。查看Modules子文件夹下的一些文件能够给你提供一些非常好的idea关于如何用这些CMake命令。



给项目文件加入一个新的文件夹

一个通用的方法来扩展一个项目文件是给他加入一个新的目录。这将包括三个步骤：

1.创建一个新的文件夹在你的源码的分层文件夹中

2.将这个新的文件夹加入到SUBDIRS命令中

3.在这个新创建的文件夹中用适当的命令建立一个CMakeLists.txt文件



This section describes how to use CMake from the software developer's point of view. That is, if your aim is to use CMake to manage your build process, read this section first.

Input to CMake



COMMAND(args)

Where COMMAND is the name of the command, and args is a white-space separated list of arguments to the command. (Arguments with embedded white-space should be quoted.) Typically there will be a CMakeLists.txt file for each directory of the project. Let's start
with a simple example. Consider building hello world. You would have a source tree with the following files:

Hello.c  CMakeLists.txt

The CMakeLists.txt file would contain two lines:

PROJECT (Hello)

ADD_EXECUTABLE(Hello Hello.c)

To build the Hello executable you just follow the process described in Running CMake above to generate the makefiles or Microsoft project files. The PROJECT command indicates what the name of the resulting workspace should be and the ADD_EXECUTABLE command
adds an executable target to the build process. That's all there is to it for this simple example. If your project requires a few files it is also quite easy, just modify the ADD_EXECUTABLE line as shown below.

ADD_EXECUTABLE(Hello Hello.c File2.c File3.c File4.c)



ADD_EXECUTABLE is just one of many commands available in CMake. Consider the more complicated example below.



PROJECT (HELLO)

SET(HELLO_SRCS Hello.c File2.c File3.c)

IF (WIN32)

  SET(HELLO_SRCS ${HELLO_SRCS} WinSupport.c)

ELSE (WIN32)

  SET(HELLO_SRCS ${HELLO_SRCS} UnixSupport.c)

ENDIF (WIN32)

ADD_EXECUTABLE (Hello ${HELLO_SRCS})



# look for the Tcl library

FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80

  PATHS  /usr/lib /usr/local/lib)

IF (TCL_LIBRARY)

  TARGET_ADD_LIBRARY (Hello TCL_LIBRARY)

ENDIF (TCL_LIBRARY)

In this example the SET command is used to group together source files into a list. The IF command is used to add either WinSupport.c or UnixSupport.c to this list. And finally the ADD_EXECUTABLE command is used to build the executable with the files listed
in the source list HELLO_SRCS. The FIND_LIBRARY command looks for the Tcl library under a few different names and in a few different paths, and if it is found adds it to the link line for the Hello executable target. Note the use of the # character to denote
a comment line.

CMake always defines some variables for use within CMakeList files. For example, WIN32 is always defined on windows systems and UNIX is always defined for UNIX systems. CMake defines a number of commands. A brief summary of the most commonly used commands follows
here. Later in the document an exhaustive list of all pre-defined commands is presented. (You may also add your own commands, see the Extension Guide for more information.)



Build Targets:





SET()

SUBDIRS()

ADD_LIBRARY()

 这里生成静态链接文件。比如ADD_LIBRARY(Whole ${HELLO_SRC})，就会生成一个libWhole.a。可供链接。

ADD_EXECUTABLE()

AUX_SOURCE_DIRECTORY()

PROJECT()

CMake works recursively, descending from the current directory into any subdirectories listed in the SUBDIRS command. The command SET is used for setting a variable, in this case to a list of source files. (Note: currently only C and C++ code can be compiled.)
ADD_LIBRARY adds a library to the list of targets this makefile will produce. ADD_EXECUTABLE adds an executable to the list of targets this makefile will produce. (Note: source code is compiled first, then libraries are built, and then executables are created.)
The AUX_SOURCE_DIRECTORY is a directory where other source code, not in this directory, whose object code is to be inserted into the current LIBRARY. All source files in the AUX_SOURCE_DIRECTORY are compiled (e.g. *.c, *.cxx, *.cpp, etc.). PROJECT (PojectName)
is a special variable used in the MSVC to create the project for the compiler, it also defines two useful variables for CMAKE: ProjectName_SOURCE_DIR and ProjectName_BINARY_DIR.



Build flags and options. In addition to the commands listed above, CMakeLists.txt often contain the following commands:



INCLUDE_DIRECTORIES()

LINK_DIRECTORIES()

LINK_LIBRARIES()

TARGET_LINK_LIBRARIES()

These commands define directories and libraries used to compile source code and build executables. An important feature of the commands listed above is that are inherited by any subdirectories. That is, as CMake descends through a directory hierarchy (defined
by SUBDIRS()) these commands are expanded each time a definition for a command is encountered. For example, if in the top-level CMakeLists file has INCLUDE_DIRECTORIES(/usr/include), with SUBDIRS(./subdir1), and the file ./subdir1/CMakeLists.txt has INCLUDE_DIRECTORIES(/tmp/foobar),
then the net result is

INCLUDE_DIRECTORIES(/usr/include /tmp/foobar)

CMake comes with a number of modules that look for commonly used packages such as OpenGL or Java. These modules save you from having to write all the CMake code to find these packages yourself. Modules can be used by including them into your CMakeList file
as shown below.



  INCLUDE (${CMAKE_ROOT}/Modules/FindTCL.cmake)

CMAKE_ROOT is always defined in CMake and can be used to point to where CMake was installed. Looking through some of the files in the Modules subdirectory can provide good ideas on how to use some of the CMake commands.



Adding A New Directory to a project



A common way to extend a project is to add a new directory. This involves three steps:

 Create the new directory somewhere in your source directory hierarchy.

 Add the new directory to the SUBDIRS command in the parent directories CMakeLists.txt

 Create a CMakeLists.txt in the new directory with the appropriate commands