1 2--- 3title: "Using Bazel" 4linkTitle: "Using Bazel" 5 6--- 7 8## Overview 9 10Skia is currently migrating towards using [Bazel](https://bazel.build/) as a build system, due to 11the ability to more tightly control what and how gets built. 12 13When referring to a file in this doc, we use 14[Bazel label notation](https://bazel.build/concepts/labels), so to refer the file located at 15`$SKIA_ROOT/docs/examples/Arc.cpp`, we would say `//docs/examples/Arc.cpp`. 16 17## Learning more about Bazel 18The Bazel docs are quite good. Suggested reading order if you are new to Bazel: 19 - [Getting Started with Bazel and C++](https://bazel.build/tutorials/cpp) 20 - [WORKSPACE.bazel and external deps](https://bazel.build/docs/external) 21 - [Targets and Labels](https://bazel.build/concepts/labels) 22 - [Understanding a build](https://bazel.build/docs/build) 23 - [Configuration with .bazelrc files](https://bazel.build/docs/bazelrc) 24 25Googlers, check out [go/bazel-bites](http://go/bazel-bites) for more tips. 26 27## Building with Bazel 28 29All this assumes you have [downloaded Skia](/docs/user/download), especially having synced the 30third_party deps using `./tools/git-sync-deps`. 31 32### Linux Hosts (you are running Bazel on a Linux machine) 33You can run a command like: 34``` 35bazel build //example:hello_world_gl 36``` 37 38This uses a hermetic C++ toolchain we put together to compile Skia on a Linux host 39(implementation is in `//toolchain`. It builds the _target_ defined in 40`//examples/BUILD.bazel` named "hello_world_gl", which uses the `sk_app` framework 41we designed to make simple applications using Skia. 42 43Bazel will put this executable in `//bazel-bin/example/hello_world_gl` and tell you it did so in 44the logs. You can run this executable yourself, or have Bazel run it by modifying the command to 45be: 46``` 47bazel run //example:hello_world_gl 48``` 49 50If you want to pass one or more flags to `bazel run`, add them on the end after a `--` like: 51``` 52bazel run //example:hello_world_gl -- --flag_one=apple --flag_two=cherry 53``` 54 55### Mac Hosts (you are running Bazel on a Mac machine) 56You can run a command like: 57``` 58bazel build //example:bazel_test_exe 59``` 60 61When building for Mac, we require the user to have Xcode installed on their device so that we can 62use system headers and Mac-specific includes when compiling. Googlers, as per usual, follow the 63instructions at [go/skia-corp-xcode](http://go/skia-corp-xcode) to install Xcode. 64 65Our Bazel toolchain assumes you have `xcode-select` in your path so that we may symlink the 66user's current Xcode directory in the toolchain's cache. Make sure `xcode-select -p` 67returns a valid path. 68 69## .bazelrc Tips 70You should make a [.bazelrc file](https://bazel.build/docs/bazelrc) in your home directory where 71you can specify settings that apply only to you. These can augment or replace the ones we define 72in the `//.bazelrc` configuration file. 73 74Skia defines some [configs](https://bazel.build/docs/bazelrc#config), that is, group of settings 75and features in `//bazel/buildrc`. This file contains configs for builds that we use regularly 76(for example, in our continuous integration system). 77 78If you want to define Skia-specific configs (and options which do not conflict with other Bazel 79projects), you make a file in `//bazel/user/buildrc` which will automatically be read in. This 80file is covered by a `.gitignore` rule and should not be checked in. 81 82You may want some or all of the following entries in your `~/.bazelrc` or `//bazel/user/buildrc` 83file. 84 85### Build Skia faster locally 86Many Linux machines have a [RAM disk mounted at /dev/shm](https://www.cyberciti.biz/tips/what-is-devshm-and-its-practical-usage.html) 87and using this as the location for the Bazel sandbox can dramatically improve compile times because 88[sandboxing](https://bazel.build/docs/sandboxing) has been observed to be I/O intensive. 89 90Add the following to `~/.bazelrc` if you have a `/dev/shm` partition that is 4+ GB big. 91``` 92build --sandbox_base=/dev/shm 93``` 94 95Mac users should probably bypass sandboxing as [it is known to be slow](https://github.com/bazelbuild/bazel/issues/8230). 96``` 97build --spawn_strategy=local 98``` 99 100### Authenticate to RBE on a Linux VM 101We are in the process of setting up Remote Build Execution (RBE) for Bazel. Some users have reported 102errors when trying to use RBE (via `--config=linux_rbe`) on Linux VMs such as: 103``` 104ERROR: Failed to query remote execution capabilities: 105Error code 404 trying to get security access token from Compute Engine metadata for the default 106service account. This may be because the virtual machine instance does not have permission 107scopes specified. It is possible to skip checking for Compute Engine metadata by specifying the 108environment variable NO_GCE_CHECK=true. 109``` 110For instances where it is not possible to set the `cloud-platform` scope 111[on the VM](https://skia-review.googlesource.com/c/skia/+/525577), one can directly link to their 112GCP credentials by adding the following to `~/.bazelrc` (substituting their username for <user>) 113after logging in via `gcloud auth login`: 114``` 115build:remote --google_credentials=/usr/local/google/home/<user>/.config/gcloud/application_default_credentials.json 116``` 117 118### Make local builds compatible with remote builds (e.g. better caching) 119Add the following to `//bazel/user/buildrc` if you are on a Linux x64 box and want to be able to 120share cached build results between things you build locally and build with `--config=linux_rbe`. 121``` 122build --host_platform=//bazel/platform:linux_x64_hermetic 123``` 124For example, if you are on a laptop, using `--config=linux_rbe` will speed up builds when you have 125access to Internet, but then if you need to go offline, you can still build locally and use the 126previous build results from the remote builds. 127