Jaswant Panchumarti | 14d1f6c | 2024-07-10 02:59:02 +0000 | [diff] [blame] | 1 | # Quickstart With CMake |
| 2 | |
| 3 | This 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 |
| 4 | that 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 |
| 18 | Cloning into 'dawn'... |
| 19 | ``` |
| 20 | |
| 21 | Git 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 | |
| 36 | Now 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 | |
| 45 | Once you have built the Dawn library, install it with `cmake` |
| 46 | |
| 47 | ```shell |
| 48 | $ cmake --install out/Release --prefix install/Release |
| 49 | ``` |
| 50 | |
| 51 | This 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 | |
| 62 | Now, create a `hello_webgpu.cpp` C++ file within the `TestDawn` directory. |
| 63 | |
| 64 | ```cpp |
Loko Kung | c2aeab7 | 2024-07-25 20:08:34 +0000 | [diff] [blame] | 65 | #include <webgpu/webgpu_cpp.h> |
Nicolas Chavez | 498fe97 | 2024-10-14 18:24:04 +0000 | [diff] [blame] | 66 | #include <webgpu/webgpu_cpp_print.h> |
Loko Kung | c2aeab7 | 2024-07-25 20:08:34 +0000 | [diff] [blame] | 67 | |
Jaswant Panchumarti | 14d1f6c | 2024-07-10 02:59:02 +0000 | [diff] [blame] | 68 | #include <cstdlib> |
| 69 | #include <iostream> |
Jaswant Panchumarti | 14d1f6c | 2024-07-10 02:59:02 +0000 | [diff] [blame] | 70 | |
| 71 | int 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 | |
| 119 | Now, create a `CMakeLists.txt` file within the `TestDawn` directory like the following: |
| 120 | |
| 121 | ```cmake |
| 122 | cmake_minimum_required(VERSION 3.13) |
| 123 | |
| 124 | project(hello_webgpu) |
| 125 | |
| 126 | find_package(Dawn REQUIRED) |
| 127 | add_executable(hello_webgpu hello_webgpu.cpp) |
| 128 | |
| 129 | # Declare dependency on the dawn::webgpu_dawn library |
| 130 | target_link_libraries(hello_webgpu dawn::webgpu_dawn) |
| 131 | ``` |
| 132 | |
| 133 | For more information on how to create CMakeLists.txt files, consult the [CMake Tutorial](https://cmake.org/getting-started/). |
| 134 | |
| 135 | ### Build test project |
| 136 | |
| 137 | Configure 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 | |
| 148 | Now 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 | |
| 157 | Now run your binary: |
| 158 | |
| 159 | ```shell |
| 160 | $ ./out/Release/hello_webgpu |
| 161 | VendorID: 8086 |
| 162 | Vendor: intel |
| 163 | Architecture: gen-12lp |
| 164 | DeviceID: 9a60 |
| 165 | Name: Intel(R) UHD Graphics (TGL GT1) |
| 166 | Driver description: Intel open-source Mesa driver: Mesa 23.2.1-1ubuntu3.1~22.04.2 |
| 167 | ``` |
| 168 | |
| 169 | Note: 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. |