Useful Sticky Notes

Monday, August 11, 2014

Getting Started with Cmake by Kitware

Having worked with HPC codes for the better part of 10 years, I am a little ashamed to say that I am only just starting to learn to use cmake. Better late than never, however.

This post serves as a cmake primer of sorts. I was very much brand-new to cmake, and wanted to start with a very simple example.

Unfortunately, the cmake tutorial by Kitware is actually a part of their book "Mastering Cmake," and not really designed to be read standalone. As such they started with a simple example, but proceeded to add complexity to that example without explaining (I assume it had been covered in the preceding chapters of the book) how one uses cmake to build the binary executables for that example. Anyway, here it is:

http://www.cmake.org/cmake/help/cmake_tutorial.html

It wasn't too difficult to figure out that one just ran "cmake ." where the CMakeLists.txt file was located, followed by "make." However, that had created a mess of temporary files at the folder. The latest forum posts online still indicate that no "cmake clean" feature exists for the reverse process. What I desired was to keep only the "true" sources for archive in a code repository. For that, I needed to apply cmake's support for out-of-source builds. This idiom for building tools/applications separates the source code from the build tree, with the tree's attendant temporary files like object files, temporarily generated code, etc. I believe this is the only idiom serious code developers should use for their build systems. It really is best-practice.

To find out how cmake supports out-of-source builds, I found a good (but a little bit complicated) primer on:

http://web.cs.swarthmore.edu/~adanner/tips/cmake.php

With these instructions, I was able to construct a very simple out-of-source example using Kitware's first tutorial code, combined with the necessary structure. This included two shell scripts to avoid some steps in this idiom which I felt introduced potential sources for error, which can mess up the folder.

My top level folder:

CMakeLists.txt
app
build.sh
clean.sh

The CMakeLists.txt file contains only the preamble, along with how to locate the source:

cmake_minimum_required (VERSION 2.6)
project (OutOfSourceTutorial)

add_subdirectory(app)


The app folder holds the source code file tutorial.C, and the CMakeLists.txt file which tells cmake how to build tutorial.C:

add_executable(Tutorial tutorial.C)

The build.sh script sets up the build folder, and invokes cmake on the top-level CMakeLists.txt file from the build folder. make can then be invoked to build the executable Tutorial. These are the steps which I found to be potential for error if they had to be done manually:

#!/bin/bash                                                                                        
mkdir build
cd build
cmake ..
make


Notes:

1. I had initially named the "app" folder "src," which was intuitive as I had always developed my codes with a "src" folder to a hold pure source code. However, the cmake implementation of this idiom names a build sub-folder the exact same name as its source counterpart. This meant a "src" folder would appear under "build." This offended my senses. I did realize however, that the idiom intended the source folder to be named after the application/tool (or part thereof.) After all, if the folder is already meant to hold only the source files under this idiom, it would be an oxymoron to call it "src."

2. The binary executable Tutorial is built into build/app rather than my expectation of something like build/bin. I am assuming this is because the developers of cmake did not wish to enforce any naming conventions, and that Cpack would take care of creating the necessary include, lib, bin, and man folders for Linux systems that I am familiar with.

No comments:

Post a Comment