MY_PROJECT

About This Template

Ideally you shouldn't have to think too hard your application's build system. This template aims to make building a C++ project as simple and easy as possible on all major platforms (Windows, MacOS, and Linux) while not overcomplicating the setup process by providing too many options. This is an intentionally simple template.

This template provides a cross platform way to build your code using CMake (the most popular C++ build system). There is also a Python build script that runs all of the CMake commands for you to make it as easy as possible.

Source files are stored in the src folder, header files are stored in the include folder, and tests are stored in the tests folder. All of these file paths are customizable. The header files folder can be removed and so can the tests folder if you disable testing.

Testing is done through GoogleTest and can be disabled if you want.

A Clang Format file is provided that can (and probably should) be modified. This provides an easy way to format your code so that you don't need to obsess over code syle. You can also remove it if you want.

Source files with the .c, .cpp, .cc, .cxx, and c++ extensions are all recognized.

This code is licensed under the Unlicense license which means you can do anything with this template without even needing to give credit.

How to Use This Template (Getting Started)

You'll need to customize a few things before you get started.

• In CMakeLists.txt:
  • Replace MY_PROJECT (line 7) with this project's name. This will be the name of the main compiled executable. It should also match name of the Git repo.
  • Optionally change the C++ standard from C++17 (line 10).
  • Optionally change the name of the folder where all of your header files will live (line 11). You can also remove this line to not have an include folder. The default is include.
  • Optionally change the name of the main file (line 12). The default is main.cpp.
  • Optionally change the name of the folder where all of your source code will live (line 13). The default is src.
  • Optionally disable the testing with GoogleTest (line 14) by replacing ON with OFF. The run_test executable will not be built if disabled.
  • Optionally change the name of the folder where all of your test files will live (line 15). The default is tests. This directory can be removed if testing is disabled.
• In this file:
  • Find and replace MY_PROJECT with this project's name.
• Optionally change the Clang Format settings in .clang-format.
• Optionally update or remove license info in LICENSE.

How to Build

Requirements

Ensure you have CMake (make sure it's on the path, i.e. cmake --version works in your terminal), a CMake generator, and a C/C++ compiler supported by CMake and your generator.

Once you have the repository cloned you can build with the Python build script, or you can build manually with CMake. Check out how to run the compiled executables once you've built successfully.

You can also use an IDE (like Visual Studio) if you'd prefer.

Python Build Script

If you have Python installed you can build using the build.py script. If you're on a POSIX OS (e.g. Linux or MacOS) you should be able to just run ./build.py, otherwise run the script with either python3 or python.

python3 build.py

If you don't get an error message from the script then you're done.

Using the Python build script you can easily switch between debug and release builds by adding the --debug and --release flags (debug by default). The script will automatically reconfigure CMake if it needs to.

python3 build.py --release

You can add -p or --parallel to compile with all CPU cores. Keep in mind that this can make error messages and warnings less cohesive.

python3 build.py -p

For more help info run the script with -h or --help.

Note

If you are on Windows the script will use Visual Studio 17 2022 as it's generator. Otherwise it will use Unix Makefiles. If you want to use the Python script make sure you have the correct generator installed.

Building With CMake

Start by configuring CMake in a build folder called build.

cmake -B build

Note

If you're using a single configuration generator like Unix Makefiles (you probably are if you're on MacOS/Linux) then you can configure for release mode by adding --DCMAKE_BUILD_TYPE=Release.

cmake -B build --DCMAKE_BUILD_TYPE=Release

Now we can build the project by running this:

cmake --build build

Note

If you're using a multi-configuration generator like Visual Studio 17 2022 (you probably are if you're on Windows) then you can build in release mode by adding --config Release.

cmake --build build --config Release

Running the Executables

Successfully built executables will be in your build directory.

Note

If you're on Windows using Visual Studio as your generator then your executables will be in the Debug sub-folder of the build directory (or Release if you built in release mode).

You can run your compiled executable like this:

On MacOS/Linux (using Unix Makefiles or a similar generator):

./build/MY_PROJECT

On Windows (using Visual Studio 17 2022 or a similar generator):

.\build\Debug\MY_PROJECT.exe        # Using Visual Studio on Windows (debug)
.\build\Release\MY_PROJECT.exe      # Using Visual Studio on Windows (release)

The same goes for the run_tests executable (just replace MY_PROJECT with run_tests).

Using an IDE

Visual Studio / CLion

Just open the project folder with the editor. CMake should automatically be configured.

Xcode

To use Xcode, configure CMake and then open the .xcodeproj folder.

cmake -B build -G "Xcode"
open build/MY_PROJECT.xcodeproj

VSCode

You can either use the integrated terminal and the build info above or you can use the CMake Tools extension to build and run with shift+F5 (you can just build with F7).