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