Project

General

Profile

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]]

Directory Structure

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>

Package Configuration

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

Package Makefile

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))

Dependencies

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
  • scp
  • svn
  • cvs
  • git
  • local
  • file

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).

Patching

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 -

<packagename>-<filename>.patch

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.

Configuring

Building

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.

Installation

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))