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 | ||