diff options
Diffstat (limited to 'docs/manual/adding-packages-gentargets.txt')
| -rw-r--r-- | docs/manual/adding-packages-gentargets.txt | 307 |
1 files changed, 307 insertions, 0 deletions
diff --git a/docs/manual/adding-packages-gentargets.txt b/docs/manual/adding-packages-gentargets.txt new file mode 100644 index 000000000..9a319d161 --- /dev/null +++ b/docs/manual/adding-packages-gentargets.txt @@ -0,0 +1,307 @@ +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,package,libfoo)) +-------------------------------- + +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 three arguments: + +* The first argument is the package directory prefix. If your package + is in +package/libfoo+, then the directory prefix is +package+. If + your package is in +package/editors/foo+, then the directory prefix + must be +package/editors+. + +* The second argument is the lower-cased package name. It must match + the prefix of the variables in the +.mk+ file and must match the + configuration option name in the +Config.in+ file. For example, if + the package name is +libfoo+, then the variables in the +.mk+ file + must start with +LIBFOO_+ and the configuration option in the + +Config.in+ file must be +BR2_PACKAGE_LIBFOO+. + +* The third argument is optional. It 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,package,libfoo)) +$(eval $(call GENTARGETS,package,libfoo,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_VERSION+. 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 +---------------------- |