docs/manual/adding-packages-generic.txt

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