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