cpp-vcpkg-starter

This is a fork of cpp-best-practices/cpp_starter_project, using vcpkg instead of conan. Some dependencies were also removed.

Getting Started

Use the Github template

First, click the green Use this template button near the top of this page. Fill in a repository name and short description, and click 'Create repository from template'. This will allow you to create a new repository in your Github account, prepopulated with the contents of this project. Now you can clone the project locally and get to work!

git clone https://github.com/<user>/<your_new_repo>.git

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.

Too Long, Didn't Install

This is a really long list of dependencies, and it's easy to mess up. That's why we have a Docker image that's already set up for you. See the Docker instructions below.

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
  

3. 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

Build Instructions

A full build has different steps:

1. Specifying the compiler using environment variables
2. Configuring the project
3. Building the project

For the subsequent builds, in case you change the source code, you only need to repeat the last step.

(1) Specify the compiler using environment variables

By default (if you don't set environment variables CC and CXX), the system default compiler will be used.

Commands for setting the compilers

• Debian/Ubuntu/MacOS:

  Set your desired compiler (clang, gcc, etc):

  • Temporarily (only for the current shell)

    Run one of the followings in the terminal:

    • clang

        CC=clang CXX=clang++
      

    • gcc

        CC=gcc CXX=g++
      

  • Permanent:

    Open ~/.bashrc using your text editor:

      gedit ~/.bashrc
    

    Add CC and CXX to point to the compilers:

      export CC=clang
      export CXX=clang++
    

    Save and close the file.

• Windows:

  • Permanent:

    Run one of the followings in PowerShell:

    • Visual Studio generator and compiler (cl)

        [Environment]::SetEnvironmentVariable("CC", "cl.exe", "User")
        [Environment]::SetEnvironmentVariable("CXX", "cl.exe", "User")
        refreshenv
      

      Set the architecture using vsvarsall:

        vsvarsall.bat x64
      

    • clang

        [Environment]::SetEnvironmentVariable("CC", "clang.exe", "User")
        [Environment]::SetEnvironmentVariable("CXX", "clang++.exe", "User")
        refreshenv
      

    • gcc

        [Environment]::SetEnvironmentVariable("CC", "gcc.exe", "User")
        [Environment]::SetEnvironmentVariable("CXX", "g++.exe", "User")
        refreshenv
      

  • Temporarily (only for the current shell):

    	$Env:CC="clang.exe"
    	$Env:CXX="clang++.exe"
    

(2) Configure your build

To configure the project, you could use cmake, or ccmake or cmake-gui. Each of them are explained in the following:

(2.a) Configuring via cmake:

With Cmake directly:

cmake -S . -B ./build

Cmake will automatically create the ./build folder if it does not exist, and it wil configure the project.

(2.b) Configuring via ccmake:

With the Cmake Curses Dialog Command Line tool:

ccmake -S . -B ./build

Once ccmake has finished setting up, press 'c' to configure the project, press 'g' to generate, and 'q' to quit.

(2.c) Configuring via cmake-gui:

To use the GUI of the cmake:

2.c.1) Open cmake-gui from the project directory:

cmake-gui .

2.c.2) Set the build directory:

2.c.3) Configure the generator:

In cmake-gui, from the upper menu select Tools/Configure.

Warning: if you have set CC and CXX always choose the use default native compilers option. This picks CC and CXX. Don't change the compiler at this stage!

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".

2.c.4) Choose the Cmake options and then generate:

(3) Build the project

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

Running the tests

You can use the ctest command run the tests.

cd ./build
ctest -C Debug
cd ../

Testing

See Catch2 tutorial

Fuzz testing

See libFuzzer Tutorial

Docker Instructions

If you have Docker installed, you can run this in your terminal, when the Dockerfile is in your working directory:

docker build --tag=my_project:latest .
docker run -it my_project:latest

This command will put you in a bash session in a Ubuntu 18.04 Docker container, with all of the tools listed in the Dependencies section already installed. Additionally, you will have g++-10 and clang++-11 installed as the default versions of g++ and clang++.

If you want to build this container using some other versions of gcc and clang, you may do so with the GCC_VER and LLVM_VER arguments:

docker build --tag=myproject:latest --build-arg GCC_VER=9 --build-arg LLVM_VER=10 .

The CC and CXX environment variables are set to GCC version 10 by default. If you wish to use clang as your default CC and CXX environment variables, you may do so like this:

docker build --tag=my_project:latest --build-arg USE_CLANG=1 .

You will be logged in as root, so you will see the # symbol as your prompt. You will be in a directory that contains a copy of the cpp_starter_project; any changes you make to your local copy will not be updated in the Docker image until you rebuild it. If you need to mount your local copy directly in the Docker image, see Docker volumes docs. TLDR:

docker run -it \
	-v absolute_path_on_host_machine:absolute_path_in_guest_container \
	my_project:latest

You can configure and build as directed above using these commands:

/starter_project# mkdir build
/starter_project# cmake -S . -B ./build
/starter_project# cmake --build ./build

You can configure and build using clang-11, without rebuilding the container, with these commands:

/starter_project# mkdir build
/starter_project# CC=clang CXX=clang++ cmake -S . -B ./build
/starter_project# cmake --build ./build

The ccmake tool is also installed; you can substitute ccmake for cmake to configure the project interactively. All of the tools this project supports are installed in the Docker image; enabling them is as simple as flipping a switch using the ccmake interface. Be aware that some of the sanitizers conflict with each other, so be sure to run them separately.

A script called build_examples.sh is provided to help you to build the example GUI projects in this container.