cmkr/docs/concepts.md

layout	title	nav_order
page	Concepts	2

Concepts (TODO: rename to "Basics" or "Basic Concepts"?)

To effectively use cmkr it helps to understand the basic concepts of CMake.

Projects

A CMake project is a collection of targets. In the context of libraries the project usually corresponds to the package that other projects can depend on.

_{Visual Studio: a CMake project corresponds to a solution.}

Targets

The basic unit of CMake is called a target. A target (also referred to as binary target in the CMake documentation) corresponds to an executable or library you can build. There are also pseudo targets, but we ignore them for now.

_{Visual Studio: a target corresponds to a project.}

Target Properties

Targets have a collection of properties that describe how to build them.

Examples of properties:

• Sources: the *.cpp files used to build the target.
• Compile options: Command line flags for the compiler.
• Link libraries: The dependencies required to build this target.

_{See the CMake documentation for an exhaustive list of target properties.}

Important: The term link has a slightly different meaning in CMake than you might expect. In addition to adding a library to the command line of the linker, CMake also propagates properties of the target you link to.

_{You can think of linking as depending on.}

The propagation of properties depends on their visibility:

• Private: properties that are only used when building the target itself.
• Interface: properties that are used when depending on this target.
• Public: combination of private and interface.

In practice you default to private, unless consumers of your library require the property to build their target. In that case you use public.

Example

The most intuitive example is with include directories. Imagine there are two targets:

1. StringUtils: A library with string utilities.
   • Sources: StringUtils/src/stringutils.cpp
   • Include directories: StringUtils/include
2. DataProcessor: An executable that uses functionality from StringUtils to process some data.
   • Sources: DataProcessor/src/main.cpp
   • Link libraries: StringUtils

The include directories property of StringUtils has to be public. If it was private, the DataProcessor target would fail to #include <stringutils.hpp> since the include directories property is not propagated.

The cmake.toml for this example would look something like this:

[project]
name = "DataProcessor"

[target.StringUtils]
type = "static"
sources = ["StringUtils/src/stringutils.cpp"]
headers = ["StringUtils/include/stringutils.hpp"]
include-directories = ["StringUtils/include"]

[target.DataProcessor]
type = "executable"
sources = ["DataProcessor/src/main.cpp"]
link-libraries = ["StringUtils"]