CMake

如果工程存在多个目录,需要确保每个要管理的目录都存在一个 CMakeLists.txt．

Set a name, version, and enable languages for the entire project.
1

project(<PROJECT-NAME> [LANGUAGES] [<language-name>...])
Sets the name of the project and stores the name in the PROJECT_NAME variable. Additionally this sets variables　PROJECT_SOURCE_DIR, PROJECT_BINARY_DIR
Signatures of this command that specify a <value>... placeholder expect zero or more arguments. Multiple arguments will be joined as a ;-list to form the actual variable value to be set.
1

set(<variable> <value>... CACHE <type> <docstring> [FORCE])
在哪里add_executable 或add_library，需要改变目标存放路径则在哪个层级的CMakeLists.txt加．
1 2

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

Display a message to the user.

1

message([<mode>] "message to display" ...)

Add an executable target called <name> to be built from the specified source files. The <name> corresponds to the logical target name and must be globally unique within a project.
1 2 3

add_executable(<name> [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [source1] [source2 ...])
Add a subdirectory to the build. The source_dir specifies the directory in which the source CMakeLists.txt and code files are located. If it is a relative path it will be evaluated with respect to the current directory. The binary_dirspecifies the directory in which to place the output files. If it is a relative path it will be evaluated with respect to the current output directory, but it may also be an absolute path. If binary_dir is not specified, the value of source_dir will be used.
1 2

add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])

Installing Targets

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


install(TARGETS targets... [EXPORT <export-name>]
        [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
          PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
         [DESTINATION <dir>]
         [PERMISSIONS permissions...]
         [CONFIGURATIONS [Debug|Release|...]]
         [COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
         [NAMELINK_ONLY|NAMELINK_SKIP]
        ] [...]
        [INCLUDES DESTINATION [<dir> ...]]
        )

example

1
2
3
4
5


install(TARGETS myExe mySharedLib myStaticLib
        RUNTIME DESTINATION bin
        LIBRARY DESTINATION lib
        ARCHIVE DESTINATION lib/static)
install(TARGETS mySharedLib DESTINATION /some/full/path)

install myExe to <prefix>/bin and myStaticLib to <prefix>/lib/static.

On non-DLL platforms mySharedLib will be installed to <prefix>/lib and /some/full/path.

Installing Files

1
2
3
4
5


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

Installing Directories

1
2
3
4
5
6
7
8
9


install(DIRECTORY dirs... DESTINATION <dir>
        [FILE_PERMISSIONS permissions...]
        [DIRECTORY_PERMISSIONS permissions...]
        [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
        [CONFIGURATIONS [Debug|Release|...]]
        [COMPONENT <component>] [EXCLUDE_FROM_ALL]
        [FILES_MATCHING]
        [[PATTERN <pattern> | REGEX <regex>]
         [EXCLUDE] [PERMISSIONS permissions...]] [...])

The last component of each directory name is appended to the destination directory but a trailing slash may be used to avoid this because it leaves the last component empty.

The FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify permissions given to files and directories in the destination.

Using the PATTERN or REGEX options “match” options specify a globbing pattern or regular expression to match directories or files encountered within input directories.

For example the code

1
2


install(DIRECTORY src/ DESTINATION include/myproj
        FILES_MATCHING PATTERN "*.h")

will extract and install header files from a source tree.

For example the code

1
2
3
4
5


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

will install the icons directory to share/myproj/icons and the files in thescripts directory to share/myproj. The icons will get default file permissions, the scripts will be given specific permissions, and any CVSdirectories will be excluded.

The SCRIPT form will invoke the given CMake script files during installation. The CODE form will invoke the given CMake code during installation.
1 2

install([[SCRIPT <file>] [CODE <code>]] [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
Adds a library target called <name> to be built from the source files listed in the command invocation.

1
2
3


add_library(<name> [STATIC | SHARED | MODULE]
            [EXCLUDE_FROM_ALL]
            [source1] [source2 ...])

The <name> corresponds to the logical target name and must be globally unique within a project.

The actual file name of the library built is constructed based on conventions of the native platform (such as lib<name>.a or <name>.lib).

Targets can have properties that affect how they are built. Set properties on a target.

1
2
3


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

using add_library, set_target_propertie to build shared and static library with the same name:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


add_library(hello SHARED ${LIBHELLO_SRC})
add_library(hello_static STATIC ${LIBHELLO_SRC})

set_target_properties(hello_static PROPERTIES OUTPUT_NAME "hello")

set_target_properties(hello PROPERTIES CLEAN_DIRECT_OUTPUT 1)
set_target_properties(hello_static PROPERTIES CLEAN_DIRECT_OUTPUT 1)

set_target_properties(hello PROPERTIES VERSION 1.2 SOVERSION 1)
set_target_properties(hello_static PROPERTIES VERSION 1.2 SOVERSION 1)

install headers files and shared, static library to system directory:

1
2
3
4
5


install(TARGETS hello hello_static
  LIBRARY DESTINATION lib
  ARCHIVE DESTINATION lib)

install(FILES hello.h DESTINATION include/hello)

cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..

make

make install

1
2
3
4
5


-- Installing: /usr/local/lib/libhello.so.1.2
-- Installing: /usr/local/lib/libhello.so.1
-- Installing: /usr/local/lib/libhello.so
-- Installing: /usr/local/lib/libhello.a
-- Installing: /usr/local/include/hello/hello.h

include header files directories and Link to external library

Add the given directories to those the compiler uses to search for include files, such as header files.
1

include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
By default the directories specified are appended onto the current list of directories. This default behavior can be changed by setting CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFOREexplicitly, you can select between appending and prepending, independent of the default.

Specify directories in which the linker will look for libraries.
1

link_directories(directory1 directory2 ...)
Note that this command is rarely necessary. Library locations returned by find_package() and find_library() are absolute paths. Pass these absolute library file paths directly to the target_link_libraries() command. CMake will ensure the linker finds them.

Specify libraries or flags to use when linking a given target and/or its dependents.
1

target_link_libraries(<target> ... <item>... ...)
The named <target> must have been created in the current directory by a command such as add_executable() or add_library() and must not be an ALIAS target.

Each <item> may be: a library target name; a full path to a library file; a debug, optimized, or general keyword immediately followed by another .
1 2 3 4

include_directories(/usr/local/include/hello) target_link_libraries(main /usr/local/lib/libhello.so) # target_link_libraries(main /usr/local/lib/libhello.a)

Finds and loads settings from an external project. <package>_FOUND will be set to indicate whether the package was found.

1
2
3
4


find_package(<package> [version] [EXACT] [QUIET] [MODULE]
             [REQUIRED] [[COMPONENTS] [components...]]
             [OPTIONAL_COMPONENTS components...]
             [NO_POLICY_SCOPE])

The REQUIRED option stops processing with an error message if the package cannot be found.

The command has two modes by which it searches for packages: “Module” mode and “Config” mode.

CMake searches for a file called Find<package>.cmake in the CMAKE_MODULE_PATH followed by the CMake installation in module mode. If no module is found and the MODULE option is not given the command proceeds to Config mode. The CONFIG option may be used to skip Module mode explicitly and switch to Config mode.

This command is used to find a library.

1

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

Table of Contents