diff --git a/README.md b/README.md index 3342d471..450ef8bc 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,39 @@ # cpp_starter_project -![CI](https://github.com/cpp-best-practices/cpp_starter_project/workflows/ci/badge.svg) +![CI](cpp_starter_project/workflows/ci/badge.svg) [![codecov](https://codecov.io/gh/cpp-best-practices/cpp_starter_project/branch/main/graph/badge.svg)](https://codecov.io/gh/cpp-best-practices/cpp_starter_project) [![Language grade: C++](https://img.shields.io/lgtm/grade/cpp/github/cpp-best-practices/cpp_starter_project)](https://lgtm.com/projects/g/cpp-best-practices/cpp_starter_project/context:cpp) + +## About cpp_starter_project + +This is a C++ Best Practices GitHub template for getting up and running with C++ quickly. + +By default (collectively known as `ENABLE_DEVELOPER_MODE`) + + * Address Sanitizer and Undefined Behavior Sanitizer enabled where possible + * Warnings as errors + * clang-tidy and cppcheck static analysis + * conan for dependencies + +It includes + + * a [nana](http://nanapro.org/en-us/) example + * a [Dear ImGui](https://github.com/ocornut/imgui) example + * a basic CLI example + * examples for fuzz, unit, and constexpr testing + * large github action testing matrix + +It requires + + * cmake + * conan + * a compiler + +If you want a simplified starter template project without these examples, check out the [cpp_boilerplate_project](https://github.com/cpp-best-practices/boilerplate). + +The Boilerplate project will merge new features first, then they will be merged (as appropriate) into this project. + ## Getting Started ### Use the Github template @@ -22,490 +52,16 @@ 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](https://chocolatey.org/install). -- for MacOS, we use [brew](https://brew.sh/). -- 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: - -#### Docker -We have a Docker image that's already set up for you. See the [Docker instructions](#docker-instructions). - -#### Setup-cpp - -We have [setup-cpp](https://github.com/aminya/setup-cpp) that is a cross-platform tool to install all the compilers and dependencies on the system. - -Please check [the setup-cpp documentation](https://github.com/aminya/setup-cpp) for more information. - -For example, on Windows, you can run the following to install llvm, cmake, ninja, ccache, conan, and cppcheck. -```ps1 -# windows example (open shell as admin) -curl -LJO "https://github.com/aminya/setup-cpp/releases/download/v0.5.7/setup_cpp_windows.exe" -./setup_cpp_windows --compiler llvm --cmake true --ninja true --ccache true --conan true --cppcheck true - -RefreshEnv.cmd # reload the environment -``` - -### Necessary Dependencies -1. A C++ compiler that supports C++17. -See [cppreference.com](https://en.cppreference.com/w/cpp/compiler_support) -to see which features are supported by each compiler. -The following compilers should work: - - * [gcc 7+](https://gcc.gnu.org/) -
- Install command - - - Debian/Ubuntu: - - sudo apt install build-essential - - - Windows: - - choco install mingw -y - - - MacOS: - - brew install gcc -
- - * [clang 6+](https://clang.llvm.org/) -
- 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](https://visualstudio.microsoft.com/) -
- 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 - -
- - -2. [Conan](https://conan.io/) -
- 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 - -
- -3. [CMake 3.15+](https://cmake.org/) -
- Install Command - - - Debian/Ubuntu: - - sudo apt-get install cmake - - - Windows: - - choco install cmake -y - - - MacOS: - - brew install cmake - -
- -### Optional Dependencies -#### C++ Tools - * [Doxygen](http://doxygen.nl/) -
- 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](https://ccache.dev/) -
- Install Command - - - Debian/Ubuntu: - - sudo apt-get install ccache - - - Windows: - - choco install ccache -y - - - MacOS: - - brew install ccache - -
- - - * [Cppcheck](http://cppcheck.sourceforge.net/) -
- Install Command - - - Debian/Ubuntu: - - sudo apt-get install cppcheck - - - Windows: - - choco install cppcheck -y - - - MacOS: - - brew install cppcheck - -
- - - * [include-what-you-use](https://include-what-you-use.org/) -
- 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](https://www.fltk.org/doc-1.4/index.html) -- [GTKMM](https://www.gtkmm.org/en/documentation.html) -- [QT](https://doc.qt.io/) - -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](http://nanapro.org/en-us/documentation/) -- [SDL](http://wiki.libsdl.org/FrontPage) -- [IMGUI](https://github.com/ocornut/imgui/tree/master/docs): - 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](https://www.sfml-dev.org/tutorials/2.5/compile-with-cmake.php) - for specifics. - -## 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. - -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. -
-Commands for setting the compilers +## More Details -- 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 [vcvarsall](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019#vcvarsall-syntax): - - vcvarsall.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. - -Instead, if you have CMake version 3.21+, you can use one of the configuration presets that are listed in the CmakePresets.json file. - - cmake . --preset - cmake --build - -#### (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: - -![build_dir](https://user-images.githubusercontent.com/16418197/82524586-fa48e380-9af4-11ea-8514-4e18a063d8eb.jpg) - -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: - -mingw - -
- -
-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: - -default_vs - -
- -
- -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". - -visual_studio - -- If you use an external LLVM: write [`LLVM_v142`](https://github.com/zufuliu/llvm-utils#llvm-for-visual-studio-2017-and-2019) - under "optional toolset to use". - -visual_studio - -
-
- -2.c.4) Choose the Cmake options and then generate: - -![generate](https://user-images.githubusercontent.com/16418197/82781591-c97feb80-9e1f-11ea-86c8-f2748b96f516.png) - -### (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. - -```shell -cd ./build -ctest -C Debug -cd ../ -``` - -## 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` instead of `pip` in this command, depending on your -platform. - -### 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` or `cmake --build`, your Conan dependencies will -be rebuilt. If you aren't using your system's default compiler, don't forget to -set the CC, CXX, CMAKE_C_COMPILER, and CMAKE_CXX_COMPILER variables, as -described in the 'Build using an alternate compiler' section above. - -### 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` to -find it. `conan info` displays information about the dependency graph of your -project, with colorized output in some terminals. - - cd build - conan info . - -In my terminal, the first couple lines of `conan info`'s output show all of the -project's configuration warnings in a bright yellow font. - -For example, the package `spdlog/1.5.0` depends on the package `fmt/6.1.2`. -If you were to modify the file `conanfile.py` so that it requires an -earlier version of `fmt`, such as `fmt/6.0.0`, and then run: - -```bash -conan remove -f '*' # clear Conan cache -rm -rf build # clear previous CMake build -cmake -S . -B ./build # rebuild Conan dependencies -conan info ./build -``` - -...the first line of output would be a warning that `spdlog` needs a more recent -version of `fmt`. + * [Dependency Setup](README_dependencies.md) + * [Building Details](README_building.md) + * [Troubleshooting](README_troubleshooting.md) + * [Docker](README_docker.md) ## Testing + See [Catch2 tutorial](https://github.com/catchorg/Catch2/blob/master/docs/tutorial.md) ## Fuzz testing @@ -513,74 +69,3 @@ See [Catch2 tutorial](https://github.com/catchorg/Catch2/blob/master/docs/tutori See [libFuzzer Tutorial](https://github.com/google/fuzzing/blob/master/tutorial/libFuzzerTutorial.md) -## Docker Instructions - -If you have [Docker](https://www.docker.com/) installed, you can run this -in your terminal, when the Dockerfile is inside the .devconatiner directory: - -```bash -docker build -f ./.devcontainer/Dockerfile --tag=my_project:latest . -docker run -it my_project:latest -``` - -This command will put you in a `bash` session in a Ubuntu 20.04 Docker container, -with all of the tools listed in the [Dependencies](#dependencies) section already installed. -Additionally, you will have `g++-11` and `clang++-13` 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: - -```bash -docker build --tag=myproject:latest --build-arg GCC_VER=10 --build-arg LLVM_VER=11 . -``` - -The CC and CXX environment variables are set to GCC version 11 by default. -If you wish to use clang as your default CC and CXX environment variables, you -may do so like this: - -```bash -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](https://docs.docker.com/storage/volumes/). -TLDR: - -```bash -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](#build) using these commands: - -```bash -/starter_project# mkdir build -/starter_project# cmake -S . -B ./build -/starter_project# cmake --build ./build -``` - -You can configure and build using `clang-13`, without rebuilding the container, -with these commands: - -```bash -/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. - diff --git a/README_building.md b/README_building.md new file mode 100644 index 00000000..b4a4b9bd --- /dev/null +++ b/README_building.md @@ -0,0 +1,193 @@ +## 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. + +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. + +
+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 [vcvarsall](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019#vcvarsall-syntax): + + vcvarsall.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. + +Instead, if you have CMake version 3.21+, you can use one of the configuration presets that are listed in the CmakePresets.json file. + + cmake . --preset + cmake --build + +#### (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: + +![build_dir](https://user-images.githubusercontent.com/16418197/82524586-fa48e380-9af4-11ea-8514-4e18a063d8eb.jpg) + +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: + +mingw + +
+ +
+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: + +default_vs + +
+ +
+ +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". + +visual_studio + +- If you use an external LLVM: write [`LLVM_v142`](https://github.com/zufuliu/llvm-utils#llvm-for-visual-studio-2017-and-2019) + under "optional toolset to use". + +visual_studio + +
+
+ +2.c.4) Choose the Cmake options and then generate: + +![generate](https://user-images.githubusercontent.com/16418197/82781591-c97feb80-9e1f-11ea-86c8-f2748b96f516.png) + +### (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. + +```shell +cd ./build +ctest -C Debug +cd ../ +``` + + diff --git a/README_dependencies.md b/README_dependencies.md new file mode 100644 index 00000000..51bc71a6 --- /dev/null +++ b/README_dependencies.md @@ -0,0 +1,236 @@ +## Dependencies + +Note about install commands: +- for Windows, we use [choco](https://chocolatey.org/install). +- for MacOS, we use [brew](https://brew.sh/). +- 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: + +#### Docker +We have a Docker image that's already set up for you. See the [Docker instructions](#docker-instructions). + +#### Setup-cpp + +We have [setup-cpp](https://github.com/aminya/setup-cpp) that is a cross-platform tool to install all the compilers and dependencies on the system. + +Please check [the setup-cpp documentation](https://github.com/aminya/setup-cpp) for more information. + +For example, on Windows, you can run the following to install llvm, cmake, ninja, ccache, conan, and cppcheck. +```ps1 +# windows example (open shell as admin) +curl -LJO "https://github.com/aminya/setup-cpp/releases/download/v0.5.7/setup_cpp_windows.exe" +./setup_cpp_windows --compiler llvm --cmake true --ninja true --ccache true --conan true --cppcheck true + +RefreshEnv.cmd # reload the environment +``` + +### Necessary Dependencies +1. A C++ compiler that supports C++17. +See [cppreference.com](https://en.cppreference.com/w/cpp/compiler_support) +to see which features are supported by each compiler. +The following compilers should work: + + * [gcc 7+](https://gcc.gnu.org/) +
+ Install command + + - Debian/Ubuntu: + + sudo apt install build-essential + + - Windows: + + choco install mingw -y + + - MacOS: + + brew install gcc +
+ + * [clang 6+](https://clang.llvm.org/) +
+ 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](https://visualstudio.microsoft.com/) +
+ 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 + +
+ + +2. [Conan](https://conan.io/) +
+ 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 + +
+ +3. [CMake 3.15+](https://cmake.org/) +
+ Install Command + + - Debian/Ubuntu: + + sudo apt-get install cmake + + - Windows: + + choco install cmake -y + + - MacOS: + + brew install cmake + +
+ +### Optional Dependencies +#### C++ Tools + * [Doxygen](http://doxygen.nl/) +
+ 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](https://ccache.dev/) +
+ Install Command + + - Debian/Ubuntu: + + sudo apt-get install ccache + + - Windows: + + choco install ccache -y + + - MacOS: + + brew install ccache + +
+ + + * [Cppcheck](http://cppcheck.sourceforge.net/) +
+ Install Command + + - Debian/Ubuntu: + + sudo apt-get install cppcheck + + - Windows: + + choco install cppcheck -y + + - MacOS: + + brew install cppcheck + +
+ + + * [include-what-you-use](https://include-what-you-use.org/) +
+ 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](https://www.fltk.org/doc-1.4/index.html) +- [GTKMM](https://www.gtkmm.org/en/documentation.html) +- [QT](https://doc.qt.io/) + +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](http://nanapro.org/en-us/documentation/) +- [SDL](http://wiki.libsdl.org/FrontPage) +- [IMGUI](https://github.com/ocornut/imgui/tree/master/docs): + 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](https://www.sfml-dev.org/tutorials/2.5/compile-with-cmake.php) + for specifics. + + diff --git a/README_docker.md b/README_docker.md new file mode 100644 index 00000000..01893209 --- /dev/null +++ b/README_docker.md @@ -0,0 +1,71 @@ +## Docker Instructions + +If you have [Docker](https://www.docker.com/) installed, you can run this +in your terminal, when the Dockerfile is inside the .devconatiner directory: + +```bash +docker build -f ./.devcontainer/Dockerfile --tag=my_project:latest . +docker run -it my_project:latest +``` + +This command will put you in a `bash` session in a Ubuntu 20.04 Docker container, +with all of the tools listed in the [Dependencies](#dependencies) section already installed. +Additionally, you will have `g++-11` and `clang++-13` 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: + +```bash +docker build --tag=myproject:latest --build-arg GCC_VER=10 --build-arg LLVM_VER=11 . +``` + +The CC and CXX environment variables are set to GCC version 11 by default. +If you wish to use clang as your default CC and CXX environment variables, you +may do so like this: + +```bash +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](https://docs.docker.com/storage/volumes/). +TLDR: + +```bash +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](#build) using these commands: + +```bash +/starter_project# mkdir build +/starter_project# cmake -S . -B ./build +/starter_project# cmake --build ./build +``` + +You can configure and build using `clang-13`, without rebuilding the container, +with these commands: + +```bash +/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. + diff --git a/README_troubleshooting.md b/README_troubleshooting.md new file mode 100644 index 00000000..182f7f01 --- /dev/null +++ b/README_troubleshooting.md @@ -0,0 +1,57 @@ +## 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` instead of `pip` in this command, depending on your +platform. + +### 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` or `cmake --build`, your Conan dependencies will +be rebuilt. If you aren't using your system's default compiler, don't forget to +set the CC, CXX, CMAKE_C_COMPILER, and CMAKE_CXX_COMPILER variables, as +described in the 'Build using an alternate compiler' section above. + +### 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` to +find it. `conan info` displays information about the dependency graph of your +project, with colorized output in some terminals. + + cd build + conan info . + +In my terminal, the first couple lines of `conan info`'s output show all of the +project's configuration warnings in a bright yellow font. + +For example, the package `spdlog/1.5.0` depends on the package `fmt/6.1.2`. +If you were to modify the file `conanfile.py` so that it requires an +earlier version of `fmt`, such as `fmt/6.0.0`, and then run: + +```bash +conan remove -f '*' # clear Conan cache +rm -rf build # clear previous CMake build +cmake -S . -B ./build # rebuild Conan dependencies +conan info ./build +``` + +...the first line of output would be a warning that `spdlog` needs a more recent +version of `fmt`. + +