cppstarterproject

Getting Started

Use the Github template

First, click the green

Use this template

$ git clone https://github.com//.git

Remove frameworks you're not going to use

If you know you're not going to use one or more of the optional gui/graphics frameworks (fltk, gtkmm, imgui, etc.), you can remove them with

git rm

$ git rm -r src/

Dependencies

Note about install commands: - for Windows, we use choco. - for MacOS, we use brew. - In case of an error in cmake, make sure that the dependencies are on the PATH.

Necessary Dependencies

1. A C++ compiler that supports C++17. See cppreference.com to see which features are supported by each compiler. The following compilers should work:

• 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
  

1. Conan
   Install Command

- Via pip - https://docs.conan.io/en/latest/installation.html#install-with-pip-recommended

    pip install --user conan

Windows:
  choco install conan -y

MacOS:
  brew install conan

1. CMake 3.15+
   Install Command

- Debian/Ubuntu:

    sudo apt-get install cmake

Windows:
  choco install cmake -y

MacOS:
  brew install cmake

Optional Dependencies

C++ Tools

• 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

GUI libraries

This project can be made to work with several optional GUI frameworks.

If desired, you should install the following optional dependencies as directed by their documentation, linked here:

• FLTK
• GTKMM
• QT

The following dependencies can be downloaded automatically by CMake and Conan. All you need to do to install them is to turn on a CMake flag during configuration. If you run into difficulty using them, please refer to their documentation, linked here:

• NANA
• SDL
• IMGUI: This framework depends on SFML, and if you are using Linux, you may need to install several of SFML's dependencies using your package manager. See the SFML build tutorial for specifics.

Build Instructions

Build directory

Make a build directory:

mkdir build

Specify the compiler using environment variables

By default (if you don't set environment variables

CC

CXX

Conan and CMake use the environment variables CC and CXX to decide which compiler to use. So to avoid the conflict issues only specify the compilers using these variables.

CMake will detect which compiler was used to build each of the Conan targets. If you build all of your Conan targets with one compiler, and then build your CMake targets with a different compiler, the project may fail to build.

Configure your build

To configure the project and write makefiles, you could use

cmake

Configure via cmake-gui:

1) Open cmake-gui from the project directory:

cmake-gui .

3) Configure the generator:

In cmake-gui, from the upper menu select

Tools/Configure

Warning: if you have set

CC

CXX

use default native compilers

CC

CXX

Windows - MinGW Makefiles

Choose MinGW Makefiles as the generator:

Windows - Visual Studio generator and compiler

You should have already set C and CXX to cl.exe.

Choose "Visual Studio 16 2019" as the generator:

Windows - Visual Studio generator and Clang Compiler

You should have already set C and CXX to clang.exe and clang++.exe.

Choose "Visual Studio 16 2019" as the generator. To tell Visual studio to use clang-cl.exe:

• If you use the LLVM that is shipped with Visual Studio: write ClangCl under "optional toolset to use".

• If you use an external LLVM: write LLVM_v142 under "optional toolset to use".

4) Choose the Cmake options and then generate:

Configure via ccmake:

with the Cmake Curses Dialog Command Line tool:

ccmake -S . -B ./build

Once

ccmake

Build

Once you have selected all the options you would like to use, you can build the project (all targets):

cmake --build ./build

For Visual Studio, give the build configuration (Release, RelWithDeb, Debug, etc) like the following:

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

Troubleshooting

Update Conan

Many problems that users have can be resolved by updating Conan, so if you are having any trouble with this project, you should start by doing that.

To update conan:

$ pip install --user --upgrade conan

You may need to use

pip3

pip

Clear Conan cache

If you continue to have trouble with your Conan dependencies, you can try clearing your Conan cache:

$ conan remove -f '*'

The next time you run

cmake

cmake --build

Identifying misconfiguration of Conan dependencies

If you have a dependency 'A' that requires a specific version of another dependency 'B', and your project is trying to use the wrong version of dependency 'B', Conan will produce warnings about this configuration error when you run CMake. These warnings can easily get lost between a couple hundred or thousand lines of output, depending on the size of your project.

If your project has a Conan configuration error, you can use

conan info

conan info

$ cd build
$ conan info .

In my terminal, the first couple lines of

conan info

For example, the package

spdlog/1.5.0

fmt/6.1.2

cmake/Conan.cmake

fmt

fmt/6.0.0

$ conan remove -f '*'       # clear Conan cache
$ rm -rf build              # clear previous CMake build
$ mkdir build && cd build
$ cmake ..                  # rebuild Conan dependencies
$ conan info .

...the first line of output would be a warning that

spdlog

fmt

Testing

See Catch2 tutorial

Fuzz testing

See libFuzzer Tutorial