This section describes how to use CMake from the software developer‘s point of view. That is, if your aim is to use CMake to manage your build process, read this section first.
Input to CMake
COMMAND(args)
Where COMMAND is the name of the command, and args is a white-space separated list of arguments to the command. (Arguments with embedded white-space should be quoted.) Typically there will be a CMakeLists.txt file for each directory of the project. Let‘s start
with a simple example. Consider building hello world. You would have a source tree with the following files:
Hello.c CMakeLists.txt
The CMakeLists.txt file would contain two lines:
PROJECT (Hello)
ADD_EXECUTABLE(Hello Hello.c)
To build the Hello executable you just follow the process described in Running CMake above to generate the makefiles or Microsoft project files. The PROJECT command indicates what the name of the resulting workspace should be and the ADD_EXECUTABLE command
adds an executable target to the build process. That‘s all there is to it for this simple example. If your project requires a few files it is also quite easy, just modify the ADD_EXECUTABLE line as shown below.
ADD_EXECUTABLE(Hello Hello.c File2.c File3.c File4.c)
ADD_EXECUTABLE is just one of many commands available in CMake. Consider the more complicated example below.
# look for the Tcl library
FIND_LIBRARY(TCL_LIBRARY NAMES tcl tcl84 tcl83 tcl82 tcl80 PATHS /usr/lib /usr/local/lib)
IF (TCL_LIBRARY) TARGET_ADD_LIBRARY (Hello TCL_LIBRARY)
ENDIF (TCL_LIBRARY)
In this example the SET command is used to group together source files into a list. The IF command is used to add either WinSupport.c or UnixSupport.c to this list. And finally the ADD_EXECUTABLE command is used to build the executable with the files listed
in the source list HELLO_SRCS. The FIND_LIBRARY command looks for the Tcl library under a few different names and in a few different paths, and if it is found adds it to the link line for the Hello executable target. Note the use of the # character to denote
a comment line.
CMake always defines some variables for use within CMakeList files. For example, WIN32 is always defined on windows systems and UNIX is always defined for UNIX systems. CMake defines a number of commands. A brief summary of the most commonly used commands follows
here. Later in the document an exhaustive list of all pre-defined commands is presented. (You may also add your own commands, see the Extension Guide for more information.)
ADD_EXECUTABLE()
AUX_SOURCE_DIRECTORY()
PROJECT()
CMake works recursively, descending from the current directory into any subdirectories listed in the SUBDIRS command. The command SET is used for setting a variable, in this case to a list of source files. (Note: currently only C and C++ code can be compiled.)
ADD_LIBRARY adds a library to the list of targets this makefile will produce. ADD_EXECUTABLE adds an executable to the list of targets this makefile will produce. (Note: source code is compiled first, then libraries are built, and then executables are created.)
The AUX_SOURCE_DIRECTORY is a directory where other source code, not in this directory, whose object code is to be inserted into the current LIBRARY. All source files in the AUX_SOURCE_DIRECTORY are compiled (e.g. *.c, *.cxx, *.cpp, etc.). PROJECT (PojectName)
is a special variable used in the MSVC to create the project for the compiler, it also defines two useful variables for CMAKE: ProjectName_SOURCE_DIR and ProjectName_BINARY_DIR.
Build flags and options. In addition to the commands listed above, CMakeLists.txt often contain the following commands:
INCLUDE_DIRECTORIES()
LINK_DIRECTORIES()
LINK_LIBRARIES()
TARGET_LINK_LIBRARIES()
These commands define directories and libraries used to compile source code and build executables. An important feature of the commands listed above is that are inherited by any subdirectories. That is, as CMake descends through a directory hierarchy (defined
by SUBDIRS()) these commands are expanded each time a definition for a command is encountered. For example, if in the top-level CMakeLists file has INCLUDE_DIRECTORIES(/usr/include), with SUBDIRS(./subdir1), and the file ./subdir1/CMakeLists.txt has INCLUDE_DIRECTORIES(/tmp/foobar),
then the net result is
INCLUDE_DIRECTORIES(/usr/include /tmp/foobar)
CMake comes with a number of modules that look for commonly used packages such as OpenGL or Java. These modules save you from having to write all the CMake code to find these packages yourself. Modules can be used by including them into your CMakeList file
as shown below.
INCLUDE (${CMAKE_ROOT}/Modules/FindTCL.cmake)
CMAKE_ROOT is always defined in CMake and can be used to point to where CMake was installed. Looking through some of the files in the Modules subdirectory can provide good ideas on how to use some of the CMake commands.
Adding A New Directory to a project
A common way to extend a project is to add a new directory. This involves three steps: Create the new directory somewhere in your source directory hierarchy. Add the new directory to the SUBDIRS command in the parent directories CMakeLists.txt Create a CMakeLists.txt in the new directory with the appropriate commands
