CMake Getting Started Tutorial

CMake Getting Started Tutorial

Reference: http://www.ibm.com/developerworks/cn/linux/l-cn-cmake/index.html

Official website: http://www.cmake.org/

Download URL: http://www.cmake.org/download/

Current version: 3.1RC3

This article was written based on the CMake 2.8 release.

CMake is a cross-platform, open-source build system (Buildsystem). CMake can generate a standard build file for a specific platform through the CMakeLists.txt file, for example: generating makefiles files for Unix platforms (using GCC compilation), generating projects/for Windows MSVC Workspaces (compiled with VS IDE) or makefile file (using NMAKE compilation).

CMake Hello World

Start by writing a simple program (HELLO.CPP):

#include <stdio.h>

int main ()

{

printf ("Hello World");

return 0;

}

Write the CMakeLists.txt and put it in the same directory as the Hello.cpp.

Project (Hello)

Cmake_minimum_required (VERSION 2.8)

Aux_source_directory (. DIR_SRCS)

Add_executable (Hello ${dir_srcs})

Create a build directory under the directory where CMakeLists.txt is located, and go to the directory to execute the CMake command to generate the building file:

Opens the Visual Studio 2008 Command Prompt window, which executes environment variables that load some vs.

mkdir Build

CD Build

Cmake-g "NMake makefiles". /

--The C compiler identification is MSVC 15.0.30729.1

--The CXX compiler identification is MSVC15.0.30729.1

....

--Detecting CXX compiler ABI Info

--Detecting CXX compiler ABI Info-done

--Configuring done

--Generating done

--Build files have been written to:i:/cmake-hello/build

The platform used here is Windows and installs Vs2008,cmake for us to build the VS2008 build file makefile, we can use NMAKE to build the application, execute:

Nmake

Microsoft (R) program Maintenance utilityversion 9.00.30729.01

Copyright (C) Microsoft Corporation. All rights reserved.

Scanning dependencies of target Hello

[100%] Building CXX Objectcmakefiles/hello.dir/hello.cpp.obj

Hello.cpp

Linking CXX executable Hello.exe

[100%] Built Target Hello

After the compilation completes successfully, the Hello application is generated under the current directory.

CMake Basic Syntax

The written CMakeLists.txt needs to conform to certain grammatical rules, which consist mainly of CMAKE commands.

1) Comment Syntax: comments in CMake use the # character to start to the end of this line.

2) CMake command: command is case-insensitive (arguments are case-sensitive), commands are composed of commands, parameter lists, and parameters are separated by spaces. Use a pair of double quotation marks to include a string that is considered to be a parameter. The command can be a built-in command (for example: project,add_executable, etc.) or a user-defined macro or function.

3) Data type: CMake The basic data type is a string, a set of strings together called a list, for example:

# Build a listvar with the set command

Set (VAR a B c)

Use Syntax ${variablename} to access the value of a variable named VariableName (the variable name is case sensitive). It is important to note that even in strings you can use ${variablename} to access the value of a variable:

Set (VAR a B c)

# Output VAR = A;b;c

Message ("VAR = ${var}")

Use the syntax $ENV {VariableName} to access the value of the environment variable (env{variablename} indicates the environment variable itself)

# outputs the value of the environment variable PATH

Message ($ENV {PATH})

4) Condition control and cyclic structure

Conditional control command for if command

if (expression)

#...

ElseIf (expression2)

#...

Else ()

#...

endif ()

For if (string):

If string is (case-insensitive) 1, ON, YES, TRUE, Y, and not 0, the number represents true

If string is (case-insensitive) 0, off, no, FALSE, N, IGNORE, empty string, string ending with-notfound, the false

String is considered to be the name of a variable if the string does not conform to either of the above cases. The value of the variable is false for each value described in the second article, otherwise it is true.

# This policy was introduced in CMake2.8.0

# So here you need to specify a minimum CMake version of 2.8

Cmake_minimum_required (VERSION 2.8)

Set (YES 0)

# Output True

if (YES)

Message (True)

Else ()

Message (False)

endif ()

# Output False

if (${yes})

Message (True)

Else ()

Message (False)

endif ()

An expression can contain operators, including the following:

Unary operators, for example: EXISTS, COMMAND, DEFINED, etc.

