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