Skip to content

fsaporito/CppCMakeStarter

Repository files navigation

CppCMakeStarter

Cpp Template Project for C++ Crossplatform development with CMake

====

Got ideas and tricks from

https://github.com/cpp-best-practices/cpp_starter_project

https://github.com/aminya/setup-cpp

https://github.com/cpp-best-practices/project_options

CMake/C++ QuickStart at C++Weekly: https://www.youtube.com/watch?v=YbgH7yat-Jo

Git, CMake and Conan Talk at CppCon 2018: https://www.youtube.com/watch?v=S4QSKLXdTtA

Effective CMake at CppNow 2017: https://www.youtube.com/watch?v=bsXLMQ6WgIk

Guide to Customize the Template Project

  1. Open CMakeLists.txt in the root folder and change the project name

  2. Open the conanfile.py and change the line 5

name = "CppCMakeStarter"

with the selected project name.

  1. Open the conanfile.py and change the lines 7 to 11
requires = (
        "catch2/2.13.7",
        "docopt.cpp/0.6.2",
        "spdlog/1.9.2",
    )

with the actual dependencies for the project

  1. Unit tests are configured with Catch. Change the test/tests.cpp to add more tests. To add more test files, change the test/CMakeLists.txt line 10 from this
add_executable(tests tests.cpp)

to for example this

add_executable(tests testsClass1.cpp testsClass2.cpp testsClass3.cpp)
  1. Fuzz tests are configured with libFuzzer. Change the fuzz_test/fuzz_tester.cpp to add more tests. To add more test files, change the fuzz_tester/CMakeLists.txt line 5 from this
add_executable(fuzz_tester fuzz_tester.cpp)

to for example this

add_executable(fuzz_tester fuzz_tester1.cpp fuzz_tester2.cpp)
  1. To add Code Modules, open src/CMakeLists and edit the lib1 and lib2 to add your own modules. Then create the folders and their respective CMakeLists.txt

  2. Open the Readme and delete from the first line to this one. In this way all the instructions for configuration and building the project will remain in the new readme.

Tools and Required Software

Before the project can be used, you should check that all the necessary softwares and tools are installed. Mandatory are the following:

