diff options
| -rw-r--r-- | documentation/Makefile | 3 | ||||
| -rw-r--r-- | documentation/dev-manual/dev-manual-model.xml | 147 | ||||
| -rw-r--r-- | documentation/kernel-dev/figures/kernel-dev-flow.png (renamed from documentation/dev-manual/figures/kernel-dev-flow.png) | bin | 35561 -> 35561 bytes | |||
| -rw-r--r-- | documentation/kernel-dev/kernel-dev-concepts-appx.xml | 5 | ||||
| -rw-r--r-- | documentation/kernel-dev/kernel-dev-intro.xml | 320 |
5 files changed, 228 insertions, 247 deletions
diff --git a/documentation/Makefile b/documentation/Makefile index 93cf6ca726..770ef93f37 100644 --- a/documentation/Makefile +++ b/documentation/Makefile | |||
| @@ -130,7 +130,6 @@ TARFILES = dev-style.css dev-manual.html \ | |||
| 130 | else | 130 | else |
| 131 | TARFILES = dev-style.css dev-manual.html \ | 131 | TARFILES = dev-style.css dev-manual.html \ |
| 132 | figures/dev-title.png \ | 132 | figures/dev-title.png \ |
| 133 | figures/kernel-dev-flow.png \ | ||
| 134 | figures/recipe-workflow.png \ | 133 | figures/recipe-workflow.png \ |
| 135 | figures/devtool-add-flow.png figures/devtool-modify-flow.png \ | 134 | figures/devtool-add-flow.png figures/devtool-modify-flow.png \ |
| 136 | figures/devtool-upgrade-flow.png \ | 135 | figures/devtool-upgrade-flow.png \ |
| @@ -330,7 +329,7 @@ XSLTOPTS = --xinclude | |||
| 330 | ALLPREQ = html eclipse tarball | 329 | ALLPREQ = html eclipse tarball |
| 331 | TARFILES = kernel-dev.html kernel-dev-style.css \ | 330 | TARFILES = kernel-dev.html kernel-dev-style.css \ |
| 332 | figures/kernel-dev-title.png figures/kernel-overview-2-generic \ | 331 | figures/kernel-dev-title.png figures/kernel-overview-2-generic \ |
| 333 | figures/kernel-architecture-overview.png \ | 332 | figures/kernel-architecture-overview.png figures/kernel-dev-flow.png \ |
| 334 | eclipse | 333 | eclipse |
| 335 | MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse | 334 | MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse |
| 336 | FIGURES = figures | 335 | FIGURES = figures |
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index 0055bccfed..b1b5efa82c 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml | |||
| @@ -41,153 +41,6 @@ | |||
| 41 | </itemizedlist> | 41 | </itemizedlist> |
| 42 | </para> | 42 | </para> |
| 43 | 43 | ||
| 44 | <section id='system-development-model'> | ||
| 45 | <title>System Development Workflow</title> | ||
| 46 | |||
| 47 | <para> | ||
| 48 | System development involves modification or creation of an image that you want to run on | ||
| 49 | a specific hardware target. | ||
| 50 | Usually, when you want to create an image that runs on embedded hardware, the image does | ||
| 51 | not require the same number of features that a full-fledged Linux distribution provides. | ||
| 52 | Thus, you can create a much smaller image that is designed to use only the | ||
| 53 | features for your particular hardware. | ||
| 54 | </para> | ||
| 55 | |||
| 56 | <para> | ||
| 57 | To help you understand how system development works in the Yocto Project, this section | ||
| 58 | covers two types of image development: BSP creation and kernel modification or | ||
| 59 | configuration. | ||
| 60 | </para> | ||
| 61 | |||
| 62 | <section id='modifying-the-kernel'> | ||
| 63 | <title><anchor id='kernel-spot' />Modifying the Kernel</title> | ||
| 64 | |||
| 65 | <para> | ||
| 66 | Kernel modification involves changing the Yocto Project kernel, which could involve changing | ||
| 67 | configuration options as well as adding new kernel recipes. | ||
| 68 | Configuration changes can be added in the form of configuration fragments, while recipe | ||
| 69 | modification comes through the kernel's <filename>recipes-kernel</filename> area | ||
| 70 | in a kernel layer you create. | ||
| 71 | </para> | ||
| 72 | |||
| 73 | <para> | ||
| 74 | The remainder of this section presents a high-level overview of the Yocto Project | ||
| 75 | kernel architecture and the steps to modify the kernel. | ||
| 76 | You can reference the | ||
| 77 | "<link linkend='patching-the-kernel'>Patching the Kernel</link>" section | ||
| 78 | for an example that changes the source code of the kernel. | ||
| 79 | For information on how to configure the kernel, see the | ||
| 80 | "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" section. | ||
| 81 | For more information on the kernel and on modifying the kernel, see the | ||
| 82 | <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. | ||
| 83 | </para> | ||
| 84 | |||
| 85 | <section id='kernel-modification-workflow'> | ||
| 86 | <title>Kernel Modification Workflow</title> | ||
| 87 | |||
| 88 | <para> | ||
| 89 | This illustration and the following list summarizes the kernel modification general workflow. | ||
| 90 | </para> | ||
| 91 | |||
| 92 | <para> | ||
| 93 | <imagedata fileref="figures/kernel-dev-flow.png" | ||
| 94 | width="6in" depth="5in" align="center" scalefit="1" /> | ||
| 95 | </para> | ||
| 96 | |||
| 97 | <para> | ||
| 98 | <orderedlist> | ||
| 99 | <listitem><para><emphasis>Set up your host development system to support | ||
| 100 | development using the Yocto Project</emphasis>: See | ||
| 101 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and | ||
| 102 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" sections both | ||
| 103 | in the Yocto Project Quick Start for requirements.</para></listitem> | ||
| 104 | <listitem><para><emphasis>Establish a local copy of project files on your | ||
| 105 | system</emphasis>: Having the | ||
| 106 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> | ||
| 107 | on your system gives you access to the build process and tools | ||
| 108 | you need. | ||
| 109 | For information on how to get these files, see the | ||
| 110 | "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>" | ||
| 111 | section. | ||
| 112 | </para></listitem> | ||
| 113 | <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>: | ||
| 114 | Temporary kernel source files are kept in the | ||
| 115 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> | ||
| 116 | created by the | ||
| 117 | OpenEmbedded build system when you run BitBake. | ||
| 118 | If you have never built the kernel in which you are | ||
| 119 | interested, you need to run an initial build to | ||
| 120 | establish local kernel source files.</para> | ||
| 121 | <para>If you are building an image for the first time, you need to get the build | ||
| 122 | environment ready by sourcing an environment setup script | ||
| 123 | (i.e. <filename>oe-init-build-env</filename> or | ||
| 124 | <filename>oe-init-build-env-memres</filename>). | ||
| 125 | You also need to be sure two key configuration files | ||
| 126 | (<filename>local.conf</filename> and <filename>bblayers.conf</filename>) | ||
| 127 | are configured appropriately.</para> | ||
| 128 | <para>The entire process for building an image is overviewed in the | ||
| 129 | "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" | ||
| 130 | section of the Yocto Project Quick Start. | ||
| 131 | You might want to reference this information. | ||
| 132 | You can find more information on BitBake in the | ||
| 133 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | ||
| 134 | </para> | ||
| 135 | <para>The build process supports several types of images to satisfy different needs. | ||
| 136 | See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in | ||
| 137 | the Yocto Project Reference Manual for information on supported images. | ||
| 138 | </para></listitem> | ||
| 139 | <listitem><para><emphasis>Make changes to the kernel source code if | ||
| 140 | applicable</emphasis>: Modifying the kernel does not always mean directly | ||
| 141 | changing source files. | ||
| 142 | However, if you have to do this, you make the changes to the files in the | ||
| 143 | Build Directory.</para></listitem> | ||
| 144 | <listitem><para><emphasis>Make kernel configuration changes if applicable</emphasis>: | ||
| 145 | If your situation calls for changing the kernel's | ||
| 146 | configuration, you can use | ||
| 147 | <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'><filename>menuconfig</filename></ulink>, | ||
| 148 | which allows you to interactively develop and test the | ||
| 149 | configuration changes you are making to the kernel. | ||
| 150 | Saving changes you make with | ||
| 151 | <filename>menuconfig</filename> updates | ||
| 152 | the kernel's <filename>.config</filename> file. | ||
| 153 | <note><title>Warning</title> | ||
| 154 | Try to resist the temptation to directly edit an | ||
| 155 | existing <filename>.config</filename> file, which is | ||
| 156 | found in the Build Directory among the source code | ||
| 157 | used for the build (e.g. see the workflow illustration | ||
| 158 | in the | ||
| 159 | "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>" | ||
| 160 | section). | ||
| 161 | Doing so, can produce unexpected results when the | ||
| 162 | OpenEmbedded build system regenerates the configuration | ||
| 163 | file. | ||
| 164 | </note> | ||
| 165 | Once you are satisfied with the configuration | ||
| 166 | changes made using <filename>menuconfig</filename> | ||
| 167 | and you have saved them, you can directly compare the | ||
| 168 | resulting <filename>.config</filename> file against an | ||
| 169 | existing original and gather those changes into a | ||
| 170 | <link linkend='creating-config-fragments'>configuration fragment file</link> | ||
| 171 | to be referenced from within the kernel's | ||
| 172 | <filename>.bbappend</filename> file.</para> | ||
| 173 | |||
| 174 | <para>Additionally, if you are working in a BSP layer | ||
| 175 | and need to modify the BSP's kernel's configuration, | ||
| 176 | you can use the | ||
| 177 | <ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'><filename>yocto-kernel</filename></ulink> | ||
| 178 | script as well as <filename>menuconfig</filename>. | ||
| 179 | The <filename>yocto-kernel</filename> script lets | ||
| 180 | you interactively set up kernel configurations. | ||
| 181 | </para></listitem> | ||
| 182 | <listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>: | ||
| 183 | Rebuilding the kernel image applies your changes. | ||
| 184 | </para></listitem> | ||
| 185 | </orderedlist> | ||
| 186 | </para> | ||
| 187 | </section> | ||
| 188 | </section> | ||
| 189 | </section> | ||
| 190 | |||
| 191 | <section id="dev-modifying-source-code"> | 44 | <section id="dev-modifying-source-code"> |
| 192 | <title>Modifying Source Code</title> | 45 | <title>Modifying Source Code</title> |
| 193 | 46 | ||
diff --git a/documentation/dev-manual/figures/kernel-dev-flow.png b/documentation/kernel-dev/figures/kernel-dev-flow.png index 009105d122..009105d122 100644 --- a/documentation/dev-manual/figures/kernel-dev-flow.png +++ b/documentation/kernel-dev/figures/kernel-dev-flow.png | |||
| Binary files differ | |||
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml index 8eb8c30dce..7f6b82fee5 100644 --- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml +++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml | |||
| @@ -406,9 +406,8 @@ | |||
| 406 | Yocto Project, is the preferred method by which to | 406 | Yocto Project, is the preferred method by which to |
| 407 | modify the kernel. | 407 | modify the kernel. |
| 408 | See the | 408 | See the |
| 409 | "<ulink url='&YOCTO_DOCS_DEV_URL;#kernel-modification-workflow'>Kernel Modification Workflow</ulink>" | 409 | "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>" |
| 410 | section in the Yocto Project Development Manual for | 410 | section. |
| 411 | information. | ||
| 412 | </para></listitem> | 411 | </para></listitem> |
| 413 | <listitem><para> | 412 | <listitem><para> |
| 414 | <emphasis>Cloned Repository:</emphasis> | 413 | <emphasis>Cloned Repository:</emphasis> |
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml index 83ca988acf..9f385d9751 100644 --- a/documentation/kernel-dev/kernel-dev-intro.xml +++ b/documentation/kernel-dev/kernel-dev-intro.xml | |||
| @@ -5,105 +5,234 @@ | |||
| 5 | <chapter id='kernel-dev-intro'> | 5 | <chapter id='kernel-dev-intro'> |
| 6 | <title>Introduction</title> | 6 | <title>Introduction</title> |
| 7 | 7 | ||
| 8 | <!-- | 8 | <section id='kernel-dev-overview'> |
| 9 | <para> | 9 | <title>Overview</title> |
| 10 | <emphasis>AR - Darren Hart:</emphasis> See if the concepts in these | ||
| 11 | three bullets are adequately covered in somewhere in this manual: | ||
| 12 | <itemizedlist> | ||
| 13 | <listitem><para>Do we convey that our kernel Git repositories | ||
| 14 | have a clear and continuous history, similar to the way the | ||
| 15 | kernel Git repositories for <filename>kernel.org</filename> | ||
| 16 | do. | ||
| 17 | </para></listitem> | ||
| 18 | <listitem><para>Does the manual note that Yocto Project delivers | ||
| 19 | a key set of supported kernel types, where | ||
| 20 | each type is tailored to meet a specific use (e.g. networking, | ||
| 21 | consumer, devices, and so forth).</para></listitem> | ||
| 22 | <listitem><para>Do we convey that the Yocto Project uses a | ||
| 23 | Git branching strategy that, from a | ||
| 24 | developer's point of view, results in a linear path from the | ||
| 25 | baseline kernel.org, through a select group of features and | ||
| 26 | ends with their BSP-specific commits.</para></listitem> | ||
| 27 | </itemizedlist> | ||
| 28 | </para> | ||
| 29 | --> | ||
| 30 | 10 | ||
| 31 | <section id='kernel-dev-overview'> | 11 | <para> |
| 32 | <title>Overview</title> | 12 | Regardless of how you intend to make use of the Yocto Project, |
| 13 | chances are you will work with the Linux kernel. | ||
| 14 | This manual introduces the kernel development process and | ||
| 15 | provides background information on the Yocto Linux kernel | ||
| 16 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>, | ||
| 17 | describes common tasks you can perform using the kernel tools, | ||
| 18 | and shows you how to use the kernel Metadata needed to work with | ||
| 19 | the kernel inside the Yocto Project. | ||
| 20 | </para> | ||
| 33 | 21 | ||
| 34 | <para> | 22 | <para> |
| 35 | Regardless of how you intend to make use of the Yocto Project, | 23 | Each Yocto Project release has a set of Yocto Linux kernel recipes, |
| 36 | chances are you will work with the Linux kernel. | 24 | whose Git repositories you can view in the Yocto |
| 37 | This manual provides background information on the Yocto Linux kernel | 25 | <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under |
| 38 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>, | 26 | the "Yocto Linux Kernel" heading. |
| 39 | describes common tasks you can perform using the kernel tools, | 27 | New recipes for the release track the latest Linux kernel |
| 40 | and shows you how to use the kernel Metadata needed to work with | 28 | upstream developments from |
| 41 | the kernel inside the Yocto Project. | 29 | <ulink url='http://www.kernel.org'></ulink> and introduce |
| 42 | </para> | 30 | newly-supported platforms. |
| 43 | 31 | Previous recipes in the release are refreshed and supported for at | |
| 44 | <para> | 32 | least one additional Yocto Project release. |
| 45 | Each Yocto Project release has a set of linux-yocto recipes, whose | 33 | As they align, these previous releases are updated to include the |
| 46 | Git repositories you can view in the Yocto | 34 | latest from the |
| 47 | <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under | 35 | <ulink url='&YOCTO_HOME_URL;/organization/long-term-support-initiative-ltsi'>Long Term Support Initiative</ulink> |
| 48 | the "Yocto Linux Kernel" heading. | 36 | (LTSI) project. |
| 49 | New recipes for the release track the latest upstream developments | 37 | Also included is a Yocto Linux kernel development recipe |
| 50 | and introduce newly-supported platforms. | 38 | (<filename>linux-yocto-dev.bb</filename>) should you want to work |
| 51 | Previous recipes in the release are refreshed and supported for at | 39 | with the very latest in upstream Yocto Linux kernel development and |
| 52 | least one additional release. | 40 | kernel Metadata development. |
| 53 | As they align, these previous releases are updated to include the | 41 | <note> |
| 54 | latest from the | 42 | For more on Yocto Linux kernels, see the |
| 55 | <ulink url='&YOCTO_HOME_URL;/organization/long-term-support-initiative-ltsi'>Long Term Support Initiative</ulink> | 43 | "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link> |
| 56 | (LTSI) project. | 44 | section. |
| 57 | Also included is a linux-yocto development recipe | 45 | </note> |
| 58 | (<filename>linux-yocto-dev.bb</filename>) should you want to work | 46 | </para> |
| 59 | with the very latest in upstream Linux kernel development and | ||
| 60 | kernel Metadata development. | ||
| 61 | </para> | ||
| 62 | 47 | ||
| 63 | <para> | 48 | <para> |
| 64 | The Yocto Project also provides a powerful set of kernel | 49 | The Yocto Project also provides a powerful set of kernel |
| 65 | tools for managing Linux kernel sources and configuration data. | 50 | tools for managing Yocto Linux kernel sources and configuration data. |
| 66 | You can use these tools to make a single configuration change, | 51 | You can use these tools to make a single configuration change, |
| 67 | apply multiple patches, or work with your own kernel sources. | 52 | apply multiple patches, or work with your own kernel sources. |
| 68 | </para> | 53 | </para> |
| 69 | 54 | ||
| 70 | <para> | 55 | <para> |
| 71 | In particular, the kernel tools allow you to generate configuration | 56 | In particular, the kernel tools allow you to generate configuration |
| 72 | fragments that specify only what you must, and nothing more. | 57 | fragments that specify only what you must, and nothing more. |
| 73 | Configuration fragments only need to contain the highest level | 58 | Configuration fragments only need to contain the highest level |
| 74 | visible <filename>CONFIG</filename> options as presented by the Linux | 59 | visible <filename>CONFIG</filename> options as presented by the |
| 75 | kernel <filename>menuconfig</filename> system. | 60 | Yocto Linux kernel <filename>menuconfig</filename> system. |
| 76 | Contrast this against a complete Linux kernel | 61 | Contrast this against a complete Yocto Linux kernel |
| 77 | <filename>.config</filename>, which includes all the automatically | 62 | <filename>.config</filename> file, which includes all the automatically |
| 78 | selected <filename>CONFIG</filename> options. | 63 | selected <filename>CONFIG</filename> options. |
| 79 | This efficiency reduces your maintenance effort and allows you | 64 | This efficiency reduces your maintenance effort and allows you |
| 80 | to further separate your configuration in ways that make sense for | 65 | to further separate your configuration in ways that make sense for |
| 81 | your project. | 66 | your project. |
| 82 | A common split separates policy and hardware. | 67 | A common split separates policy and hardware. |
| 83 | For example, all your kernels might support | 68 | For example, all your kernels might support the |
| 84 | the <filename>proc</filename> and <filename>sys</filename> filesystems, | 69 | <filename>proc</filename> and <filename>sys</filename> filesystems, |
| 85 | but only specific boards require sound, USB, or specific drivers. | 70 | but only specific boards require sound, USB, or specific drivers. |
| 86 | Specifying these configurations individually allows you to aggregate | 71 | Specifying these configurations individually allows you to aggregate |
| 87 | them together as needed, but maintains them in only one place. | 72 | them together as needed, but maintains them in only one place. |
| 88 | Similar logic applies to separating source changes. | 73 | Similar logic applies to separating source changes. |
| 89 | </para> | 74 | </para> |
| 90 | 75 | ||
| 91 | <para> | 76 | <para> |
| 92 | If you do not maintain your own kernel sources and need to make | 77 | If you do not maintain your own kernel sources and need to make |
| 93 | only minimal changes to the sources, the released recipes provide a | 78 | only minimal changes to the sources, the released recipes provide a |
| 94 | vetted base upon which to layer your changes. | 79 | vetted base upon which to layer your changes. |
| 95 | Doing so allows you to benefit from the continual kernel | 80 | Doing so allows you to benefit from the continual kernel |
| 96 | integration and testing performed during development of the | 81 | integration and testing performed during development of the |
| 97 | Yocto Project. | 82 | Yocto Project. |
| 98 | </para> | 83 | </para> |
| 84 | |||
| 85 | <para> | ||
| 86 | If, instead, you have a very specific Linux kernel source tree | ||
| 87 | and are unable to align with one of the official Yocto Linux kernel | ||
| 88 | recipes, an alternative exists by which you can use the Yocto | ||
| 89 | Project Linux kernel tools with your own kernel sources. | ||
| 90 | </para> | ||
| 91 | </section> | ||
| 92 | |||
| 93 | <section id='kernel-modification-workflow'> | ||
| 94 | <title>Kernel Modification Workflow</title> | ||
| 95 | |||
| 96 | <para> | ||
| 97 | Kernel modification involves changing the Yocto Project kernel, | ||
| 98 | which could involve changing configuration options as well as adding | ||
| 99 | new kernel recipes. | ||
| 100 | Configuration changes can be added in the form of configuration | ||
| 101 | fragments, while recipe modification comes through the kernel's | ||
| 102 | <filename>recipes-kernel</filename> area in a kernel layer you create. | ||
| 103 | </para> | ||
| 104 | |||
| 105 | <para> | ||
| 106 | This section presents a high-level overview of the Yocto Project | ||
| 107 | kernel modification workflow. | ||
| 108 | You can find additional information here: | ||
| 109 | <itemizedlist> | ||
| 110 | <listitem><para> | ||
| 111 | "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>" | ||
| 112 | in the Yocto Project Development Manual. | ||
| 113 | </para></listitem> | ||
| 114 | <listitem><para> | ||
| 115 | "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>" | ||
| 116 | in the Yocto Project Development Manual. | ||
| 117 | </para></listitem> | ||
| 118 | </itemizedlist> | ||
| 119 | This illustration and the following list summarizes the kernel | ||
| 120 | modification general workflow. | ||
| 121 | <imagedata fileref="figures/kernel-dev-flow.png" | ||
| 122 | width="6in" depth="5in" align="center" scalefit="1" /> | ||
| 123 | </para> | ||
| 124 | |||
| 125 | <para> | ||
| 126 | <orderedlist> | ||
| 127 | <listitem><para> | ||
| 128 | <emphasis>Set up Your Host Development System to Support | ||
| 129 | Development Using the Yocto Project</emphasis>: | ||
| 130 | See | ||
| 131 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" | ||
| 132 | and | ||
| 133 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" | ||
| 134 | sections both in the Yocto Project Quick Start for | ||
| 135 | requirements. | ||
| 136 | </para></listitem> | ||
| 137 | <listitem><para> | ||
| 138 | <emphasis>Clone the <filename>poky</filename> Repository</emphasis>: | ||
| 139 | Having the | ||
| 140 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> | ||
| 141 | on your system gives you access to the build process and tools | ||
| 142 | you need. | ||
| 143 | For information on how to get these files, see the | ||
| 144 | "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>" | ||
| 145 | section in the Yocto Project Development Manual. | ||
| 146 | </para></listitem> | ||
| 147 | <listitem><para> | ||
| 148 | <emphasis>Establish the Temporary Kernel Source Files</emphasis>: | ||
| 149 | Temporary kernel source files are kept in the | ||
| 150 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> | ||
| 151 | created by the OpenEmbedded build system when you run BitBake. | ||
| 152 | If you have never built the kernel in which you are | ||
| 153 | interested, you need to run an initial build to | ||
| 154 | establish local kernel source files.</para> | ||
| 155 | |||
| 156 | <para>If you are building an image for the first time, you | ||
| 157 | need to get the build environment ready by sourcing an | ||
| 158 | environment setup script | ||
| 159 | (i.e. <filename>oe-init-build-env</filename> or | ||
| 160 | <filename>oe-init-build-env-memres</filename>). | ||
| 161 | You also need to be sure two key configuration files | ||
| 162 | (<filename>local.conf</filename> and | ||
| 163 | <filename>bblayers.conf</filename>) are configured | ||
| 164 | appropriately.</para> | ||
| 165 | |||
| 166 | <para>The entire process for building an image is overviewed | ||
| 167 | in the | ||
| 168 | "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" | ||
| 169 | section of the Yocto Project Quick Start. | ||
| 170 | You might want to reference this information. | ||
| 171 | You can find more information on BitBake in the | ||
| 172 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | ||
| 173 | </para> | ||
| 174 | |||
| 175 | <para>The build process supports several types of images to | ||
| 176 | satisfy different needs. | ||
| 177 | See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" | ||
| 178 | chapter in the Yocto Project Reference Manual for information | ||
| 179 | on supported images. | ||
| 180 | </para></listitem> | ||
| 181 | <listitem><para> | ||
| 182 | <emphasis>Make Changes to the Kernel Source Code if | ||
| 183 | applicable</emphasis>: | ||
| 184 | Modifying the kernel does not always mean directly | ||
| 185 | changing source files. | ||
| 186 | However, if you have to do this, you make the changes to the | ||
| 187 | files in the Build Directory. | ||
| 188 | </para></listitem> | ||
| 189 | <listitem><para> | ||
| 190 | <emphasis>Make Kernel Configuration Changes if | ||
| 191 | Applicable</emphasis>: | ||
| 192 | If your situation calls for changing the kernel's | ||
| 193 | configuration, you can use | ||
| 194 | <link linkend='generating-configuration-files'><filename>menuconfig</filename></link>, | ||
| 195 | which allows you to interactively develop and test the | ||
| 196 | configuration changes you are making to the kernel. | ||
| 197 | Saving changes you make with <filename>menuconfig</filename> | ||
| 198 | updates the kernel's <filename>.config</filename> file. | ||
| 199 | <note><title>Warning</title> | ||
| 200 | Try to resist the temptation to directly edit an | ||
| 201 | existing <filename>.config</filename> file, which is | ||
| 202 | found in the Build Directory among the source code | ||
| 203 | used for the build (e.g. see the workflow illustration | ||
| 204 | in the | ||
| 205 | "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>" | ||
| 206 | section). | ||
| 207 | Doing so, can produce unexpected results when the | ||
| 208 | OpenEmbedded build system regenerates the configuration | ||
| 209 | file. | ||
| 210 | </note> | ||
| 211 | Once you are satisfied with the configuration | ||
| 212 | changes made using <filename>menuconfig</filename> | ||
| 213 | and you have saved them, you can directly compare the | ||
| 214 | resulting <filename>.config</filename> file against an | ||
| 215 | existing original and gather those changes into a | ||
| 216 | <ulink url='&YOCTO_DOCS_DEV_URL;#creating-config-fragments'>configuration fragment file</ulink> | ||
| 217 | to be referenced from within the kernel's | ||
| 218 | <filename>.bbappend</filename> file.</para> | ||
| 219 | |||
| 220 | <para>Additionally, if you are working in a BSP layer | ||
| 221 | and need to modify the BSP's kernel's configuration, | ||
| 222 | you can use the | ||
| 223 | <ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'><filename>yocto-kernel</filename></ulink> | ||
| 224 | script as well as <filename>menuconfig</filename>. | ||
| 225 | The <filename>yocto-kernel</filename> script lets | ||
| 226 | you interactively set up kernel configurations. | ||
| 227 | </para></listitem> | ||
| 228 | <listitem><para> | ||
| 229 | <emphasis>Rebuild the Kernel Image With Your Changes</emphasis>: | ||
| 230 | Rebuilding the kernel image applies your changes. | ||
| 231 | </para></listitem> | ||
| 232 | </orderedlist> | ||
| 233 | </para> | ||
| 234 | </section> | ||
| 99 | 235 | ||
| 100 | <para> | ||
| 101 | If, instead, you have a very specific Linux kernel source tree | ||
| 102 | and are unable to align with one of the official linux-yocto | ||
| 103 | recipes, an alternative exists by which you can use the Yocto | ||
| 104 | Project Linux kernel tools with your own kernel sources. | ||
| 105 | </para> | ||
| 106 | </section> | ||
| 107 | 236 | ||
| 108 | <section id='kernel-dev-other-resources'> | 237 | <section id='kernel-dev-other-resources'> |
| 109 | <title>Other Resources</title> | 238 | <title>Other Resources</title> |
| @@ -126,8 +255,9 @@ | |||
| 126 | </para></listitem> | 255 | </para></listitem> |
| 127 | <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" section | 256 | <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" section |
| 128 | in the Yocto Project Development Manual</para></listitem> | 257 | in the Yocto Project Development Manual</para></listitem> |
| 129 | <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel'>Modifying the Kernel</ulink>" section | 258 | <listitem><para>The "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>" |
| 130 | in the Yocto Project Development Manual.</para></listitem> | 259 | section. |
| 260 | </para></listitem> | ||
| 131 | </itemizedlist> | 261 | </itemizedlist> |
| 132 | </para> | 262 | </para> |
| 133 | 263 | ||
