✓ Verified 💻 Development ✓ Enhanced Data

Sonic Build

Build SONiC (Software for Open Networking in the Cloud) switch images from sonic-buildimage.

Rating
4.2 (398 reviews)
Downloads
26,504 downloads
Version
1.0.0

Overview

Build SONiC (Software for Open Networking in the Cloud) switch images from sonic-buildimage.

Complete Documentation

View Source →

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:

  • 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

KnobDefaultRecommendedEffect
SONIC_CONFIG_BUILD_JOBS14Parallel top-level package builds
SONIC_CONFIG_MAKE_JOBS$(nproc)defaultCompiler threads per package
BUILD_SKIP_TESTny (dev)Skip unit tests
SONIC_BUILD_MEMORYunset24gDocker --memory — contains OOM in container
SONIC_DPKG_CACHE_METHODnonerwcacheCache .deb packages for incremental builds
DEFAULT_BUILD_LOG_TIMESTAMPnonesimpleTimestamps in build logs
SONIC_CONFIG_USE_NATIVE_DOCKERD_FOR_BUILDunsetyHost 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

Installation

Terminal bash 

openclaw install sonic-build
Copied!

💻Code Examples

make SONIC_BUILD_JOBS=4 target/sonic-vs.img.gz

make-sonicbuildjobs4-targetsonic-vsimggz.txt
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`

DEFAULT_BUILD_LOG_TIMESTAMP = simple

defaultbuildlogtimestamp--simple.txt
## 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.

make SONIC_BUILDER_EXTRA_CMDLINE="--memory=24g" ...

make-sonicbuilderextracmdline--memory24g-.txt
## Caching

### DPKG cache (package-level)

ls target/debs/bookworm/ | grep <name>

ls-targetdebsbookworm--grep-name.txt
## Clean Builds

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

make SONIC_BUILD_JOBS=4 target/sonic-vs.img.gz

make-sonicbuildjobs4-targetsonic-vsimggz.txt
> Stale artifacts (`.bin`, squashfs) confuse make into skipping phases.

## Submodules
example.sh
cd sonic-buildimage
make init
make configure PLATFORM=vs   # or broadcom, mellanox, etc.
make SONIC_BUILD_JOBS=4 target/sonic-vs.img.gz
example.txt
SONIC_CONFIG_BUILD_JOBS = 4
BUILD_SKIP_TEST = y
SONIC_BUILD_MEMORY = 24g
DEFAULT_BUILD_LOG_TIMESTAMP = simple
example.sh
# Container-scoped OOM (host stays healthy):
SONIC_BUILD_MEMORY = 24g
# Or via CLI:
make SONIC_BUILDER_EXTRA_CMDLINE="--memory=24g" ...
example.sh
make target/debs/bookworm/sonic-utilities_1.2-1_all.deb
make target/docker-syncd-vs.gz
ls target/debs/bookworm/ | grep <name>
example.sh
rm -rf target/*   # always full clean, not selective
make configure PLATFORM=vs
make SONIC_BUILD_JOBS=4 target/sonic-vs.img.gz

Tags

#coding_agents-and-ides

Quick Info

Category Development
Model Claude 3.5
Complexity One-Click
Author rustiqly
Last Updated 3/10/2026
🚀
Optimized for
Claude 3.5
🧠

Ready to Install?

Get started with this skill in seconds

openclaw install sonic-build

Resources

📂
OpenClaw Skills
View on OpenClaw GitHub
→

Related Skills

✓ Verified 💻 Development

4claw

4claw — a moderated imageboard for AI agents.

🧠 Claude-Ready #ai_and-llms
)}
★ 4.4 (118)
↓ 4,990
v1.0.0
✓ Verified 💻 Development

Aap Passport

Agent Attestation Protocol - The Reverse Turing Test.

🧠 Claude-Ready #ai_and-llms
)}
★ 4.3 (89)
↓ 4,621
v1.0.0
✓ Verified 💻 Development

Acestep Lyrics Transcription

Transcribe audio to timestamped lyrics using OpenAI Whisper or ElevenLabs Scribe API.

⚡ GPT-Optimized #ai_and-llms #api #script
)}
★ 3.8 (274)
↓ 17,648
v1.0.0
✓ Verified 💻 Development

Adaptive Suite

A continuously adaptive skill suite that empowers Clawdbot.

🧠 Claude-Ready #ai_and-llms #bot
)}
★ 4.7 (88)
↓ 1,625
v1.0.0