Bazel First-Time Setup

This document describes how to configure Bazel to connect to an EngFlow Remote Execution cluster.

1. Prepare a Docker container for remote actions

Remote actions are executed in a Docker container to ensure a consistent execution environment. The Docker container must include all system dependencies of actions. For example, a C++ compiler may be required.

If there are no special requirements, Bazel toolchains project provides Ubuntu 16.04 base images.

2. Create a remote configuration

In Bazel, a platform expresses an environment where an action can run. When performing remote execution, Bazel is instructed to build for a special EngFlow platform. This platform carries the Docker image and other environmental configuration to the remote execution service.

Once a Docker container is ready, use the rbe_configs_gen tool to generate Bazel configuration for the image. For example, the following will generate configuration for a Ubuntu 20.04 image into a engflow_config directory:

$ rbe_configs_gen \
    --toolchain_container=gcr.io/bazel-public/ubuntu2004-bazel-java11@sha256:69a78f121230c6d5cbfe2f4af8ce65481aa3f2acaaaf8e899df335f1ac1b35b5 \
    --exec_os=linux \
    --target_os=linux \
    --generate_java_configs=false \
    --output_config_path engflow_config \
    --output_src_root .

rbe_configs_gen generates a remote platform target for EngFlow in engflow_config/config/BUILD. It also outputs configuration for the C++ toolchain in the container into engflow_config/cc/.

If you already have a custom C++ compiler crosstool, it’s likely easiest to manually write the EngFlow platform rule rather than using rbe_configs_gen. Here is an example engflow_config/config/BUILD for an x86_64 Linux image:

platform(
    name = "platform",
    constraint_values = [
        "@bazel_tools//platforms:linux",
        "@bazel_tools//platforms:x86_64",
    ],
    exec_properties = {
        "container-image": "docker://gcr.io/bazel-public/ubuntu2004-java11@sha256:69a78f121230c6d5cbfe2f4af8ce65481aa3f2acaaaf8e899df335f1ac1b35b5",
    },
)

3. Set up .bazelrc.

Configure Bazel to use the EngFlow platform in .bazelrc.

1. Add common flags:

   build:engflow --define=EXECUTOR=remote
   build:engflow --disk_cache=
   build:engflow --experimental_inmemory_dotd_files
   build:engflow --experimental_inmemory_jdeps_files
   build:engflow --incompatible_strict_action_env=true
   build:engflow --remote_timeout=600
   build:engflow --nolegacy_important_outputs
   

2. Add platform flags:

   build:engflow --host_platform=//engflow_config/config:platform
   build:engflow --platforms=//engflow_config/config:platform
   

3. If not using a custom C++ toolchain already, add flags for the container’s C++ toolchain:

   build:engflow --action_env=BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1
   build:engflow --crosstool_top=//engflow_config/cc:toolchain
   

4. If Java is required, optionally use the hermetic JDK shipped with Bazel:

   build:engflow --java_runtime_version=remotejdk_11
   

5. Add the remote executor flags. Use the host name or IP address of the Load Balancer.

   • If you use TLS with our certificate (engflow-ca.crt):

     build:engflow --remote_cache=grpcs://demo.engflow.com:<PORT>            
     build:engflow --remote_executor=grpcs://demo.engflow.com:<PORT>
     build:engflow --bes_backend=grpcs://demo.engflow.com:<PORT>
     build:engflow --bes_results_url=https://demo.engflow.com:<PORT>/invocation/
     build:engflow --tls_certificate=<PATH>/engflow-remote-execution/engflow-ca.crt
     

   • If you don’t use TLS:

     build:engflow --remote_cache=grpc://<LOAD_BALANCER_IP>:<PORT>
     build:engflow --remote_executor=grpc://<LOAD_BALANCER_IP>:<PORT>
     build:engflow --bes_backend=grpc://demo.engflow.com:<PORT>
     build:engflow --bes_results_url=http://demo.engflow.com:<PORT>/invocation/
     

Usage

We recommend using the latest available Bazel version.

bazel build --config=engflow //foo:bar