Project setup tutorial (using cmake)

In this tutorial we will set up a project that uses sc and CMake to compile and run the fibonacci example. No prior knowledge of CMake is assumed, but good programming skills are. We will not cover any code, based on the assumption that the reader is able to read through the well-commented code already.

Prerequisites

• CMake 3.3+
• Git

Setup

First create a folder to contain our fibonacci program. Let's name it fibonacci.

# current dir is ~
mkdir fibonacci
cd fibonacci

Check out sc within this new folder, so we can directly reference its CMakeLists.txt.

# current dir is ~/fibonacci
git clone https://github.com/rhoot/sc.git

And finally, copy out the fibonacci.c file from within sc/examples as we plan on using it as the program source.

# current dir is ~/fibonacci
cp sc/examples/fibonacci.c fibonacci.c

Creating CMakeLists.txt

Create a file with the name CMakeLists.txt within the new fibonacci folder, and open it in your preferred editor. This will be the complete contents:

cmake_minimum_required(VERSION 3.3)
project(fibonacci)
enable_language(C)

# sc
add_subdirectory(sc)
set_target_properties(sc_tests PROPERTIES EXCLUDE_FROM_ALL 1 EXCLUDE_FROM_DEFAULT_BUILD 1)

# fibonacci
add_executable(fibonacci fibonacci.c)
target_include_directories(fibonacci PUBLIC include)
target_link_libraries(fibonacci PUBLIC sc)

Let's go through that code section by section, starting with the header:

cmake_minimum_required(VERSION 3.3)
project(fibonacci)
enable_language(C)

This sets up basic project properties. First we tell CMake which version of it is required for our CMakeLists.txt. As 3.3 is the lowest version currently supported by sc, that is the version we will use as well. We then give the project a name (fibonacci), and tell CMake we will be compiling C code.

# sc
add_subdirectory(sc)
set_target_properties(sc_tests PROPERTIES EXCLUDE_FROM_ALL 1 EXCLUDE_FROM_DEFAULT_BUILD 1)

This is all that's required to tell CMake that we want to build sc as well. The first line tells it to process any CMakeLists.txt files within the sc folder. sc has its own CMakeLists.txt, so we don't have to write our own.

The second line may not be quite as straight forward. The sc repository contains two targets in its CMakeLists.txt: sc, and sc_tests. The former is the library itself, while the latter is its unit tests. As we only want to link with sc however, we do not care about the unit tests, and can exclude it from our project to reduce build times and compiler output noise. This is done by setting the EXCLUDE_FROM_ALL and EXCLUDE_FROM_DEFAULT_BUILD properties on the target. Regardless of what one might think going by the name of the former property, both are required to exclude the target in all configurations.

# fibonacci
add_executable(fibonacci fibonacci.c)
target_link_libraries(fibonacci sc)

Finally we set up our fibonacci target itself. The first line defines the target as being an executable named fibonacci, made up by the given source files. The only source file in our case is fibonacci.c. After that we tell cmake that our newly defined fibonacci target needs to link with the sc target for its symbols.

Compiling and running

Save your CMakeLists.txt file, and let's generate some build files! CMake supports "out of source" builds, which means you don't need to have build output files littered all over your source files. This also means it's easy to clean up the build, as you can just delete the build folder. To use an "out of source" build, create a new folder and invoke CMake from within that folder.

# current dir is ~/fibonacci
mkdir build
cd build
cmake ..

The .. tells cmake our source — with the CMakeLists.txt file — is located one folder up. This should generate some system appropriate build files in the build folder. If you are using Visual Studio, you can now open the generated fibonacci.sln file and build it. If you are not using Visual Studio it's likely makefiles were generated, and running make would build everything.

Hopefully you now have an executable named fibonacci (fibonacci.exe on Windows) within your build folder, and running it should output:

0
1
1
2
3
5
8
13
21
34