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