submodule/skia/bazel/rbe/README.md

   1 RBE configurations
   2 ==================
   3
   4 Some subdirectories of this folder are generated. For example, `gce_linux` was generated by running
   5 `make generate_linux_config`. Those generated files describe the C++ and Java toolchain that are
   6 in the RBE Docker image; these toolchains are required to run Bazel, but are **not** the toolchains
   7 that we use to compile our code.
   8
   9 We build our own, bare-bones, Docker image to use on RBE. We intend to use a hermetic toolchain
  10 (see //toolchain) that specifies everything necessary to compile and link Skia. Use of the
  11 hermetic toolchain on and off RBE makes the build reproducible and consistent across machines,
  12 and not require internet access (assuming the toolchain has been cached at least once). This setup
  13 has the desirable property of not needing to change and upload RBE Docker images if we need to
  14 change a small detail of our toolchain.
  15
  16 The only requirement we have of our Docker image (beyond the minimum requirements to run Bazel)
  17 are that it have sufficient runtime libraries to run our toolchain. For example, this means that
  18 the Linux RBE image has at least glibc 2.32, which is the current minimum requirement of the
  19 Linux binaries in our toolchain. This is the same requirement of any developer who tries to
  20 build Skia using Bazel locally.
  21
  22 Getting rbe_configs_gen
  23 -----------------------
  24 It is suggested to download a prebuilt binary from
  25 [GitHub](https://github.com/bazelbuild/bazel-toolchains/releases/tag/v5.1.1) and put that onto
  26 your PATH.
  27
  28 Creating/Updating the RBE image
  29 -------------------------------
  30 In accordance with SLSA level 1, we want to be able to have a scripted way of building our image
  31 and specify exactly what artifacts are in it. To accommodate this, we specify the exact sha256
  32 hash of the base Docker image we use and the exact versions of the packages we install on top of
  33 that. If we need to add a package or update things, it is best build the image without these
  34 qualifiers to see what was actually used, and then respecify them so if someone were to build
  35 the docker image again, they are likely to get the same image.
  36
  37 This process is:
  38  1) Modify the appropriate Dockerfile (e.g. gce_linux_container/Dockerfile) to not have the
  39     version or hash qualifiers. Also increment the appropriate VERSION variable in `Makefile`.
  40  2) Add any new packages or make any changes.
  41  3) Run `make build_linux_container` to build the image locally. One may verify it works by running
  42     something like `docker run -it gcr.io/skia-public/rbe_linux:v2 /bin/bash`.
  43  4) Note the versions and base image hash that were used. Modify the Dockerfile to use these.
  44  5) Run `make push_linux_container` to rebuild the container and push it to GCS where it can
  45     be used by our RBE workers. Note the sha256 hash of this created container
  46  6) Modify the appropriate generate step in `Makefile` (e.g. `generate_linux_config`) to refer
  47     to the correct toolchain_container. Then, run that step.
  48  7) Modify the RBE platform in `./BUILD.bazel` to refer to the new `container_image`.
  49
  50 We chose not to use Bazel rules for this container step, as that could be difficult to bootstrap
  51 without Bazel already setup. Additionally, Make is a simple and sufficient way to script the steps
  52 for SLSA purposes.
  53
  54 Defining our own Bazel RBE platforms
  55 ------------------------------------
  56 While the generated files *do* have a platform we can use (e.g.
  57 `//bazel/rbe/gce_linux/config:platform`), we do not use it because we cannot easily customize it
  58 without a risk that the changes will be lost when we update the image. Thankfully, we can specify
  59 our own platforms, which we do in `./BUILD.bazel`.
  60
  61 More details
  62 ------------
  63 https://docs.google.com/document/d/14xMZCKews69SSTfULhE8HDUzT5XvPwZ4CvRufEvcZ74/edit
  64
  65 RBE Metrics
  66 -----------
  67 http://go/skia-rbe-metrics