834f9311aa
This patch will add <pkg>_CONFIG_FIXUP variable to buildroot infra. It's purpose is to inform buildroot that the package in question contains some $(STAGING_DIR)/usr/bin/*-config files and that we want to automatically fix prefixes of such files. It is often the case that many packages call these files during their configuration step to determine 3rd party library package locations and any flags needed to link against them. For example: Some package might try to check the existense and linking flags of NSPR package by calling $(STAGING_DIR)/usr/bin/nspr-config --prefix. Without this fix. NSPR would return /usr/ as it's prefix which is wrong when cross-compiling. Correct would be $(STAGING_DIR)/usr. All packages that have <pkg>_INSTALL_STAGING = YES defined and also install some config file(s) into $(STAGING_DIR)/usr/bin must hereafter also define <pkg>_CONFIG_FIXUP with the correspondig filename(s). For example: DIVINE_CONFIG_FIXUP = divine-config or for multiple files: IMAGEMAGICK_CONFIG_FIXUP = Magick-config Wand-config Signed-off-by: Stefan Fröberg <stefan.froberg@petroprogram.com> Signed-off-by: Peter Korsgaard <jacmet@sunsite.dk>
440 lines
19 KiB
Plaintext
440 lines
19 KiB
Plaintext
// -*- mode:doc; -*-
|
|
|
|
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: LIBFOO_VERSION = 1.0
|
|
07: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
|
|
08: LIBFOO_SITE = http://www.foosoftware.org/download
|
|
09: LIBFOO_LICENSE = GPLv3+
|
|
10: LIBFOO_LICENSE_FILES = COPYING
|
|
11: LIBFOO_INSTALL_STAGING = YES
|
|
12: LIBFOO_CONFIG_FIXUP = libfoo-config
|
|
13: LIBFOO_DEPENDENCIES = host-libaaa libbbb
|
|
14:
|
|
15: define LIBFOO_BUILD_CMDS
|
|
16: $(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D) all
|
|
17: endef
|
|
18:
|
|
19: define LIBFOO_INSTALL_STAGING_CMDS
|
|
20: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
|
|
21: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
|
|
22: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
|
|
23: endef
|
|
24:
|
|
25: define LIBFOO_INSTALL_TARGET_CMDS
|
|
26: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
|
|
27: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
|
|
28: endef
|
|
29:
|
|
30: define LIBFOO_DEVICES
|
|
31: /dev/foo c 666 0 0 42 0 - - -
|
|
32: endef
|
|
33:
|
|
34: define LIBFOO_PERMISSIONS
|
|
35: /bin/foo f 4755 0 0 - - - - -
|
|
36: endef
|
|
37:
|
|
38: $(eval $(generic-package))
|
|
--------------------------------
|
|
|
|
The Makefile begins on line 6 to 10 with metadata information: the
|
|
version of the package (+LIBFOO_VERSION+), the name of the
|
|
tarball containing the package (+LIBFOO_SOURCE+) 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 11, 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 12, 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_FIXUP+ 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.
|
|
|
|
Example 1:
|
|
|
|
Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'.
|
|
|
|
So it's fixup would be:
|
|
|
|
DIVINE_CONFIG = divine-config
|
|
|
|
Example 2:
|
|
|
|
Package imagemagick installs the following scripts:
|
|
'$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config'
|
|
|
|
So it's fixup would be:
|
|
|
|
IMAGEMAGICK_CONFIG_FIXUP = Magick-config Magick++-config \
|
|
MagickCore-config MagickWand-config Wand-config
|
|
|
|
On line 13, 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 14..27, 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 line 29..31, we define a device-node file used by this package
|
|
(+LIBFOO_DEVICES+).
|
|
|
|
On line 33..35, we define the permissions to set to specific files
|
|
installed by this package (+LIBFOO_PERMISSIONS+).
|
|
|
|
Finally, on line 37, 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.
|
|
|
|
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, 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+. +
|
|
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
|
|
itself use a different mechanism: all files of the form
|
|
+<packagename>-*.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. Git, Subversion, Mercurial,
|
|
and Bazaar are supported URL types for retrieving packages directly
|
|
from source code management systems. 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=git://github.com/kergoth/tslib.git+ +
|
|
+LIBFOO_SITE=/opt/software/libfoo.tar.gz+ +
|
|
+LIBFOO_SITE=$(TOPDIR)/../src/libfoo/+
|
|
|
|
* +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.
|
|
** +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.
|
|
|
|
* +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. In
|
|
a similar way, +HOST_LIBFOO_DEPENDENCIES+ lists the dependencies for
|
|
the current host package.
|
|
|
|
* +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_CONFIG_FIXUP+ 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'.
|
|
|
|
* +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_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.
|
|
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.
|
|
|
|
* +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_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+.
|
|
|
|
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_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_CLEAN_CMDS+, lists the actions to perform to clean up
|
|
the build directory of the package.
|
|
|
|
* +LIBFOO_UNINSTALL_TARGET_CMDS+ lists the actions to
|
|
uninstall the package from the target directory +$(TARGET_DIR)+
|
|
|
|
* +LIBFOO_UNINSTALL_STAGING_CMDS+ lists the actions to
|
|
uninstall the package from the staging directory +$(STAGING_DIR)+.
|
|
|
|
* +LIBFOO_INSTALL_INIT_SYSV+ and +LIBFOO_INSTALL_INIT_SYSTEMD+ list the
|
|
actions to install init scripts either for the systemV-like init systems
|
|
(busybox, sysvinit, etc.) 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 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:
|
|
|
|
* +$(@D)+, which contains the directory in which the package source
|
|
code has been uncompressed.
|
|
|
|
* +$(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.
|
|
|
|
The last feature of the generic infrastructure is the ability to add
|
|
hooks. These define further actions to perform after existing steps.
|
|
Most hooks aren't really useful for generic packages, since the +.mk+
|
|
file already has full control over the actions performed in each step
|
|
of the package construction. The hooks are more useful for packages
|
|
using the autotools infrastructure described below. However, since
|
|
they are provided by the generic infrastructure, they are documented
|
|
here. The exception is +LIBFOO_POST_PATCH_HOOKS+. Patching the
|
|
package and producing legal info are not user definable, so
|
|
+LIBFOO_POST_PATCH_HOOKS+ and +LIBFOO_POST_LEGAL_INFO_HOOKS+ are
|
|
useful for generic packages.
|
|
|
|
The following hook points are available:
|
|
|
|
* +LIBFOO_POST_DOWNLOAD_HOOKS+
|
|
* +LIBFOO_POST_EXTRACT_HOOKS+
|
|
* +LIBFOO_PRE_PATCH_HOOKS+
|
|
* +LIBFOO_POST_PATCH_HOOKS+
|
|
* +LIBFOO_PRE_CONFIGURE_HOOKS+
|
|
* +LIBFOO_POST_CONFIGURE_HOOKS+
|
|
* +LIBFOO_POST_BUILD_HOOKS+
|
|
* +LIBFOO_POST_INSTALL_HOOKS+ (for host packages only)
|
|
* +LIBFOO_POST_INSTALL_STAGING_HOOKS+ (for target packages only)
|
|
* +LIBFOO_POST_INSTALL_TARGET_HOOKS+ (for target packages only)
|
|
* +LIBFOO_POST_LEGAL_INFO_HOOKS+
|
|
|
|
These variables are 'lists' of variable names containing actions to be
|
|
performed at this hook point. This allows several hooks to be
|
|
registered at a given hook point. Here is an example:
|
|
|
|
----------------------
|
|
define LIBFOO_POST_PATCH_FIXUP
|
|
action1
|
|
action2
|
|
endef
|
|
|
|
LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
|
|
----------------------
|