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