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+. + 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 ** +svn+ for retrieving source code from a Subversion repository. 295 Used by default when +LIBFOO_SITE+ begins with +svn://+. When a 296 +http://+ Subversion repository URL is specified in 297 +LIBFOO_SITE+, one 'must' specify +LIBFOO_SITE_METHOD=svn+. 298 Buildroot performs a checkout which is preserved as a tarball in 299 the download cache; subsequent builds use the tarball instead of 300 performing another checkout. 301 ** +cvs+ for retrieving source code from a CVS repository. 302 Used by default when +LIBFOO_SITE+ begins with +cvs://+. 303 The downloaded source code is cached as with the +svn+ method. 304 Anonymous pserver mode is assumed otherwise explicitly defined 305 on +LIBFOO_SITE+. Both 306 +LIBFOO_SITE=cvs://libfoo.net:/cvsroot/libfoo+ and 307 +LIBFOO_SITE=cvs://:ext:libfoo.net:/cvsroot/libfoo+ 308 are accepted, on the former anonymous pserver access mode is 309 assumed. 310 +LIBFOO_SITE+ 'must' contain the source URL as well as the remote 311 repository directory. The module is the package name. 312 +LIBFOO_VERSION+ is 'mandatory' and 'must' be a tag, a branch, or 313 a date (e.g. "2014-10-20", "2014-10-20 13:45", "2014-10-20 314 13:45+01" see "man cvs" for further details). 315 ** +git+ for retrieving source code from a Git repository. Used by 316 default when +LIBFOO_SITE+ begins with +git://+. The downloaded 317 source code is cached as with the +svn+ 318 method. 319 ** +hg+ for retrieving source code from a Mercurial repository. One 320 'must' specify +LIBFOO_SITE_METHOD=hg+ when +LIBFOO_SITE+ 321 contains a Mercurial repository URL. The downloaded source code 322 is cached as with the +svn+ method. 323 ** +bzr+ for retrieving source code from a Bazaar repository. Used 324 by default when +LIBFOO_SITE+ begins with +bzr://+. The 325 downloaded source code is cached as with the +svn+ method. 326 ** +file+ for a local tarball. One should use this when 327 +LIBFOO_SITE+ specifies a package tarball as a local filename. 328 Useful for software that isn't available publicly or in version 329 control. 330 ** +local+ for a local source code directory. One should use this 331 when +LIBFOO_SITE+ specifies a local directory path containing 332 the package source code. Buildroot copies the contents of the 333 source directory into the package's build directory. Note that 334 for +local+ packages, no patches are applied. If you need to 335 still patch the source code, use +LIBFOO_POST_RSYNC_HOOKS+, see 336 xref:hooks-rsync[]. 337 338* +LIBFOO_GIT_SUBMODULES+ can be set to +YES+ to create an archive 339 with the git submodules in the repository. This is only available 340 for packages downloaded with git (i.e. when 341 +LIBFOO_SITE_METHOD=git+). Note that we try not to use such git 342 submodules when they contain bundled libraries, in which case we 343 prefer to use those libraries from their own package. 344 345* +LIBFOO_STRIP_COMPONENTS+ is the number of leading components 346 (directories) that tar must strip from file names on extraction. 347 The tarball for most packages has one leading component named 348 "<pkg-name>-<pkg-version>", thus Buildroot passes 349 --strip-components=1 to tar to remove it. 350 For non-standard packages that don't have this component, or 351 that have more than one leading component to strip, set this 352 variable with the value to be passed to tar. Default: 1. 353 354* +LIBFOO_EXCLUDES+ is a space-separated list of patterns to exclude 355 when extracting the archive. Each item from that list is passed as 356 a tar's +--exclude+ option. By default, empty. 357 358* +LIBFOO_DEPENDENCIES+ lists the dependencies (in terms of package 359 name) that are required for the current target package to 360 compile. These dependencies are guaranteed to be compiled and 361 installed before the configuration of the current package starts. 362 However, modifications to configuration of these dependencies will 363 not force a rebuild of the current package. In a similar way, 364 +HOST_LIBFOO_DEPENDENCIES+ lists the dependencies for the current 365 host package. 366 367* +LIBFOO_EXTRACT_DEPENDENCIES+ lists the dependencies (in terms of 368 package name) that are required for the current target package to be 369 extracted. These dependencies are guaranteed to be compiled and 370 installed before the extract step of the current package 371 starts. This is only used internally by the package infrastructure, 372 and should typically not be used directly by packages. 373 374* +LIBFOO_PATCH_DEPENDENCIES+ lists the dependencies (in terms of 375 package name) that are required for the current package to be 376 patched. These dependencies are guaranteed to be extracted and 377 patched (but not necessarily built) before the current package is 378 patched. In a similar way, +HOST_LIBFOO_PATCH_DEPENDENCIES+ lists 379 the dependencies for the current host package. 380 This is seldom used; usually, +LIBFOO_DEPENDENCIES+ is what you 381 really want to use. 382 383* +LIBFOO_PROVIDES+ lists all the virtual packages +libfoo+ is an 384 implementation of. See xref:virtual-package-tutorial[]. 385 386* +LIBFOO_INSTALL_STAGING+ can be set to +YES+ or +NO+ (default). If 387 set to +YES+, then the commands in the +LIBFOO_INSTALL_STAGING_CMDS+ 388 variables are executed to install the package into the staging 389 directory. 390 391* +LIBFOO_INSTALL_TARGET+ can be set to +YES+ (default) or +NO+. If 392 set to +YES+, then the commands in the +LIBFOO_INSTALL_TARGET_CMDS+ 393 variables are executed to install the package into the target 394 directory. 395 396* +LIBFOO_INSTALL_IMAGES+ can be set to +YES+ or +NO+ (default). If 397 set to +YES+, then the commands in the +LIBFOO_INSTALL_IMAGES_CMDS+ 398 variable are executed to install the package into the images 399 directory. 400 401* +LIBFOO_CONFIG_SCRIPTS+ lists the names of the files in 402 '$(STAGING_DIR)/usr/bin' that need some special fixing to make them 403 cross-compiling friendly. Multiple file names separated by space can 404 be given and all are relative to '$(STAGING_DIR)/usr/bin'. The files 405 listed in +LIBFOO_CONFIG_SCRIPTS+ are also removed from 406 +$(TARGET_DIR)/usr/bin+ since they are not needed on the target. 407 408* +LIBFOO_DEVICES+ lists the device files to be created by Buildroot 409 when using the static device table. The syntax to use is the 410 makedevs one. You can find some documentation for this syntax in the 411 xref:makedev-syntax[]. This variable is optional. 412 413* +LIBFOO_PERMISSIONS+ lists the changes of permissions to be done at 414 the end of the build process. The syntax is once again the makedevs one. 415 You can find some documentation for this syntax in the xref:makedev-syntax[]. 416 This variable is optional. 417 418* +LIBFOO_USERS+ lists the users to create for this package, if it installs 419 a program you want to run as a specific user (e.g. as a daemon, or as a 420 cron-job). The syntax is similar in spirit to the makedevs one, and is 421 described in the xref:makeuser-syntax[]. This variable is optional. 422 423* +LIBFOO_LICENSE+ defines the license (or licenses) under which the package 424 is released. 425 This name will appear in the manifest file produced by +make legal-info+. 426 If the license appears in https://spdx.org/licenses/[the SPDX License List], 427 use the SPDX short identifier to make the manifest file uniform. 428 Otherwise, describe the license in a precise and concise way, avoiding 429 ambiguous names such as +BSD+ which actually name a family of licenses. 430 This variable is optional. If it is not defined, +unknown+ will appear in 431 the +license+ field of the manifest file for this package. + 432 The expected format for this variable must comply with the following rules: 433 ** If different parts of the package are released under different 434 licenses, then +comma+ separate licenses (e.g. +`LIBFOO_LICENSE = 435 GPL-2.0+, LGPL-2.1+`+). If there is clear distinction between which 436 component is licensed under what license, then annotate the license 437 with that component, between parenthesis (e.g. +`LIBFOO_LICENSE = 438 GPL-2.0+ (programs), LGPL-2.1+ (libraries)`+). 439 ** If some licenses are conditioned on a sub-option being enabled, append 440 the conditional licenses with a comma (e.g.: `FOO_LICENSE += , GPL-2.0+ 441 (programs)`); the infrastructure will internally remove the space before 442 the comma. 443 ** If the package is dual licensed, then separate licenses with the 444 +or+ keyword (e.g. +`LIBFOO_LICENSE = AFL-2.1 or GPL-2.0+`+). 445 446* +LIBFOO_LICENSE_FILES+ is a space-separated list of files in the package 447 tarball that contain the license(s) under which the package is released. 448 +make legal-info+ copies all of these files in the +legal-info+ directory. 449 See xref:legal-info[] for more information. 450 This variable is optional. If it is not defined, a warning will be produced 451 to let you know, and +not saved+ will appear in the +license files+ field 452 of the manifest file for this package. 453 454* +LIBFOO_ACTUAL_SOURCE_TARBALL+ only applies to packages whose 455 +LIBFOO_SITE+ / +LIBFOO_SOURCE+ pair points to an archive that does 456 not actually contain source code, but binary code. This a very 457 uncommon case, only known to apply to external toolchains which come 458 already compiled, although theoretically it might apply to other 459 packages. In such cases a separate tarball is usually available with 460 the actual source code. Set +LIBFOO_ACTUAL_SOURCE_TARBALL+ to the 461 name of the actual source code archive and Buildroot will download 462 it and use it when you run +make legal-info+ to collect 463 legally-relevant material. Note this file will not be downloaded 464 during regular builds nor by +make source+. 465 466* +LIBFOO_ACTUAL_SOURCE_SITE+ provides the location of the actual 467 source tarball. The default value is +LIBFOO_SITE+, so you don't 468 need to set this variable if the binary and source archives are 469 hosted on the same directory. If +LIBFOO_ACTUAL_SOURCE_TARBALL+ is 470 not set, it doesn't make sense to define 471 +LIBFOO_ACTUAL_SOURCE_SITE+. 472 473* +LIBFOO_REDISTRIBUTE+ can be set to +YES+ (default) or +NO+ to indicate if 474 the package source code is allowed to be redistributed. Set it to +NO+ for 475 non-opensource packages: Buildroot will not save the source code for this 476 package when collecting the +legal-info+. 477 478* +LIBFOO_FLAT_STACKSIZE+ defines the stack size of an application built into 479 the FLAT binary format. The application stack size on the NOMMU architecture 480 processors can't be enlarged at run time. The default stack size for the 481 FLAT binary format is only 4k bytes. If the application consumes more stack, 482 append the required number here. 483 484* +LIBFOO_BIN_ARCH_EXCLUDE+ is a space-separated list of paths (relative 485 to the target directory) to ignore when checking that the package 486 installs correctly cross-compiled binaries. You seldom need to set this 487 variable, unless the package installs binary blobs outside the default 488 locations, `/lib/firmware`, `/usr/lib/firmware`, `/lib/modules`, 489 `/usr/lib/modules`, and `/usr/share`, which are automatically excluded. 490 491* +LIBFOO_IGNORE_CVES+ is a space-separated list of CVEs that tells 492 Buildroot CVE tracking tools which CVEs should be ignored for this 493 package. This is typically used when the CVE is fixed by a patch in 494 the package, or when the CVE for some reason does not affect the 495 Buildroot package. A Makefile comment must always precede the 496 addition of a CVE to this variable. Example: 497 498---------------------- 499# 0001-fix-cve-2020-12345.patch 500LIBFOO_IGNORE_CVES += CVE-2020-12345 501# only when built with libbaz, which Buildroot doesn't support 502LIBFOO_IGNORE_CVES += CVE-2020-54321 503---------------------- 504 505* +LIBFOO_CPE_ID_*+ variables is a set of variables that allows the 506 package to define its https://nvd.nist.gov/products/cpe[CPE 507 identifier]. The available variables are: 508+ 509-- 510** +LIBFOO_CPE_ID_PREFIX+, specifies the prefix of the CPE identifier, 511 i.e the first three fields. When not defined, the default value is 512 +cpe:2.3:a+. 513 514** +LIBFOO_CPE_ID_VENDOR+, specifies the vendor part of the CPE 515 identifier. When not defined, the default value is 516 +<pkgname>_project+. 517 518** +LIBFOO_CPE_ID_PRODUCT+, specifies the product part of the CPE 519 identifier. When not defined, the default value is +<pkgname>+. 520 521** +LIBFOO_CPE_ID_VERSION+, specifies the version part of the CPE 522 identifier. When not defined the default value is 523 +$(LIBFOO_VERSION)+. 524 525** +LIBFOO_CPE_ID_UPDATE+ specifies the _update_ part of the CPE 526 identifier. When not defined the default value is +*+. 527-- 528+ 529If any of those variables is defined, then the generic package 530infrastructure assumes the package provides valid CPE information. In 531this case, the generic package infrastructure will define 532+LIBFOO_CPE_ID+. 533+ 534For a host package, if its +LIBFOO_CPE_ID_*+ variables are not 535defined, it inherits the value of those variables from the 536corresponding target package. 537 538The recommended way to define these variables is to use the following 539syntax: 540 541---------------------- 542LIBFOO_VERSION = 2.32 543---------------------- 544 545Now, the variables that define what should be performed at the 546different steps of the build process. 547 548* +LIBFOO_EXTRACT_CMDS+ lists the actions to be performed to extract 549 the package. This is generally not needed as tarballs are 550 automatically handled by Buildroot. However, if the package uses a 551 non-standard archive format, such as a ZIP or RAR file, or has a 552 tarball with a non-standard organization, this variable allows to 553 override the package infrastructure default behavior. 554 555* +LIBFOO_CONFIGURE_CMDS+ lists the actions to be performed to 556 configure the package before its compilation. 557 558* +LIBFOO_BUILD_CMDS+ lists the actions to be performed to 559 compile the package. 560 561* +HOST_LIBFOO_INSTALL_CMDS+ lists the actions to be performed 562 to install the package, when the package is a host package. The 563 package must install its files to the directory given by 564 +$(HOST_DIR)+. All files, including development files such as 565 headers should be installed, since other packages might be compiled 566 on top of this package. 567 568* +LIBFOO_INSTALL_TARGET_CMDS+ lists the actions to be 569 performed to install the package to the target directory, when the 570 package is a target package. The package must install its files to 571 the directory given by +$(TARGET_DIR)+. Only the files required for 572 'execution' of the package have to be 573 installed. Header files, static libraries and documentation will be 574 removed again when the target filesystem is finalized. 575 576* +LIBFOO_INSTALL_STAGING_CMDS+ lists the actions to be 577 performed to install the package to the staging directory, when the 578 package is a target package. The package must install its files to 579 the directory given by +$(STAGING_DIR)+. All development files 580 should be installed, since they might be needed to compile other 581 packages. 582 583* +LIBFOO_INSTALL_IMAGES_CMDS+ lists the actions to be performed to 584 install the package to the images directory, when the package is a 585 target package. The package must install its files to the directory 586 given by +$(BINARIES_DIR)+. Only files that are binary images (aka 587 images) that do not belong in the +TARGET_DIR+ but are necessary 588 for booting the board should be placed here. For example, a package 589 should utilize this step if it has binaries which would be similar 590 to the kernel image, bootloader or root filesystem images. 591 592* +LIBFOO_INSTALL_INIT_SYSV+, +LIBFOO_INSTALL_INIT_OPENRC+ and 593 +LIBFOO_INSTALL_INIT_SYSTEMD+ list the actions to install init 594 scripts either for the systemV-like init systems (busybox, 595 sysvinit, etc.), openrc or for the systemd units. These commands 596 will be run only when the relevant init system is installed (i.e. 597 if systemd is selected as the init system in the configuration, 598 only +LIBFOO_INSTALL_INIT_SYSTEMD+ will be run). The only exception 599 is when openrc is chosen as init system and +LIBFOO_INSTALL_INIT_OPENRC+ 600 has not been set, in such situation +LIBFOO_INSTALL_INIT_SYSV+ will 601 be called, since openrc supports sysv init scripts. 602 When systemd is used as the init system, buildroot will automatically enable 603 all services using the +systemctl preset-all+ command in the final phase of 604 image building. You can add preset files to prevent a particular unit from 605 being automatically enabled by buildroot. 606 607* +LIBFOO_HELP_CMDS+ lists the actions to print the package help, which 608 is included to the main +make help+ output. These commands can print 609 anything in any format. 610 This is seldom used, as packages rarely have custom rules. *Do not use 611 this variable*, unless you really know that you need to print help. 612 613* +LIBFOO_LINUX_CONFIG_FIXUPS+ lists the Linux kernel configuration 614 options that are needed to build and use this package, and without 615 which the package is fundamentally broken. This shall be a set of 616 calls to one of the kconfig tweaking option: `KCONFIG_ENABLE_OPT`, 617 `KCONFIG_DISABLE_OPT`, or `KCONFIG_SET_OPT`. 618 This is seldom used, as package usually have no strict requirements on 619 the kernel options. 620 621The preferred way to define these variables is: 622 623---------------------- 624define LIBFOO_CONFIGURE_CMDS 625 action 1 626 action 2 627 action 3 628endef 629---------------------- 630 631In the action definitions, you can use the following variables: 632 633* +$(LIBFOO_PKGDIR)+ contains the path to the directory containing the 634 +libfoo.mk+ and +Config.in+ files. This variable is useful when it is 635 necessary to install a file bundled in Buildroot, like a runtime 636 configuration file, a splashscreen image... 637 638* +$(@D)+, which contains the directory in which the package source 639 code has been uncompressed. 640 641* +$(LIBFOO_DL_DIR)+ contains the path to the directory where all the downloads 642 made by Buildroot for +libfoo+ are stored in. 643 644* +$(TARGET_CC)+, +$(TARGET_LD)+, etc. to get the target 645 cross-compilation utilities 646 647* +$(TARGET_CROSS)+ to get the cross-compilation toolchain prefix 648 649* Of course the +$(HOST_DIR)+, +$(STAGING_DIR)+ and +$(TARGET_DIR)+ 650 variables to install the packages properly. Those variables point to 651 the global _host_, _staging_ and _target_ directories, unless 652 _per-package directory_ support is used, in which case they point to 653 the current package _host_, _staging_ and _target_ directories. In 654 both cases, it doesn't make any difference from the package point of 655 view: it should simply use +HOST_DIR+, +STAGING_DIR+ and 656 +TARGET_DIR+. See xref:top-level-parallel-build[] for more details 657 about _per-package directory_ support. 658 659Finally, you can also use hooks. See xref:hooks[] for more information. 660