Set up your environment - Docker

  • Docker image definitions are provided to manage build environments, simplifying the process.

  • The docker compose run <platform> command is used for the simplest build usage, defaulting to a debug build with cobalt as the target.

  • Build configurations can be customized using environment variables like CONFIG and TARGET to specify optimization levels and build targets.

  • Windows builds are supported through a separate docker-compose-windows.yml file, which can be specified using the -f flag.

  • The base operating system image used for builds can be customized by passing the BASE_OS argument to docker compose build, allowing for different Debian-based images.

We provide Docker image definitions to simplify managing build environments.

The instructions below assume Docker is installed and is able to run basic hello-world verification. docker compose command is expected to be available as well.

Set up your workstation

Clone the Cobalt code repository. The following git command creates a cobalt directory that contains the repository:

$ git clone https://github.com/youtube/cobalt.git
$ cd cobalt

Usage

The simplest usage is:

docker compose run <platform>

By default, a debug build will be built, with cobalt as a target. You can override this with an environment variable, e.g.

docker compose run -e CONFIG=devel -e TARGET=nplb <platform>

where config is one of the four optimization levels, debug, devel, qa and gold, and target is the build target passed to ninja

See Cobalt README for full details.

Builds will be available in your ${COBALT_SRC}/out directory.

Windows Builds

We have a separate docker compose file for windows. Use the -f or --file flags to specify a configuration file to use.

docker compose -f docker-compose-windows.yml run win-win32

Customization

To parametrize base operating system images used for the build, pass BASE_OS as an argument to docker compose as follows:

docker compose build --build-arg BASE_OS="ubuntu:bionic" base

This parameter is defined in docker/linux/base/Dockerfile and is passed to Docker FROM ... statement.

Available parameters for customizing container execution are:

BASE_OS: passed to base image at build time to select a Debian-based base os image and version. Defaults to Debian 10. ubuntu:bionic and ubuntu:xenial are other tested examples.

PLATFORM: Cobalt build platform, passed to GN

CONFIG: Cobalt build config, passed to GN. Defaults to debug

TARGET: Build target, passed to ninja

The docker-compose.yml contains the currently defined experimental build configurations. Edit or add new service entries as needed, to build custom configurations.

Pre-built images

Troubleshooting

To debug build issues, enter the shell of the corresponding build container by launching the bash shell, i.e.

docker compose run linux-x64x11 /bin/bash

and try to build Cobalt with the usual GN / ninja flow.