7a63f1a08c
Signed-off-by: Trevor Woerner <twoerner@gmail.com> Signed-off-by: Peter Korsgaard <jacmet@sunsite.dk>
295 lines
12 KiB
Plaintext
295 lines
12 KiB
Plaintext
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.
|
|
|
|
[[gentargets-tutorial]]
|
|
|
|
+GENTARGETS+ 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_INSTALL_STAGING = YES
|
|
10: LIBFOO_DEPENDENCIES = host-libaaa libbbb
|
|
11:
|
|
12: define LIBFOO_BUILD_CMDS
|
|
13: $(MAKE) CC=$(TARGET_CC) LD=$(TARGET_LD) -C $(@D) all
|
|
14: endef
|
|
15:
|
|
16: define LIBFOO_INSTALL_STAGING_CMDS
|
|
17: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
|
|
18: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
|
|
19: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
|
|
20: endef
|
|
21:
|
|
22: define LIBFOO_INSTALL_TARGET_CMDS
|
|
23: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
|
|
24: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
|
|
25: endef
|
|
26:
|
|
27: $(eval $(call GENTARGETS))
|
|
--------------------------------
|
|
|
|
The Makefile begins on line 6 to 8 with metadata information: the
|
|
version of the package (+LIBFOO_VERSION+), the name of the
|
|
tarball containing the package (+LIBFOO_SOURCE+) and the
|
|
Internet location at which the tarball can be downloaded
|
|
(+LIBFOO_SITE+). 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 9, 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 10, 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 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.
|
|
|
|
Finally, on line 27, we call the +GENTARGETS+ which
|
|
generates, according to the variables defined previously, all the
|
|
Makefile code necessary to make your package working.
|
|
|
|
[[gentargets-reference]]
|
|
|
|
+GENTARGETS+ Reference
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The +GENTARGETS+ macro takes one optional argument. This argument can
|
|
be used to tell if the package is a target package (cross-compiled for
|
|
the target) or a host package (natively compiled for the host). If
|
|
unspecified, it is assumed that it is a target package. See below for
|
|
details.
|
|
|
|
For a given package, in a single +.mk+ file, it is possible to call
|
|
GENTARGETS twice, once to create the rules to generate a target
|
|
package and once to create the rules to generate a host package:
|
|
|
|
----------------------
|
|
$(eval $(call GENTARGETS))
|
|
$(eval $(call GENTARGETS,host))
|
|
----------------------
|
|
|
|
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 +GENTARGETS+ macro *must* be at the end of the +.mk+
|
|
file, after all variable definitions.
|
|
|
|
For the target package, the +GENTARGETS+ uses the variables defined by
|
|
the .mk file and prefixed by the uppercased package name:
|
|
+LIBFOO_*+. For the host package, it uses the +HOST_LIBFOO_*+. 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
|
|
Subversion or Git branch or tag, for packages that are fetched
|
|
directly from their revision control system. +
|
|
Example: +LIBFOO_VERSION = 0.1.2+
|
|
|
|
* +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 the name of a patch, that will be
|
|
downloaded from the same location as the tarball indicated in
|
|
+LIBFOO_SOURCE+. If +HOST_LIBFOO_PATCH+ is not specified, it
|
|
defaults to +LIBFOO_PATCH+. Also note that another mechanism is
|
|
available to patch a package: all files of the form
|
|
+packagename-packageversion-description.patch+ present in the
|
|
package directory inside Buildroot will be applied to the package
|
|
after extraction.
|
|
|
|
* +LIBFOO_SITE+ may contain the Internet location of the package. It
|
|
can either be the HTTP or FTP location of a tarball, or the URL of a
|
|
Git or Subversion repository (see +LIBFOO_SITE_METHOD+ below). If
|
|
+HOST_LIBFOO_SITE+ is not specified, it defaults to
|
|
+LIBFOO_SITE+. If none are specified, then the location is assumed
|
|
to be
|
|
+http://$$(BR2_SOURCEFORGE_MIRROR).dl.sourceforge.net/sourceforge/packagename+. +
|
|
Examples: +LIBFOO_SITE=http://www.libfoosoftware.org/libfoo+ +
|
|
+LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor/+
|
|
|
|
* +LIBFOO_SITE_METHOD+ may contain the method to fetch the package
|
|
source code. It can either be +wget+ (for normal FTP/HTTP downloads
|
|
of tarballs), +svn+, +git+ or +bzr+. When not specified, it is
|
|
guessed from the URL given in +LIBFOO_SITE+: +svn://+, +git://+ and
|
|
+bzr://+ URLs will use the +svn+, +git+ and +bzr+ methods
|
|
respectively. All other URL-types will use the +wget+ method. So for
|
|
example, in the case of a package whose source code is available
|
|
through Subversion repository on HTTP, one 'must' specifiy
|
|
+LIBFOO_SITE_METHOD=svn+. For +svn+ and +git+ methods, what
|
|
Buildroot does is a checkout/clone of the repository which is then
|
|
tarballed and stored into the download cache. Next builds will not
|
|
checkout/clone again, but will use the tarball directly. When
|
|
+HOST_LIBFOO_SITE_METHOD+ is not specified, it defaults to the value
|
|
of +LIBFOO_SITE_METHOD+. See +package/multimedia/tremor/+ for an
|
|
example.
|
|
|
|
* +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 dependency 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.
|
|
|
|
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+, used to list the actions to be performed to
|
|
configure the package before its compilation
|
|
|
|
* +LIBFOO_BUILD_CMDS+, used to list the actions to be performed to
|
|
compile the package
|
|
|
|
* +HOST_LIBFOO_INSTALL_CMDS+, used to list 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+, used to list 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
|
|
'documentation' and 'execution' of the package should be
|
|
installed. Header files should not be installed, they will be copied
|
|
to the target, if the +development files in target filesystem+
|
|
option is selected.
|
|
|
|
* +LIBFOO_INSTALL_STAGING_CMDS+, used to list 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+, used to list the actions to perform to clean up
|
|
the build directory of the package.
|
|
|
|
* +LIBFOO_UNINSTALL_TARGET_CMDS+, used to list the actions to
|
|
uninstall the package from the target directory +$(TARGET_DIR)+
|
|
|
|
* +LIBFOO_UNINSTALL_STAGING_CMDS+, used to list the actions to
|
|
uninstall the package from the staging directory +$(STAGING_DIR)+.
|
|
|
|
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 is not user definable, so +LIBFOO_POST_PATCH_HOOKS+ will be
|
|
userful for generic packages.
|
|
|
|
The following hook points are available:
|
|
|
|
* +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)
|
|
|
|
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
|
|
----------------------
|