Binary operators, for example: EQUAL, less, GREATER, strless, Strgreater, etc.

Not (non-operator)

and (with operator), or (or operator)

Operator precedence: unary operator > two-tuple operator > Not > and, or

Common operators introduce:

if (not expression)

The real premise is that expression is false.

if (EXPR1 and EXPR2)

The real premise is that both Expr1 and EXPR2 are true.

if (expr1 OR expr2)

The real premise is that EXPR1 or EXPR2 is true.

if (COMMAND command-name)

Is true if there is a command-name command, macro, or function that can be called

if (EXISTS name)

The true premise is that there is a file or directory with name (absolute path should be used)

if (file1 Is_newer_than file2)

The premise is that File1 has a file that does not exist in file2 new or file1, file2 (absolute path should be used)

if (Is_directory directory-name)

The real premise is that Directory-name represents a directory (absolute path should be used)

if (variable|string MATCHES regex)

True if the value of a variable or string matches a regex regular expression

if (variable|string less variable|string)

if (variable|string GREATER variable|string)

if (variable|string EQUAL variable|string)

True if the value of a variable or string is a valid number and satisfies a condition less than (greater than, equal to)

if (variable|string strless variable|string)

if (variable|string strgreatervariable|string)

if (variable|string strequalvariable|string)

True if the value of a variable or string satisfies a condition less than (greater than, equal to) in a dictionary order

if (DEFINED variable)

The true premise is that the variable represented by the variable is defined.

Example of a Foreach loop:

Set (VAR a B c)

foreach (f ${var})

Message (${f})

Endforeach ()

While loop example:

Set (VAR 5)

while (${var} GREATER 0)

Message (${var})

Math (EXPR VAR "${var}-1")

Endwhile ()

5) Functions and macro definitions

The function creates a local scope for the variable, and the macro uses the global scope. Example:

# define a macro Hello

Macro (Hello MESSAGE)

Message (${message})

Endmacro ()

# Call Macro Hello

Hello ("Hello World")

# define a function Hello

function (Hello MESSAGE)

Message (${message})

Endfunction ()

Functions and macros can be returned through the command return (), but the return values of functions and macros must be passed through parameters. For example:

Cmake_minimum_required (VERSION 2.8)

function (Get_func RESULT)

The value of the #RESULT is the value of the argument, so you need to use ${result}

#这里使用 Parent_scope because the function constructs a local scope

Set (${result} "Hello Function" Parent_scope)

Endfunction ()

Macro (Get_macro RESULT)

Set (${result} "Hello Macro")

Endmacro ()

Get_func (V1)

# Output Hello Function

Message (${V1})

Get_macro (V2)

# Output Hello Macro

Message (${v2})

7) Some problems with strings

Strings can span lines and support the transfer of characters, for example:

Set (VAR "Hello

World ")

# The output results are:

# ${var} = Hello

# World

Message ("\${var} = ${var}")

CMake Common Commands

Here are some common commands (the CMake 2.8 command can be queried here):

Http://www.cmake.org/cmake/help/v2.8.8/cmake.html#section_Commands

1) Project command

Command syntax: Project (<projectname> [languageName1 languageName2 ...])

Command brief: The name used to specify the project

Usage Example: Project (Main)

2) cmake_minimum_required command

Command syntax: cmake_minimum_required (VERSION Major[.minor[.patch[.tweak]]][fatal_error])

Command brief: The minimum version used to specify the desired CMake

Example of Use: cmake_minimum_required (VERSION 2.8)

3) aux_source_directory command

Command syntax: aux_source_directory (<dir> <variable>)

Command brief: Used to save the names of all source files under the Dir directory in the variable variable

Usage Example: aux_source_directory (. DIR_SRCS)

4) add_executable command

Command syntax: add_executable (<name> [WIN32] [Macosx_bundle][exclude_from_all] source1 source2 ... sourcen)

Command brief: Used to specify a set of source files Source1 source2 ... sourcen compiles an executable file named name

Usage Example: add_executable (Main ${dir_srcs})

5) Add_library Command

Command syntax: add_library ([STATIC | SHARED | MODULE] [Exclude_from_all] source1source2 ... sourcen)

Command brief: Used to specify a set of source files Source1 source2 ... sourcen compiles a library file and is named name

