docs/manual/adding-packages-generic.txt

   1 // -*- mode:doc; -*-
   2
   3 Infrastructure for packages with specific build systems
   4 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   5
   6 By 'packages with specific build systems' we mean all the packages
   7 whose build system is not one of the standard ones, such as
   8 'autotools' or 'CMake'. This typically includes packages whose build
   9 system is based on hand-written Makefiles or shell scripts.
  10
  11 [[generic-package-tutorial]]
  12
  13 +generic-package+ Tutorial
  14 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  15
  16 ------------------------------
  17 01: #############################################################
  18 02: #
  19 03: # libfoo
  20 04: #
  21 05: #############################################################
  22 06: LIBFOO_VERSION = 1.0
  23 07: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  24 08: LIBFOO_SITE = http://www.foosoftware.org/download
  25 09: LIBFOO_LICENSE = GPLv3+
  26 10: LIBFOO_LICENSE_FILES = COPYING
  27 11: LIBFOO_INSTALL_STAGING = YES
  28 12: LIBFOO_DEPENDENCIES = host-libaaa libbbb
  29 13:
  30 14: define LIBFOO_BUILD_CMDS
  31 15:     $(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D) all
  32 16: endef
  33 17:
  34 18: define LIBFOO_INSTALL_STAGING_CMDS
  35 19:     $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
  36 20:     $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
  37 21:     $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
  38 22: endef
  39 23:
  40 24: define LIBFOO_INSTALL_TARGET_CMDS
  41 25:     $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
  42 26:     $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
  43 27: endef
  44 28:
  45 29: define LIBFOO_DEVICES
  46 30:     /dev/foo  c  666  0  0  42  0  -  -  -
  47 31: endef
  48 32:
  49 33: define LIBFOO_PERMISSIONS
  50 34:     /bin/foo  f  4755  0  0  -  -  -  -  -
  51 35: endef
  52 36:
  53 37: $(eval $(generic-package))
  54 --------------------------------
  55
  56 The Makefile begins on line 6 to 8 with metadata information: the
  57 version of the package (+LIBFOO_VERSION+), the name of the
  58 tarball containing the package (+LIBFOO_SOURCE+) and the
  59 Internet location at which the tarball can be downloaded
  60 (+LIBFOO_SITE+). All variables must start with the same prefix,
  61 +LIBFOO_+ in this case. This prefix is always the uppercased
  62 version of the package name (see below to understand where the package
  63 name is defined).
  64
  65 On line 9, we specify that this package wants to install something to
  66 the staging space. This is often needed for libraries, since they must
  67 install header files and other development files in the staging space.
  68 This will ensure that the commands listed in the
  69 +LIBFOO_INSTALL_STAGING_CMDS+ variable will be executed.
  70
  71 On line 10, we specify the list of dependencies this package relies
  72 on. These dependencies are listed in terms of lower-case package names,
  73 which can be packages for the target (without the +host-+
  74 prefix) or packages for the host (with the +host-+) prefix).
  75 Buildroot will ensure that all these packages are built and installed
  76 'before' the current package starts its configuration.
  77
  78 The rest of the Makefile defines what should be done at the different
  79 steps of the package configuration, compilation and installation.
  80 +LIBFOO_BUILD_CMDS+ tells what steps should be performed to
  81 build the package. +LIBFOO_INSTALL_STAGING_CMDS+ tells what
  82 steps should be performed to install the package in the staging space.
  83 +LIBFOO_INSTALL_TARGET_CMDS+ tells what steps should be
  84 performed to install the package in the target space.
  85
  86 All these steps rely on the +$(@D)+ variable, which
  87 contains the directory where the source code of the package has been
  88 extracted.
  89
  90 Finally, on line 35, we call the +generic-package+ which
  91 generates, according to the variables defined previously, all the
  92 Makefile code necessary to make your package working.
  93
  94 [[generic-package-reference]]
  95
  96 +generic-package+ Reference
  97 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  98
  99 There are two variants of the generic target. The +generic-package+ macro is
 100 used for packages to be cross-compiled for the target.  The
 101 +host-generic-package+ macro is used for host packages, natively compiled
 102 for the host.  It is possible to call both of them in a single +.mk+
 103 file: once to create the rules to generate a target
 104 package and once to create the rules to generate a host package:
 105
 106 ----------------------
 107 $(eval $(generic-package))
 108 $(eval $(host-generic-package))
 109 ----------------------
 110
 111 This might be useful if the compilation of the target package requires
 112 some tools to be installed on the host. If the package name is
 113 +libfoo+, then the name of the package for the target is also
 114 +libfoo+, while the name of the package for the host is
 115 +host-libfoo+. These names should be used in the DEPENDENCIES
 116 variables of other packages, if they depend on +libfoo+ or
 117 +host-libfoo+.
 118
 119 The call to the +generic-package+ and/or +host-generic-package+ macro *must* be
 120 at the end of the +.mk+ file, after all variable definitions.
 121
 122 For the target package, the +generic-package+ uses the variables defined by
 123 the .mk file and prefixed by the uppercased package name:
 124 +LIBFOO_*+. +host-generic-package+ uses the +HOST_LIBFOO_*+ variables. For
 125 'some' variables, if the +HOST_LIBFOO_+ prefixed variable doesn't
 126 exist, the package infrastructure uses the corresponding variable
 127 prefixed by +LIBFOO_+. This is done for variables that are likely to
 128 have the same value for both the target and host packages. See below
 129 for details.
 130
 131 The list of variables that can be set in a +.mk+ file to give metadata
 132 information is (assuming the package name is +libfoo+) :
 133
 134 * +LIBFOO_VERSION+, mandatory, must contain the version of the
 135   package. Note that if +HOST_LIBFOO_VERSION+ doesn't exist, it is
 136   assumed to be the same as +LIBFOO_VERSION+. It can also be a
 137   revision number, branch or tag for packages that are fetched
 138   directly from their revision control system. +
 139   Examples: +
 140     +LIBFOO_VERSION = 0.1.2+ +
 141     +LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057+ +
 142     +LIBFOO_VERSION = stable+
 143
 144 * +LIBFOO_SOURCE+ may contain the name of the tarball of
 145   the package. If +HOST_LIBFOO_SOURCE+ is not specified, it
 146   defaults to +LIBFOO_SOURCE+. If none are specified, then
 147   the value is assumed to be
 148   +packagename-$(LIBFOO_VERSION).tar.gz+. +
 149   Example: +LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2+
 150
 151 * +LIBFOO_PATCH+ may contain the name of a patch, that will be
 152   downloaded from the same location as the tarball indicated in
 153   +LIBFOO_SOURCE+. If +HOST_LIBFOO_PATCH+ is not specified, it
 154   defaults to +LIBFOO_PATCH+. Note that patches that are included
 155   in Buildroot itself use a different mechanism: all files of the
 156   form +<packagename>-*.patch+ present in the package directory inside
 157   Buildroot will be applied to the package after extraction (see
 158   xref:patch-policy[patching a package]).
 159
 160 * +LIBFOO_SITE+ provides the location of the package, which can be a
 161   URL or a local filesystem path. HTTP, FTP and SCP are supported URL
 162   types for retrieving package tarballs. Git, Subversion, Mercurial,
 163   and Bazaar are supported URL types for retrieving packages directly
 164   from source code management systems. A filesystem path may be used
 165   to specify either a tarball or a directory containing the package
 166   source code. See +LIBFOO_SITE_METHOD+ below for more details on how
 167   retrieval works. +
 168   Note that SCP URLs should be of the form
 169   +scp://[user@]host:filepath+, and that filepath is relative to the
 170   user's home directory, so you may want to prepend the path with a
 171   slash for absolute paths:
 172   +scp://[user@]host:/absolutepath+. +
 173   If +HOST_LIBFOO_SITE+ is not specified, it defaults to
 174   +LIBFOO_SITE+.
 175   Examples: +
 176     +LIBFOO_SITE=http://www.libfoosoftware.org/libfoo+ +
 177     +LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor/+ +
 178     +LIBFOO_SITE=git://github.com/kergoth/tslib.git+ +
 179     +LIBFOO_SITE=/opt/software/libfoo.tar.gz+ +
 180     +LIBFOO_SITE=$(TOPDIR)/../src/libfoo/+
 181
 182 * +LIBFOO_SITE_METHOD+ determines the method used to fetch or copy the
 183   package source code. In many cases, Buildroot guesses the method
 184   from the contents of +LIBFOO_SITE+ and setting +LIBFOO_SITE_METHOD+
 185   is unnecessary. When +HOST_LIBFOO_SITE_METHOD+ is not specified, it
 186   defaults to the value of +LIBFOO_SITE_METHOD+. +
 187   The possible values of +LIBFOO_SITE_METHOD+ are:
 188   ** +wget+ for normal FTP/HTTP downloads of tarballs.  Used by
 189      default when +LIBFOO_SITE+ begins with +http://+, +https://+ or
 190      +ftp://+.
 191   ** +scp+ for downloads of tarballs over SSH with scp.  Used by
 192      default when +LIBFOO_SITE+ begins with +scp://+.
 193   ** +svn+ for retrieving source code from a Subversion repository.
 194      Used by default when +LIBFOO_SITE+ begins with +svn://+.  When a
 195      +http://+ Subversion repository URL is specified in
 196      +LIBFOO_SITE+, one 'must' specify +LIBFOO_SITE_METHOD=svn+.
 197      Buildroot performs a checkout which is preserved as a tarball in
 198      the download cache; subsequent builds use the tarball instead of
 199      performing another checkout.
 200   ** +git+ for retrieving source code from a Git repository.  Used by
 201      default when +LIBFOO_SITE+ begins with +git://+. The downloaded
 202      source code is cached as with the +svn+
 203      method.
 204   ** +hg+ for retrieving source code from a Mercurial repository. One
 205      'must' specify +LIBFOO_SITE_METHOD=hg+ when +LIBFOO_SITE+
 206      contains a Mercurial repository URL. The downloaded source code
 207      is cached as with the +svn+ method.
 208   ** +bzr+ for retrieving source code from a Bazaar repository. Used
 209      by default when +LIBFOO_SITE+ begins with +bzr://+. The
 210      downloaded source code is cached as with the +svn+ method.
 211   ** +file+ for a local tarball.  One should use this when
 212      +LIBFOO_SITE+ specifies a package tarball as a local filename.
 213      Useful for software that isn't available publicly or in version
 214      control.
 215   ** +local+ for a local source code directory.  One should use this
 216      when +LIBFOO_SITE+ specifies a local directory path containing
 217      the package source code.  Buildroot copies the contents of the
 218      source directory into the package's build directory.
 219
 220 * +LIBFOO_DEPENDENCIES+ lists the dependencies (in terms of package
 221   name) that are required for the current target package to
 222   compile. These dependencies are guaranteed to be compiled and
 223   installed before the configuration of the current package starts. In
 224   a similar way, +HOST_LIBFOO_DEPENDENCIES+ lists the dependencies for
 225   the current host package.
 226
 227 * +LIBFOO_INSTALL_STAGING+ can be set to +YES+ or +NO+ (default). If
 228   set to +YES+, then the commands in the +LIBFOO_INSTALL_STAGING_CMDS+
 229   variables are executed to install the package into the staging
 230   directory.
 231
 232 * +LIBFOO_INSTALL_TARGET+ can be set to +YES+ (default) or +NO+. If
 233   set to +YES+, then the commands in the +LIBFOO_INSTALL_TARGET_CMDS+
 234   variables are executed to install the package into the target
 235   directory.
 236
 237 * +LIBFOO_DEVICES+ lists the device files to be created by Buildroot
 238   when using the static device table. The syntax to use is the
 239   makedevs one. You can find some documentation for this syntax in the
 240   xref:makedev-syntax[]. This variable is optional.
 241
 242 * +LIBFOO_PERMISSIONS+ lists the changes of permissions to be done at
 243   the end of the build process. The syntax is once again the makedevs one.
 244   You can find some documentation for this syntax in the xref:makedev-syntax[].
 245   This variable is optional.
 246
 247 * +LIBFOO_LICENSE+ defines the license (or licenses) under which the package
 248   is released.
 249   This name will appear in the manifest file produced by +make legal-info+.
 250   If the license appears in xref:legal-info-list-licenses[the following list],
 251   use the same string to make the manifest file uniform.
 252   Otherwise, describe the license in a precise and concise way, avoiding
 253   ambiguous names such as +BSD+ which actually name a family of licenses.
 254   This variable is optional. If it is not defined, +unknown+ will appear in
 255   the +license+ field of the manifest file for this package.
 256
 257 * +LIBFOO_LICENSE_FILES+ is a space-separated list of files in the package
 258   tarball that contain the license(s) under which the package is released.
 259   +make legal-info+ copies all of these files in the +legal-info+ directory.
 260   See xref:legal-info[] for more information.
 261   This variable is optional. If it is not defined, a warning will be produced
 262   to let you know, and +not saved+ will appear in the +license files+ field
 263   of the manifest file for this package.
 264
 265 * +LIBFOO_REDISTRIBUTE+ can be set to +YES+ (default) or +NO+ to indicate if
 266   the package source code is allowed to be redistributed. Set it to +NO+ for
 267   non-opensource packages: Buildroot will not save the source code for this
 268   package when collecting the +legal-info+.
 269
 270 The recommended way to define these variables is to use the following
 271 syntax:
 272
 273 ----------------------
 274 LIBFOO_VERSION = 2.32
 275 ----------------------
 276
 277 Now, the variables that define what should be performed at the
 278 different steps of the build process.
 279
 280 * +LIBFOO_CONFIGURE_CMDS+ lists the actions to be performed to
 281   configure the package before its compilation.
 282
 283 * +LIBFOO_BUILD_CMDS+ lists the actions to be performed to
 284   compile the package.
 285
 286 * +HOST_LIBFOO_INSTALL_CMDS+ lists the actions to be performed
 287   to install the package, when the package is a host package. The
 288   package must install its files to the directory given by
 289   +$(HOST_DIR)+. All files, including development files such as
 290   headers should be installed, since other packages might be compiled
 291   on top of this package.
 292
 293 * +LIBFOO_INSTALL_TARGET_CMDS+ lists the actions to be
 294   performed to install the package to the target directory, when the
 295   package is a target package. The package must install its files to
 296   the directory given by +$(TARGET_DIR)+. Only the files required for
 297   'execution' of the package have to be
 298   installed. Header files, static libraries and documentation will be
 299   removed again when the target filesystem is finalized.
 300
 301 * +LIBFOO_INSTALL_STAGING_CMDS+ lists the actions to be
 302   performed to install the package to the staging directory, when the
 303   package is a target package. The package must install its files to
 304   the directory given by +$(STAGING_DIR)+. All development files
 305   should be installed, since they might be needed to compile other
 306   packages.
 307
 308 * +LIBFOO_CLEAN_CMDS+, lists the actions to perform to clean up
 309   the build directory of the package.
 310
 311 * +LIBFOO_UNINSTALL_TARGET_CMDS+ lists the actions to
 312   uninstall the package from the target directory +$(TARGET_DIR)+
 313
 314 * +LIBFOO_UNINSTALL_STAGING_CMDS+ lists the actions to
 315   uninstall the package from the staging directory +$(STAGING_DIR)+.
 316
 317 * +LIBFOO_INSTALL_INIT_SYSV+ and +LIBFOO_INSTALL_INIT_SYSTEMD+ list the
 318   actions to install init scripts either for the systemV-like init systems
 319   (busybox, sysvinit, etc.) or for the systemd units. These commands
 320   will be run only when the relevant init system is installed (i.e. if
 321   systemd is selected as the init system in the configuration, only
 322   +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run).
 323
 324 The preferred way to define these variables is:
 325
 326 ----------------------
 327 define LIBFOO_CONFIGURE_CMDS
 328         action 1
 329         action 2
 330         action 3
 331 endef
 332 ----------------------
 333
 334 In the action definitions, you can use the following variables:
 335
 336 * +$(@D)+, which contains the directory in which the package source
 337   code has been uncompressed.
 338
 339 * +$(TARGET_CC)+, +$(TARGET_LD)+, etc. to get the target
 340   cross-compilation utilities
 341
 342 * +$(TARGET_CROSS)+ to get the cross-compilation toolchain prefix
 343
 344 * Of course the +$(HOST_DIR)+, +$(STAGING_DIR)+ and +$(TARGET_DIR)+
 345   variables to install the packages properly.
 346
 347 The last feature of the generic infrastructure is the ability to add
 348 hooks. These define further actions to perform after existing steps.
 349 Most hooks aren't really useful for generic packages, since the +.mk+
 350 file already has full control over the actions performed in each step
 351 of the package construction. The hooks are more useful for packages
 352 using the autotools infrastructure described below.  However, since
 353 they are provided by the generic infrastructure, they are documented
 354 here. The exception is +LIBFOO_POST_PATCH_HOOKS+.  Patching the
 355 package and producing legal info are not user definable, so
 356 +LIBFOO_POST_PATCH_HOOKS+ and +LIBFOO_POST_LEGAL_INFO_HOOKS+ are
 357 useful for generic packages.
 358
 359 The following hook points are available:
 360
 361 * +LIBFOO_POST_PATCH_HOOKS+
 362 * +LIBFOO_PRE_CONFIGURE_HOOKS+
 363 * +LIBFOO_POST_CONFIGURE_HOOKS+
 364 * +LIBFOO_POST_BUILD_HOOKS+
 365 * +LIBFOO_POST_INSTALL_HOOKS+ (for host packages only)
 366 * +LIBFOO_POST_INSTALL_STAGING_HOOKS+ (for target packages only)
 367 * +LIBFOO_POST_INSTALL_TARGET_HOOKS+ (for target packages only)
 368 * +LIBFOO_POST_LEGAL_INFO_HOOKS+
 369
 370 These variables are 'lists' of variable names containing actions to be
 371 performed at this hook point. This allows several hooks to be
 372 registered at a given hook point. Here is an example:
 373
 374 ----------------------
 375 define LIBFOO_POST_PATCH_FIXUP
 376         action1
 377         action2
 378 endef
 379
 380 LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
 381 ----------------------