Project setup 🟢

Resulting code: step000

In the recurring example we build throughout the chapters of this guide, we use CMake to organize the compilation of the code. This is a very standard way of handling cross-platform builds in C++, and we follow the idioms of Modern CMake.

In this first chapter, we set up a very basic C++ project, with one source file and one CMakeLists.txt file to tell how to build it in a cross-platform way.

Requirements

All we need to install is CMake and a C++ compiler, instructions are detailed below per OS.

Hint

After the installation, you can type which cmake (linux/macOS) or where cmake (Windows) to see whether your command line finds the full path to the cmake command. If not, make sure your PATH environment variable contains the directory where CMake is installed.

Linux

If you are under an Ubuntu/Debian distribution, install the following packages:

sudo apt install cmake build-essential

Other distributions have equivalent packages, make sure you have the commands cmake, make and g++ working.

Windows

Download and install CMake from the download page. You may use either Visual Studio or MinGW as the C++ compiler toolkit.

MacOS

You can install CMake using brew install cmake, and XCode to build the project.

Minimal project

The most minimal project consists then in a main.cpp source file, and a CMakeLists.txt build file.

Let us start with the classic hello world in main.cpp:

// In file 'main.cpp'
#include <iostream>

int main (int, char**) {
    std::cout << "Hello, world!" << std::endl;
    return 0;
}

In CMakeLists.txt, we specify that we want to create a target of type executable, called “App” (this will also be the name of the executable file), and whose source code is main.cpp:

# In file 'CMakeLists.txt'
add_executable(App main.cpp)

CMake also expects at the beginning of CMakeLists.txt to know the version of CMake the file is written for (minimum supported…your version) and some information about the project:

cmake_minimum_required(VERSION 3.21...3.30)
project(
    LearnWebGPU # name of the project, which will also be the name of the visual studio solution if you use it
    VERSION 0.1.0 # any version number
    LANGUAGES CXX C # programming languages used by the project
)

{{Define app target}}

{{Recommended extras}}

Building

We are now ready to build our minimal project. Open a terminal and go to the directory where you have the CMakeLists.txt and main.cpp files:

cd your/project/directory

Hint

From a Windows file explorer showing your project’s directory, press Ctrl+L, then type cmd and hit return. This opens a terminal in the current directory.

Let us now ask CMake to create the build files for our project. We ask it to isolate the build files from our source code by placing them in a build/ directory with the -B build option. This way, we can easily distinguish the generated build files from the ones we manually wrote (a.k.a. the source files):

cmake . -B build

Tip

If you are using git to version your project (which I recommend), you may create a .gitignore file and add a line with build/ in it to prevent git from versioning the generated build files.

After running the CMake command above, you should see a build/ directory which contains either a Makefile for make, a .sln file for Visual Studio or an XCode project, depending on your system.

Important

Calling CMake just prepared the project for your compiler, but did not build anything. The idea is that our CMakeLists.txt file is the source of truth of compilation options, and CMake is able to adapt it to whichever platform you build for.

Note

You can use the -G options to force a particular build system (make, Visual Studio, XCode, ninja, etc.), see cmake -h for more info.

To finally build the program and generate the App (or App.exe) executable, you can either open the generated Visual Studio or XCode solution, or type in the terminal:

cmake --build build

Then run the resulting program:

build/App  # linux/macOS
build\Debug\App.exe  # Windows

You should see the expected output:

Hello, world!

Conclusion

We now have a good basic project configuration, that we will build upon in the next chapters. In the next chapters, we will see how to integrate WebGPU to our project, how to initialize it, and how to open a window into which to draw.

Resulting code: step000