123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665 |
- // -*- mode:doc; -*-
- // vim: set syntax=asciidoc:
- === 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
- 'autotools' or 'CMake'. This typically includes packages whose build
- system is based on hand-written Makefiles or shell scripts.
- [[generic-package-tutorial]]
- ==== +generic-package+ tutorial
- ------------------------------
- 01: ################################################################################
- 02: #
- 03: # libfoo
- 04: #
- 05: ################################################################################
- 06:
- 07: LIBFOO_VERSION = 1.0
- 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
- 09: LIBFOO_SITE = http://www.foosoftware.org/download
- 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) $(TARGET_CONFIGURE_OPTS) -C $(@D) all
- 18: endef
- 19:
- 20: define LIBFOO_INSTALL_STAGING_CMDS
- 21: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
- 22: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
- 23: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
- 24: endef
- 25:
- 26: define LIBFOO_INSTALL_TARGET_CMDS
- 27: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
- 28: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
- 29: endef
- 30:
- 31: define LIBFOO_USERS
- 32: foo -1 libfoo -1 * - - - LibFoo daemon
- 33: endef
- 34:
- 35: define LIBFOO_DEVICES
- 36: /dev/foo c 666 0 0 42 0 - - -
- 37: endef
- 38:
- 39: define LIBFOO_PERMISSIONS
- 40: /bin/foo f 4755 foo libfoo - - - - -
- 41: endef
- 42:
- 43: $(eval $(generic-package))
- --------------------------------
- The Makefile begins on line 7 to 11 with metadata information: the
- version of the package (+LIBFOO_VERSION+), the name of the
- tarball containing the package (+LIBFOO_SOURCE+) (xz-ed tarball recommended)
- the Internet location at which the tarball can be downloaded from
- (+LIBFOO_SITE+), the license (+LIBFOO_LICENSE+) and file with the
- license text (+LIBFOO_LICENSE_FILES+). All variables must start with
- the same prefix, +LIBFOO_+ in this case. This prefix is always the
- uppercased version of the package name (see below to understand where
- the package name is defined).
- On line 12, we specify that this package wants to install something to
- the staging space. This is often needed for libraries, since they must
- install header files and other development files in the staging space.
- This will ensure that the commands listed in the
- +LIBFOO_INSTALL_STAGING_CMDS+ variable will be executed.
- On line 13, we specify that there is some fixing to be done to some
- of the 'libfoo-config' files that were installed during
- +LIBFOO_INSTALL_STAGING_CMDS+ phase.
- These *-config files are executable shell script files that are
- located in '$(STAGING_DIR)/usr/bin' directory and are executed
- by other 3rd party packages to find out the location and the linking
- flags of this particular package.
- The problem is that all these *-config files by default give wrong,
- host system linking flags that are unsuitable for cross-compiling.
- For example: '-I/usr/include' instead of '-I$(STAGING_DIR)/usr/include'
- or: '-L/usr/lib' instead of '-L$(STAGING_DIR)/usr/lib'
- So some sed magic is done to these scripts to make them give correct
- flags.
- The argument to be given to +LIBFOO_CONFIG_SCRIPTS+ is the file name(s)
- of the shell script(s) needing fixing. All these names are relative to
- '$(STAGING_DIR)/usr/bin' and if needed multiple names can be given.
- In addition, the scripts listed in +LIBFOO_CONFIG_SCRIPTS+ are removed
- from +$(TARGET_DIR)/usr/bin+, since they are not needed on the target.
- .Config script: 'divine' package
- ================================
- Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'.
- So its fixup would be:
- --------------------------------
- DIVINE_CONFIG_SCRIPTS = divine-config
- --------------------------------
- ================================
- .Config script: 'imagemagick' package:
- ================================
- Package imagemagick installs the following scripts:
- '$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config'
- So it's fixup would be:
- --------------------------------
- IMAGEMAGICK_CONFIG_SCRIPTS = \
- Magick-config Magick++-config \
- MagickCore-config MagickWand-config Wand-config
- --------------------------------
- ================================
- On line 14, we specify the list of dependencies this package relies
- on. These dependencies are listed in terms of lower-case package names,
- which can be packages for the target (without the +host-+
- prefix) or packages for the host (with the +host-+) prefix).
- Buildroot will ensure that all these packages are built and installed
- 'before' the current package starts its configuration.
- The rest of the Makefile, lines 16..29, defines what should be done
- at the different steps of the package configuration, compilation and
- installation.
- +LIBFOO_BUILD_CMDS+ tells what steps should be performed to
- build the package. +LIBFOO_INSTALL_STAGING_CMDS+ tells what
- steps should be performed to install the package in the staging space.
- +LIBFOO_INSTALL_TARGET_CMDS+ tells what steps should be
- performed to install the package in the target space.
- All these steps rely on the +$(@D)+ variable, which
- contains the directory where the source code of the package has been
- extracted.
- On lines 31..33, 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 39..41, we define the permissions to set to specific files
- installed by this package (+LIBFOO_PERMISSIONS+).
- 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
- There are two variants of the generic target. The +generic-package+ macro is
- 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+
- file: once to create the rules to generate a target
- package and once to create the rules to generate a host package:
- ----------------------
- $(eval $(generic-package))
- $(eval $(host-generic-package))
- ----------------------
- This might be useful if the compilation of the target package requires
- some tools to be installed on the host. If the package name is
- +libfoo+, then the name of the package for the target is also
- +libfoo+, while the name of the package for the host is
- +host-libfoo+. These names should be used in the DEPENDENCIES
- 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 +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_*+. +host-generic-package+ uses the +HOST_LIBFOO_*+ variables. For
- 'some' variables, if the +HOST_LIBFOO_+ prefixed variable doesn't
- exist, the package infrastructure uses the corresponding variable
- prefixed by +LIBFOO_+. This is done for variables that are likely to
- have the same value for both the target and host packages. See below
- for details.
- The list of variables that can be set in a +.mk+ file to give metadata
- information is (assuming the package name is +libfoo+) :
- * +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 or a tag for packages that are fetched directly
- from their version control system. 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+
- +
- .Note:
- Using a branch name as +FOO_VERSION+ is not supported, because it does
- not and can not work as people would expect it should:
- +
- 1. due to local caching, Buildroot will not re-fetch the repository,
- so people who expect to be able to follow the remote repository
- would be quite surprised and disappointed;
- 2. because two builds can never be perfectly simultaneous, and because
- the remote repository may get new commits on the branch anytime,
- two users, using the same Buildroot tree and building the same
- configuration, may get different source, thus rendering the build
- non reproducible, and people would be quite surprised and
- disappointed.
- * +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 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
- +*.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
- in the Buildroot package directory.
- * +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. 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. 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. +
- Note that SCP URLs should be of the form
- +scp://[user@]host:filepath+, and that filepath is relative to the
- user's home directory, so you may want to prepend the path with a
- slash for absolute paths:
- +scp://[user@]host:/absolutepath+. +
- If +HOST_LIBFOO_SITE+ is not specified, it defaults to
- +LIBFOO_SITE+.
- Examples: +
- +LIBFOO_SITE=http://www.libfoosoftware.org/libfoo+ +
- +LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor+ +
- +LIBFOO_SITE=/opt/software/libfoo.tar.gz+ +
- +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
- from the contents of +LIBFOO_SITE+ and setting +LIBFOO_SITE_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
- default when +LIBFOO_SITE+ begins with +http://+, +https://+ or
- +ftp://+.
- ** +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
- +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
- the download cache; subsequent builds use the tarball instead of
- performing another checkout.
- ** +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.
- 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 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.
- ** +hg+ for retrieving source code from a Mercurial repository. One
- 'must' specify +LIBFOO_SITE_METHOD=hg+ when +LIBFOO_SITE+
- contains a Mercurial repository URL. 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
- +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
- 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. 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
- compile. These dependencies are guaranteed to be compiled and
- installed before the configuration of the current package starts.
- However, modifications to configuration of these dependencies will
- not force a rebuild of the current package. In 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 (but not necessarily built) 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
- directory.
- * +LIBFOO_INSTALL_TARGET+ can be set to +YES+ (default) or +NO+. If
- set to +YES+, then the commands in the +LIBFOO_INSTALL_TARGET_CMDS+
- 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
- be given and all are relative to '$(STAGING_DIR)/usr/bin'. The files
- listed in +LIBFOO_CONFIG_SCRIPTS+ are also removed from
- +$(TARGET_DIR)/usr/bin+ since they are not needed on the target.
- * +LIBFOO_DEVICES+ lists the device files to be created by Buildroot
- when using the static device table. The syntax to use is the
- makedevs one. You can find some documentation for this syntax in the
- xref:makedev-syntax[]. This variable is optional.
- * +LIBFOO_PERMISSIONS+ lists the changes of permissions to be done at
- the end of the build process. The syntax is once again the makedevs one.
- You can find some documentation for this syntax in the xref:makedev-syntax[].
- 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 (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 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 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 some licenses are conditioned on a sub-option being enabled, append
- the conditional licenses with a comma (e.g.: `FOO_LICENSE += , GPL-2.0+
- (programs)`); the infrastructure will internally remove the space before
- the comma.
- ** 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.
- +make legal-info+ copies all of these files in the +legal-info+ directory.
- See xref:legal-info[] for more information.
- This variable is optional. If it is not defined, a warning will be produced
- 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+ / +LIBFOO_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
- package when collecting the +legal-info+.
- * +LIBFOO_FLAT_STACKSIZE+ defines the stack size of an application built into
- the FLAT binary format. The application stack size on the NOMMU architecture
- processors can't be enlarged at run time. The default stack size for the
- 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.
- * +LIBFOO_IGNORE_CVES+ is a space-separated list of CVEs that tells
- Buildroot CVE tracking tools which CVEs should be ignored for this
- package. This is typically used when the CVE is fixed by a patch in
- the package, or when the CVE for some reason does not affect the
- Buildroot package. A Makefile comment must always precede the
- addition of a CVE to this variable. Example:
- ----------------------
- # 0001-fix-cve-2020-12345.patch
- LIBFOO_IGNORE_CVES += CVE-2020-12345
- # only when built with libbaz, which Buildroot doesn't support
- LIBFOO_IGNORE_CVES += CVE-2020-54321
- ----------------------
- * +LIBFOO_CPE_ID_*+ variables is a set of variables that allows the
- package to define its https://nvd.nist.gov/products/cpe[CPE
- identifier]. The available variables are:
- +
- --
- ** +LIBFOO_CPE_ID_PREFIX+, specifies the prefix of the CPE identifier,
- i.e the first three fields. When not defined, the default value is
- +cpe:2.3:a+.
- ** +LIBFOO_CPE_ID_VENDOR+, specifies the vendor part of the CPE
- identifier. When not defined, the default value is
- +<pkgname>_project+.
- ** +LIBFOO_CPE_ID_PRODUCT+, specifies the product part of the CPE
- identifier. When not defined, the default value is +<pkgname>+.
- ** +LIBFOO_CPE_ID_VERSION+, specifies the version part of the CPE
- identifier. When not defined the default value is
- +$(LIBFOO_VERSION)+.
- ** +LIBFOO_CPE_ID_VERSION_MINOR+ specifies the _update_ part of the
- CPE identifier. When not defined the default value is +*+.
- --
- +
- If any of those variables is defined, then the generic package
- infrastructure assumes the package provides valid CPE information. In
- this case, +LIBFOO_CPE_ID_VALID = YES+ will be set, and the generic
- package infrastructure will define +LIBFOO_CPE_ID+.
- +
- Alternatively, a package can also explicitly set +LIBFOO_CPE_ID_VALID
- = YES+ if the default values for +LIBFOO_CPE_ID_PREFIX+,
- +LIBFOO_CPE_ID_VENDOR+, +LIBFOO_CPE_ID_PRODUCT+,
- +LIBFOO_CPE_ID_VERSION+, +LIBFOO_CPE_ID_VERSION_MINOR+ are all correct
- for this package and don't need to be explicitly overridden.
- +
- For a host package, if its +LIBFOO_CPE_ID_*+ variables are not
- defined, it inherits the value of those variables from the
- corresponding target package.
- The recommended way to define these variables is to use the following
- syntax:
- ----------------------
- LIBFOO_VERSION = 2.32
- ----------------------
- Now, the variables that define what should be performed at the
- different steps of the build process.
- * +LIBFOO_EXTRACT_CMDS+ lists the actions to be performed to extract
- the package. This is generally not needed as tarballs are
- automatically handled by Buildroot. However, if the package uses a
- non-standard archive format, such as a ZIP or RAR file, or has a
- tarball with a non-standard organization, this variable allows to
- override the package infrastructure default behavior.
- * +LIBFOO_CONFIGURE_CMDS+ lists the actions to be performed to
- configure the package before its compilation.
- * +LIBFOO_BUILD_CMDS+ lists the actions to be performed to
- compile the package.
- * +HOST_LIBFOO_INSTALL_CMDS+ lists the actions to be performed
- to install the package, when the package is a host package. The
- package must install its files to the directory given by
- +$(HOST_DIR)+. All files, including development files such as
- headers should be installed, since other packages might be compiled
- on top of this package.
- * +LIBFOO_INSTALL_TARGET_CMDS+ lists the actions to be
- performed to install the package to the target directory, when the
- package is a target package. The package must install its files to
- the directory given by +$(TARGET_DIR)+. Only the files required for
- 'execution' of the package have to be
- installed. Header files, static libraries and documentation will be
- removed again when the target filesystem is finalized.
- * +LIBFOO_INSTALL_STAGING_CMDS+ lists the actions to be
- performed to install the package to the staging directory, when the
- package is a target package. The package must install its files to
- the directory given by +$(STAGING_DIR)+. All development files
- should be installed, since they might be needed to compile other
- packages.
- * +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+, +LIBFOO_INSTALL_INIT_OPENRC+ and
- +LIBFOO_INSTALL_INIT_SYSTEMD+ list the actions to install init
- scripts either for the systemV-like init systems (busybox,
- sysvinit, etc.), openrc or for the systemd units. These commands
- will be run only when the relevant init system is installed (i.e.
- if systemd is selected as the init system in the configuration,
- only +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run). The only exception
- is when openrc is chosen as init system and +LIBFOO_INSTALL_INIT_OPENRC+
- has not been set, in such situation +LIBFOO_INSTALL_INIT_SYSV+ will
- be called, since openrc supports sysv init scripts.
- When systemd is used as the init system, buildroot will automatically enable
- all services using the +systemctl preset-all+ command in the final phase of
- image building. You can add preset files to prevent a particular unit from
- being automatically enabled by buildroot.
- * +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.
- * +LIBFOO_LINUX_CONFIG_FIXUPS+ lists the Linux kernel configuration
- options that are needed to build and use this package, and without
- which the package is fundamentally broken. This shall be a set of
- calls to one of the kconfig tweaking option: `KCONFIG_ENABLE_OPT`,
- `KCONFIG_DISABLE_OPT`, or `KCONFIG_SET_OPT`.
- This is seldom used, as package usually have no strict requirements on
- the kernel options.
- The preferred way to define these variables is:
- ----------------------
- define LIBFOO_CONFIGURE_CMDS
- action 1
- action 2
- action 3
- endef
- ----------------------
- 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
- * +$(TARGET_CROSS)+ to get the cross-compilation toolchain prefix
- * Of course the +$(HOST_DIR)+, +$(STAGING_DIR)+ and +$(TARGET_DIR)+
- variables to install the packages properly. Those variables point to
- the global _host_, _staging_ and _target_ directories, unless
- _per-package directory_ support is used, in which case they point to
- the current package _host_, _staging_ and _target_ directories. In
- both cases, it doesn't make any difference from the package point of
- view: it should simply use +HOST_DIR+, +STAGING_DIR+ and
- +TARGET_DIR+. See xref:top-level-parallel-build[] for more details
- about _per-package directory_ support.
- Finally, you can also use hooks. See xref:hooks[] for more information.
|