summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-08-18 15:12:33 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-09-02 00:52:48 +0100
commita64831cad79e46c50509aad89f6fefad71123b60 (patch)
tree4b8e92879e4a6444efd696f2caf9dd7bd92297d9
parent25aacfe1dadad0e762dccd1c1d061ea77c25a3a3 (diff)
downloadpoky-a64831cad79e46c50509aad89f6fefad71123b60.tar.gz
kernel-dev, dev-manual: Moved Kernel prep steps
The dev-manual had a place-holder section for getting the build host ready for using YP and then doing kernel development. This stuff is better suited for the actual kernel development manual. I moved the section. Moving created several broken links in the manual set that had to be fixed. In the dev-manual, I updated the introductory list to include the newly moved kernel stuff. (From yocto-docs rev: 2e21260bb5f84e9e30eb353ec841d5962e8a7642) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/dev-manual/dev-manual-start.xml127
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml76
-rw-r--r--documentation/kernel-dev/kernel-dev-concepts-appx.xml4
-rw-r--r--documentation/kernel-dev/kernel-dev-examples.xml8
-rw-r--r--documentation/kernel-dev/kernel-dev-intro.xml124
-rw-r--r--documentation/kernel-dev/kernel-dev-maint-appx.xml8
6 files changed, 206 insertions, 141 deletions
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 85dff0b673..94595756b8 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -45,7 +45,9 @@
45 </para></listitem> 45 </para></listitem>
46 <listitem><para> 46 <listitem><para>
47 <emphasis>Kernel Development:</emphasis> 47 <emphasis>Kernel Development:</emphasis>
48 Need some kernel links. 48 See the
49 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</ulink>"
50 section in the Yocto Project Linux Kernel Development Manual.
49 </para></listitem> 51 </para></listitem>
50 <listitem><para> 52 <listitem><para>
51 <emphasis>Eclipse Development:</emphasis> 53 <emphasis>Eclipse Development:</emphasis>
@@ -231,129 +233,6 @@
231 section in the Toaster User Manual. 233 section in the Toaster User Manual.
232 </para> 234 </para>
233 </section> 235 </section>
234
235 <section id='local-kernel-files'>
236 <title>Setting Up to Work on a Kernel</title>
237
238 <para>
239 Kernel development is best accomplished using
240 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
241 and not through traditional kernel workflow methods.
242 This section provides procedures to set up for both.
243 </para>
244
245 <section id='getting-ready-to-develop-using-devtool'>
246 <title>Getting Ready to Develop using <filename>devtool</filename></title>
247
248 <para role='writernotes'>
249 Need the updated wiki stuff here
250 </para>
251 </section>
252
253 <section id='getting-ready-for-traditional-kernel-development'>
254 <title>Getting Ready for Traditional Kernel Development</title>
255
256 <para>
257 For traditional kernel development using the Yocto
258 Project, you need to establish local copies of the
259 kernel source.
260 You can find Git repositories of supported Yocto Project
261 kernels organized under "Yocto Linux Kernel" in the Yocto
262 Project Source Repositories at
263 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
264 </para>
265
266 <para>
267 This setup can involve creating a bare clone of the
268 Yocto Project kernel and then copying that cloned
269 repository.
270 You can create the bare clone and the copy of the bare
271 clone anywhere you like.
272 For simplicity, it is recommended that you create these
273 structures outside of the
274 <ulink url='&YOCTO_DOCS_REF_URL;source-directory'>Source Directory</ulink>,
275 which is usually named <filename>poky</filename>.
276 </para>
277
278 <para>
279 The following steps show how to create a bare clone of the
280 <filename>linux-yocto-4.4</filename> kernel and then
281 create a copy of that clone:
282 <note>
283 When you have a local Yocto Project kernel Git
284 repository, you can reference that repository rather than
285 the upstream Git repository as part of the
286 <filename>clone</filename> command.
287 Doing so can speed up the process.
288 </note>
289 <orderedlist>
290 <listitem><para>
291 <emphasis>Create the Bare Clone:</emphasis>
292 In the following example, the bare clone is named
293 <filename>linux-yocto-4.4.git</filename>:
294 <literallayout class='monospaced'>
295 $ git clone &dash;&dash;bare git://git.yoctoproject.org/linux-yocto-4.4 linux-yocto-4.4.git
296 Cloning into bare repository 'linux-yocto-4.4.git'...
297 remote: Counting objects: 4543903, done.
298 remote: Compressing objects: 100% (695618/695618), done.
299 remote: Total 4543903 (delta 3818435), reused 4541724 (delta 3816256)
300 Receiving objects: 100% (4543903/4543903), 801.08 MiB | 6.55 MiB/s, done.
301 Resolving deltas: 100% (3818435/3818435), done.
302 Checking connectivity... done.
303 </literallayout>
304 </para></listitem>
305 <listitem><para>
306 <emphasis>Create the Copy of the Bare Clone:</emphasis>
307 In the following command, the copy of the bare clone
308 is named <filename>my-linux-yocto-4.4-work</filename>:
309 <literallayout class='monospaced'>
310 $ git clone linux-yocto-4.4.git my-linux-yocto-4.4-work
311 Cloning into 'my-linux-yocto-4.4-work'...
312 done.
313 Checking out files: 100% (52221/52221), done.
314 </literallayout>
315 </para></listitem>
316 <listitem><para>
317 <emphasis>Cloning the <filename>meta-yocto-kernel-extras</filename> Repository:</emphasis>
318 The <filename>meta-yocto-kernel-extras</filename> Git
319 repository contains Metadata needed only if you are
320 modifying and building the kernel image.
321 In particular, it contains the kernel BitBake append
322 (<filename>.bbappend</filename>) files that you edit to
323 point to your locally modified kernel source files and to
324 build the kernel image.
325 Pointing to these local files is much more efficient than
326 requiring a download of the kernel's source files from
327 upstream each time you make changes to the kernel.</para>
328
329 <para>You can find the
330 <filename>meta-yocto-kernel-extras</filename> Git
331 Repository in the "Yocto Metadata Layers" area of the
332 Yocto Project Source Repositories at
333 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
334 It is good practice to create this Git repository
335 inside the Source Directory.</para>
336
337 <para>Following is an example that creates the
338 <filename>meta-yocto-kernel-extras</filename> Git
339 repository inside the Source Directory, which is named
340 <filename>poky</filename>, in this case:
341 <literallayout class='monospaced'>
342 $ cd ~/poky
343 $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
344 Cloning into 'meta-yocto-kernel-extras'...
345 remote: Counting objects: 727, done.
346 remote: Compressing objects: 100% (452/452), done.
347 remote: Total 727 (delta 260), reused 719 (delta 252)
348 Receiving objects: 100% (727/727), 536.36 KiB | 0 bytes/s, done.
349 Resolving deltas: 100% (260/260), done.
350 Checking connectivity... done.
351 </literallayout>
352 </para></listitem>
353 </orderedlist>
354 </para>
355 </section>
356 </section>
357</section> 236</section>
358 237
359<section id='working-with-yocto-project-source-files'> 238<section id='working-with-yocto-project-source-files'>
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index c55f68bc24..8c8fe05711 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -474,15 +474,15 @@
474 </para> 474 </para>
475 475
476 <para> 476 <para>
477 The example assumes a clean build exists for the <filename>qemux86</filename> 477 The example builds an extensible SDK, which is then used to
478 machine in a 478 build, using <filename>devtool</filename>, a clean image for the
479 default <filename>qemux86</filename> machine in a
479 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> 480 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
480 named <filename>poky</filename>. 481 named <filename>poky</filename>.
481 Furthermore, the 482 In the example, the
482 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> 483 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
483 is <filename>build</filename> and is located in 484 is <filename>build</filename> and is located in the default
484 <filename>poky</filename> and the kernel is based on the 485 <filename>poky_sdk</filename> directory.
485 Linux 3.4 kernel.
486 </para> 486 </para>
487 487
488 <para> 488 <para>
@@ -491,12 +491,74 @@
491 section. 491 section.
492 </para> 492 </para>
493 493
494 <section id='patch-kernel-set-up-the-build-host'>
495 <title>Set Up the Build Host</title>
496
497 <para>
498 Prior to creating any actual patches for your kernel, you
499 need to prepare the build host.
500 This example builds an extensible SDK.
501 Follow these steps:
502 <itemizedlist>
503 <listitem><para>
504 <emphasis>Set Up the Build Environment:</emphasis>
505 Be sure you are set up to use BitBake in a shell.
506 See the
507 "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
508 section in the Yocto Project Development Manual for information
509 on how to get a build host ready that is either a native
510 Linux machine or a machine that uses CROPS.
511 </para></listitem>
512 <listitem><para>
513 <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
514 You need to have a local copy of the Yocto Project
515 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
516 (i.e. a local <filename>poky</filename> repository).
517 See the
518 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
519 and possibly the
520 "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
521 and
522 "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
523 sections all in the Yocto Project Development Manual for
524 information on how to clone the <filename>poky</filename>
525 repository and check out the appropriate branch for your work.
526 </para></listitem>
527 <listitem><para>
528 <emphasis>Initialize the Build Environment:</emphasis>
529 While in the root directory of the Source Directory (i.e.
530 <filename>poky</filename>), run the
531 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
532 environment setup script to define the OpenEmbedded
533 build environment on your build host.
534 <literallayout class='monospaced'>
535 $ source &OE_INIT_FILE;
536 </literallayout>
537 Among other things, the script creates the
538 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
539 which is <filename>build</filename> in this case
540 and is located in the
541 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
542 After the script runs, your current working directory
543 is set to the <filename>build</filename> directory.
544 <note>
545 For information on running a memory-resident
546 <ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>,
547 see the
548 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
549 setup script.
550 </note>
551 </para></listitem>
552 </itemizedlist>
553 </para>
554 </section>
555
494 <section id='create-a-layer-for-your-changes'> 556 <section id='create-a-layer-for-your-changes'>
495 <title>Create a Layer for your Changes</title> 557 <title>Create a Layer for your Changes</title>
496 558
497 <para> 559 <para>
498 The first step is to create a layer so you can isolate your 560 The first step is to create a layer so you can isolate your
499 changes. 561 changes to the kernel.
500 Rather than use the <filename>yocto-layer</filename> script 562 Rather than use the <filename>yocto-layer</filename> script
501 to create the layer, this example steps through the process 563 to create the layer, this example steps through the process
502 by hand. 564 by hand.
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index 60d67d64fe..76f52526a3 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -416,8 +416,8 @@
416 Yocto Linux kernel tree. 416 Yocto Linux kernel tree.
417 For information on how to clone a Yocto Linux kernel 417 For information on how to clone a Yocto Linux kernel
418 Git repository, see the 418 Git repository, see the
419 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Setting Up to Work On a Kernel</ulink>" 419 "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
420 section in the Yocto Project Development Manual. 420 section.
421 </para></listitem> 421 </para></listitem>
422 <listitem><para> 422 <listitem><para>
423 <emphasis>Temporary Source Files from a Build:</emphasis> 423 <emphasis>Temporary Source Files from a Build:</emphasis>
diff --git a/documentation/kernel-dev/kernel-dev-examples.xml b/documentation/kernel-dev/kernel-dev-examples.xml
index 1d8dae3211..15622003e5 100644
--- a/documentation/kernel-dev/kernel-dev-examples.xml
+++ b/documentation/kernel-dev/kernel-dev-examples.xml
@@ -51,10 +51,10 @@
51 <literallayout class='monospaced'> 51 <literallayout class='monospaced'>
52 $ git clone git://git.yoctoproject.org/linux-yocto-3.4 52 $ git clone git://git.yoctoproject.org/linux-yocto-3.4
53 </literallayout> 53 </literallayout>
54 For another example of how to set up a local Git repository of the Yocto Project 54 For more information on how to set up a local Git repository of the
55 kernel files, see the 55 Yocto Project kernel files, see the
56 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted 56 "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
57 item in the Yocto Project Development Manual. 57 section.
58 </para> 58 </para>
59 <para> 59 <para>
60 Once you have cloned the kernel Git repository on your local machine, you can 60 Once you have cloned the kernel Git repository on your local machine, you can
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
index 899ed65db2..9080ddc1b8 100644
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -90,6 +90,130 @@
90 </para> 90 </para>
91</section> 91</section>
92 92
93<section id='preparing-the-build-host-to-work-on-the-kernel'>
94 <title>Preparing the Build Host to Work on the Kernel</title>
95
96 <para>
97 Kernel development is best accomplished using
98 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
99 and not through traditional kernel workflow methods.
100 This section provides information for both scenarios.
101 </para>
102
103 <section id='getting-ready-to-develop-using-devtool'>
104 <title>Getting Ready to Develop using <filename>devtool</filename></title>
105
106 <para role='writernotes'>
107 Need the updated wiki stuff here
108 </para>
109 </section>
110
111 <section id='getting-ready-for-traditional-kernel-development'>
112 <title>Getting Ready for Traditional Kernel Development</title>
113
114 <para>
115 For traditional kernel development using the Yocto
116 Project, you need to establish local copies of the
117 kernel source.
118 You can find Git repositories of supported Yocto Project
119 kernels organized under "Yocto Linux Kernel" in the Yocto
120 Project Source Repositories at
121 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
122 </para>
123
124 <para>
125 This setup can involve creating a bare clone of the
126 Yocto Project kernel and then copying that cloned
127 repository.
128 You can create the bare clone and the copy of the bare
129 clone anywhere you like.
130 For simplicity, it is recommended that you create these
131 structures outside of the
132 <ulink url='&YOCTO_DOCS_REF_URL;source-directory'>Source Directory</ulink>,
133 which is usually named <filename>poky</filename>.
134 </para>
135
136 <para>
137 The following steps show how to create a bare clone of the
138 <filename>linux-yocto-4.4</filename> kernel and then
139 create a copy of that clone:
140 <note>
141 When you have a local Yocto Project kernel Git
142 repository, you can reference that repository rather than
143 the upstream Git repository as part of the
144 <filename>clone</filename> command.
145 Doing so can speed up the process.
146 </note>
147 <orderedlist>
148 <listitem><para>
149 <emphasis>Create the Bare Clone:</emphasis>
150 In the following example, the bare clone is named
151 <filename>linux-yocto-4.4.git</filename>:
152 <literallayout class='monospaced'>
153 $ git clone &dash;&dash;bare git://git.yoctoproject.org/linux-yocto-4.4 linux-yocto-4.4.git
154 Cloning into bare repository 'linux-yocto-4.4.git'...
155 remote: Counting objects: 4543903, done.
156 remote: Compressing objects: 100% (695618/695618), done.
157 remote: Total 4543903 (delta 3818435), reused 4541724 (delta 3816256)
158 Receiving objects: 100% (4543903/4543903), 801.08 MiB | 6.55 MiB/s, done.
159 Resolving deltas: 100% (3818435/3818435), done.
160 Checking connectivity... done.
161 </literallayout>
162 </para></listitem>
163 <listitem><para>
164 <emphasis>Create the Copy of the Bare Clone:</emphasis>
165 In the following command, the copy of the bare clone
166 is named <filename>my-linux-yocto-4.4-work</filename>:
167 <literallayout class='monospaced'>
168 $ git clone linux-yocto-4.4.git my-linux-yocto-4.4-work
169 Cloning into 'my-linux-yocto-4.4-work'...
170 done.
171 Checking out files: 100% (52221/52221), done.
172 </literallayout>
173 </para></listitem>
174 <listitem><para>
175 <emphasis>Cloning the <filename>meta-yocto-kernel-extras</filename> Repository:</emphasis>
176 The <filename>meta-yocto-kernel-extras</filename> Git
177 repository contains Metadata needed only if you are
178 modifying and building the kernel image.
179 In particular, it contains the kernel BitBake append
180 (<filename>.bbappend</filename>) files that you edit to
181 point to your locally modified kernel source files and
182 to build the kernel image.
183 Pointing to these local files is much more efficient
184 than requiring a download of the kernel's source files
185 from upstream each time you make changes to the kernel.
186 </para>
187
188 <para>You can find the
189 <filename>meta-yocto-kernel-extras</filename> Git
190 Repository in the "Yocto Metadata Layers" area of the
191 Yocto Project Source Repositories at
192 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
193 It is good practice to create this Git repository
194 inside the Source Directory.</para>
195
196 <para>Following is an example that creates the
197 <filename>meta-yocto-kernel-extras</filename> Git
198 repository inside the Source Directory, which is named
199 <filename>poky</filename>, in this case:
200 <literallayout class='monospaced'>
201 $ cd ~/poky
202 $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
203 Cloning into 'meta-yocto-kernel-extras'...
204 remote: Counting objects: 727, done.
205 remote: Compressing objects: 100% (452/452), done.
206 remote: Total 727 (delta 260), reused 719 (delta 252)
207 Receiving objects: 100% (727/727), 536.36 KiB | 0 bytes/s, done.
208 Resolving deltas: 100% (260/260), done.
209 Checking connectivity... done.
210 </literallayout>
211 </para></listitem>
212 </orderedlist>
213 </para>
214 </section>
215</section>
216
93<section id='kernel-modification-workflow'> 217<section id='kernel-modification-workflow'>
94 <title>Kernel Modification Workflow</title> 218 <title>Kernel Modification Workflow</title>
95 219
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml
index 7cfcb45c94..446bace5ea 100644
--- a/documentation/kernel-dev/kernel-dev-maint-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-maint-appx.xml
@@ -34,10 +34,10 @@
34 <literallayout class='monospaced'> 34 <literallayout class='monospaced'>
35 $ git clone git://git.yoctoproject.org/linux-yocto-3.19 35 $ git clone git://git.yoctoproject.org/linux-yocto-3.19
36 </literallayout> 36 </literallayout>
37 For another example of how to set up a local Git repository of the Yocto Project 37 For more information on how to set up a local Git repository of
38 kernel files, see the 38 the Yocto Project kernel files, see the
39 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted 39 "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
40 item in the Yocto Project Development Manual. 40 section.
41 </para> 41 </para>
42 <para> 42 <para>
43 Once you have cloned the kernel Git repository on your local machine, you can 43 Once you have cloned the kernel Git repository on your local machine, you can