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:
- Bookworm phase — compile all packages (debs, python wheels, Docker images) into
target/debs/bookworm/ - 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 -sfor DCO sign-off- Rebase to latest master before force-push
- Add tests — run
BUILD_SKIP_TEST=nat least once - Monitor CI after push