- C++ compiler compatible with C++20

  • gcc 7+

    Install command
    • Debian/Ubuntu:

        sudo apt install build-essential
      
    • Windows:

        choco install mingw -y
      
    • MacOS:

        brew install gcc
      
  • clang 6+

    Install command
    • Debian/Ubuntu:

        bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"
      
    • Windows:

      Visual Studio 2019 ships with LLVM (see the Visual Studio section). However, to install LLVM separately:

        choco install llvm -y
      

      llvm-utils for using external LLVM with Visual Studio generator:

        git clone https://github.com/zufuliu/llvm-utils.git
        cd llvm-utils/VS2017
        .\install.bat
      
    • MacOS:

        brew install llvm
      
  • Visual Studio 2019 or higher

    Install command + Environment setup

    On Windows, you need to install Visual Studio 2019 because of the SDK and libraries that ship with it.

    Visual Studio IDE - 2019 Community (installs Clang too):

      choco install -y visualstudio2019community --package-parameters "add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --includeOptional --passive --locale en-US"
    

    Put MSVC compiler, Clang compiler, and vcvarsall.bat on the path:

      	choco install vswhere -y
      	refreshenv
    
      	# change to x86 for 32bit
      	$clpath = vswhere -products * -latest -prerelease -find **/Hostx64/x64/*
      	$clangpath = vswhere -products * -latest -prerelease -find **/Llvm/bin/*
      	$vcvarsallpath =  vswhere -products * -latest -prerelease -find **/Auxiliary/Build/*
    
      	$path = [System.Environment]::GetEnvironmentVariable("PATH", "User")
      	[Environment]::SetEnvironmentVariable("Path", $path + ";$clpath" + ";$clangpath" + ";$vcvarsallpath", "User")
      	refreshenv
    

- CMake at least version 3.15 or higher

Install Command
  • Debian/Ubuntu:

      sudo apt-get install cmake
    
  • Windows:

      choco install cmake -y
    
  • MacOS:

      brew install cmake
    

- Conan (Also Vcpkg could be used but isn't tested)

Install Command

Note: Check that pip is installed with python3, otherwise there will be errors when configuring the cmake project

  • Windows:

      choco install conan -y
    
  • MacOS:

      brew install conan
    


To setup the environment on linux ubuntu, there are two scripts that can be used:

  1. For installing conan
scripts/conan_install.sh
  1. For Installing the required Cpp tools
scripts/required_cpp_tools_install.sh

Optional Tools

This project may also run with other software for static code analysis, documentation and related things. These are optional but they are strongly suggested for development since they improve code quality.

Furthermore, a clang-format file is present the root folder to have a standard formatting for the codebase.

  • Doxygen

    Install Command
    • Debian/Ubuntu:

        sudo apt-get install doxygen
        sudo apt-get install graphviz
      
    • Windows:

        choco install doxygen.install -y
        choco install graphviz -y
      
    • MacOS:

        brew install doxygen
        brew install graphviz
      
  • ccache

    Install Command
    • Debian/Ubuntu:

        sudo apt-get install ccache
      
    • Windows:

        choco install ccache -y
      
    • MacOS:

        brew install ccache
      
  • Cppcheck

    Install Command
    • Debian/Ubuntu:

        sudo apt-get install cppcheck
      
    • Windows:

        choco install cppcheck -y
      
    • MacOS:

        brew install cppcheck
      
  • include-what-you-use

    Install Command

    Follow instructions here: https://github.com/include-what-you-use/include-what-you-use#how-to-install

To install these optional tools environment on linux ubuntu the following script can be run:

For Installing the required Cpp tools

scripts/optional_cpp_tools_install.sh

Build

This software uses cmake for generating the build system configuration.

In particular, starting from the root directory, the command to generate the build configuration is:

  • Single Configuration Builders (Make, Ninja)
      Single configuration builders won't know about configurations, so cmake has to create different build directories for each one of them.
    
      - Release
      ```Bash
      cmake -S . -B ./build/Release -DCMAKE_BUILD_TYPE:STRING=Release
      ```
    
      - Debug
      ```Bash
      cmake -S . -B ./build/Debug -DCMAKE_BUILD_TYPE:STRING=Debug
      ```
    
      - Release with Debug Symbols
      ```Bash
      cmake -S . -B ./build/RelWithDebInfo
      ```
    
      - Release with Minimum Size
      ```Bash
      cmake -S . -B ./build/MinSizeRel
      ```
    
  • Multiconfiguration Builders (Visual Studio, Ninja Multi-Configuration)
      Multiconfiguration builders will work directly in a single build folder and the actual configuration has to be specified at compile time.
      ```Bash
      cmake -S . -B ./build
      ```
    

Then, to actually compile the code, you can use directly cmake via the following commands launched from the root directory:

  • Single Configuration Builders (Make, Ninja)

    Single configuration builders won't know about configurations, so the build process has to be launched separately from each build folder.

    • Release

       cmake --build ./build/Release
    • Debug

       cmake --build ./build/Debug
    • Release with Debug Symbols

       cmake --build ./build/RelWithDebInfo
    • Release with Minimum Size

       cmake --build ./build/MinSizeRel
  • Multiconfiguration Builders (Visual Studio, Ninja Multi-Configuration)

    Multiconfiguration builders will work directly in a single build folder and the actual configuration has to be specified at build time.

    • Release

       cmake --build ./build -- /p:configuration=release
    • Debug

       cmake --build ./build -- /p:configuration=Debug
    • Release with Debug Symbols

       cmake --build ./build -- /p:configuration=RelWithDebInfo
    • Release with Minimum Size

       cmake --build ./build -- /p:configuration=MinSizeRel

CMake will automatically pick the predefined C++ compiler. On Linux systems you can change it via the "CXX" system variable.

Automatic Tests can be run from the build directly via CMake.

  • Single Configuration Builders (Make, Ninja) ```Bash cd build/Debug ctest -C Debug ```
  • Multiconfiguration Builders (Visual Studio, Ninja Multi-Configuration) ```Bash cd build ctest -C Debug ```

This library uses the Catch2 framework for automatic testing.

Continuous Integration

This project uses appveyor for running continuous integration. After every commit, the source code is compiled and tested on the following environments:

  • Linux Ubuntu 20.04 with GCC 9.3.0
  • Windows Server 2022 with MSBuild VC142

Static Code Analysis and Sanitizers

The cmake configuration supports various tools to be run automatically post build

  • What You See is What You Get
  • Clang-Tidy
  • Cppcheck

To add them to the build process, uncomment the relative options in the root's cmake file from line 22 to 43. These tools must be installed on the develompent system and cmake must be able to find them on the current system path. See the section on optional tools for installation instructions.

Library Documentation

The library supports doxygen for automatically generating code documentation. See the section on optional tools for instructions on installing doxigen on your system. The "doxygen-docs" target will be automatically generated by cmake if the option is uncommented in the root's cmake file on line 33. For example, if you generate a make configuration, the command to create the documentation after the build has been completed would be

cd build/Release
make doxygen-docs

If the process is successfull, the produced documentation will be found in the following directory:

build/Release/html

About

Template Project for C++ with CMake

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published