Usage Example: Add_library (Lib ${dir_srcs})

6) add_dependencies Command

Command syntax: add_dependencies (target-name depend-target1 Depend-target2 ...)

Command summary: Used to specify that a target (executable or library file) depends on other targets. The goal here must be the target of add_executable, add_library, add_custom_target command creation.

7) Add_subdirectory Command

Command syntax: add_subdirectory (Source_dir [Binary_dir] [Exclude_from_all])

Command brief: To add a subdirectory that needs to be built

Usage Example: Add_subdirectory (LIB)

8) target_link_libraries Command

Command syntax: target_link_libraries (<target> [Item1] [ITEM2 [...]] [[Debug|optimized|general]] ...)

Command brief: Used to specify target needs to link item1 item2 .... The target must have been created here, and the linked item can be a target that already exists (the dependency will be added automatically)

Usage Example: target_link_libraries (Main Lib)

9) Set command

Command syntax: Set (<variable> <value> [[CACHE <type><docstring> [Force]] | Parent_scope])

Command summary: The value that is used to set the variable variable. If the cache variable is specified, it is placed in the cache.

Use example: Set (ProjectName Main)

) unset command

Command syntax: unset (<variable> [CACHE])

Command brief: For removing variable variable. If the cache variable is specified, it will be removed from the cache.

Usage Example: unset (VAR CACHE)

One) Message command

Command syntax: Message ([status| Warning| Author_warning| fatal_error| Send_error] "message todisplay" ...)

Command brief: For output information

Usage Example: Message ("Hello World")

) include_directories command

Command syntax: include_directories ([after| Before] [SYSTEM] dir1 dir2 ...)

Command summary: Used to set the directory, these settings of the directory will be used by the compiler to find the include file

Usage Example: include_directories (${project_source_dir}/lib)

) Find_path command

Command syntax: Find_path (<VAR> name1 [path1 path2 ...])

Command summary: Used to find the path containing the file name1, if found, save the path in VAR (this path is an absolute path), and if not found, the result is <var>-notfound. By default, Var is saved in the Cache, and we need to clear Var to make the next query (using the unset command).

Examples of Use:

Find_path (Lua_include_path Lua.h${lua_include_find_path})

if (not Lua_include_path)

Message (send_error "Header file lua.h not found")

endif ()

) find_library command

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

Command brief: The path used to find the library file name1, if found, save the path in VAR (this path is an absolute path) and the result is <var>-notfound if it is not found. A similar command link_directories has been less recommended to use

) add_definitions command

Command syntax: add_definitions (-dfoo-dbar ...)

Command brief: Used to add compiler command-line flags (options), which we typically use to add preprocessor definitions

Usage Example: add_definitions (-d_unicode-dunicode)

) execute_process command

Command syntax:

Execute_process (COMMAND <cmd1>[args1 ...])

[COMMAND <cmd2>[args2 ...] [...]]

[Working_directory<directory>]

[TIMEOUT <seconds>]

[Result_variable<variable>]

[Output_variable<variable>]

[Error_variable<variable>]

[Input_file <file>]

[Output_file <file>]

[Error_file <file>]

[Output_quiet]

[Error_quiet]

[Output_strip_trailing_whitespace]

[Error_strip_trailing_whitespace])

Command summary: Used to execute one or more external commands. The standard output for each command passes through the pipeline to the standard input for the next command. Working_directory is used to specify the working directory of the External command, result_variable is used to specify a variable to hold the result of the external command execution, which may be the exit code of the last external command executed or a string that describes the error condition, OUTPUT _variable or error_variable is used to specify a variable to hold standard output or standard error, output_quiet or error_quiet to ignore standard output and standard error.

Usage Example: execute_process (COMMAND ls)

) File command

Command brief: This command provides rich file and directory related operations (here is just a few more commonly used)

Examples of Use:

# Traversal of the Directory

# GLOB is used to generate a list of file (directory) paths and save in variable

# The file name of each file in the path list can match globbing expressions (not regular expression, but similar)

# If the RELATIVE path is specified, the path in the returned file path list is relative to the RELATIVE path

# file (GLOB variable [RELATIVE path][globbing expressions] ...)

# get the path to all the files (directories) in the current directory and save them in the All_file_path variable

