diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2012-06-14 11:24:48 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2012-06-29 14:59:24 +0100 |
commit | ed26c02ac6cb435137ffaafddcd71fa5d7658076 (patch) | |
tree | 972b494263ce7db3ac85978c7c6c22f820260f8a | |
parent | 860acfbdaa0d0143d7c6ffd2f77e92189ea223d7 (diff) | |
download | poky-ed26c02ac6cb435137ffaafddcd71fa5d7658076.tar.gz |
documentation/dev-manual/dev-manual-model.xml: 1.1.2 variables and updates
First pass at implementing the poky.ent variables. Also updated text
in spots.
(From yocto-docs rev: bd91876ea4aa06088f43951e7c988d7445e46de0)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/dev-manual/dev-manual-model.xml | 184 |
1 files changed, 100 insertions, 84 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index 10206cbd79..30142a61b3 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml | |||
@@ -1,5 +1,6 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
3 | 4 | ||
4 | <chapter id='dev-manual-model'> | 5 | <chapter id='dev-manual-model'> |
5 | 6 | ||
@@ -23,9 +24,8 @@ | |||
23 | "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" appendix. | 24 | "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" appendix. |
24 | For a user-space application development example that uses the | 25 | For a user-space application development example that uses the |
25 | <trademark class='trade'>Eclipse</trademark> IDE, | 26 | <trademark class='trade'>Eclipse</trademark> IDE, |
26 | see the | 27 | see <ulink url='&YOCTO_DOCS_ADT_URL;'>The Yocto Project Application Development |
27 | <ulink url='http://www.yoctoproject.org/docs/1.1.1/adt-manual/adt-manual.html'> | 28 | Toolkit (ADT) User's Guide</ulink>. |
28 | The Yocto Project Application Development Toolkit (ADT) User's Guide</ulink>. | ||
29 | </para> | 29 | </para> |
30 | 30 | ||
31 | <section id='system-development-model'> | 31 | <section id='system-development-model'> |
@@ -35,8 +35,8 @@ | |||
35 | System development involves modification or creation of an image that you want to run on | 35 | System development involves modification or creation of an image that you want to run on |
36 | a specific hardware target. | 36 | a specific hardware target. |
37 | Usually, when you want to create an image that runs on embedded hardware, the image does | 37 | Usually, when you want to create an image that runs on embedded hardware, the image does |
38 | not require the same amount of features that a full-fledged Linux distribution provides. | 38 | not require the same number of features that a full-fledged Linux distribution provides. |
39 | Thus, you can create a much smaller image that is designed to just use the hardware | 39 | Thus, you can create a much smaller image that is designed to use only the hardware |
40 | features for your particular hardware. | 40 | features for your particular hardware. |
41 | </para> | 41 | </para> |
42 | 42 | ||
@@ -50,8 +50,8 @@ | |||
50 | <title>Developing a Board Support Package (BSP)</title> | 50 | <title>Developing a Board Support Package (BSP)</title> |
51 | 51 | ||
52 | <para> | 52 | <para> |
53 | A BSP is a package of recipes that, when applied, during a build results in | 53 | A BSP is a packageof recipes that, when applied, during a build results in |
54 | an image you can run on a particular board. | 54 | an image that you can run on a particular board. |
55 | Thus, the package, when compiled into the new image, supports the operation of the board. | 55 | Thus, the package, when compiled into the new image, supports the operation of the board. |
56 | </para> | 56 | </para> |
57 | 57 | ||
@@ -61,8 +61,8 @@ | |||
61 | </note> | 61 | </note> |
62 | 62 | ||
63 | <para> | 63 | <para> |
64 | The remainder of this section presents the basic steps to create a BSP basing it on an | 64 | The remainder of this section presents the basic steps used to create a BSP |
65 | existing BSP that ships with the Yocto Project. | 65 | based on an existing BSP that ships with the Yocto Project. |
66 | You can reference the "<link linkend='dev-manual-bsp-appendix'>BSP Development Example</link>" | 66 | You can reference the "<link linkend='dev-manual-bsp-appendix'>BSP Development Example</link>" |
67 | appendix for a detailed example that uses the Crown Bay BSP as a base BSP from which to start. | 67 | appendix for a detailed example that uses the Crown Bay BSP as a base BSP from which to start. |
68 | </para> | 68 | </para> |
@@ -79,18 +79,19 @@ | |||
79 | <orderedlist> | 79 | <orderedlist> |
80 | <listitem><para><emphasis>Set up your host development system to support | 80 | <listitem><para><emphasis>Set up your host development system to support |
81 | development using the Yocto Project</emphasis>: See the | 81 | development using the Yocto Project</emphasis>: See the |
82 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>The Linux Distributions</ulink>" and the | 82 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" |
83 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html#packages'>The Packages</ulink>" sections both | 83 | and the |
84 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both | ||
84 | in the Yocto Project Quick Start for requirements.</para></listitem> | 85 | in the Yocto Project Quick Start for requirements.</para></listitem> |
85 | <listitem><para><emphasis>Establish a local copy of the Yocto Project files on your | 86 | <listitem><para><emphasis>Establish a local copy of the Yocto Project files on your |
86 | system</emphasis>: You need to have the Yocto Project files available on your host system. | 87 | system</emphasis>: You need to have the Yocto Project files available on your host system. |
87 | Having the Yocto Project files on your system gives you access to the build | 88 | Having the Yocto Project files on your system gives you access to the build |
88 | process and tools you need. | 89 | process and to the tools you need. |
89 | For information on how to get these files, see the | 90 | For information on how to get these files, see the |
90 | "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> | 91 | "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> |
91 | <listitem><para><emphasis>Establish a local copy of the base BSP files</emphasis>: Having | 92 | <listitem><para><emphasis>Establish a local copy of the base BSP files</emphasis>: Having |
92 | the BSP files on your system gives you access to the build | 93 | the BSP files on your system gives you access to the build |
93 | process and tools you need for creating a BSP. | 94 | process and to the tools you need for creating a BSP. |
94 | For information on how to get these files, see the | 95 | For information on how to get these files, see the |
95 | "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> | 96 | "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> |
96 | <listitem><para><emphasis>Choose a Yocto Project-supported BSP as your base BSP</emphasis>: | 97 | <listitem><para><emphasis>Choose a Yocto Project-supported BSP as your base BSP</emphasis>: |
@@ -111,13 +112,15 @@ | |||
111 | Crown Bay that does not support the <trademark class='registered'>Intel</trademark> | 112 | Crown Bay that does not support the <trademark class='registered'>Intel</trademark> |
112 | Embedded Media Graphics Driver (EMGD). | 113 | Embedded Media Graphics Driver (EMGD). |
113 | The remainder of this example uses that base BSP.</para> | 114 | The remainder of this example uses that base BSP.</para> |
114 | <para>To see the supported BSPs, go to the Yocto Project | 115 | <para>To see the supported BSPs, go to the |
115 | <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click | 116 | <ulink url='&YOCTO_HOME_URL;/download'>Download</ulink> page on the Yocto Project |
116 | on “BSP Downloads.”</para></listitem> | 117 | website and click on “BSP Downloads.”</para></listitem> |
117 | <listitem><para><emphasis>Create your own BSP layer</emphasis>: Layers are ideal for | 118 | <listitem><para><emphasis>Create your own BSP layer</emphasis>: Layers are ideal for |
118 | isolating and storing work for a given piece of hardware. | 119 | isolating and storing work for a given piece of hardware. |
119 | A layer is really just a location or area in which you place the recipes for your BSP. | 120 | A layer is really just a location or area in which you place the recipes for your BSP. |
120 | In fact, a BSP is, in itself, a special type of layer. | 121 | In fact, a BSP is, in itself, a special type of layer. |
122 | </para> | ||
123 | <para> | ||
121 | Another example that illustrates a layer is an application. | 124 | Another example that illustrates a layer is an application. |
122 | Suppose you are creating an application that has library or other dependencies in | 125 | Suppose you are creating an application that has library or other dependencies in |
123 | order for it to compile and run. | 126 | order for it to compile and run. |
@@ -137,16 +140,17 @@ | |||
137 | N450, and Sugar Bay are isolated.</note> | 140 | N450, and Sugar Bay are isolated.</note> |
138 | <para>When you set up a layer for a new BSP, you should follow a standard layout. | 141 | <para>When you set up a layer for a new BSP, you should follow a standard layout. |
139 | This layout is described in the section | 142 | This layout is described in the section |
140 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>Example Filesystem Layout</ulink>" section of the Board Support Package (BSP) Development Guide. | 143 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>" |
144 | section of the Board Support Package (BSP) Development Guide. | ||
141 | In the standard layout, you will notice a suggested structure for recipes and | 145 | In the standard layout, you will notice a suggested structure for recipes and |
142 | configuration information. | 146 | configuration information. |
143 | You can see the standard layout for the Crown Bay BSP in this example by examining the | 147 | You can see the standard layout for the Crown Bay BSP in this example by examining the |
144 | directory structure of the <filename>meta-crownbay</filename> layer inside the | 148 | directory structure of the <filename>meta-crownbay</filename> layer inside the |
145 | local Yocto Project files.</para></listitem> | 149 | local Yocto Project files.</para></listitem> |
146 | <listitem><para><emphasis>Make configuration changes to your new BSP | 150 | <listitem><para><emphasis>Make configuration changes to your new BSP |
147 | layer</emphasis>: The standard BSP layer structure organizes the files you need to edit in | 151 | layer</emphasis>: The standard BSP layer structure organizes the files you need |
148 | <filename>conf</filename> and several <filename>recipes-*</filename> directories within the | 152 | to edit in <filename>conf</filename> and several <filename>recipes-*</filename> |
149 | BSP layer. | 153 | directories within the BSP layer. |
150 | Configuration changes identify where your new layer is on the local system | 154 | Configuration changes identify where your new layer is on the local system |
151 | and identify which kernel you are going to use. | 155 | and identify which kernel you are going to use. |
152 | </para></listitem> | 156 | </para></listitem> |
@@ -160,7 +164,8 @@ | |||
160 | You need to get the build environment ready by sourcing an environment setup script | 164 | You need to get the build environment ready by sourcing an environment setup script |
161 | and you need to be sure two key configuration files are configured appropriately.</para> | 165 | and you need to be sure two key configuration files are configured appropriately.</para> |
162 | <para>The entire process for building an image is overviewed in the section | 166 | <para>The entire process for building an image is overviewed in the section |
163 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html#building-image'>Building an Image</ulink>" section of the Yocto Project Quick Start. | 167 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section |
168 | of the Yocto Project Quick Start. | ||
164 | You might want to reference this information.</para></listitem> | 169 | You might want to reference this information.</para></listitem> |
165 | <listitem><para><emphasis>Build the image</emphasis>: The Yocto Project uses the BitBake | 170 | <listitem><para><emphasis>Build the image</emphasis>: The Yocto Project uses the BitBake |
166 | tool to build images based on the type of image you want to create. | 171 | tool to build images based on the type of image you want to create. |
@@ -168,8 +173,8 @@ | |||
168 | <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para> | 173 | <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para> |
169 | <para>The build process supports several types of images to satisfy different needs. | 174 | <para>The build process supports several types of images to satisfy different needs. |
170 | See the | 175 | See the |
171 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/poky-ref-manual/poky-ref-manual.html#ref-images'>Reference: Images</ulink>" | 176 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Reference: Images</ulink>" appendix |
172 | appendix in The Yocto Project Reference Manual for information on | 177 | in The Yocto Project Reference Manual for information on |
173 | supported images.</para></listitem> | 178 | supported images.</para></listitem> |
174 | </orderedlist> | 179 | </orderedlist> |
175 | </para> | 180 | </para> |
@@ -178,10 +183,10 @@ | |||
178 | You can view a video presentation on "Building Custom Embedded Images with Yocto" | 183 | You can view a video presentation on "Building Custom Embedded Images with Yocto" |
179 | at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>. | 184 | at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>. |
180 | You can also find supplemental information in | 185 | You can also find supplemental information in |
181 | <ulink url='http://yoctoproject.org/docs/1.1.1/bsp-guide/bsp-guide.html'> | 186 | <ulink url='&YOCTO_DOCS_BSP_URL;'> |
182 | The Board Support Package (BSP) Development Guide</ulink>. | 187 | The Board Support Package (BSP) Development Guide</ulink>. |
183 | Finally, there is wiki page write up of the example also located | 188 | Finally, there is wiki page write up of the example also located |
184 | <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'> | 189 | <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'> |
185 | here</ulink> that you might find helpful. | 190 | here</ulink> that you might find helpful. |
186 | </para> | 191 | </para> |
187 | </section> | 192 | </section> |
@@ -191,7 +196,7 @@ | |||
191 | 196 | ||
192 | <para> | 197 | <para> |
193 | Kernel modification involves changing the Linux Yocto kernel, which could involve changing | 198 | Kernel modification involves changing the Linux Yocto kernel, which could involve changing |
194 | configuration variables as well as adding new kernel recipes. | 199 | configuration options as well as adding new kernel recipes. |
195 | Configuration changes can be added in the form of configuration fragments, while recipe | 200 | Configuration changes can be added in the form of configuration fragments, while recipe |
196 | modification comes through the kernel's <filename>recipes-kernel</filename> area | 201 | modification comes through the kernel's <filename>recipes-kernel</filename> area |
197 | in a kernel layer you create. | 202 | in a kernel layer you create. |
@@ -201,7 +206,7 @@ | |||
201 | The remainder of this section presents a high-level overview of the Linux Yocto | 206 | The remainder of this section presents a high-level overview of the Linux Yocto |
202 | kernel architecture and the steps to modify the Linux Yocto kernel. | 207 | kernel architecture and the steps to modify the Linux Yocto kernel. |
203 | For a complete discussion of the kernel, see | 208 | For a complete discussion of the kernel, see |
204 | <ulink url='http://www.yoctoproject.org/docs/1.1.1/kernel-manual/kernel-manual.html'> | 209 | <ulink url='&YOCTO_DOCS_KERNEL_URL;'> |
205 | The Yocto Project Kernel Architecture and Use Manual</ulink>. | 210 | The Yocto Project Kernel Architecture and Use Manual</ulink>. |
206 | You can reference the appendix | 211 | You can reference the appendix |
207 | "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" | 212 | "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" |
@@ -212,39 +217,41 @@ | |||
212 | <title>Kernel Overview</title> | 217 | <title>Kernel Overview</title> |
213 | 218 | ||
214 | <para> | 219 | <para> |
215 | When one thinks of the source files for a kernel they usually think of a fixed structure | 220 | Traditionally, when one thinks of a patched kernel, they think of a base kernel |
216 | of files that contain kernel patches. | 221 | source tree and a fixed structure that contains kernel patches. |
217 | The Yocto Project, however, employs mechanisims, that in a sense, result in a kernel source | 222 | The Yocto Project, however, employs mechanisms, that in a sense, result in a kernel source |
218 | generator. | 223 | generator. |
219 | By the end of this section, this analogy will become clearer. | 224 | By the end of this section, this analogy will become clearer. |
220 | </para> | 225 | </para> |
221 | 226 | ||
222 | <para> | 227 | <para> |
223 | You can find a web interface to the Linux Yocto kernel source repositories at | 228 | You can find a web interface to the Linux Yocto kernel source repositories at |
224 | <ulink url='http://git.yoctoproject.org/'></ulink>. | 229 | <ulink url='&YOCTO_GIT_URL;'></ulink>. |
225 | If you look at the interface, you will see to the left a grouping of | 230 | If you look at the interface, you will see to the left a grouping of |
226 | Git repositories titled "Yocto Linux Kernel." | 231 | Git repositories titled "Yocto Linux Kernel." |
227 | Within this group, you will find the four different kernels supported by | 232 | Within this group, you will find several kernels supported by |
228 | the Yocto Project: | 233 | the Yocto Project: |
229 | <itemizedlist> | 234 | <itemizedlist> |
230 | <listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The | 235 | <listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The |
231 | stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem> | 236 | stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem> |
232 | <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The | 237 | <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The |
233 | stable Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem> | 238 | stable Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem> |
234 | <listitem><para><emphasis><filename>linux-yocto-3.0</filename></emphasis> - The | 239 | <listitem><para><emphasis><filename>linux-yocto-3.0</filename></emphasis> - The stable |
235 | stable Linux Yocto kernel to use with the Yocto Project current (master) development. | 240 | Linux Yocto kernel that is based on the Linux 3.0 release.</para></listitem> |
236 | This kernel is based on the Linux 3.0 release.</para></listitem> | ||
237 | <listitem><para><emphasis><filename>linux-yocto-3.0-1.1.x</filename></emphasis> - The | 241 | <listitem><para><emphasis><filename>linux-yocto-3.0-1.1.x</filename></emphasis> - The |
238 | stable Linux Yocto kernel to use with the Yocto Project Release 1.1.x. | 242 | stable Linux Yocto kernel to use with the Yocto Project Release 1.1.x. This kernel |
239 | This kernel is based on the Linux 3.0 release.</para></listitem> | 243 | is based on the Linux 3.0 release</para></listitem> |
244 | <listitem><para><emphasis><filename>linux-yocto-3.2</filename></emphasis> - The | ||
245 | stable Linux Yocto kernel to use with the Yocto Project Release 1.2. This kernel | ||
246 | is based on the Linux 3.2 release</para></listitem> | ||
240 | <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development | 247 | <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development |
241 | kernel based on the latest upstream release candidate available.</para></listitem> | 248 | kernel based on the latest upstream release candidate available.</para></listitem> |
242 | </itemizedlist> | 249 | </itemizedlist> |
243 | </para> | 250 | </para> |
244 | 251 | ||
245 | <para> | 252 | <para> |
246 | The kernels are maintained using the Git application that, in a sense, structures | 253 | The kernels are maintained using the Git revision control system |
247 | them in a "tree" complete with branches and leaves. | 254 | that structures them using the familiar "tree", "branch", and "leaf" scheme. |
248 | Branches represent diversions from general code to more specific code, while leaves | 255 | Branches represent diversions from general code to more specific code, while leaves |
249 | represent the end-points for a complete and unique kernel whose source files | 256 | represent the end-points for a complete and unique kernel whose source files |
250 | when gathered from the root of the tree to the leaf accumulate to create the files | 257 | when gathered from the root of the tree to the leaf accumulate to create the files |
@@ -257,7 +264,7 @@ | |||
257 | 264 | ||
258 | <para> | 265 | <para> |
259 | Within the figure, the "Kernel.org Branch Point" represents the point in the tree | 266 | Within the figure, the "Kernel.org Branch Point" represents the point in the tree |
260 | where a supported base kernel diverges from the Linux kernel. | 267 | where a supported base kernel is modified from the Linux kernel. |
261 | For example, this could be the branch point for the <filename>linux-yocto-3.0</filename> | 268 | For example, this could be the branch point for the <filename>linux-yocto-3.0</filename> |
262 | kernel. | 269 | kernel. |
263 | Thus, everything further to the right in the structure is based on the | 270 | Thus, everything further to the right in the structure is based on the |
@@ -271,14 +278,14 @@ | |||
271 | 278 | ||
272 | <para> | 279 | <para> |
273 | The overall result is a Git-maintained repository from which all the supported | 280 | The overall result is a Git-maintained repository from which all the supported |
274 | Yocto Project kernels can be derived for all the supported Yocto Project devices. | 281 | Yocto Project kernel types can be derived for all the supported Yocto Project devices. |
275 | A big advantage to this scheme is the sharing of common features by keeping them in | 282 | A big advantage to this scheme is the sharing of common features by keeping them in |
276 | "larger" branches within the tree. | 283 | "larger" branches within the tree. |
277 | This practice eliminates redundant storage of similar features shared among kernels. | 284 | This practice eliminates redundant storage of similar features shared among kernels. |
278 | </para> | 285 | </para> |
279 | 286 | ||
280 | <note> | 287 | <note> |
281 | Keep in mind the figure does not take into account all four supported Linux Yocto | 288 | Keep in mind the figure does not take into account all the supported Linux Yocto |
282 | kernel types, but rather shows a single generic kernel just for conceptual purposes. | 289 | kernel types, but rather shows a single generic kernel just for conceptual purposes. |
283 | Also keep in mind that this structure represents the Yocto Project source repositories | 290 | Also keep in mind that this structure represents the Yocto Project source repositories |
284 | that are either pulled from during the build or established on the host development system | 291 | that are either pulled from during the build or established on the host development system |
@@ -353,11 +360,11 @@ | |||
353 | <para> | 360 | <para> |
354 | Again, for a complete discussion of the Yocto Project kernel's architcture and its | 361 | Again, for a complete discussion of the Yocto Project kernel's architcture and its |
355 | branching strategy, | 362 | branching strategy, |
356 | see the <ulink url='http://www.yoctoproject.org/docs/1.1.1/kernel-manual/kernel-manual.html'> | 363 | see <ulink url='&YOCTO_DOCS_KERNEL_URL;'> |
357 | The Yocto Project Kernel Architecture and Use Manual</ulink>. | 364 | The Yocto Project Kernel Architecture and Use Manual</ulink>. |
358 | Also, you can reference | 365 | You can also reference the |
359 | <xref linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source Code</xref> | 366 | "<link linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source Code</link>" |
360 | for a detailed example that modifies the kernel. | 367 | section for a detailed example that modifies the kernel. |
361 | </para> | 368 | </para> |
362 | </section> | 369 | </section> |
363 | 370 | ||
@@ -377,8 +384,8 @@ | |||
377 | <orderedlist> | 384 | <orderedlist> |
378 | <listitem><para><emphasis>Set up your host development system to support | 385 | <listitem><para><emphasis>Set up your host development system to support |
379 | development using the Yocto Project</emphasis>: See | 386 | development using the Yocto Project</emphasis>: See |
380 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>The Linux Distributions</ulink>" and | 387 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" and |
381 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html#packages'>The Packages</ulink>" sections both | 388 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both |
382 | in the Yocto Project Quick Start for requirements.</para></listitem> | 389 | in the Yocto Project Quick Start for requirements.</para></listitem> |
383 | <listitem><para><emphasis>Establish a local copy of the Yocto Project files on your | 390 | <listitem><para><emphasis>Establish a local copy of the Yocto Project files on your |
384 | system</emphasis>: Having the Yocto Project files on your system gives you access to | 391 | system</emphasis>: Having the Yocto Project files on your system gives you access to |
@@ -394,7 +401,10 @@ | |||
394 | Project files Git repository. | 401 | Project files Git repository. |
395 | For information on how to get these files, see the bulleted item | 402 | For information on how to get these files, see the bulleted item |
396 | "<link linkend='poky-extras-repo'>The <filename>poky-extras</filename> Git Repository</link>" | 403 | "<link linkend='poky-extras-repo'>The <filename>poky-extras</filename> Git Repository</link>" |
397 | earlier in this manual.</para></listitem> | 404 | earlier in this manual. |
405 | <note>While it is certainly possible to modify the kernel without involving | ||
406 | a local Git repository, the suggested workflow for kernel modification | ||
407 | using the Yocto Project does use a Git repository.</note></para></listitem> | ||
398 | <listitem><para><emphasis>Establish a local copy of the Linux Yocto kernel files on your | 408 | <listitem><para><emphasis>Establish a local copy of the Linux Yocto kernel files on your |
399 | system</emphasis>: In order to make modifications to the kernel you need two things: | 409 | system</emphasis>: In order to make modifications to the kernel you need two things: |
400 | a bare clone of the Linux Yocto kernel you are modifying and | 410 | a bare clone of the Linux Yocto kernel you are modifying and |
@@ -416,7 +426,7 @@ | |||
416 | Once the changes are made, you need to use Git commands to commit the changes | 426 | Once the changes are made, you need to use Git commands to commit the changes |
417 | and then push them to the bare clone.</para></listitem> | 427 | and then push them to the bare clone.</para></listitem> |
418 | <listitem><para><emphasis>Make kernel configuration changes | 428 | <listitem><para><emphasis>Make kernel configuration changes |
419 | to your local kernel layer if applicable</emphasis>: | 429 | if applicable</emphasis>: |
420 | If your situation calls for changing the kernel's configuration, you can | 430 | If your situation calls for changing the kernel's configuration, you can |
421 | use <filename>menuconfig</filename> | 431 | use <filename>menuconfig</filename> |
422 | to enable and disable kernel configurations. | 432 | to enable and disable kernel configurations. |
@@ -424,11 +434,18 @@ | |||
424 | configuration changes you are making to the kernel. | 434 | configuration changes you are making to the kernel. |
425 | When saved, changes using <filename>menuconfig</filename> update the kernel's | 435 | When saved, changes using <filename>menuconfig</filename> update the kernel's |
426 | <filename>.config</filename>. | 436 | <filename>.config</filename>. |
427 | As an alternative method to changing the kernel's configuration, you can simply | 437 | Try to resist the temptation of directly editing the <filename>.config</filename> |
428 | edit the <filename>.config</filename> found in the Yocto Project build | 438 | file found in the Yocto Project build directory at |
429 | directory at <filename>tmp/sysroots/<machine-name>/kernel</filename> | 439 | <filename>tmp/sysroots/<machine-name>/kernel</filename>. |
430 | directly.</para></listitem> | 440 | Doing so, can produce unexpected results when the Yocto Project build system |
431 | <listitem><para><emphasis>Add new kernel recipes if applicable</emphasis>: The standard | 441 | regenerates the configuration file.</para> |
442 | <para>Once you are satisfied with the configuration changes made using | ||
443 | <filename>menuconfig</filename>, you can directly examine the | ||
444 | <filename>.config</filename> file against a saved original and gather those | ||
445 | changes into a config fragment to be referenced from within the kernel's | ||
446 | <filename>.bbappend</filename> file.</para></listitem> | ||
447 | <listitem><para><emphasis>Add or extend kernel recipes if applicable</emphasis>: | ||
448 | The standard | ||
432 | layer structure organizes recipe files inside the | 449 | layer structure organizes recipe files inside the |
433 | <filename>meta-kernel-dev</filename> layer that is within the | 450 | <filename>meta-kernel-dev</filename> layer that is within the |
434 | <filename>poky-extras</filename> Git repository. | 451 | <filename>poky-extras</filename> Git repository. |
@@ -440,14 +457,15 @@ | |||
440 | <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the | 457 | <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the |
441 | changes to your kernel (configurations, source code changes, recipe additions, | 458 | changes to your kernel (configurations, source code changes, recipe additions, |
442 | or recipe changes), there remains a few things | 459 | or recipe changes), there remains a few things |
443 | you need to do in order for the Yocto Project build system to create your image. | 460 | you need to do in order for the Yocto Project build system (BitBake) to create your image. |
444 | If you have not done so, you need to get the build environment ready by sourcing | 461 | If you have not done so, you need to get the build environment ready by sourcing |
445 | the environment setup script described earlier. | 462 | the environment setup script described earlier. |
446 | You also need to be sure two key configuration files | 463 | You also need to be sure two key configuration files |
447 | (<filename>local.conf</filename> and <filename>bblayers.conf</filename>) | 464 | (<filename>local.conf</filename> and <filename>bblayers.conf</filename>) |
448 | are configured appropriately.</para> | 465 | are configured appropriately.</para> |
449 | <para>The entire process for building an image is overviewed in the | 466 | <para>The entire process for building an image is overviewed in the |
450 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html#building-image'>Building an Image</ulink>" section of the Yocto Project Quick Start. | 467 | "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" |
468 | section of the Yocto Project Quick Start. | ||
451 | You might want to reference this information. | 469 | You might want to reference this information. |
452 | Also, you should look at the detailed examples found in the appendices at | 470 | Also, you should look at the detailed examples found in the appendices at |
453 | at the end of this manual.</para></listitem> | 471 | at the end of this manual.</para></listitem> |
@@ -458,8 +476,8 @@ | |||
458 | <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para> | 476 | <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para> |
459 | <para>The build process supports several types of images to satisfy different needs. | 477 | <para>The build process supports several types of images to satisfy different needs. |
460 | See the appendix | 478 | See the appendix |
461 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/poky-ref-manual/poky-ref-manual.html#ref-images'>Reference: Images</ulink>" | 479 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Reference: Images</ulink>" in |
462 | in The Yocto Project Reference Manual for information on supported images.</para></listitem> | 480 | The Yocto Project Reference Manual for information on supported images.</para></listitem> |
463 | <listitem><para><emphasis>Make your configuration changes available | 481 | <listitem><para><emphasis>Make your configuration changes available |
464 | in the kernel layer</emphasis>: Up to this point, all the configuration changes to the | 482 | in the kernel layer</emphasis>: Up to this point, all the configuration changes to the |
465 | kernel have been done and tested iteratively. | 483 | kernel have been done and tested iteratively. |
@@ -467,10 +485,10 @@ | |||
467 | which allows you to distribute the layer.</para></listitem> | 485 | which allows you to distribute the layer.</para></listitem> |
468 | <listitem><para><emphasis>If applicable, share your in-tree changes</emphasis>: | 486 | <listitem><para><emphasis>If applicable, share your in-tree changes</emphasis>: |
469 | If the changes you made | 487 | If the changes you made |
470 | are suited for all Linux Yocto users, you might want to push the changes to a | 488 | are suited for all Linux Yocto users, you might want to send them on for inclusion |
471 | contribution area for the Linux Yocto Git repository. | 489 | into the Linux Yocto Git repository. |
472 | Once the changes are pushed, you can request that they | 490 | If the changes are accepted, the Yocto Project Maintainer pulls them into |
473 | be pulled into the master branch of the kernel tree. | 491 | the master branch of the kernel tree. |
474 | Doing so makes them available to everyone using the kernel.</para></listitem> | 492 | Doing so makes them available to everyone using the kernel.</para></listitem> |
475 | </orderedlist> | 493 | </orderedlist> |
476 | </para> | 494 | </para> |
@@ -509,7 +527,7 @@ | |||
509 | provides an overview of the general development process. | 527 | provides an overview of the general development process. |
510 | If you want to see a detailed example of the process as it is used from within the Eclipse | 528 | If you want to see a detailed example of the process as it is used from within the Eclipse |
511 | IDE, see | 529 | IDE, see |
512 | <ulink url='http://www.yoctoproject.org/docs/1.1.1/adt-manual/adt-manual.html'> | 530 | <ulink url='&YOCTO_DOCS_ADT_URL;'> |
513 | The Application Development Toolkit (ADT) User's Manual</ulink>. | 531 | The Application Development Toolkit (ADT) User's Manual</ulink>. |
514 | </para> | 532 | </para> |
515 | 533 | ||
@@ -526,8 +544,8 @@ | |||
526 | <orderedlist> | 544 | <orderedlist> |
527 | <listitem><para><emphasis>Prepare the Host System for the Yocto Project</emphasis>: | 545 | <listitem><para><emphasis>Prepare the Host System for the Yocto Project</emphasis>: |
528 | See | 546 | See |
529 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>The Linux Distributions</ulink>" and | 547 | "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" and |
530 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html#packages'>The Packages</ulink>" sections both | 548 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both |
531 | in the Yocto Project Quick Start for requirements.</para></listitem> | 549 | in the Yocto Project Quick Start for requirements.</para></listitem> |
532 | 550 | ||
533 | <!-- | 551 | <!-- |
@@ -552,15 +570,15 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the | |||
552 | You must have a target kernel image that has been built using the Yocto Project.</para> | 570 | You must have a target kernel image that has been built using the Yocto Project.</para> |
553 | <para>Depending on whether the Yocto Project has a pre-built image that matches your target | 571 | <para>Depending on whether the Yocto Project has a pre-built image that matches your target |
554 | architecture and where you are going to run the image while you develop your application | 572 | architecture and where you are going to run the image while you develop your application |
555 | (QEMU or real hardware), the area you get the image from differs. | 573 | (QEMU or real hardware), the area from which you get the image differs. |
556 | <itemizedlist> | 574 | <itemizedlist> |
557 | <listitem><para>Download the image from | 575 | <listitem><para>Download the image from |
558 | <ulink url='http://downloads.yoctoproject.org/releases/yocto/yocto-1.1.1/machines/'> | 576 | <ulink url='&YOCTO_MACHINES_DL_URL;'> |
559 | <filename>machines</filename></ulink> if your target architecture is supported | 577 | <filename>machines</filename></ulink> if your target architecture is supported |
560 | and you are going to develop and test your application on actual hardware. | 578 | and you are going to develop and test your application on actual hardware. |
561 | </para></listitem> | 579 | </para></listitem> |
562 | <listitem><para>Download the image from the | 580 | <listitem><para>Download the image from the |
563 | <ulink url='http://downloads.yoctoproject.org/releases/yocto/yocto-1.1.1/machines/qemu/'> | 581 | <ulink url='&YOCTO_QEMU_DL_URL;'> |
564 | <filename>machines/qemu</filename></ulink> if your target architecture is supported | 582 | <filename>machines/qemu</filename></ulink> if your target architecture is supported |
565 | and you are going to develop and test your application using the QEMU | 583 | and you are going to develop and test your application using the QEMU |
566 | emulator.</para></listitem> | 584 | emulator.</para></listitem> |
@@ -575,10 +593,8 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the | |||
575 | </itemizedlist></para> | 593 | </itemizedlist></para> |
576 | <para>For information on pre-built kernel image naming schemes for images | 594 | <para>For information on pre-built kernel image naming schemes for images |
577 | that can run on the QEMU emulator, see the | 595 | that can run on the QEMU emulator, see the |
578 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" | 596 | "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" |
579 | section in | 597 | section in the Yocto Project Quick Start.</para></listitem> |
580 | <ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html'> | ||
581 | The Yocto Project Quick Start</ulink>.</para></listitem> | ||
582 | <listitem><para><emphasis>Install the ADT</emphasis>: | 598 | <listitem><para><emphasis>Install the ADT</emphasis>: |
583 | The ADT provides a target-specific cross-development toolchain, the root filesystem, | 599 | The ADT provides a target-specific cross-development toolchain, the root filesystem, |
584 | the QEMU emulator, and other tools that can help you develop your application. | 600 | the QEMU emulator, and other tools that can help you develop your application. |
@@ -586,9 +602,9 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the | |||
586 | easy method. | 602 | easy method. |
587 | You can get these pieces by running an ADT installer script, which is configurable. | 603 | You can get these pieces by running an ADT installer script, which is configurable. |
588 | For information on how to install the ADT, see the | 604 | For information on how to install the ADT, see the |
589 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/adt-manual/adt-manual.html#using-the-adt-installer'>Using the ADT Installer</ulink>" section in | 605 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Using the ADT Installer</ulink>" |
590 | <ulink url='http://www.yoctoproject.org/docs/1.1.1/adt-manual/adt-manual.html'>The Yocto Project | 606 | section |
591 | Application Development (ADT) User's Manual</ulink>.</para></listitem> | 607 | in the Yocto Project Application Development (ADT) User's Manual.</para></listitem> |
592 | <listitem><para><emphasis>If Applicable, Secure the Target Root Filesystem</emphasis>: | 608 | <listitem><para><emphasis>If Applicable, Secure the Target Root Filesystem</emphasis>: |
593 | If you choose not to install the ADT using the ADT Installer, | 609 | If you choose not to install the ADT using the ADT Installer, |
594 | you need to find and download the | 610 | you need to find and download the |
@@ -632,14 +648,14 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the | |||
632 | <orderedlist> | 648 | <orderedlist> |
633 | <listitem><para><emphasis>Install the cross-development toolchain for your target hardware:</emphasis> | 649 | <listitem><para><emphasis>Install the cross-development toolchain for your target hardware:</emphasis> |
634 | For information on how to install the toolchain, see the | 650 | For information on how to install the toolchain, see the |
635 | "<ulink url='http://www.yoctoproject/docs/1.1.1/adt-manual/adt-manual.html#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" section in | 651 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" |
636 | <ulink url='http://www.yoctoproject/docs/1.1.1/adt-manual/adt-manual.html'>The Yocto Project | 652 | section |
637 | Application Development (ADT) User's Manual</ulink>.</para></listitem> | 653 | in the Yocto Project Application Development (ADT) User's Manual.</para></listitem> |
638 | <listitem><para><emphasis>Download the Target Image:</emphasis> The Yocto Project supports | 654 | <listitem><para><emphasis>Download the Target Image:</emphasis> The Yocto Project supports |
639 | several target architectures and has many pre-built kernel images and root filesystem | 655 | several target architectures and has many pre-built kernel images and root filesystem |
640 | images.</para> | 656 | images.</para> |
641 | <para>If you are going to develop your application on hardware, go to the | 657 | <para>If you are going to develop your application on hardware, go to the |
642 | <ulink url='http://downloads.yoctoproject.org/releases/yocto/yocto-1.1.1/machines/'> | 658 | <ulink url='&YOCTO_MACHINES_DL_URL;'> |
643 | <filename>machines</filename></ulink> download area and choose a target machine area | 659 | <filename>machines</filename></ulink> download area and choose a target machine area |
644 | from which to download the kernel image and root filesystem. | 660 | from which to download the kernel image and root filesystem. |
645 | This download area could have several files in it that support development using | 661 | This download area could have several files in it that support development using |
@@ -649,7 +665,7 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the | |||
649 | Be sure to get the files you need for your particular development process.</para> | 665 | Be sure to get the files you need for your particular development process.</para> |
650 | <para>If you are going to develop your application and then run and test it using the QEMU | 666 | <para>If you are going to develop your application and then run and test it using the QEMU |
651 | emulator, go to the | 667 | emulator, go to the |
652 | <ulink url='http://downloads.yoctoproject.org/releases/yocto/yocto-1.1.1/machines/qemu/'> | 668 | <ulink url='&YOCTO_QEMU_DL_URL;'> |
653 | <filename>machines/qemu</filename></ulink> download area. | 669 | <filename>machines/qemu</filename></ulink> download area. |
654 | From this area, go down into the directory for your target architecture | 670 | From this area, go down into the directory for your target architecture |
655 | (e.g. <filename>qemux86_64</filename> for an | 671 | (e.g. <filename>qemux86_64</filename> for an |
@@ -657,7 +673,7 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the | |||
657 | Download kernel, root filesystem, and any other files you need for your process. | 673 | Download kernel, root filesystem, and any other files you need for your process. |
658 | <note>In order to use the root filesystem in QEMU, you need to extract it. | 674 | <note>In order to use the root filesystem in QEMU, you need to extract it. |
659 | See the | 675 | See the |
660 | "<ulink url='http://www.yoctoproject.org/docs/1.1.1/adt-manual/adt-manual.html#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>" section for information on how to extract the | 676 | "<ulink url='&YOCTO_DOCS_ADT_URL;#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>" section for information on how to extract the |
661 | root filesystem.</note></para></listitem> | 677 | root filesystem.</note></para></listitem> |
662 | <listitem><para><emphasis>Develop and Test your Application:</emphasis> At this point, | 678 | <listitem><para><emphasis>Develop and Test your Application:</emphasis> At this point, |
663 | you have the tools to develop your application. | 679 | you have the tools to develop your application. |