kumquat-buildroot/docs/manual/adding-packages-gentargets.txt

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