diff options
Diffstat (limited to 'docs/manual/adding-packages-gentargets.txt')
| -rw-r--r-- | docs/manual/adding-packages-gentargets.txt | 369 |
1 files changed, 0 insertions, 369 deletions
diff --git a/docs/manual/adding-packages-gentargets.txt b/docs/manual/adding-packages-gentargets.txt deleted file mode 100644 index cc412090b..000000000 --- a/docs/manual/adding-packages-gentargets.txt +++ /dev/null @@ -1,369 +0,0 @@ -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]] - -+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_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: define LIBFOO_DEVICES -28: /dev/foo c 666 0 0 42 0 - - - -29: endef -30: -31: define LIBFOO_PERMISSIONS -32: /bin/foo f 4755 0 0 - - - - - -33: endef -34: -35: $(eval $(generic-package)) --------------------------------- - -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 35, we call the +generic-package+ which -generates, according to the variables defined previously, all the -Makefile code necessary to make your package working. - -[[gentargets-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 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+ 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+. 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=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 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. - -* +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 is one of those listed in xref:legal-info[], - 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. - If the root filesystem you generate contains non-opensource packages, you - can define their license as +PROPRIETARY+: Buildroot will not save any - licensing info or source code for this package. - 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. - -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 ----------------------- |