Building FBOSS

FBOSS is not installed from a package manager: you build it from source inside a Docker container that carries the whole toolchain. This page covers the requirements, the container image, the build command for each stack (platform services, forwarding stack against a vendor SDK, fake SAI), build types, partial builds, and how to verify the result. The complete flag reference for the build wrapper is on run-getdeps.py Reference.

Note: The repository has no releases, no changelog, and no binary packages. Everything below builds from a checkout of github.com/meta/fboss.

Requirements

Requirement	Details
Host OS	Any Linux host that runs Docker. The build container itself is CentOS Stream 9 (`fboss/oss/docker/Dockerfile`, `FROM quay.io/centos/centos:stream9`); a Debian variant exists as `Dockerfile.debian`.
Docker	Used for the build container. The repo's helper scripts call `sudo docker ...`.
Disk	A full build "may take significant space (>50GB of storage)" according to the build snippets; mount a large volume at the scratch path.
Memory	Builds are memory-hungry. If compilation dies unexpectedly, lower parallelism (`--num-jobs`) before suspecting the compiler or the code.
Python	Python 3 inside the container runs `run-getdeps.py` and the packaging scripts.
Vendor SDK (forwarding stack on real hardware only)	A precompiled `libsai_impl.a` (or `libsai_impl.so`) plus its SAI headers from your ASIC vendor. Not needed for platform services or fake SAI builds.
Target switch (to run on hardware)	The packaging guide assumes a switch running CentOS 9 with the ASIC vendor's kernel modules installed. See Packaging and Running on a Switch.

Do not install the build dependencies on your host. The container image provides the compiler toolchain (Clang by default, with GCC available) and all system packages.

Step 1: Clone the Repository

git clone https://github.com/meta/fboss.git
cd fboss

All later commands run from the repository root.

Step 2: Build the Docker Image

# Optional: stop all containers and wipe the Docker image cache for a fresh start
sudo docker container kill -a && sudo docker container prune -f
sudo docker image prune -af

# Build the image; it is tagged fboss_image:latest
sudo docker build . -t fboss_image -f fboss/oss/docker/Dockerfile

The Dockerfile path is relative, so run it from the repository root. The image installs sccache, the CentOS CRB and EPEL repositories, the development packages FBOSS needs, and the LLVM toolchain.

Warning: The clean-up commands kill and prune all containers and images on the host, not only FBOSS ones.

Alternative: Load a Prebuilt Image

If building the image fails (for example behind a restrictive network), download an image tarball exported by the project's GitHub Actions workflows export-centos-docker-image.yml or export-debian-docker-image.yml, then load it. The published image also contains the dependency sources, so a later build does not need network access:

zstd -d fboss_debian_docker_image.tar.zst
sudo docker load < fboss_debian_docker_image.tar

Step 3: Pin Dependencies and Start the Container

FBOSS depends on many Meta open source projects (folly, fbthrift, fb303, and others). Their revisions are pinned in a tarball that you extract into build/deps/github_hashes/ before building:

rm -rf build/deps/github_hashes/
tar xvzf fboss/oss/stable_commits/latest_stable_hashes.tar.gz

Then start a long-running container with the repository mounted at /var/FBOSS/fboss.

For the platform stack (or a fake SAI build):

sudo docker run -d -it --name=FBOSS_BUILD_CONTAINER \
    -v $PWD:/var/FBOSS/fboss:z \
    -v /opt/app/localbuild:/var/FBOSS/tmp_bld_dir:z \
    fboss_image:latest bash

For the forwarding stack against a vendor SDK, also mount the SDK, whose directory contains lib/ and include/:

sudo docker run -d -it --name=FBOSS_BUILD_CONTAINER \
    -v $PWD:/var/FBOSS/fboss:z \
    -v /path_to_sdk:/opt/sdk:z \
    -v /opt/app/localbuild:/var/FBOSS/tmp_bld_dir:z \
    fboss_image:latest bash

The /opt/app/localbuild mount is optional; it puts the build tree (the scratch path) on a host volume with enough space. Enter the container:

sudo docker exec -it FBOSS_BUILD_CONTAINER bash

Step 4: Build

All builds go through fboss/oss/scripts/run-getdeps.py, a wrapper around Meta's getdeps.py (build/fbcode_builder/getdeps.py). It selects the SAI implementation, configures the toolchain, then calls getdeps, which builds every dependency and then FBOSS with CMake.

Arguments before the getdeps subcommand (build) belong to the wrapper; everything from build on is passed to getdeps unchanged.

Platform Stack

