diff options
Diffstat (limited to 'documentation/dev-manual/layers.rst')
-rw-r--r-- | documentation/dev-manual/layers.rst | 919 |
1 files changed, 919 insertions, 0 deletions
diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst new file mode 100644 index 0000000000..91889bd0ae --- /dev/null +++ b/documentation/dev-manual/layers.rst | |||
@@ -0,0 +1,919 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | Understanding and Creating Layers | ||
4 | ********************************* | ||
5 | |||
6 | The OpenEmbedded build system supports organizing | ||
7 | :term:`Metadata` into multiple layers. | ||
8 | Layers allow you to isolate different types of customizations from each | ||
9 | other. For introductory information on the Yocto Project Layer Model, | ||
10 | see the | ||
11 | ":ref:`overview-manual/yp-intro:the yocto project layer model`" | ||
12 | section in the Yocto Project Overview and Concepts Manual. | ||
13 | |||
14 | Creating Your Own Layer | ||
15 | ======================= | ||
16 | |||
17 | .. note:: | ||
18 | |||
19 | It is very easy to create your own layers to use with the OpenEmbedded | ||
20 | build system, as the Yocto Project ships with tools that speed up creating | ||
21 | layers. This section describes the steps you perform by hand to create | ||
22 | layers so that you can better understand them. For information about the | ||
23 | layer-creation tools, see the | ||
24 | ":ref:`bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script`" | ||
25 | section in the Yocto Project Board Support Package (BSP) Developer's | ||
26 | Guide and the ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" | ||
27 | section further down in this manual. | ||
28 | |||
29 | Follow these general steps to create your layer without using tools: | ||
30 | |||
31 | #. *Check Existing Layers:* Before creating a new layer, you should be | ||
32 | sure someone has not already created a layer containing the Metadata | ||
33 | you need. You can see the :oe_layerindex:`OpenEmbedded Metadata Index <>` | ||
34 | for a list of layers from the OpenEmbedded community that can be used in | ||
35 | the Yocto Project. You could find a layer that is identical or close | ||
36 | to what you need. | ||
37 | |||
38 | #. *Create a Directory:* Create the directory for your layer. When you | ||
39 | create the layer, be sure to create the directory in an area not | ||
40 | associated with the Yocto Project :term:`Source Directory` | ||
41 | (e.g. the cloned ``poky`` repository). | ||
42 | |||
43 | While not strictly required, prepend the name of the directory with | ||
44 | the string "meta-". For example:: | ||
45 | |||
46 | meta-mylayer | ||
47 | meta-GUI_xyz | ||
48 | meta-mymachine | ||
49 | |||
50 | With rare exceptions, a layer's name follows this form:: | ||
51 | |||
52 | meta-root_name | ||
53 | |||
54 | Following this layer naming convention can save | ||
55 | you trouble later when tools, components, or variables "assume" your | ||
56 | layer name begins with "meta-". A notable example is in configuration | ||
57 | files as shown in the following step where layer names without the | ||
58 | "meta-" string are appended to several variables used in the | ||
59 | configuration. | ||
60 | |||
61 | #. *Create a Layer Configuration File:* Inside your new layer folder, | ||
62 | you need to create a ``conf/layer.conf`` file. It is easiest to take | ||
63 | an existing layer configuration file and copy that to your layer's | ||
64 | ``conf`` directory and then modify the file as needed. | ||
65 | |||
66 | The ``meta-yocto-bsp/conf/layer.conf`` file in the Yocto Project | ||
67 | :yocto_git:`Source Repositories </poky/tree/meta-yocto-bsp/conf>` | ||
68 | demonstrates the required syntax. For your layer, you need to replace | ||
69 | "yoctobsp" with a unique identifier for your layer (e.g. "machinexyz" | ||
70 | for a layer named "meta-machinexyz"):: | ||
71 | |||
72 | # We have a conf and classes directory, add to BBPATH | ||
73 | BBPATH .= ":${LAYERDIR}" | ||
74 | |||
75 | # We have recipes-* directories, add to BBFILES | ||
76 | BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ | ||
77 | ${LAYERDIR}/recipes-*/*/*.bbappend" | ||
78 | |||
79 | BBFILE_COLLECTIONS += "yoctobsp" | ||
80 | BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" | ||
81 | BBFILE_PRIORITY_yoctobsp = "5" | ||
82 | LAYERVERSION_yoctobsp = "4" | ||
83 | LAYERSERIES_COMPAT_yoctobsp = "dunfell" | ||
84 | |||
85 | Here is an explanation of the layer configuration file: | ||
86 | |||
87 | - :term:`BBPATH`: Adds the layer's | ||
88 | root directory to BitBake's search path. Through the use of the | ||
89 | :term:`BBPATH` variable, BitBake locates class files (``.bbclass``), | ||
90 | configuration files, and files that are included with ``include`` | ||
91 | and ``require`` statements. For these cases, BitBake uses the | ||
92 | first file that matches the name found in :term:`BBPATH`. This is | ||
93 | similar to the way the ``PATH`` variable is used for binaries. It | ||
94 | is recommended, therefore, that you use unique class and | ||
95 | configuration filenames in your custom layer. | ||
96 | |||
97 | - :term:`BBFILES`: Defines the | ||
98 | location for all recipes in the layer. | ||
99 | |||
100 | - :term:`BBFILE_COLLECTIONS`: | ||
101 | Establishes the current layer through a unique identifier that is | ||
102 | used throughout the OpenEmbedded build system to refer to the | ||
103 | layer. In this example, the identifier "yoctobsp" is the | ||
104 | representation for the container layer named "meta-yocto-bsp". | ||
105 | |||
106 | - :term:`BBFILE_PATTERN`: | ||
107 | Expands immediately during parsing to provide the directory of the | ||
108 | layer. | ||
109 | |||
110 | - :term:`BBFILE_PRIORITY`: | ||
111 | Establishes a priority to use for recipes in the layer when the | ||
112 | OpenEmbedded build finds recipes of the same name in different | ||
113 | layers. | ||
114 | |||
115 | - :term:`LAYERVERSION`: | ||
116 | Establishes a version number for the layer. You can use this | ||
117 | version number to specify this exact version of the layer as a | ||
118 | dependency when using the | ||
119 | :term:`LAYERDEPENDS` | ||
120 | variable. | ||
121 | |||
122 | - :term:`LAYERDEPENDS`: | ||
123 | Lists all layers on which this layer depends (if any). | ||
124 | |||
125 | - :term:`LAYERSERIES_COMPAT`: | ||
126 | Lists the :yocto_wiki:`Yocto Project </Releases>` | ||
127 | releases for which the current version is compatible. This | ||
128 | variable is a good way to indicate if your particular layer is | ||
129 | current. | ||
130 | |||
131 | |||
132 | .. note:: | ||
133 | |||
134 | A layer does not have to contain only recipes ``.bb`` or append files | ||
135 | ``.bbappend``. Generally, developers create layers using | ||
136 | ``bitbake-layers create-layer``. | ||
137 | See ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`", | ||
138 | explaining how the ``layer.conf`` file is created from a template located in | ||
139 | ``meta/lib/bblayers/templates/layer.conf``. | ||
140 | In fact, none of the variables set in ``layer.conf`` are mandatory, | ||
141 | except when :term:`BBFILE_COLLECTIONS` is present. In this case | ||
142 | :term:`LAYERSERIES_COMPAT` and :term:`BBFILE_PATTERN` have to be | ||
143 | defined too. | ||
144 | |||
145 | #. *Add Content:* Depending on the type of layer, add the content. If | ||
146 | the layer adds support for a machine, add the machine configuration | ||
147 | in a ``conf/machine/`` file within the layer. If the layer adds | ||
148 | distro policy, add the distro configuration in a ``conf/distro/`` | ||
149 | file within the layer. If the layer introduces new recipes, put the | ||
150 | recipes you need in ``recipes-*`` subdirectories within the layer. | ||
151 | |||
152 | .. note:: | ||
153 | |||
154 | For an explanation of layer hierarchy that is compliant with the | ||
155 | Yocto Project, see the ":ref:`bsp-guide/bsp:example filesystem layout`" | ||
156 | section in the Yocto Project Board Support Package (BSP) Developer's Guide. | ||
157 | |||
158 | #. *Optionally Test for Compatibility:* If you want permission to use | ||
159 | the Yocto Project Compatibility logo with your layer or application | ||
160 | that uses your layer, perform the steps to apply for compatibility. | ||
161 | See the | ||
162 | ":ref:`dev-manual/layers:making sure your layer is compatible with yocto project`" | ||
163 | section for more information. | ||
164 | |||
165 | Following Best Practices When Creating Layers | ||
166 | ============================================= | ||
167 | |||
168 | To create layers that are easier to maintain and that will not impact | ||
169 | builds for other machines, you should consider the information in the | ||
170 | following list: | ||
171 | |||
172 | - *Avoid "Overlaying" Entire Recipes from Other Layers in Your | ||
173 | Configuration:* In other words, do not copy an entire recipe into | ||
174 | your layer and then modify it. Rather, use an append file | ||
175 | (``.bbappend``) to override only those parts of the original recipe | ||
176 | you need to modify. | ||
177 | |||
178 | - *Avoid Duplicating Include Files:* Use append files (``.bbappend``) | ||
179 | for each recipe that uses an include file. Or, if you are introducing | ||
180 | a new recipe that requires the included file, use the path relative | ||
181 | to the original layer directory to refer to the file. For example, | ||
182 | use ``require recipes-core/``\ `package`\ ``/``\ `file`\ ``.inc`` instead | ||
183 | of ``require`` `file`\ ``.inc``. If you're finding you have to overlay | ||
184 | the include file, it could indicate a deficiency in the include file | ||
185 | in the layer to which it originally belongs. If this is the case, you | ||
186 | should try to address that deficiency instead of overlaying the | ||
187 | include file. For example, you could address this by getting the | ||
188 | maintainer of the include file to add a variable or variables to make | ||
189 | it easy to override the parts needing to be overridden. | ||
190 | |||
191 | - *Structure Your Layers:* Proper use of overrides within append files | ||
192 | and placement of machine-specific files within your layer can ensure | ||
193 | that a build is not using the wrong Metadata and negatively impacting | ||
194 | a build for a different machine. Here are some examples: | ||
195 | |||
196 | - *Modify Variables to Support a Different Machine:* Suppose you | ||
197 | have a layer named ``meta-one`` that adds support for building | ||
198 | machine "one". To do so, you use an append file named | ||
199 | ``base-files.bbappend`` and create a dependency on "foo" by | ||
200 | altering the :term:`DEPENDS` | ||
201 | variable:: | ||
202 | |||
203 | DEPENDS = "foo" | ||
204 | |||
205 | The dependency is created during any | ||
206 | build that includes the layer ``meta-one``. However, you might not | ||
207 | want this dependency for all machines. For example, suppose you | ||
208 | are building for machine "two" but your ``bblayers.conf`` file has | ||
209 | the ``meta-one`` layer included. During the build, the | ||
210 | ``base-files`` for machine "two" will also have the dependency on | ||
211 | ``foo``. | ||
212 | |||
213 | To make sure your changes apply only when building machine "one", | ||
214 | use a machine override with the :term:`DEPENDS` statement:: | ||
215 | |||
216 | DEPENDS:one = "foo" | ||
217 | |||
218 | You should follow the same strategy when using ``:append`` | ||
219 | and ``:prepend`` operations:: | ||
220 | |||
221 | DEPENDS:append:one = " foo" | ||
222 | DEPENDS:prepend:one = "foo " | ||
223 | |||
224 | As an actual example, here's a | ||
225 | snippet from the generic kernel include file ``linux-yocto.inc``, | ||
226 | wherein the kernel compile and link options are adjusted in the | ||
227 | case of a subset of the supported architectures:: | ||
228 | |||
229 | DEPENDS:append:aarch64 = " libgcc" | ||
230 | KERNEL_CC:append:aarch64 = " ${TOOLCHAIN_OPTIONS}" | ||
231 | KERNEL_LD:append:aarch64 = " ${TOOLCHAIN_OPTIONS}" | ||
232 | |||
233 | DEPENDS:append:nios2 = " libgcc" | ||
234 | KERNEL_CC:append:nios2 = " ${TOOLCHAIN_OPTIONS}" | ||
235 | KERNEL_LD:append:nios2 = " ${TOOLCHAIN_OPTIONS}" | ||
236 | |||
237 | DEPENDS:append:arc = " libgcc" | ||
238 | KERNEL_CC:append:arc = " ${TOOLCHAIN_OPTIONS}" | ||
239 | KERNEL_LD:append:arc = " ${TOOLCHAIN_OPTIONS}" | ||
240 | |||
241 | KERNEL_FEATURES:append:qemuall=" features/debug/printk.scc" | ||
242 | |||
243 | - *Place Machine-Specific Files in Machine-Specific Locations:* When | ||
244 | you have a base recipe, such as ``base-files.bb``, that contains a | ||
245 | :term:`SRC_URI` statement to a | ||
246 | file, you can use an append file to cause the build to use your | ||
247 | own version of the file. For example, an append file in your layer | ||
248 | at ``meta-one/recipes-core/base-files/base-files.bbappend`` could | ||
249 | extend :term:`FILESPATH` using :term:`FILESEXTRAPATHS` as follows:: | ||
250 | |||
251 | FILESEXTRAPATHS:prepend := "${THISDIR}/${BPN}:" | ||
252 | |||
253 | The build for machine "one" will pick up your machine-specific file as | ||
254 | long as you have the file in | ||
255 | ``meta-one/recipes-core/base-files/base-files/``. However, if you | ||
256 | are building for a different machine and the ``bblayers.conf`` | ||
257 | file includes the ``meta-one`` layer and the location of your | ||
258 | machine-specific file is the first location where that file is | ||
259 | found according to :term:`FILESPATH`, builds for all machines will | ||
260 | also use that machine-specific file. | ||
261 | |||
262 | You can make sure that a machine-specific file is used for a | ||
263 | particular machine by putting the file in a subdirectory specific | ||
264 | to the machine. For example, rather than placing the file in | ||
265 | ``meta-one/recipes-core/base-files/base-files/`` as shown above, | ||
266 | put it in ``meta-one/recipes-core/base-files/base-files/one/``. | ||
267 | Not only does this make sure the file is used only when building | ||
268 | for machine "one", but the build process locates the file more | ||
269 | quickly. | ||
270 | |||
271 | In summary, you need to place all files referenced from | ||
272 | :term:`SRC_URI` in a machine-specific subdirectory within the layer in | ||
273 | order to restrict those files to machine-specific builds. | ||
274 | |||
275 | - *Perform Steps to Apply for Yocto Project Compatibility:* If you want | ||
276 | permission to use the Yocto Project Compatibility logo with your | ||
277 | layer or application that uses your layer, perform the steps to apply | ||
278 | for compatibility. See the | ||
279 | ":ref:`dev-manual/layers:making sure your layer is compatible with yocto project`" | ||
280 | section for more information. | ||
281 | |||
282 | - *Follow the Layer Naming Convention:* Store custom layers in a Git | ||
283 | repository that use the ``meta-layer_name`` format. | ||
284 | |||
285 | - *Group Your Layers Locally:* Clone your repository alongside other | ||
286 | cloned ``meta`` directories from the :term:`Source Directory`. | ||
287 | |||
288 | Making Sure Your Layer is Compatible With Yocto Project | ||
289 | ======================================================= | ||
290 | |||
291 | When you create a layer used with the Yocto Project, it is advantageous | ||
292 | to make sure that the layer interacts well with existing Yocto Project | ||
293 | layers (i.e. the layer is compatible with the Yocto Project). Ensuring | ||
294 | compatibility makes the layer easy to be consumed by others in the Yocto | ||
295 | Project community and could allow you permission to use the Yocto | ||
296 | Project Compatible Logo. | ||
297 | |||
298 | .. note:: | ||
299 | |||
300 | Only Yocto Project member organizations are permitted to use the | ||
301 | Yocto Project Compatible Logo. The logo is not available for general | ||
302 | use. For information on how to become a Yocto Project member | ||
303 | organization, see the :yocto_home:`Yocto Project Website <>`. | ||
304 | |||
305 | The Yocto Project Compatibility Program consists of a layer application | ||
306 | process that requests permission to use the Yocto Project Compatibility | ||
307 | Logo for your layer and application. The process consists of two parts: | ||
308 | |||
309 | #. Successfully passing a script (``yocto-check-layer``) that when run | ||
310 | against your layer, tests it against constraints based on experiences | ||
311 | of how layers have worked in the real world and where pitfalls have | ||
312 | been found. Getting a "PASS" result from the script is required for | ||
313 | successful compatibility registration. | ||
314 | |||
315 | #. Completion of an application acceptance form, which you can find at | ||
316 | :yocto_home:`/compatible-registration/`. | ||
317 | |||
318 | To be granted permission to use the logo, you need to satisfy the | ||
319 | following: | ||
320 | |||
321 | - Be able to check the box indicating that you got a "PASS" when | ||
322 | running the script against your layer. | ||
323 | |||
324 | - Answer "Yes" to the questions on the form or have an acceptable | ||
325 | explanation for any questions answered "No". | ||
326 | |||
327 | - Be a Yocto Project Member Organization. | ||
328 | |||
329 | The remainder of this section presents information on the registration | ||
330 | form and on the ``yocto-check-layer`` script. | ||
331 | |||
332 | Yocto Project Compatible Program Application | ||
333 | -------------------------------------------- | ||
334 | |||
335 | Use the form to apply for your layer's approval. Upon successful | ||
336 | application, you can use the Yocto Project Compatibility Logo with your | ||
337 | layer and the application that uses your layer. | ||
338 | |||
339 | To access the form, use this link: | ||
340 | :yocto_home:`/compatible-registration`. | ||
341 | Follow the instructions on the form to complete your application. | ||
342 | |||
343 | The application consists of the following sections: | ||
344 | |||
345 | - *Contact Information:* Provide your contact information as the fields | ||
346 | require. Along with your information, provide the released versions | ||
347 | of the Yocto Project for which your layer is compatible. | ||
348 | |||
349 | - *Acceptance Criteria:* Provide "Yes" or "No" answers for each of the | ||
350 | items in the checklist. There is space at the bottom of the form for | ||
351 | any explanations for items for which you answered "No". | ||
352 | |||
353 | - *Recommendations:* Provide answers for the questions regarding Linux | ||
354 | kernel use and build success. | ||
355 | |||
356 | ``yocto-check-layer`` Script | ||
357 | ---------------------------- | ||
358 | |||
359 | The ``yocto-check-layer`` script provides you a way to assess how | ||
360 | compatible your layer is with the Yocto Project. You should run this | ||
361 | script prior to using the form to apply for compatibility as described | ||
362 | in the previous section. You need to achieve a "PASS" result in order to | ||
363 | have your application form successfully processed. | ||
364 | |||
365 | The script divides tests into three areas: COMMON, BSP, and DISTRO. For | ||
366 | example, given a distribution layer (DISTRO), the layer must pass both | ||
367 | the COMMON and DISTRO related tests. Furthermore, if your layer is a BSP | ||
368 | layer, the layer must pass the COMMON and BSP set of tests. | ||
369 | |||
370 | To execute the script, enter the following commands from your build | ||
371 | directory:: | ||
372 | |||
373 | $ source oe-init-build-env | ||
374 | $ yocto-check-layer your_layer_directory | ||
375 | |||
376 | Be sure to provide the actual directory for your | ||
377 | layer as part of the command. | ||
378 | |||
379 | Entering the command causes the script to determine the type of layer | ||
380 | and then to execute a set of specific tests against the layer. The | ||
381 | following list overviews the test: | ||
382 | |||
383 | - ``common.test_readme``: Tests if a ``README`` file exists in the | ||
384 | layer and the file is not empty. | ||
385 | |||
386 | - ``common.test_parse``: Tests to make sure that BitBake can parse the | ||
387 | files without error (i.e. ``bitbake -p``). | ||
388 | |||
389 | - ``common.test_show_environment``: Tests that the global or per-recipe | ||
390 | environment is in order without errors (i.e. ``bitbake -e``). | ||
391 | |||
392 | - ``common.test_world``: Verifies that ``bitbake world`` works. | ||
393 | |||
394 | - ``common.test_signatures``: Tests to be sure that BSP and DISTRO | ||
395 | layers do not come with recipes that change signatures. | ||
396 | |||
397 | - ``common.test_layerseries_compat``: Verifies layer compatibility is | ||
398 | set properly. | ||
399 | |||
400 | - ``bsp.test_bsp_defines_machines``: Tests if a BSP layer has machine | ||
401 | configurations. | ||
402 | |||
403 | - ``bsp.test_bsp_no_set_machine``: Tests to ensure a BSP layer does not | ||
404 | set the machine when the layer is added. | ||
405 | |||
406 | - ``bsp.test_machine_world``: Verifies that ``bitbake world`` works | ||
407 | regardless of which machine is selected. | ||
408 | |||
409 | - ``bsp.test_machine_signatures``: Verifies that building for a | ||
410 | particular machine affects only the signature of tasks specific to | ||
411 | that machine. | ||
412 | |||
413 | - ``distro.test_distro_defines_distros``: Tests if a DISTRO layer has | ||
414 | distro configurations. | ||
415 | |||
416 | - ``distro.test_distro_no_set_distros``: Tests to ensure a DISTRO layer | ||
417 | does not set the distribution when the layer is added. | ||
418 | |||
419 | Enabling Your Layer | ||
420 | =================== | ||
421 | |||
422 | Before the OpenEmbedded build system can use your new layer, you need to | ||
423 | enable it. To enable your layer, simply add your layer's path to the | ||
424 | :term:`BBLAYERS` variable in your ``conf/bblayers.conf`` file, which is | ||
425 | found in the :term:`Build Directory`. The following example shows how to | ||
426 | enable your new ``meta-mylayer`` layer (note how your new layer exists | ||
427 | outside of the official ``poky`` repository which you would have checked | ||
428 | out earlier):: | ||
429 | |||
430 | # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf | ||
431 | # changes incompatibly | ||
432 | POKY_BBLAYERS_CONF_VERSION = "2" | ||
433 | BBPATH = "${TOPDIR}" | ||
434 | BBFILES ?= "" | ||
435 | BBLAYERS ?= " \ | ||
436 | /home/user/poky/meta \ | ||
437 | /home/user/poky/meta-poky \ | ||
438 | /home/user/poky/meta-yocto-bsp \ | ||
439 | /home/user/mystuff/meta-mylayer \ | ||
440 | " | ||
441 | |||
442 | BitBake parses each ``conf/layer.conf`` file from the top down as | ||
443 | specified in the :term:`BBLAYERS` variable within the ``conf/bblayers.conf`` | ||
444 | file. During the processing of each ``conf/layer.conf`` file, BitBake | ||
445 | adds the recipes, classes and configurations contained within the | ||
446 | particular layer to the source directory. | ||
447 | |||
448 | Appending Other Layers Metadata With Your Layer | ||
449 | =============================================== | ||
450 | |||
451 | A recipe that appends Metadata to another recipe is called a BitBake | ||
452 | append file. A BitBake append file uses the ``.bbappend`` file type | ||
453 | suffix, while the corresponding recipe to which Metadata is being | ||
454 | appended uses the ``.bb`` file type suffix. | ||
455 | |||
456 | You can use a ``.bbappend`` file in your layer to make additions or | ||
457 | changes to the content of another layer's recipe without having to copy | ||
458 | the other layer's recipe into your layer. Your ``.bbappend`` file | ||
459 | resides in your layer, while the main ``.bb`` recipe file to which you | ||
460 | are appending Metadata resides in a different layer. | ||
461 | |||
462 | Being able to append information to an existing recipe not only avoids | ||
463 | duplication, but also automatically applies recipe changes from a | ||
464 | different layer into your layer. If you were copying recipes, you would | ||
465 | have to manually merge changes as they occur. | ||
466 | |||
467 | When you create an append file, you must use the same root name as the | ||
468 | corresponding recipe file. For example, the append file | ||
469 | ``someapp_3.1.bbappend`` must apply to ``someapp_3.1.bb``. This | ||
470 | means the original recipe and append filenames are version | ||
471 | number-specific. If the corresponding recipe is renamed to update to a | ||
472 | newer version, you must also rename and possibly update the | ||
473 | corresponding ``.bbappend`` as well. During the build process, BitBake | ||
474 | displays an error on starting if it detects a ``.bbappend`` file that | ||
475 | does not have a corresponding recipe with a matching name. See the | ||
476 | :term:`BB_DANGLINGAPPENDS_WARNONLY` | ||
477 | variable for information on how to handle this error. | ||
478 | |||
479 | Overlaying a File Using Your Layer | ||
480 | ---------------------------------- | ||
481 | |||
482 | As an example, consider the main formfactor recipe and a corresponding | ||
483 | formfactor append file both from the :term:`Source Directory`. | ||
484 | Here is the main | ||
485 | formfactor recipe, which is named ``formfactor_0.0.bb`` and located in | ||
486 | the "meta" layer at ``meta/recipes-bsp/formfactor``:: | ||
487 | |||
488 | SUMMARY = "Device formfactor information" | ||
489 | DESCRIPTION = "A formfactor configuration file provides information about the \ | ||
490 | target hardware for which the image is being built and information that the \ | ||
491 | build system cannot obtain from other sources such as the kernel." | ||
492 | SECTION = "base" | ||
493 | LICENSE = "MIT" | ||
494 | LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" | ||
495 | PR = "r45" | ||
496 | |||
497 | SRC_URI = "file://config file://machconfig" | ||
498 | S = "${WORKDIR}" | ||
499 | |||
500 | PACKAGE_ARCH = "${MACHINE_ARCH}" | ||
501 | INHIBIT_DEFAULT_DEPS = "1" | ||
502 | |||
503 | do_install() { | ||
504 | # Install file only if it has contents | ||
505 | install -d ${D}${sysconfdir}/formfactor/ | ||
506 | install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/ | ||
507 | if [ -s "${S}/machconfig" ]; then | ||
508 | install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ | ||
509 | fi | ||
510 | } | ||
511 | |||
512 | In the main recipe, note the :term:`SRC_URI` | ||
513 | variable, which tells the OpenEmbedded build system where to find files | ||
514 | during the build. | ||
515 | |||
516 | Here is the append file, which is named ``formfactor_0.0.bbappend`` | ||
517 | and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The | ||
518 | file is in the layer at ``recipes-bsp/formfactor``:: | ||
519 | |||
520 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" | ||
521 | |||
522 | By default, the build system uses the | ||
523 | :term:`FILESPATH` variable to | ||
524 | locate files. This append file extends the locations by setting the | ||
525 | :term:`FILESEXTRAPATHS` | ||
526 | variable. Setting this variable in the ``.bbappend`` file is the most | ||
527 | reliable and recommended method for adding directories to the search | ||
528 | path used by the build system to find files. | ||
529 | |||
530 | The statement in this example extends the directories to include | ||
531 | ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``, | ||
532 | which resolves to a directory named ``formfactor`` in the same directory | ||
533 | in which the append file resides (i.e. | ||
534 | ``meta-raspberrypi/recipes-bsp/formfactor``. This implies that you must | ||
535 | have the supporting directory structure set up that will contain any | ||
536 | files or patches you will be including from the layer. | ||
537 | |||
538 | Using the immediate expansion assignment operator ``:=`` is important | ||
539 | because of the reference to :term:`THISDIR`. The trailing colon character is | ||
540 | important as it ensures that items in the list remain colon-separated. | ||
541 | |||
542 | .. note:: | ||
543 | |||
544 | BitBake automatically defines the :term:`THISDIR` variable. You should | ||
545 | never set this variable yourself. Using ":prepend" as part of the | ||
546 | :term:`FILESEXTRAPATHS` ensures your path will be searched prior to other | ||
547 | paths in the final list. | ||
548 | |||
549 | Also, not all append files add extra files. Many append files simply | ||
550 | allow to add build options (e.g. ``systemd``). For these cases, your | ||
551 | append file would not even use the :term:`FILESEXTRAPATHS` statement. | ||
552 | |||
553 | The end result of this ``.bbappend`` file is that on a Raspberry Pi, where | ||
554 | ``rpi`` will exist in the list of :term:`OVERRIDES`, the file | ||
555 | ``meta-raspberrypi/recipes-bsp/formfactor/formfactor/rpi/machconfig`` will be | ||
556 | used during :ref:`ref-tasks-fetch` and the test for a non-zero file size in | ||
557 | :ref:`ref-tasks-install` will return true, and the file will be installed. | ||
558 | |||
559 | Installing Additional Files Using Your Layer | ||
560 | -------------------------------------------- | ||
561 | |||
562 | As another example, consider the main ``xserver-xf86-config`` recipe and a | ||
563 | corresponding ``xserver-xf86-config`` append file both from the :term:`Source | ||
564 | Directory`. Here is the main ``xserver-xf86-config`` recipe, which is named | ||
565 | ``xserver-xf86-config_0.1.bb`` and located in the "meta" layer at | ||
566 | ``meta/recipes-graphics/xorg-xserver``:: | ||
567 | |||
568 | SUMMARY = "X.Org X server configuration file" | ||
569 | HOMEPAGE = "http://www.x.org" | ||
570 | SECTION = "x11/base" | ||
571 | LICENSE = "MIT" | ||
572 | LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" | ||
573 | PR = "r33" | ||
574 | |||
575 | SRC_URI = "file://xorg.conf" | ||
576 | |||
577 | S = "${WORKDIR}" | ||
578 | |||
579 | CONFFILES:${PN} = "${sysconfdir}/X11/xorg.conf" | ||
580 | |||
581 | PACKAGE_ARCH = "${MACHINE_ARCH}" | ||
582 | ALLOW_EMPTY:${PN} = "1" | ||
583 | |||
584 | do_install () { | ||
585 | if test -s ${WORKDIR}/xorg.conf; then | ||
586 | install -d ${D}/${sysconfdir}/X11 | ||
587 | install -m 0644 ${WORKDIR}/xorg.conf ${D}/${sysconfdir}/X11/ | ||
588 | fi | ||
589 | } | ||
590 | |||
591 | Here is the append file, which is named ``xserver-xf86-config_%.bbappend`` | ||
592 | and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The | ||
593 | file is in the layer at ``recipes-graphics/xorg-xserver``:: | ||
594 | |||
595 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" | ||
596 | |||
597 | SRC_URI:append:rpi = " \ | ||
598 | file://xorg.conf.d/98-pitft.conf \ | ||
599 | file://xorg.conf.d/99-calibration.conf \ | ||
600 | " | ||
601 | do_install:append:rpi () { | ||
602 | PITFT="${@bb.utils.contains("MACHINE_FEATURES", "pitft", "1", "0", d)}" | ||
603 | if [ "${PITFT}" = "1" ]; then | ||
604 | install -d ${D}/${sysconfdir}/X11/xorg.conf.d/ | ||
605 | install -m 0644 ${WORKDIR}/xorg.conf.d/98-pitft.conf ${D}/${sysconfdir}/X11/xorg.conf.d/ | ||
606 | install -m 0644 ${WORKDIR}/xorg.conf.d/99-calibration.conf ${D}/${sysconfdir}/X11/xorg.conf.d/ | ||
607 | fi | ||
608 | } | ||
609 | |||
610 | FILES:${PN}:append:rpi = " ${sysconfdir}/X11/xorg.conf.d/*" | ||
611 | |||
612 | Building off of the previous example, we once again are setting the | ||
613 | :term:`FILESEXTRAPATHS` variable. In this case we are also using | ||
614 | :term:`SRC_URI` to list additional source files to use when ``rpi`` is found in | ||
615 | the list of :term:`OVERRIDES`. The :ref:`ref-tasks-install` task will then perform a | ||
616 | check for an additional :term:`MACHINE_FEATURES` that if set will cause these | ||
617 | additional files to be installed. These additional files are listed in | ||
618 | :term:`FILES` so that they will be packaged. | ||
619 | |||
620 | Prioritizing Your Layer | ||
621 | ======================= | ||
622 | |||
623 | Each layer is assigned a priority value. Priority values control which | ||
624 | layer takes precedence if there are recipe files with the same name in | ||
625 | multiple layers. For these cases, the recipe file from the layer with a | ||
626 | higher priority number takes precedence. Priority values also affect the | ||
627 | order in which multiple ``.bbappend`` files for the same recipe are | ||
628 | applied. You can either specify the priority manually, or allow the | ||
629 | build system to calculate it based on the layer's dependencies. | ||
630 | |||
631 | To specify the layer's priority manually, use the | ||
632 | :term:`BBFILE_PRIORITY` | ||
633 | variable and append the layer's root name:: | ||
634 | |||
635 | BBFILE_PRIORITY_mylayer = "1" | ||
636 | |||
637 | .. note:: | ||
638 | |||
639 | It is possible for a recipe with a lower version number | ||
640 | :term:`PV` in a layer that has a higher | ||
641 | priority to take precedence. | ||
642 | |||
643 | Also, the layer priority does not currently affect the precedence | ||
644 | order of ``.conf`` or ``.bbclass`` files. Future versions of BitBake | ||
645 | might address this. | ||
646 | |||
647 | Managing Layers | ||
648 | =============== | ||
649 | |||
650 | You can use the BitBake layer management tool ``bitbake-layers`` to | ||
651 | provide a view into the structure of recipes across a multi-layer | ||
652 | project. Being able to generate output that reports on configured layers | ||
653 | with their paths and priorities and on ``.bbappend`` files and their | ||
654 | applicable recipes can help to reveal potential problems. | ||
655 | |||
656 | For help on the BitBake layer management tool, use the following | ||
657 | command:: | ||
658 | |||
659 | $ bitbake-layers --help | ||
660 | |||
661 | The following list describes the available commands: | ||
662 | |||
663 | - ``help:`` Displays general help or help on a specified command. | ||
664 | |||
665 | - ``show-layers:`` Shows the current configured layers. | ||
666 | |||
667 | - ``show-overlayed:`` Lists overlayed recipes. A recipe is overlayed | ||
668 | when a recipe with the same name exists in another layer that has a | ||
669 | higher layer priority. | ||
670 | |||
671 | - ``show-recipes:`` Lists available recipes and the layers that | ||
672 | provide them. | ||
673 | |||
674 | - ``show-appends:`` Lists ``.bbappend`` files and the recipe files to | ||
675 | which they apply. | ||
676 | |||
677 | - ``show-cross-depends:`` Lists dependency relationships between | ||
678 | recipes that cross layer boundaries. | ||
679 | |||
680 | - ``add-layer:`` Adds a layer to ``bblayers.conf``. | ||
681 | |||
682 | - ``remove-layer:`` Removes a layer from ``bblayers.conf`` | ||
683 | |||
684 | - ``flatten:`` Flattens the layer configuration into a separate | ||
685 | output directory. Flattening your layer configuration builds a | ||
686 | "flattened" directory that contains the contents of all layers, with | ||
687 | any overlayed recipes removed and any ``.bbappend`` files appended to | ||
688 | the corresponding recipes. You might have to perform some manual | ||
689 | cleanup of the flattened layer as follows: | ||
690 | |||
691 | - Non-recipe files (such as patches) are overwritten. The flatten | ||
692 | command shows a warning for these files. | ||
693 | |||
694 | - Anything beyond the normal layer setup has been added to the | ||
695 | ``layer.conf`` file. Only the lowest priority layer's | ||
696 | ``layer.conf`` is used. | ||
697 | |||
698 | - Overridden and appended items from ``.bbappend`` files need to be | ||
699 | cleaned up. The contents of each ``.bbappend`` end up in the | ||
700 | flattened recipe. However, if there are appended or changed | ||
701 | variable values, you need to tidy these up yourself. Consider the | ||
702 | following example. Here, the ``bitbake-layers`` command adds the | ||
703 | line ``#### bbappended ...`` so that you know where the following | ||
704 | lines originate:: | ||
705 | |||
706 | ... | ||
707 | DESCRIPTION = "A useful utility" | ||
708 | ... | ||
709 | EXTRA_OECONF = "--enable-something" | ||
710 | ... | ||
711 | |||
712 | #### bbappended from meta-anotherlayer #### | ||
713 | |||
714 | DESCRIPTION = "Customized utility" | ||
715 | EXTRA_OECONF += "--enable-somethingelse" | ||
716 | |||
717 | |||
718 | Ideally, you would tidy up these utilities as follows:: | ||
719 | |||
720 | ... | ||
721 | DESCRIPTION = "Customized utility" | ||
722 | ... | ||
723 | EXTRA_OECONF = "--enable-something --enable-somethingelse" | ||
724 | ... | ||
725 | |||
726 | - ``layerindex-fetch``: Fetches a layer from a layer index, along | ||
727 | with its dependent layers, and adds the layers to the | ||
728 | ``conf/bblayers.conf`` file. | ||
729 | |||
730 | - ``layerindex-show-depends``: Finds layer dependencies from the | ||
731 | layer index. | ||
732 | |||
733 | - ``save-build-conf``: Saves the currently active build configuration | ||
734 | (``conf/local.conf``, ``conf/bblayers.conf``) as a template into a layer. | ||
735 | This template can later be used for setting up builds via :term:`TEMPLATECONF`. | ||
736 | For information about saving and using configuration templates, see | ||
737 | ":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`". | ||
738 | |||
739 | - ``create-layer``: Creates a basic layer. | ||
740 | |||
741 | - ``create-layers-setup``: Writes out a configuration file and/or a script that | ||
742 | can replicate the directory structure and revisions of the layers in a current build. | ||
743 | For more information, see ":ref:`dev-manual/layers:saving and restoring the layers setup`". | ||
744 | |||
745 | Creating a General Layer Using the ``bitbake-layers`` Script | ||
746 | ============================================================ | ||
747 | |||
748 | The ``bitbake-layers`` script with the ``create-layer`` subcommand | ||
749 | simplifies creating a new general layer. | ||
750 | |||
751 | .. note:: | ||
752 | |||
753 | - For information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`" | ||
754 | section in the Yocto | ||
755 | Project Board Specific (BSP) Developer's Guide. | ||
756 | |||
757 | - In order to use a layer with the OpenEmbedded build system, you | ||
758 | need to add the layer to your ``bblayers.conf`` configuration | ||
759 | file. See the ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`" | ||
760 | section for more information. | ||
761 | |||
762 | The default mode of the script's operation with this subcommand is to | ||
763 | create a layer with the following: | ||
764 | |||
765 | - A layer priority of 6. | ||
766 | |||
767 | - A ``conf`` subdirectory that contains a ``layer.conf`` file. | ||
768 | |||
769 | - A ``recipes-example`` subdirectory that contains a further | ||
770 | subdirectory named ``example``, which contains an ``example.bb`` | ||
771 | recipe file. | ||
772 | |||
773 | - A ``COPYING.MIT``, which is the license statement for the layer. The | ||
774 | script assumes you want to use the MIT license, which is typical for | ||
775 | most layers, for the contents of the layer itself. | ||
776 | |||
777 | - A ``README`` file, which is a file describing the contents of your | ||
778 | new layer. | ||
779 | |||
780 | In its simplest form, you can use the following command form to create a | ||
781 | layer. The command creates a layer whose name corresponds to | ||
782 | "your_layer_name" in the current directory:: | ||
783 | |||
784 | $ bitbake-layers create-layer your_layer_name | ||
785 | |||
786 | As an example, the following command creates a layer named ``meta-scottrif`` | ||
787 | in your home directory:: | ||
788 | |||
789 | $ cd /usr/home | ||
790 | $ bitbake-layers create-layer meta-scottrif | ||
791 | NOTE: Starting bitbake server... | ||
792 | Add your new layer with 'bitbake-layers add-layer meta-scottrif' | ||
793 | |||
794 | If you want to set the priority of the layer to other than the default | ||
795 | value of "6", you can either use the ``--priority`` option or you | ||
796 | can edit the | ||
797 | :term:`BBFILE_PRIORITY` value | ||
798 | in the ``conf/layer.conf`` after the script creates it. Furthermore, if | ||
799 | you want to give the example recipe file some name other than the | ||
800 | default, you can use the ``--example-recipe-name`` option. | ||
801 | |||
802 | The easiest way to see how the ``bitbake-layers create-layer`` command | ||
803 | works is to experiment with the script. You can also read the usage | ||
804 | information by entering the following:: | ||
805 | |||
806 | $ bitbake-layers create-layer --help | ||
807 | NOTE: Starting bitbake server... | ||
808 | usage: bitbake-layers create-layer [-h] [--priority PRIORITY] | ||
809 | [--example-recipe-name EXAMPLERECIPE] | ||
810 | layerdir | ||
811 | |||
812 | Create a basic layer | ||
813 | |||
814 | positional arguments: | ||
815 | layerdir Layer directory to create | ||
816 | |||
817 | optional arguments: | ||
818 | -h, --help show this help message and exit | ||
819 | --priority PRIORITY, -p PRIORITY | ||
820 | Layer directory to create | ||
821 | --example-recipe-name EXAMPLERECIPE, -e EXAMPLERECIPE | ||
822 | Filename of the example recipe | ||
823 | |||
824 | Adding a Layer Using the ``bitbake-layers`` Script | ||
825 | ================================================== | ||
826 | |||
827 | Once you create your general layer, you must add it to your | ||
828 | ``bblayers.conf`` file. Adding the layer to this configuration file | ||
829 | makes the OpenEmbedded build system aware of your layer so that it can | ||
830 | search it for metadata. | ||
831 | |||
832 | Add your layer by using the ``bitbake-layers add-layer`` command:: | ||
833 | |||
834 | $ bitbake-layers add-layer your_layer_name | ||
835 | |||
836 | Here is an example that adds a | ||
837 | layer named ``meta-scottrif`` to the configuration file. Following the | ||
838 | command that adds the layer is another ``bitbake-layers`` command that | ||
839 | shows the layers that are in your ``bblayers.conf`` file:: | ||
840 | |||
841 | $ bitbake-layers add-layer meta-scottrif | ||
842 | NOTE: Starting bitbake server... | ||
843 | Parsing recipes: 100% |##########################################################| Time: 0:00:49 | ||
844 | Parsing of 1441 .bb files complete (0 cached, 1441 parsed). 2055 targets, 56 skipped, 0 masked, 0 errors. | ||
845 | $ bitbake-layers show-layers | ||
846 | NOTE: Starting bitbake server... | ||
847 | layer path priority | ||
848 | ========================================================================== | ||
849 | meta /home/scottrif/poky/meta 5 | ||
850 | meta-poky /home/scottrif/poky/meta-poky 5 | ||
851 | meta-yocto-bsp /home/scottrif/poky/meta-yocto-bsp 5 | ||
852 | workspace /home/scottrif/poky/build/workspace 99 | ||
853 | meta-scottrif /home/scottrif/poky/build/meta-scottrif 6 | ||
854 | |||
855 | |||
856 | Adding the layer to this file | ||
857 | enables the build system to locate the layer during the build. | ||
858 | |||
859 | .. note:: | ||
860 | |||
861 | During a build, the OpenEmbedded build system looks in the layers | ||
862 | from the top of the list down to the bottom in that order. | ||
863 | |||
864 | Saving and restoring the layers setup | ||
865 | ===================================== | ||
866 | |||
867 | Once you have a working build with the correct set of layers, it is beneficial | ||
868 | to capture the layer setup --- what they are, which repositories they come from | ||
869 | and which SCM revisions they're at --- into a configuration file, so that this | ||
870 | setup can be easily replicated later, perhaps on a different machine. Here's | ||
871 | how to do this:: | ||
872 | |||
873 | $ bitbake-layers create-layers-setup /srv/work/alex/meta-alex/ | ||
874 | NOTE: Starting bitbake server... | ||
875 | NOTE: Created /srv/work/alex/meta-alex/setup-layers.json | ||
876 | NOTE: Created /srv/work/alex/meta-alex/setup-layers | ||
877 | |||
878 | The tool needs a single argument which tells where to place the output, consisting | ||
879 | of a json formatted layer configuration, and a ``setup-layers`` script that can use that configuration | ||
880 | to restore the layers in a different location, or on a different host machine. The argument | ||
881 | can point to a custom layer (which is then deemed a "bootstrap" layer that needs to be | ||
882 | checked out first), or into a completely independent location. | ||
883 | |||
884 | The replication of the layers is performed by running the ``setup-layers`` script provided | ||
885 | above: | ||
886 | |||
887 | #. Clone the bootstrap layer or some other repository to obtain | ||
888 | the json config and the setup script that can use it. | ||
889 | |||
890 | #. Run the script directly with no options:: | ||
891 | |||
892 | alex@Zen2:/srv/work/alex/my-build$ meta-alex/setup-layers | ||
893 | Note: not checking out source meta-alex, use --force-bootstraplayer-checkout to override. | ||
894 | |||
895 | Setting up source meta-intel, revision 15.0-hardknott-3.3-310-g0a96edae, branch master | ||
896 | Running 'git init -q /srv/work/alex/my-build/meta-intel' | ||
897 | Running 'git remote remove origin > /dev/null 2>&1; git remote add origin git://git.yoctoproject.org/meta-intel' in /srv/work/alex/my-build/meta-intel | ||
898 | Running 'git fetch -q origin || true' in /srv/work/alex/my-build/meta-intel | ||
899 | Running 'git checkout -q 0a96edae609a3f48befac36af82cf1eed6786b4a' in /srv/work/alex/my-build/meta-intel | ||
900 | |||
901 | Setting up source poky, revision 4.1_M1-372-g55483d28f2, branch akanavin/setup-layers | ||
902 | Running 'git init -q /srv/work/alex/my-build/poky' | ||
903 | Running 'git remote remove origin > /dev/null 2>&1; git remote add origin git://git.yoctoproject.org/poky' in /srv/work/alex/my-build/poky | ||
904 | Running 'git fetch -q origin || true' in /srv/work/alex/my-build/poky | ||
905 | Running 'git remote remove poky-contrib > /dev/null 2>&1; git remote add poky-contrib ssh://git@push.yoctoproject.org/poky-contrib' in /srv/work/alex/my-build/poky | ||
906 | Running 'git fetch -q poky-contrib || true' in /srv/work/alex/my-build/poky | ||
907 | Running 'git checkout -q 11db0390b02acac1324e0f827beb0e2e3d0d1d63' in /srv/work/alex/my-build/poky | ||
908 | |||
909 | .. note:: | ||
910 | This will work to update an existing checkout as well. | ||
911 | |||
912 | .. note:: | ||
913 | The script is self-sufficient and requires only python3 | ||
914 | and git on the build machine. | ||
915 | |||
916 | .. note:: | ||
917 | Both the ``create-layers-setup`` and the ``setup-layers`` provided several additional options | ||
918 | that customize their behavior - you are welcome to study them via ``--help`` command line parameter. | ||
919 | |||