{"id":18459514,"url":"https://github.com/sonic-net/sonic-buildimage","last_synced_at":"2025-05-14T00:08:57.292Z","repository":{"id":37283638,"uuid":"53432472","full_name":"sonic-net/sonic-buildimage","owner":"sonic-net","description":"Scripts which perform an installable binary image build for SONiC","archived":false,"fork":false,"pushed_at":"2025-05-10T07:56:16.000Z","size":74934,"stargazers_count":803,"open_issues_count":2242,"forks_count":1540,"subscribers_count":127,"default_branch":"master","last_synced_at":"2025-05-10T08:32:06.930Z","etag":null,"topics":["hacktoberfest","sonic"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sonic-net.png","metadata":{"files":{"readme":"README.arm64_build_on_amd64.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-03-08T17:42:37.000Z","updated_at":"2025-05-10T07:56:21.000Z","dependencies_parsed_at":"2022-07-13T13:50:30.842Z","dependency_job_id":"e4400201-38e4-409e-b5e5-9e0d9e8ca580","html_url":"https://github.com/sonic-net/sonic-buildimage","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonic-net%2Fsonic-buildimage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonic-net%2Fsonic-buildimage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonic-net%2Fsonic-buildimage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonic-net%2Fsonic-buildimage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sonic-net","download_url":"https://codeload.github.com/sonic-net/sonic-buildimage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254044055,"owners_count":22005066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","sonic"],"created_at":"2024-11-06T08:23:26.546Z","updated_at":"2025-05-14T00:08:52.276Z","avatar_url":"https://github.com/sonic-net.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# SONiC Buildimage Guide\n## Overview\nSONiC buildimage is a *GNU make* based environment for build process automation.\nIt consists of two main parts:\n * Backend - collection of makefiles and other helpers that define generic target groups, used by recipes\n * Frontend - collection of recipes, that define metadata for each build target\n\n## Structure\nFile structure of SONiC Buildimage is as follows:  \n```\nsonic-buildimage/  \n  Makefile  \n  slave.mk  \n  sonic-slave/  \n    Dockerfile  \n  rules/  \n    config  \n    functions\n    recipe1.mk\n    ..\n  dockers/  \n    docker1/  \n      Dockerfile.template    \n    ..  \n  src/  \n    submodule1/    \n    ..  \n    package1/  \n      Makefile  \n    ..  \n  platform/  \n    vendor1/  \n    ..  \n  target/  \n    debs/  \n    python-wheels/  \n```\n### Backend  \n**Makefile**, **slave.mk** and **sonic-slave/Dockerfile** are the backend of buildimage.  \n*slave.mk* is the actual makefile. It defines a set of rules for *target groups* (more on that later).\nYou can find a make rule for every target that is defined in recipe there.  \n*Makefile* is a wrapper over sonic-slave docker image.  \n\nEvery part of build is executed in a docker container called sonic-slave, specifically crafted for this environment.\nIf build is started for the first time on a particular host, a new sonic-slave image will be built form *sonic-slave/Dockerfile* on the machine.\nIt might take some time, so be patient.\nAfter that all subsequent make commands will be executed inside this container.\n*Makefile* takes every target that is passed to make command and delegates it as an entry point to a container,\nmaking process of running container transparent.  \n  \n### Frontend  \n**rules/** has a collection of recipes for platform independent targets.\nEvery recipe is a file that describes a metadata of a specific target, that is needed for its build.  \nYou might find **rules/config** very useful, as it is a configuration file for a build system, which enables/disables some tweaks.  \n**dockers/** directory is a place where you can find Dockerfiles for generic docker images.  \n**src/** is a place where a source code for generic packages goes.\nIt has both submodules (simple case, just run dpkg-buildpackage to build),\nand directories with more complicated components, that provide their own Makefiles.\n**platform/** contains all vendor-specific recipes, submodules etc.  \nEvery **platform/[VENDOR]/** directory is a derived part of buildimage frontend, that defines rules and targets for a concrete vendor.  \n\n### Build output\n**target/** is basically a build output. You can find all build artifacts there.  \n\n## Recipes and target groups\nNow let's go over a definition of recipes and target groups.  \n**Recipe** is a small makefile that defines a target and set of variables for building it.\nIf you want to add a new target to buildimage (.deb package or docker image), you have to create a recipe for this target.  \n**Target group** is a set of targets that are built according to the same rules.\nEvery recipe sets a target group to which this target belongs.  \n\n### Recipe example\nLets take a recipe for swsscommon as an example:  \n```make\n# libswsscommon package\n\nLIBSWSSCOMMON = libswsscommon_1.0.0_amd64.deb\n$(LIBSWSSCOMMON)_SRC_PATH = $(SRC_PATH)/sonic-swss-common\n$(LIBSWSSCOMMON)_DEPENDS += $(LIBHIREDIS_DEV) $(LIBNL3_DEV) $(LIBNL_GENL3_DEV) \\\n                            $(LIBNL_ROUTE3_DEV) $(LIBNL_NF3_DEV) \\\n\t\t\t    $(LIBNL_CLI_DEV)\n$(LIBSWSSCOMMON)_RDEPENDS += $(LIBHIREDIS) $(LIBNL3) $(LIBNL_GENL3) \\\n                             $(LIBNL_ROUTE3) $(LIBNL_NF3) $(LIBNL_CLI)\nSONIC_DPKG_DEBS += $(LIBSWSSCOMMON)\n\nLIBSWSSCOMMON_DEV = libswsscommon-dev_1.0.0_amd64.deb\n$(eval $(call add_derived_package,$(LIBSWSSCOMMON),$(LIBSWSSCOMMON_DEV)))\n```\nFirst we define our package swsscommon.  \nThen we specify **SRC_PATH** (path to sources),\n**DEPENDS** (build dependencies),\nand **RDEPENDS** (runtime dependencies for docker installation).  \nThen we add our target to SONIC_DPKG_DEBS target group.  \nAt the end we define a dev package for swsscommon and make it derived from main one.\nUsing **add_derived_package** just makes a deep copy of package's metadata, so that we don't have to repeat ourselves.  \n\n### Target groups\n**SONIC_DPKG_DEBS**  \nMain target group for building .deb packages.\nDefine:  \n```make\nSOME_NEW_DEB = some_new_deb.deb # name of your package\n$(SOME_NEW_DEB)_SRC_PATH = $(SRC_PATH)/project_name # path to directory with sources\n$(SOME_NEW_DEB)_DEPENDS = $(SOME_OTHER_DEB1) $(SOME_OTHER_DEB2) ... # build dependencies\n$(SOME_NEW_DEB)_RDEPENDS = $(SOME_OTHER_DEB1) $(SOME_OTHER_DEB2) ... # runtime dependencies\nSONIC_DPKG_DEBS += $(SOME_NEW_DEB) # add package to this target group\n```\n\n**SONIC_PYTHON_STDEB_DEBS**  \nSame as above, but instead of building package using dpkg-buildpackage it executes `python setup.py --command-packages=stdeb.command bdist_deb`.\nDefine:  \n```make\nSOME_NEW_DEB = some_new_deb.deb # name of your package\n$(SOME_NEW_DEB)_SRC_PATH = $(SRC_PATH)/project_name # path to directory with sources\n$(SOME_NEW_DEB)_DEPENDS = $(SOME_OTHER_DEB1) $(SOME_OTHER_DEB2) ... # build dependencies\n$(SOME_NEW_DEB)_RDEPENDS = $(SOME_OTHER_DEB1) $(SOME_OTHER_DEB2) ... # runtime dependencies\nSONIC_PYTHON_STDEB_DEBS += $(SOME_NEW_DEB) # add package to this target group\n```\n\n**SONIC_MAKE_DEBS**  \nThis is a bit more flexible case.\nIf you have to do some specific type of build or apply paths prior to build, just define your own Makefile and add it to buildimage.\nDefine:\n```make\nSOME_NEW_DEB = some_new_deb.deb # name of your package\n$(SOME_NEW_DEB)_SRC_PATH = $(SRC_PATH)/project_name # path to directory with sources\n$(SOME_NEW_DEB)_DEPENDS = $(SOME_OTHER_DEB1) $(SOME_OTHER_DEB2) ... # build dependencies\n$(SOME_NEW_DEB)_RDEPENDS = $(SOME_OTHER_DEB1) $(SOME_OTHER_DEB2) ... # runtime dependencies\nSONIC_MAKE_DEBS += $(SOME_NEW_DEB) # add package to this target group\n```\n\nIf some packages have to be built locally due to some legal issues or they are already prebuilt and available online, you might find next four target groups useful.  \n\n**SONIC_COPY_DEBS**  \nThose packages will be just copied from specified location on your machine.\nDefine:  \n```make\nSOME_NEW_DEB = some_new_deb.deb # name of your package\n$(SOME_NEW_DEB)_PATH = path/to/some_new_deb.deb # path to file\nSONIC_COPY_DEBS += $(SOME_NEW_DEB) # add package to this target group\n```\n\n**SONIC_COPY_FILES**  \nSame as above, but applicable for regular files. Use when you need some regular files for installation in docker container.\nDefine:  \n```make\nSOME_NEW_FILE = some_new_file # name of your file\n$(SOME_NEW_FILE)_PATH = path/to/some_new_file # path to file\nSONIC_COPY_FILES += $(SOME_NEW_FILE) # add file to this target group\n```\n\n**SONIC_ONLINE_DEBS**  \nTarget group for debian packages that should be fetched from an online source.\nDefine:  \n```make\nSOME_NEW_DEB = some_new_deb.deb # name of your package\n$(SOME_NEW_DEB)_URL = https://url/to/this/deb.deb # path to file # URL for downloading\nSONIC_ONLINE_DEBS += $(SOME_NEW_DEB) # add file to this target group\n```\n\n**SONIC_ONLINE_FILES**  \nTarget group for regular files that should be fetched from an online source.\nDefine:  \n```make\nSOME_NEW_FILE = some_new_file # name of your file\n$(SOME_NEW_FILE)_URL = https://url/to/this/file # URL for downloading\nSONIC_ONLINE_FILES += $(SOME_NEW_FILE) # add file to this target group\n```\n\nDocker images also have their target groups.  \n**SONIC_SIMPLE_DOCKER_IMAGES**  \nAs you see from a name of the group, it is intended to build a docker image from a regular Dockerfile.\nDefine:  \n```make\nSOME_DOCKER = some_docker.gz # name of your docker\n$(SOME_DOCKER)_PATH = path/to/your/docker # path to your Dockerfile\nSONIC_SIMPLE_DOCKER_IMAGES += $(SOME_DOCKER) # add docker to this group\n```\n\n**SONIC_DOCKER_IMAGES**  \nThis one is a bit more sophisticated. You can define debian packages from buildimage that will be installed to it, and corresponding Dockerfile will be dynamically generated from a template.\nDefine:  \n```make\nSOME_DOCKER = some_docker.gz # name of your docker\n$(SOME_DOCKER)_PATH = path/to/your/docker # path to your Dockerfile\n$(SOME_DOCKER)_DEPENDS += $(SOME_DEB1) $(SOME_DEB2) # .deb packages to install into image\n$(SOME_DOCKER)_PYTHON_WHEELS += $(SOME_WHL1) $(SOME_WHL2) # python wheels to install into image\n$(SOME_DOCKER)_LOAD_DOCKERS += $(SOME_OTHER_DOCkER) # docker image from which this one is built\nSONIC_DOCKER_IMAGES += $(SOME_DOCKER) # add docker to this group\n```\n\n## Tips \u0026 Tricks\nAlthough every target is built inside a sonic-slave container, which exits at the end of build, you can enter bash of sonic-slave using this command:\n```\n$ make sonic-slave-bash\n```\nIt is very useful for debugging when you add a new target and facing some troubles.\n\nsonic-slave environment is built only once, but if sonic-slave/Dockerfile was updated, you can rebuild it with this command:\n```\n$ make sonic-slave-build\n```\n\nOne can print out all available targets by executing the following command:\n```\n$ make list\n```\n\nAll target groups are used by one or another recipe, so use those recipes as a reference when adding new ones.\n\n## Build debug dockers and debug SONiC installer image:\nUsing 'INSTALL_DEBUG_TOOLS=y' builds the debug image.\n\nFor example:\n`INSTALL_DEBUG_TOOLS=y make target/sonic-broadcom.bin` \n\n* Builds debug docker images.\n* Debug images carry a suffix of \"-dbg\"\n    * e.g. target/docker-orchagent-dbg.gz\n* target/sonic-broadcom.bin is built using debug docker images\n    * Selective sources are archived and available under /src\n    * An empty /debug dir is created for use during debug session.\n    * All debug dockers are mounted with /src:ro and /debug:rw\n    * Login banner will briefly describe these features.\n  \n\n_Note: target/sonic-broadcom.bin name is the same irrespective of built using debug or non-debug dockers._\n\n_Recommend: Rename image built using INSTALL_DEBUG_TOOLS=y to mark it explicit. May be `mv target/sonic-broadcom.bin target/sonic-broadcom-dbg.bin`_\n\n### Debug dockers\n* Built with all available debug symbols.\n* Installed with many basic packages that would be required for debugging\n    * gdb\n    * gdbserver\n    * vim\n    * strace\n    * openssh-client\n    * sshpass\n* Loadable into any environment that supports docker\n* Outside SONiC image, you may run the docker with `--entrypoint=/bin/bash` \n* Use -v to map any of your host directories\n* To debug a core file in non-SONiC environment that supports docker\n    * `docker load -i docker-\u003cname\u003e-dbg.gz`\n    * copy your unzipped core file into ~/debug\n    * `docker run -it --entrypoint=/bin/bash -v ~/debug:/debug \u003cimage id\u003e`\n    * `gdb /usr/bin/\u003cyour binary\u003e -c /debug/\u003cyour core\u003e`\n    \n### Debug SONiC image\n\n* Install this image into the switch that supports this image.\n\t* For platform independent binary, you may use a debug image for virtual switch\n* Open the archive in /src, if you would need source code for debugging\n* Every debug enabled docker is mounted with /src as read-only\n* The host has /debug dir and it is mapped into every debuggable docker as /debug with read-write permission.\n* To debug a core\n    * Copy core into /debug of host and unzip it\n        * Feel free to create \u0026 use sub-dirs as needed.\n        * Entire /debug is mounted inside docker\n    * Get into the docker (`docker -it exec \u003cname\u003e bash`)\n    * `gdb /usr/bin/\u003cbinary\u003e -c /debug/\u003ccore file path\u003e`\n    * Use set-directory in gdb to map appropriate source dir from under /src\n    * You may set gdb logs to go into /debug\n* For live debugging\n    * Use this as a regular switch\n    * Get into docker, and you may\n        * start process under dbg\n        * attach gdb to running process\n    * Set required source dir from under /src as needed\n    * May use /debug to record all geb logs or any spew from debug session.\n    \n  ### To enhance debug dockers\n  * Add to `\u003cdocker name\u003e_DBG_IMAGE_PACKAGES`, additional debug tools that will be pre-installed during build.\n\t* e.g. `$(DOCKER_ORCHAGENT)_DBG_IMAGE_PACKAGES += perl`\n\t* Build will install these tools using \"apt\"\n  * Add to `\u003cdocker name\u003e_DBG_DEPENDS`, additional debug .deb packages that will be pre-installed during build.\n\t* e.g. `$(DOCKER_ORCHAGENT)_DBG_DEPENDS +=  $(SWSS_DBG) $(LIBSWSSCOMMON_DBG) $(LIBSAIREDIS_DBG)`\n  * Add to `DBG_SRC_ARCHIVE`, the source dirs to archive\n\t* The source files (.c, .cpp, .h \u0026 .hpp) under this dir tree are archived.\n\t* e.g. rules/swss.mk has `DBG_SRC_ARCHIVE += swss`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonic-net%2Fsonic-buildimage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsonic-net%2Fsonic-buildimage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonic-net%2Fsonic-buildimage/lists"}