Platform services need no SDK. Build the fboss_platform_services CMake target:

cd /var/FBOSS/fboss
time ./fboss/oss/scripts/run-getdeps.py \
  build \
  --allow-system-packages \
  --build-type MinSizeRel \
  --extra-cmake-defines='{"CMAKE_CXX_STANDARD": "20", "RANGE_V3_TESTS": "OFF", "RANGE_V3_PERF": "OFF"}' \
  --scratch-path /var/FBOSS/tmp_bld_dir \
  --cmake-target fboss_platform_services \
  fboss

Forwarding Stack Against a Vendor SDK

Pass the SAI implementation, the SDK version, and where the SDK artifacts are:

cd /var/FBOSS/fboss
time ./fboss/oss/scripts/run-getdeps.py \
  --npu-sai-impl SAI_BRCM_IMPL \
  --npu-sai-sdk-version SAI_VERSION_14_0_EA_ODP \
  --npu-sai-version 1.16.1 \
  --npu-libsai-impl-path /opt/sdk \
  --npu-experiments-path /opt/sdk/experimental \
  build \
  --allow-system-packages \
  --build-type MinSizeRel \
  --extra-cmake-defines='{"CMAKE_CXX_STANDARD": "20", "RANGE_V3_TESTS": "OFF", "RANGE_V3_PERF": "OFF"}' \
  --scratch-path /var/FBOSS/tmp_bld_dir \
  fboss

Pick --npu-sai-impl and --npu-sai-sdk-version for your ASIC. Meta's officially supported values are listed on run-getdeps.py Reference, and ./fboss/oss/scripts/run-getdeps.py -h prints them. --npu-sai-sdk-version is mandatory whenever --npu-sai-impl is given; the script exits with Error: --npu-sai-sdk-version is required when using --npu-sai-impl=... otherwise. Unknown values only print a Note: ... is not a Meta officially supported value message and the build continues.

Fake SAI (No Hardware)

If you pass neither --npu-sai-impl nor --phy-sai-impl, the wrapper prints No SAI implementation provided, defaulting to fake SAI build (BUILD_SAI_FAKE=1) and builds the agent against an in-tree fake SAI. This is the build used by the Quick Start simulator and for development without a switch.

QSFP Targets Against a PHY SDK

Platforms with external PHYs (retimers) link qsfp_service against a separate PHY SAI SDK (Broadcom PAI). Because the ASIC and PHY SDKs usually use different SAI versions, the wrapper builds in passes: when you combine --npu-sai-impl with --phy-sai-impl SAI_BRCM_PAI_IMPL, it first builds everything against the NPU SDK, then rebuilds only the qsfp_targets CMake target against the PAI SDK into the same tree. The PAI SDK must provide lib/ with libepdm.a, libpai.a, libphymodepil.a and include/ with sai/, pai_macsec/, epdm/; pass it with --phy-pai-sdk-path or --phy-pai-sdk-tarball, or populate /var/FBOSS/pai_impl by hand. Details are on run-getdeps.py Reference.

Build Types

--build-type is a getdeps option:

Build type	Description	Use case
`Debug`	No optimization, full debug symbols	Development and debugging
`RelWithDebInfo`	Optimized with debug symbols	Default when `--build-type` is omitted
`MinSizeRel`	Size-optimized, no debug symbols	Production and constrained switches; used in all the repo's example commands
`Release`	Fully optimized, no debug symbols	Maximum performance

Building Only Some Targets

Pass --cmake-target <target> (a getdeps option) to build one target. Useful aggregate targets defined in the top-level CMakeLists.txt:

Target	Contents
`fboss_platform_services`	`platform_manager`, `sensor_service`, `fan_service`, `data_corral_service`, `fw_util`, `weutil`, `rackmon`, `reboot_cause_finder`, `watchdog_util`, `rma-showtech`, `fixmyfboss`, `sensor_service_client`, plus platform unit and hardware tests
`qsfp_targets`	`qsfp_service`, `qsfp_hw_test`, `qsfp_hal_test`, `wedge_qsfp_util`, and transceiver unit tests
`led_targets`	`led_service`, `led_service_hw_test`
`fboss2_targets`	`fboss2`, `fboss2-dev`, `fboss2_integration_test`, and CLI unit tests
`fboss_forwarding_stack`	Only defined for SAI or fake SAI builds: `fboss2`, `fboss2-dev`, `fsdb`, `qsfp_service`, `wedge_qsfp_util`, `diag_shell_client`, plus `wedge_agent-sai_impl`, `fboss_sw_agent`, `fboss_hw_agent-sai_impl` (or the fake agent targets)
`fboss_other_services`	`qsfp_targets`, `led_targets`, `fboss2_targets`, and FSDB
`fboss_fake_agent_targets`	Fake SAI builds only: the agent binaries and `sai_replayer-fake`
`fboss_fake_agent_test_targets`	Fake SAI builds only: `sai_test-fake`, `sai_agent_hw_test-fake`, `multi_switch_agent_hw_test`, scale and invariant tests, `switch_test`

