diff options
author | Nicolas Dechesne <nicolas.dechesne@linaro.org> | 2020-07-24 16:27:54 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2020-09-17 10:09:33 +0100 |
commit | c473fa229239752367c5d573160fc8738cf1907e (patch) | |
tree | f8520ba3aa3cf911333dbd31e38e9a52203a0285 /documentation/kernel-dev | |
parent | 4cd953989de42c7a83f666c23e077d53b016a1f1 (diff) | |
download | poky-c473fa229239752367c5d573160fc8738cf1907e.tar.gz |
sphinx: fix internal links
Many of the internal links were not converted probably from DocBook
using pandoc. After looking at the various patterns, the follow series
of 'naive' Python regexp were used to perform some additional
automatic conversion.
Also, since we rely on built-in glossary, all links to terms need to
use the sphinx :term: syntax.
This commit is generated using the following Python series of regexp:
line = re.sub("`+(\w+)`* <(\&YOCTO_DOCS_REF_URL;)?#var-\\1>`__",
":term:`\\1`",
line)
line = re.sub("`+do_([a-z_]+)`* <(\&YOCTO_DOCS_REF_URL;)?#ref-tasks-\\1>`__",
":ref:`ref-tasks-\\1`",
line)
line = re.sub("`+([a-z_\-\*\.]+).bbclass`* <(\&YOCTO_DOCS_REF_URL;)?#ref-classes-\\1>`__",
":ref:`\\1.bbclass <ref-classes-\\1>`",
line)
line = re.sub("`+([a-z_\-\*\.]+)`* <(\&YOCTO_DOCS_REF_URL;)?#ref-classes-\\1>`__",
":ref:`\\1 <ref-classes-\\1>`",
line)
line = re.sub("`Source Directory <(\&YOCTO_DOCS_REF_URL;)?#source-directory>`__",
":term:`Source Directory`",
line)
line = re.sub("`Build Directory <(\&YOCTO_DOCS_REF_URL;)?#build-directory>`__",
":term:`Build Directory`",
line)
line = re.sub("`Metadata <(\&YOCTO_DOCS_REF_URL;)?#metadata>`__",
":term:`Metadata`",
line)
line = re.sub("`BitBake <(\&YOCTO_DOCS_REF_URL;)?#bitbake-term>`__",
":term:`BitBake`",
line)
line = re.sub("`Images <(\&YOCTO_DOCS_REF_URL;)?#ref-images>`__",
":ref:`ref-manual/ref-images:Images`",
line)
line = re.sub("`Classes <(\&YOCTO_DOCS_REF_URL;)?#ref-classes>`__",
":ref:`ref-manual/ref-classes:Classes`",
line)
line = re.sub("`workspace <(\&YOCTO_DOCS_REF_URL;)?#devtool-the-workspace-layer-structure>`__",
":ref:`devtool-the-workspace-layer-structure`",
line)
line = re.sub("`Open-?Embedded b?B?uild s?S?ystem <(\&YOCTO_DOCS_REF_URL;)?#build-system-term>`__",
":term:`OpenEmbedded Build System`",
line)
line = re.sub("`(OpenEmbedded-Core )?(\(?OE-Core\)? )?<(\&YOCTO_DOCS_REF_URL;)?#oe-core>`__",
":term:`OpenEmbedded-Core (OE-Core)`",
line)
It won't catch multiline strings, but it catches a very large number
of occurences!
(From yocto-docs rev: 3f537d17de5b1fb76ba3bee196481984a4826378)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev')
-rw-r--r-- | documentation/kernel-dev/kernel-dev-advanced.rst | 54 | ||||
-rw-r--r-- | documentation/kernel-dev/kernel-dev-common.rst | 134 | ||||
-rw-r--r-- | documentation/kernel-dev/kernel-dev-concepts-appx.rst | 2 | ||||
-rw-r--r-- | documentation/kernel-dev/kernel-dev-faq.rst | 10 | ||||
-rw-r--r-- | documentation/kernel-dev/kernel-dev-intro.rst | 2 | ||||
-rw-r--r-- | documentation/kernel-dev/kernel-dev-maint-appx.rst | 4 |
6 files changed, 103 insertions, 103 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.rst b/documentation/kernel-dev/kernel-dev-advanced.rst index 90323d3e2a..36a34ca28c 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.rst +++ b/documentation/kernel-dev/kernel-dev-advanced.rst | |||
@@ -11,7 +11,7 @@ Overview | |||
11 | 11 | ||
12 | In addition to supporting configuration fragments and patches, the Yocto | 12 | In addition to supporting configuration fragments and patches, the Yocto |
13 | Project kernel tools also support rich | 13 | Project kernel tools also support rich |
14 | `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ that you can use to define | 14 | :term:`Metadata` that you can use to define |
15 | complex policies and Board Support Package (BSP) support. The purpose of | 15 | complex policies and Board Support Package (BSP) support. The purpose of |
16 | the Metadata and the tools that manage it is to help you manage the | 16 | the Metadata and the tools that manage it is to help you manage the |
17 | complexity of the configuration and sources used to support multiple | 17 | complexity of the configuration and sources used to support multiple |
@@ -27,7 +27,7 @@ Kernel development tools ("kern-tools") exist also in the Yocto Project | |||
27 | Source Repositories under the "Yocto Linux Kernel" heading in the | 27 | Source Repositories under the "Yocto Linux Kernel" heading in the |
28 | ``yocto-kernel-tools`` Git repository. The recipe that builds these | 28 | ``yocto-kernel-tools`` Git repository. The recipe that builds these |
29 | tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in | 29 | tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in |
30 | the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ (e.g. | 30 | the :term:`Source Directory` (e.g. |
31 | ``poky``). | 31 | ``poky``). |
32 | 32 | ||
33 | Using Kernel Metadata in a Recipe | 33 | Using Kernel Metadata in a Recipe |
@@ -49,9 +49,9 @@ linux-yocto recipe. | |||
49 | file) is said to be a "linux-yocto style" recipe. | 49 | file) is said to be a "linux-yocto style" recipe. |
50 | 50 | ||
51 | Every linux-yocto style recipe must define the | 51 | Every linux-yocto style recipe must define the |
52 | ```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__ variable. This | 52 | :term:`KMACHINE` variable. This |
53 | variable is typically set to the same value as the ``MACHINE`` variable, | 53 | variable is typically set to the same value as the ``MACHINE`` variable, |
54 | which is used by `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__. | 54 | which is used by :term:`BitBake`. |
55 | However, in some cases, the variable might instead refer to the | 55 | However, in some cases, the variable might instead refer to the |
56 | underlying platform of the ``MACHINE``. | 56 | underlying platform of the ``MACHINE``. |
57 | 57 | ||
@@ -65,7 +65,7 @@ Descriptions <#bsp-descriptions>`__ section for more information. | |||
65 | 65 | ||
66 | Every linux-yocto style recipe must also indicate the Linux kernel | 66 | Every linux-yocto style recipe must also indicate the Linux kernel |
67 | source repository branch used to build the Linux kernel. The | 67 | source repository branch used to build the Linux kernel. The |
68 | ```KBRANCH`` <&YOCTO_DOCS_REF_URL;#var-KBRANCH>`__ variable must be set | 68 | :term:`KBRANCH` variable must be set |
69 | to indicate the branch. | 69 | to indicate the branch. |
70 | 70 | ||
71 | .. note:: | 71 | .. note:: |
@@ -84,7 +84,7 @@ to indicate the branch. | |||
84 | The linux-yocto style recipes can optionally define the following | 84 | The linux-yocto style recipes can optionally define the following |
85 | variables: KERNEL_FEATURES LINUX_KERNEL_TYPE | 85 | variables: KERNEL_FEATURES LINUX_KERNEL_TYPE |
86 | 86 | ||
87 | ```LINUX_KERNEL_TYPE`` <&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE>`__ | 87 | :term:`LINUX_KERNEL_TYPE` |
88 | defines the kernel type to be used in assembling the configuration. If | 88 | defines the kernel type to be used in assembling the configuration. If |
89 | you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard". | 89 | you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard". |
90 | Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search | 90 | Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search |
@@ -103,10 +103,10 @@ a match, they issue a warning. | |||
103 | The tools first search for the ``KMACHINE`` and then for the | 103 | The tools first search for the ``KMACHINE`` and then for the |
104 | ``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they | 104 | ``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they |
105 | will use the sources from the ``KBRANCH`` and any configuration | 105 | will use the sources from the ``KBRANCH`` and any configuration |
106 | specified in the ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__. | 106 | specified in the :term:`SRC_URI`. |
107 | 107 | ||
108 | You can use the | 108 | You can use the |
109 | ```KERNEL_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES>`__ | 109 | :term:`KERNEL_FEATURES` |
110 | variable to include features (configuration fragments, patches, or both) | 110 | variable to include features (configuration fragments, patches, or both) |
111 | that are not already included by the ``KMACHINE`` and | 111 | that are not already included by the ``KMACHINE`` and |
112 | ``LINUX_KERNEL_TYPE`` variable combination. For example, to include a | 112 | ``LINUX_KERNEL_TYPE`` variable combination. For example, to include a |
@@ -185,7 +185,7 @@ contain "features" as far as the kernel tools are concerned. | |||
185 | 185 | ||
186 | Paths used in kernel Metadata files are relative to base, which is | 186 | Paths used in kernel Metadata files are relative to base, which is |
187 | either | 187 | either |
188 | ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__ if | 188 | :term:`FILESEXTRAPATHS` if |
189 | you are creating Metadata in `recipe-space <#recipe-space-metadata>`__, | 189 | you are creating Metadata in `recipe-space <#recipe-space-metadata>`__, |
190 | or the top level of | 190 | or the top level of |
191 | ```yocto-kernel-cache`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/>`__ | 191 | ```yocto-kernel-cache`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/>`__ |
@@ -218,7 +218,7 @@ fragment files in the "`Creating Configuration | |||
218 | Fragments <#creating-config-fragments>`__" section. | 218 | Fragments <#creating-config-fragments>`__" section. |
219 | 219 | ||
220 | Within the ``smp.scc`` file, the | 220 | Within the ``smp.scc`` file, the |
221 | ```KFEATURE_DESCRIPTION`` <&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION>`__ | 221 | :term:`KFEATURE_DESCRIPTION` |
222 | statement provides a short description of the fragment. Higher level | 222 | statement provides a short description of the fragment. Higher level |
223 | kernel tools use this description. | 223 | kernel tools use this description. |
224 | 224 | ||
@@ -312,7 +312,7 @@ non-hardware configuration fragments with patches you want to use when | |||
312 | building a Linux kernel of a specific type (e.g. a real-time kernel). | 312 | building a Linux kernel of a specific type (e.g. a real-time kernel). |
313 | Syntactically, kernel types are no different than features as described | 313 | Syntactically, kernel types are no different than features as described |
314 | in the "`Features <#features>`__" section. The | 314 | in the "`Features <#features>`__" section. The |
315 | ```LINUX_KERNEL_TYPE`` <&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE>`__ | 315 | :term:`LINUX_KERNEL_TYPE` |
316 | variable in the kernel recipe selects the kernel type. For example, in | 316 | variable in the kernel recipe selects the kernel type. For example, in |
317 | the ``linux-yocto_4.12.bb`` kernel recipe found in | 317 | the ``linux-yocto_4.12.bb`` kernel recipe found in |
318 | ``poky/meta/recipes-kernel/linux``, a | 318 | ``poky/meta/recipes-kernel/linux``, a |
@@ -432,9 +432,9 @@ ktypes/standard/standard.scc branch beaglebone include beaglebone.scc # | |||
432 | default policy for standard kernels include | 432 | default policy for standard kernels include |
433 | features/latencytop/latencytop.scc include | 433 | features/latencytop/latencytop.scc include |
434 | features/profiling/profiling.scc Every top-level BSP description file | 434 | features/profiling/profiling.scc Every top-level BSP description file |
435 | should define the ```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__, | 435 | should define the :term:`KMACHINE`, |
436 | ```KTYPE`` <&YOCTO_DOCS_REF_URL;#var-KTYPE>`__, and | 436 | :term:`KTYPE`, and |
437 | ```KARCH`` <&YOCTO_DOCS_REF_URL;#var-KARCH>`__ variables. These | 437 | :term:`KARCH` variables. These |
438 | variables allow the OpenEmbedded build system to identify the | 438 | variables allow the OpenEmbedded build system to identify the |
439 | description as meeting the criteria set by the recipe being built. This | 439 | description as meeting the criteria set by the recipe being built. This |
440 | example supports the "beaglebone" machine for the "standard" kernel and | 440 | example supports the "beaglebone" machine for the "standard" kernel and |
@@ -444,7 +444,7 @@ Be aware that a hard link between the ``KTYPE`` variable and a kernel | |||
444 | type description file does not exist. Thus, if you do not have the | 444 | type description file does not exist. Thus, if you do not have the |
445 | kernel type defined in your kernel Metadata as it is here, you only need | 445 | kernel type defined in your kernel Metadata as it is here, you only need |
446 | to ensure that the | 446 | to ensure that the |
447 | ```LINUX_KERNEL_TYPE`` <&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE>`__ | 447 | :term:`LINUX_KERNEL_TYPE` |
448 | variable in the kernel recipe and the ``KTYPE`` variable in the BSP | 448 | variable in the kernel recipe and the ``KTYPE`` variable in the BSP |
449 | description file match. | 449 | description file match. |
450 | 450 | ||
@@ -529,9 +529,9 @@ with the most basic functionality of the system as defined in the base | |||
529 | "minnow" description file. | 529 | "minnow" description file. |
530 | 530 | ||
531 | Notice again the three critical variables: | 531 | Notice again the three critical variables: |
532 | ```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__, | 532 | :term:`KMACHINE`, |
533 | ```KTYPE`` <&YOCTO_DOCS_REF_URL;#var-KTYPE>`__, and | 533 | :term:`KTYPE`, and |
534 | ```KARCH`` <&YOCTO_DOCS_REF_URL;#var-KARCH>`__. Of these variables, only | 534 | :term:`KARCH`. Of these variables, only |
535 | ``KTYPE`` has changed to specify the "tiny" kernel type. | 535 | ``KTYPE`` has changed to specify the "tiny" kernel type. |
536 | 536 | ||
537 | Kernel Metadata Location | 537 | Kernel Metadata Location |
@@ -564,12 +564,12 @@ Recipe-Space Metadata | |||
564 | 564 | ||
565 | When stored in recipe-space, the kernel Metadata files reside in a | 565 | When stored in recipe-space, the kernel Metadata files reside in a |
566 | directory hierarchy below | 566 | directory hierarchy below |
567 | ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__. For | 567 | :term:`FILESEXTRAPATHS`. For |
568 | a linux-yocto recipe or for a Linux kernel recipe derived by copying and | 568 | a linux-yocto recipe or for a Linux kernel recipe derived by copying and |
569 | modifying | 569 | modifying |
570 | ``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to | 570 | ``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to |
571 | a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to | 571 | a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to |
572 | ``${``\ ```THISDIR`` <&YOCTO_DOCS_REF_URL;#var-THISDIR>`__\ ``}/${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}``. | 572 | ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. |
573 | See the "`Modifying an Existing | 573 | See the "`Modifying an Existing |
574 | Recipe <#modifying-an-existing-recipe>`__" section for more information. | 574 | Recipe <#modifying-an-existing-recipe>`__" section for more information. |
575 | 575 | ||
@@ -582,10 +582,10 @@ When the Metadata is stored in recipe-space, you must take steps to | |||
582 | ensure BitBake has the necessary information to decide what files to | 582 | ensure BitBake has the necessary information to decide what files to |
583 | fetch and when they need to be fetched again. It is only necessary to | 583 | fetch and when they need to be fetched again. It is only necessary to |
584 | specify the ``.scc`` files on the | 584 | specify the ``.scc`` files on the |
585 | ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__. BitBake parses them | 585 | :term:`SRC_URI`. BitBake parses them |
586 | and fetches any files referenced in the ``.scc`` files by the | 586 | and fetches any files referenced in the ``.scc`` files by the |
587 | ``include``, ``patch``, or ``kconf`` commands. Because of this, it is | 587 | ``include``, ``patch``, or ``kconf`` commands. Because of this, it is |
588 | necessary to bump the recipe ```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__ | 588 | necessary to bump the recipe :term:`PR` |
589 | value when changing the content of files not explicitly listed in the | 589 | value when changing the content of files not explicitly listed in the |
590 | ``SRC_URI``. | 590 | ``SRC_URI``. |
591 | 591 | ||
@@ -600,7 +600,7 @@ Metadata Outside the Recipe-Space | |||
600 | When stored outside of the recipe-space, the kernel Metadata files | 600 | When stored outside of the recipe-space, the kernel Metadata files |
601 | reside in a separate repository. The OpenEmbedded build system adds the | 601 | reside in a separate repository. The OpenEmbedded build system adds the |
602 | Metadata to the build as a "type=kmeta" repository through the | 602 | Metadata to the build as a "type=kmeta" repository through the |
603 | ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ variable. As an | 603 | :term:`SRC_URI` variable. As an |
604 | example, consider the following ``SRC_URI`` statement from the | 604 | example, consider the following ``SRC_URI`` statement from the |
605 | ``linux-yocto_4.12.bb`` kernel recipe: SRC_URI = | 605 | ``linux-yocto_4.12.bb`` kernel recipe: SRC_URI = |
606 | "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; | 606 | "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; |
@@ -742,10 +742,10 @@ within an SCC description file (``.scc``): | |||
742 | "ref" if specified. | 742 | "ref" if specified. |
743 | 743 | ||
744 | - ``define``: Defines variables, such as | 744 | - ``define``: Defines variables, such as |
745 | ```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__, | 745 | :term:`KMACHINE`, |
746 | ```KTYPE`` <&YOCTO_DOCS_REF_URL;#var-KTYPE>`__, | 746 | :term:`KTYPE`, |
747 | ```KARCH`` <&YOCTO_DOCS_REF_URL;#var-KARCH>`__, and | 747 | :term:`KARCH`, and |
748 | ```KFEATURE_DESCRIPTION`` <&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION>`__. | 748 | :term:`KFEATURE_DESCRIPTION`. |
749 | 749 | ||
750 | - ``include SCC_FILE``: Includes an SCC file in the current file. The | 750 | - ``include SCC_FILE``: Includes an SCC file in the current file. The |
751 | file is parsed as if you had inserted it inline. | 751 | file is parsed as if you had inserted it inline. |
diff --git a/documentation/kernel-dev/kernel-dev-common.rst b/documentation/kernel-dev/kernel-dev-common.rst index 085c6d396c..b5f794e733 100644 --- a/documentation/kernel-dev/kernel-dev-common.rst +++ b/documentation/kernel-dev/kernel-dev-common.rst | |||
@@ -72,7 +72,7 @@ section: | |||
72 | "poky". | 72 | "poky". |
73 | 73 | ||
74 | 2. *Prepare Your ``local.conf`` File:* By default, the | 74 | 2. *Prepare Your ``local.conf`` File:* By default, the |
75 | ```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable is set to | 75 | :term:`MACHINE` variable is set to |
76 | "qemux86-64", which is fine if you are building for the QEMU emulator | 76 | "qemux86-64", which is fine if you are building for the QEMU emulator |
77 | in 64-bit mode. However, if you are not, you need to set the | 77 | in 64-bit mode. However, if you are not, you need to set the |
78 | ``MACHINE`` variable appropriately in your ``conf/local.conf`` file | 78 | ``MACHINE`` variable appropriately in your ``conf/local.conf`` file |
@@ -82,7 +82,7 @@ section: | |||
82 | 82 | ||
83 | Also, since you are preparing to work on the kernel image, you need | 83 | Also, since you are preparing to work on the kernel image, you need |
84 | to set the | 84 | to set the |
85 | ```MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS>`__ | 85 | :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` |
86 | variable to include kernel modules. | 86 | variable to include kernel modules. |
87 | 87 | ||
88 | In this example we wish to build for qemux86 so we must set the | 88 | In this example we wish to build for qemux86 so we must set the |
@@ -115,7 +115,7 @@ section: | |||
115 | 115 | ||
116 | 4. *Inform the BitBake Build Environment About Your Layer:* As directed | 116 | 4. *Inform the BitBake Build Environment About Your Layer:* As directed |
117 | when you created your layer, you need to add the layer to the | 117 | when you created your layer, you need to add the layer to the |
118 | ```BBLAYERS`` <&YOCTO_DOCS_REF_URL;#var-BBLAYERS>`__ variable in the | 118 | :term:`BBLAYERS` variable in the |
119 | ``bblayers.conf`` file as follows: $ cd ~/poky/build $ bitbake-layers | 119 | ``bblayers.conf`` file as follows: $ cd ~/poky/build $ bitbake-layers |
120 | add-layer ../../meta-mylayer NOTE: Starting bitbake server... $ | 120 | add-layer ../../meta-mylayer NOTE: Starting bitbake server... $ |
121 | 121 | ||
@@ -236,7 +236,7 @@ section: | |||
236 | "poky". | 236 | "poky". |
237 | 237 | ||
238 | 2. *Prepare Your ``local.conf`` File:* By default, the | 238 | 2. *Prepare Your ``local.conf`` File:* By default, the |
239 | ```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable is set to | 239 | :term:`MACHINE` variable is set to |
240 | "qemux86-64", which is fine if you are building for the QEMU emulator | 240 | "qemux86-64", which is fine if you are building for the QEMU emulator |
241 | in 64-bit mode. However, if you are not, you need to set the | 241 | in 64-bit mode. However, if you are not, you need to set the |
242 | ``MACHINE`` variable appropriately in your ``conf/local.conf`` file | 242 | ``MACHINE`` variable appropriately in your ``conf/local.conf`` file |
@@ -246,7 +246,7 @@ section: | |||
246 | 246 | ||
247 | Also, since you are preparing to work on the kernel image, you need | 247 | Also, since you are preparing to work on the kernel image, you need |
248 | to set the | 248 | to set the |
249 | ```MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS>`__ | 249 | :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` |
250 | variable to include kernel modules. | 250 | variable to include kernel modules. |
251 | 251 | ||
252 | In this example we wish to build for qemux86 so we must set the | 252 | In this example we wish to build for qemux86 so we must set the |
@@ -279,7 +279,7 @@ section: | |||
279 | 279 | ||
280 | 4. *Inform the BitBake Build Environment About Your Layer:* As directed | 280 | 4. *Inform the BitBake Build Environment About Your Layer:* As directed |
281 | when you created your layer, you need to add the layer to the | 281 | when you created your layer, you need to add the layer to the |
282 | ```BBLAYERS`` <&YOCTO_DOCS_REF_URL;#var-BBLAYERS>`__ variable in the | 282 | :term:`BBLAYERS` variable in the |
283 | ``bblayers.conf`` file as follows: $ cd ~/poky/build $ bitbake-layers | 283 | ``bblayers.conf`` file as follows: $ cd ~/poky/build $ bitbake-layers |
284 | add-layer ../../meta-mylayer NOTE: Starting bitbake server ... $ | 284 | add-layer ../../meta-mylayer NOTE: Starting bitbake server ... $ |
285 | 285 | ||
@@ -343,7 +343,7 @@ Creating and Preparing a Layer | |||
343 | 343 | ||
344 | If you are going to be modifying kernel recipes, it is recommended that | 344 | If you are going to be modifying kernel recipes, it is recommended that |
345 | you create and prepare your own layer in which to do your work. Your | 345 | you create and prepare your own layer in which to do your work. Your |
346 | layer contains its own `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__ | 346 | layer contains its own :term:`BitBake` |
347 | append files (``.bbappend``) and provides a convenient mechanism to | 347 | append files (``.bbappend``) and provides a convenient mechanism to |
348 | create your own recipe files (``.bb``) as well as store and use kernel | 348 | create your own recipe files (``.bb``) as well as store and use kernel |
349 | patch files. For background information on working with layers, see the | 349 | patch files. For background information on working with layers, see the |
@@ -393,8 +393,8 @@ home directory: | |||
393 | "${THISDIR}/${PN}:" SRC_URI_append = " file://patch-file-one" | 393 | "${THISDIR}/${PN}:" SRC_URI_append = " file://patch-file-one" |
394 | SRC_URI_append = " file://patch-file-two" SRC_URI_append = " | 394 | SRC_URI_append = " file://patch-file-two" SRC_URI_append = " |
395 | file://patch-file-three" The | 395 | file://patch-file-three" The |
396 | ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__ | 396 | :term:`FILESEXTRAPATHS` |
397 | and ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements | 397 | and :term:`SRC_URI` statements |
398 | enable the OpenEmbedded build system to find patch files. For more | 398 | enable the OpenEmbedded build system to find patch files. For more |
399 | information on using append files, see the "`Using .bbappend Files in | 399 | information on using append files, see the "`Using .bbappend Files in |
400 | Your Layer <&YOCTO_DOCS_DEV_URL;#using-bbappend-files>`__" section in | 400 | Your Layer <&YOCTO_DOCS_DEV_URL;#using-bbappend-files>`__" section in |
@@ -406,7 +406,7 @@ Modifying an Existing Recipe | |||
406 | In many cases, you can customize an existing linux-yocto recipe to meet | 406 | In many cases, you can customize an existing linux-yocto recipe to meet |
407 | the needs of your project. Each release of the Yocto Project provides a | 407 | the needs of your project. Each release of the Yocto Project provides a |
408 | few Linux kernel recipes from which you can choose. These are located in | 408 | few Linux kernel recipes from which you can choose. These are located in |
409 | the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ in | 409 | the :term:`Source Directory` in |
410 | ``meta/recipes-kernel/linux``. | 410 | ``meta/recipes-kernel/linux``. |
411 | 411 | ||
412 | Modifying an existing recipe can consist of the following: | 412 | Modifying an existing recipe can consist of the following: |
@@ -431,12 +431,12 @@ modifying the ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe, | |||
431 | the append file will typically be located as follows within your custom | 431 | the append file will typically be located as follows within your custom |
432 | layer: your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend The | 432 | layer: your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend The |
433 | append file should initially extend the | 433 | append file should initially extend the |
434 | ```FILESPATH`` <&YOCTO_DOCS_REF_URL;#var-FILESPATH>`__ search path by | 434 | :term:`FILESPATH` search path by |
435 | prepending the directory that contains your files to the | 435 | prepending the directory that contains your files to the |
436 | ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__ | 436 | :term:`FILESEXTRAPATHS` |
437 | variable as follows: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" The | 437 | variable as follows: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" The |
438 | path | 438 | path |
439 | ``${``\ ```THISDIR`` <&YOCTO_DOCS_REF_URL;#var-THISDIR>`__\ ``}/${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}`` | 439 | ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}`` |
440 | expands to "linux-yocto" in the current directory for this example. If | 440 | expands to "linux-yocto" in the current directory for this example. If |
441 | you add any new files that modify the kernel recipe and you have | 441 | you add any new files that modify the kernel recipe and you have |
442 | extended ``FILESPATH`` as described above, you must place the files in | 442 | extended ``FILESPATH`` as described above, you must place the files in |
@@ -472,16 +472,16 @@ COMPATIBLE_MACHINE_beaglebone = "beaglebone" LINUX_VERSION_genericx86 = | |||
472 | = "4.12.10" LINUX_VERSION_beaglebone = "4.12.10" This append file | 472 | = "4.12.10" LINUX_VERSION_beaglebone = "4.12.10" This append file |
473 | contains statements used to support several BSPs that ship with the | 473 | contains statements used to support several BSPs that ship with the |
474 | Yocto Project. The file defines machines using the | 474 | Yocto Project. The file defines machines using the |
475 | ```COMPATIBLE_MACHINE`` <&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE>`__ | 475 | :term:`COMPATIBLE_MACHINE` |
476 | variable and uses the | 476 | variable and uses the |
477 | ```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__ variable to ensure | 477 | :term:`KMACHINE` variable to ensure |
478 | the machine name used by the OpenEmbedded build system maps to the | 478 | the machine name used by the OpenEmbedded build system maps to the |
479 | machine name used by the Linux Yocto kernel. The file also uses the | 479 | machine name used by the Linux Yocto kernel. The file also uses the |
480 | optional ```KBRANCH`` <&YOCTO_DOCS_REF_URL;#var-KBRANCH>`__ variable to | 480 | optional :term:`KBRANCH` variable to |
481 | ensure the build process uses the appropriate kernel branch. | 481 | ensure the build process uses the appropriate kernel branch. |
482 | 482 | ||
483 | Although this particular example does not use it, the | 483 | Although this particular example does not use it, the |
484 | ```KERNEL_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES>`__ | 484 | :term:`KERNEL_FEATURES` |
485 | variable could be used to enable features specific to the kernel. The | 485 | variable could be used to enable features specific to the kernel. The |
486 | append file points to specific commits in the `Source | 486 | append file points to specific commits in the `Source |
487 | Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ Git repository and | 487 | Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ Git repository and |
@@ -497,7 +497,7 @@ accomplish this definition by putting the configurations in a file or a | |||
497 | set of files inside a directory located at the same level as your | 497 | set of files inside a directory located at the same level as your |
498 | kernel's append file and having the same name as the kernel's main | 498 | kernel's append file and having the same name as the kernel's main |
499 | recipe file. With all these conditions met, simply reference those files | 499 | recipe file. With all these conditions met, simply reference those files |
500 | in the ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statement in | 500 | in the :term:`SRC_URI` statement in |
501 | the append file. | 501 | the append file. |
502 | 502 | ||
503 | For example, suppose you had some configuration options in a file called | 503 | For example, suppose you had some configuration options in a file called |
@@ -515,7 +515,7 @@ the following in your append file: SRC_URI += "file://myconfig.cfg \\ | |||
515 | file://eth.cfg \\ file://gfx.cfg" | 515 | file://eth.cfg \\ file://gfx.cfg" |
516 | 516 | ||
517 | Another variable you can use in your kernel recipe append file is the | 517 | Another variable you can use in your kernel recipe append file is the |
518 | ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__ | 518 | :term:`FILESEXTRAPATHS` |
519 | variable. When you use this statement, you are extending the locations | 519 | variable. When you use this statement, you are extending the locations |
520 | used by the OpenEmbedded system to look for files and patches as the | 520 | used by the OpenEmbedded system to look for files and patches as the |
521 | recipe is processed. | 521 | recipe is processed. |
@@ -546,9 +546,9 @@ Applying Patches | |||
546 | If you have a single patch or a small series of patches that you want to | 546 | If you have a single patch or a small series of patches that you want to |
547 | apply to the Linux kernel source, you can do so just as you would with | 547 | apply to the Linux kernel source, you can do so just as you would with |
548 | any other recipe. You first copy the patches to the path added to | 548 | any other recipe. You first copy the patches to the path added to |
549 | ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__ in | 549 | :term:`FILESEXTRAPATHS` in |
550 | your ``.bbappend`` file as described in the previous section, and then | 550 | your ``.bbappend`` file as described in the previous section, and then |
551 | reference them in ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ | 551 | reference them in :term:`SRC_URI` |
552 | statements. | 552 | statements. |
553 | 553 | ||
554 | For example, you can apply a three-patch series by adding the following | 554 | For example, you can apply a three-patch series by adding the following |
@@ -572,7 +572,7 @@ Changing the Configuration | |||
572 | You can make wholesale or incremental changes to the final ``.config`` | 572 | You can make wholesale or incremental changes to the final ``.config`` |
573 | file used for the eventual Linux kernel configuration by including a | 573 | file used for the eventual Linux kernel configuration by including a |
574 | ``defconfig`` file and by specifying configuration fragments in the | 574 | ``defconfig`` file and by specifying configuration fragments in the |
575 | ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ to be applied to that | 575 | :term:`SRC_URI` to be applied to that |
576 | file. | 576 | file. |
577 | 577 | ||
578 | If you have a complete, working Linux kernel ``.config`` file you want | 578 | If you have a complete, working Linux kernel ``.config`` file you want |
@@ -583,8 +583,8 @@ following lines to the linux-yocto ``.bbappend`` file in your layer: | |||
583 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += | 583 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += |
584 | "file://defconfig" The ``SRC_URI`` tells the build system how to search | 584 | "file://defconfig" The ``SRC_URI`` tells the build system how to search |
585 | for the file, while the | 585 | for the file, while the |
586 | ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__ | 586 | :term:`FILESEXTRAPATHS` |
587 | extends the ```FILESPATH`` <&YOCTO_DOCS_REF_URL;#var-FILESPATH>`__ | 587 | extends the :term:`FILESPATH` |
588 | variable (search directories) to include the ``${PN}`` directory you | 588 | variable (search directories) to include the ``${PN}`` directory you |
589 | created to hold the configuration changes. | 589 | created to hold the configuration changes. |
590 | 590 | ||
@@ -631,7 +631,7 @@ looks for ``defconfig`` files in the layer used for Metadata, which is | |||
631 | ``defconfig`` files in your layer but would rather allow users to use | 631 | ``defconfig`` files in your layer but would rather allow users to use |
632 | the default configuration from the kernel tree and still be able to add | 632 | the default configuration from the kernel tree and still be able to add |
633 | configuration fragments to the | 633 | configuration fragments to the |
634 | ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ through, for example, | 634 | :term:`SRC_URI` through, for example, |
635 | append files, you can direct the OpenEmbedded build system to use a | 635 | append files, you can direct the OpenEmbedded build system to use a |
636 | ``defconfig`` file that is "in-tree". | 636 | ``defconfig`` file that is "in-tree". |
637 | 637 | ||
@@ -651,7 +651,7 @@ build system detects a statement that identifies an "out-of-tree" | |||
651 | ``KBUILD_DEFCONFIG`` variable. | 651 | ``KBUILD_DEFCONFIG`` variable. |
652 | 652 | ||
653 | See the | 653 | See the |
654 | ```KBUILD_DEFCONFIG`` <&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG>`__ | 654 | :term:`KBUILD_DEFCONFIG` |
655 | variable description for more information. | 655 | variable description for more information. |
656 | 656 | ||
657 | Using ``devtool`` to Patch the Kernel | 657 | Using ``devtool`` to Patch the Kernel |
@@ -844,8 +844,8 @@ Section. | |||
844 | addition to your ``local.conf`` file specifying to use | 844 | addition to your ``local.conf`` file specifying to use |
845 | "kernel-modules" and the "qemux86" machine, it must also point to the | 845 | "kernel-modules" and the "qemux86" machine, it must also point to the |
846 | updated kernel source files. Add | 846 | updated kernel source files. Add |
847 | ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ and | 847 | :term:`SRC_URI` and |
848 | ```SRCREV`` <&YOCTO_DOCS_REF_URL;#var-SRCREV>`__ statements similar | 848 | :term:`SRCREV` statements similar |
849 | to the following to your ``local.conf``: $ cd ~/poky/build/conf Add | 849 | to the following to your ``local.conf``: $ cd ~/poky/build/conf Add |
850 | the following to the ``local.conf``: SRC_URI_pn-linux-yocto = | 850 | the following to the ``local.conf``: SRC_URI_pn-linux-yocto = |
851 | "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; | 851 | "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; |
@@ -907,8 +907,8 @@ Section. | |||
907 | contents: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 907 | contents: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" |
908 | SRC_URI_append = " | 908 | SRC_URI_append = " |
909 | file://0001-calibrate.c-Added-some-printk-statements.patch" The | 909 | file://0001-calibrate.c-Added-some-printk-statements.patch" The |
910 | ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__ | 910 | :term:`FILESEXTRAPATHS` |
911 | and ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements | 911 | and :term:`SRC_URI` statements |
912 | enable the OpenEmbedded build system to find the patch file. | 912 | enable the OpenEmbedded build system to find the patch file. |
913 | 913 | ||
914 | For more information on append files and patches, see the "`Creating | 914 | For more information on append files and patches, see the "`Creating |
@@ -968,16 +968,16 @@ environment, you must do the following: | |||
968 | - Because you launch ``menuconfig`` using BitBake, you must be sure to | 968 | - Because you launch ``menuconfig`` using BitBake, you must be sure to |
969 | set up your environment by running the | 969 | set up your environment by running the |
970 | ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ script found in | 970 | ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ script found in |
971 | the `Build Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__. | 971 | the :term:`Build Directory`. |
972 | 972 | ||
973 | - You must be sure of the state of your build's configuration in the | 973 | - You must be sure of the state of your build's configuration in the |
974 | `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__. | 974 | :term:`Source Directory`. |
975 | 975 | ||
976 | - Your build host must have the following two packages installed: | 976 | - Your build host must have the following two packages installed: |
977 | libncurses5-dev libtinfo-dev | 977 | libncurses5-dev libtinfo-dev |
978 | 978 | ||
979 | The following commands initialize the BitBake environment, run the | 979 | The following commands initialize the BitBake environment, run the |
980 | ```do_kernel_configme`` <&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme>`__ | 980 | :ref:`ref-tasks-kernel_configme` |
981 | task, and launch ``menuconfig``. These commands assume the Source | 981 | task, and launch ``menuconfig``. These commands assume the Source |
982 | Directory's top-level folder is ``~/poky``: $ cd poky $ source | 982 | Directory's top-level folder is ``~/poky``: $ cd poky $ source |
983 | oe-init-build-env $ bitbake linux-yocto -c kernel_configme -f $ bitbake | 983 | oe-init-build-env $ bitbake linux-yocto -c kernel_configme -f $ bitbake |
@@ -1089,17 +1089,17 @@ which the OpenEmbedded build system can draw to create the final | |||
1089 | 1089 | ||
1090 | To create a ``defconfig``, start with a complete, working Linux kernel | 1090 | To create a ``defconfig``, start with a complete, working Linux kernel |
1091 | ``.config`` file. Copy that file to the appropriate | 1091 | ``.config`` file. Copy that file to the appropriate |
1092 | ``${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}`` directory in | 1092 | ``${``\ :term:`PN`\ ``}`` directory in |
1093 | your layer's ``recipes-kernel/linux`` directory, and rename the copied | 1093 | your layer's ``recipes-kernel/linux`` directory, and rename the copied |
1094 | file to "defconfig" (e.g. | 1094 | file to "defconfig" (e.g. |
1095 | ``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then, | 1095 | ``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then, |
1096 | add the following lines to the linux-yocto ``.bbappend`` file in your | 1096 | add the following lines to the linux-yocto ``.bbappend`` file in your |
1097 | layer: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += | 1097 | layer: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += |
1098 | "file://defconfig" The | 1098 | "file://defconfig" The |
1099 | ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ tells the build | 1099 | :term:`SRC_URI` tells the build |
1100 | system how to search for the file, while the | 1100 | system how to search for the file, while the |
1101 | ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__ | 1101 | :term:`FILESEXTRAPATHS` |
1102 | extends the ```FILESPATH`` <&YOCTO_DOCS_REF_URL;#var-FILESPATH>`__ | 1102 | extends the :term:`FILESPATH` |
1103 | variable (search directories) to include the ``${PN}`` directory you | 1103 | variable (search directories) to include the ``${PN}`` directory you |
1104 | created to hold the configuration changes. | 1104 | created to hold the configuration changes. |
1105 | 1105 | ||
@@ -1179,7 +1179,7 @@ steps: | |||
1179 | 3. *Create the Configuration Fragment:* Run the ``diffconfig`` command | 1179 | 3. *Create the Configuration Fragment:* Run the ``diffconfig`` command |
1180 | to prepare a configuration fragment. The resulting file | 1180 | to prepare a configuration fragment. The resulting file |
1181 | ``fragment.cfg`` is placed in the | 1181 | ``fragment.cfg`` is placed in the |
1182 | ``${``\ ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__\ ``}`` | 1182 | ``${``\ :term:`WORKDIR`\ ``}`` |
1183 | directory: $ bitbake linux-yocto -c diffconfig | 1183 | directory: $ bitbake linux-yocto -c diffconfig |
1184 | 1184 | ||
1185 | The ``diffconfig`` command creates a file that is a list of Linux kernel | 1185 | The ``diffconfig`` command creates a file that is a list of Linux kernel |
@@ -1196,7 +1196,7 @@ information on how to use the output as a configuration fragment. | |||
1196 | 1196 | ||
1197 | Where do you put your configuration fragment files? You can place these | 1197 | Where do you put your configuration fragment files? You can place these |
1198 | files in an area pointed to by | 1198 | files in an area pointed to by |
1199 | ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ as directed by your | 1199 | :term:`SRC_URI` as directed by your |
1200 | ``bblayers.conf`` file, which is located in your layer. The OpenEmbedded | 1200 | ``bblayers.conf`` file, which is located in your layer. The OpenEmbedded |
1201 | build system picks up the configuration and adds it to the kernel's | 1201 | build system picks up the configuration and adds it to the kernel's |
1202 | configuration. For example, suppose you had a set of configuration | 1202 | configuration. For example, suppose you had a set of configuration |
@@ -1219,7 +1219,7 @@ Validating Configuration | |||
1219 | ------------------------ | 1219 | ------------------------ |
1220 | 1220 | ||
1221 | You can use the | 1221 | You can use the |
1222 | ```do_kernel_configcheck`` <&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck>`__ | 1222 | :ref:`ref-tasks-kernel_configcheck` |
1223 | task to provide configuration validation: $ bitbake linux-yocto -c | 1223 | task to provide configuration validation: $ bitbake linux-yocto -c |
1224 | kernel_configcheck -f Running this task produces warnings for when a | 1224 | kernel_configcheck -f Running this task produces warnings for when a |
1225 | requested configuration does not appear in the final ``.config`` file or | 1225 | requested configuration does not appear in the final ``.config`` file or |
@@ -1268,9 +1268,9 @@ The output describes the various problems that you can encounter along | |||
1268 | with where to find the offending configuration items. You can use the | 1268 | with where to find the offending configuration items. You can use the |
1269 | information in the logs to adjust your configuration files and then | 1269 | information in the logs to adjust your configuration files and then |
1270 | repeat the | 1270 | repeat the |
1271 | ```do_kernel_configme`` <&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme>`__ | 1271 | :ref:`ref-tasks-kernel_configme` |
1272 | and | 1272 | and |
1273 | ```do_kernel_configcheck`` <&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck>`__ | 1273 | :ref:`ref-tasks-kernel_configcheck` |
1274 | tasks until they produce no warnings. | 1274 | tasks until they produce no warnings. |
1275 | 1275 | ||
1276 | For more information on how to use the ``menuconfig`` tool, see the | 1276 | For more information on how to use the ``menuconfig`` tool, see the |
@@ -1395,7 +1395,7 @@ If you cannot work with one of the Linux kernel versions supported by | |||
1395 | existing linux-yocto recipes, you can still make use of the Yocto | 1395 | existing linux-yocto recipes, you can still make use of the Yocto |
1396 | Project Linux kernel tooling by working with your own sources. When you | 1396 | Project Linux kernel tooling by working with your own sources. When you |
1397 | use your own sources, you will not be able to leverage the existing | 1397 | use your own sources, you will not be able to leverage the existing |
1398 | kernel `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ and stabilization | 1398 | kernel :term:`Metadata` and stabilization |
1399 | work of the linux-yocto sources. However, you will be able to manage | 1399 | work of the linux-yocto sources. However, you will be able to manage |
1400 | your own Metadata in the same format as the linux-yocto sources. | 1400 | your own Metadata in the same format as the linux-yocto sources. |
1401 | Maintaining format compatibility facilitates converging with linux-yocto | 1401 | Maintaining format compatibility facilitates converging with linux-yocto |
@@ -1428,7 +1428,7 @@ Here are some basic steps you can use to work with your own sources: | |||
1428 | the following: $ make defconfig After running the command, copy the | 1428 | the following: $ make defconfig After running the command, copy the |
1429 | resulting ``.config`` file to the ``files`` directory in your layer | 1429 | resulting ``.config`` file to the ``files`` directory in your layer |
1430 | as "defconfig" and then add it to the | 1430 | as "defconfig" and then add it to the |
1431 | ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ variable in the | 1431 | :term:`SRC_URI` variable in the |
1432 | recipe. | 1432 | recipe. |
1433 | 1433 | ||
1434 | Running the ``make defconfig`` command results in the default | 1434 | Running the ``make defconfig`` command results in the default |
@@ -1445,7 +1445,7 @@ Here are some basic steps you can use to work with your own sources: | |||
1445 | 4. *Edit the Recipe:* Edit the following variables in your recipe as | 1445 | 4. *Edit the Recipe:* Edit the following variables in your recipe as |
1446 | appropriate for your project: | 1446 | appropriate for your project: |
1447 | 1447 | ||
1448 | - ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__: The | 1448 | - :term:`SRC_URI`: The |
1449 | ``SRC_URI`` should specify a Git repository that uses one of the | 1449 | ``SRC_URI`` should specify a Git repository that uses one of the |
1450 | supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``, | 1450 | supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``, |
1451 | and so forth). The ``SRC_URI`` variable should also specify either | 1451 | and so forth). The ``SRC_URI`` variable should also specify either |
@@ -1453,32 +1453,32 @@ Here are some basic steps you can use to work with your own sources: | |||
1453 | skeleton recipe provides an example ``SRC_URI`` as a syntax | 1453 | skeleton recipe provides an example ``SRC_URI`` as a syntax |
1454 | reference. | 1454 | reference. |
1455 | 1455 | ||
1456 | - ```LINUX_VERSION`` <&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION>`__: | 1456 | - :term:`LINUX_VERSION`: |
1457 | The Linux kernel version you are using (e.g. "4.12"). | 1457 | The Linux kernel version you are using (e.g. "4.12"). |
1458 | 1458 | ||
1459 | - ```LINUX_VERSION_EXTENSION`` <&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION>`__: | 1459 | - :term:`LINUX_VERSION_EXTENSION`: |
1460 | The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the | 1460 | The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the |
1461 | resulting kernel and visible through the ``uname`` command. | 1461 | resulting kernel and visible through the ``uname`` command. |
1462 | 1462 | ||
1463 | - ```SRCREV`` <&YOCTO_DOCS_REF_URL;#var-SRCREV>`__: The commit ID | 1463 | - :term:`SRCREV`: The commit ID |
1464 | from which you want to build. | 1464 | from which you want to build. |
1465 | 1465 | ||
1466 | - ```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__: Treat this variable the | 1466 | - :term:`PR`: Treat this variable the |
1467 | same as you would in any other recipe. Increment the variable to | 1467 | same as you would in any other recipe. Increment the variable to |
1468 | indicate to the OpenEmbedded build system that the recipe has | 1468 | indicate to the OpenEmbedded build system that the recipe has |
1469 | changed. | 1469 | changed. |
1470 | 1470 | ||
1471 | - ```PV`` <&YOCTO_DOCS_REF_URL;#var-PV>`__: The default ``PV`` | 1471 | - :term:`PV`: The default ``PV`` |
1472 | assignment is typically adequate. It combines the | 1472 | assignment is typically adequate. It combines the |
1473 | ``LINUX_VERSION`` with the Source Control Manager (SCM) revision | 1473 | ``LINUX_VERSION`` with the Source Control Manager (SCM) revision |
1474 | as derived from the ```SRCPV`` <&YOCTO_DOCS_REF_URL;#var-SRCPV>`__ | 1474 | as derived from the :term:`SRCPV` |
1475 | variable. The combined results are a string with the following | 1475 | variable. The combined results are a string with the following |
1476 | form: | 1476 | form: |
1477 | 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 | 1477 | 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 |
1478 | While lengthy, the extra verbosity in ``PV`` helps ensure you are | 1478 | While lengthy, the extra verbosity in ``PV`` helps ensure you are |
1479 | using the exact sources from which you intend to build. | 1479 | using the exact sources from which you intend to build. |
1480 | 1480 | ||
1481 | - ```COMPATIBLE_MACHINE`` <&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE>`__: | 1481 | - :term:`COMPATIBLE_MACHINE`: |
1482 | A list of the machines supported by your new recipe. This variable | 1482 | A list of the machines supported by your new recipe. This variable |
1483 | in the example recipe is set by default to a regular expression | 1483 | in the example recipe is set by default to a regular expression |
1484 | that matches only the empty string, "(^$)". This default setting | 1484 | that matches only the empty string, "(^$)". This default setting |
@@ -1546,13 +1546,13 @@ or other files necessary for building the module that do not come with | |||
1546 | the sources. Finally, update the recipe as needed for the module. | 1546 | the sources. Finally, update the recipe as needed for the module. |
1547 | Typically, you will need to set the following variables: | 1547 | Typically, you will need to set the following variables: |
1548 | 1548 | ||
1549 | - ```DESCRIPTION`` <&YOCTO_DOCS_REF_URL;#var-DESCRIPTION>`__ | 1549 | - :term:`DESCRIPTION` |
1550 | 1550 | ||
1551 | - ```LICENSE*`` <&YOCTO_DOCS_REF_URL;#var-LICENSE>`__ | 1551 | - ```LICENSE*`` <&YOCTO_DOCS_REF_URL;#var-LICENSE>`__ |
1552 | 1552 | ||
1553 | - ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ | 1553 | - :term:`SRC_URI` |
1554 | 1554 | ||
1555 | - ```PV`` <&YOCTO_DOCS_REF_URL;#var-PV>`__ | 1555 | - :term:`PV` |
1556 | 1556 | ||
1557 | Depending on the build system used by the module sources, you might need | 1557 | Depending on the build system used by the module sources, you might need |
1558 | to make some adjustments. For example, a typical module ``Makefile`` | 1558 | to make some adjustments. For example, a typical module ``Makefile`` |
@@ -1561,14 +1561,14 @@ looks much like the one provided with the ``hello-mod`` template: obj-m | |||
1561 | modules_install: $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install ... | 1561 | modules_install: $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install ... |
1562 | 1562 | ||
1563 | The important point to note here is the | 1563 | The important point to note here is the |
1564 | ```KERNEL_SRC`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC>`__ variable. The | 1564 | :term:`KERNEL_SRC` variable. The |
1565 | ```module`` <&YOCTO_DOCS_REF_URL;#ref-classes-module>`__ class sets this | 1565 | :ref:`module <ref-classes-module>` class sets this |
1566 | variable and the | 1566 | variable and the |
1567 | ```KERNEL_PATH`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH>`__ variable to | 1567 | :term:`KERNEL_PATH` variable to |
1568 | ``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build | 1568 | ``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build |
1569 | information to build modules. If your module ``Makefile`` uses a | 1569 | information to build modules. If your module ``Makefile`` uses a |
1570 | different variable, you might want to override the | 1570 | different variable, you might want to override the |
1571 | ```do_compile`` <&YOCTO_DOCS_REF_URL;#ref-tasks-compile>`__ step, or | 1571 | :ref:`ref-tasks-compile` step, or |
1572 | create a patch to the ``Makefile`` to work with the more typical | 1572 | create a patch to the ``Makefile`` to work with the more typical |
1573 | ``KERNEL_SRC`` or ``KERNEL_PATH`` variables. | 1573 | ``KERNEL_SRC`` or ``KERNEL_PATH`` variables. |
1574 | 1574 | ||
@@ -1577,13 +1577,13 @@ module in your images. To do this, see the documentation for the | |||
1577 | following variables in the Yocto Project Reference Manual and set one of | 1577 | following variables in the Yocto Project Reference Manual and set one of |
1578 | them appropriately for your machine configuration file: | 1578 | them appropriately for your machine configuration file: |
1579 | 1579 | ||
1580 | - ```MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS>`__ | 1580 | - :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` |
1581 | 1581 | ||
1582 | - ```MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS>`__ | 1582 | - :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` |
1583 | 1583 | ||
1584 | - ```MACHINE_EXTRA_RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS>`__ | 1584 | - :term:`MACHINE_EXTRA_RDEPENDS` |
1585 | 1585 | ||
1586 | - ```MACHINE_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS>`__ | 1586 | - :term:`MACHINE_EXTRA_RRECOMMENDS` |
1587 | 1587 | ||
1588 | Modules are often not required for boot and can be excluded from certain | 1588 | Modules are often not required for boot and can be excluded from certain |
1589 | build configurations. The following allows for the most flexibility: | 1589 | build configurations. The following allows for the most flexibility: |
@@ -1592,8 +1592,8 @@ derived by appending the module filename without the ``.ko`` extension | |||
1592 | to the string "kernel-module-". | 1592 | to the string "kernel-module-". |
1593 | 1593 | ||
1594 | Because the variable is | 1594 | Because the variable is |
1595 | ```RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS>`__ and not a | 1595 | :term:`RRECOMMENDS` and not a |
1596 | ```RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-RDEPENDS>`__ variable, the build | 1596 | :term:`RDEPENDS` variable, the build |
1597 | will not fail if this module is not available to include in the image. | 1597 | will not fail if this module is not available to include in the image. |
1598 | 1598 | ||
1599 | Inspecting Changes and Commits | 1599 | Inspecting Changes and Commits |
@@ -1661,9 +1661,9 @@ Adding Recipe-Space Kernel Features | |||
1661 | 1661 | ||
1662 | You can add kernel features in the | 1662 | You can add kernel features in the |
1663 | `recipe-space <#recipe-space-metadata>`__ by using the | 1663 | `recipe-space <#recipe-space-metadata>`__ by using the |
1664 | ```KERNEL_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES>`__ | 1664 | :term:`KERNEL_FEATURES` |
1665 | variable and by specifying the feature's ``.scc`` file path in the | 1665 | variable and by specifying the feature's ``.scc`` file path in the |
1666 | ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statement. When you | 1666 | :term:`SRC_URI` statement. When you |
1667 | add features using this method, the OpenEmbedded build system checks to | 1667 | add features using this method, the OpenEmbedded build system checks to |
1668 | be sure the features are present. If the features are not present, the | 1668 | be sure the features are present. If the features are not present, the |
1669 | build stops. Kernel features are the last elements processed for | 1669 | build stops. Kernel features are the last elements processed for |
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.rst b/documentation/kernel-dev/kernel-dev-concepts-appx.rst index f3349a6be4..ed1486b65d 100644 --- a/documentation/kernel-dev/kernel-dev-concepts-appx.rst +++ b/documentation/kernel-dev/kernel-dev-concepts-appx.rst | |||
@@ -313,7 +313,7 @@ The temporary kernel source files resulting from a build using BitBake | |||
313 | have a particular hierarchy. When you build the kernel on your | 313 | have a particular hierarchy. When you build the kernel on your |
314 | development system, all files needed for the build are taken from the | 314 | development system, all files needed for the build are taken from the |
315 | source repositories pointed to by the | 315 | source repositories pointed to by the |
316 | ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ variable and gathered | 316 | :term:`SRC_URI` variable and gathered |
317 | in a temporary work area where they are subsequently used to create the | 317 | in a temporary work area where they are subsequently used to create the |
318 | unique kernel. Thus, in a sense, the process constructs a local source | 318 | unique kernel. Thus, in a sense, the process constructs a local source |
319 | tree specific to your kernel from which to generate the new kernel | 319 | tree specific to your kernel from which to generate the new kernel |
diff --git a/documentation/kernel-dev/kernel-dev-faq.rst b/documentation/kernel-dev/kernel-dev-faq.rst index 9ae93506e9..fd9f8ce33d 100644 --- a/documentation/kernel-dev/kernel-dev-faq.rst +++ b/documentation/kernel-dev/kernel-dev-faq.rst | |||
@@ -28,12 +28,12 @@ append file to override metadata. How do I install a specific kernel | |||
28 | module? Linux kernel modules are packaged individually. To ensure a | 28 | module? Linux kernel modules are packaged individually. To ensure a |
29 | specific kernel module is included in an image, include it in the | 29 | specific kernel module is included in an image, include it in the |
30 | appropriate machine | 30 | appropriate machine |
31 | ```RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS>`__ variable. | 31 | :term:`RRECOMMENDS` variable. |
32 | These other variables are useful for installing specific modules: | 32 | These other variables are useful for installing specific modules: |
33 | ```MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS>`__ | 33 | :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` |
34 | ```MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS>`__ | 34 | :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` |
35 | ```MACHINE_EXTRA_RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS>`__ | 35 | :term:`MACHINE_EXTRA_RDEPENDS` |
36 | ```MACHINE_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS>`__ | 36 | :term:`MACHINE_EXTRA_RRECOMMENDS` |
37 | For example, set the following in the ``qemux86.conf`` file to include | 37 | For example, set the following in the ``qemux86.conf`` file to include |
38 | the ``ab123`` kernel modules with images built for the ``qemux86`` | 38 | the ``ab123`` kernel modules with images built for the ``qemux86`` |
39 | machine: MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123" For more | 39 | machine: MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123" For more |
diff --git a/documentation/kernel-dev/kernel-dev-intro.rst b/documentation/kernel-dev/kernel-dev-intro.rst index 82a77913b7..cb4ffcf13b 100644 --- a/documentation/kernel-dev/kernel-dev-intro.rst +++ b/documentation/kernel-dev/kernel-dev-intro.rst | |||
@@ -13,7 +13,7 @@ Regardless of how you intend to make use of the Yocto Project, chances | |||
13 | are you will work with the Linux kernel. This manual describes how to | 13 | are you will work with the Linux kernel. This manual describes how to |
14 | set up your build host to support kernel development, introduces the | 14 | set up your build host to support kernel development, introduces the |
15 | kernel development process, provides background information on the Yocto | 15 | kernel development process, provides background information on the Yocto |
16 | Linux kernel `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__, describes | 16 | Linux kernel :term:`Metadata`, describes |
17 | common tasks you can perform using the kernel tools, shows you how to | 17 | common tasks you can perform using the kernel tools, shows you how to |
18 | use the kernel Metadata needed to work with the kernel inside the Yocto | 18 | use the kernel Metadata needed to work with the kernel inside the Yocto |
19 | Project, and provides insight into how the Yocto Project team develops | 19 | Project, and provides insight into how the Yocto Project team develops |
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.rst b/documentation/kernel-dev/kernel-dev-maint-appx.rst index b4e5f199c9..d76e789d56 100644 --- a/documentation/kernel-dev/kernel-dev-maint-appx.rst +++ b/documentation/kernel-dev/kernel-dev-maint-appx.rst | |||
@@ -111,7 +111,7 @@ patch, or BSP: | |||
111 | 111 | ||
112 | 4. *Append Extra Features:* Extra features are appended to the top-level | 112 | 4. *Append Extra Features:* Extra features are appended to the top-level |
113 | feature description. These features can come from the | 113 | feature description. These features can come from the |
114 | ```KERNEL_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES>`__ | 114 | :term:`KERNEL_FEATURES` |
115 | variable in recipes. | 115 | variable in recipes. |
116 | 116 | ||
117 | 5. *Locate, Expand, and Append Each Feature:* Each extra feature is | 117 | 5. *Locate, Expand, and Append Each Feature:* Each extra feature is |
@@ -172,7 +172,7 @@ can consider the compilation phase of kernel development, which is | |||
172 | building a kernel image. Some prerequisites exist that are validated by | 172 | building a kernel image. Some prerequisites exist that are validated by |
173 | the build process before compilation starts: | 173 | the build process before compilation starts: |
174 | 174 | ||
175 | - The ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ points to the | 175 | - The :term:`SRC_URI` points to the |
176 | kernel Git repository. | 176 | kernel Git repository. |
177 | 177 | ||
178 | - A BSP build branch with Metadata exists in the ``yocto-kernel-cache`` | 178 | - A BSP build branch with Metadata exists in the ``yocto-kernel-cache`` |