// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
-Infrastructure for packages with specific build systems
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Infrastructure for packages with specific build systems
By 'packages with specific build systems' we mean all the packages
whose build system is not one of the standard ones, such as
[[generic-package-tutorial]]
-+generic-package+ Tutorial
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+==== +generic-package+ tutorial
------------------------------
01: ################################################################################
07: LIBFOO_VERSION = 1.0
08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
09: LIBFOO_SITE = http://www.foosoftware.org/download
-10: LIBFOO_LICENSE = GPLv3+
+10: LIBFOO_LICENSE = GPL-3.0+
11: LIBFOO_LICENSE_FILES = COPYING
12: LIBFOO_INSTALL_STAGING = YES
13: LIBFOO_CONFIG_SCRIPTS = libfoo-config
14: LIBFOO_DEPENDENCIES = host-libaaa libbbb
15:
16: define LIBFOO_BUILD_CMDS
-17: $(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D) all
+17: $(MAKE) $(TARGET_CONFIGURE_OPTS) -C $(@D) all
18: endef
19:
20: define LIBFOO_INSTALL_STAGING_CMDS
28: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
29: endef
30:
-31: define LIBFOO_DEVICES
-32: /dev/foo c 666 0 0 42 0 - - -
+31: define LIBFOO_USERS
+32: foo -1 libfoo -1 * - - - LibFoo daemon
33: endef
34:
-35: define LIBFOO_PERMISSIONS
-36: /bin/foo f 4755 0 0 - - - - -
+35: define LIBFOO_DEVICES
+36: /dev/foo c 666 0 0 42 0 - - -
37: endef
38:
-39: define LIBFOO_USERS
-40: foo -1 libfoo -1 * - - - LibFoo daemon
+39: define LIBFOO_PERMISSIONS
+40: /bin/foo f 4755 foo libfoo - - - - -
41: endef
42:
43: $(eval $(generic-package))
contains the directory where the source code of the package has been
extracted.
-On line 31..33, we define a device-node file used by this package
+On lines 31..43, we define a user that is used by this package (e.g.
+to run a daemon as non-root) (+LIBFOO_USERS+).
+
+On line 35..37, we define a device-node file used by this package
(+LIBFOO_DEVICES+).
-On line 35..37, we define the permissions to set to specific files
+On line 39..41, we define the permissions to set to specific files
installed by this package (+LIBFOO_PERMISSIONS+).
-On lines 39..41, we define a user that is used by this package (eg.
-to run a daemon as non-root) (+LIBFOO_USERS+).
-
Finally, on line 43, we call the +generic-package+ function, which
generates, according to the variables defined previously, all the
Makefile code necessary to make your package working.
[[generic-package-reference]]
-+generic-package+ Reference
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+==== +generic-package+ reference
There are two variants of the generic target. The +generic-package+ macro is
-used for packages to be cross-compiled for the target. The
+used for packages to be cross-compiled for the target. The
+host-generic-package+ macro is used for host packages, natively compiled
-for the host. It is possible to call both of them in a single +.mk+
+for the host. It is possible to call both of them in a single +.mk+
file: once to create the rules to generate a target
package and once to create the rules to generate a host package:
variables of other packages, if they depend on +libfoo+ or
+host-libfoo+.
-The call to the +generic-package+ and/or +host-generic-package+ macro *must* be
-at the end of the +.mk+ file, after all variable definitions.
+The call to the +generic-package+ and/or +host-generic-package+ macro
+*must* be at the end of the +.mk+ file, after all variable definitions.
+The call to +host-generic-package+ *must* be after the call to
++generic-package+, if any.
For the target package, the +generic-package+ uses the variables defined by
the .mk file and prefixed by the uppercased package name:
* +LIBFOO_VERSION+, mandatory, must contain the version of the
package. Note that if +HOST_LIBFOO_VERSION+ doesn't exist, it is
assumed to be the same as +LIBFOO_VERSION+. It can also be a
- revision number, branch or tag for packages that are fetched
- directly from their revision control system. +
- Examples: +
- +LIBFOO_VERSION = 0.1.2+ +
- +LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057+ +
- +LIBFOO_VERSION = stable+
-
-* +LIBFOO_SOURCE+ may contain the name of the tarball of
- the package. If +HOST_LIBFOO_SOURCE+ is not specified, it
- defaults to +LIBFOO_SOURCE+. If none are specified, then
- the value is assumed to be
- +packagename-$(LIBFOO_VERSION).tar.gz+. +
+ revision number or a tag for packages that are fetched directly
+ from their version control system. Do not use a branch name as
+ version; it does not work. Examples:
+ ** a version for a release tarball: +LIBFOO_VERSION = 0.1.2+
+ ** a sha1 for a git tree: +LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057+
+ ** a tag for a git tree +LIBFOO_VERSION = v0.1.2+
+
+* +LIBFOO_SOURCE+ may contain the name of the tarball of the package,
+ which Buildroot will use to download the tarball from
+ +LIBFOO_SITE+. If +HOST_LIBFOO_SOURCE+ is not specified, it defaults
+ to +LIBFOO_SOURCE+. If none are specified, then the value is assumed
+ to be +libfoo-$(LIBFOO_VERSION).tar.gz+. +
Example: +LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2+
* +LIBFOO_PATCH+ may contain a space-separated list of patch file
- names, that will be downloaded from the same location as the tarball
- indicated in +LIBFOO_SOURCE+, and then applied to the package source
- code. If +HOST_LIBFOO_PATCH+ is not specified, it defaults to
- +LIBFOO_PATCH+. Note that patches that are included in Buildroot
+ names, that Buildroot will download and apply to the package source
+ code. If an entry contains +://+, then Buildroot will assume it is a
+ full URL and download the patch from this location. Otherwise,
+ Buildroot will assume that the patch should be downloaded from
+ +LIBFOO_SITE+. If +HOST_LIBFOO_PATCH+ is not specified, it defaults
+ to +LIBFOO_PATCH+. Note that patches that are included in Buildroot
itself use a different mechanism: all files of the form
- +<packagename>-*.patch+ present in the package directory inside
+ +*.patch+ present in the package directory inside
Buildroot will be applied to the package after extraction (see
xref:patch-policy[patching a package]). Finally, patches listed in
the +LIBFOO_PATCH+ variable are applied _before_ the patches stored
* +LIBFOO_SITE+ provides the location of the package, which can be a
URL or a local filesystem path. HTTP, FTP and SCP are supported URL
- types for retrieving package tarballs. Git, Subversion, Mercurial,
+ types for retrieving package tarballs. In these cases don't include a
+ trailing slash: it will be added by Buildroot between the directory
+ and the filename as appropriate. Git, Subversion, Mercurial,
and Bazaar are supported URL types for retrieving packages directly
- from source code management systems. A filesystem path may be used
+ from source code management systems. There is a helper function to make
+ it easier to download source tarballs from GitHub (refer to
+ xref:github-download-url[] for details). A filesystem path may be used
to specify either a tarball or a directory containing the package
source code. See +LIBFOO_SITE_METHOD+ below for more details on how
retrieval works. +
+LIBFOO_SITE+.
Examples: +
+LIBFOO_SITE=http://www.libfoosoftware.org/libfoo+ +
- +LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor/+ +
- +LIBFOO_SITE=git://github.com/kergoth/tslib.git+ +
+ +LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor+ +
+LIBFOO_SITE=/opt/software/libfoo.tar.gz+ +
- +LIBFOO_SITE=$(TOPDIR)/../src/libfoo/+
-
-* +LIBFOO_EXTRA_DOWNLOADS+ lists a number of additional files that
- Buildroot should download from +LIBFOO_SITE+ in addition to the main
- +LIBFOO_SOURCE+ (which usually is a tarball). Buildroot will not do
- anything with those additional files, except download files: it will
- be up to the package recipe to use them from +$(DL_DIR)+.
+ +LIBFOO_SITE=$(TOPDIR)/../src/libfoo+
+
+* +LIBFOO_DL_OPTS+ is a space-separated list of additional options to
+ pass to the downloader. Useful for retrieving documents with
+ server-side checking for user logins and passwords, or to use a proxy.
+ All download methods valid for +LIBFOO_SITE_METHOD+ are supported;
+ valid options depend on the download method (consult the man page
+ for the respective download utilities).
+
+* +LIBFOO_EXTRA_DOWNLOADS+ is a space-separated list of additional
+ files that Buildroot should download. If an entry contains +://+
+ then Buildroot will assume it is a complete URL and will download
+ the file using this URL. Otherwise, Buildroot will assume the file
+ to be downloaded is located at +LIBFOO_SITE+. Buildroot will not do
+ anything with those additional files, except download them: it will
+ be up to the package recipe to use them from +$(LIBFOO_DL_DIR)+.
* +LIBFOO_SITE_METHOD+ determines the method used to fetch or copy the
package source code. In many cases, Buildroot guesses the method
is unnecessary. When +HOST_LIBFOO_SITE_METHOD+ is not specified, it
defaults to the value of +LIBFOO_SITE_METHOD+. +
The possible values of +LIBFOO_SITE_METHOD+ are:
- ** +wget+ for normal FTP/HTTP downloads of tarballs. Used by
+ ** +wget+ for normal FTP/HTTP downloads of tarballs. Used by
default when +LIBFOO_SITE+ begins with +http://+, +https://+ or
+ftp://+.
- ** +scp+ for downloads of tarballs over SSH with scp. Used by
+ ** +scp+ for downloads of tarballs over SSH with scp. Used by
default when +LIBFOO_SITE+ begins with +scp://+.
** +svn+ for retrieving source code from a Subversion repository.
- Used by default when +LIBFOO_SITE+ begins with +svn://+. When a
+ Used by default when +LIBFOO_SITE+ begins with +svn://+. When a
+http://+ Subversion repository URL is specified in
+LIBFOO_SITE+, one 'must' specify +LIBFOO_SITE_METHOD=svn+.
Buildroot performs a checkout which is preserved as a tarball in
** +cvs+ for retrieving source code from a CVS repository.
Used by default when +LIBFOO_SITE+ begins with +cvs://+.
The downloaded source code is cached as with the +svn+ method.
- Only anonymous pserver mode is supported.
+ Anonymous pserver mode is assumed otherwise explicitly defined
+ on +LIBFOO_SITE+. Both
+ +LIBFOO_SITE=cvs://libfoo.net:/cvsroot/libfoo+ and
+ +LIBFOO_SITE=cvs://:ext:libfoo.net:/cvsroot/libfoo+
+ are accepted, on the former anonymous pserver access mode is
+ assumed.
+LIBFOO_SITE+ 'must' contain the source URL as well as the remote
repository directory. The module is the package name.
- +LIBFOO_VERSION+ is 'mandatory' and 'must' be a timestamp.
- ** +git+ for retrieving source code from a Git repository. Used by
+ +LIBFOO_VERSION+ is 'mandatory' and 'must' be a tag, a branch, or
+ a date (e.g. "2014-10-20", "2014-10-20 13:45", "2014-10-20
+ 13:45+01" see "man cvs" for further details).
+ ** +git+ for retrieving source code from a Git repository. Used by
default when +LIBFOO_SITE+ begins with +git://+. The downloaded
source code is cached as with the +svn+
method.
** +bzr+ for retrieving source code from a Bazaar repository. Used
by default when +LIBFOO_SITE+ begins with +bzr://+. The
downloaded source code is cached as with the +svn+ method.
- ** +file+ for a local tarball. One should use this when
+ ** +file+ for a local tarball. One should use this when
+LIBFOO_SITE+ specifies a package tarball as a local filename.
Useful for software that isn't available publicly or in version
control.
- ** +local+ for a local source code directory. One should use this
+ ** +local+ for a local source code directory. One should use this
when +LIBFOO_SITE+ specifies a local directory path containing
- the package source code. Buildroot copies the contents of the
- source directory into the package's build directory.
+ the package source code. Buildroot copies the contents of the
+ source directory into the package's build directory. Note that
+ for +local+ packages, no patches are applied. If you need to
+ still patch the source code, use +LIBFOO_POST_RSYNC_HOOKS+, see
+ xref:hooks-rsync[].
+
+* +LIBFOO_GIT_SUBMODULES+ can be set to +YES+ to create an archive
+ with the git submodules in the repository. This is only available
+ for packages downloaded with git (i.e. when
+ +LIBFOO_SITE_METHOD=git+). Note that we try not to use such git
+ submodules when they contain bundled libraries, in which case we
+ prefer to use those libraries from their own package.
+
+* +LIBFOO_STRIP_COMPONENTS+ is the number of leading components
+ (directories) that tar must strip from file names on extraction.
+ The tarball for most packages has one leading component named
+ "<pkg-name>-<pkg-version>", thus Buildroot passes
+ --strip-components=1 to tar to remove it.
+ For non-standard packages that don't have this component, or
+ that have more than one leading component to strip, set this
+ variable with the value to be passed to tar. Default: 1.
+
+* +LIBFOO_EXCLUDES+ is a space-separated list of patterns to exclude
+ when extracting the archive. Each item from that list is passed as
+ a tar's +--exclude+ option. By default, empty.
* +LIBFOO_DEPENDENCIES+ lists the dependencies (in terms of package
name) that are required for the current target package to
a similar way, +HOST_LIBFOO_DEPENDENCIES+ lists the dependencies for
the current host package.
+* +LIBFOO_EXTRACT_DEPENDENCIES+ lists the dependencies (in terms of
+ package name) that are required for the current target package to be
+ extracted. These dependencies are guaranteed to be compiled and
+ installed before the extract step of the current package
+ starts. This is only used internally by the package infrastructure,
+ and should typically not be used directly by packages.
+
+* +LIBFOO_PATCH_DEPENDENCIES+ lists the dependencies (in terms of
+ package name) that are required for the current package to be
+ patched. These dependencies are guaranteed to be extracted and
+ patched before the current package is patched. In a similar way,
+ +HOST_LIBFOO_PATCH_DEPENDENCIES+ lists the dependencies for the
+ current host package.
+ This is seldom used; usually, +LIBFOO_DEPENDENCIES+ is what you
+ really want to use.
+
+* +LIBFOO_PROVIDES+ lists all the virtual packages +libfoo+ is an
+ implementation of. See xref:virtual-package-tutorial[].
+
* +LIBFOO_INSTALL_STAGING+ can be set to +YES+ or +NO+ (default). If
set to +YES+, then the commands in the +LIBFOO_INSTALL_STAGING_CMDS+
variables are executed to install the package into the staging
variables are executed to install the package into the target
directory.
+* +LIBFOO_INSTALL_IMAGES+ can be set to +YES+ or +NO+ (default). If
+ set to +YES+, then the commands in the +LIBFOO_INSTALL_IMAGES_CMDS+
+ variable are executed to install the package into the images
+ directory.
+
* +LIBFOO_CONFIG_SCRIPTS+ lists the names of the files in
'$(STAGING_DIR)/usr/bin' that need some special fixing to make them
cross-compiling friendly. Multiple file names separated by space can
This variable is optional.
* +LIBFOO_USERS+ lists the users to create for this package, if it installs
- a program you want to run as a specific user (eg. as a daemon, or as a
+ a program you want to run as a specific user (e.g. as a daemon, or as a
cron-job). The syntax is similar in spirit to the makedevs one, and is
described in the xref:makeuser-syntax[]. This variable is optional.
* +LIBFOO_LICENSE+ defines the license (or licenses) under which the package
is released.
This name will appear in the manifest file produced by +make legal-info+.
- If the license appears in xref:legal-info-list-licenses[the following list],
- use the same string to make the manifest file uniform.
+ If the license appears in https://spdx.org/licenses/[the SPDX License List],
+ use the SPDX short identifier to make the manifest file uniform.
Otherwise, describe the license in a precise and concise way, avoiding
ambiguous names such as +BSD+ which actually name a family of licenses.
This variable is optional. If it is not defined, +unknown+ will appear in
- the +license+ field of the manifest file for this package.
+ the +license+ field of the manifest file for this package. +
+ The expected format for this variable must comply with the following rules:
+ ** If different parts of the package are released under different
+ licenses, then +comma+ separate licenses (e.g. +`LIBFOO_LICENSE =
+ GPL-2.0+, LGPL-2.1+`+). If there is clear distinction between which
+ component is licensed under what license, then annotate the license
+ with that component, between parenthesis (e.g. +`LIBFOO_LICENSE =
+ GPL-2.0+ (programs), LGPL-2.1+ (libraries)`+).
+ ** If the package is dual licensed, then separate licenses with the
+ +or+ keyword (e.g. +`LIBFOO_LICENSE = AFL-2.1 or GPL-2.0+`+).
* +LIBFOO_LICENSE_FILES+ is a space-separated list of files in the package
tarball that contain the license(s) under which the package is released.
to let you know, and +not saved+ will appear in the +license files+ field
of the manifest file for this package.
+* +LIBFOO_ACTUAL_SOURCE_TARBALL+ only applies to packages whose
+ +LIBFOO_SITE+ / +LIBTOO_SOURCE+ pair points to an archive that does
+ not actually contain source code, but binary code. This a very
+ uncommon case, only known to apply to external toolchains which come
+ already compiled, although theoretically it might apply to other
+ packages. In such cases a separate tarball is usually available with
+ the actual source code. Set +LIBFOO_ACTUAL_SOURCE_TARBALL+ to the
+ name of the actual source code archive and Buildroot will download
+ it and use it when you run +make legal-info+ to collect
+ legally-relevant material. Note this file will not be downloaded
+ during regular builds nor by +make source+.
+
+* +LIBFOO_ACTUAL_SOURCE_SITE+ provides the location of the actual
+ source tarball. The default value is +LIBFOO_SITE+, so you don't
+ need to set this variable if the binary and source archives are
+ hosted on the same directory. If +LIBFOO_ACTUAL_SOURCE_TARBALL+ is
+ not set, it doesn't make sense to define
+ +LIBFOO_ACTUAL_SOURCE_SITE+.
+
* +LIBFOO_REDISTRIBUTE+ can be set to +YES+ (default) or +NO+ to indicate if
the package source code is allowed to be redistributed. Set it to +NO+ for
non-opensource packages: Buildroot will not save the source code for this
FLAT binary format is only 4k bytes. If the application consumes more stack,
append the required number here.
+* +LIBFOO_BIN_ARCH_EXCLUDE+ is a space-separated list of paths (relative
+ to the target directory) to ignore when checking that the package
+ installs correctly cross-compiled binaries. You seldom need to set this
+ variable, unless the package installs binary blobs outside the default
+ locations, `/lib/firmware`, `/usr/lib/firmware`, `/lib/modules`,
+ `/usr/lib/modules`, and `/usr/share`, which are automatically excluded.
+
The recommended way to define these variables is to use the following
syntax:
should be installed, since they might be needed to compile other
packages.
-* +LIBFOO_CLEAN_CMDS+, lists the actions to perform to clean up
- the build directory of the package.
+* +LIBFOO_INSTALL_IMAGES_CMDS+ lists the actions to be performed to
+ install the package to the images directory, when the package is a
+ target package. The package must install its files to the directory
+ given by +$(BINARIES_DIR)+. Only files that are binary images (aka
+ images) that do not belong in the +TARGET_DIR+ but are necessary
+ for booting the board should be placed here. For example, a package
+ should utilize this step if it has binaries which would be similar
+ to the kernel image, bootloader or root filesystem images.
* +LIBFOO_INSTALL_INIT_SYSV+ and +LIBFOO_INSTALL_INIT_SYSTEMD+ list the
actions to install init scripts either for the systemV-like init systems
systemd is selected as the init system in the configuration, only
+LIBFOO_INSTALL_INIT_SYSTEMD+ will be run).
+* +LIBFOO_HELP_CMDS+ lists the actions to print the package help, which
+ is included to the main +make help+ output. These commands can print
+ anything in any format.
+ This is seldom used, as packages rarely have custom rules. *Do not use
+ this variable*, unless you really know that you need to print help.
+
The preferred way to define these variables is:
----------------------
In the action definitions, you can use the following variables:
+* +$(LIBFOO_PKGDIR)+ contains the path to the directory containing the
+ +libfoo.mk+ and +Config.in+ files. This variable is useful when it is
+ necessary to install a file bundled in Buildroot, like a runtime
+ configuration file, a splashscreen image...
+
* +$(@D)+, which contains the directory in which the package source
code has been uncompressed.
+* +$(LIBFOO_DL_DIR)+ contains the path to the directory where all the downloads
+ made by Buildroot for +libfoo+ are stored in.
+
* +$(TARGET_CC)+, +$(TARGET_LD)+, etc. to get the target
cross-compilation utilities
projects / coffee / buildroot.git / blobdiff