This is a template for C++ projects. What you get:
- Sources, headers and test files separated in distinct folders.
- External libraries that are locally cloned by Github.
- External libraries installed and managed by Conan.
- Use of modern CMake for building and compiling.
- Unit testing, using Catch2, Logging, using Loguru and Benchmarking, using Celero.
- Continuous testing with Github Actions.
- Code coverage reports, including automatic upload to Codecov.
- Code documentation with Doxygen.
- Optional: Use of VSCode with the C/C++ and CMakeTools extension.
├── CMakeLists.txt
├── app
│ ├── CMakesLists.txt
│ └── main.cc
├── benchmarks
│ ├── CMakesLists.txt
│ └── main.cc
├── docs
├── ├── Doxyfile
│ └── html/
├── external
│ ├── CMakesLists.txt
│ ├── linalg/
│ └── loguru/
├── include
│ └── my_lib.h
├── src
│ ├── CMakesLists.txt
│ └── my_lib.cc
└── tests
├── CMakeLists.txt
└── main.cc
Sources go in src/, header files in include/, main programs in app/, tests go in tests/ and benchmarks go in benchmarks/.
If you add a new executable, say app/new_executable.cc
, you only need to add the following two lines to CMakeLists.txt:
add_executable(new_executable app/new_executable.cc) # Name of exec. and location of file.
target_link_libraries(new_executable PRIVATE ${LIBRARY_NAME}) # Link the executable to lib built from src/*.cc (if it uses it).
- CMake 3.14+
- GNU Makefile
- Doxygen
- Conan
- MSVC 2017 (or higher), G++7 (or higher), Clang++7 (or higher)
- Code Covergae (only on GNU|Clang): lcov, gcovr
- App Executable: The build type can be Debug/Release/MinSizeRel or RelWithDebInfo
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --config Release --target CppTemplate_executable
./bin/CppTemplate_executable
- Code Coverage: The build type has to be Coverage.
cd build
cmake -DCMAKE_BUILD_TYPE=Coverage -DENABLE_CODE_COVERAGE=ON ..
cmake --build . --config Coverage --target CppTemplate_coverage
- Unit testing: The build type should to be Debug for GCC/Clang and Release for MSVC (due to bug).
cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build . --config Debug --target CppTemplate_unit_tests
./bin/CppTemplate_unit_tests
- Benchmarking: The build type should to be Release.
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_BENCHMARKS=ON ..
cmake --build . --config Release --target CppTemplate_benchmarks
./bin/CppTemplate_benchmarks
- Documentation:
cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build . --config Debug --target CppTemplate_docs
cmake [<options>] -S <path-to-source> -B <path-to-build>
Assuming that a CMakeLists.txt is in the root directory, you can generate a project like the following.
mkdir build
cd build
cmake -S .. -B . # Option 1
cmake .. # Option 2
Assuming that you have already build the CMake project, you can update the generated project.
cd build
cmake .
cd build
cmake -S .. -B . -G "Unix Makefiles" # Option 1
cmake .. -G "Unix Makefiles" # Option 2
cd build
cmake -S .. -B . -G "Visual Studio 16 2019" # Option 1
cmake .. -G "Visual Studio 16 2019" # Option 2
Per default the standard type is in the most cases the debug type. If you want to generate the project, for example, in release mode you have to set the build type.
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
If you have set some options in the CMakeLists, you can pass values in the command line.
cd build
cmake -DMY_OPTION=[ON|OFF] ..
To build a project, you need to generate it beforehand. Building a project is pretty straightforward, by typing the following.
cmake --build <dir> [<options>] [-- <build-tool-options>]
If you want to build the project in parallel you can use the following option.
cd build
cmake --build .
The standard build command would build all created targets within the CMakeLists. If you want to build a specific target, you can do so.
cd build
cmake --build . --target ExternalLibraries_Executable
The target ExternalLibraries_Executable is just an example of a possible target name. Note: All dependent targets will be build beforehand.
Besides setting the target within the cmake build command, you could also run the previously generated Makefile (from the generating step). If you want to build the ExternalLibraries_Executable, you could to the following.
cd build
make ExternalLibraries_Executable
After generating the project and building a specific target you might want to run the executable. In the default case, the executable is stored in build/5_ExternalLibraries/app/ExternalLibraries_Executable, assuming that you are building the project 5_ExternalLibraries and the main file of the executable is in the app dir.
cd build
./bin/ExternalLibraries_Executable
There are the three following linking types:
- PRIVATE: When A links in B as PRIVATE, it is saying that A uses B in its implementation, but B is not used in any part of A's public API. Any code that makes calls into A would not need to refer directly to anything from B.
- INTERFACE: When A links in B as INTERFACE, it is saying that A does not use B in its implementation, but B is used in A's public API. Code that calls into A may need to refer to things from B in order to make such calls.
- PUBLIC: When A links in B as PUBLIC, it is essentially a combination of PRIVATE and INTERFACE. It says that A uses B in its implementation and B is also used in A's public API.
- Shared: Shared libraries reduce the amount of code that is duplicated in each program that makes use of the library, keeping the binaries small. It also allows you to replace the shared object with one that is functionally equivalent, without needing to recompile the program that makes use of it. Shared libraries will, however have a small additional cost for the execution.
- Static: Static libraries increase the overall size of the binary, but it means that you don't need to carry along a copy of the library that is being used. As the code is connected at compile time there are not any additional run-time loading costs. The code is simply there.