1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc: 3 4[[adding-board-support]] 5== Adding support for a particular board 6 7Buildroot contains basic configurations for several publicly available 8hardware boards, so that users of such a board can easily build a system 9that is known to work. You are welcome to add support for other boards 10to Buildroot too. 11 12To do so, you need to create a normal Buildroot configuration that 13builds a basic system for the hardware: (internal) toolchain, kernel, 14bootloader, filesystem and a simple BusyBox-only userspace. No specific 15package should be selected: the configuration should be as minimal as 16possible, and should only build a working basic BusyBox system for the 17target platform. You can of course use more complicated configurations 18for your internal projects, but the Buildroot project will only 19integrate basic board configurations. This is because package 20selections are highly application-specific. 21 22Once you have a known working configuration, run +make 23savedefconfig+. This will generate a minimal +defconfig+ file at the 24root of the Buildroot source tree. Move this file into the +configs/+ 25directory, and rename it +<boardname>_defconfig+. If the configuration 26is a bit more complicated, it is nice to manually reformat it and 27separate it into sections, with a comment before each section. Typical 28sections are _Architecture_, _Toolchain options_ (typically just linux 29headers version), _Firmware_, _Bootloader_, _Kernel_, and _Filesystem_. 30 31Always use fixed versions or commit hashes for the different 32components, not the "latest" version. For example, set 33+BR2_LINUX_KERNEL_CUSTOM_VERSION=y+ and 34+BR2_LINUX_KERNEL_CUSTOM_VERSION_VALUE+ to the kernel version you tested 35with. 36 37It is recommended to use as much as possible upstream versions of the 38Linux kernel and bootloaders, and to use as much as possible default 39kernel and bootloader configurations. If they are incorrect for your 40board, or no default exists, we encourage you to send fixes to the 41corresponding upstream projects. 42 43However, in the mean time, you may want to store kernel or bootloader 44configuration or patches specific to your target platform. To do so, 45create a directory +board/<manufacturer>+ and a subdirectory 46+board/<manufacturer>/<boardname>+. You can then store your patches 47and configurations in these directories, and reference them from the main 48Buildroot configuration. Refer to xref:customize[] for more details. 49 50Before submitting patches for new boards it is recommended to test it by 51building it using latest gitlab-CI docker container. To do this use 52+utils/docker-run+ script and inside it issue these commands: 53 54-------------------- 55 $ make <boardname>_defconfig 56 $ make 57-------------------- 58 59By default, Buildroot developers use the official image hosted on the 60https://gitlab.com/buildroot.org/buildroot/container_registry/2395076[gitlab.com 61registry] and it should be convenient for most usage. If you still want 62to build your own docker image, you can base it off the official image 63as the +FROM+ directive of your own _Dockerfile_: 64 65---- 66FROM registry.gitlab.com/buildroot.org/buildroot/base:YYYYMMDD.HHMM 67RUN ... 68COPY ... 69---- 70 71The current version _YYYYMMDD.HHMM_ can be found in the +.gitlab-ci.yml+ 72file at the top of the Buildroot source tree; all past versions are 73listed in the aforementioned registry as well. 74