File (GLOB all_file_path./*)

# get the file name of the. h file in the current directory and save it to the All_h_file variable

# The variable cmake_current_list_dir here indicates the absolute path of the directory where the CMakeLists.txt file is being processed (2.8.3 and later versions are supported)

File (GLOB all_h_file relative${cmake_current_list_dir} ${cmake_current_list_dir}/*.h)

CMake Common variables

UNIX If True, represents a unix-like system, including Appleos X and CygWin

WIN32 If true, it is represented as a Windows system, including CygWin

If Apple is true, it is represented as an Apple system

Cmake_sizeof_void_p represents the size of the void* (for example, 4 or 8), which can be used to determine whether the current build is 32-bit or 64-bit

Cmake_current_list_dir indicates the absolute path of the directory in which the CMakeLists.txt file is being processed (2.8.3 and later versions are supported)

Cmake_archive_output_directory the output path used to set the ARCHIVE target

Cmake_library_output_directory the output path used to set the LIBRARY target

Cmake_runtime_output_directory the output path used to set the RUNTIME target

Build Type

CMake provides us with four types of build:

Debug

Release

Minsizerel

Relwithdebinfo

If you use CMake to generate projects/workspaces for Windows MSVC then we will get the 4 solution configurations described above.

If you use CMake to generate Makefile, we need to do some different things. There is a variable cmake_build_type in CMake that specifies the build type, which is used only for make-based generators. We can specify the build type like this:

$ cmake-dcmake_build_type=debug.

The value of Cmake_build_type here is one of the 4 build types mentioned above.

Compile and link flags

C compile flag related variables:

Cmake_c_flags

Cmake_c_flags_[debug| release| minsizerel| Relwithdebinfo]

C + + compiler flags related variables:

Cmake_cxx_flags

Cmake_cxx_flags_[debug| release| minsizerel| Relwithdebinfo]

Cmake_c_flags or cmake_cxx_flags can specify a compile flag

Cmake_c_flags_[debug| release| minsizerel| Relwithdebinfo] or Cmake_cxx_flags_[debug| release| minsizerel| Relwithdebinfo] Specifies the compilation flags for a particular build type, which will be added to the cmake_c_flags or cmake_cxx_flags, for example, if the build type is DEBUG, then Cmake_cxx_flags_ DEBUG will be added to the cmake_cxx_flags.

Link Flag Related variables:

Cmake_exe_linker_flags

Cmake_exe_linker_flags_[debug| release| minsizerel| Relwithdebinfo]

Cmake_module_linker_flags

Cmake_module_linker_flags_[debug| release| minsizerel| Relwithdebinfo]

Cmake_shared_linker_flags

Cmake_shared_linker_flags_[debug| release| minsizerel| Relwithdebinfo]

They are similar to compiler flags related variables

Generate Debug and Release versions

In Visual Studio we can generate the debug version and release version of the program, using CMake we can also achieve the above effect. The debug version of the project generates executable files that require debugging information and do not need to be optimized, while the release version does not require debugging information but needs to be optimized. These attributes are determined by the compile-time parameters in gcc/g++, and if the tuning level is tuned to the maximum required to set the parameter-o3, the minimum is-o0 is not optimized; The parameter to add debug information is-g-ggdb, and if you do not add this parameter, the debug information will not be included in the generated binaries.

There is a variable cmake_build_type in CMake that can be used for Debug, Release, Relwithdebinfo, and Minsizerel. When the value of this variable is Debug, CMake uses the string in the variable cmake_cxx_flags_debug and Cmake_c_flags_debug as the compilation option to generate the makefile, when the variable value is Release, The project generates Makefile using the variable cmake_cxx_flags_release and cmake_c_flags_release options.

Example:

PROJECT (Main)

Cmake_minimum_required (VERSION 2.6)

SET (Cmake_source_dir.)

SET (cmake_cxx_flags_debug "$ENV {cxxflags}-o0-wall-g-ggdb")

SET (cmake_cxx_flags_release "$ENV {cxxflags}-o3-wall")

Aux_source_directory (. DIR_SRCS)

Add_executable (main ${dir_srcs})

Lines 5th and 6 set two variables cmake_cxx_flags_debug and Cmake_cxx_flags_release, which are compilation options for DEBUG and RELEASE respectively. You need to execute the ccmake command to generate Makefile after editing CMakeList.txt. At the root of the entry, enter "Ccmake." Into a graphical interface.

Compiling 32-bit and 64-bit programs

For Windows MSVC, we can set CMake Generator to determine whether to generate Win32 or Win64 engineering files, for example:

# for building Visual Studio 10win64 project files

Cmake-g "Visual Studio ten Win64"

# for building Visual Studio 10win32 project files

Cmake-g "Visual Studio 10"

We can view the Generator available on the current platform through CMake--help.

CMake. -duse_32bits=1

if (use_32bits)

Message (STATUS "Using 32bits")

Set (cmake_c_flags "${cmake_c_flags}-m32")

Set (cmake_cxx_flags "${cmake_cxx_flags}-m32")

Else ()

endif (Use_32bits)

For Unix and Unix-like platforms, we can control whether 32-bit or 64-bit builds are made through compiler flags (options).

GCC command-line arguments

32-bit version: Add the-m32 parameter to generate 32-bit code.

64-bit version: Add the-m64 parameter to generate 64-bit code.

Debug version: Add the-G parameter to generate debug information.

Release version: Add the-static parameter, static link, so that the program no longer dependent on the dynamic library. Plus the-o3 parameter for fastest speed optimization. Add the-dndebug parameter, define the Ndebug macro, and mask the assertion.

When there is no-m32 or-m64 parameter, code that is consistent with the operating system's number of bits is normally generated, but some compilers have exceptions, such as-

GCC, under 32-bit Linux, is compiled to 32-bit code by default.

GCC, under 64-bit Linux, is compiled to 64-bit code by default.

The MinGW under the window system is always compiled into 32-bit code. Because MinGW only supports 32-bit code.

The MINGW-W64 under the window system (for example, TDM-GCC is installed, Mingw-w64 is selected), and by default it is compiled into 64-bit code, which is included under 32-bit Windows systems.

Examples in the makefile file:

# [args] build mode. 0 for debug mode, 1 for release mode. Makerelease=1.

Ifeq ($ (RELEASE), 0)

CFLAGS + =-G

Else

#release

CFLAGS + =-static-o3-dndebug

Lflags + =-static

endif

# [Args] The number of program bits. 32 represents a 32-bit program, 64 represents a 64-bit program, and other defaults. Makebits=32.

Ifeq ($ (BITS), 32)

CFLAGS + =-m32

Lflags + =-m32

Else

Ifeq ($ (BITS), 64)

CFLAGS + =-m64

Lflags + =-m64

Else

endif

endif

How to handle a multi-source file directory

We will place a CMakeLists.txt file in each source directory. We now assume that there is such a project:

HelloWorld

|

+-------Main.cpp

|

+-------CMakeLists.txt

|

+-------Lib

|

+-------Lib.cpp

|

+-------Lib.h

|

+-------CMakeLists.txt

The files in the Lib directory will be compiled into a library. First, let's look at the CMakeLists.txt file in the Lib directory:

Aux_source_directory (. DIR_SRCS)

Add_library (Lib ${dir_srcs})

Then, take a look at the CMakeLists.txt file in the HelloWorld directory:

Project (Main)

Cmake_minimum_required (VERSION 2.8)

Add_subdirectory (LIB)

Aux_source_directory (. DIR_SRCS)

Add_executable (Main ${dir_srcs})

Target_link_libraries (Main Lib)

Here, Add_subdirectory is used to specify the subdirectories that need to be built, and the target_link_libraries command is used to indicate that the Main executable requires a link to the Lib library. We execute CMake. command, the command in CMakeLists.txt in the HelloWorld directory is executed first, and when executed to the Add_subdirectory (Lib) command, it enters the Lib subdirectory and executes the CMakeLists.txt file.

External build (out of source builds)

We execute CMake in the directory where the CMakeLists.txt is located. Will generate a lot of files, these files and our source files mixed together bad management, we use the external constructs the way to solve this problem. Explain it with the Hello World project above:

Build a build directory under the HelloWorld directory (build directory can be built in how to place)

Go to the build directory and build it externally CMake. (Syntax is the path of CMake <cmakelists.txt; CMake is used here.) Indicates that the CMakeLists.txt is in the parent directory of the Build directory). This CMake will generate the file in the build directory.

CMake Getting Started Tutorial