blob: 00881b2f7e5c0d30d8b9299cafe7c2fc104aea10 [file] [log] [blame] [view]
Jaswant Panchumarti14d1f6c2024-07-10 02:59:02 +00001# Quickstart With CMake
2
3This document is designed to allow you to build Dawn with CMake and link to it from other CMake projects. If you're planning to work on Dawn specifically, please use `gclient` and `depot_tools`. It ensures
4that you always get the right dependencies and compilers.
5
6## Prerequisites
7
8- A compatible platform (e.g. Windows, macOS, Linux, etc.). Most platforms are fully supported.
9- A compatible C++ compiler supporting at least C++17. Most major compilers are supported.
10- Git for interacting with the Dawn source code repository.
11- CMake for building your project and Dawn. Dawn supports CMake 3.13+.
12
13## Getting the Dawn Code
14
15```shell
16# Change to the directory where you want to create the code repository
17$ git clone https://dawn.googlesource.com/dawn
18Cloning into 'dawn'...
19```
20
21Git will create the repository within a directory named `dawn`. Navigate into this directory and configure the project.
22
23## Build and install Dawn with CMake
24```shell
25$ cd dawn
26$ cmake -S . -B out/Release -DDAWN_FETCH_DEPENDENCIES=ON -DDAWN_ENABLE_INSTALL=ON -DCMAKE_BUILD_TYPE=Release
27...
28-- Configuring done (34.9s)
29-- Generating done (0.8s)
30-- Build files have been written to: ${PWD}/out/Release
31```
32
33- `DAWN_FETCH_DEPENDENCIES=ON` uses a Python script `fetch_dawn_dependencies.py` as a less tedious alternative to setting up depot_tools and fetching dependencies via `gclient`.
34- `DAWN_ENABLE_INSTALL=ON` configures the project to install binaries, headers and cmake configuration files in a directory of your choice. This allows other projects to discover Dawn in CMake and link with it.
35
36Now you can build Dawn:
37
38```shell
39$ cmake --build out/Release
40...
41[100%] Linking CXX static library libdawn_utils.a
42[100%] Built target dawn_utils
43```
44
45Once you have built the Dawn library, install it with `cmake`
46
47```shell
48$ cmake --install out/Release --prefix install/Release
49```
50
51This installs Dawn from the `out/Release` build tree into `install/Release`.
52
53## Linking your code to the Dawn installation
54
55### Create test code
56
57```shell
58$ mkdir TestDawn
59$ cd TestDawn
60```
61
62Now, create a `hello_webgpu.cpp` C++ file within the `TestDawn` directory.
63
64```cpp
Loko Kungc2aeab72024-07-25 20:08:34 +000065#include <webgpu/webgpu_cpp.h>
Nicolas Chavez498fe972024-10-14 18:24:04 +000066#include <webgpu/webgpu_cpp_print.h>
Loko Kungc2aeab72024-07-25 20:08:34 +000067
Jaswant Panchumarti14d1f6c2024-07-10 02:59:02 +000068#include <cstdlib>
69#include <iostream>
Jaswant Panchumarti14d1f6c2024-07-10 02:59:02 +000070
71int main(int argc, char *argv[]) {
72 wgpu::InstanceDescriptor instanceDescriptor{};
73 instanceDescriptor.features.timedWaitAnyEnable = true;
74 wgpu::Instance instance = wgpu::CreateInstance(&instanceDescriptor);
75 if (instance == nullptr) {
76 std::cerr << "Instance creation failed!\n";
77 return EXIT_FAILURE;
78 }
79 // Synchronously request the adapter.
80 wgpu::RequestAdapterOptions options = {};
81 wgpu::Adapter adapter;
82 wgpu::RequestAdapterCallbackInfo callbackInfo = {};
83 callbackInfo.nextInChain = nullptr;
84 callbackInfo.mode = wgpu::CallbackMode::WaitAnyOnly;
85 callbackInfo.callback = [](WGPURequestAdapterStatus status,
86 WGPUAdapter adapter, const char *message,
87 void *userdata) {
88 if (status != WGPURequestAdapterStatus_Success) {
89 std::cerr << "Failed to get an adapter:" << message;
90 return;
91 }
92 *static_cast<wgpu::Adapter *>(userdata) = wgpu::Adapter::Acquire(adapter);
93 };
94 callbackInfo.userdata = &adapter;
95 instance.WaitAny(instance.RequestAdapter(&options, callbackInfo), UINT64_MAX);
96 if (adapter == nullptr) {
97 std::cerr << "RequestAdapter failed!\n";
98 return EXIT_FAILURE;
99 }
100
101 wgpu::DawnAdapterPropertiesPowerPreference power_props{};
102
103 wgpu::AdapterInfo info{};
104 info.nextInChain = &power_props;
105
106 adapter.GetInfo(&info);
107 std::cout << "VendorID: " << std::hex << info.vendorID << std::dec << "\n";
108 std::cout << "Vendor: " << info.vendor << "\n";
109 std::cout << "Architecture: " << info.architecture << "\n";
110 std::cout << "DeviceID: " << std::hex << info.deviceID << std::dec << "\n";
111 std::cout << "Name: " << info.device << "\n";
112 std::cout << "Driver description: " << info.description << "\n";
113 return EXIT_SUCCESS;
114}
115```
116
117### Create CMakeLists.txt file
118
119Now, create a `CMakeLists.txt` file within the `TestDawn` directory like the following:
120
121```cmake
122cmake_minimum_required(VERSION 3.13)
123
124project(hello_webgpu)
125
126find_package(Dawn REQUIRED)
127add_executable(hello_webgpu hello_webgpu.cpp)
128
129# Declare dependency on the dawn::webgpu_dawn library
130target_link_libraries(hello_webgpu dawn::webgpu_dawn)
131```
132
133For more information on how to create CMakeLists.txt files, consult the [CMake Tutorial](https://cmake.org/getting-started/).
134
135### Build test project
136
137Configure the CMake build from a fresh binary directory. This configuration is called an “out of source” build and is the preferred method for CMake projects.
138
139```shell
140$ export CMAKE_PREFIX_PATH=/path/to/dawn/install/Release
141$ cmake -S . -B out/Release -DCMAKE_BUILD_TYPE=Release
142...
143-- Configuring done (0.2s)
144-- Generating done (0.0s)
145-- Build files have been written to: ${PWD}/out/Release
146```
147
148Now build our test application:
149
150```shell
151$ cmake --build out/Release
152[ 50%] Building CXX object CMakeFiles/hello_webgpu.dir/hello_webgpu.cpp.o
153[100%] Linking CXX executable hello_webgpu
154[100%] Built target hello_webgpu
155```
156
157Now run your binary:
158
159```shell
160$ ./out/Release/hello_webgpu
161VendorID: 8086
162Vendor: intel
163Architecture: gen-12lp
164DeviceID: 9a60
165Name: Intel(R) UHD Graphics (TGL GT1)
166Driver description: Intel open-source Mesa driver: Mesa 23.2.1-1ubuntu3.1~22.04.2
167```
168
169Note: You may move the contents of `install/Release` to any other directory and `cmake` will still be able to discover dawn as long as `CMAKE_PREFIX_PATH` points to the new install tree.