CMake01快速上手

CMake快速上手

本文旨在快速上手并且使用cmake，更多深入内容请参考后续的blog。

第一个CMake

• 源文件

#include <stdio.h>
int main()
{
    printf("Hello World from t1 Main\r\n");
    return 0;
}

• CMakeLists.txt

PROJECT (HELLO)
SET(SRC_LIST main.c)
MESSAGE(STATUS "This is BINARY dir " ${HELLO_BINARY_DIR})
MESSAGE(STATUS "This is SOURCE dir "${HELLO_SOURCE_DIR})
ADD_EXECUTABLE(hello ${SRC_LIST})
ADD_EXECUTABLE(hello2 ${SRC_LIST})

• bash指令

cmake .
make

PROJECT

PROJECT(projectname [CXX] [C] [Java])

可以用这个指令定义工程，并且可以指定工程支持的语言，支持的语言列表是可以忽略的，默认情况表示支持所有语言。这个指令隐式定义了两个cmake变量：_BINARY_DIR以及_SOURCE_DIR，这里就是HELLO_BINARY_DIR和HELLO_SOURCE_DIR(所以CMakeLists.txt中两个MESSAGE指令可以直接是使用这两个变量)，因为采用的是内部编译，两个变量目前指的都是工程所在路径。

同时cmake系统也帮我们预定义了PROJECT_BINARY_DIR和PROJECT_SOURCE_DIR变量，他们的值分别和HELLO_BINARY_DIR和HELLO_SOURCE_DIR一致。

为了统一起见，建议以后直接使用PROJECT_BINARY_DIR，PROJECT_SOURCE_DIR，即使修改了工程名称，也不会影响这两个变量。如果使用了_SOURCE_DIR，修改工程名称后，需要同时修改这些变量。

SET

SET(VAR [VALUE] [CACHE TYPE DOCSTRING [FORMCE]])

现阶段只要了解SET指令可以用来显式定义变量即可。

比如我们也可以定义成的

SET(SRC_LIST main.c t1.c t2.c)

小羊来啦！！！！！yeyeyeyeyeyey爱你宝宝！！！

MESSAGE

MESSAGE([SEND_ERROR | STATUS | FATAL_ERROR] "message to display" ...)

这个指令用于向终端输出用户定义的信息，包含三种类型：

• SEND_ERROR，产生错误，生成过程被跳过
• STATUS，输出前缀唯一的信息
• FATAL_ERROR，立即终止所有cmake过程

我们在这里使用的是STATUS 信息输出，演示了由PROJECT 指令定义的两个隐式变量HELLO_BINARY_DIR 和HELLO_SOURCE_DIR。

ADD_EXECUTABLE

ADD_EXECUTABLE(hello ${SRC_LIST})

定义了这个工程会生成一个名为hello的可执行文件，相关的源文件是SRC_LIST中定义的源文件列表，本例中也可以写成

ADD_EXECUTABLE(hello main.c)

基本语法规则

• 变量使用${}方式取值，但是在IF控制语句中直接使用变量名
• 指令（参数1 参数2）
• 指令是大小写无关的，参数和变量是大小写相关的，但是推荐使用大写指令
• 如果源文件有空格，需要使用引号：SET(SRC_LIST "ma in.cc")
• 清理工程只需要make clean
• 需要为任何子目录添加CMakeLists.txt

关于内部构建和外部构建：

刚刚的例子使用的是内部编译，编译完成后，会有很多中间文件，但是cmake又不支持自动删除中间文件，所以我们需要用到”外部编译“：

在CMakeLists.txt所在文件夹新建一个build文件夹，进入build文件夹，运行cmake ..即可。

更好的Hello World

我们新建一个文件夹t2，进入t2再新建一个文件夹src，将main.c拷贝到src中。在t2和src中分别新建一个CMakeLists.txt（上面语法规则说过，每个子目录都要有一个CMakeLists.txt）。

• t2/CMakeLists.txt

PROJECT(HELLO)
ADD_SUBDIRECTORY(src bin)

• src/CMakeLists.txt

ADD_EXECUTABLE(hello main.c)

然后在t2目录下建立build文件夹，进入build文件夹。

cmake ..
make

构建完成后，你会发现生成的目标文件hello位于build/bin目录中。

ADD_SUBDIRECTORY

ADD_SUBDIRECTORY(source_dir [binary_dir] [EXCLUDE_FROM_ALL])

这个指令用于当前工程添加存放源文件的子目录，并且可以指定中间二进制和目标二进制存放位置。EXCLUDE_FROM_ALL参数的含义是：将这个目录从编译过程中排除。比如，工程example，可能需要工程构建完成后，再进入example目录单独构建。

上面的例子定义了将src子目录加入工程，并且指定了编译输出路径为bin。如果不指定bin，那么编译结果都会存放再build/src中（这个目录和原有src对应），指定bin目录后，相当于再编译时将src重命名为bin。

