Set up your environment - Linux

These instructions explain how Linux users set up their Cobalt development environment, clone a copy of the Cobalt code repository, and build a Cobalt binary. Note that the binary has a graphical client and must be run locally on the machine that you are using to view the client. For example, you cannot SSH into another machine and run the binary on that machine.

These instructions were tested on a fresh ubuntu:20.04 Docker image. (1/12/22) Required libraries can differ depending on your Linux distribution and version.

Set up your workstation

  1. Run the following command to install packages needed to build and run Cobalt on Linux:

    $ sudo apt update && sudo apt install -qqy --no-install-recommends \
    pkgconf ninja-build bison yasm binutils clang libgles2-mesa-dev \
    mesa-common-dev libpulse-dev libavresample-dev libasound2-dev \
    libxrender-dev libxcomposite-dev libxml2-dev curl git \
    python3.8-venv

  2. Install Node.js via nvm:

    $ export NVM_DIR=~/.nvm
$ export NODE_VERSION=12.17.0

$ curl --silent -o- https://raw.githubusercontent.com/creationix/nvm/v0.35.3/install.sh | bash

$ . $NVM_DIR/nvm.sh \
    && nvm install --lts \
    && nvm alias default lts/* \
    && nvm use default

  3. Install ccache to support build acceleration. ccache is automatically used when available, otherwise defaults to unaccelerated building:

    $ sudo apt install -qqy --no-install-recommends ccache

    We recommend adjusting the cache size as needed to increase cache hits:

    $ ccache --max-size=20G

  4. Install GN, which we use for our build system code. There are a few ways to get the binary, follow the instructions for whichever way you prefer here.

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

    $ git clone https://cobalt.googlesource.com/cobalt

  6. Set PYTHONPATH environment variable to include the full path to the top-level cobalt directory from the previous step. Add the following to the end of your ~/.bash_profile (replacing fullpathto with the actual path where you cloned the repo):

    export PYTHONPATH="/fullpathto/cobalt:${PYTHONPATH}"

    You should also run the above command in your termainal so it's available immediately, rather than when you next login.

Set up Developer Tools

  1. Enter your new cobalt directory:

    $ cd cobalt

  2. Create a Python 3 virtual environment for working on Cobalt (feel free to use virtualenvwrapper instead):

    $ python3 -m venv ~/.virtualenvs/cobalt_dev
$ source ~/.virtualenvs/cobalt_dev/bin/activate
$ pip install -r requirements.txt

  3. Install the pre-commit hooks:

    $ pre-commit install -t post-checkout -t pre-commit -t pre-push --allow-missing-config
$ git checkout -b <my-branch-name> origin/master

Build and Run Cobalt

  1. Build the code running the following command in the top-level cobalt directory. You must specify a platform when running this command. On Ubuntu Linux, the canonical platform is linux-x64x11.

    You can also use the -c command-line flag to specify a build_type. Valid build types are debug, devel, qa, and gold. If you specify a build type, the command finishes sooner. Otherwise, all types are built.

    $ python cobalt/build/gn.py [-c <build_type>] -p <platform>

  2. Compile the code from the cobalt/ directory:

    $ ninja -C out/<platform>_<build_type> <target_name>

    The previous command contains three variables:

    1. <platform> is the platform configuration that identifies the platform. As described in the Starboard porting guide, it contains a family name (like linux) and a binary variant (like x64x11), separated by a hyphen.
    2. <build_type> is the build you are compiling. Possible values are debug, devel, qa, and gold.
    3. <target_name> is the name assigned to the compiled code and it is used to run the code compiled in this step. The most common names are cobalt, nplb, and all:
      • cobalt builds the Cobalt app.
      • nplb builds Starboard's platform verification test suite to ensure that your platform's code passes all tests for running Cobalt.
      • all builds all targets.

    For example:

    ninja -C out/linux-x64x11_debug cobalt

    This command compiles the Cobalt debug configuration for the linux-x64x11 platform and creates a target named cobalt that you can then use to run the compiled code.

  3. Run the compiled code to launch the Cobalt client:

    # Note that 'cobalt' was the <target_name> from the previous step.
$ out/linux-x64x11_debug/cobalt [--url=<url>]

    The flags in the following table are frequently used, and the full set of flags that this command supports are in cobalt/browser/switches.cc.

    Flags
    allow_http Indicates that you want to use `http` instead of `https`.
    ignore_certificate_errors Indicates that you want to connect to an https host that doesn't have a certificate that can be validated by our set of root CAs.
    url Defines the startup URL that Cobalt will use. If no value is set, then Cobalt uses a default URL. This option lets you point at a different app than the YouTube app.