7b9524a79f
MarkDown linter "mdl" reports many warnings on README.md. Let them get fixed to ease its maintenance and readability. Signed-off-by: Guillaume Lambert <guillaume.lambert@orange.com>
381 lines
22 KiB
Markdown
381 lines
22 KiB
Markdown
*static analysis*:
|
|
|
|
[](https://lgtm.com/projects/g/Azure/sonic-buildimage/alerts/)
|
|
[](https://lgtm.com/projects/g/Azure/sonic-buildimage/context:python)
|
|
|
|
*master builds*:
|
|
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=146&branchName=master)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=138&branchName=master)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=143&branchName=master)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=140&branchName=master)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=148&branchName=master)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=139&branchName=master)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=141&branchName=master)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=149&branchName=master)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=142&branchName=master)
|
|
|
|
*202205 builds*:
|
|
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=146&branchName=202205)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=138&branchName=202205)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=143&branchName=202205)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=140&branchName=202205)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=148&branchName=202205)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=139&branchName=202205)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=141&branchName=202205)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=149&branchName=202205)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=142&branchName=202205)
|
|
|
|
*202111 builds*:
|
|
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=146&branchName=202111)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=138&branchName=202111)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=143&branchName=202111)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=140&branchName=202111)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=148&branchName=202111)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=139&branchName=202111)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=141&branchName=202111)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=149&branchName=202111)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=142&branchName=202111)
|
|
|
|
*202012 builds*:
|
|
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=146&branchName=202012)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=138&branchName=202012)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=143&branchName=202012)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=140&branchName=202012)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=148&branchName=202012)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=141&branchName=202012)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=139&branchName=202012)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=149&branchName=202012)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=142&branchName=202012)
|
|
|
|
*201911 builds*:
|
|
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=146&branchName=201911)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=138&branchName=201911)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=148&branchName=201911)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=139&branchName=201911)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=149&branchName=201911)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=142&branchName=201911)
|
|
|
|
*201811 builds*:
|
|
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=138&branchName=201811)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=139&branchName=201811)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=148&branchName=201811)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=149&branchName=201811)
|
|
[](https://dev.azure.com/mssonic/build/_build/latest?definitionId=142&branchName=201811)
|
|
|
|
# sonic-buildimage
|
|
|
|
## Build SONiC Switch Images
|
|
|
|
# Description
|
|
|
|
Following are the instructions on how to build an [(ONIE)](https://github.com/opencomputeproject/onie)
|
|
compatible network operating system (NOS) installer image for network switches,
|
|
and also how to build docker images running inside the NOS.
|
|
Note that SONiC images are build per ASIC platform.
|
|
Switches using the same ASIC platform share a common image.
|
|
For a list of supported switches and ASIC, please refer to this [list](https://github.com/sonic-net/SONiC/wiki/Supported-Devices-and-Platforms)
|
|
|
|
# Hardware
|
|
|
|
Any server can be a build image server as long as it has:
|
|
|
|
* Multiple cores to increase build speed
|
|
* Plenty of RAM (less than 8 GiB is likely to cause issues)
|
|
* 300G of free disk space
|
|
* KVM Virtualization Support.
|
|
|
|
> Note: If you are in a VM, make sure you have support for nested virtualization.
|
|
> Some cases (e.g. building OVS image) also requires extra configuration
|
|
> options to expose the full KVM interface to the VM
|
|
> (e.g. [the KVM paravirtualization support on VirtualBox](https://www.virtualbox.org/manual/ch10.html#gimproviders)).
|
|
|
|
A good choice of OS for building SONiC is currently Ubuntu 20.04.
|
|
|
|
## Prerequisites
|
|
|
|
* Install pip and jinja in host build machine, execute below commands
|
|
if j2/j2cli is not available:
|
|
|
|
```shell
|
|
sudo apt install -y python3-pip
|
|
pip3 install --user j2cli
|
|
```
|
|
|
|
* Install [Docker](https://docs.docker.com/engine/install/) and configure your
|
|
system to allow running the 'docker' command without 'sudo':
|
|
* Add current user to the docker group: `sudo gpasswd -a ${USER} docker`
|
|
* Log out and log back in so that your group membership is re-evaluated
|
|
|
|
> Note: If a previous installation of Docker using snap was present on the
|
|
> system, remove it and also remove docker from snap before reinstallating docker.
|
|
> This will avoid [known bugs that falsely report read-only filesystems issues](https://stackoverflow.com/questions/52526219/docker-mkdir-read-only-file-system)
|
|
> during the build process.
|
|
|
|
## Clone the repository with all the git submodules
|
|
|
|
To clone the code repository recursively:
|
|
|
|
```shell
|
|
git clone --recurse-submodules https://github.com/sonic-net/sonic-buildimage.git
|
|
```
|
|
|
|
## Usage
|
|
|
|
To build SONiC installer image and docker images, run the following commands:
|
|
|
|
```shell
|
|
# Ensure the 'overlay' module is loaded on your development system
|
|
sudo modprobe overlay
|
|
|
|
# Enter the source directory
|
|
cd sonic-buildimage
|
|
|
|
# (Optional) Checkout a specific branch. By default, it uses master branch.
|
|
# For example, to checkout the branch 201911, use "git checkout 201911"
|
|
git checkout [branch_name]
|
|
|
|
# Execute make init once after cloning the repo,
|
|
# or after fetching remote repo with submodule updates
|
|
make init
|
|
|
|
# Execute make configure once to configure ASIC
|
|
make configure PLATFORM=[ASIC_VENDOR]
|
|
|
|
# Build SONiC image with 4 jobs in parallel.
|
|
# Note: You can set this higher, but 4 is a good number for most cases
|
|
# and is well-tested.
|
|
make SONIC_BUILD_JOBS=4 all
|
|
```
|
|
|
|
The supported ASIC vendors are:
|
|
|
|
* PLATFORM=barefoot
|
|
* PLATFORM=broadcom
|
|
* PLATFORM=marvell
|
|
* PLATFORM=mellanox
|
|
* PLATFORM=cavium
|
|
* PLATFORM=centec
|
|
* PLATFORM=nephos
|
|
* PLATFORM=innovium
|
|
* PLATFORM=vs
|
|
|
|
## Usage for ARM Architecture
|
|
|
|
ARM build has dependency in docker version 18.
|
|
If docker version is 19, downgrade to 18 with:
|
|
|
|
```shell
|
|
sudo apt-get install --allow-downgrades -y docker-ce=5:18.09.0~3-0~ubuntu-xenial
|
|
sudo apt-get install --allow-downgrades -y docker-ce-cli=5:18.09.0~3-0~ubuntu-xenial
|
|
```
|
|
|
|
To build Arm32 bit for (ARMHF) platform
|
|
|
|
```shell
|
|
# Execute make configure once to configure ASIC and ARCH
|
|
make configure PLATFORM=[ASIC_VENDOR] PLATFORM_ARCH=armhf
|
|
make target/sonic-[ASIC_VENDER]-armhf.bin
|
|
```
|
|
|
|
_example:_
|
|
|
|
```shell
|
|
make configure PLATFORM=marvell-armhf PLATFORM_ARCH=armhf
|
|
make target/sonic-marvell-armhf.bin
|
|
```
|
|
|
|
To build Arm32 bit for (ARMHF) Marvell platform on amd64 host for debian buster
|
|
using cross-compilation, run the following commands:
|
|
|
|
```shell
|
|
# Execute make configure once to configure ASIC and ARCH for cross-compilation build
|
|
|
|
NOJESSIE=1 NOSTRETCH=1 BLDENV=buster CROSS_BLDENV=1 \
|
|
make configure PLATFORM=marvell-armhf PLATFORM_ARCH=armhf
|
|
|
|
# Execute Arm32 build using cross-compilation environment
|
|
|
|
NOJESSIE=1 NOSTRETCH=1 BLDENV=buster CROSS_BLDENV=1 make target/sonic-marvell-armhf.bin
|
|
```
|
|
|
|
Running the above Arm32 build using cross-compilation instead of qemu emulator
|
|
drastically reduces the build time.
|
|
|
|
To build Arm64 bit for platform
|
|
|
|
```shell
|
|
# Execute make configure once to configure ASIC and ARCH
|
|
|
|
make configure PLATFORM=[ASIC_VENDOR] PLATFORM_ARCH=arm64
|
|
|
|
# example:
|
|
|
|
make configure PLATFORM=marvell-arm64 PLATFORM_ARCH=arm64
|
|
```
|
|
|
|
**NOTE**:
|
|
|
|
* Recommend reserving at least 100G free space to build one platform
|
|
with a single job.
|
|
The build process will use more disk if you are setting `SONIC_BUILD_JOBS`
|
|
to more than 1.
|
|
* If Docker's workspace folder, `/var/lib/docker`,
|
|
resides on a partition without sufficient free space,
|
|
you may encounter an error like the following during a Docker container build job:
|
|
|
|
`/usr/bin/tar: /path/to/sonic-buildimage/<some_file>:
|
|
Cannot write: No space left on device`
|
|
|
|
The solution is to [move the directory](https://linuxconfig.org/how-to-move-docker-s-default-var-lib-docker-to-another-directory-on-ubuntu-debian-linux)
|
|
to a partition with more free space.
|
|
* Use
|
|
`http_proxy=[your_proxy] https_proxy=[your_proxy] no_proxy=[your_no_proxy] make`
|
|
to enable http(s) proxy in the build process.
|
|
* Add your user account to `docker` group and use your user account to make.
|
|
`root` or `sudo` are not supported.
|
|
|
|
The SONiC installer contains all docker images needed.
|
|
SONiC uses one image for all devices of a same ASIC vendor.
|
|
|
|
For Broadcom ASIC, we build ONIE and EOS image.
|
|
EOS image is used for Arista devices,
|
|
ONIE image is used for all other Broadcom ASIC based devices.
|
|
|
|
```shell
|
|
make configure PLATFORM=broadcom
|
|
# build debian stretch required targets
|
|
BLDENV=stretch make stretch
|
|
# build ONIE image
|
|
make target/sonic-broadcom.bin
|
|
# build EOS image
|
|
make target/sonic-aboot-broadcom.swi
|
|
```
|
|
|
|
You may find the rules/config file useful.
|
|
It contains configuration options for the build process,
|
|
like adding more verbosity or showing dependencies,
|
|
username and password for base image etc.
|
|
|
|
Every docker image is built and saved to target/ directory.
|
|
So, for instance, to build only docker-database, execute:
|
|
|
|
```shell
|
|
make target/docker-database.gz
|
|
```
|
|
|
|
Same goes for debian packages, which are under target/debs/:
|
|
|
|
```shell
|
|
make target/debs/swss_1.0.0_amd64.deb
|
|
```
|
|
|
|
Every target has a clean target, so in order to clean swss, execute:
|
|
|
|
```shell
|
|
make target/debs/swss_1.0.0_amd64.deb-clean
|
|
```
|
|
|
|
It is recommended to use clean targets to clean all packages that are built together,
|
|
like dev packages for instance.
|
|
In order to be more familiar with build process and make some changes to it,
|
|
it is recommended to read this short [Documentation](README.buildsystem.md).
|
|
|
|
## Build debug dockers and debug SONiC installer image
|
|
|
|
SONiC build system supports building dockers and ONIE-image with debug tools
|
|
and debug symbols, to help with live & core debugging.
|
|
For details refer to [SONiC Buildimage Guide](https://github.com/sonic-net/sonic-buildimage/blob/master/README.buildsystem.md).
|
|
|
|
## SAI Version
|
|
|
|
Please refer to [SONiC roadmap](https://github.com/sonic-net/SONiC/wiki/Sonic-Roadmap-Planning)
|
|
on the SAI version for each SONiC release.
|
|
|
|
## Notes
|
|
|
|
* If you are running make for the first time, a sonic-slave-${USER} docker image
|
|
will be built automatically.
|
|
This may take a while, but it is a one-time action, so please be patient.
|
|
* The root user account is disabled. However, the created user can `sudo`.
|
|
* The target directory is `./target`, containing the NOS installer image
|
|
and docker images.
|
|
* sonic-generic.bin: SONiC switch installer image (ONIE compatible)
|
|
* sonic-aboot.bin: SONiC switch installer image (Aboot compatible)
|
|
* docker-base.gz: base docker image where other docker images are built from,
|
|
only used in build process (gzip tar archive)
|
|
* docker-database.gz: docker image for in-memory key-value store,
|
|
used as inter-process communication (gzip tar archive)
|
|
* docker-fpm.gz: docker image for quagga with fpm module enabled
|
|
(gzip tar archive)
|
|
* docker-orchagent.gz: docker image for SWitch State Service (SWSS)
|
|
(gzip tar archive)
|
|
* docker-syncd-brcm.gz: docker image for the daemon to sync database
|
|
and Broadcom switch ASIC (gzip tar archive)
|
|
* docker-syncd-cavm.gz: docker image for the daemon to sync database
|
|
and Cavium switch ASIC (gzip tar archive)
|
|
* docker-syncd-mlnx.gz: docker image for the daemon to sync database
|
|
and Mellanox switch ASIC (gzip tar archive)
|
|
* docker-syncd-nephos.gz: docker image for the daemon to sync database
|
|
and Nephos switch ASIC (gzip tar archive)
|
|
* docker-syncd-invm.gz: docker image for the daemon to sync database
|
|
and Innovium switch ASIC (gzip tar archive)
|
|
* docker-sonic-p4.gz: docker image for all-in-one for p4 software switch
|
|
(gzip tar archive)
|
|
* docker-sonic-vs.gz: docker image for all-in-one for software virtual switch
|
|
(gzip tar archive)
|
|
* docker-sonic-mgmt.gz: docker image for
|
|
[managing, configuring and monitoring SONiC](https://github.com/sonic-net/sonic-mgmt)
|
|
(gzip tar archive)
|
|
|
|
## Contribution Guide
|
|
|
|
All contributors must sign a contribution license agreement before contributions
|
|
can be accepted.
|
|
Visit [EasyCLA - Linux Foundation](https://easycla.lfx.linuxfoundation.org).
|
|
|
|
## GitHub Workflow
|
|
|
|
We're following basic GitHub Flow.
|
|
If you have no idea what we're talking about, check out [GitHub's official guide](https://guides.github.com/introduction/flow/).
|
|
Note that merge is only performed by the repository maintainer.
|
|
|
|
Guide for performing commits:
|
|
|
|
* Isolate each commit to one component/bugfix/issue/feature
|
|
* Use a standard commit message format:
|
|
|
|
> [component/folder touched]: Description intent of your changes
|
|
>
|
|
> [List of changes]
|
|
>
|
|
> Signed-off-by: Your Name your@email.com
|
|
|
|
For example:
|
|
|
|
> swss-common: Stabilize the ConsumerTable
|
|
>
|
|
> * Fixing autoreconf
|
|
> * Fixing unit-tests by adding checkers and initialize the DB before start
|
|
> * Adding the ability to select from multiple channels
|
|
> * Health-Monitor - The idea of the patch is that if something went wrong
|
|
> with the notification channel,
|
|
> we will have the option to know about it (Query the LLEN table length).
|
|
>
|
|
> Signed-off-by: user@dev.null
|
|
|
|
* Each developer should fork this repository and [add the team as a Contributor](https://help.github.com/articles/adding-collaborators-to-a-personal-repository)
|
|
* Push your changes to your private fork and do "pull-request" to this repository
|
|
* Use a pull request to do code review
|
|
* Use issues to keep track of what is going on
|
|
|
|
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
|
|
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
|
|
or contact [opencode@microsoft.com](mailto:opencode@microsoft.com)
|
|
with any additional questions or comments.
|