Cmake Practice(二)

上一节我们用一个实例简单地演示了cmake的用法,这一节我们将继续.

四，更好一点的Hello World
从本小节开始，后面所有的构建我们都将采用out-of-source外部构建，约定的构建目录是工程目录下的build自录

cd leran-cmakemkdir build

本小节的任务是让前面的Hello World更像一个工程，我们需要作的是：

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

1，准备工作：
在/leran-cmake/目录下新建子目录practice2
将practice1工程的main.c和CMakeLists.txt拷贝到practice2目录中

2,添加子目录src:

cd practice2mkdir srcmv main.c src

上一节我们提到，需要为任何子目录建立一个CMakeLists.txt，进入子目录src，编写CMakeLists.txt如下：

ADD_EXECUTABLE(hello main.c)

将practice2工程的CMakeLists.txt修改为：

PROJECT(HELLO) ADD_SUBDIRECTORY(src bin)

然后在build目录中进行构建

cd ../build/rm -rf *cmake ../practice2/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，所有的中间结果和目标二进制都将存放在bin目录。

这里需要提一下的是 SUBDIRS 指令,使用方法是:
SUBDIRS(dir1 dir2…),但是这个指令已经不推荐使用。它可以一次添加多个子目录,
并且,即使外部编译,子目录体系仍然会被保存。
如果我们在上面的例子中将 ADD_SUBDIRECTORY (src bin)修改为 SUBDIRS(src)。
那么在 build 目录中将出现一个 src 目录,生成的目标代码 hello 将存放在 src 目录中。

3,换个地方保存目标二进制
不论是 SUBDIRS 还是 ADD_SUBDIRECTORY 指令(不论是否指定编译输出目录),我们都可
以通过 SET 指令重新定义 EXECUTABLE_OUTPUT_PATH 和 LIBRARY_OUTPUT_PATH 变量
来指定最终的目标二进制的位置(指最终生成的 hello 或者最终的共享库,不包含编译生成
的中间文件)
SET(EXECUTABLE_OUTPUT_PATH PROJECTBINARYDIR/bin)SET(LIBRARYOUTPUTPATH{PROJECT_BINARY_DIR}/lib)

在第一节我们提到了_BINARY_DIR 和 PROJECT_BINARY_DIR 变量,他
们指的编译发生的当前目录,如果是内部编译,就相当于 PROJECT_SOURCE_DIR 也就是
工程代码所在目录,如果是外部编译,指的是外部编译所在目录,也就是本例中的 build
目录。

所以,上面两个指令分别定义了:
可执行二进制的输出路径为 build/bin 和库的输出路径为 build/lib.
本节我们没有提到共享库和静态库的构建,所以,你可以不考虑第二条指令。

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

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

所以,即使最简单的手工编写的 Makefile,看起来也是这个样子的:

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

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

稍微复杂一点的是还需要定义 PREFIX,一般 autotools 工程,会运行这样的指令:

./configure –prefix=/usr //或者./configure --prefix=/usr/local 来指定PREFIX

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

DESTDIR=PREFIX=/usrinstall:mkdir -p $(DESTDIR)/$(PREFIX)/bininstall -m 755 hello $(DESTDIR)/$(PREFIX)/bin

那么我们的 HelloWorld 应该怎么进行安装呢?
这里需要引入一个新的 cmake 指令 INSTALL 和一个非常有用的变量CMAKE_INSTALL_PREFIX。

CMAKE_INSTALL_PREFIX 变量类似于 configure 脚本的 – prefix,常见的使用方法看起来是这个样子:

cmake -DCMAKE_INSTALL_PREFIX=/usr .

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

INSTALL 指令包含了各种安装类型,我们需要一个个分开解释:
目标文件的安装:

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

参数中的 TARGETS 后面跟的就是我们通过 ADD_EXECUTABLE 或者 DD_LIBRARY 定义的目标文件,可能是可执行二进制、动态库、静态库。

目标类型也就相对应的有三种,ARCHIVE 特指静态库,LIBRARY 特指动态库,RUNTIME特指可执行目标二进制。

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        )

上面的例子会将:

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

特别注意的是你不需要关心 TARGETS 具体生成的路径,只需要写上 TARGETS 名称就可以了。

普通文件的安装:

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.

安装时 CMAKE 脚本的执行:
INSTALL([[SCRIPT ] [CODE ]] […])
SCRIPT 参数用于在安装时调用 cmake 脚本文件(也就是.cmake 文件)
CODE 参数用于执行 CMAKE 指令,必须以双引号括起来。比如:

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

安装还有几个被标记为过时的指令,比如 INSTALL_FILES 等,这些指令已经不再推荐使用,所以,这里就不再赘述了。

下面,我们就来改写我们的工程文件,让他来支持各种文件的安装,并且,我们要使用CMAKE_INSTALL_PREFIX 指令。

5,修改 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/practice2,

首先我们先补上为添加的文件。
添加 doc 目录及文件:

cd practice2/mkdir docvi doc/hello.txt   //随便填写一些内容并保存

在工程目录添加 runhello.sh 脚本,内容为:

./hello

添加工程目录中的 COPYRIGHT 和 README

touch COPYRIGHTtouch README

下面改写各目录的 CMakeLists.txt 文件。
1,安装 COPYRIGHT/README,直接修改主工程文件 CMakelists.txt,加入以下指令:

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

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

INSTALL(PROGRAMS ${PROJECT_BINARY_DIR}/bin/hello runhello.sh DESTINATION bin)

3,安装 doc 中的 hello.txt
这里有两种方式:
一是通过在 doc 目录建立CMakeLists.txt 并将 doc 目录通过 ADD_SUBDIRECTORY 加入工程来完成。
另一种方法是直接在工程目录通过INSTALL(DIRECTORY 来完成),前者比较简单,各位可以根据兴趣自己完成,我们来尝试后者,顺便演示以下 DIRECTORY 的安装。

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

然后进入build目录下编译安装

cd build/cmake -DCMAKE_INSTALL_PREFIX=/tmp/practice2/usr ../practice2/makemake install

安装成功后可以去/tmp/practice2/usr看看

.├── bin│   ├── hello│   └── runhello.sh└── share    └── doc        └── cmake            └── practice2                ├── COPYRIGHT                ├── hello.txt                └── README

7,一个疑问
如果我没有定义 CMAKE_INSTALL_PREFIX 会安装到什么地方?
你可以尝试以下,cmake ..;make;make install,你会发现
CMAKE_INSTALL_PREFIX 的默认定义是/usr/local

在下一小节,我们将探讨如何在 cmake 中构建动态库和静态库.