Buildroot Package How-to¶
This article tells you how integrate your software package (or other's software) into Buildroot by making a Buildroot package. When you make a Buildroot package for your software, a menu option appears in the Buildroot configuration tool ('make menuconfig') that allows the system builder to include it in the target image generated by 'make'.
A Buildroot package consists of configuration and Makefiles that tell Buildroot how to obtain, configure, build and install a software package for the target.
Detailed documentation for this process is covered in the developer's section of the Buildroot manual - [[https://buildroot.org/downloads/manual/manual.html#_developer_guide]]
Buildroot packages are stored in the packages/ directory. The package configuration gets it's own directory so you will see a directory for each Buildroot package. The packages are organized (somewhat) hierarchically. Packages for Fermi software are stored in packages/fermi/.
The directory for the 'acnetd' package looks like this -
[jdiamond@adlinux acnetd]$ pwd /home/jdiamond/workspace/ees-buildroot/package/fermi/acnetd [jdiamond@adlinux acnetd]$ ls -lh total 16K -rw-r--r--. 1 jdiamond bdmicrop 508 Apr 4 14:46 acnetd-Makefile.patch -rw-r--r--. 1 jdiamond bdmicrop 539 Apr 4 14:46 acnetd.mk -rw-r--r--. 1 jdiamond bdmicrop 344 Mar 26 09:12 acnetd.startscript -rw-r--r--. 1 jdiamond bdmicrop 63 Mar 26 09:12 Config.in
The two required files are Config.in and <package-name>.mk. These files provide information to buildroot about the package and how to build it. Also included in the acnetd package are a patch-file that is applied before the Buildroot starts to build acnetd and a startscipt that is included in the target image's /etc/init.d directory.
The first step to making a Buildroot package for your software is to checkout the ees-buildroot project and create a package directory -
[jdiamond@adlinux ees-buildroot]$ mkdir package/fermi/<package-name>
The Config.in file describes your package to the menuconfig utility. The file for your package should look like this -
config BR2_PACKAGE_<PACKAGE-NAME> bool "<package-name>" help A description of your package that is available with the 'help' function from within menuconfig
The Config.in file in the parent directory of your package configures the menu structure that your package appears in. You need to edit this file to add your package under the appropriate menu.
[jdiamond@adlinux procServ]$ nano ../Config.in
Add a line to the appropriate menu for your package's Config.in file:
menu "Controls Department / ACNET Libraries" source "package/fermi/acnetd/Config.in" source "package/fermi/erlutil/Config.in" source "package/fermi/erlacnet/Config.in" source "package/fermi/erlalarmhandler/Config.in" source "package/fermi/erlclock/Config.in" source "package/fermi/erldrf2/Config.in" source "package/fermi/erllookup/Config.in" source "package/fermi/erlsync/Config.in" source "package/fermi/erldbnews/Config.in" source "package/fermi/erldaq/Config.in" source "package/fermi/erlcdev/Config.in" source "package/fermi/erlfrontends/Config.in" source "package/fermi/erlstandarddev/Config.in" source "package/fermi/<package-name>/Config.in" endmenu
The <package-name>.mk file is used by Buildroot to download, configure, build and install (to staging and/or the target image) your software.
For software packages that use generic build tools, the file should look something like this -
<PACKAGE-NAME>_VERSION = v1.0 <PACKAGE-NAME>_SITE = ssh://p-<project-name>@cdcvs.fnal.gov/cvs/projects/<project-name> <PACKAGE-NAME>_SITE_METHOD = git <PACKAGE-NAME>_DEPENDENCIES = openssl define <PACKAGE-NAME>_BUILD_CMDS $(MAKE) THIS_ARCH="$(ARCH)" CC="$(TARGET_CC)" CXX="$(TARGET_CXX)" LD="$(TARGET_LD)" -C $(@D) prefix="$(STAGING_DIR)" endef define <PACKAGE-NAME>_INSTALL_TARGET_CMDS install -D -m 0755 $(@D)/acnetd $(TARGET_DIR)/usr/bin/acnetd install -D -m 0755 package/fermi/acnetd/acnetd.startscript $(TARGET_DIR)/etc/init.d/S80acnetd endef $(eval $(generic-package))
Buildroot will ensure that all of the dependent packages you list in <PACKAGE-NAME>_DEPENDENCIES are built before it attempts to build your package.
Downloading¶Buildroot will download the package for you using http, ftp, cvs, svn or git. The download method is configured via the <PACKAGE-NAME>_SITE_METHOD parameter. Valid methods include (see the package infrastructure section of the Buildroot documentation for complete list) -
- wget - http or ftp
The location of the software to download is provided to the <PACKAGE-NAME>_SITE parameter. The format varies depending on the method you use. Again, the package infrastructure section of the Buildroot documentation has a complete description. Shown in the above example is how to download from the cdcvs Git repository. For wget (http or ftp) the value is just the URL of the path to the tar-ball you want to retrieve (Buildroot will figure the filename as '<package-name>-<version>.tar.gz' unless you tell it otherwise).
Some software requires minor or not-so-minor modification to the source code before it can be built in the Buildroot environment. The preferred way to handle this situation is with patch files that are applied to the source after it has been downloaded and un-packed.
You can supply patch files in the package directory with a name of the form -
Buildroot will search for patches with this form right after un-packing the source for your package and apply them before the package is built.
Buildroot invokes the <PACKAGE-NAME>_BUILD_CMDS target to build the software. In this example, the target toolchain is passed to the make utility via the CC, CXX and LD parameters.
Buildroot invokes the <PACKAGE-NAME>_INSTALL_TARGET_CMDS target to install the software to the target image. Use the $(TARGET_DIR) variable to copy the files your software requires to be on the target to the appropriate directory in the target file system. The example above uses the 'install' command with the -D and -m options to create the necessary path (if it doesn't exist) and to set the permissions in one line.
Packages that support autotools¶
If your software package is based on autotools (most Linux/FOSS software is) then the <package-name>.mk file is much simpler as Buildroot already knows how to supply the cross-compile parameters to these packages -
<PACKAGE-NAME>_VERSION = 1.0 <PACKAGE-NAME>_SOURCE = <package-name>-$(<PACKAGE-NAME>_VERSION).tar.gz <PACKAGE-NAME>_SITE = https://<path-to-package-name> <PACKAGE-NAME>_SITE_METHOD = wget <PACKAGE-NAME>_INSTALL_STAGING = NO <PACKAGE-NAME>_INSTALL_TARGET = YES <PACKAGE-NAME>_DEPENDENCIES = $(eval $(autotools-package))