2 // vim: set syntax=asciidoc:
4 === Infrastructure for packages with specific build systems
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.
11 [[generic-package-tutorial]]
13 ==== +generic-package+ tutorial
15 ------------------------------
16 01: ################################################################################
20 05: ################################################################################
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 = GPLv3+
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
31 16: define LIBFOO_BUILD_CMDS
32 17: $(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D) all
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
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
46 31: define LIBFOO_DEVICES
47 32: /dev/foo c 666 0 0 42 0 - - -
50 35: define LIBFOO_PERMISSIONS
51 36: /bin/foo f 4755 0 0 - - - - -
54 39: define LIBFOO_USERS
55 40: foo -1 libfoo -1 * - - - LibFoo daemon
58 43: $(eval $(generic-package))
59 --------------------------------
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).
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.
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.
85 The problem is that all these *-config files by default give wrong,
86 host system linking flags that are unsuitable for cross-compiling.
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'
91 So some sed magic is done to these scripts to make them give correct
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.
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.
100 .Config script: 'divine' package
101 ================================
102 Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'.
104 So its fixup would be:
106 --------------------------------
107 DIVINE_CONFIG_SCRIPTS = divine-config
108 --------------------------------
109 ================================
111 .Config script: 'imagemagick' package:
112 ================================
113 Package imagemagick installs the following scripts:
114 '$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config'
116 So it's fixup would be:
118 --------------------------------
119 IMAGEMAGICK_CONFIG_SCRIPTS = \
120 Magick-config Magick++-config \
121 MagickCore-config MagickWand-config Wand-config
122 --------------------------------
123 ================================
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.
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
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.
141 All these steps rely on the +$(@D)+ variable, which
142 contains the directory where the source code of the package has been
145 On line 31..33, we define a device-node file used by this package
148 On line 35..37, we define the permissions to set to specific files
149 installed by this package (+LIBFOO_PERMISSIONS+).
151 On lines 39..41, we define a user that is used by this package (e.g.
152 to run a daemon as non-root) (+LIBFOO_USERS+).
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.
158 [[generic-package-reference]]
160 ==== +generic-package+ reference
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:
169 ----------------------
170 $(eval $(generic-package))
171 $(eval $(host-generic-package))
172 ----------------------
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
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.
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
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+) :
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. +
203 +LIBFOO_VERSION = 0.1.2+ +
204 +LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057+ +
205 +LIBFOO_VERSION = stable+
207 * +LIBFOO_SOURCE+ may contain the name of the tarball of
208 the package. If +HOST_LIBFOO_SOURCE+ is not specified, it
209 defaults to +LIBFOO_SOURCE+. If none are specified, then
210 the value is assumed to be
211 +libfoo-$(LIBFOO_VERSION).tar.gz+. +
212 Example: +LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2+
214 * +LIBFOO_PATCH+ may contain a space-separated list of patch file
215 names, that will be downloaded from the same location as the tarball
216 indicated in +LIBFOO_SOURCE+, and then applied to the package source
217 code. If +HOST_LIBFOO_PATCH+ is not specified, it defaults to
218 +LIBFOO_PATCH+. Note that patches that are included in Buildroot
219 itself use a different mechanism: all files of the form
220 +<packagename>-*.patch+ present in the package directory inside
221 Buildroot will be applied to the package after extraction (see
222 xref:patch-policy[patching a package]). Finally, patches listed in
223 the +LIBFOO_PATCH+ variable are applied _before_ the patches stored
224 in the Buildroot package directory.
226 * +LIBFOO_SITE+ provides the location of the package, which can be a
227 URL or a local filesystem path. HTTP, FTP and SCP are supported URL
228 types for retrieving package tarballs. Git, Subversion, Mercurial,
229 and Bazaar are supported URL types for retrieving packages directly
230 from source code management systems. There is a helper function to make
231 it easier to download source tarballs from github (refer to
232 xref:github-download-url[] for details). A filesystem path may be used
233 to specify either a tarball or a directory containing the package
234 source code. See +LIBFOO_SITE_METHOD+ below for more details on how
236 Note that SCP URLs should be of the form
237 +scp://[user@]host:filepath+, and that filepath is relative to the
238 user's home directory, so you may want to prepend the path with a
239 slash for absolute paths:
240 +scp://[user@]host:/absolutepath+. +
241 If +HOST_LIBFOO_SITE+ is not specified, it defaults to
244 +LIBFOO_SITE=http://www.libfoosoftware.org/libfoo+ +
245 +LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor/+ +
246 +LIBFOO_SITE=/opt/software/libfoo.tar.gz+ +
247 +LIBFOO_SITE=$(TOPDIR)/../src/libfoo/+
249 * +LIBFOO_EXTRA_DOWNLOADS+ lists a number of additional files that
250 Buildroot should download from +LIBFOO_SITE+ in addition to the main
251 +LIBFOO_SOURCE+ (which usually is a tarball). Buildroot will not do
252 anything with those additional files, except download files: it will
253 be up to the package recipe to use them from +$(BR2_DL_DIR)+.
255 * +LIBFOO_SITE_METHOD+ determines the method used to fetch or copy the
256 package source code. In many cases, Buildroot guesses the method
257 from the contents of +LIBFOO_SITE+ and setting +LIBFOO_SITE_METHOD+
258 is unnecessary. When +HOST_LIBFOO_SITE_METHOD+ is not specified, it
259 defaults to the value of +LIBFOO_SITE_METHOD+. +
260 The possible values of +LIBFOO_SITE_METHOD+ are:
261 ** +wget+ for normal FTP/HTTP downloads of tarballs. Used by
262 default when +LIBFOO_SITE+ begins with +http://+, +https://+ or
264 ** +scp+ for downloads of tarballs over SSH with scp. Used by
265 default when +LIBFOO_SITE+ begins with +scp://+.
266 ** +svn+ for retrieving source code from a Subversion repository.
267 Used by default when +LIBFOO_SITE+ begins with +svn://+. When a
268 +http://+ Subversion repository URL is specified in
269 +LIBFOO_SITE+, one 'must' specify +LIBFOO_SITE_METHOD=svn+.
270 Buildroot performs a checkout which is preserved as a tarball in
271 the download cache; subsequent builds use the tarball instead of
272 performing another checkout.
273 ** +cvs+ for retrieving source code from a CVS repository.
274 Used by default when +LIBFOO_SITE+ begins with +cvs://+.
275 The downloaded source code is cached as with the +svn+ method.
276 Only anonymous pserver mode is supported.
277 +LIBFOO_SITE+ 'must' contain the source URL as well as the remote
278 repository directory. The module is the package name.
279 +LIBFOO_VERSION+ is 'mandatory' and 'must' be a timestamp.
280 ** +git+ for retrieving source code from a Git repository. Used by
281 default when +LIBFOO_SITE+ begins with +git://+. The downloaded
282 source code is cached as with the +svn+
284 ** +hg+ for retrieving source code from a Mercurial repository. One
285 'must' specify +LIBFOO_SITE_METHOD=hg+ when +LIBFOO_SITE+
286 contains a Mercurial repository URL. The downloaded source code
287 is cached as with the +svn+ method.
288 ** +bzr+ for retrieving source code from a Bazaar repository. Used
289 by default when +LIBFOO_SITE+ begins with +bzr://+. The
290 downloaded source code is cached as with the +svn+ method.
291 ** +file+ for a local tarball. One should use this when
292 +LIBFOO_SITE+ specifies a package tarball as a local filename.
293 Useful for software that isn't available publicly or in version
295 ** +local+ for a local source code directory. One should use this
296 when +LIBFOO_SITE+ specifies a local directory path containing
297 the package source code. Buildroot copies the contents of the
298 source directory into the package's build directory.
300 * +LIBFOO_DEPENDENCIES+ lists the dependencies (in terms of package
301 name) that are required for the current target package to
302 compile. These dependencies are guaranteed to be compiled and
303 installed before the configuration of the current package starts. In
304 a similar way, +HOST_LIBFOO_DEPENDENCIES+ lists the dependencies for
305 the current host package.
307 * +LIBFOO_PROVIDES+ lists all the virtual packages +libfoo+ is an
308 implementation of. See xref:virtual-package-tutorial[].
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 (e.g. 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_IMAGES_CMDS+ lists the actions to be performed to
417 install the package to the images directory, when the package is a
418 target package. The package must install its files to the directory
419 given by +$(BINARIES_DIR)+. Only files that are binary images (aka
420 images) that do not belong in the +TARGET_DIR+ but are necessary
421 for booting the board should be placed here. For example, a package
422 should utilize this step if it has binaries which would be similar
423 to the kernel image, bootloader or root filesystem images.
425 * +LIBFOO_INSTALL_INIT_SYSV+ and +LIBFOO_INSTALL_INIT_SYSTEMD+ list the
426 actions to install init scripts either for the systemV-like init systems
427 (busybox, sysvinit, etc.) or for the systemd units. These commands
428 will be run only when the relevant init system is installed (i.e. if
429 systemd is selected as the init system in the configuration, only
430 +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run).
432 The preferred way to define these variables is:
434 ----------------------
435 define LIBFOO_CONFIGURE_CMDS
440 ----------------------
442 In the action definitions, you can use the following variables:
444 * +$(@D)+, which contains the directory in which the package source
445 code has been uncompressed.
447 * +$(TARGET_CC)+, +$(TARGET_LD)+, etc. to get the target
448 cross-compilation utilities
450 * +$(TARGET_CROSS)+ to get the cross-compilation toolchain prefix
452 * Of course the +$(HOST_DIR)+, +$(STAGING_DIR)+ and +$(TARGET_DIR)+
453 variables to install the packages properly.
455 Finally, you can also use hooks. See xref:hooks[] for more information.