CMake is a cross platform build system for automatically compiling source code. It is similar to using Makefiles, but CMake is first used to automatically configure and build a Makefile from a CMakeLists.txt description. Once this file is built, you can use normal make command. Let's say we have a project with a top level CMakeLists.txt file. To configure the initial build, we first make a separate build directory. Then we run cmake followed by make.

$ cd ~cs40/examples
[examples]$ mkdir build
[examples]$ cd build
[build]$ cmake .. 
[build]$ make -j8

If we already have a build directory and have previously run cmake .., we do not need to run cmake again. We can just run make in any of the subdirectories of the build folder. Having a separate build directory might be new to some, so here is a short explanation using the figure below for a project in the examples folder The green subdirectory above contains all source code you write. It is the contents of your creative efforts. You would find .cpp files, .h files, .ui files, and all the files managed by git in this folder. Each folder in this green subtree will usually have an accompanying CMakeLists.txt file which describes what files to compile and what executables to build.

Separate from the green folders are the build directories. Let's focus on the one on the right labeled cmake build. The contents of these subfolders are generated automatically by cmake, make and the compiler, using the CMakeLists.txt files in the green source tree as instructions. Since these files can be automatically generated from the green source tree, there is no need to include them in git. In fact, the .gitignore file in the source tree is usually set to ignore the entire build directory.

This design has a number of advantages:

• Automatically built files are separated from the source tree.
• By not polluting the source tree, we avoid accidentally committing auto-generated files to git
• By not committing auto-generated files to git, we reduce git repo bloat and reduce the chance of merge conflicts
• If needed, we can have multiple builds in separate build directories, e.g., a build with debug symbols or a build optimized for release.
• We can safely remove the entire build directory to save space and return to a clean source tree

The primary disadvantage of using a separate build directory is that it can sometimes get confusing if we are in the build tree or the source tree. Additionally it can be confusing to know where to run make or cmake. The figure above should help reduce confusion.

Only run cmake .. in a top level build directory

Don't run cmake directly in your src tree. It may work, but it will create a bunch of auto-generated files in your source tree that may be hard to remove manually. If you did not set your .gitignore file to ignore these auto-generated files and directories, it may be difficult to discern what changes were made by you and which were made by cmake.

To avoid this problem, first create an empty build directory and cd into that directory. Next run cmake followed by the path to top-level CMakeLists.txt. In this case, it would be the CMakeLists.txt file in the examples directory. The figure above shows two cases.

In the first case, we made the build directory inside the examples folder. This is the style I use in class.

$ cd ~cs40/examples
[examples]$ mkdir build
[examples]$ cd build
[build]$ cmake .. 
[build]$ make -j8

In the second case, we made a build-examples-Desktop-Default directory at the same depth as the examples folder. QtCreator prefers this style by default, though you can configure these preferences. In essence QtCreator did the following

$ cd ~cs40/
[cs40]$ mkdir build-examples-Desktop-Default
[cs40]$ cd build-examples-Desktop-Default
[build-examples-Desktop-Default]$ cmake ../examples
[build-examples-Desktop-Default]$ make -j8

Note that the cmake command in this case is ../examples as we have to go back one directory (into ~/cs40) and then down into the examples folder to find the CMakeLists.txt folder.

Run make anywhere

Once you have run cmake, you do not need to run it again unless a) you create another build directory or b) your current build directory is destroyed or horribly broken. In either of these cases, follow the steps above and run cmake in the top level build directory.

CMake will create makefiles inside many of the folders inside a build directory and you can run make or make -j8 in any of these directories and it will do the right thing. You can even run make in your src tree, but since there is no Makefile in your source tree, only CMakeLists.txt files, nothing will happen.

If you have still have questions, feel free to follow up on Piazza and I'll try to update this document

Soon we will need to edit our CMakeLists.txt and I'll post instructions on how to do that here as well. Stay tuned.

Home Page

Last updated: Tuesday, September 22, 2020 at 01:07:44 PM