| 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. |
| |
| [[generic-package-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. |
| |
| [[generic-package-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)+. |
| |
| * +LIBFOO_INSTALL_INIT_SYSV+ and +LIBFOO_INSTALL_INIT_SYSTEMD+, used |
| to install init scripts either for the systemV-like init systems |
| (busybox, sysvinit, etc.) or for the systemd units. These commands |
| will be run only when the relevant init system is installed (i.e. if |
| systemd is selected as the init system in the configuration, only |
| +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run). |
| |
| 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 |
| ---------------------- |