How do I install the Sonic Build skill?

Run npx skillmds@latest add johnalbertini14-glitch/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?

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

Sonic Build by johnalbertini14-glitch

Name: Sonic Build
Rating: 4.666666666666667 (3 reviews)
Author: johnalbertini14-glitch

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

johnalbertini14-glitch Updated Sep 21, 2026 1 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```bashcd sonic-buildimagemake initmake 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 ArchitectureTwo-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.## ConfigurationAll 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````makefileSONIC_CONFIG_BUILD_JOBS = 4BUILD_SKIP_TEST = ySONIC_BUILD_MEMORY = 24gDEFAULT_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 ProtectionWithout 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)```makefileSONIC_DPKG_CACHE_METHOD = rwcacheSONIC_DPKG_CACHE_SOURCE = /var/cache/sonic/artifacts```### Version cache (downloads)```makefileSONIC_VERSION_CACHE_METHOD = cache```## Rebuilding a Single Package```bashmake target/debs/bookworm/sonic-utilities_1.2-1_all.debmake target/docker-syncd-vs.gzls target/debs/bookworm/ | grep <name>```## Clean BuildsWhen to clean: after branch switch, rebase, or unexplained failures.```bashrm -rf target/* # always full clean, not selectivemake configure PLATFORM=vsmake SONIC_BUILD_JOBS=4 target/sonic-vs.img.gz```> Stale artifacts (`.bin`, squashfs) confuse make into skipping phases.## Submodules```bashmake init # after clone or pullgit submodule update --init --force src/<module> # fix corrupted submodule```SSH clone is more reliable than HTTPS (HTTPS can give HTTP 500).## Common PitfallsFor detailed troubleshooting, see `references/troubleshooting.md`.## PrerequisitesSee `references/prerequisites.md` for host setup (Docker, Python, jinjanator).## VS Platform NotesSee `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