1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc: 3 4=== Infrastructure for packages with specific build systems 5 6By 'packages with specific build systems' we mean all the packages 7whose build system is not one of the standard ones, such as 8'autotools' or 'CMake'. This typically includes packages whose build 9system is based on hand-written Makefiles or shell scripts. 10 11[[generic-package-tutorial]] 12 13==== +generic-package+ tutorial 14 15------------------------------ 1601: ################################################################################ 1702: # 1803: # libfoo 1904: # 2005: ################################################################################ 2106: 2207: LIBFOO_VERSION = 1.0 2308: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz 2409: LIBFOO_SITE = http://www.foosoftware.org/download 2510: LIBFOO_LICENSE = GPL-3.0+ 2611: LIBFOO_LICENSE_FILES = COPYING 2712: LIBFOO_INSTALL_STAGING = YES 2813: LIBFOO_CONFIG_SCRIPTS = libfoo-config 2914: LIBFOO_DEPENDENCIES = host-libaaa libbbb 3015: 3116: define LIBFOO_BUILD_CMDS 3217: $(MAKE) $(TARGET_CONFIGURE_OPTS) -C $(@D) all 3318: endef 3419: 3520: define LIBFOO_INSTALL_STAGING_CMDS 3621: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a 3722: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h 3823: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib 3924: endef 4025: 4126: define LIBFOO_INSTALL_TARGET_CMDS 4227: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib 4328: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d 4429: endef 4530: 4631: define LIBFOO_USERS 4732: foo -1 libfoo -1 * - - - LibFoo daemon 4833: endef 4934: 5035: define LIBFOO_DEVICES 5136: /dev/foo c 666 0 0 42 0 - - - 5237: endef 5338: 5439: define LIBFOO_PERMISSIONS 5540: /bin/foo f 4755 foo libfoo - - - - - 5641: endef 5742: 5843: $(eval $(generic-package)) 59-------------------------------- 60 61The Makefile begins on line 7 to 11 with metadata information: the 62version of the package (+LIBFOO_VERSION+), the name of the 63tarball containing the package (+LIBFOO_SOURCE+) (xz-ed tarball recommended) 64the Internet location at which the tarball can be downloaded from 65(+LIBFOO_SITE+), the license (+LIBFOO_LICENSE+) and file with the 66license text (+LIBFOO_LICENSE_FILES+). All variables must start with 67the same prefix, +LIBFOO_+ in this case. This prefix is always the 68uppercased version of the package name (see below to understand where 69the package name is defined). 70 71On line 12, we specify that this package wants to install something to 72the staging space. This is often needed for libraries, since they must 73install header files and other development files in the staging space. 74This will ensure that the commands listed in the 75+LIBFOO_INSTALL_STAGING_CMDS+ variable will be executed. 76 77On line 13, we specify that there is some fixing to be done to some 78of the 'libfoo-config' files that were installed during 79+LIBFOO_INSTALL_STAGING_CMDS+ phase. 80These *-config files are executable shell script files that are 81located in '$(STAGING_DIR)/usr/bin' directory and are executed 82by other 3rd party packages to find out the location and the linking 83flags of this particular package. 84 85The problem is that all these *-config files by default give wrong, 86host system linking flags that are unsuitable for cross-compiling. 87 88For example: '-I/usr/include' instead of '-I$(STAGING_DIR)/usr/include' 89or: '-L/usr/lib' instead of '-L$(STAGING_DIR)/usr/lib' 90 91So some sed magic is done to these scripts to make them give correct 92flags. 93The argument to be given to +LIBFOO_CONFIG_SCRIPTS+ is the file name(s) 94of 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 97In addition, the scripts listed in +LIBFOO_CONFIG_SCRIPTS+ are removed 98from +$(TARGET_DIR)/usr/bin+, since they are not needed on the target. 99 100.Config script: 'divine' package 101================================ 102Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'. 103 104So its fixup would be: 105 106-------------------------------- 107DIVINE_CONFIG_SCRIPTS = divine-config 108-------------------------------- 109================================ 110 111.Config script: 'imagemagick' package: 112================================ 113Package imagemagick installs the following scripts: 114'$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config' 115 116So it's fixup would be: 117 118-------------------------------- 119IMAGEMAGICK_CONFIG_SCRIPTS = \ 120 Magick-config Magick++-config \ 121 MagickCore-config MagickWand-config Wand-config 122-------------------------------- 123================================ 124 125On line 14, we specify the list of dependencies this package relies 126on. These dependencies are listed in terms of lower-case package names, 127which can be packages for the target (without the +host-+ 128prefix) or packages for the host (with the +host-+) prefix). 129Buildroot will ensure that all these packages are built and installed 130'before' the current package starts its configuration. 131 132The rest of the Makefile, lines 16..29, defines what should be done 133at the different steps of the package configuration, compilation and 134installation. 135+LIBFOO_BUILD_CMDS+ tells what steps should be performed to 136build the package. +LIBFOO_INSTALL_STAGING_CMDS+ tells what 137steps should be performed to install the package in the staging space. 138+LIBFOO_INSTALL_TARGET_CMDS+ tells what steps should be 139performed to install the package in the target space. 140 141All these steps rely on the +$(@D)+ variable, which 142contains the directory where the source code of the package has been 143extracted. 144 145On lines 31..33, we define a user that is used by this package (e.g. 146to run a daemon as non-root) (+LIBFOO_USERS+). 147 148On line 35..37, we define a device-node file used by this package 149(+LIBFOO_DEVICES+). 150 151On line 39..41, we define the permissions to set to specific files 152installed by this package (+LIBFOO_PERMISSIONS+). 153 154Finally, on line 43, we call the +generic-package+ function, which 155generates, according to the variables defined previously, all the 156Makefile code necessary to make your package working. 157 158[[generic-package-reference]] 159 160==== +generic-package+ reference 161 162There are two variants of the generic target. The +generic-package+ macro is 163used for packages to be cross-compiled for the target. The 164+host-generic-package+ macro is used for host packages, natively compiled 165for the host. It is possible to call both of them in a single +.mk+ 166file: once to create the rules to generate a target 167package and once to create the rules to generate a host package: 168 169---------------------- 170$(eval $(generic-package)) 171$(eval $(host-generic-package)) 172---------------------- 173 174This might be useful if the compilation of the target package requires 175some 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 179variables of other packages, if they depend on +libfoo+ or 180+host-libfoo+. 181 182The call to the +generic-package+ and/or +host-generic-package+ macro 183*must* be at the end of the +.mk+ file, after all variable definitions. 184The call to +host-generic-package+ *must* be after the call to 185+generic-package+, if any. 186 187For the target package, the +generic-package+ uses the variables defined by 188the .mk file and prefixed by the uppercased package name: 189+LIBFOO_*+. +host-generic-package+ uses the +HOST_LIBFOO_*+ variables. For 190'some' variables, if the +HOST_LIBFOO_+ prefixed variable doesn't 191exist, the package infrastructure uses the corresponding variable 192prefixed by +LIBFOO_+. This is done for variables that are likely to 193have the same value for both the target and host packages. See below 194for details. 195 196The list of variables that can be set in a +.mk+ file to give metadata 197information is (assuming the package name is +libfoo+) : 198 199* +LIBFOO_VERSION+, mandatory, must contain the version of the 200 package. Note that if +HOST_LIBFOO_VERSION+ doesn't exist, it is 201 assumed to be the same as +LIBFOO_VERSION+. It can also be a 202 revision number or a tag for packages that are fetched directly 203 from their version control system. Examples: 204 ** a version for a release tarball: +LIBFOO_VERSION = 0.1.2+ 205 ** a sha1 for a git tree: +LIBFOO_VERSION = cb9d6aa9429e838f0e54faa3d455bcbab5eef057+ 206 ** a tag for a git tree +LIBFOO_VERSION = v0.1.2+ 207+ 208.Note: 209Using a branch name as +FOO_VERSION+ is not supported, because it does 210not and can not work as people would expect it should: 211+ 212 1. due to local caching, Buildroot will not re-fetch the repository, 213 so people who expect to be able to follow the remote repository 214 would be quite surprised and disappointed; 215 2. because two builds can never be perfectly simultaneous, and because 216 the remote repository may get new commits on the branch anytime, 217 two users, using the same Buildroot tree and building the same 218 configuration, may get different source, thus rendering the build 219 non reproducible, and people would be quite surprised and 220 disappointed. 221 222* +LIBFOO_SOURCE+ may contain the name of the tarball of the package, 223 which Buildroot will use to download the tarball from 224 +LIBFOO_SITE+. If +HOST_LIBFOO_SOURCE+ is not specified, it defaults 225 to +LIBFOO_SOURCE+. If none are specified, then the value is assumed 226 to be +libfoo-$(LIBFOO_VERSION).tar.gz+. + 227 Example: +LIBFOO_SOURCE = foobar-$(LIBFOO_VERSION).tar.bz2+ 228 229* +LIBFOO_PATCH+ may contain a space-separated list of patch file 230 names, that Buildroot will download and apply to the package source 231 code. If an entry contains +://+, then Buildroot will assume it is a 232 full URL and download the patch from this location. Otherwise, 233 Buildroot will assume that the patch should be downloaded from 234 +LIBFOO_SITE+. If +HOST_LIBFOO_PATCH+ is not specified, it defaults 235 to +LIBFOO_PATCH+. Note that patches that are included in Buildroot 236 itself use a different mechanism: all files of the form 237 +*.patch+ present in the package directory inside 238 Buildroot will be applied to the package after extraction (see 239 xref:patch-policy[patching a package]). Finally, patches listed in 240 the +LIBFOO_PATCH+ variable are applied _before_ the patches stored 241 in the Buildroot package directory. 242 243* +LIBFOO_SITE+ provides the location of the package, which can be a 244 URL or a local filesystem path. HTTP, FTP and SCP are supported URL 245 types for retrieving package tarballs. In these cases don't include a 246 trailing slash: it will be added by Buildroot between the directory 247 and the filename as appropriate. Git, Subversion, Mercurial, 248 and Bazaar are supported URL types for retrieving packages directly 249 from source code management systems. There is a helper function to make 250 it easier to download source tarballs from GitHub (refer to 251 xref:github-download-url[] for details). A filesystem path may be used 252 to specify either a tarball or a directory containing the package 253 source code. See +LIBFOO_SITE_METHOD+ below for more details on how 254 retrieval works. + 255 Note that SCP URLs should be of the form 256 +scp://[user@]host:filepath+, and that filepath is relative to the 257 user's home directory, so you may want to prepend the path with a 258 slash for absolute paths: 259 +scp://[user@]host:/absolutepath+. The same goes for SFTP URLs. + 260 If +HOST_LIBFOO_SITE+ is not specified, it defaults to 261 +LIBFOO_SITE+. 262 Examples: + 263 +LIBFOO_SITE=http://www.libfoosoftware.org/libfoo+ + 264 +LIBFOO_SITE=http://svn.xiph.org/trunk/Tremor+ + 265 +LIBFOO_SITE=/opt/software/libfoo.tar.gz+ + 266 +LIBFOO_SITE=$(TOPDIR)/../src/libfoo+ 267 268* +LIBFOO_DL_OPTS+ is a space-separated list of additional options to 269 pass to the downloader. Useful for retrieving documents with 270 server-side checking for user logins and passwords, or to use a proxy. 271 All download methods valid for +LIBFOO_SITE_METHOD+ are supported; 272 valid options depend on the download method (consult the man page 273 for the respective download utilities). 274 275* +LIBFOO_EXTRA_DOWNLOADS+ is a space-separated list of additional 276 files that Buildroot should download. If an entry contains +://+ 277 then Buildroot will assume it is a complete URL and will download 278 the file using this URL. Otherwise, Buildroot will assume the file 279 to be downloaded is located at +LIBFOO_SITE+. Buildroot will not do 280 anything with those additional files, except download them: it will 281 be up to the package recipe to use them from +$(LIBFOO_DL_DIR)+. 282 283* +LIBFOO_SITE_METHOD+ determines the method used to fetch or copy the 284 package source code. In many cases, Buildroot guesses the method 285 from the contents of +LIBFOO_SITE+ and setting +LIBFOO_SITE_METHOD+ 286 is unnecessary. When +HOST_LIBFOO_SITE_METHOD+ is not specified, it 287 defaults to the value of +LIBFOO_SITE_METHOD+. + 288 The possible values of +LIBFOO_SITE_METHOD+ are: 289 ** +wget+ for normal FTP/HTTP downloads of tarballs. Used by 290 default when +LIBFOO_SITE+ begins with +http://+, +https://+ or 291 +ftp://+. 292 ** +scp+ for downloads of tarballs over SSH with scp. Used by 293 default when +LIBFOO_SITE+ begins with +scp://+. 294 ** +sftp+ for downloads of tarballs over SSH with sftp. Used by 295 default when +LIBFOO_SITE+ begins with +sftp://+. 296 ** +svn+ for retrieving source code from a Subversion repository. 297 Used by default when +LIBFOO_SITE+ begins with +svn://+. When a 298 +http://+ Subversion repository URL is specified in 299 +LIBFOO_SITE+, one 'must' specify +LIBFOO_SITE_METHOD=svn+. 300 Buildroot performs a checkout which is preserved as a tarball in 301 the download cache; subsequent builds use the tarball instead of 302 performing another checkout. 303 ** +cvs+ for retrieving source code from a CVS repository. 304 Used by default when +LIBFOO_SITE+ begins with +cvs://+. 305 The downloaded source code is cached as with the +svn+ method. 306 Anonymous pserver mode is assumed otherwise explicitly defined 307 on +LIBFOO_SITE+. Both 308 +LIBFOO_SITE=cvs://libfoo.net:/cvsroot/libfoo+ and 309 +LIBFOO_SITE=cvs://:ext:libfoo.net:/cvsroot/libfoo+ 310 are accepted, on the former anonymous pserver access mode is 311 assumed. 312 +LIBFOO_SITE+ 'must' contain the source URL as well as the remote 313 repository directory. The module is the package name. 314 +LIBFOO_VERSION+ is 'mandatory' and 'must' be a tag, a branch, or 315 a date (e.g. "2014-10-20", "2014-10-20 13:45", "2014-10-20 316 13:45+01" see "man cvs" for further details). 317 ** +git+ for retrieving source code from a Git repository. Used by 318 default when +LIBFOO_SITE+ begins with +git://+. The downloaded 319 source code is cached as with the +svn+ method. 320 ** +hg+ for retrieving source code from a Mercurial repository. One 321 'must' specify +LIBFOO_SITE_METHOD=hg+ when +LIBFOO_SITE+ 322 contains a Mercurial repository URL. The downloaded source code 323 is cached as with the +svn+ method. 324 ** +bzr+ for retrieving source code from a Bazaar repository. Used 325 by default when +LIBFOO_SITE+ begins with +bzr://+. The 326 downloaded source code is cached as with the +svn+ method. 327 ** +file+ for a local tarball. One should use this when 328 +LIBFOO_SITE+ specifies a package tarball as a local filename. 329 Useful for software that isn't available publicly or in version 330 control. 331 ** +local+ for a local source code directory. One should use this 332 when +LIBFOO_SITE+ specifies a local directory path containing 333 the package source code. Buildroot copies the contents of the 334 source directory into the package's build directory. Note that 335 for +local+ packages, no patches are applied. If you need to 336 still patch the source code, use +LIBFOO_POST_RSYNC_HOOKS+, see 337 xref:hooks-rsync[]. 338 339* +LIBFOO_GIT_SUBMODULES+ can be set to +YES+ to create an archive 340 with the git submodules in the repository. This is only available 341 for packages downloaded with git (i.e. when 342 +LIBFOO_SITE_METHOD=git+). Note that we try not to use such git 343 submodules when they contain bundled libraries, in which case we 344 prefer to use those libraries from their own package. 345 346* +LIBFOO_GIT_LFS+ should be set to +YES+ if the Git repository uses 347 Git LFS to store large files out of band. This is only available for 348 packages downloaded with git (i.e. when +LIBFOO_SITE_METHOD=git+). 349 350* +LIBFOO_SVN_EXTERNALS+ can be set to +YES+ to create an archive with 351 the svn external references. This is only available for packages 352 downloaded with subversion. 353 354* +LIBFOO_STRIP_COMPONENTS+ is the number of leading components 355 (directories) that tar must strip from file names on extraction. 356 The tarball for most packages has one leading component named 357 "<pkg-name>-<pkg-version>", thus Buildroot passes 358 --strip-components=1 to tar to remove it. 359 For non-standard packages that don't have this component, or 360 that have more than one leading component to strip, set this 361 variable with the value to be passed to tar. Default: 1. 362 363* +LIBFOO_EXCLUDES+ is a space-separated list of patterns to exclude 364 when extracting the archive. Each item from that list is passed as 365 a tar's +--exclude+ option. By default, empty. 366 367* +LIBFOO_DEPENDENCIES+ lists the dependencies (in terms of package 368 name) that are required for the current target package to 369 compile. These dependencies are guaranteed to be compiled and 370 installed before the configuration of the current package starts. 371 However, modifications to configuration of these dependencies will 372 not force a rebuild of the current package. In a similar way, 373 +HOST_LIBFOO_DEPENDENCIES+ lists the dependencies for the current 374 host package. 375 376* +LIBFOO_EXTRACT_DEPENDENCIES+ lists the dependencies (in terms of 377 package name) that are required for the current target package to be 378 extracted. These dependencies are guaranteed to be compiled and 379 installed before the extract step of the current package 380 starts. This is only used internally by the package infrastructure, 381 and should typically not be used directly by packages. 382 383* +LIBFOO_PATCH_DEPENDENCIES+ lists the dependencies (in terms of 384 package name) that are required for the current package to be 385 patched. These dependencies are guaranteed to be extracted and 386 patched (but not necessarily built) before the current package is 387 patched. In a similar way, +HOST_LIBFOO_PATCH_DEPENDENCIES+ lists 388 the dependencies for the current host package. 389 This is seldom used; usually, +LIBFOO_DEPENDENCIES+ is what you 390 really want to use. 391 392* +LIBFOO_PROVIDES+ lists all the virtual packages +libfoo+ is an 393 implementation of. See xref:virtual-package-tutorial[]. 394 395* +LIBFOO_INSTALL_STAGING+ can be set to +YES+ or +NO+ (default). If 396 set to +YES+, then the commands in the +LIBFOO_INSTALL_STAGING_CMDS+ 397 variables are executed to install the package into the staging 398 directory. 399 400* +LIBFOO_INSTALL_TARGET+ can be set to +YES+ (default) or +NO+. If 401 set to +YES+, then the commands in the +LIBFOO_INSTALL_TARGET_CMDS+ 402 variables are executed to install the package into the target 403 directory. 404 405* +LIBFOO_INSTALL_IMAGES+ can be set to +YES+ or +NO+ (default). If 406 set to +YES+, then the commands in the +LIBFOO_INSTALL_IMAGES_CMDS+ 407 variable are executed to install the package into the images 408 directory. 409 410* +LIBFOO_CONFIG_SCRIPTS+ lists the names of the files in 411 '$(STAGING_DIR)/usr/bin' that need some special fixing to make them 412 cross-compiling friendly. Multiple file names separated by space can 413 be given and all are relative to '$(STAGING_DIR)/usr/bin'. The files 414 listed in +LIBFOO_CONFIG_SCRIPTS+ are also removed from 415 +$(TARGET_DIR)/usr/bin+ since they are not needed on the target. 416 417* +LIBFOO_DEVICES+ lists the device files to be created by Buildroot 418 when using the static device table. The syntax to use is the 419 makedevs one. You can find some documentation for this syntax in the 420 xref:makedev-syntax[]. This variable is optional. 421 422* +LIBFOO_PERMISSIONS+ lists the changes of permissions to be done at 423 the end of the build process. The syntax is once again the makedevs one. 424 You can find some documentation for this syntax in the xref:makedev-syntax[]. 425 This variable is optional. 426 427* +LIBFOO_USERS+ lists the users to create for this package, if it installs 428 a program you want to run as a specific user (e.g. as a daemon, or as a 429 cron-job). The syntax is similar in spirit to the makedevs one, and is 430 described in the xref:makeuser-syntax[]. This variable is optional. 431 432* +LIBFOO_LICENSE+ defines the license (or licenses) under which the package 433 is released. 434 This name will appear in the manifest file produced by +make legal-info+. 435 If the license appears in https://spdx.org/licenses/[the SPDX License List], 436 use the SPDX short identifier to make the manifest file uniform. 437 Otherwise, describe the license in a precise and concise way, avoiding 438 ambiguous names such as +BSD+ which actually name a family of licenses. 439 This variable is optional. If it is not defined, +unknown+ will appear in 440 the +license+ field of the manifest file for this package. + 441 The expected format for this variable must comply with the following rules: 442 ** If different parts of the package are released under different 443 licenses, then +comma+ separate licenses (e.g. +`LIBFOO_LICENSE = 444 GPL-2.0+, LGPL-2.1+`+). If there is clear distinction between which 445 component is licensed under what license, then annotate the license 446 with that component, between parenthesis (e.g. +`LIBFOO_LICENSE = 447 GPL-2.0+ (programs), LGPL-2.1+ (libraries)`+). 448 ** If some licenses are conditioned on a sub-option being enabled, append 449 the conditional licenses with a comma (e.g.: `FOO_LICENSE += , GPL-2.0+ 450 (programs)`); the infrastructure will internally remove the space before 451 the comma. 452 ** If the package is dual licensed, then separate licenses with the 453 +or+ keyword (e.g. +`LIBFOO_LICENSE = AFL-2.1 or GPL-2.0+`+). 454 455* +LIBFOO_LICENSE_FILES+ is a space-separated list of files in the package 456 tarball that contain the license(s) under which the package is released. 457 +make legal-info+ copies all of these files in the +legal-info+ directory. 458 See xref:legal-info[] for more information. 459 This variable is optional. If it is not defined, a warning will be produced 460 to let you know, and +not saved+ will appear in the +license files+ field 461 of the manifest file for this package. 462 463* +LIBFOO_ACTUAL_SOURCE_TARBALL+ only applies to packages whose 464 +LIBFOO_SITE+ / +LIBFOO_SOURCE+ pair points to an archive that does 465 not actually contain source code, but binary code. This a very 466 uncommon case, only known to apply to external toolchains which come 467 already compiled, although theoretically it might apply to other 468 packages. In such cases a separate tarball is usually available with 469 the actual source code. Set +LIBFOO_ACTUAL_SOURCE_TARBALL+ to the 470 name of the actual source code archive and Buildroot will download 471 it and use it when you run +make legal-info+ to collect 472 legally-relevant material. Note this file will not be downloaded 473 during regular builds nor by +make source+. 474 475* +LIBFOO_ACTUAL_SOURCE_SITE+ provides the location of the actual 476 source tarball. The default value is +LIBFOO_SITE+, so you don't 477 need to set this variable if the binary and source archives are 478 hosted on the same directory. If +LIBFOO_ACTUAL_SOURCE_TARBALL+ is 479 not set, it doesn't make sense to define 480 +LIBFOO_ACTUAL_SOURCE_SITE+. 481 482* +LIBFOO_REDISTRIBUTE+ can be set to +YES+ (default) or +NO+ to indicate if 483 the package source code is allowed to be redistributed. Set it to +NO+ for 484 non-opensource packages: Buildroot will not save the source code for this 485 package when collecting the +legal-info+. 486 487* +LIBFOO_FLAT_STACKSIZE+ defines the stack size of an application built into 488 the FLAT binary format. The application stack size on the NOMMU architecture 489 processors can't be enlarged at run time. The default stack size for the 490 FLAT binary format is only 4k bytes. If the application consumes more stack, 491 append the required number here. 492 493* +LIBFOO_BIN_ARCH_EXCLUDE+ is a space-separated list of paths (relative 494 to the target directory) to ignore when checking that the package 495 installs correctly cross-compiled binaries. You seldom need to set this 496 variable, unless the package installs binary blobs outside the default 497 locations, `/lib/firmware`, `/usr/lib/firmware`, `/lib/modules`, 498 `/usr/lib/modules`, and `/usr/share`, which are automatically excluded. 499 500* +LIBFOO_IGNORE_CVES+ is a space-separated list of CVEs that tells 501 Buildroot CVE tracking tools which CVEs should be ignored for this 502 package. This is typically used when the CVE is fixed by a patch in 503 the package, or when the CVE for some reason does not affect the 504 Buildroot package. A Makefile comment must always precede the 505 addition of a CVE to this variable. Example: 506+ 507---------------------- 508# 0001-fix-cve-2020-12345.patch 509LIBFOO_IGNORE_CVES += CVE-2020-12345 510# only when built with libbaz, which Buildroot doesn't support 511LIBFOO_IGNORE_CVES += CVE-2020-54321 512---------------------- 513 514* [[cpe-id]] +LIBFOO_CPE_ID_*+ variables is a set of variables that allows the 515 package to define its https://nvd.nist.gov/products/cpe[CPE 516 identifier]. The available variables are: 517+ 518-- 519** +LIBFOO_CPE_ID_VALID+, if set to +YES+, specifies that the default 520 values for each of the following variables is appropriate, and 521 generates a valid CPE ID. 522 523** +LIBFOO_CPE_ID_PREFIX+, specifies the prefix of the CPE identifier, 524 i.e the first three fields. When not defined, the default value is 525 +cpe:2.3:a+. 526 527** +LIBFOO_CPE_ID_VENDOR+, specifies the vendor part of the CPE 528 identifier. When not defined, the default value is 529 +<pkgname>_project+. 530 531** +LIBFOO_CPE_ID_PRODUCT+, specifies the product part of the CPE 532 identifier. When not defined, the default value is +<pkgname>+. 533 534** +LIBFOO_CPE_ID_VERSION+, specifies the version part of the CPE 535 identifier. When not defined the default value is 536 +$(LIBFOO_VERSION)+. 537 538** +LIBFOO_CPE_ID_UPDATE+ specifies the _update_ part of the CPE 539 identifier. When not defined the default value is +*+. 540-- 541+ 542If any of those variables is defined, then the generic package 543infrastructure assumes the package provides valid CPE information. In 544this case, the generic package infrastructure will define 545+LIBFOO_CPE_ID+. 546+ 547For a host package, if its +LIBFOO_CPE_ID_*+ variables are not 548defined, it inherits the value of those variables from the 549corresponding target package. 550 551The recommended way to define these variables is to use the following 552syntax: 553 554---------------------- 555LIBFOO_VERSION = 2.32 556---------------------- 557 558Now, the variables that define what should be performed at the 559different steps of the build process. 560 561* +LIBFOO_EXTRACT_CMDS+ lists the actions to be performed to extract 562 the package. This is generally not needed as tarballs are 563 automatically handled by Buildroot. However, if the package uses a 564 non-standard archive format, such as a ZIP or RAR file, or has a 565 tarball with a non-standard organization, this variable allows to 566 override the package infrastructure default behavior. 567 568* +LIBFOO_CONFIGURE_CMDS+ lists the actions to be performed to 569 configure the package before its compilation. 570 571* +LIBFOO_BUILD_CMDS+ lists the actions to be performed to 572 compile the package. 573 574* +HOST_LIBFOO_INSTALL_CMDS+ lists the actions to be performed 575 to install the package, when the package is a host package. The 576 package must install its files to the directory given by 577 +$(HOST_DIR)+. All files, including development files such as 578 headers should be installed, since other packages might be compiled 579 on top of this package. 580 581* +LIBFOO_INSTALL_TARGET_CMDS+ lists the actions to be 582 performed to install the package to the target directory, when the 583 package is a target package. The package must install its files to 584 the directory given by +$(TARGET_DIR)+. Only the files required for 585 'execution' of the package have to be 586 installed. Header files, static libraries and documentation will be 587 removed again when the target filesystem is finalized. 588 589* +LIBFOO_INSTALL_STAGING_CMDS+ lists the actions to be 590 performed to install the package to the staging directory, when the 591 package is a target package. The package must install its files to 592 the directory given by +$(STAGING_DIR)+. All development files 593 should be installed, since they might be needed to compile other 594 packages. 595 596* +LIBFOO_INSTALL_IMAGES_CMDS+ lists the actions to be performed to 597 install the package to the images directory, when the package is a 598 target package. The package must install its files to the directory 599 given by +$(BINARIES_DIR)+. Only files that are binary images (aka 600 images) that do not belong in the +TARGET_DIR+ but are necessary 601 for booting the board should be placed here. For example, a package 602 should utilize this step if it has binaries which would be similar 603 to the kernel image, bootloader or root filesystem images. 604 605* +LIBFOO_INSTALL_INIT_SYSV+, +LIBFOO_INSTALL_INIT_OPENRC+ and 606 +LIBFOO_INSTALL_INIT_SYSTEMD+ list the actions to install init 607 scripts either for the systemV-like init systems (busybox, 608 sysvinit, etc.), openrc or for the systemd units. These commands 609 will be run only when the relevant init system is installed (i.e. 610 if systemd is selected as the init system in the configuration, 611 only +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run). The only exception 612 is when openrc is chosen as init system and +LIBFOO_INSTALL_INIT_OPENRC+ 613 has not been set, in such situation +LIBFOO_INSTALL_INIT_SYSV+ will 614 be called, since openrc supports sysv init scripts. 615 When systemd is used as the init system, buildroot will automatically enable 616 all services using the +systemctl preset-all+ command in the final phase of 617 image building. You can add preset files to prevent a particular unit from 618 being automatically enabled by buildroot. 619 620* +LIBFOO_HELP_CMDS+ lists the actions to print the package help, which 621 is included to the main +make help+ output. These commands can print 622 anything in any format. 623 This is seldom used, as packages rarely have custom rules. *Do not use 624 this variable*, unless you really know that you need to print help. 625 626* +LIBFOO_LINUX_CONFIG_FIXUPS+ lists the Linux kernel configuration 627 options that are needed to build and use this package, and without 628 which the package is fundamentally broken. This shall be a set of 629 calls to one of the kconfig tweaking option: `KCONFIG_ENABLE_OPT`, 630 `KCONFIG_DISABLE_OPT`, or `KCONFIG_SET_OPT`. 631 This is seldom used, as package usually have no strict requirements on 632 the kernel options. 633 634The preferred way to define these variables is: 635 636---------------------- 637define LIBFOO_CONFIGURE_CMDS 638 action 1 639 action 2 640 action 3 641endef 642---------------------- 643 644In the action definitions, you can use the following variables: 645 646* +$(LIBFOO_PKGDIR)+ contains the path to the directory containing the 647 +libfoo.mk+ and +Config.in+ files. This variable is useful when it is 648 necessary to install a file bundled in Buildroot, like a runtime 649 configuration file, a splashscreen image... 650 651* +$(@D)+, which contains the directory in which the package source 652 code has been uncompressed. 653 654* +$(LIBFOO_DL_DIR)+ contains the path to the directory where all the downloads 655 made by Buildroot for +libfoo+ are stored in. 656 657* +$(TARGET_CC)+, +$(TARGET_LD)+, etc. to get the target 658 cross-compilation utilities 659 660* +$(TARGET_CROSS)+ to get the cross-compilation toolchain prefix 661 662* Of course the +$(HOST_DIR)+, +$(STAGING_DIR)+ and +$(TARGET_DIR)+ 663 variables to install the packages properly. Those variables point to 664 the global _host_, _staging_ and _target_ directories, unless 665 _per-package directory_ support is used, in which case they point to 666 the current package _host_, _staging_ and _target_ directories. In 667 both cases, it doesn't make any difference from the package point of 668 view: it should simply use +HOST_DIR+, +STAGING_DIR+ and 669 +TARGET_DIR+. See xref:top-level-parallel-build[] for more details 670 about _per-package directory_ support. 671 672Finally, you can also use hooks. See xref:hooks[] for more information. 673