Summary of “cmake practice”: CMake Build Process and Basic Commands

Zero. Basic Syntax Rules

0.1 Variables

  Variables are referenced using ${VALUENAME}, but variable names are used directly in IF control statements.

1. CMAKE_BINARY_DIR, PROJECT_BINARY_DIR, and <ProjectName>_BINARY_DIR all represent the build directory. For an in-source build, this is the top-level project directory; for an out-of-source build, it is the directory where the project is built.
2. CMAKE_SOURCE_DIR, PROJECT_SOURCE_DIR, and <ProjectName>_SOURCE_DIR all represent the top-level project directory.
3. CMAKE_CURRENT_SOURCE_DIR: Represents the path containing the CMakeLists.txt currently being processed.
4. CMAKE_CURRENT_BINARY_DIR: For an in-source build, this is the same as CMAKE_CURRENT_SOURCE_DIR; for an out-of-source build, it represents the target build directory.
5. CMAKE_CURRENT_LIST_FILE: The full path to the CMakeLists.txt containing this variable.
6. CMAKE_CURRENT_LIST_LINE: The line containing this variable.
7. CMAKE_MODULE_PATH: Defines the path containing CMake modules.
8. EXECUTABLE_OUTPUT_PATH and LIBRARY_OUTPUT_PATH: Redefine the output directories for the final results, respectively.
9. PROJECT_NAME: The project name.

0.2 Command Rules

  1. The basic syntax is: command(argument 1 argument 2 …)   2. Arguments are separated by spaces or semicolons, for example, ADD_EXECUTABLE(hello main.c;func.c).   3. Commands are case-insensitive, while arguments and variables are case-sensitive, but using uppercase for all commands is recommended.   4. When a filename contains spaces, double quotes must be used, for example, SET(SRC_LIST "fu nc.c").

0.3 Basic Build Process

  1. Write the program and the CMakeLists.txt file.   2. Create an out-of-source build directory: mkdir build   3. Enter the out-of-source build directory: cd build   4. Build the project: cmake ..   5. Perform the actual build: make   6. Run the program: ./<Executable Filename>   7. Clean the project: make clean

One. Basic Commands

1. PROJECT Command

PROJECT(projectname [CXX] [C] [Java])
# 例：PROJECT(HELLO)

  Defines the project name and can specify the languages supported by the project. All languages are supported by default. This command implicitly defines two variables: PROJECT_BINARY_DIR and PROJECT_SOURCE_DIR.

2. SET Command

SET(VAR [VALUE] [CACHE TYPE DOCSTRING [FORCE]])
# 例1：SET(SRC_LIST main.c)
# 例2：SET(EXECUTABLE_OUPUT_PATH ${PROJECT_BINARY_DIR}/bin)

  Used to explicitly define variables.   In the CMakeLists.txt file containing ADD_EXECUTABL, adding the statement shown in Example 2 changes the output path of the final target binary to build/bin.

3. MESSAGE Command

MESSAGE([SEND_ERROR | STATUS | FATAL_ERROR] "message to display")
# 例：MESSAGE(STATUS "This is BINARY dir ${HELLO_BINARY_DIR}")

  Used to output user-defined information to the terminal. There are three types:

• SEND_ERROR: Generates an error and skips the generation process.
• STATUS: Outputs information prefixed with -.
• FATAL_ERROR: Immediately terminates all CMake processes.

4. ADD_EXECUTABLE Command

ADD_EXECUTABLE(<Executable Filename> ${SRC_LIST})
# 例：ADD_EXECUTABLE(hello ${SRC_LIST})

  Specifies that the project will generate an executable named <Executable Filename>. Its source files are the list of source files defined in SRC_LIST.

5. ADD_SUBDIRECTORY Command

ADD_SUBDIRECTORY(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
# 例：ADD_SUBDIRECTORY(src bin)

  Used to add a subdirectory to the current project and optionally specify where its binary files are stored. EXCLUDE_FROM_ALL means excluding this directory from the build process. (For example, if the src subdirectory is added to the project and the build output path is specified as bin, all build results will be placed in build/bin.)

6. INSTALL Command

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>]
         [NAMELINK_COMPONENT <component>]
         [OPTIONAL] [EXCLUDE_FROM_ALL]
         [NAMELINK_ONLY|NAMELINK_SKIP]
        ] [...]
        [INCLUDES DESTINATION [<dir> ...]]
        )
# 例：INSTALL(FILES COPYRIGHT README DESTINATION share/doc/cmake/test)
# 例：INSTALL(PROGRAMS runprog.sh DESTINATION bin)

  The INSTALL command is used to install various types of files. The TARGETS argument identifies the files to install, which can be binaries, shared libraries, or static libraries. Once the INSTALL commands have been written in the respective CMakeLists.txt files, the installation can begin.   The installation process is as follows:

	cmake -DCMAKE_INSTALL_PREFIX=<Install Path>
	make
	make install

7. ADD_DEPENDENCIES Command

ADD_DEPENDENCIES(target-name depend-target1 depend-target2 ...)

  Defines the other targets that target depends on, ensuring that those targets have already been built before this project is compiled.

8. ADD_TEST and ENABLE_TESTING Commands

ADD_TEST(testname Exename arg1 arg2 ...)
ENABLE_TEST()

  Used to create a test target. After the makefile is generated, it can be tested with make test.

9. EXEC_PROGRAM

EXEC_PROGRAM(Executable
			[directory in which to run]
			[ARGS <arguments to executable>]
			[OUTPUT_VARIABLE <var>]
			[RETURN_VALUE <var>])

  Used to specify that a program should run in a particular directory.

Three. Building and Using Static and Shared Libraries

3.1 How to Build Static and Shared Libraries

  1. Create a new lib folder in the project directory and add it to the project directory.

# 工程目录下的CMakeLists.txt
PROJECT(HELLOLIB)
ADD_SUBDIRECTORY(lib)

  2. Create the source files in the lib folder.   3. In the lib directory, create a CMakeLists.txt.

SET(LIBHELLO_SRC hello.c)
#创建动态库
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 VERSION 1.2 SOVERSION 1)
#安装共享库和头文件
INSTALL(TARGETS hello hello_static LIBRARY DESTINATION lib ARCHIVE DESTINATION lib)
INSTALL(FILES hello.h DESTINATION include/hello)

  4. Install the shared library and header files.

cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
make
make install

3.2 Using External Shared Libraries and Header Files

  1. Create a src directory in the new project directory and write the source file main.c in it.   2. Write the project directory’s CMakeLists.txt.

PROJECT(NEWHELLO)
ADD_SUBDIRECTORY(src)

  3. Write the src directory’s CMakeLists.txt.

ADD_EXECUTABLE(main main.c)
# 添加头文件搜索路径
INCLUDE_DIRECTORIES(/usr/include/hello)
# 将目标文件链接到共享库
TARGET_LINK_LIBRARIES(main libhello.so)
# 或：TARGET_LINK_LIBRARIES(main hello)
# 或链接到静态库：TARGET_LINK_LIBRARIES(main libhello.a)

  4. Build and run.

cd build
cmake ..
make

Referenced from cmake practice