1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3Writing a New Recipe 4******************** 5 6Recipes (``.bb`` files) are fundamental components in the Yocto Project 7environment. Each software component built by the OpenEmbedded build 8system requires a recipe to define the component. This section describes 9how to create, write, and test a new recipe. 10 11.. note:: 12 13 For information on variables that are useful for recipes and for 14 information about recipe naming issues, see the 15 ":ref:`ref-manual/varlocality:recipes`" section of the Yocto Project 16 Reference Manual. 17 18Overview 19======== 20 21The following figure shows the basic process for creating a new recipe. 22The remainder of the section provides details for the steps. 23 24.. image:: figures/recipe-workflow.png 25 :align: center 26 :width: 50% 27 28Locate or Automatically Create a Base Recipe 29============================================ 30 31You can always write a recipe from scratch. However, there are three choices 32that can help you quickly get started with a new recipe: 33 34- ``devtool add``: A command that assists in creating a recipe and an 35 environment conducive to development. 36 37- ``recipetool create``: A command provided by the Yocto Project that 38 automates creation of a base recipe based on the source files. 39 40- *Existing Recipes:* Location and modification of an existing recipe 41 that is similar in function to the recipe you need. 42 43.. note:: 44 45 For information on recipe syntax, see the 46 ":ref:`dev-manual/new-recipe:recipe syntax`" section. 47 48Creating the Base Recipe Using ``devtool add`` 49---------------------------------------------- 50 51The ``devtool add`` command uses the same logic for auto-creating the 52recipe as ``recipetool create``, which is listed below. Additionally, 53however, ``devtool add`` sets up an environment that makes it easy for 54you to patch the source and to make changes to the recipe as is often 55necessary when adding a recipe to build a new piece of software to be 56included in a build. 57 58You can find a complete description of the ``devtool add`` command in 59the ":ref:`sdk-manual/extensible:a closer look at \`\`devtool add\`\``" section 60in the Yocto Project Application Development and the Extensible Software 61Development Kit (eSDK) manual. 62 63Creating the Base Recipe Using ``recipetool create`` 64---------------------------------------------------- 65 66``recipetool create`` automates creation of a base recipe given a set of 67source code files. As long as you can extract or point to the source 68files, the tool will construct a recipe and automatically configure all 69pre-build information into the recipe. For example, suppose you have an 70application that builds using Autotools. Creating the base recipe using 71``recipetool`` results in a recipe that has the pre-build dependencies, 72license requirements, and checksums configured. 73 74To run the tool, you just need to be in your :term:`Build Directory` and 75have sourced the build environment setup script (i.e. 76:ref:`structure-core-script`). To get help on the tool, use the following 77command:: 78 79 $ recipetool -h 80 NOTE: Starting bitbake server... 81 usage: recipetool [-d] [-q] [--color COLOR] [-h] <subcommand> ... 82 83 OpenEmbedded recipe tool 84 85 options: 86 -d, --debug Enable debug output 87 -q, --quiet Print only errors 88 --color COLOR Colorize output (where COLOR is auto, always, never) 89 -h, --help show this help message and exit 90 91 subcommands: 92 create Create a new recipe 93 newappend Create a bbappend for the specified target in the specified 94 layer 95 setvar Set a variable within a recipe 96 appendfile Create/update a bbappend to replace a target file 97 appendsrcfiles Create/update a bbappend to add or replace source files 98 appendsrcfile Create/update a bbappend to add or replace a source file 99 Use recipetool <subcommand> --help to get help on a specific command 100 101Running ``recipetool create -o OUTFILE`` creates the base recipe and 102locates it properly in the layer that contains your source files. 103Following are some syntax examples: 104 105 - Use this syntax to generate a recipe based on source. Once generated, 106 the recipe resides in the existing source code layer:: 107 108 recipetool create -o OUTFILE source 109 110 - Use this syntax to generate a recipe using code that 111 you extract from source. The extracted code is placed in its own layer 112 defined by :term:`EXTERNALSRC`:: 113 114 recipetool create -o OUTFILE -x EXTERNALSRC source 115 116 - Use this syntax to generate a recipe based on source. The options 117 direct ``recipetool`` to generate debugging information. Once generated, 118 the recipe resides in the existing source code layer:: 119 120 recipetool create -d -o OUTFILE source 121 122Locating and Using a Similar Recipe 123----------------------------------- 124 125Before writing a recipe from scratch, it is often useful to discover 126whether someone else has already written one that meets (or comes close 127to meeting) your needs. The Yocto Project and OpenEmbedded communities 128maintain many recipes that might be candidates for what you are doing. 129You can find a good central index of these recipes in the 130:oe_layerindex:`OpenEmbedded Layer Index <>`. 131 132Working from an existing recipe or a skeleton recipe is the best way to 133get started. Here are some points on both methods: 134 135- *Locate and modify a recipe that is close to what you want to do:* 136 This method works when you are familiar with the current recipe 137 space. The method does not work so well for those new to the Yocto 138 Project or writing recipes. 139 140 Some risks associated with this method are using a recipe that has 141 areas totally unrelated to what you are trying to accomplish with 142 your recipe, not recognizing areas of the recipe that you might have 143 to add from scratch, and so forth. All these risks stem from 144 unfamiliarity with the existing recipe space. 145 146- *Use and modify the following skeleton recipe:* If for some reason 147 you do not want to use ``recipetool`` and you cannot find an existing 148 recipe that is close to meeting your needs, you can use the following 149 structure to provide the fundamental areas of a new recipe:: 150 151 DESCRIPTION = "" 152 HOMEPAGE = "" 153 LICENSE = "" 154 SECTION = "" 155 DEPENDS = "" 156 LIC_FILES_CHKSUM = "" 157 158 SRC_URI = "" 159 160Storing and Naming the Recipe 161============================= 162 163Once you have your base recipe, you should put it in your own layer and 164name it appropriately. Locating it correctly ensures that the 165OpenEmbedded build system can find it when you use BitBake to process 166the recipe. 167 168- *Storing Your Recipe:* The OpenEmbedded build system locates your 169 recipe through the layer's ``conf/layer.conf`` file and the 170 :term:`BBFILES` variable. This 171 variable sets up a path from which the build system can locate 172 recipes. Here is the typical use:: 173 174 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ 175 ${LAYERDIR}/recipes-*/*/*.bbappend" 176 177 Consequently, you need to be sure you locate your new recipe inside 178 your layer such that it can be found. 179 180 You can find more information on how layers are structured in the 181 ":ref:`dev-manual/layers:understanding and creating layers`" section. 182 183- *Naming Your Recipe:* When you name your recipe, you need to follow 184 this naming convention:: 185 186 basename_version.bb 187 188 Use lower-cased characters and do not include the reserved suffixes 189 ``-native``, ``-cross``, ``-initial``, or ``-dev`` casually (i.e. do not use 190 them as part of your recipe name unless the string applies). Here are some 191 examples: 192 193 .. code-block:: none 194 195 cups_1.7.0.bb 196 gawk_4.0.2.bb 197 irssi_0.8.16-rc1.bb 198 199Running a Build on the Recipe 200============================= 201 202Creating a new recipe is usually an iterative process that requires 203using BitBake to process the recipe multiple times in order to 204progressively discover and add information to the recipe file. 205 206Assuming you have sourced the build environment setup script (i.e. 207:ref:`structure-core-script`) and you are in the :term:`Build Directory`, use 208BitBake to process your recipe. All you need to provide is the 209``basename`` of the recipe as described in the previous section:: 210 211 $ bitbake basename 212 213During the build, the OpenEmbedded build system creates a temporary work 214directory for each recipe 215(``${``\ :term:`WORKDIR`\ ``}``) 216where it keeps extracted source files, log files, intermediate 217compilation and packaging files, and so forth. 218 219The path to the per-recipe temporary work directory depends on the 220context in which it is being built. The quickest way to find this path 221is to have BitBake return it by running the following:: 222 223 $ bitbake -e basename | grep ^WORKDIR= 224 225As an example, assume a Source Directory 226top-level folder named ``poky``, a default :term:`Build Directory` at 227``poky/build``, and a ``qemux86-poky-linux`` machine target system. 228Furthermore, suppose your recipe is named ``foo_1.3.0.bb``. In this 229case, the work directory the build system uses to build the package 230would be as follows:: 231 232 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 233 234Inside this directory you can find sub-directories such as ``image``, 235``packages-split``, and ``temp``. After the build, you can examine these 236to determine how well the build went. 237 238.. note:: 239 240 You can find log files for each task in the recipe's ``temp`` 241 directory (e.g. ``poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp``). 242 Log files are named ``log.taskname`` (e.g. ``log.do_configure``, 243 ``log.do_fetch``, and ``log.do_compile``). 244 245You can find more information about the build process in 246":doc:`/overview-manual/development-environment`" 247chapter of the Yocto Project Overview and Concepts Manual. 248 249Fetching Code 250============= 251 252The first thing your recipe must do is specify how to fetch the source 253files. Fetching is controlled mainly through the 254:term:`SRC_URI` variable. Your recipe 255must have a :term:`SRC_URI` variable that points to where the source is 256located. For a graphical representation of source locations, see the 257":ref:`overview-manual/concepts:sources`" section in 258the Yocto Project Overview and Concepts Manual. 259 260The :ref:`ref-tasks-fetch` task uses 261the prefix of each entry in the :term:`SRC_URI` variable value to determine 262which :ref:`fetcher <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` to use to get your 263source files. It is the :term:`SRC_URI` variable that triggers the fetcher. 264The :ref:`ref-tasks-patch` task uses 265the variable after source is fetched to apply patches. The OpenEmbedded 266build system uses 267:term:`FILESOVERRIDES` for 268scanning directory locations for local files in :term:`SRC_URI`. 269 270The :term:`SRC_URI` variable in your recipe must define each unique location 271for your source files. It is good practice to not hard-code version 272numbers in a URL used in :term:`SRC_URI`. Rather than hard-code these 273values, use ``${``\ :term:`PV`\ ``}``, 274which causes the fetch process to use the version specified in the 275recipe filename. Specifying the version in this manner means that 276upgrading the recipe to a future version is as simple as renaming the 277recipe to match the new version. 278 279Here is a simple example from the 280``meta/recipes-devtools/strace/strace_5.5.bb`` recipe where the source 281comes from a single tarball. Notice the use of the 282:term:`PV` variable:: 283 284 SRC_URI = "https://strace.io/files/${PV}/strace-${PV}.tar.xz \ 285 286Files mentioned in :term:`SRC_URI` whose names end in a typical archive 287extension (e.g. ``.tar``, ``.tar.gz``, ``.tar.bz2``, ``.zip``, and so 288forth), are automatically extracted during the 289:ref:`ref-tasks-unpack` task. For 290another example that specifies these types of files, see the 291":ref:`dev-manual/new-recipe:autotooled package`" section. 292 293Another way of specifying source is from an SCM. For Git repositories, 294you must specify :term:`SRCREV` and you should specify :term:`PV` to include 295the revision with :term:`SRCPV`. Here is an example from the recipe 296``meta/recipes-core/musl/gcompat_git.bb``:: 297 298 SRC_URI = "git://git.adelielinux.org/adelie/gcompat.git;protocol=https;branch=current" 299 300 PV = "1.0.0+1.1+git${SRCPV}" 301 SRCREV = "af5a49e489fdc04b9cf02547650d7aeaccd43793" 302 303If your :term:`SRC_URI` statement includes URLs pointing to individual files 304fetched from a remote server other than a version control system, 305BitBake attempts to verify the files against checksums defined in your 306recipe to ensure they have not been tampered with or otherwise modified 307since the recipe was written. Two checksums are used: 308``SRC_URI[md5sum]`` and ``SRC_URI[sha256sum]``. 309 310If your :term:`SRC_URI` variable points to more than a single URL (excluding 311SCM URLs), you need to provide the ``md5`` and ``sha256`` checksums for 312each URL. For these cases, you provide a name for each URL as part of 313the :term:`SRC_URI` and then reference that name in the subsequent checksum 314statements. Here is an example combining lines from the files 315``git.inc`` and ``git_2.24.1.bb``:: 316 317 SRC_URI = "${KERNELORG_MIRROR}/software/scm/git/git-${PV}.tar.gz;name=tarball \ 318 ${KERNELORG_MIRROR}/software/scm/git/git-manpages-${PV}.tar.gz;name=manpages" 319 320 SRC_URI[tarball.md5sum] = "166bde96adbbc11c8843d4f8f4f9811b" 321 SRC_URI[tarball.sha256sum] = "ad5334956301c86841eb1e5b1bb20884a6bad89a10a6762c958220c7cf64da02" 322 SRC_URI[manpages.md5sum] = "31c2272a8979022497ba3d4202df145d" 323 SRC_URI[manpages.sha256sum] = "9a7ae3a093bea39770eb96ca3e5b40bff7af0b9f6123f089d7821d0e5b8e1230" 324 325Proper values for ``md5`` and ``sha256`` checksums might be available 326with other signatures on the download page for the upstream source (e.g. 327``md5``, ``sha1``, ``sha256``, ``GPG``, and so forth). Because the 328OpenEmbedded build system only deals with ``sha256sum`` and ``md5sum``, 329you should verify all the signatures you find by hand. 330 331If no :term:`SRC_URI` checksums are specified when you attempt to build the 332recipe, or you provide an incorrect checksum, the build will produce an 333error for each missing or incorrect checksum. As part of the error 334message, the build system provides the checksum string corresponding to 335the fetched file. Once you have the correct checksums, you can copy and 336paste them into your recipe and then run the build again to continue. 337 338.. note:: 339 340 As mentioned, if the upstream source provides signatures for 341 verifying the downloaded source code, you should verify those 342 manually before setting the checksum values in the recipe and 343 continuing with the build. 344 345This final example is a bit more complicated and is from the 346``meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.20.bb`` recipe. The 347example's :term:`SRC_URI` statement identifies multiple files as the source 348files for the recipe: a tarball, a patch file, a desktop file, and an icon:: 349 350 SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \ 351 file://xwc.patch \ 352 file://rxvt.desktop \ 353 file://rxvt.png" 354 355When you specify local files using the ``file://`` URI protocol, the 356build system fetches files from the local machine. The path is relative 357to the :term:`FILESPATH` variable 358and searches specific directories in a certain order: 359``${``\ :term:`BP`\ ``}``, 360``${``\ :term:`BPN`\ ``}``, and 361``files``. The directories are assumed to be subdirectories of the 362directory in which the recipe or append file resides. For another 363example that specifies these types of files, see the 364":ref:`dev-manual/new-recipe:single .c file package (hello world!)`" section. 365 366The previous example also specifies a patch file. Patch files are files 367whose names usually end in ``.patch`` or ``.diff`` but can end with 368compressed suffixes such as ``diff.gz`` and ``patch.bz2``, for example. 369The build system automatically applies patches as described in the 370":ref:`dev-manual/new-recipe:patching code`" section. 371 372Fetching Code Through Firewalls 373------------------------------- 374 375Some users are behind firewalls and need to fetch code through a proxy. 376See the ":doc:`/ref-manual/faq`" chapter for advice. 377 378Limiting the Number of Parallel Connections 379------------------------------------------- 380 381Some users are behind firewalls or use servers where the number of parallel 382connections is limited. In such cases, you can limit the number of fetch 383tasks being run in parallel by adding the following to your ``local.conf`` 384file:: 385 386 do_fetch[number_threads] = "4" 387 388Unpacking Code 389============== 390 391During the build, the 392:ref:`ref-tasks-unpack` task unpacks 393the source with ``${``\ :term:`S`\ ``}`` 394pointing to where it is unpacked. 395 396If you are fetching your source files from an upstream source archived 397tarball and the tarball's internal structure matches the common 398convention of a top-level subdirectory named 399``${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``, 400then you do not need to set :term:`S`. However, if :term:`SRC_URI` specifies to 401fetch source from an archive that does not use this convention, or from 402an SCM like Git or Subversion, your recipe needs to define :term:`S`. 403 404If processing your recipe using BitBake successfully unpacks the source 405files, you need to be sure that the directory pointed to by ``${S}`` 406matches the structure of the source. 407 408Patching Code 409============= 410 411Sometimes it is necessary to patch code after it has been fetched. Any 412files mentioned in :term:`SRC_URI` whose names end in ``.patch`` or 413``.diff`` or compressed versions of these suffixes (e.g. ``diff.gz`` are 414treated as patches. The 415:ref:`ref-tasks-patch` task 416automatically applies these patches. 417 418The build system should be able to apply patches with the "-p1" option 419(i.e. one directory level in the path will be stripped off). If your 420patch needs to have more directory levels stripped off, specify the 421number of levels using the "striplevel" option in the :term:`SRC_URI` entry 422for the patch. Alternatively, if your patch needs to be applied in a 423specific subdirectory that is not specified in the patch file, use the 424"patchdir" option in the entry. 425 426As with all local files referenced in 427:term:`SRC_URI` using ``file://``, 428you should place patch files in a directory next to the recipe either 429named the same as the base name of the recipe 430(:term:`BP` and 431:term:`BPN`) or "files". 432 433Licensing 434========= 435 436Your recipe needs to have both the 437:term:`LICENSE` and 438:term:`LIC_FILES_CHKSUM` 439variables: 440 441- :term:`LICENSE`: This variable specifies the license for the software. 442 If you do not know the license under which the software you are 443 building is distributed, you should go to the source code and look 444 for that information. Typical files containing this information 445 include ``COPYING``, :term:`LICENSE`, and ``README`` files. You could 446 also find the information near the top of a source file. For example, 447 given a piece of software licensed under the GNU General Public 448 License version 2, you would set :term:`LICENSE` as follows:: 449 450 LICENSE = "GPL-2.0-only" 451 452 The licenses you specify within :term:`LICENSE` can have any name as long 453 as you do not use spaces, since spaces are used as separators between 454 license names. For standard licenses, use the names of the files in 455 ``meta/files/common-licenses/`` or the :term:`SPDXLICENSEMAP` flag names 456 defined in ``meta/conf/licenses.conf``. 457 458- :term:`LIC_FILES_CHKSUM`: The OpenEmbedded build system uses this 459 variable to make sure the license text has not changed. If it has, 460 the build produces an error and it affords you the chance to figure 461 it out and correct the problem. 462 463 You need to specify all applicable licensing files for the software. 464 At the end of the configuration step, the build process will compare 465 the checksums of the files to be sure the text has not changed. Any 466 differences result in an error with the message containing the 467 current checksum. For more explanation and examples of how to set the 468 :term:`LIC_FILES_CHKSUM` variable, see the 469 ":ref:`dev-manual/licenses:tracking license changes`" section. 470 471 To determine the correct checksum string, you can list the 472 appropriate files in the :term:`LIC_FILES_CHKSUM` variable with incorrect 473 md5 strings, attempt to build the software, and then note the 474 resulting error messages that will report the correct md5 strings. 475 See the ":ref:`dev-manual/new-recipe:fetching code`" section for 476 additional information. 477 478 Here is an example that assumes the software has a ``COPYING`` file:: 479 480 LIC_FILES_CHKSUM = "file://COPYING;md5=xxx" 481 482 When you try to build the 483 software, the build system will produce an error and give you the 484 correct string that you can substitute into the recipe file for a 485 subsequent build. 486 487Dependencies 488============ 489 490Most software packages have a short list of other packages that they 491require, which are called dependencies. These dependencies fall into two 492main categories: build-time dependencies, which are required when the 493software is built; and runtime dependencies, which are required to be 494installed on the target in order for the software to run. 495 496Within a recipe, you specify build-time dependencies using the 497:term:`DEPENDS` variable. Although there are nuances, 498items specified in :term:`DEPENDS` should be names of other 499recipes. It is important that you specify all build-time dependencies 500explicitly. 501 502Another consideration is that configure scripts might automatically 503check for optional dependencies and enable corresponding functionality 504if those dependencies are found. If you wish to make a recipe that is 505more generally useful (e.g. publish the recipe in a layer for others to 506use), instead of hard-disabling the functionality, you can use the 507:term:`PACKAGECONFIG` variable to allow functionality and the 508corresponding dependencies to be enabled and disabled easily by other 509users of the recipe. 510 511Similar to build-time dependencies, you specify runtime dependencies 512through a variable - 513:term:`RDEPENDS`, which is 514package-specific. All variables that are package-specific need to have 515the name of the package added to the end as an override. Since the main 516package for a recipe has the same name as the recipe, and the recipe's 517name can be found through the 518``${``\ :term:`PN`\ ``}`` variable, then 519you specify the dependencies for the main package by setting 520``RDEPENDS:${PN}``. If the package were named ``${PN}-tools``, then you 521would set ``RDEPENDS:${PN}-tools``, and so forth. 522 523Some runtime dependencies will be set automatically at packaging time. 524These dependencies include any shared library dependencies (i.e. if a 525package "example" contains "libexample" and another package "mypackage" 526contains a binary that links to "libexample" then the OpenEmbedded build 527system will automatically add a runtime dependency to "mypackage" on 528"example"). See the 529":ref:`overview-manual/concepts:automatically added runtime dependencies`" 530section in the Yocto Project Overview and Concepts Manual for further 531details. 532 533Configuring the Recipe 534====================== 535 536Most software provides some means of setting build-time configuration 537options before compilation. Typically, setting these options is 538accomplished by running a configure script with options, or by modifying 539a build configuration file. 540 541.. note:: 542 543 As of Yocto Project Release 1.7, some of the core recipes that 544 package binary configuration scripts now disable the scripts due to 545 the scripts previously requiring error-prone path substitution. The 546 OpenEmbedded build system uses ``pkg-config`` now, which is much more 547 robust. You can find a list of the ``*-config`` scripts that are disabled 548 in the ":ref:`migration-1.7-binary-configuration-scripts-disabled`" section 549 in the Yocto Project Reference Manual. 550 551A major part of build-time configuration is about checking for 552build-time dependencies and possibly enabling optional functionality as 553a result. You need to specify any build-time dependencies for the 554software you are building in your recipe's 555:term:`DEPENDS` value, in terms of 556other recipes that satisfy those dependencies. You can often find 557build-time or runtime dependencies described in the software's 558documentation. 559 560The following list provides configuration items of note based on how 561your software is built: 562 563- *Autotools:* If your source files have a ``configure.ac`` file, then 564 your software is built using Autotools. If this is the case, you just 565 need to modify the configuration. 566 567 When using Autotools, your recipe needs to inherit the 568 :ref:`ref-classes-autotools` class and it does not have to 569 contain a :ref:`ref-tasks-configure` task. However, you might still want to 570 make some adjustments. For example, you can set :term:`EXTRA_OECONF` or 571 :term:`PACKAGECONFIG_CONFARGS` to pass any needed configure options that 572 are specific to the recipe. 573 574- *CMake:* If your source files have a ``CMakeLists.txt`` file, then 575 your software is built using CMake. If this is the case, you just 576 need to modify the configuration. 577 578 When you use CMake, your recipe needs to inherit the 579 :ref:`ref-classes-cmake` class and it does not have to contain a 580 :ref:`ref-tasks-configure` task. You can make some adjustments by setting 581 :term:`EXTRA_OECMAKE` to pass any needed configure options that are 582 specific to the recipe. 583 584 .. note:: 585 586 If you need to install one or more custom CMake toolchain files 587 that are supplied by the application you are building, install the 588 files to ``${D}${datadir}/cmake/Modules`` during :ref:`ref-tasks-install`. 589 590- *Other:* If your source files do not have a ``configure.ac`` or 591 ``CMakeLists.txt`` file, then your software is built using some 592 method other than Autotools or CMake. If this is the case, you 593 normally need to provide a 594 :ref:`ref-tasks-configure` task 595 in your recipe unless, of course, there is nothing to configure. 596 597 Even if your software is not being built by Autotools or CMake, you 598 still might not need to deal with any configuration issues. You need 599 to determine if configuration is even a required step. You might need 600 to modify a Makefile or some configuration file used for the build to 601 specify necessary build options. Or, perhaps you might need to run a 602 provided, custom configure script with the appropriate options. 603 604 For the case involving a custom configure script, you would run 605 ``./configure --help`` and look for the options you need to set. 606 607Once configuration succeeds, it is always good practice to look at the 608``log.do_configure`` file to ensure that the appropriate options have 609been enabled and no additional build-time dependencies need to be added 610to :term:`DEPENDS`. For example, if the configure script reports that it 611found something not mentioned in :term:`DEPENDS`, or that it did not find 612something that it needed for some desired optional functionality, then 613you would need to add those to :term:`DEPENDS`. Looking at the log might 614also reveal items being checked for, enabled, or both that you do not 615want, or items not being found that are in :term:`DEPENDS`, in which case 616you would need to look at passing extra options to the configure script 617as needed. For reference information on configure options specific to 618the software you are building, you can consult the output of the 619``./configure --help`` command within ``${S}`` or consult the software's 620upstream documentation. 621 622Using Headers to Interface with Devices 623======================================= 624 625If your recipe builds an application that needs to communicate with some 626device or needs an API into a custom kernel, you will need to provide 627appropriate header files. Under no circumstances should you ever modify 628the existing 629``meta/recipes-kernel/linux-libc-headers/linux-libc-headers.inc`` file. 630These headers are used to build ``libc`` and must not be compromised 631with custom or machine-specific header information. If you customize 632``libc`` through modified headers all other applications that use 633``libc`` thus become affected. 634 635.. note:: 636 637 Never copy and customize the ``libc`` header file (i.e. 638 ``meta/recipes-kernel/linux-libc-headers/linux-libc-headers.inc``). 639 640The correct way to interface to a device or custom kernel is to use a 641separate package that provides the additional headers for the driver or 642other unique interfaces. When doing so, your application also becomes 643responsible for creating a dependency on that specific provider. 644 645Consider the following: 646 647- Never modify ``linux-libc-headers.inc``. Consider that file to be 648 part of the ``libc`` system, and not something you use to access the 649 kernel directly. You should access ``libc`` through specific ``libc`` 650 calls. 651 652- Applications that must talk directly to devices should either provide 653 necessary headers themselves, or establish a dependency on a special 654 headers package that is specific to that driver. 655 656For example, suppose you want to modify an existing header that adds I/O 657control or network support. If the modifications are used by a small 658number programs, providing a unique version of a header is easy and has 659little impact. When doing so, bear in mind the guidelines in the 660previous list. 661 662.. note:: 663 664 If for some reason your changes need to modify the behavior of the ``libc``, 665 and subsequently all other applications on the system, use a ``.bbappend`` 666 to modify the ``linux-kernel-headers.inc`` file. However, take care to not 667 make the changes machine specific. 668 669Consider a case where your kernel is older and you need an older 670``libc`` ABI. The headers installed by your recipe should still be a 671standard mainline kernel, not your own custom one. 672 673When you use custom kernel headers you need to get them from 674:term:`STAGING_KERNEL_DIR`, 675which is the directory with kernel headers that are required to build 676out-of-tree modules. Your recipe will also need the following:: 677 678 do_configure[depends] += "virtual/kernel:do_shared_workdir" 679 680Compilation 681=========== 682 683During a build, the :ref:`ref-tasks-compile` task happens after source is fetched, 684unpacked, and configured. If the recipe passes through :ref:`ref-tasks-compile` 685successfully, nothing needs to be done. 686 687However, if the compile step fails, you need to diagnose the failure. 688Here are some common issues that cause failures. 689 690.. note:: 691 692 For cases where improper paths are detected for configuration files 693 or for when libraries/headers cannot be found, be sure you are using 694 the more robust ``pkg-config``. See the note in section 695 ":ref:`dev-manual/new-recipe:Configuring the Recipe`" for additional information. 696 697- *Parallel build failures:* These failures manifest themselves as 698 intermittent errors, or errors reporting that a file or directory 699 that should be created by some other part of the build process could 700 not be found. This type of failure can occur even if, upon 701 inspection, the file or directory does exist after the build has 702 failed, because that part of the build process happened in the wrong 703 order. 704 705 To fix the problem, you need to either satisfy the missing dependency 706 in the Makefile or whatever script produced the Makefile, or (as a 707 workaround) set :term:`PARALLEL_MAKE` to an empty string:: 708 709 PARALLEL_MAKE = "" 710 711 For information on parallel Makefile issues, see the 712 ":ref:`dev-manual/debugging:debugging parallel make races`" section. 713 714- *Improper host path usage:* This failure applies to recipes building 715 for the target or ":ref:`ref-classes-nativesdk`" only. The 716 failure occurs when the compilation process uses improper headers, 717 libraries, or other files from the host system when cross-compiling for 718 the target. 719 720 To fix the problem, examine the ``log.do_compile`` file to identify 721 the host paths being used (e.g. ``/usr/include``, ``/usr/lib``, and 722 so forth) and then either add configure options, apply a patch, or do 723 both. 724 725- *Failure to find required libraries/headers:* If a build-time 726 dependency is missing because it has not been declared in 727 :term:`DEPENDS`, or because the 728 dependency exists but the path used by the build process to find the 729 file is incorrect and the configure step did not detect it, the 730 compilation process could fail. For either of these failures, the 731 compilation process notes that files could not be found. In these 732 cases, you need to go back and add additional options to the 733 configure script as well as possibly add additional build-time 734 dependencies to :term:`DEPENDS`. 735 736 Occasionally, it is necessary to apply a patch to the source to 737 ensure the correct paths are used. If you need to specify paths to 738 find files staged into the sysroot from other recipes, use the 739 variables that the OpenEmbedded build system provides (e.g. 740 :term:`STAGING_BINDIR`, :term:`STAGING_INCDIR`, :term:`STAGING_DATADIR`, and so 741 forth). 742 743Installing 744========== 745 746During :ref:`ref-tasks-install`, the task copies the built files along with their 747hierarchy to locations that would mirror their locations on the target 748device. The installation process copies files from the 749``${``\ :term:`S`\ ``}``, 750``${``\ :term:`B`\ ``}``, and 751``${``\ :term:`WORKDIR`\ ``}`` 752directories to the ``${``\ :term:`D`\ ``}`` 753directory to create the structure as it should appear on the target 754system. 755 756How your software is built affects what you must do to be sure your 757software is installed correctly. The following list describes what you 758must do for installation depending on the type of build system used by 759the software being built: 760 761- *Autotools and CMake:* If the software your recipe is building uses 762 Autotools or CMake, the OpenEmbedded build system understands how to 763 install the software. Consequently, you do not have to have a 764 :ref:`ref-tasks-install` task as part of your recipe. You just need to make 765 sure the install portion of the build completes with no issues. 766 However, if you wish to install additional files not already being 767 installed by ``make install``, you should do this using a 768 ``do_install:append`` function using the install command as described 769 in the "Manual" bulleted item later in this list. 770 771- *Other (using* ``make install``\ *)*: You need to define a :ref:`ref-tasks-install` 772 function in your recipe. The function should call 773 ``oe_runmake install`` and will likely need to pass in the 774 destination directory as well. How you pass that path is dependent on 775 how the ``Makefile`` being run is written (e.g. ``DESTDIR=${D}``, 776 ``PREFIX=${D}``, ``INSTALLROOT=${D}``, and so forth). 777 778 For an example recipe using ``make install``, see the 779 ":ref:`dev-manual/new-recipe:makefile-based package`" section. 780 781- *Manual:* You need to define a :ref:`ref-tasks-install` function in your 782 recipe. The function must first use ``install -d`` to create the 783 directories under 784 ``${``\ :term:`D`\ ``}``. Once the 785 directories exist, your function can use ``install`` to manually 786 install the built software into the directories. 787 788 You can find more information on ``install`` at 789 https://www.gnu.org/software/coreutils/manual/html_node/install-invocation.html. 790 791For the scenarios that do not use Autotools or CMake, you need to track 792the installation and diagnose and fix any issues until everything 793installs correctly. You need to look in the default location of 794``${D}``, which is ``${WORKDIR}/image``, to be sure your files have been 795installed correctly. 796 797.. note:: 798 799 - During the installation process, you might need to modify some of 800 the installed files to suit the target layout. For example, you 801 might need to replace hard-coded paths in an initscript with 802 values of variables provided by the build system, such as 803 replacing ``/usr/bin/`` with ``${bindir}``. If you do perform such 804 modifications during :ref:`ref-tasks-install`, be sure to modify the 805 destination file after copying rather than before copying. 806 Modifying after copying ensures that the build system can 807 re-execute :ref:`ref-tasks-install` if needed. 808 809 - ``oe_runmake install``, which can be run directly or can be run 810 indirectly by the :ref:`ref-classes-autotools` and 811 :ref:`ref-classes-cmake` classes, runs ``make install`` in parallel. 812 Sometimes, a Makefile can have missing dependencies between targets that 813 can result in race conditions. If you experience intermittent failures 814 during :ref:`ref-tasks-install`, you might be able to work around them by 815 disabling parallel Makefile installs by adding the following to the 816 recipe:: 817 818 PARALLEL_MAKEINST = "" 819 820 See :term:`PARALLEL_MAKEINST` for additional information. 821 822 - If you need to install one or more custom CMake toolchain files 823 that are supplied by the application you are building, install the 824 files to ``${D}${datadir}/cmake/Modules`` during 825 :ref:`ref-tasks-install`. 826 827Enabling System Services 828======================== 829 830If you want to install a service, which is a process that usually starts 831on boot and runs in the background, then you must include some 832additional definitions in your recipe. 833 834If you are adding services and the service initialization script or the 835service file itself is not installed, you must provide for that 836installation in your recipe using a ``do_install:append`` function. If 837your recipe already has a :ref:`ref-tasks-install` function, update the function 838near its end rather than adding an additional ``do_install:append`` 839function. 840 841When you create the installation for your services, you need to 842accomplish what is normally done by ``make install``. In other words, 843make sure your installation arranges the output similar to how it is 844arranged on the target system. 845 846The OpenEmbedded build system provides support for starting services two 847different ways: 848 849- *SysVinit:* SysVinit is a system and service manager that manages the 850 init system used to control the very basic functions of your system. 851 The init program is the first program started by the Linux kernel 852 when the system boots. Init then controls the startup, running and 853 shutdown of all other programs. 854 855 To enable a service using SysVinit, your recipe needs to inherit the 856 :ref:`ref-classes-update-rc.d` class. The class helps 857 facilitate safely installing the package on the target. 858 859 You will need to set the 860 :term:`INITSCRIPT_PACKAGES`, 861 :term:`INITSCRIPT_NAME`, 862 and 863 :term:`INITSCRIPT_PARAMS` 864 variables within your recipe. 865 866- *systemd:* System Management Daemon (systemd) was designed to replace 867 SysVinit and to provide enhanced management of services. For more 868 information on systemd, see the systemd homepage at 869 https://freedesktop.org/wiki/Software/systemd/. 870 871 To enable a service using systemd, your recipe needs to inherit the 872 :ref:`ref-classes-systemd` class. See the ``systemd.bbclass`` file 873 located in your :term:`Source Directory` section for more information. 874 875Packaging 876========= 877 878Successful packaging is a combination of automated processes performed 879by the OpenEmbedded build system and some specific steps you need to 880take. The following list describes the process: 881 882- *Splitting Files*: The :ref:`ref-tasks-package` task splits the files produced 883 by the recipe into logical components. Even software that produces a 884 single binary might still have debug symbols, documentation, and 885 other logical components that should be split out. The :ref:`ref-tasks-package` 886 task ensures that files are split up and packaged correctly. 887 888- *Running QA Checks*: The :ref:`ref-classes-insane` class adds a 889 step to the package generation process so that output quality 890 assurance checks are generated by the OpenEmbedded build system. This 891 step performs a range of checks to be sure the build's output is free 892 of common problems that show up during runtime. For information on 893 these checks, see the :ref:`ref-classes-insane` class and 894 the ":ref:`ref-manual/qa-checks:qa error and warning messages`" 895 chapter in the Yocto Project Reference Manual. 896 897- *Hand-Checking Your Packages*: After you build your software, you 898 need to be sure your packages are correct. Examine the 899 ``${``\ :term:`WORKDIR`\ ``}/packages-split`` 900 directory and make sure files are where you expect them to be. If you 901 discover problems, you can set 902 :term:`PACKAGES`, 903 :term:`FILES`, 904 ``do_install(:append)``, and so forth as needed. 905 906- *Splitting an Application into Multiple Packages*: If you need to 907 split an application into several packages, see the 908 ":ref:`dev-manual/new-recipe:splitting an application into multiple packages`" 909 section for an example. 910 911- *Installing a Post-Installation Script*: For an example showing how 912 to install a post-installation script, see the 913 ":ref:`dev-manual/new-recipe:post-installation scripts`" section. 914 915- *Marking Package Architecture*: Depending on what your recipe is 916 building and how it is configured, it might be important to mark the 917 packages produced as being specific to a particular machine, or to 918 mark them as not being specific to a particular machine or 919 architecture at all. 920 921 By default, packages apply to any machine with the same architecture 922 as the target machine. When a recipe produces packages that are 923 machine-specific (e.g. the 924 :term:`MACHINE` value is passed 925 into the configure script or a patch is applied only for a particular 926 machine), you should mark them as such by adding the following to the 927 recipe:: 928 929 PACKAGE_ARCH = "${MACHINE_ARCH}" 930 931 On the other hand, if the recipe produces packages that do not 932 contain anything specific to the target machine or architecture at 933 all (e.g. recipes that simply package script files or configuration 934 files), you should use the :ref:`ref-classes-allarch` class to 935 do this for you by adding this to your recipe:: 936 937 inherit allarch 938 939 Ensuring that the package architecture is correct is not critical 940 while you are doing the first few builds of your recipe. However, it 941 is important in order to ensure that your recipe rebuilds (or does 942 not rebuild) appropriately in response to changes in configuration, 943 and to ensure that you get the appropriate packages installed on the 944 target machine, particularly if you run separate builds for more than 945 one target machine. 946 947Sharing Files Between Recipes 948============================= 949 950Recipes often need to use files provided by other recipes on the build 951host. For example, an application linking to a common library needs 952access to the library itself and its associated headers. The way this 953access is accomplished is by populating a sysroot with files. Each 954recipe has two sysroots in its work directory, one for target files 955(``recipe-sysroot``) and one for files that are native to the build host 956(``recipe-sysroot-native``). 957 958.. note:: 959 960 You could find the term "staging" used within the Yocto project 961 regarding files populating sysroots (e.g. the :term:`STAGING_DIR` 962 variable). 963 964Recipes should never populate the sysroot directly (i.e. write files 965into sysroot). Instead, files should be installed into standard 966locations during the 967:ref:`ref-tasks-install` task within 968the ``${``\ :term:`D`\ ``}`` directory. The 969reason for this limitation is that almost all files that populate the 970sysroot are cataloged in manifests in order to ensure the files can be 971removed later when a recipe is either modified or removed. Thus, the 972sysroot is able to remain free from stale files. 973 974A subset of the files installed by the :ref:`ref-tasks-install` task are 975used by the :ref:`ref-tasks-populate_sysroot` task as defined by the 976:term:`SYSROOT_DIRS` variable to automatically populate the sysroot. It 977is possible to modify the list of directories that populate the sysroot. 978The following example shows how you could add the ``/opt`` directory to 979the list of directories within a recipe:: 980 981 SYSROOT_DIRS += "/opt" 982 983.. note:: 984 985 The `/sysroot-only` is to be used by recipes that generate artifacts 986 that are not included in the target filesystem, allowing them to share 987 these artifacts without needing to use the :term:`DEPLOY_DIR`. 988 989For a more complete description of the :ref:`ref-tasks-populate_sysroot` 990task and its associated functions, see the 991:ref:`staging <ref-classes-staging>` class. 992 993Using Virtual Providers 994======================= 995 996Prior to a build, if you know that several different recipes provide the 997same functionality, you can use a virtual provider (i.e. ``virtual/*``) 998as a placeholder for the actual provider. The actual provider is 999determined at build-time. 1000 1001A common scenario where a virtual provider is used would be for the kernel 1002recipe. Suppose you have three kernel recipes whose :term:`PN` values map to 1003``kernel-big``, ``kernel-mid``, and ``kernel-small``. Furthermore, each of 1004these recipes in some way uses a :term:`PROVIDES` statement that essentially 1005identifies itself as being able to provide ``virtual/kernel``. Here is one way 1006through the :ref:`ref-classes-kernel` class:: 1007 1008 PROVIDES += "virtual/kernel" 1009 1010Any recipe that inherits the :ref:`ref-classes-kernel` class is 1011going to utilize a :term:`PROVIDES` statement that identifies that recipe as 1012being able to provide the ``virtual/kernel`` item. 1013 1014Now comes the time to actually build an image and you need a kernel 1015recipe, but which one? You can configure your build to call out the 1016kernel recipe you want by using the :term:`PREFERRED_PROVIDER` variable. As 1017an example, consider the :yocto_git:`x86-base.inc 1018</poky/tree/meta/conf/machine/include/x86/x86-base.inc>` include file, which is a 1019machine (i.e. :term:`MACHINE`) configuration file. This include file is the 1020reason all x86-based machines use the ``linux-yocto`` kernel. Here are the 1021relevant lines from the include file:: 1022 1023 PREFERRED_PROVIDER_virtual/kernel ??= "linux-yocto" 1024 PREFERRED_VERSION_linux-yocto ??= "4.15%" 1025 1026When you use a virtual provider, you do not have to "hard code" a recipe 1027name as a build dependency. You can use the 1028:term:`DEPENDS` variable to state the 1029build is dependent on ``virtual/kernel`` for example:: 1030 1031 DEPENDS = "virtual/kernel" 1032 1033During the build, the OpenEmbedded build system picks 1034the correct recipe needed for the ``virtual/kernel`` dependency based on 1035the :term:`PREFERRED_PROVIDER` variable. If you want to use the small kernel 1036mentioned at the beginning of this section, configure your build as 1037follows:: 1038 1039 PREFERRED_PROVIDER_virtual/kernel ??= "kernel-small" 1040 1041.. note:: 1042 1043 Any recipe that :term:`PROVIDES` a ``virtual/*`` item that is ultimately not 1044 selected through :term:`PREFERRED_PROVIDER` does not get built. Preventing these 1045 recipes from building is usually the desired behavior since this mechanism's 1046 purpose is to select between mutually exclusive alternative providers. 1047 1048The following lists specific examples of virtual providers: 1049 1050- ``virtual/kernel``: Provides the name of the kernel recipe to use 1051 when building a kernel image. 1052 1053- ``virtual/bootloader``: Provides the name of the bootloader to use 1054 when building an image. 1055 1056- ``virtual/libgbm``: Provides ``gbm.pc``. 1057 1058- ``virtual/egl``: Provides ``egl.pc`` and possibly ``wayland-egl.pc``. 1059 1060- ``virtual/libgl``: Provides ``gl.pc`` (i.e. libGL). 1061 1062- ``virtual/libgles1``: Provides ``glesv1_cm.pc`` (i.e. libGLESv1_CM). 1063 1064- ``virtual/libgles2``: Provides ``glesv2.pc`` (i.e. libGLESv2). 1065 1066.. note:: 1067 1068 Virtual providers only apply to build time dependencies specified with 1069 :term:`PROVIDES` and :term:`DEPENDS`. They do not apply to runtime 1070 dependencies specified with :term:`RPROVIDES` and :term:`RDEPENDS`. 1071 1072Properly Versioning Pre-Release Recipes 1073======================================= 1074 1075Sometimes the name of a recipe can lead to versioning problems when the 1076recipe is upgraded to a final release. For example, consider the 1077``irssi_0.8.16-rc1.bb`` recipe file in the list of example recipes in 1078the ":ref:`dev-manual/new-recipe:storing and naming the recipe`" section. 1079This recipe is at a release candidate stage (i.e. "rc1"). When the recipe is 1080released, the recipe filename becomes ``irssi_0.8.16.bb``. The version 1081change from ``0.8.16-rc1`` to ``0.8.16`` is seen as a decrease by the 1082build system and package managers, so the resulting packages will not 1083correctly trigger an upgrade. 1084 1085In order to ensure the versions compare properly, the recommended 1086convention is to set :term:`PV` within the 1087recipe to "previous_version+current_version". You can use an additional 1088variable so that you can use the current version elsewhere. Here is an 1089example:: 1090 1091 REALPV = "0.8.16-rc1" 1092 PV = "0.8.15+${REALPV}" 1093 1094Post-Installation Scripts 1095========================= 1096 1097Post-installation scripts run immediately after installing a package on 1098the target or during image creation when a package is included in an 1099image. To add a post-installation script to a package, add a 1100``pkg_postinst:``\ `PACKAGENAME`\ ``()`` function to the recipe file 1101(``.bb``) and replace `PACKAGENAME` with the name of the package you want 1102to attach to the ``postinst`` script. To apply the post-installation 1103script to the main package for the recipe, which is usually what is 1104required, specify 1105``${``\ :term:`PN`\ ``}`` in place of 1106PACKAGENAME. 1107 1108A post-installation function has the following structure:: 1109 1110 pkg_postinst:PACKAGENAME() { 1111 # Commands to carry out 1112 } 1113 1114The script defined in the post-installation function is called when the 1115root filesystem is created. If the script succeeds, the package is 1116marked as installed. 1117 1118.. note:: 1119 1120 Any RPM post-installation script that runs on the target should 1121 return a 0 exit code. RPM does not allow non-zero exit codes for 1122 these scripts, and the RPM package manager will cause the package to 1123 fail installation on the target. 1124 1125Sometimes it is necessary for the execution of a post-installation 1126script to be delayed until the first boot. For example, the script might 1127need to be executed on the device itself. To delay script execution 1128until boot time, you must explicitly mark post installs to defer to the 1129target. You can use ``pkg_postinst_ontarget()`` or call 1130``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``. Any 1131failure of a ``pkg_postinst()`` script (including exit 1) triggers an 1132error during the 1133:ref:`ref-tasks-rootfs` task. 1134 1135If you have recipes that use ``pkg_postinst`` function and they require 1136the use of non-standard native tools that have dependencies during 1137root filesystem construction, you need to use the 1138:term:`PACKAGE_WRITE_DEPS` 1139variable in your recipe to list these tools. If you do not use this 1140variable, the tools might be missing and execution of the 1141post-installation script is deferred until first boot. Deferring the 1142script to the first boot is undesirable and impossible for read-only 1143root filesystems. 1144 1145.. note:: 1146 1147 There is equivalent support for pre-install, pre-uninstall, and post-uninstall 1148 scripts by way of ``pkg_preinst``, ``pkg_prerm``, and ``pkg_postrm``, 1149 respectively. These scrips work in exactly the same way as does 1150 ``pkg_postinst`` with the exception that they run at different times. Also, 1151 because of when they run, they are not applicable to being run at image 1152 creation time like ``pkg_postinst``. 1153 1154Testing 1155======= 1156 1157The final step for completing your recipe is to be sure that the 1158software you built runs correctly. To accomplish runtime testing, add 1159the build's output packages to your image and test them on the target. 1160 1161For information on how to customize your image by adding specific 1162packages, see ":ref:`dev-manual/customizing-images:customizing images`" section. 1163 1164Examples 1165======== 1166 1167To help summarize how to write a recipe, this section provides some 1168examples given various scenarios: 1169 1170- Recipes that use local files 1171 1172- Using an Autotooled package 1173 1174- Using a Makefile-based package 1175 1176- Splitting an application into multiple packages 1177 1178- Adding binaries to an image 1179 1180Single .c File Package (Hello World!) 1181------------------------------------- 1182 1183Building an application from a single file that is stored locally (e.g. 1184under ``files``) requires a recipe that has the file listed in the 1185:term:`SRC_URI` variable. Additionally, you need to manually write the 1186:ref:`ref-tasks-compile` and :ref:`ref-tasks-install` tasks. The :term:`S` variable defines the 1187directory containing the source code, which is set to 1188:term:`WORKDIR` in this case --- the 1189directory BitBake uses for the build:: 1190 1191 SUMMARY = "Simple helloworld application" 1192 SECTION = "examples" 1193 LICENSE = "MIT" 1194 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" 1195 1196 SRC_URI = "file://helloworld.c" 1197 1198 S = "${WORKDIR}" 1199 1200 do_compile() { 1201 ${CC} ${LDFLAGS} helloworld.c -o helloworld 1202 } 1203 1204 do_install() { 1205 install -d ${D}${bindir} 1206 install -m 0755 helloworld ${D}${bindir} 1207 } 1208 1209By default, the ``helloworld``, ``helloworld-dbg``, and 1210``helloworld-dev`` packages are built. For information on how to 1211customize the packaging process, see the 1212":ref:`dev-manual/new-recipe:splitting an application into multiple packages`" 1213section. 1214 1215Autotooled Package 1216------------------ 1217 1218Applications that use Autotools such as ``autoconf`` and ``automake`` 1219require a recipe that has a source archive listed in :term:`SRC_URI` and 1220also inherit the :ref:`ref-classes-autotools` class, 1221which contains the definitions of all the steps needed to build an 1222Autotool-based application. The result of the build is automatically 1223packaged. And, if the application uses NLS for localization, packages 1224with local information are generated (one package per language). 1225Following is one example: (``hello_2.3.bb``):: 1226 1227 SUMMARY = "GNU Helloworld application" 1228 SECTION = "examples" 1229 LICENSE = "GPL-2.0-or-later" 1230 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" 1231 1232 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" 1233 1234 inherit autotools gettext 1235 1236The variable :term:`LIC_FILES_CHKSUM` is used to track source license 1237changes as described in the 1238":ref:`dev-manual/licenses:tracking license changes`" section in 1239the Yocto Project Overview and Concepts Manual. You can quickly create 1240Autotool-based recipes in a manner similar to the previous example. 1241 1242Makefile-Based Package 1243---------------------- 1244 1245Applications that use GNU ``make`` also require a recipe that has the 1246source archive listed in :term:`SRC_URI`. You do not need to add a 1247:ref:`ref-tasks-compile` step since by default BitBake starts the ``make`` command 1248to compile the application. If you need additional ``make`` options, you 1249should store them in the 1250:term:`EXTRA_OEMAKE` or 1251:term:`PACKAGECONFIG_CONFARGS` 1252variables. BitBake passes these options into the GNU ``make`` 1253invocation. Note that a :ref:`ref-tasks-install` task is still required. 1254Otherwise, BitBake runs an empty :ref:`ref-tasks-install` task by default. 1255 1256Some applications might require extra parameters to be passed to the 1257compiler. For example, the application might need an additional header 1258path. You can accomplish this by adding to the :term:`CFLAGS` variable. The 1259following example shows this:: 1260 1261 CFLAGS:prepend = "-I ${S}/include " 1262 1263In the following example, ``lz4`` is a makefile-based package:: 1264 1265 SUMMARY = "Extremely Fast Compression algorithm" 1266 DESCRIPTION = "LZ4 is a very fast lossless compression algorithm, providing compression speed at 400 MB/s per core, scalable with multi-cores CPU. It also features an extremely fast decoder, with speed in multiple GB/s per core, typically reaching RAM speed limits on multi-core systems." 1267 HOMEPAGE = "https://github.com/lz4/lz4" 1268 1269 LICENSE = "BSD-2-Clause | GPL-2.0-only" 1270 LIC_FILES_CHKSUM = "file://lib/LICENSE;md5=ebc2ea4814a64de7708f1571904b32cc \ 1271 file://programs/COPYING;md5=b234ee4d69f5fce4486a80fdaf4a4263 \ 1272 file://LICENSE;md5=d57c0d21cb917fb4e0af2454aa48b956 \ 1273 " 1274 1275 PE = "1" 1276 1277 SRCREV = "d44371841a2f1728a3f36839fd4b7e872d0927d3" 1278 1279 SRC_URI = "git://github.com/lz4/lz4.git;branch=release;protocol=https \ 1280 file://CVE-2021-3520.patch \ 1281 " 1282 UPSTREAM_CHECK_GITTAGREGEX = "v(?P<pver>.*)" 1283 1284 S = "${WORKDIR}/git" 1285 1286 # Fixed in r118, which is larger than the current version. 1287 CVE_CHECK_IGNORE += "CVE-2014-4715" 1288 1289 EXTRA_OEMAKE = "PREFIX=${prefix} CC='${CC}' CFLAGS='${CFLAGS}' DESTDIR=${D} LIBDIR=${libdir} INCLUDEDIR=${includedir} BUILD_STATIC=no" 1290 1291 do_install() { 1292 oe_runmake install 1293 } 1294 1295 BBCLASSEXTEND = "native nativesdk" 1296 1297Splitting an Application into Multiple Packages 1298----------------------------------------------- 1299 1300You can use the variables :term:`PACKAGES` and :term:`FILES` to split an 1301application into multiple packages. 1302 1303Following is an example that uses the ``libxpm`` recipe. By default, 1304this recipe generates a single package that contains the library along 1305with a few binaries. You can modify the recipe to split the binaries 1306into separate packages:: 1307 1308 require xorg-lib-common.inc 1309 1310 SUMMARY = "Xpm: X Pixmap extension library" 1311 LICENSE = "MIT" 1312 LIC_FILES_CHKSUM = "file://COPYING;md5=51f4270b012ecd4ab1a164f5f4ed6cf7" 1313 DEPENDS += "libxext libsm libxt" 1314 PE = "1" 1315 1316 XORG_PN = "libXpm" 1317 1318 PACKAGES =+ "sxpm cxpm" 1319 FILES:cxpm = "${bindir}/cxpm" 1320 FILES:sxpm = "${bindir}/sxpm" 1321 1322In the previous example, we want to ship the ``sxpm`` and ``cxpm`` 1323binaries in separate packages. Since ``bindir`` would be packaged into 1324the main :term:`PN` package by default, we prepend the :term:`PACKAGES` variable 1325so additional package names are added to the start of list. This results 1326in the extra ``FILES:*`` variables then containing information that 1327define which files and directories go into which packages. Files 1328included by earlier packages are skipped by latter packages. Thus, the 1329main :term:`PN` package does not include the above listed files. 1330 1331Packaging Externally Produced Binaries 1332-------------------------------------- 1333 1334Sometimes, you need to add pre-compiled binaries to an image. For 1335example, suppose that there are binaries for proprietary code, 1336created by a particular division of a company. Your part of the company 1337needs to use those binaries as part of an image that you are building 1338using the OpenEmbedded build system. Since you only have the binaries 1339and not the source code, you cannot use a typical recipe that expects to 1340fetch the source specified in 1341:term:`SRC_URI` and then compile it. 1342 1343One method is to package the binaries and then install them as part of 1344the image. Generally, it is not a good idea to package binaries since, 1345among other things, it can hinder the ability to reproduce builds and 1346could lead to compatibility problems with ABI in the future. However, 1347sometimes you have no choice. 1348 1349The easiest solution is to create a recipe that uses the 1350:ref:`ref-classes-bin-package` class and to be sure that you are using default 1351locations for build artifacts. In most cases, the 1352:ref:`ref-classes-bin-package` class handles "skipping" the configure and 1353compile steps as well as sets things up to grab packages from the appropriate 1354area. In particular, this class sets ``noexec`` on both the 1355:ref:`ref-tasks-configure` and :ref:`ref-tasks-compile` tasks, sets 1356``FILES:${PN}`` to "/" so that it picks up all files, and sets up a 1357:ref:`ref-tasks-install` task, which effectively copies all files from ``${S}`` 1358to ``${D}``. The :ref:`ref-classes-bin-package` class works well when the files 1359extracted into ``${S}`` are already laid out in the way they should be laid out 1360on the target. For more information on these variables, see the :term:`FILES`, 1361:term:`PN`, :term:`S`, and :term:`D` variables in the Yocto Project Reference 1362Manual's variable glossary. 1363 1364.. note:: 1365 1366 - Using :term:`DEPENDS` is a good 1367 idea even for components distributed in binary form, and is often 1368 necessary for shared libraries. For a shared library, listing the 1369 library dependencies in :term:`DEPENDS` makes sure that the libraries 1370 are available in the staging sysroot when other recipes link 1371 against the library, which might be necessary for successful 1372 linking. 1373 1374 - Using :term:`DEPENDS` also allows runtime dependencies between 1375 packages to be added automatically. See the 1376 ":ref:`overview-manual/concepts:automatically added runtime dependencies`" 1377 section in the Yocto Project Overview and Concepts Manual for more 1378 information. 1379 1380If you cannot use the :ref:`ref-classes-bin-package` class, you need to be sure you are 1381doing the following: 1382 1383- Create a recipe where the 1384 :ref:`ref-tasks-configure` and 1385 :ref:`ref-tasks-compile` tasks do 1386 nothing: It is usually sufficient to just not define these tasks in 1387 the recipe, because the default implementations do nothing unless a 1388 Makefile is found in 1389 ``${``\ :term:`S`\ ``}``. 1390 1391 If ``${S}`` might contain a Makefile, or if you inherit some class 1392 that replaces :ref:`ref-tasks-configure` and :ref:`ref-tasks-compile` with custom 1393 versions, then you can use the 1394 ``[``\ :ref:`noexec <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` 1395 flag to turn the tasks into no-ops, as follows:: 1396 1397 do_configure[noexec] = "1" 1398 do_compile[noexec] = "1" 1399 1400 Unlike 1401 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:deleting a task`, 1402 using the flag preserves the dependency chain from the 1403 :ref:`ref-tasks-fetch`, 1404 :ref:`ref-tasks-unpack`, and 1405 :ref:`ref-tasks-patch` tasks to the 1406 :ref:`ref-tasks-install` task. 1407 1408- Make sure your :ref:`ref-tasks-install` task installs the binaries 1409 appropriately. 1410 1411- Ensure that you set up :term:`FILES` 1412 (usually 1413 ``FILES:${``\ :term:`PN`\ ``}``) to 1414 point to the files you have installed, which of course depends on 1415 where you have installed them and whether those files are in 1416 different locations than the defaults. 1417 1418Following Recipe Style Guidelines 1419================================= 1420 1421When writing recipes, it is good to conform to existing style 1422guidelines. The :oe_wiki:`OpenEmbedded Styleguide </Styleguide>` wiki page 1423provides rough guidelines for preferred recipe style. 1424 1425It is common for existing recipes to deviate a bit from this style. 1426However, aiming for at least a consistent style is a good idea. Some 1427practices, such as omitting spaces around ``=`` operators in assignments 1428or ordering recipe components in an erratic way, are widely seen as poor 1429style. 1430 1431Recipe Syntax 1432============= 1433 1434Understanding recipe file syntax is important for writing recipes. The 1435following list overviews the basic items that make up a BitBake recipe 1436file. For more complete BitBake syntax descriptions, see the 1437":doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata`" 1438chapter of the BitBake User Manual. 1439 1440- *Variable Assignments and Manipulations:* Variable assignments allow 1441 a value to be assigned to a variable. The assignment can be static 1442 text or might include the contents of other variables. In addition to 1443 the assignment, appending and prepending operations are also 1444 supported. 1445 1446 The following example shows some of the ways you can use variables in 1447 recipes:: 1448 1449 S = "${WORKDIR}/postfix-${PV}" 1450 CFLAGS += "-DNO_ASM" 1451 CFLAGS:append = " --enable-important-feature" 1452 1453- *Functions:* Functions provide a series of actions to be performed. 1454 You usually use functions to override the default implementation of a 1455 task function or to complement a default function (i.e. append or 1456 prepend to an existing function). Standard functions use ``sh`` shell 1457 syntax, although access to OpenEmbedded variables and internal 1458 methods are also available. 1459 1460 Here is an example function from the ``sed`` recipe:: 1461 1462 do_install () { 1463 autotools_do_install 1464 install -d ${D}${base_bindir} 1465 mv ${D}${bindir}/sed ${D}${base_bindir}/sed 1466 rmdir ${D}${bindir}/ 1467 } 1468 1469 It is 1470 also possible to implement new functions that are called between 1471 existing tasks as long as the new functions are not replacing or 1472 complementing the default functions. You can implement functions in 1473 Python instead of shell. Both of these options are not seen in the 1474 majority of recipes. 1475 1476- *Keywords:* BitBake recipes use only a few keywords. You use keywords 1477 to include common functions (``inherit``), load parts of a recipe 1478 from other files (``include`` and ``require``) and export variables 1479 to the environment (``export``). 1480 1481 The following example shows the use of some of these keywords:: 1482 1483 export POSTCONF = "${STAGING_BINDIR}/postconf" 1484 inherit autoconf 1485 require otherfile.inc 1486 1487- *Comments (#):* Any lines that begin with the hash character (``#``) 1488 are treated as comment lines and are ignored:: 1489 1490 # This is a comment 1491 1492This next list summarizes the most important and most commonly used 1493parts of the recipe syntax. For more information on these parts of the 1494syntax, you can reference the 1495":doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata`" chapter 1496in the BitBake User Manual. 1497 1498- *Line Continuation (\\):* Use the backward slash (``\``) character to 1499 split a statement over multiple lines. Place the slash character at 1500 the end of the line that is to be continued on the next line:: 1501 1502 VAR = "A really long \ 1503 line" 1504 1505 .. note:: 1506 1507 You cannot have any characters including spaces or tabs after the 1508 slash character. 1509 1510- *Using Variables (${VARNAME}):* Use the ``${VARNAME}`` syntax to 1511 access the contents of a variable:: 1512 1513 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" 1514 1515 .. note:: 1516 1517 It is important to understand that the value of a variable 1518 expressed in this form does not get substituted automatically. The 1519 expansion of these expressions happens on-demand later (e.g. 1520 usually when a function that makes reference to the variable 1521 executes). This behavior ensures that the values are most 1522 appropriate for the context in which they are finally used. On the 1523 rare occasion that you do need the variable expression to be 1524 expanded immediately, you can use the 1525 := 1526 operator instead of 1527 = 1528 when you make the assignment, but this is not generally needed. 1529 1530- *Quote All Assignments ("value"):* Use double quotes around values in 1531 all variable assignments (e.g. ``"value"``). Following is an example:: 1532 1533 VAR1 = "${OTHERVAR}" 1534 VAR2 = "The version is ${PV}" 1535 1536- *Conditional Assignment (?=):* Conditional assignment is used to 1537 assign a value to a variable, but only when the variable is currently 1538 unset. Use the question mark followed by the equal sign (``?=``) to 1539 make a "soft" assignment used for conditional assignment. Typically, 1540 "soft" assignments are used in the ``local.conf`` file for variables 1541 that are allowed to come through from the external environment. 1542 1543 Here is an example where ``VAR1`` is set to "New value" if it is 1544 currently empty. However, if ``VAR1`` has already been set, it 1545 remains unchanged:: 1546 1547 VAR1 ?= "New value" 1548 1549 In this next example, ``VAR1`` is left with the value "Original value":: 1550 1551 VAR1 = "Original value" 1552 VAR1 ?= "New value" 1553 1554- *Appending (+=):* Use the plus character followed by the equals sign 1555 (``+=``) to append values to existing variables. 1556 1557 .. note:: 1558 1559 This operator adds a space between the existing content of the 1560 variable and the new content. 1561 1562 Here is an example:: 1563 1564 SRC_URI += "file://fix-makefile.patch" 1565 1566- *Prepending (=+):* Use the equals sign followed by the plus character 1567 (``=+``) to prepend values to existing variables. 1568 1569 .. note:: 1570 1571 This operator adds a space between the new content and the 1572 existing content of the variable. 1573 1574 Here is an example:: 1575 1576 VAR =+ "Starts" 1577 1578- *Appending (:append):* Use the ``:append`` operator to append values 1579 to existing variables. This operator does not add any additional 1580 space. Also, the operator is applied after all the ``+=``, and ``=+`` 1581 operators have been applied and after all ``=`` assignments have 1582 occurred. This means that if ``:append`` is used in a recipe, it can 1583 only be overridden by another layer using the special ``:remove`` 1584 operator, which in turn will prevent further layers from adding it back. 1585 1586 The following example shows the space being explicitly added to the 1587 start to ensure the appended value is not merged with the existing 1588 value:: 1589 1590 CFLAGS:append = " --enable-important-feature" 1591 1592 You can also use 1593 the ``:append`` operator with overrides, which results in the actions 1594 only being performed for the specified target or machine:: 1595 1596 CFLAGS:append:sh4 = " --enable-important-sh4-specific-feature" 1597 1598- *Prepending (:prepend):* Use the ``:prepend`` operator to prepend 1599 values to existing variables. This operator does not add any 1600 additional space. Also, the operator is applied after all the ``+=``, 1601 and ``=+`` operators have been applied and after all ``=`` 1602 assignments have occurred. 1603 1604 The following example shows the space being explicitly added to the 1605 end to ensure the prepended value is not merged with the existing 1606 value:: 1607 1608 CFLAGS:prepend = "-I${S}/myincludes " 1609 1610 You can also use the 1611 ``:prepend`` operator with overrides, which results in the actions 1612 only being performed for the specified target or machine:: 1613 1614 CFLAGS:prepend:sh4 = "-I${S}/myincludes " 1615 1616- *Overrides:* You can use overrides to set a value conditionally, 1617 typically based on how the recipe is being built. For example, to set 1618 the :term:`KBRANCH` variable's 1619 value to "standard/base" for any target 1620 :term:`MACHINE`, except for 1621 qemuarm where it should be set to "standard/arm-versatile-926ejs", 1622 you would do the following:: 1623 1624 KBRANCH = "standard/base" 1625 KBRANCH:qemuarm = "standard/arm-versatile-926ejs" 1626 1627 Overrides are also used to separate 1628 alternate values of a variable in other situations. For example, when 1629 setting variables such as 1630 :term:`FILES` and 1631 :term:`RDEPENDS` that are 1632 specific to individual packages produced by a recipe, you should 1633 always use an override that specifies the name of the package. 1634 1635- *Indentation:* Use spaces for indentation rather than tabs. For 1636 shell functions, both currently work. However, it is a policy 1637 decision of the Yocto Project to use tabs in shell functions. Realize 1638 that some layers have a policy to use spaces for all indentation. 1639 1640- *Using Python for Complex Operations:* For more advanced processing, 1641 it is possible to use Python code during variable assignments (e.g. 1642 search and replacement on a variable). 1643 1644 You indicate Python code using the ``${@python_code}`` syntax for the 1645 variable assignment:: 1646 1647 SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz 1648 1649- *Shell Function Syntax:* Write shell functions as if you were writing 1650 a shell script when you describe a list of actions to take. You 1651 should ensure that your script works with a generic ``sh`` and that 1652 it does not require any ``bash`` or other shell-specific 1653 functionality. The same considerations apply to various system 1654 utilities (e.g. ``sed``, ``grep``, ``awk``, and so forth) that you 1655 might wish to use. If in doubt, you should check with multiple 1656 implementations --- including those from BusyBox. 1657 1658