[docs] Update build prerequisites for Ubuntu 24.04 and add performance tips by rustiqly · Pull Request #25522 · sonic-net/sonic-buildimage

rustiqly · 2026-02-15T17:38:05Z

Changes

Ubuntu 24.04 support

Updated the recommended OS line to include Ubuntu 24.04 alongside 22.04
Added a note about Python 3.12+ breaking j2cli (the imp module was removed) and that jinjanator is the drop-in replacement

Prerequisites script improvements

Promoted running scripts/prerequisites.sh locally (after clone) as the primary option
Kept the curl | bash one-liner as a secondary option for fresh setups
Documented environment variable overrides (SONIC_REPO, SONIC_DIR, BRANCH)

Build performance tips (new section)

Parallelism vs memory trade-off table (JOBS × 6GB ≤ RAM)
SONIC_BUILD_MEMORY for container-scoped OOM protection
BUILD_SKIP_TEST=y for faster dev iteration
rules/config.user example for persistent config

Motivation

New contributors frequently hit these issues:

Build fails on Ubuntu 24.04 due to j2cli/imp (our PR [prerequisites] Fix j2 install for Python 3.12+ hosts #25402 fixed the script, but README still says 22.04 only)
OOM kills at higher parallelism with no guidance on memory requirements (our PR [build] Add SONIC_BUILD_MEMORY config to limit container memory #25411 added the config knob)
No documentation on rules/config.user for persistent build settings

This PR consolidates our learnings into the main README.

mssonicbld · 2026-02-15T17:38:13Z

/azp run Azure.sonic-buildimage

azure-pipelines · 2026-02-15T17:38:23Z

Azure Pipelines successfully started running 1 pipeline(s).

Copilot

Pull request overview

Updates the main build documentation to better support Ubuntu 24.04 hosts and to capture practical build performance guidance for contributors building SONiC images.

Changes:

Extend recommended host OS guidance to include Ubuntu 24.04 and explain the Python 3.12 imp removal impact on legacy j2cli.
Reframe scripts/prerequisites.sh usage (local run vs curl | bash) and document environment-variable overrides.
Add a new “Build performance tips” section covering RAM vs parallelism, container memory limiting, skipping tests, and rules/config.user.

mssonicbld · 2026-02-18T04:20:39Z

/azp run Azure.sonic-buildimage

azure-pipelines · 2026-02-18T04:20:50Z

Azure Pipelines successfully started running 1 pipeline(s).

rustiqly · 2026-02-18T04:21:25Z

Addressed all three Copilot review comments in the latest push:

Prerequisites script cloning twice — Clarified that curl | bash is primary (for fresh setups), local bash scripts/prerequisites.sh is secondary (after cloning). Added note that the script skips cloning if the directory already exists.
Env var override clarity — Simplified to a single-line example.
Memory formula inconsistency — Fixed the formula to account for ~4 GB base overhead: (JOBS × 5 GB) + 4 GB ≤ available RAM, which aligns with the table (1×5+4=9≈10, 4×5+4=24, 8×5+4=44≈48).

mssonicbld · 2026-02-18T04:22:53Z

/azp run Azure.sonic-buildimage

azure-pipelines · 2026-02-18T04:23:05Z

Azure Pipelines successfully started running 1 pipeline(s).

mssonicbld · 2026-02-23T16:55:41Z

/azp run Azure.sonic-buildimage

azure-pipelines · 2026-02-23T16:55:52Z

Azure Pipelines successfully started running 1 pipeline(s).

mssonicbld · 2026-02-24T15:06:31Z

/azp run Azure.sonic-buildimage

azure-pipelines · 2026-02-24T15:06:44Z

Azure Pipelines successfully started running 1 pipeline(s).

mssonicbld · 2026-02-24T17:07:25Z

/azp run Azure.sonic-buildimage

azure-pipelines · 2026-02-24T17:07:38Z

Azure Pipelines successfully started running 1 pipeline(s).

mssonicbld · 2026-02-25T15:03:42Z

/azp run Azure.sonic-buildimage

azure-pipelines · 2026-02-25T15:03:55Z

Azure Pipelines successfully started running 1 pipeline(s).

mssonicbld · 2026-02-26T15:10:22Z

/azp run Azure.sonic-buildimage

azure-pipelines · 2026-02-26T15:10:33Z

Azure Pipelines successfully started running 1 pipeline(s).

rustiqly · 2026-02-27T04:49:51Z

Addressed all 3 Copilot review threads:

Clarified prerequisites script behavior when clone already exists (set SONIC_DIR)
Improved env var override documentation
Fixed RAM table to match formula (JOBS × 6 GB + 4 GB)

mssonicbld · 2026-02-27T04:50:42Z

/azp run Azure.sonic-buildimage

azure-pipelines · 2026-02-27T04:50:54Z

Azure Pipelines successfully started running 1 pipeline(s).

yxieca · 2026-02-28T12:10:30Z

CI failures: Azure.sonic-buildimage (t2, optional t1-lag-vpp). Please address/re-run.\n\nAI agent on behalf of Ying.

rustiqly · 2026-02-28T14:57:07Z

The t2 and t1-lag-vpp (optional) failures are infra-flaky KVM tests — same pattern seen across many PRs currently. All builds pass. Will need a maintainer to re-trigger Azure pipelines when convenient.

yxieca · 2026-02-28T15:13:29Z

CI is currently failing (Azure/Elastictest). Please re-run or investigate the failing jobs; happy to re-review once green. AI agent on behalf of Ying.

yxieca · 2026-02-28T18:12:44Z

Quick pass: change looks fine. CI has failing Azure impacted-area tests; please rerun/check and update. AI agent on behalf of Ying.

yxieca · 2026-02-28T21:12:35Z

Quick check: CI is currently failing on this PR. Please address the failing checks and I can re-review once it's green.\n\n— AI agent on behalf of Ying

rustiqly · 2026-03-01T01:57:51Z

The CI failures here are Azure infrastructure flaky tests (kvmtest-t2, vpp, dualtor, etc.) — not related to the code change. These same tests fail across many unrelated PRs. A maintainer CI re-trigger should get them green. Thanks!

yxieca · 2026-03-01T03:12:06Z

AI agent on behalf of Ying: CI has failing checks at the moment (see GitHub/Azure status). Please re-run or fix failures; I’ll re-review once green.

yxieca · 2026-03-01T06:21:08Z

AI agent on behalf of Ying: Azure.sonic-buildimage failed (kvmtest-t2 / optional kvmtest-t1-lag-vpp). Please re-run/resolve.

yxieca · 2026-03-01T09:20:38Z

AI agent on behalf of Ying: quick scan looks fine, but CI currently shows failures/pending. Please check the failing jobs and rerun; I’ll re-review once green.

yxieca · 2026-03-01T12:20:37Z

CI shows failures (Azure/impacted-area tests). Please re-run or confirm if infra flake. Once green, I can approve.\n\nAI agent on behalf of Ying.

yxieca · 2026-03-01T15:20:37Z

AI agent on behalf of Ying: quick check shows outstanding issues.

CI failing: Azure.sonic-buildimage; Azure.sonic-buildimage (Test impacted-area-kvmtest-t2 by Elastictest); Azure.sonic-buildimage (Test kvmtest-t1-lag-vpp by Elastictest [OPTIONAL]).
Please address/re-run; I’ll re-check.

yxieca

AI agent on behalf of Ying. Quick review: [docs]. No issues found.

yxieca

AI agent on behalf of Ying. Quick review: [docs] Update build prerequisites for Ubuntu 24.04 and add performance tips. No issues found.

mssonicbld · 2026-03-02T15:03:04Z

/azp run Azure.sonic-buildimage

azure-pipelines · 2026-03-02T15:03:17Z

Azure Pipelines successfully started running 1 pipeline(s).

…e tips - Add Ubuntu 24.04 as supported build OS with Python 3.12+ note - Promote running prerequisites.sh locally instead of curl-piping - Document environment variable overrides for prerequisites.sh - Add build performance section: parallelism/memory trade-offs, OOM protection, test skipping, and rules/config.user usage Signed-off-by: Rustiqly <rustiqly@users.noreply.github.com>

- Clarify that running locally requires setting SONIC_DIR to existing clone - Explain that existing clone skips clone/checkout, installs prereqs only - Fix RAM table to match formula (JOBS × 6 GB + 4 GB) Signed-off-by: Rustiqly <rustiqly@users.noreply.github.com>

mssonicbld · 2026-03-04T15:07:23Z

/azp run Azure.sonic-buildimage

azure-pipelines · 2026-03-04T15:07:35Z

Azure Pipelines successfully started running 1 pipeline(s).

…e tips (sonic-net#25522) * [docs] Update build prerequisites for Ubuntu 24.04 and add performance tips - Add Ubuntu 24.04 as supported build OS with Python 3.12+ note - Promote running prerequisites.sh locally instead of curl-piping - Document environment variable overrides for prerequisites.sh - Add build performance section: parallelism/memory trade-offs, OOM protection, test skipping, and rules/config.user usage Signed-off-by: Rustiqly <rustiqly@users.noreply.github.com> * Address Copilot review: clarify prerequisites usage and fix RAM table - Clarify that running locally requires setting SONIC_DIR to existing clone - Explain that existing clone skips clone/checkout, installs prereqs only - Fix RAM table to match formula (JOBS × 6 GB + 4 GB) Signed-off-by: Rustiqly <rustiqly@users.noreply.github.com> --------- Signed-off-by: Rustiqly <rustiqly@users.noreply.github.com> Co-authored-by: Rustiqly <rustiqly@users.noreply.github.com> Signed-off-by: Feng Pan <fenpan@microsoft.com>

…e tips (sonic-net#25522) * [docs] Update build prerequisites for Ubuntu 24.04 and add performance tips - Add Ubuntu 24.04 as supported build OS with Python 3.12+ note - Promote running prerequisites.sh locally instead of curl-piping - Document environment variable overrides for prerequisites.sh - Add build performance section: parallelism/memory trade-offs, OOM protection, test skipping, and rules/config.user usage Signed-off-by: Rustiqly <rustiqly@users.noreply.github.com> * Address Copilot review: clarify prerequisites usage and fix RAM table - Clarify that running locally requires setting SONIC_DIR to existing clone - Explain that existing clone skips clone/checkout, installs prereqs only - Fix RAM table to match formula (JOBS × 6 GB + 4 GB) Signed-off-by: Rustiqly <rustiqly@users.noreply.github.com> --------- Signed-off-by: Rustiqly <rustiqly@users.noreply.github.com> Co-authored-by: Rustiqly <rustiqly@users.noreply.github.com>

rustiqly requested a review from lguohan as a code owner February 15, 2026 17:38

lihuay requested a review from Copilot February 16, 2026 03:03

Copilot started reviewing on behalf of lihuay February 16, 2026 03:03 View session

Copilot AI reviewed Feb 16, 2026

View reviewed changes

Comment thread README.md

Comment thread README.md Outdated

Comment thread README.md Outdated

rustiqly force-pushed the docs/update-build-prerequisites branch from becc6a4 to d77a35c Compare February 18, 2026 04:20

rustiqly force-pushed the docs/update-build-prerequisites branch 2 times, most recently from 7b7d0cb to f88bb1a Compare February 24, 2026 15:01

rustiqly force-pushed the docs/update-build-prerequisites branch from f88bb1a to 41fd4e6 Compare February 24, 2026 17:01

rustiqly force-pushed the docs/update-build-prerequisites branch from 41fd4e6 to cf5046f Compare February 25, 2026 15:01

rustiqly mentioned this pull request Feb 26, 2026

[CI] Flaky kvmtest-t1-lag failures on unrelated PRs #25694

Open

rustiqly force-pushed the docs/update-build-prerequisites branch from cf5046f to cb87cad Compare February 26, 2026 15:01

yxieca approved these changes Mar 1, 2026

View reviewed changes

rustiqly force-pushed the docs/update-build-prerequisites branch from 3b9d6e3 to 734cf23 Compare March 2, 2026 15:01

rustiqly force-pushed the docs/update-build-prerequisites branch from 734cf23 to 14fc5a0 Compare March 3, 2026 15:02

rustiqly added 2 commits March 4, 2026 07:04

rustiqly force-pushed the docs/update-build-prerequisites branch from 14fc5a0 to 5fcdc08 Compare March 4, 2026 15:04

lihuay merged commit f57d63b into sonic-net:master Mar 4, 2026
8 of 15 checks passed

Conversation

rustiqly commented Feb 15, 2026

Changes

Ubuntu 24.04 support

Prerequisites script improvements

Build performance tips (new section)

Motivation

Uh oh!

mssonicbld commented Feb 15, 2026

Uh oh!

azure-pipelines Bot commented Feb 15, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mssonicbld commented Feb 18, 2026

Uh oh!

azure-pipelines Bot commented Feb 18, 2026

Uh oh!

rustiqly commented Feb 18, 2026

Uh oh!

mssonicbld commented Feb 18, 2026

Uh oh!

azure-pipelines Bot commented Feb 18, 2026

Uh oh!

mssonicbld commented Feb 23, 2026

Uh oh!

azure-pipelines Bot commented Feb 23, 2026

Uh oh!

mssonicbld commented Feb 24, 2026

Uh oh!

azure-pipelines Bot commented Feb 24, 2026

Uh oh!

mssonicbld commented Feb 24, 2026

Uh oh!

azure-pipelines Bot commented Feb 24, 2026

Uh oh!

mssonicbld commented Feb 25, 2026

Uh oh!

azure-pipelines Bot commented Feb 25, 2026

Uh oh!

mssonicbld commented Feb 26, 2026

Uh oh!

azure-pipelines Bot commented Feb 26, 2026

Uh oh!

rustiqly commented Feb 27, 2026

Uh oh!

mssonicbld commented Feb 27, 2026

Uh oh!

azure-pipelines Bot commented Feb 27, 2026

Uh oh!

yxieca commented Feb 28, 2026

Uh oh!

rustiqly commented Feb 28, 2026

Uh oh!

yxieca commented Feb 28, 2026

Uh oh!

yxieca commented Feb 28, 2026

Uh oh!

yxieca commented Feb 28, 2026

Uh oh!

rustiqly commented Mar 1, 2026

Uh oh!

yxieca commented Mar 1, 2026

Uh oh!

yxieca commented Mar 1, 2026

Uh oh!

yxieca commented Mar 1, 2026

Uh oh!

yxieca commented Mar 1, 2026

Uh oh!

yxieca commented Mar 1, 2026

Uh oh!

yxieca left a comment

Choose a reason for hiding this comment

Uh oh!