docs/manual/adding-packages-generic.txt

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