换个地方保存目标二进制

我们可以通过SET指令重新定义EXECUTABLE_OUTPUT_PATH和LIBRARY_OUTPUT_PATH变量来指定最终的目标二进制位置。

SET(EXECUTABLE_OUTPUT_PATH ${PROJECT_BINARY_DIR}/bin)
SET(LIBRARY_OUTPUT_PATH ${PROJECT_BINARY_DIR}/lib)

上面两个指令分别定义了：可执行二进制的输出路径为build/bin 和库的输出路径为build/lib。

问题是，我们应该把这两条指令写在工程的 CMakeLists.txt 还是 src 目录下的CMakeLists.txt，把握一个简单的原则，在哪里ADD_EXECUTABLE 或ADD_LIBRARY，如果需要改变目标存放路径，就在哪里加入上述的定义。

如何安装

安装的需要有两种，一种是从代码编译然后直接make install安装，一种是打包时的指定目录安装。

所以，即使是最简单的手工编写的Makefile，看起来也是这样的。

DESTDIR=
intall:
  mkdir -p $(DESTDIR)/usr/bin install -m 755 hello $(DESTDIR)/usr/bin

你可以通过make install将hello直接安装到/usr/bin目录，也可以通过make installl DESTDIR=/tmp/test将他安装在/tmp/test/usr/bin目录，打包时这个方式经常被使用。

那么我们的HelloWorld应该怎么安装呢？

这里需要引入一个新的cmake指令INSTALL和一个非常有用的变量CMAKE_INSTALL_PERFIX。常见的使用方法是这样的的。

cmake -DCMAKE_INSTALL_PERFIX=/usr .

INSTALL指令用于定义安装规则，安装目标内容包括目标二进制，动态库，静态库以及文件，目录，脚本等。

INSTALL安装规则

INSTALL(TARGETS targets...
[[ARCHIVE|LIBRARY|RUNTIME]
[DESTINATION <dir>]
[PERMISSIONS permissions...]
[CONFIGURATIONS
[Debug|Release|...]]
[COMPONENT <component>]
[OPTIONAL]
] [...])

• 参数中的TARGET后面就是我们通过ADD_EXECUTABLE或者ADD_LIBRARY定义的目标文件，可能是可指定二进制，动态库，静态库。

• 目标类型有三种：ARCHIVE特质静态库，LIBRARY特质动态库，RUNTIME特指可执行目标二进制。

• DESTINATION定义了安装的路径，如果路径已/开头，那就是绝对路径，这是CMAKE_INSTALL_PREFIX其实就无效了。如果你希望使用CMAKE_INSTALL_PREFIX来定义安装路径，就要写成相对路径，即不要以/开头，那么安装后的路径就是${CMAKE_INSTALL_PREFIX}/

举个简单例子：

INSTALL(TARGETS myrun mylib mystaticlib RUNTIME DESTINATION bin 
LIBRARY DESTINATION lib
ARCHIVE DESTINATION libstatic
)

上面的例子会将：

• 可执行二进制myrun 安装到${CMAKE_INSTALL_PERFIX}/bin
• 目录动态库libmylib 安装到${CMAKE_INSTALL_PREFIX}/lib 目录
• 静态库libmystaticlib 安装到${CMAKE_INSTALL_PREFIX}/libstatic 目录

普通文件安装

INSTALL(FILES files... DESTINATION <dir> [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>]
[RENAME <name>] [OPTIONAL])

可用于安装一般文件，并且可以指定访问权限，文件名是此指令所在路径下的相对路径。如果默认不定义权限PERMISSIONS，安装权限为：

OWNER_WRITE，OWNER_READ，GROUP_READ和WORLD_READ，即644权限。

非目标文件的可执行程序安装（比如脚本之类的）：

INSTALL(PROGRAMS files... DESTINATION <dir>
[PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] [RENAME <name>] [OPTIONAL])

和上面的FILES指令使用方法一样，唯一的不同是安装后的权限为：

OWNER_EXECUTE，GROUP_EXECUTE和WORLD_EXECUTE，即755权限。

目录的安装：

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参数。

DIRECTORY后面连接的是所在Source目录相对路径，但是务必注意：abc和abc/有很大的区别。

如果目录名不是以/结尾，那么这个目录将被安装为目标目录下的abc，如果目录名以/结尾，代表这个目录中的内容安装到目标路径，但不包括这个目录本身。

PATTERN用于使用正则表达式进行过滤，PERMISSIONS用于指定PATTERN过滤后的文件权限。

我们来看一个例子：

INSTALL(DIRECTORY icons scripts/ DESTINATION share/myproj
PATTERN "CVS" EXCLUDE
PATTERN "scripts/*"
PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
GROUP_EXECUTE GROUP_READ)

