How do I install the Sonic Build skill?

Run npx skillmds@latest add modbender/sonic-build in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Sonic Build safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Sonic Build?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Sonic Build free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Sonic Build?

modbender (@modbender) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Sonic Build by modbender — Agent Skill

Name: Sonic Build
Rating: 4.666666666666667 (3 reviews)
Author: modbender

Sonic Build

Build SONiC (Software for Open Networking in the Cloud) switch images from sonic-buildimage. Use when building VS/ASIC images, configuring build parallelism/memory/caching, debugging build failures, managing submodules, cleaning artifacts, or optimizing build performance. Covers all platforms (VS, broadcom, mellanox, marvell, nvidia-bluefield).

modbender Updated Sep 9, 2026 12 repo stars

File contents

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 -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

---name: sonic-builddescription: Build SONiC (Software for Open Networking in the Cloud) switch images from sonic-buildimage. Use when building VS/ASIC images, configuring build parallelism/memory/caching, debugging build failures, managing submodules, cleaning artifacts, or optimizing build performance. Covers all platforms (VS, broadcom, mellanox, marvell, nvidia-bluefield).--- # SONiC Image Build ## Quick Start ```bash 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` ```makefile 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. ```bash # 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) ```makefile SONIC_DPKG_CACHE_METHOD = rwcache SONIC_DPKG_CACHE_SOURCE = /var/cache/sonic/artifacts ``` ### Version cache (downloads) ```makefile SONIC_VERSION_CACHE_METHOD = cache ``` ## Rebuilding a Single Package ```bash 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. ```bash 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 ```bash 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

Frequently asked questions