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+. Also note that another mechanism is
 155   available to patch a package: all files of the form
 156   +packagename-packageversion-description.patch+ present in the
 157   package directory inside Buildroot will be applied to the package
 158   after extraction.
 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   If the root filesystem you generate contains non-opensource packages, you
 255   can define their license as +PROPRIETARY+: Buildroot will not save any
 256   licensing info or source code for this package.
 257   This variable is optional. If it is not defined, +unknown+ will appear in
 258   the +license+ field of the manifest file for this package.
 259
 260 * +LIBFOO_LICENSE_FILES+ is a space-separated list of files in the package
 261   tarball that contain the license(s) under which the package is released.
 262   +make legal-info+ copies all of these files in the +legal-info+ directory.
 263   See xref:legal-info[] for more information.
 264   This variable is optional. If it is not defined, a warning will be produced
 265   to let you know, and +not saved+ will appear in the +license files+ field
 266   of the manifest file for this package.
 267
 268 The recommended way to define these variables is to use the following
 269 syntax:
 270
 271 ----------------------
 272 LIBFOO_VERSION = 2.32
 273 ----------------------
 274
 275 Now, the variables that define what should be performed at the
 276 different steps of the build process.
 277
 278 * +LIBFOO_CONFIGURE_CMDS+ lists the actions to be performed to
 279   configure the package before its compilation.
 280
 281 * +LIBFOO_BUILD_CMDS+ lists the actions to be performed to
 282   compile the package.
 283
 284 * +HOST_LIBFOO_INSTALL_CMDS+ lists the actions to be performed
 285   to install the package, when the package is a host package. The
 286   package must install its files to the directory given by
 287   +$(HOST_DIR)+. All files, including development files such as
 288   headers should be installed, since other packages might be compiled
 289   on top of this package.
 290
 291 * +LIBFOO_INSTALL_TARGET_CMDS+ lists the actions to be
 292   performed to install the package to the target directory, when the
 293   package is a target package. The package must install its files to
 294   the directory given by +$(TARGET_DIR)+. Only the files required for
 295   'documentation' and 'execution' of the package should be
 296   installed. Header files should not be installed, they will be copied
 297   to the target, if the +development files in target filesystem+
 298   option is selected.
 299
 300 * +LIBFOO_INSTALL_STAGING_CMDS+ lists the actions to be
 301   performed to install the package to the staging directory, when the
 302   package is a target package. The package must install its files to
 303   the directory given by +$(STAGING_DIR)+. All development files
 304   should be installed, since they might be needed to compile other
 305   packages.
 306
 307 * +LIBFOO_CLEAN_CMDS+, lists the actions to perform to clean up
 308   the build directory of the package.
 309
 310 * +LIBFOO_UNINSTALL_TARGET_CMDS+ lists the actions to
 311   uninstall the package from the target directory +$(TARGET_DIR)+
 312
 313 * +LIBFOO_UNINSTALL_STAGING_CMDS+ lists the actions to
 314   uninstall the package from the staging directory +$(STAGING_DIR)+.
 315
 316 * +LIBFOO_INSTALL_INIT_SYSV+ and +LIBFOO_INSTALL_INIT_SYSTEMD+ list the
 317   actions to install init scripts either for the systemV-like init systems
 318   (busybox, sysvinit, etc.) or for the systemd units. These commands
 319   will be run only when the relevant init system is installed (i.e. if
 320   systemd is selected as the init system in the configuration, only
 321   +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run).
 322
 323 The preferred way to define these variables is:
 324
 325 ----------------------
 326 define LIBFOO_CONFIGURE_CMDS
 327         action 1
 328         action 2
 329         action 3
 330 endef
 331 ----------------------
 332
 333 In the action definitions, you can use the following variables:
 334
 335 * +$(@D)+, which contains the directory in which the package source
 336   code has been uncompressed.
 337
 338 * +$(TARGET_CC)+, +$(TARGET_LD)+, etc. to get the target
 339   cross-compilation utilities
 340
 341 * +$(TARGET_CROSS)+ to get the cross-compilation toolchain prefix
 342
 343 * Of course the +$(HOST_DIR)+, +$(STAGING_DIR)+ and +$(TARGET_DIR)+
 344   variables to install the packages properly.
 345
 346 The last feature of the generic infrastructure is the ability to add
 347 hooks. These define further actions to perform after existing steps.
 348 Most hooks aren't really useful for generic packages, since the +.mk+
 349 file already has full control over the actions performed in each step
 350 of the package construction. The hooks are more useful for packages
 351 using the autotools infrastructure described below.  However, since
 352 they are provided by the generic infrastructure, they are documented
 353 here. The exception is +LIBFOO_POST_PATCH_HOOKS+.  Patching the
 354 package and producing legal info are not user definable, so
 355 +LIBFOO_POST_PATCH_HOOKS+ and +LIBFOO_POST_LEGAL_INFO_HOOKS+ are
 356 useful for generic packages.
 357
 358 The following hook points are available:
 359
 360 * +LIBFOO_POST_PATCH_HOOKS+
 361 * +LIBFOO_PRE_CONFIGURE_HOOKS+
 362 * +LIBFOO_POST_CONFIGURE_HOOKS+
 363 * +LIBFOO_POST_BUILD_HOOKS+
 364 * +LIBFOO_POST_INSTALL_HOOKS+ (for host packages only)
 365 * +LIBFOO_POST_INSTALL_STAGING_HOOKS+ (for target packages only)
 366 * +LIBFOO_POST_INSTALL_TARGET_HOOKS+ (for target packages only)
 367 * +LIBFOO_POST_LEGAL_INFO_HOOKS+
 368
 369 These variables are 'lists' of variable names containing actions to be
 370 performed at this hook point. This allows several hooks to be
 371 registered at a given hook point. Here is an example:
 372
 373 ----------------------
 374 define LIBFOO_POST_PATCH_FIXUP
 375         action1
 376         action2
 377 endef
 378
 379 LIBFOO_POST_PATCH_HOOKS += LIBFOO_POST_PATCH_FIXUP
 380 ----------------------