third_party/dawn/docs/building.md

   1 # Building Dawn
   2
   3 ## System requirements
   4
   5  * Git
   6  * CMake (3.10.2 or later) (if desired)
   7  * GN (if desired)
   8  * Ninja (or other build tool)
   9  * Python, for fetching dependencies
  10  * [depot_tools] in your path
  11
  12 - Linux
  13   - The `pkg-config` command:
  14     ```sh
  15     # Install pkg-config on Ubuntu
  16     sudo apt-get install pkg-config
  17     ```
  18
  19 - Mac
  20   - [Xcode](https://developer.apple.com/xcode/) 12.2+.
  21   - The macOS 11.0 SDK. Run `xcode-select` to check whether you have it.
  22     ```sh
  23     ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs
  24     ```
  25
  26 ## Get the code and its dependencies
  27
  28 ### Using `depot_tools`
  29
  30 Dawn uses the Chromium build system and dependency management so you need to [install depot_tools] and add it to the PATH.
  31
  32 [install depot_tools]: http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up
  33
  34 ```sh
  35 # Clone the repo as "dawn"
  36 git clone https://dawn.googlesource.com/dawn dawn && cd dawn
  37
  38 # Bootstrap the gclient configuration
  39 cp scripts/standalone.gclient .gclient
  40
  41 # Fetch external dependencies and toolchains with gclient
  42 gclient sync
  43 ```
  44
  45 ### Without `depot_tools`
  46
  47 If you cannot or do not want to depend on `depot_tools`, you may use the `tools/fetch_dawn_dependencies.py` to clone the dependencies' repositories:
  48
  49 ```sh
  50 # Clone the repo as "dawn"
  51 git clone https://dawn.googlesource.com/dawn dawn && cd dawn
  52
  53 # Fetch dependencies (lose equivalent of gclient sync)
  54 python tools/fetch_dawn_dependencies.py --use-test-deps
  55 ```
  56
  57 Use `python tools/fetch_dawn_dependencies.py -h` to know more about the available options. The `--use-test-deps` option used above specifies to also fetch dependencies needed by tests. Contrary to `depot_tools`, this scripts does not figure out option-dependent requirements automatically.
  58
  59 ## Build Dawn
  60
  61 ### Compiling using CMake + Ninja
  62 ```sh
  63 mkdir -p out/Debug
  64 cd out/Debug
  65 cmake -GNinja ../..
  66 ninja # or autoninja
  67 ```
  68
  69 ### Compiling using CMake + make
  70 ```sh
  71 mkdir -p out/Debug
  72 cd out/Debug
  73 cmake ../..
  74 make # -j N for N-way parallel build
  75 ```
  76
  77 ### Compiling using gn + ninja
  78 ```sh
  79 mkdir -p out/Debug
  80 gn gen out/Debug
  81 autoninja -C out/Debug
  82 ```
  83
  84 The most common GN build option is `is_debug=true/false`; otherwise
  85 `gn args out/Debug --list` shows all the possible options.
  86
  87 On macOS you'll want to add the `use_system_xcode=true` in most cases.
  88 (and if you're a googler please get XCode from go/xcode).
  89
  90 To generate a Microsoft Visual Studio solution, add `ide=vs2022` and
  91 `ninja-executable=<dawn parent directory>\dawn\third_party\ninja\ninja.exe`.
  92 The .sln file will be created in the output directory specified.
  93
  94 ### Fuzzers on MacOS
  95 If you are attempting fuzz, using `TINT_BUILD_FUZZERS=ON`, the version of llvm
  96 in the XCode SDK does not have the needed libfuzzer functionality included.
  97
  98 The build error that you will see from using the XCode SDK will look something
  99 like this:
 100 ```
 101 ld: file not found:/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/11.0.0/lib/darwin/libclang_rt.fuzzer_osx.a
 102 ```
 103
 104 The solution to this problem is to use a full version llvm, like what you would
 105 get via homebrew, `brew install llvm`, and use something like `CC=<path to full
 106 clang> cmake ..` to setup a build using that toolchain.
 107