SONiC Image Build

Quick Start

cd sonic-buildimage
make init
make configure PLATFORM=vs   # or broadcom, mellanox, etc.
make SONIC_BUILD_JOBS=4 target/sonic-vs.img.gz

For dev builds (skip tests): add BUILD_SKIP_TEST=y.

Build Architecture

Two-phase build via GNU Make → slave.mk → sonic-slave Docker container:

1. Bookworm phase — compile all packages (debs, python wheels, Docker images) into target/debs/bookworm/
2. Trixie phase — assemble final image from phase 1 packages into target/debs/trixie/

Makefile invokes Makefile.work with different BLDENV per phase. The configure target creates per-distro directories.

Configuration

All knobs in rules/config. Override in rules/config.user (gitignored, persists across rebases).

Key Knobs

Knob	Default	Recommended	Effect
SONIC_CONFIG_BUILD_JOBS	1	4	Parallel top-level package builds
SONIC_CONFIG_MAKE_JOBS	$(nproc)	default	Compiler threads per package
BUILD_SKIP_TEST	n	y (dev)	Skip unit tests
SONIC_BUILD_MEMORY	unset	24g	Docker --memory — contains OOM in container
SONIC_DPKG_CACHE_METHOD	none	rwcache	Cache .deb packages for incremental builds
DEFAULT_BUILD_LOG_TIMESTAMP	none	simple	Timestamps in build logs
SONIC_CONFIG_USE_NATIVE_DOCKERD_FOR_BUILD	unset	y	Host Docker daemon instead of DinD

Recommended rules/config.user

SONIC_CONFIG_BUILD_JOBS = 4
BUILD_SKIP_TEST = y
SONIC_BUILD_MEMORY = 24g
DEFAULT_BUILD_LOG_TIMESTAMP = simple

Parallelism

Rule of thumb: JOBS × 6GB ≤ available RAM.

• JOBS=1: ~3h VS build, ~10GB RAM
• JOBS=4: significant speedup, ~20GB RAM
• JOBS=8: OOM risk on <48GB RAM

Why JOBS=1 is slow: 64/194 packages depend on libswsscommon (critical path bottleneck). JOBS=1 leaves most cores idle.

Memory Protection

Without limits, parallel builds can trigger the kernel OOM killer on any host process.

# Container-scoped OOM (host stays healthy):
SONIC_BUILD_MEMORY = 24g
# Or via CLI:
make SONIC_BUILDER_EXTRA_CMDLINE="--memory=24g" ...

Caching

DPKG cache (package-level)

SONIC_DPKG_CACHE_METHOD = rwcache
SONIC_DPKG_CACHE_SOURCE = /var/cache/sonic/artifacts

Version cache (downloads)

SONIC_VERSION_CACHE_METHOD = cache

Rebuilding a Single Package

make target/debs/bookworm/sonic-utilities_1.2-1_all.deb
make target/docker-syncd-vs.gz
ls target/debs/bookworm/ | grep <name>

Clean Builds

When to clean: after branch switch, rebase, or unexplained failures.

rm -rf target/*   # always full clean, not selective
make configure PLATFORM=vs
make SONIC_BUILD_JOBS=4 target/sonic-vs.img.gz

Stale artifacts (.bin, squashfs) confuse make into skipping phases.

Submodules

make init                                          # after clone or pull
git submodule update --init --force src/<module>    # fix corrupted submodule

SSH clone is more reliable than HTTPS (HTTPS can give HTTP 500).

Common Pitfalls

For detailed troubleshooting, see references/troubleshooting.md.

Prerequisites

See references/prerequisites.md for host setup (Docker, Python, jinjanator).

VS Platform Notes

See references/vs-platform.md for VS-specific details (TAP devices, port mapping, sai.profile, oper speed).

PR Submission

• Single commit per PR (squash before push)
• git commit -s for DCO sign-off
• Rebase to latest master before force-push
• Add tests — run BUILD_SKIP_TEST=n at least once
• Monitor CI after push