summaryrefslogtreecommitdiff
path: root/docs/manual/adding-packages-gentargets.txt
diff options
context:
space:
mode:
authorArnout Vandecappelle (Essensium/Mind) <arnout@mind.be>2012-07-06 00:06:46 +0200
committerThomas Petazzoni <thomas.petazzoni@free-electrons.com>2012-07-17 20:24:03 +0200
commit2359e1223f622c8984f235fd8ddfb40a8e1cdc7a (patch)
tree03246b91a4f642f2019492092ca17db4a64fd54e /docs/manual/adding-packages-gentargets.txt
parente1502ebc0c92763896c53d405ee9c7c7a1a33e24 (diff)
Clean up naming of old GENTARGETS infrastructure
With the renaming of XXXTARGETS to xxx-package, the names of the pkg-xxx.mk files is inconsistent, as well as some internal names in the documentation. These inconsistencies are cleaned up here. Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be> ...kages-autotargets.txt => adding-packages-autotools.txt} | 4 ++-- ...packages-cmaketargets.txt => adding-packages-cmake.txt} | 4 ++-- docs/manual/adding-packages-directory.txt | 12 ++++++------ ...packages-gentargets.txt => adding-packages-generic.txt} | 4 ++-- docs/manual/adding-packages.txt | 6 +++--- package/Makefile.in | 6 +++--- package/{pkg-autotargets.mk => pkg-autotools.mk} | 0 package/{pkg-cmaketargets.mk => pkg-cmake.mk} | 0 package/{pkg-gentargets.mk => pkg-generic.mk} | 0 9 files changed, 18 insertions(+), 18 deletions(-) Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Diffstat (limited to 'docs/manual/adding-packages-gentargets.txt')
-rw-r--r--docs/manual/adding-packages-gentargets.txt369
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
-----------------------