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