2 // vim: set syntax=asciidoc:
4 Infrastructure for packages with specific build systems
5 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
12 [[generic-package-tutorial]]
14 +generic-package+ Tutorial
15 ^^^^^^^^^^^^^^^^^^^^^^^^^^
17 ------------------------------
18 01: ################################################################################
22 05: ################################################################################
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
33 16: define LIBFOO_BUILD_CMDS
34 17: $(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D) all
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
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
48 31: define LIBFOO_DEVICES
49 32: /dev/foo c 666 0 0 42 0 - - -
52 35: define LIBFOO_PERMISSIONS
53 36: /bin/foo f 4755 0 0 - - - - -
56 39: define LIBFOO_USERS
57 40: foo -1 libfoo -1 * - - - LibFoo daemon
60 43: $(eval $(generic-package))
61 --------------------------------
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).
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.
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.
87 The problem is that all these *-config files by default give wrong,
88 host system linking flags that are unsuitable for cross-compiling.
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'
93 So some sed magic is done to these scripts to make them give correct
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.
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.
102 .Config script: 'divine' package
103 ================================
104 Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'.
106 So its fixup would be:
108 --------------------------------
109 DIVINE_CONFIG_SCRIPTS = divine-config
110 --------------------------------
111 ================================
113 .Config script: 'imagemagick' package:
114 ================================
115 Package imagemagick installs the following scripts:
116 '$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config'
118 So it's fixup would be:
120 --------------------------------
121 IMAGEMAGICK_CONFIG_SCRIPTS = \
122 Magick-config Magick++-config \
123 MagickCore-config MagickWand-config Wand-config
124 --------------------------------
125 ================================
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.
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
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.
143 All these steps rely on the +$(@D)+ variable, which
144 contains the directory where the source code of the package has been
147 On line 31..33, we define a device-node file used by this package
150 On line 35..37, we define the permissions to set to specific files
151 installed by this package (+LIBFOO_PERMISSIONS+).
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+).
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.
160 [[generic-package-reference]]
162 +generic-package+ Reference
163 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
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:
172 ----------------------
173 $(eval $(generic-package))
174 $(eval $(host-generic-package))
175 ----------------------
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
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.
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
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+) :
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. +
206 +LIBFOO_VERSION = 0.1.2+ +
207 +LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057+ +
208 +LIBFOO_VERSION = stable+
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+
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.
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. There is a helper function to make
234 it easier to download source tarballs from github (refer to
235 xref:github-download-url[] for details). A filesystem path may be used
236 to specify either a tarball or a directory containing the package
237 source code. See +LIBFOO_SITE_METHOD+ below for more details on how
239 Note that SCP URLs should be of the form
240 +scp://[user@]host:filepath+, and that filepath is relative to the
241 user's home directory, so you may want to prepend the path with a
242 slash for absolute paths:
243 +scp://[user@]host:/absolutepath+. +
244 If +HOST_LIBFOO_SITE+ is not specified, it defaults to
247 +LIBFOO_SITE=http://www.libfoosoftware.org/libfoo+ +
248 +LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor/+ +
249 +LIBFOO_SITE=/opt/software/libfoo.tar.gz+ +
250 +LIBFOO_SITE=$(TOPDIR)/../src/libfoo/+
252 * +LIBFOO_EXTRA_DOWNLOADS+ lists a number of additional files that
253 Buildroot should download from +LIBFOO_SITE+ in addition to the main
254 +LIBFOO_SOURCE+ (which usually is a tarball). Buildroot will not do
255 anything with those additional files, except download files: it will
256 be up to the package recipe to use them from +$(BR2_DL_DIR)+.
258 * +LIBFOO_SITE_METHOD+ determines the method used to fetch or copy the
259 package source code. In many cases, Buildroot guesses the method
260 from the contents of +LIBFOO_SITE+ and setting +LIBFOO_SITE_METHOD+
261 is unnecessary. When +HOST_LIBFOO_SITE_METHOD+ is not specified, it
262 defaults to the value of +LIBFOO_SITE_METHOD+. +
263 The possible values of +LIBFOO_SITE_METHOD+ are:
264 ** +wget+ for normal FTP/HTTP downloads of tarballs. Used by
265 default when +LIBFOO_SITE+ begins with +http://+, +https://+ or
267 ** +scp+ for downloads of tarballs over SSH with scp. Used by
268 default when +LIBFOO_SITE+ begins with +scp://+.
269 ** +svn+ for retrieving source code from a Subversion repository.
270 Used by default when +LIBFOO_SITE+ begins with +svn://+. When a
271 +http://+ Subversion repository URL is specified in
272 +LIBFOO_SITE+, one 'must' specify +LIBFOO_SITE_METHOD=svn+.
273 Buildroot performs a checkout which is preserved as a tarball in
274 the download cache; subsequent builds use the tarball instead of
275 performing another checkout.
276 ** +cvs+ for retrieving source code from a CVS repository.
277 Used by default when +LIBFOO_SITE+ begins with +cvs://+.
278 The downloaded source code is cached as with the +svn+ method.
279 Only anonymous pserver mode is supported.
280 +LIBFOO_SITE+ 'must' contain the source URL as well as the remote
281 repository directory. The module is the package name.
282 +LIBFOO_VERSION+ is 'mandatory' and 'must' be a timestamp.
283 ** +git+ for retrieving source code from a Git repository. Used by
284 default when +LIBFOO_SITE+ begins with +git://+. The downloaded
285 source code is cached as with the +svn+
287 ** +hg+ for retrieving source code from a Mercurial repository. One
288 'must' specify +LIBFOO_SITE_METHOD=hg+ when +LIBFOO_SITE+
289 contains a Mercurial repository URL. The downloaded source code
290 is cached as with the +svn+ method.
291 ** +bzr+ for retrieving source code from a Bazaar repository. Used
292 by default when +LIBFOO_SITE+ begins with +bzr://+. The
293 downloaded source code is cached as with the +svn+ method.
294 ** +file+ for a local tarball. One should use this when
295 +LIBFOO_SITE+ specifies a package tarball as a local filename.
296 Useful for software that isn't available publicly or in version
298 ** +local+ for a local source code directory. One should use this
299 when +LIBFOO_SITE+ specifies a local directory path containing
300 the package source code. Buildroot copies the contents of the
301 source directory into the package's build directory.
303 * +LIBFOO_DEPENDENCIES+ lists the dependencies (in terms of package
304 name) that are required for the current target package to
305 compile. These dependencies are guaranteed to be compiled and
306 installed before the configuration of the current package starts. In
307 a similar way, +HOST_LIBFOO_DEPENDENCIES+ lists the dependencies for
308 the current host package.
310 * +LIBFOO_INSTALL_STAGING+ can be set to +YES+ or +NO+ (default). If
311 set to +YES+, then the commands in the +LIBFOO_INSTALL_STAGING_CMDS+
312 variables are executed to install the package into the staging
315 * +LIBFOO_INSTALL_TARGET+ can be set to +YES+ (default) or +NO+. If
316 set to +YES+, then the commands in the +LIBFOO_INSTALL_TARGET_CMDS+
317 variables are executed to install the package into the target
320 * +LIBFOO_CONFIG_SCRIPTS+ lists the names of the files in
321 '$(STAGING_DIR)/usr/bin' that need some special fixing to make them
322 cross-compiling friendly. Multiple file names separated by space can
323 be given and all are relative to '$(STAGING_DIR)/usr/bin'. The files
324 listed in +LIBFOO_CONFIG_SCRIPTS+ are also removed from
325 +$(TARGET_DIR)/usr/bin+ since they are not needed on the target.
327 * +LIBFOO_DEVICES+ lists the device files to be created by Buildroot
328 when using the static device table. The syntax to use is the
329 makedevs one. You can find some documentation for this syntax in the
330 xref:makedev-syntax[]. This variable is optional.
332 * +LIBFOO_PERMISSIONS+ lists the changes of permissions to be done at
333 the end of the build process. The syntax is once again the makedevs one.
334 You can find some documentation for this syntax in the xref:makedev-syntax[].
335 This variable is optional.
337 * +LIBFOO_USERS+ lists the users to create for this package, if it installs
338 a program you want to run as a specific user (eg. as a daemon, or as a
339 cron-job). The syntax is similar in spirit to the makedevs one, and is
340 described in the xref:makeuser-syntax[]. This variable is optional.
342 * +LIBFOO_LICENSE+ defines the license (or licenses) under which the package
344 This name will appear in the manifest file produced by +make legal-info+.
345 If the license appears in xref:legal-info-list-licenses[the following list],
346 use the same string to make the manifest file uniform.
347 Otherwise, describe the license in a precise and concise way, avoiding
348 ambiguous names such as +BSD+ which actually name a family of licenses.
349 This variable is optional. If it is not defined, +unknown+ will appear in
350 the +license+ field of the manifest file for this package.
352 * +LIBFOO_LICENSE_FILES+ is a space-separated list of files in the package
353 tarball that contain the license(s) under which the package is released.
354 +make legal-info+ copies all of these files in the +legal-info+ directory.
355 See xref:legal-info[] for more information.
356 This variable is optional. If it is not defined, a warning will be produced
357 to let you know, and +not saved+ will appear in the +license files+ field
358 of the manifest file for this package.
360 * +LIBFOO_REDISTRIBUTE+ can be set to +YES+ (default) or +NO+ to indicate if
361 the package source code is allowed to be redistributed. Set it to +NO+ for
362 non-opensource packages: Buildroot will not save the source code for this
363 package when collecting the +legal-info+.
365 * +LIBFOO_FLAT_STACKSIZE+ defines the stack size of an application built into
366 the FLAT binary format. The application stack size on the NOMMU architecture
367 processors can't be enlarged at run time. The default stack size for the
368 FLAT binary format is only 4k bytes. If the application consumes more stack,
369 append the required number here.
371 The recommended way to define these variables is to use the following
374 ----------------------
375 LIBFOO_VERSION = 2.32
376 ----------------------
378 Now, the variables that define what should be performed at the
379 different steps of the build process.
381 * +LIBFOO_EXTRACT_CMDS+ lists the actions to be performed to extract
382 the package. This is generally not needed as tarballs are
383 automatically handled by Buildroot. However, if the package uses a
384 non-standard archive format, such as a ZIP or RAR file, or has a
385 tarball with a non-standard organization, this variable allows to
386 override the package infrastructure default behavior.
388 * +LIBFOO_CONFIGURE_CMDS+ lists the actions to be performed to
389 configure the package before its compilation.
391 * +LIBFOO_BUILD_CMDS+ lists the actions to be performed to
394 * +HOST_LIBFOO_INSTALL_CMDS+ lists the actions to be performed
395 to install the package, when the package is a host package. The
396 package must install its files to the directory given by
397 +$(HOST_DIR)+. All files, including development files such as
398 headers should be installed, since other packages might be compiled
399 on top of this package.
401 * +LIBFOO_INSTALL_TARGET_CMDS+ lists the actions to be
402 performed to install the package to the target directory, when the
403 package is a target package. The package must install its files to
404 the directory given by +$(TARGET_DIR)+. Only the files required for
405 'execution' of the package have to be
406 installed. Header files, static libraries and documentation will be
407 removed again when the target filesystem is finalized.
409 * +LIBFOO_INSTALL_STAGING_CMDS+ lists the actions to be
410 performed to install the package to the staging directory, when the
411 package is a target package. The package must install its files to
412 the directory given by +$(STAGING_DIR)+. All development files
413 should be installed, since they might be needed to compile other
416 * +LIBFOO_INSTALL_INIT_SYSV+ and +LIBFOO_INSTALL_INIT_SYSTEMD+ list the
417 actions to install init scripts either for the systemV-like init systems
418 (busybox, sysvinit, etc.) or for the systemd units. These commands
419 will be run only when the relevant init system is installed (i.e. if
420 systemd is selected as the init system in the configuration, only
421 +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run).
423 The preferred way to define these variables is:
425 ----------------------
426 define LIBFOO_CONFIGURE_CMDS
431 ----------------------
433 In the action definitions, you can use the following variables:
435 * +$(@D)+, which contains the directory in which the package source
436 code has been uncompressed.
438 * +$(TARGET_CC)+, +$(TARGET_LD)+, etc. to get the target
439 cross-compilation utilities
441 * +$(TARGET_CROSS)+ to get the cross-compilation toolchain prefix
443 * Of course the +$(HOST_DIR)+, +$(STAGING_DIR)+ and +$(TARGET_DIR)+
444 variables to install the packages properly.
446 Finally, you can also use hooks. See xref:hooks[] for more information.