Skip to main content
Basis provides a Docker image that includes all required build dependencies, including CMake, Clang, protobuf, and optional ROS 1 (Noetic) packages. You can also build the framework from source if you prefer to manage your own environment.

​
Prerequisites

Before you begin, ensure you have the following installed on your host machine:
  • Docker 20.10 or later — for the recommended Docker-based workflow
  • Git — to clone the repository
  • Python 3 with pip — required only for building from source outside Docker
Basis currently targets Ubuntu Focal (20.04) as its primary build platform. This is the last Ubuntu release with ROS 1 (Noetic) support. The Docker image is built on ubuntu:focal.
The repository ships with two Docker image targets:
ImageDescription
basis-envCore build environment with CMake, Clang 18, protobuf, and Python tooling
basis-env-rosExtends basis-env with ROS Noetic (roscpp_serialization, std_msgs, sensor_msgs)
1

Clone the repository

git clone https://github.com/basis-robotics/basis.git
cd basis
2

Build the Docker images

Run the provided build script from the repository root. By default it builds both basis-env and basis-env-ros.
bash docker/build-env.sh
To build only the base image without ROS, set the BASIS_ENABLE_ROS environment variable to 0:
BASIS_ENABLE_ROS=0 bash docker/build-env.sh
The Dockerfile uses BuildKit layer caching for apt packages. Rebuilds after the initial pull are significantly faster.
3

Start a development shell

Use the run script to launch an interactive container. It mounts the repository root at /basis inside the container.
bash docker/run-env.sh
If a container named basis is already running, the script attaches to it instead of starting a new one. You can pass additional arguments directly through to bash:
bash docker/run-env.sh -c "cmake --build /basis/build"
The run script passes --privileged to Docker and mounts the repository at /basis. The working directory inside the container is /basis.
4

Build Basis inside the container

Inside the container, configure and build with CMake:
cmake -S /basis -B /basis/build -DCMAKE_BUILD_TYPE=Release
cmake --build /basis/build --parallel
sudo cmake --install /basis/build
This installs Basis to /opt/basis by default (controlled by the BASIS_INSTALL_DIR CMake variable).To enable ROS support, pass -DBASIS_ENABLE_ROS=ON:
cmake -S /basis -B /basis/build \
  -DCMAKE_BUILD_TYPE=Release \
  -DBASIS_ENABLE_ROS=ON
cmake --build /basis/build --parallel
sudo cmake --install /basis/build

​
Option 2: Build from source

If you need to build outside of Docker, you must install all dependencies manually.

​
Required dependencies

# CMake (3.25.1 or later required)
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null \
  | gpg --dearmor - \
  | sudo tee /etc/apt/trusted.gpg.d/kitware.gpg >/dev/null
sudo apt-add-repository "deb https://apt.kitware.com/ubuntu/ $(lsb_release -cs) main"
sudo apt install cmake

# Compiler and build tools
sudo apt install --no-install-recommends \
  clang \
  make \
  libstdc++-11-dev \
  libprotobuf-dev \
  protobuf-compiler \
  uuid-dev \
  git \
  ninja-build

# Python tooling (required for code generation)
pip install jsonschema pyyaml jinja2

​
Optional: ROS 1 support

To enable the rosmsg serialization plugin and use ROS 1 message types: 
sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" \
  > /etc/apt/sources.list.d/ros-latest.list'
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
sudo apt update
sudo apt install --no-install-recommends \
  ros-noetic-roscpp-serialization \
  ros-noetic-std-msgs \
  ros-noetic-sensor-msgs

​
Configure and build

1

Clone the repository

git clone https://github.com/basis-robotics/basis.git
cd basis
2

Configure with CMake

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DBASIS_ENABLE_ROS=OFF
Key CMake options:
OptionDefaultDescription
BASIS_INSTALL_DIR/opt/basisInstallation prefix
BASIS_ENABLE_ROSOFFEnable ROS 1 (Noetic) integration
BASIS_ENABLE_TESTINGON when top-levelBuild unit tests
3

Build and install

cmake --build build --parallel
sudo cmake --install build

​
Sourcing the environment

After installation, source the environment script to add Basis binaries and libraries to your shell’s search paths: 
source /opt/basis/bash/source_env.sh
This sets the following environment variables: 
export BASIS_ROOT=/opt/basis/
export PATH=${PATH}:${BASIS_ROOT}/bin
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${BASIS_ROOT}/lib:${BASIS_ROOT}/plugins/serialization:${BASIS_ROOT}/plugins/transport:${BASIS_ROOT}/unit
The Docker image adds this line to /home/basis/.bashrc automatically. When working outside Docker, add it to your own shell profile.

​
Verifying the installation

After sourcing the environment, confirm that the coordinator binary is available: 
coordinator --help
If the command is not found, verify that BASIS_ROOT/bin is in your PATH and that cmake --install completed successfully.

​
Next steps

Quickstart

Write your first Unit, run code generation, and connect to the coordinator

Unit YAML schema

Full reference for the .unit.yaml handler declaration format

Build docs developers (and LLMs) love

Get started for freeTalk to us