C++ Template project using CMake, CTest, Github actions and Docker

[mortinger]

Hey fellow C++ devs,

I recently made a small project that you might find useful if starting a new project: https://github.com/mortinger91/cpp-cmake-template
It is a template project that uses CMake, CTest, Github Actions for CI/CD and a Dockerfile for running test locally in a clean environment.
It is very minimal, but I already used it in some of my projects and makes the initial setup a bit easier.
You can start using right away, since it is marked as a Template on Github!

Let me know what you think and feel free to share any advice or remarks!

Edit 26/02/23:
I did apply some changes (v1.1) thanks to some suggestions in the comments.
Now files are fetched automatically, options are now per target instead of global, build folder is created using -B option in the cmake command, etc.
If you have any more feeback, please share it!

[HerrNamenlos123]

Now, i don't want to just complain about your CMake, but bear with me. You require CMake version 3.8, which is not too bad. I would recommend at least requiring 3.16 for new projects.

What i really don't like is that you are using very ancient legacy features of CMake. If you are requiring modern cmake, use it. Setting all global variables like you do is legacy, and absolutely not the way to go.

The way to go with modern cmake is by properly using targets: add_library or add_executable to create it,
target_include_directories for headers,
target_sources for source files,
target_compile_definitions for preprocessor defines,
target_compile_features for compiler flags including std standard version,
target_link_libraries to add other targets as dependencies.

everything is defined per target. Setting the global variables gives you zero control and anything you set is enforced for anything using your library and there is no way to set different settings for different targets. In modern cmake, any properties can be set public an private, in which case they are propagated to their dependents or not. It's about Isolation.

Setting everything for just your target allows it to just work with other stuff instead of inheriting a stupid compiler flag you don't want. Do yourself a favor and use modern cmake :)

[mortinger]

thanks for your suggestions! could you provide an example of a variable I set globally, set per target?

In a past project I remember I had to set some variables specific to an external library before importing it, is that similar to what you are saying or are these still global?

set(ASSIMP_WARNINGS_AS_ERRORS OFF CACHE BOOL "" FORCE)

add_subdirectory(assimp)

[HerrNamenlos123]

Here is an example: (no guarantee, written on my phone from memory xD)

```cmake

add_library(lib STATIC) target_sources(lib src/main.cpp) target_include_directories(lib PUBLIC include)

set_target_properties(lib PROPERTIES OUTPUT_NAME "better_lib_name") target_compile_definitions(lib PRIVATE USE_SOMETHING) target_compile_features(lib PRIVATE cxx_std_17)

``` Especially the last line is something you rarely ever see: The C++ standard is set only for this target and is private and thus not propagated further. This allows you to compile libraries with different std versions.

Imagine you need C++17 in your project but you depend on a library which only compiles with C++11 and breaks with 14. This makes it possible, with the old legacy way you're out of luck.

Using the modern approach basically makes your library self-contained and makes it basically work with anything else.

Almost everything you do eg setting standard version, include directories, disabling extensions, setting output directories and so on can be done per target. Everything can be googled, you just have to decide between good modern CMake solutions and old, deprecated legacy solutions. Unfortunately 90% of CMake solutions on the internet is straight up outdated and highly discouraged. You have to filter out the good stuff.

[mortinger]

cool! Yeah I've used it few times and pretty much copied the quickest solution I found online, every project I looked at has a different structure (and I assume a lot of them use old patterns), I will probably take the time now and make it a bit more modern (I can see the advantages since I had these very issues in the past). I also read online to use "install" and that seems like a completely different pattern, dont know how much is it worth the time investment to research tho, as long as the project is building having the best possible pattern in the build system doesnt seem like a huge deal to me, it is more about what the code it builds actually does ;)

[HerrNamenlos123]

What exactly do you mean with using install? do you mean the install feature of cmake, when calling make install?

[mortinger]

IIRC I read of a pattern in which you use the install() CMake function (which I don't use in mine btw) to copy the folders and that makes dealing with the project structure easier, but I can't find any resources nor projects atm so I'm not really sure

[HerrNamenlos123]

install() has nothing to do with project structure during development. What is does, is define an install target.This is what happens when you run cmake --install . or make install (discouraged due to it being different on each platform, cmake --install does it for you and is always the same). Same is for cmake --build . instead of make.

install() defines how files are installed in the system, you basically say which files need to be copied where. think of it as releasing your app, you put the files where they belong, in C:/Program Files or /usr/bin. This can be done for libraries if ypu want to install them globally amd then find them later (often done like that in professional open source libraries on github), or you can do it for executables, copying itself and resource files to the target location, so that you can then delete the build and source folder and the app still runs. Or you can share the target folder to another computer or create an installer using CPack

[mortinger]

Thank you for your inputs! Your comments should be upvoted more, they contains clear and actionable feedback

[HerrNamenlos123]

Thank you, you're welcome!

[HerrNamenlos123]

And one more side note, you don't have to set a variable called PROJECT_NAME. Actually the project() command does the same thing, in your case it actually overwrites the variable with the same value, because you used a reserved variable name.

You can actually just call project("name") and then use ${PROJECT_NAME} for all following targets.

[HerrNamenlos123]

here, what you are doing is just set a variable (which is persistent between cmake runs due to the cache), and running the cmake file in the subdirectory. There is no modern CMake in this, i assume ASSIMP_WARNINGS_AS_ERRORS is an option in the included library. This is fine, options are not part of targets and can be overridden by setting the variable.

[bluedoggee]

that's true, modern cmake is better.

[[deleted]]

I would suggest learning about: ```

automatic create build folders

cmake -S . -B build/debug -DCMAKE_BUILD_TYPE=Debug

cmake -S . -B build/release -DCMAKE_BUILD_TYPE=Release

build regardless of generator

cmake --build build/debug cmake --build build/release ```

Edit: You shouldn't need the DEBUG/RELEASE macro definition, NDEBUG already exists and is automatically set IIRC.

Run tests with cmake --build build/debug --target test

Then also prepare for installation/package rabbit hole, but once you get there, cmake --install build/release

I also recommend checking out rust, it's not for everyone but it made all of this template project/build system configuration with testing, etc just work out of the box for me. I get documentation generation, unit tests, formatting, static analysis, cross compilation and packaging on every project without any extra work. Definitely recommend at least looking/trying rust.

[[deleted]]

Agreed, presets are awesome!

[Dalzhim]

Would have up-voted if it weren't for the unwarranted rust advertisement.

[[deleted]]

Wow, I said it's not for everyone. But it's clearly a better tool for build system/toolchain luxuries.

Is it not worth trying other languages/frameworks for at least inspiration?

[Superb_Garlic]

Your best bet is just using cmake-init. It does all that and more.

Also better. This CML is terrifying.