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 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 01: ################################################################################
  17 02: #
  18 03: # libfoo
  19 04: #
  20 05: ################################################################################
  21 06:
  22 07: LIBFOO_VERSION = 1.0
  23 08: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
  24 09: LIBFOO_SITE = http://www.foosoftware.org/download
  25 10: LIBFOO_LICENSE = GPL-3.0+
  26 11: LIBFOO_LICENSE_FILES = COPYING
  27 12: LIBFOO_INSTALL_STAGING = YES
  28 13: LIBFOO_CONFIG_SCRIPTS = libfoo-config
  29 14: LIBFOO_DEPENDENCIES = host-libaaa libbbb
  30 15:
  31 16: define LIBFOO_BUILD_CMDS
  32 17:     $(MAKE) $(TARGET_CONFIGURE_OPTS) -C $(@D) all
  33 18: endef
  34 19:
  35 20: define LIBFOO_INSTALL_STAGING_CMDS
  36 21:     $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a
  37 22:     $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h
  38 23:     $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib
  39 24: endef
  40 25:
  41 26: define LIBFOO_INSTALL_TARGET_CMDS
  42 27:     $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib
  43 28:     $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d
  44 29: endef
  45 30:
  46 31: define LIBFOO_USERS
  47 32:     foo -1 libfoo -1 * - - - LibFoo daemon
  48 33: endef
  49 34:
  50 35: define LIBFOO_DEVICES
  51 36:     /dev/foo  c  666  0  0  42  0  -  -  -
  52 37: endef
  53 38:
  54 39: define LIBFOO_PERMISSIONS
  55 40:     /bin/foo  f  4755  foo  libfoo   -  -  -  -  -
  56 41: endef
  57 42:
  58 43: $(eval $(generic-package))
  59 --------------------------------
  60
  61 The Makefile begins on line 7 to 11 with metadata information: the
  62 version of the package (+LIBFOO_VERSION+), the name of the
  63 tarball containing the package (+LIBFOO_SOURCE+) (xz-ed tarball recommended)
  64 the Internet location at which the tarball can be downloaded from
  65 (+LIBFOO_SITE+), the license (+LIBFOO_LICENSE+) and file with the
  66 license text (+LIBFOO_LICENSE_FILES+). All variables must start with
  67 the same prefix, +LIBFOO_+ in this case. This prefix is always the
  68 uppercased version of the package name (see below to understand where
  69 the package name is defined).
  70
  71 On line 12, we specify that this package wants to install something to
  72 the staging space. This is often needed for libraries, since they must
  73 install header files and other development files in the staging space.
  74 This will ensure that the commands listed in the
  75 +LIBFOO_INSTALL_STAGING_CMDS+ variable will be executed.
  76
  77 On line 13, we specify that there is some fixing to be done to some
  78 of the 'libfoo-config' files that were installed during
  79 +LIBFOO_INSTALL_STAGING_CMDS+ phase.
  80 These *-config files are executable shell script files that are
  81 located in '$(STAGING_DIR)/usr/bin' directory and are executed
  82 by other 3rd party packages to find out the location and the linking
  83 flags of this particular package.
  84
  85 The problem is that all these *-config files by default give wrong,
  86 host system linking flags that are unsuitable for cross-compiling.
  87
  88 For example:    '-I/usr/include' instead of '-I$(STAGING_DIR)/usr/include'
  89 or:             '-L/usr/lib' instead of '-L$(STAGING_DIR)/usr/lib'
  90
  91 So some sed magic is done to these scripts to make them give correct
  92 flags.
  93 The argument to be given to +LIBFOO_CONFIG_SCRIPTS+ is the file name(s)
  94 of the shell script(s) needing fixing. All these names are relative to
  95 '$(STAGING_DIR)/usr/bin' and if needed multiple names can be given.
  96
  97 In addition, the scripts listed in +LIBFOO_CONFIG_SCRIPTS+ are removed
  98 from +$(TARGET_DIR)/usr/bin+, since they are not needed on the target.
  99
 100 .Config script: 'divine' package
 101 ================================
 102 Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'.
 103
 104 So its fixup would be:
 105
 106 --------------------------------
 107 DIVINE_CONFIG_SCRIPTS = divine-config
 108 --------------------------------
 109 ================================
 110
 111 .Config script: 'imagemagick' package:
 112 ================================
 113 Package imagemagick installs the following scripts:
 114 '$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config'
 115
 116 So it's fixup would be:
 117
 118 --------------------------------
 119 IMAGEMAGICK_CONFIG_SCRIPTS = \
 120    Magick-config Magick++-config \
 121    MagickCore-config MagickWand-config Wand-config
 122 --------------------------------
 123 ================================
 124
 125 On line 14, we specify the list of dependencies this package relies
 126 on. These dependencies are listed in terms of lower-case package names,
 127 which can be packages for the target (without the +host-+
 128 prefix) or packages for the host (with the +host-+) prefix).
 129 Buildroot will ensure that all these packages are built and installed
 130 'before' the current package starts its configuration.
 131
 132 The rest of the Makefile, lines 16..29, defines what should be done
 133 at the different steps of the package configuration, compilation and
 134 installation.
 135 +LIBFOO_BUILD_CMDS+ tells what steps should be performed to
 136 build the package. +LIBFOO_INSTALL_STAGING_CMDS+ tells what
 137 steps should be performed to install the package in the staging space.
 138 +LIBFOO_INSTALL_TARGET_CMDS+ tells what steps should be
 139 performed to install the package in the target space.
 140
 141 All these steps rely on the +$(@D)+ variable, which
 142 contains the directory where the source code of the package has been
 143 extracted.
 144
 145 On lines 31..43, we define a user that is used by this package (e.g.
 146 to run a daemon as non-root) (+LIBFOO_USERS+).
 147
 148 On line 35..37, we define a device-node file used by this package
 149 (+LIBFOO_DEVICES+).
 150
 151 On line 39..41, we define the permissions to set to specific files
 152 installed by this package (+LIBFOO_PERMISSIONS+).
 153
 154 Finally, on line 43, we call the +generic-package+ function, which
 155 generates, according to the variables defined previously, all the
 156 Makefile code necessary to make your package working.
 157
 158 [[generic-package-reference]]
 159
 160 ==== +generic-package+ reference
 161
 162 There are two variants of the generic target. The +generic-package+ macro is
 163 used for packages to be cross-compiled for the target. The
 164 +host-generic-package+ macro is used for host packages, natively compiled
 165 for the host. It is possible to call both of them in a single +.mk+
 166 file: once to create the rules to generate a target
 167 package and once to create the rules to generate a host package:
 168
 169 ----------------------
 170 $(eval $(generic-package))
 171 $(eval $(host-generic-package))
 172 ----------------------
 173
 174 This might be useful if the compilation of the target package requires
 175 some tools to be installed on the host. If the package name is
 176 +libfoo+, then the name of the package for the target is also
 177 +libfoo+, while the name of the package for the host is
 178 +host-libfoo+. These names should be used in the DEPENDENCIES
 179 variables of other packages, if they depend on +libfoo+ or
 180 +host-libfoo+.
 181
 182 The call to the +generic-package+ and/or +host-generic-package+ macro *must* be
 183 at the end of the +.mk+ file, after all variable definitions.
 184
 185 For the target package, the +generic-package+ uses the variables defined by
 186 the .mk file and prefixed by the uppercased package name:
 187 +LIBFOO_*+. +host-generic-package+ uses the +HOST_LIBFOO_*+ variables. For
 188 'some' variables, if the +HOST_LIBFOO_+ prefixed variable doesn't
 189 exist, the package infrastructure uses the corresponding variable
 190 prefixed by +LIBFOO_+. This is done for variables that are likely to
 191 have the same value for both the target and host packages. See below
 192 for details.
 193
 194 The list of variables that can be set in a +.mk+ file to give metadata
 195 information is (assuming the package name is +libfoo+) :
 196
 197 * +LIBFOO_VERSION+, mandatory, must contain the version of the
 198   package. Note that if +HOST_LIBFOO_VERSION+ doesn't exist, it is
 199   assumed to be the same as +LIBFOO_VERSION+. It can also be a
 200   revision number, branch or tag for packages that are fetched
 201   directly from their revision control system. +
 202   Examples: +
 203     +LIBFOO_VERSION = 0.1.2+ +
 204     +LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057+ +
 205     +LIBFOO_VERSION = stable+
 206
 207 * +LIBFOO_SOURCE+ may contain the name of the tarball of the package,
 208   which Buildroot will use to download the tarball from
 209   +LIBFOO_SITE+. If +HOST_LIBFOO_SOURCE+ is not specified, it defaults
 210   to +LIBFOO_SOURCE+. If none are specified, then the value is assumed
 211   to be +libfoo-$(LIBFOO_VERSION).tar.gz+. +
 212   Example: +LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2+
 213
 214 * +LIBFOO_PATCH+ may contain a space-separated list of patch file
 215   names, that Buildroot will download and apply to the package source
 216   code. If an entry contains +://+, then Buildroot will assume it is a
 217   full URL and download the patch from this location. Otherwise,
 218   Buildroot will assume that the patch should be downloaded from
 219   +LIBFOO_SITE+. If +HOST_LIBFOO_PATCH+ is not specified, it defaults
 220   to +LIBFOO_PATCH+. Note that patches that are included in Buildroot
 221   itself use a different mechanism: all files of the form
 222   +*.patch+ present in the package directory inside
 223   Buildroot will be applied to the package after extraction (see
 224   xref:patch-policy[patching a package]). Finally, patches listed in
 225   the +LIBFOO_PATCH+ variable are applied _before_ the patches stored
 226   in the Buildroot package directory.
 227
 228 * +LIBFOO_SITE+ provides the location of the package, which can be a
 229   URL or a local filesystem path. HTTP, FTP and SCP are supported URL
 230   types for retrieving package tarballs. In these cases don't include a
 231   trailing slash: it will be added by Buildroot between the directory
 232   and the filename as appropriate. Git, Subversion, Mercurial,
 233   and Bazaar are supported URL types for retrieving packages directly
 234   from source code management systems. There is a helper function to make
 235   it easier to download source tarballs from GitHub (refer to
 236   xref:github-download-url[] for details). A filesystem path may be used
 237   to specify either a tarball or a directory containing the package
 238   source code. See +LIBFOO_SITE_METHOD+ below for more details on how
 239   retrieval works. +
 240   Note that SCP URLs should be of the form
 241   +scp://[user@]host:filepath+, and that filepath is relative to the
 242   user's home directory, so you may want to prepend the path with a
 243   slash for absolute paths:
 244   +scp://[user@]host:/absolutepath+. +
 245   If +HOST_LIBFOO_SITE+ is not specified, it defaults to
 246   +LIBFOO_SITE+.
 247   Examples: +
 248     +LIBFOO_SITE=http://www.libfoosoftware.org/libfoo+ +
 249     +LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor+ +
 250     +LIBFOO_SITE=/opt/software/libfoo.tar.gz+ +
 251     +LIBFOO_SITE=$(TOPDIR)/../src/libfoo+
 252
 253 * +LIBFOO_DL_OPTS+ is a space-separated list of additional options to
 254   pass to the downloader. Useful for retrieving documents with
 255   server-side checking for user logins and passwords, or to use a proxy.
 256   All download methods valid for +LIBFOO_SITE_METHOD+ are supported;
 257   valid options depend on the download method (consult the man page
 258   for the respective download utilities).
 259
 260 * +LIBFOO_EXTRA_DOWNLOADS+ is a space-separated list of additional
 261   files that Buildroot should download. If an entry contains +://+
 262   then Buildroot will assume it is a complete URL and will download
 263   the file using this URL. Otherwise, Buildroot will assume the file
 264   to be downloaded is located at +LIBFOO_SITE+. Buildroot will not do
 265   anything with those additional files, except download them: it will
 266   be up to the package recipe to use them from +$(DL_DIR)+.
 267
 268 * +LIBFOO_SITE_METHOD+ determines the method used to fetch or copy the
 269   package source code. In many cases, Buildroot guesses the method
 270   from the contents of +LIBFOO_SITE+ and setting +LIBFOO_SITE_METHOD+
 271   is unnecessary. When +HOST_LIBFOO_SITE_METHOD+ is not specified, it
 272   defaults to the value of +LIBFOO_SITE_METHOD+. +
 273   The possible values of +LIBFOO_SITE_METHOD+ are:
 274   ** +wget+ for normal FTP/HTTP downloads of tarballs. Used by
 275      default when +LIBFOO_SITE+ begins with +http://+, +https://+ or
 276      +ftp://+.
 277   ** +scp+ for downloads of tarballs over SSH with scp. Used by
 278      default when +LIBFOO_SITE+ begins with +scp://+.
 279   ** +svn+ for retrieving source code from a Subversion repository.
 280      Used by default when +LIBFOO_SITE+ begins with +svn://+. When a
 281      +http://+ Subversion repository URL is specified in
 282      +LIBFOO_SITE+, one 'must' specify +LIBFOO_SITE_METHOD=svn+.
 283      Buildroot performs a checkout which is preserved as a tarball in
 284      the download cache; subsequent builds use the tarball instead of
 285      performing another checkout.
 286   ** +cvs+ for retrieving source code from a CVS repository.
 287      Used by default when +LIBFOO_SITE+ begins with +cvs://+.
 288      The downloaded source code is cached as with the +svn+ method.
 289      Anonymous pserver mode is assumed otherwise explicitly defined
 290      on +LIBFOO_SITE+. Both
 291      +LIBFOO_SITE=cvs://libfoo.net:/cvsroot/libfoo+ and
 292      +LIBFOO_SITE=cvs://:ext:libfoo.net:/cvsroot/libfoo+
 293      are accepted, on the former anonymous pserver access mode is
 294      assumed.
 295      +LIBFOO_SITE+ 'must' contain the source URL as well as the remote
 296      repository directory. The module is the package name.
 297      +LIBFOO_VERSION+ is 'mandatory' and 'must' be a tag, a branch, or
 298      a date (e.g. "2014-10-20", "2014-10-20 13:45", "2014-10-20
 299      13:45+01" see "man cvs" for further details).
 300   ** +git+ for retrieving source code from a Git repository. Used by
 301      default when +LIBFOO_SITE+ begins with +git://+. The downloaded
 302      source code is cached as with the +svn+
 303      method.
 304   ** +hg+ for retrieving source code from a Mercurial repository. One
 305      'must' specify +LIBFOO_SITE_METHOD=hg+ when +LIBFOO_SITE+
 306      contains a Mercurial repository URL. The downloaded source code
 307      is cached as with the +svn+ method.
 308   ** +bzr+ for retrieving source code from a Bazaar repository. Used
 309      by default when +LIBFOO_SITE+ begins with +bzr://+. The
 310      downloaded source code is cached as with the +svn+ method.
 311   ** +file+ for a local tarball. One should use this when
 312      +LIBFOO_SITE+ specifies a package tarball as a local filename.
 313      Useful for software that isn't available publicly or in version
 314      control.
 315   ** +local+ for a local source code directory. One should use this
 316      when +LIBFOO_SITE+ specifies a local directory path containing
 317      the package source code. Buildroot copies the contents of the
 318      source directory into the package's build directory. Note that
 319      for +local+ packages, no patches are applied. If you need to
 320      still patch the source code, use +LIBFOO_POST_RSYNC_HOOKS+, see
 321      xref:hooks-rsync[].
 322
 323 * +LIBFOO_GIT_SUBMODULES+ can be set to +YES+ to create an archive
 324   with the git submodules in the repository.  This is only available
 325   for packages downloaded with git (i.e. when
 326   +LIBFOO_SITE_METHOD=git+).  Note that we try not to use such git
 327   submodules when they contain bundled libraries, in which case we
 328   prefer to use those libraries from their own package.
 329
 330 * +LIBFOO_STRIP_COMPONENTS+ is the number of leading components
 331   (directories) that tar must strip from file names on extraction.
 332   The tarball for most packages has one leading component named
 333   "<pkg-name>-<pkg-version>", thus Buildroot passes
 334   --strip-components=1 to tar to remove it.
 335   For non-standard packages that don't have this component, or
 336   that have more than one leading component to strip, set this
 337   variable with the value to be passed to tar. Default: 1.
 338
 339 * +LIBFOO_EXCLUDES+ is a space-separated list of patterns to exclude
 340   when extracting the archive. Each item from that list is passed as
 341   a tar's +--exclude+ option. By default, empty.
 342
 343 * +LIBFOO_DEPENDENCIES+ lists the dependencies (in terms of package
 344   name) that are required for the current target package to
 345   compile. These dependencies are guaranteed to be compiled and
 346   installed before the configuration of the current package starts. In
 347   a similar way, +HOST_LIBFOO_DEPENDENCIES+ lists the dependencies for
 348   the current host package.
 349
 350 * +LIBFOO_PATCH_DEPENDENCIES+ lists the dependencies (in terms of
 351   package name) that are required for the current package to be
 352   patched. These dependencies are guaranteed to be extracted and
 353   patched before the current package is patched. In a similar way,
 354   +HOST_LIBFOO_PATCH_DEPENDENCIES+ lists the dependencies for the
 355   current host package.
 356   This is seldom used; usually, +LIBFOO_DEPENDENCIES+ is what you
 357   really want to use.
 358
 359 * +LIBFOO_PROVIDES+ lists all the virtual packages +libfoo+ is an
 360   implementation of. See xref:virtual-package-tutorial[].
 361
 362 * +LIBFOO_INSTALL_STAGING+ can be set to +YES+ or +NO+ (default). If
 363   set to +YES+, then the commands in the +LIBFOO_INSTALL_STAGING_CMDS+
 364   variables are executed to install the package into the staging
 365   directory.
 366
 367 * +LIBFOO_INSTALL_TARGET+ can be set to +YES+ (default) or +NO+. If
 368   set to +YES+, then the commands in the +LIBFOO_INSTALL_TARGET_CMDS+
 369   variables are executed to install the package into the target
 370   directory.
 371
 372 * +LIBFOO_INSTALL_IMAGES+ can be set to +YES+ or +NO+ (default). If
 373   set to +YES+, then the commands in the +LIBFOO_INSTALL_IMAGES_CMDS+
 374   variable are executed to install the package into the images
 375   directory.
 376
 377 * +LIBFOO_CONFIG_SCRIPTS+ lists the names of the files in
 378   '$(STAGING_DIR)/usr/bin' that need some special fixing to make them
 379   cross-compiling friendly. Multiple file names separated by space can
 380   be given and all are relative to '$(STAGING_DIR)/usr/bin'. The files
 381   listed in +LIBFOO_CONFIG_SCRIPTS+ are also removed from
 382   +$(TARGET_DIR)/usr/bin+ since they are not needed on the target.
 383
 384 * +LIBFOO_DEVICES+ lists the device files to be created by Buildroot
 385   when using the static device table. The syntax to use is the
 386   makedevs one. You can find some documentation for this syntax in the
 387   xref:makedev-syntax[]. This variable is optional.
 388
 389 * +LIBFOO_PERMISSIONS+ lists the changes of permissions to be done at
 390   the end of the build process. The syntax is once again the makedevs one.
 391   You can find some documentation for this syntax in the xref:makedev-syntax[].
 392   This variable is optional.
 393
 394 * +LIBFOO_USERS+ lists the users to create for this package, if it installs
 395   a program you want to run as a specific user (e.g. as a daemon, or as a
 396   cron-job). The syntax is similar in spirit to the makedevs one, and is
 397   described in the xref:makeuser-syntax[]. This variable is optional.
 398
 399 * +LIBFOO_LICENSE+ defines the license (or licenses) under which the package
 400   is released.
 401   This name will appear in the manifest file produced by +make legal-info+.
 402   If the license appears in https://spdx.org/licenses/[the SPDX License List],
 403   use the SPDX short identifier to make the manifest file uniform.
 404   Otherwise, describe the license in a precise and concise way, avoiding
 405   ambiguous names such as +BSD+ which actually name a family of licenses.
 406   This variable is optional. If it is not defined, +unknown+ will appear in
 407   the +license+ field of the manifest file for this package. +
 408   The expected format for this variable must comply with the following rules:
 409   ** If different parts of the package are released under different
 410   licenses, then +comma+ separate licenses (e.g. +`LIBFOO_LICENSE =
 411   GPL-2.0+, LGPL-2.1+`+). If there is clear distinction between which
 412   component is licensed under what license, then annotate the license
 413   with that component, between parenthesis (e.g. +`LIBFOO_LICENSE =
 414   GPL-2.0+ (programs), LGPL-2.1+ (libraries)`+).
 415   ** If the package is dual licensed, then separate licenses with the
 416   +or+ keyword (e.g. +`LIBFOO_LICENSE = AFL-2.1 or GPL-2.0+`+).
 417
 418 * +LIBFOO_LICENSE_FILES+ is a space-separated list of files in the package
 419   tarball that contain the license(s) under which the package is released.
 420   +make legal-info+ copies all of these files in the +legal-info+ directory.
 421   See xref:legal-info[] for more information.
 422   This variable is optional. If it is not defined, a warning will be produced
 423   to let you know, and +not saved+ will appear in the +license files+ field
 424   of the manifest file for this package.
 425
 426 * +LIBFOO_ACTUAL_SOURCE_TARBALL+ only applies to packages whose
 427   +LIBFOO_SITE+ / +LIBTOO_SOURCE+ pair points to an archive that does
 428   not actually contain source code, but binary code. This a very
 429   uncommon case, only known to apply to external toolchains which come
 430   already compiled, although theoretically it might apply to other
 431   packages. In such cases a separate tarball is usually available with
 432   the actual source code. Set +LIBFOO_ACTUAL_SOURCE_TARBALL+ to the
 433   name of the actual source code archive and Buildroot will download
 434   it and use it when you run +make legal-info+ to collect
 435   legally-relevant material.  Note this file will not be downloaded
 436   during regular builds nor by +make source+.
 437
 438 * +LIBFOO_ACTUAL_SOURCE_SITE+ provides the location of the actual
 439   source tarball. The default value is +LIBFOO_SITE+, so you don't
 440   need to set this variable if the binary and source archives are
 441   hosted on the same directory.  If +LIBFOO_ACTUAL_SOURCE_TARBALL+ is
 442   not set, it doesn't make sense to define
 443   +LIBFOO_ACTUAL_SOURCE_SITE+.
 444
 445 * +LIBFOO_REDISTRIBUTE+ can be set to +YES+ (default) or +NO+ to indicate if
 446   the package source code is allowed to be redistributed. Set it to +NO+ for
 447   non-opensource packages: Buildroot will not save the source code for this
 448   package when collecting the +legal-info+.
 449
 450 * +LIBFOO_FLAT_STACKSIZE+ defines the stack size of an application built into
 451   the FLAT binary format. The application stack size on the NOMMU architecture
 452   processors can't be enlarged at run time. The default stack size for the
 453   FLAT binary format is only 4k bytes. If the application consumes more stack,
 454   append the required number here.
 455
 456 * +LIBFOO_BIN_ARCH_EXCLUDE+ is a space-separated list of paths (relative
 457   to the target directory) to ignore when checking that the package
 458   installs correctly cross-compiled binaries. You seldom need to set this
 459   variable, unless the package installs binary blobs outside the default
 460   locations, `/lib/firmware`, `/usr/lib/firmware`, `/lib/modules`,
 461   `/usr/lib/modules`, and `/usr/share`, which are automatically excluded.
 462
 463 The recommended way to define these variables is to use the following
 464 syntax:
 465
 466 ----------------------
 467 LIBFOO_VERSION = 2.32
 468 ----------------------
 469
 470 Now, the variables that define what should be performed at the
 471 different steps of the build process.
 472
 473 * +LIBFOO_EXTRACT_CMDS+ lists the actions to be performed to extract
 474   the package. This is generally not needed as tarballs are
 475   automatically handled by Buildroot. However, if the package uses a
 476   non-standard archive format, such as a ZIP or RAR file, or has a
 477   tarball with a non-standard organization, this variable allows to
 478   override the package infrastructure default behavior.
 479
 480 * +LIBFOO_CONFIGURE_CMDS+ lists the actions to be performed to
 481   configure the package before its compilation.
 482
 483 * +LIBFOO_BUILD_CMDS+ lists the actions to be performed to
 484   compile the package.
 485
 486 * +HOST_LIBFOO_INSTALL_CMDS+ lists the actions to be performed
 487   to install the package, when the package is a host package. The
 488   package must install its files to the directory given by
 489   +$(HOST_DIR)+. All files, including development files such as
 490   headers should be installed, since other packages might be compiled
 491   on top of this package.
 492
 493 * +LIBFOO_INSTALL_TARGET_CMDS+ lists the actions to be
 494   performed to install the package to the target directory, when the
 495   package is a target package. The package must install its files to
 496   the directory given by +$(TARGET_DIR)+. Only the files required for
 497   'execution' of the package have to be
 498   installed. Header files, static libraries and documentation will be
 499   removed again when the target filesystem is finalized.
 500
 501 * +LIBFOO_INSTALL_STAGING_CMDS+ lists the actions to be
 502   performed to install the package to the staging directory, when the
 503   package is a target package. The package must install its files to
 504   the directory given by +$(STAGING_DIR)+. All development files
 505   should be installed, since they might be needed to compile other
 506   packages.
 507
 508 * +LIBFOO_INSTALL_IMAGES_CMDS+ lists the actions to be performed to
 509   install the package to the images directory, when the package is a
 510   target package. The package must install its files to the directory
 511   given by +$(BINARIES_DIR)+. Only files that are binary images (aka
 512   images) that do not belong in the +TARGET_DIR+ but are necessary
 513   for booting the board should be placed here. For example, a package
 514   should utilize this step if it has binaries which would be similar
 515   to the kernel image, bootloader or root filesystem images.
 516
 517 * +LIBFOO_INSTALL_INIT_SYSV+ and +LIBFOO_INSTALL_INIT_SYSTEMD+ list the
 518   actions to install init scripts either for the systemV-like init systems
 519   (busybox, sysvinit, etc.) or for the systemd units. These commands
 520   will be run only when the relevant init system is installed (i.e. if
 521   systemd is selected as the init system in the configuration, only
 522   +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run).
 523
 524 * +LIBFOO_HELP_CMDS+ lists the actions to print the package help, which
 525   is included to the main +make help+ output. These commands can print
 526   anything in any format.
 527   This is seldom used, as packages rarely have custom rules. *Do not use
 528   this variable*, unless you really know that you need to print help.
 529
 530 The preferred way to define these variables is:
 531
 532 ----------------------
 533 define LIBFOO_CONFIGURE_CMDS
 534         action 1
 535         action 2
 536         action 3
 537 endef
 538 ----------------------
 539
 540 In the action definitions, you can use the following variables:
 541
 542 * +$(LIBFOO_PKGDIR)+ contains the path to the directory containing the
 543   +libfoo.mk+ and +Config.in+ files. This variable is useful when it is
 544   necessary to install a file bundled in Buildroot, like a runtime
 545   configuration file, a splashscreen image...
 546
 547 * +$(@D)+, which contains the directory in which the package source
 548   code has been uncompressed.
 549
 550 * +$(DL_DIR)+ contains the path to the directory where all the downloads made
 551   by Buildroot are stored.
 552
 553 * +$(TARGET_CC)+, +$(TARGET_LD)+, etc. to get the target
 554   cross-compilation utilities
 555
 556 * +$(TARGET_CROSS)+ to get the cross-compilation toolchain prefix
 557
 558 * Of course the +$(HOST_DIR)+, +$(STAGING_DIR)+ and +$(TARGET_DIR)+
 559   variables to install the packages properly.
 560
 561 Finally, you can also use hooks. See xref:hooks[] for more information.