Any add_executable or add_library name in the CMake files is also a valid target.

Building Your Local Changes

By default getdeps does not build your working tree. It fetches FBOSS at the commit pinned in build/deps/github_hashes/facebook/fboss-rev.txt (extracted from the stable hashes tarball). To build your checkout, including uncommitted changes, add --src-dir .:

time ./fboss/oss/scripts/run-getdeps.py \
  build \
  --allow-system-packages \
  --build-type MinSizeRel \
  --extra-cmake-defines='{"CMAKE_CXX_STANDARD": "20", "RANGE_V3_TESTS": "OFF", "RANGE_V3_PERF": "OFF"}' \
  --scratch-path /var/FBOSS/tmp_bld_dir \
  --src-dir . \
  fboss

Only the fboss source is overridden; the other dependencies still follow the extracted hashes, so the extraction step is still required.

One-Command Alternative: `docker-build.py`

fboss/oss/scripts/docker-build.py automates the whole sequence from the host: it extracts the stable hashes, builds the fboss_image image, starts a container named FBOSS_BUILD_CONTAINER, and runs the build with the scratch path mounted at /var/FBOSS/tmp_bld_dir. Its options:

Option	Meaning
`--scratch-path PATH`	Required. Host directory for build and install files; created if missing.
`--target T`	CMake target to build; repeat to build several targets in sequence. Default: all FBOSS targets.
`--local`	Build the local clone instead of a fresh clone at the head commit.
`--num-jobs N`	Parallel jobs for getdeps. Default: number of CPUs.
`--env-var VAR:VAL`	Extra environment variable for the build, for example `BUILD_SAI_FAKE:1`. Repeatable.
`--no-system-deps`	Build every dependency from source instead of using system packages.
`--extra-cmake-defines JSON`	Extra CMake defines passed to getdeps.
`--extras-dir DIR`	Mount this directory into the container at `/var/extras`.
`--dot-file NAME`	Mount a dotfile from your home directory (for example `.vimrc`). Repeatable.
`--no-docker-output`	Do not attach TTY output to the container.
`--use-clang` / `--no-use-clang`	Build with Clang (default) or GCC.

Toolchain Selection

run-getdeps.py inspects g++ --version. If the active compiler is GCC, it switches the container to Clang with update-alternatives --set gcc /usr/local/llvm/bin/clang and exits with an error if that fails. Pass --use-gcc to stay on GCC (it runs update-alternatives --set gcc /opt/rh/gcc-toolset-12/root/usr/bin/gcc). With Clang it also derives extra C++ flags from CMakeLists.txt and forces -std=c++20.

Verifying the Build

Everything lands under the scratch path: compiled FBOSS binaries in build/fboss/, and the dependencies' install trees (their libraries) under installed/. This is the layout package-fboss.py and the fboss-sim scripts read. Check that the binaries you expect exist:

ls /var/FBOSS/tmp_bld_dir/build/fboss/ | grep -E "agent|fboss2|qsfp_service"

To check that shared libraries resolve, package the build and run ldd on the switch as described in Packaging and Running on a Switch. For a forwarding build you should see fboss_sw_agent, fboss_hw_agent-sai_impl, and wedge_agent-sai_impl; for fake SAI builds the test binaries carry a -fake suffix (for example sai_test-fake).

Troubleshooting the Build

Symptom	Cause and fix
Compiler killed, random internal errors	Out of memory. Reduce `--num-jobs`.
Your edits are not in the binaries	You built the pinned commit. Add `--src-dir .`.
`docker build` fails on package downloads	Load the prebuilt image from GitHub Actions instead (see above).
`Error: --npu-sai-sdk-version is required...`	Add `--npu-sai-sdk-version` whenever `--npu-sai-impl` is set.
`Error: SAI_VERSION is X but the SDK's SAI headers are Y`	`--npu-sai-version` disagrees with `saiversion.h` in the SDK. Drop the flag or make it match.
Tempted to delete the scratch directory	Don't, unless you want a full rebuild; it "rarely addresses the actual failure" (AGENTS.md).

More symptoms are listed in Troubleshooting.