Installation on Ubuntu

This guide covers building and installing mosaic-core — the robot-side C++ library — on Ubuntu.

mosaic-core has been tested on Ubuntu 24.04 (x86_64 / arm64).

---

Prerequisites

System Dependencies

Install the required packages:

sudo apt-get update
sudo apt-get install -y \
  git \
  cmake \
  build-essential \
  libssl-dev \
  libopencv-dev \
  libjsoncpp-dev \
  libfmt-dev \
  libyaml-cpp-dev \
  libcpprest-dev

CMake 3.14+

Verify your CMake version:

cmake --version

If the version is below 3.14, install a newer version from cmake.org.

---

1. Clone the Repository

git clone https://github.com/ACSL-MOSAIC/mosaic-core.git
cd mosaic-core

---

2. Set Up WebRTC

mosaic-core depends on Google’s WebRTC native library (libwebrtc.a). You can either use the pre-built tarball (recommended) or build from source.

Option A: Use Pre-built Tarball (Recommended)

Pre-built tarballs for WebRTC branch 6723 are included in the repository.

x86_64:

cd third_party
tar -xzf webrtc-tarballs/webrtc-6723-x86.tar.gz
cd ..

arm64:

cd third_party
tar -xzf webrtc-tarballs/webrtc-6723-arm64.tar.gz
cd ..

After extraction, verify the library exists:

ls third_party/webrtc/src/out/Default/obj/libwebrtc.a

---

Option B: Build WebRTC from Source

Building WebRTC from source takes 1–2 hours and requires ~20 GB of disk space.

Step 1. Fetch the WebRTC source

cd third_party
bash webrtc-scripts/fetch_webrtc_source.sh
cd ..

Step 2. Build WebRTC

Run the build script for your architecture:

# x86_64
bash third_party/webrtc-scripts/build_webrtc_x86_64.sh

# arm64
bash third_party/webrtc-scripts/build_webrtc_arm64.sh

---

3. Build mosaic-core

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

CMake Options

Option	Default	Description
BUILD_PYTHON_BINDINGS	ON	Build Python bindings
BUILD_TESTS	ON	Build unit tests
BUILD_SHARED_LIBS	ON	Build as shared library

Example — disable Python bindings and tests:

cmake .. -DCMAKE_BUILD_TYPE=Release \
         -DBUILD_PYTHON_BINDINGS=OFF \
         -DBUILD_TESTS=OFF

---

4. Install

sudo make install

This installs:

• Headers → /usr/local/include/mosaic/
• Library → /usr/local/lib/
• CMake config → /usr/local/lib/cmake/mosaic-core/

You can then find the library from another CMake project with:

find_package(mosaic-core REQUIRED)
target_link_libraries(your_target mosaic::mosaic-core)

---

5. Python Bindings (Optional)

If BUILD_PYTHON_BINDINGS=ON (default), the Python package is built alongside the C++ library.

Install it in editable mode from the build output:

pip install -e build/python

Verify the installation:

import mosaic_core
print(mosaic_core.__version__)

---

Troubleshooting

libwebrtc.a not found

Make sure the WebRTC tarball was extracted correctly:

ls third_party/webrtc/src/out/Default/obj/libwebrtc.a

find_package fails for a dependency

Install the missing package via apt-get. For example, if cpprestsdk is not found:

sudo apt-get install -y libcpprest-dev

Linker errors with dl or pthread

These are system libraries and should always be available on Ubuntu. If missing:

sudo apt-get install -y libc6-dev