这条指令的结果是：

将icons目录安装到 /share/myproj，将scripts/中的内容安装到 /share/myproj

不包含目录名为CVS的目录，对于scripts/*文件指定权限为OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_EXECUTE GROUP_READ。

修改HelloWorld支持安装

这里我们先说一下这一节要实现的任务：

1. 问工程添加一个子目录src，用来存储源代码；
2. 添加一个子目录doc，用来储存这个工程的文档hello.txt；
3. 在工程目录添加文本文件COPYRIGHT，README；
4. 在工程目录添加一个runhello.sh脚本，用来调用hello二进制
5. 将构建后的目标文件放入构建目录bin子目录；
6. 最终安装这些文件：将hello二进制与runhello.sh安装到//bin，将doc目录中的hello.txt以及COPYRIGHT/README安装到//share/doc/cmake/t2

首先我们在原来t2先补上添加的文件。

下面改写各目录的CMakeLists.txt 文件。

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

INSTALL(FILES COPYRIGHT README DESTINATION share/doc/cmake/t2)

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

INSTALL(PROGRAMS runhello.sh DESTINATION bin)

3，安装 doc 中的hello.txt，这里有两种方式：一是通过在doc 目录建立 CMakeLists.txt 并将 doc 目录通过ADD_SUBDIRECTORY 加入工程来完成。另一种方法

是直接在工程目录通过

INSTALL(DIRECTORY 来完成)，前者比较简单，各位可以根据兴趣自己完成，我们来尝试后者，顺便演示以下DIRECTORY 的安装。

因为hello.txt 要安装到//share/doc/cmake/t2，所以我们不能直接安装整个doc 目录，这里采用的方式是安装 doc 目录中的内容，也就是使用”doc/”

在工程文件中添加

INSTALL(DIRECTORY doc/ DESTINATION share/doc/cmake/t2)

尝试修改的结果

cmake -DCMAKE_INSTALL_PREFIX=/tmp/t2/usr
make
sudo make install

让我们进入/tmp/t2 目录看一下安装结果：

./usr
./usr/share
./usr/share/doc
./usr/share/doc/cmake
./usr/share/doc/cmake/t2
./usr/share/doc/cmake/t2/hello.txt
./usr/share/doc/cmake/t2/README
./usr/share/doc/cmake/t2/COPYRIGHT
./usr/bin
./usr/bin/hello
./usr/bin/runhello.sh

静态库和动态库

• 新建一个目录t3存放本工程
• 建立共享库

cd t3
mkdir lib
cd lib
touch hello.h hello.c CMakeLists.txt

• lib/hello.h

#ifndef HELLO_H_
#define HELLO_H_
#include <stdio.h>
void hello_func(void);
#endif

• t3/lib/hello.c

#include "hello.h"
void hello_func(void)
{
    printf("Hello World!\r\n");
    return;
}

• t3/lib/CMakeLists.txt

set(lib_src hello.c)
add_library(hello SHARED ${lib_src})

• t3/CMakeLists.txt

project(HELLOLIB)
add_subdirectory(lib so)

然后在t3目录下：

mkdir build
cd build
cmake ..
make
ls

你会看到一个so文件夹，里面有libhello.so文件。

ADD_LIBRARY

ADD_LIBRARY(libname [SHARED|STATIC|MODULE] [EXCLUDE_FROM_ALL]
source1 source2 ... sourceN)

你不需要写全libhello.so，只要写hello即可，cmake系统会自动生成libhello.X

类型有三种：

• SHARED 动态库
• STATIC 静态库
• MODULE 使用dyld的系统有效，不然默认SHARED

添加静态库

同样使用上面的指令，我们在支持动态库的基础上再为工程添加一个静态库，按照一般的习惯，静态库名字跟动态库名字应该是一致的，只不过后缀是.a 罢了。

然后再在build 目录进行外部编译，我们会发现，静态库根本没有被构建，仍然只生成了一个动态库。因为hello 作为一个target 是不能重名的，所以，静态库构建指令无效

如果我们把上面的hello修改为hello_static：

`ADD_LIBRARY(hello_staic STATIC ${lib_src})

就可以构建一个libhello_static.a的静态库了。

但是这种结果显示不是我们想要的，我们需要的是名字相同的静态库和动态库，因为 target称是唯一的，所以，我们肯定不能通过 ADD_LIBRARY 指令来实现了。这时候我们需要用另外一个指令：

SET_TARGET_PROPERTIES

SET_TARGET_PROPERTIES(target1 target2 ...
PROPERTIES prop1 value1
prop2 value2 ...)

这条指令可以用来设置输出名称，对用动态库，还可以指定动态库版本。在本例中，我们需要作的是向lib/CMakeLists.txt 中添加一条：

SET_TARGET_PROPERTIES(hello_static PROPERTIES OUTPUT_NAME "hello")

这样我们就可以同时得到libhello.so&libhello.a了。

动态库版本号

按照规则，动态库是应该包含一个版本号的，我们可以看一下系统的动态库，一般情况是

libhello.so.1.2

libhello.so ->libhello.so.1

libhello.so.1->libhello.so.1.2

为了实现动态库版本号，我们仍然需要使用 SET_TARGET_PROPERTIES 指令。

具体使用方法如下：

SET_TARGET_PROPERTIES(hello PROPERTIES VERSION 1.2 SOVERSION 1)
# VERSION 动态库版本
#SOVERSION  API版本

将上述指令加入lib/CMakeLists.txt 中，重新构建看看结果。

在 build/so目录会生成： libhello.so.1.2 libhello.so.1->libhello.so.1.2 libhello.so ->libhello.so.1

安装共享库和头文件

以上面的例子，我们需要将libhello.a, libhello.so.x 以及 hello.h 安装到系统目录，才能真正让其他人开发使用，在本例中我们将 hello 的共享库安装到/lib目录，将hello.h 安装到/include/hello 目录。

利用上一节提到的INSTALL指令，我们向lib/CMakeLists.txt中添加如下指令：

INSTALL(TARGETS hello hello_static
LIBRARY DESTINATION lib
ARCHIVE DESTINATION lib)
INSTALL(FILES hello.h DESTINATION include/hello

运行：

cmake -DCMAKE_INSTALL_PREFIX=/usr ..
make
make install

我们就可以将头文件和共享库安装到系统目录/usr/lib 和/usr/include/hello 中了。

如何使用外部共享库

• 建立一个t4文件夹，存放文件。
• 建立src目录，编写main.c
• 编写t4/CMakeLists.txt
• 编写t4/src/CMakeLists.txt

main.c

#include <stdio.h>
#include "hello.h"
int main()
{
    hello_func();
    return 0;
}

t4/src/CMakeLists.txt

add_executable(main main.c)

t4/CMakeLists.txt

project(NEWHELLO)
add_subdirectory(src bin)

这时你建立build编译，是编译失败的，因为没有hello.h依赖，这时我们就需要搜索头文件。

引入头文件搜索路径

为了让我们的工程能够找到hello.h 头文件，我们需要引入一个新的指令：

INCLUDE_DIRECTORIES

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

这条指令可以用来向工程添加多个特定的头文件搜索路径，路径之间用空格分割，如果路径中包含了空格，可以使用双引号将它括起来，默认的行为是追加到当前的头文件搜索路径的后面，你可以通过两种方式来进行控制搜索路径添加的方式：

１，CMAKE_INCLUDE_DIRECTORIES_BEFORE，通过SET 这个cmake 变量为on，可以将添加的头文件搜索路径放在已有路径的前面。

２，通过AFTER 或者BEFORE 参数，也可以控制是追加还是置前。

现在我们在src/CMakeLists.txt 中添加一个头文件搜索路径，方式很简单，加入：

INCLUDE_DIRECTORY(/usr/include/hello

进入build 目录，重新进行构建，这是找不到 hello.h 的错误已经消失，但是出现了一个新的错误：

main.c:(.text+0x12): undefined reference to `HelloFunc’

因为我们并没有link 到共享库libhello 上。

为target添加共享库

我们现在需要完成的任务是将目标文件链接到 libhello，这里我们需要引入两个新的指令

LINK_DIRECTORIES和`TARGET_LINK_LIBRARIES

LINK_DIRECTORIES

LINK_DIRECTORIES(directory1 directory2 ...)

这个指令非常简单，添加非标准的共享库搜索路径，比如，在工程内部同时存在共享库和可执行二进制，在编译时就需要指定一下这些共享库的路径。

TARGET_LINK_LIBRARIES

so

TARGET_LINK_LIBRARIES(target library1
<debug | optimized> library2
...)

这个指令可以用来为target 添加需要链接的共享库，本例中是一个可执行文件，但是同样可以用于为自己编写的共享库添加共享库链接。

为了解决我们前面遇到的HelloFunc 未定义错误，我们需要作的是向 src/CMakeLists.txt 中添加如下指令：

TARGET_LINK_LIBRARIES(main libhello.so)

我们进入build编译完成后，就可以进入bin看到有一个main可执行文件。

使用ldd main查看main的连接情况：

linux-gate.so.1 => (0xb7ee7000)

libhello.so.1 => /usr/lib/libhello.so.1 (0xb7ece000)

libc.so.6 => /lib/libc.so.6 (0xb7d77000)

/lib/ld-linux.so.2 (0xb7ee8000)

可以清楚的看到main 确实链接了共享库libhello，而且链接的是动态库 libhello.so.1。

a

如果是链接静态库，只要把libhello.so改成libhello.a即可