summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/kernel-dev')
-rw-r--r--documentation/kernel-dev/kernel-dev-faq.xml1386
1 files changed, 537 insertions, 849 deletions
diff --git a/documentation/kernel-dev/kernel-dev-faq.xml b/documentation/kernel-dev/kernel-dev-faq.xml
index 9d9aef6d06..176573de28 100644
--- a/documentation/kernel-dev/kernel-dev-faq.xml
+++ b/documentation/kernel-dev/kernel-dev-faq.xml
@@ -2,916 +2,604 @@
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[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4 4
5<chapter id='kernel-how-to'> 5<chapter id='faq'>
6 6<title>FAQ</title>
7<title>Working with the Yocto Project Kernel</title> 7<qandaset>
8 8 <qandaentry>
9 9 <question>
10<section id='actions-org'>
11 <title>Introduction</title>
12 <para>
13 This chapter describes how to accomplish tasks involving a kernel's tree structure.
14 The information is designed to help the developer that wants to modify the Yocto
15 Project kernel and contribute changes upstream to the Yocto Project.
16 The information covers the following:
17 <itemizedlist>
18 <listitem><para>Tree construction</para></listitem>
19 <listitem><para>Build strategies</para></listitem>
20 <listitem><para>Workflow examples</para></listitem>
21 </itemizedlist>
22 </para>
23</section>
24
25 <section id='tree-construction'>
26 <title>Tree Construction</title>
27 <para>
28 This section describes construction of the Yocto Project kernel source repositories
29 as accomplished by the Yocto Project team to create kernel repositories.
30 These kernel repositories are found under the heading "Yocto Linux Kernel" at
31 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
32 and can be shipped as part of a Yocto Project release.
33 The team creates these repositories by
34 compiling and executing the set of feature descriptions for every BSP/feature
35 in the product.
36 Those feature descriptions list all necessary patches,
37 configuration, branching, tagging and feature divisions found in a kernel.
38 Thus, the Yocto Project kernel repository (or tree) is built.
39 </para>
40 <para>
41 The existence of this tree allows you to access and clone a particular
42 Yocto Project kernel repository and use it to build images based on their configurations
43 and features.
44 </para>
45 <para>
46 You can find the files used to describe all the valid features and BSPs
47 in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
48 Git tree.
49 For example, the following command clones the Yocto Project baseline kernel that
50 branched off of <filename>linux.org</filename> version 3.4:
51 <literallayout class='monospaced'>
52 $ git clone git://git.yoctoproject.org/linux-yocto-3.4
53 </literallayout>
54 For another example of how to set up a local Git repository of the Yocto Project
55 kernel files, see the
56 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
57 item in the Yocto Project Development Manual.
58 </para>
59 <para>
60 Once you have cloned the kernel Git repository on your local machine, you can
61 switch to the <filename>meta</filename> branch within the repository.
62 Here is an example that assumes the local Git repository for the kernel is in
63 a top-level directory named <filename>linux-yocto-3.4</filename>:
64 <literallayout class='monospaced'>
65 $ cd ~/linux-yocto-3.4
66 $ git checkout -b meta origin/meta
67 </literallayout>
68 Once you have checked out and switched to the <filename>meta</filename> branch,
69 you can see a snapshot of all the kernel configuration and feature descriptions that are
70 used to build that particular kernel repository.
71 These descriptions are in the form of <filename>.scc</filename> files.
72 </para>
73 <para>
74 You should realize, however, that browsing your local kernel repository
75 for feature descriptions and patches is not an effective way to determine what is in a
76 particular kernel branch.
77 Instead, you should use Git directly to discover the changes in a branch.
78 Using Git is an efficient and flexible way to inspect changes to the kernel.
79 For examples showing how to use Git to inspect kernel commits, see the following sections
80 in this chapter.
81 <note>
82 Ground up reconstruction of the complete kernel tree is an action only taken by the
83 Yocto Project team during an active development cycle.
84 When you create a clone of the kernel Git repository, you are simply making it
85 efficiently available for building and development.
86 </note>
87 </para>
88 <para>
89 The following steps describe what happens when the Yocto Project Team constructs
90 the Yocto Project kernel source Git repository (or tree) found at
91 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
92 introduction of a new top-level kernel feature or BSP.
93 These are the actions that effectively create the tree
94 that includes the new feature, patch or BSP:
95 <orderedlist>
96 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
97 Normally, this feature is a BSP for a particular kernel type.</para></listitem>
98 <listitem><para>The file that describes the top-level feature is located by searching
99 these system directories:
100 <itemizedlist>
101 <listitem><para>The in-tree kernel-cache directories, which are located
102 in <filename>meta/cfg/kernel-cache</filename></para></listitem>
103 <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
104 found in recipes</para></listitem>
105 </itemizedlist>
106 For a typical build, the target of the search is a
107 feature description in an <filename>.scc</filename> file
108 whose name follows this format:
109 <literallayout class='monospaced'>
110 &lt;bsp_name&gt;-&lt;kernel_type&gt;.scc
111 </literallayout>
112 </para></listitem>
113 <listitem><para>Once located, the feature description is either compiled into a simple script
114 of actions, or into an existing equivalent script that is already part of the
115 shipped kernel.</para></listitem>
116 <listitem><para>Extra features are appended to the top-level feature description.
117 These features can come from the
118 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
119 variable in recipes.</para></listitem>
120 <listitem><para>Each extra feature is located, compiled and appended to the script
121 as described in step three.</para></listitem>
122 <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
123 directories.
124 These directories are descriptions of all the branches, tags, patches and configurations that
125 need to be applied to the base Git repository to completely create the
126 source (build) branch for the new BSP or feature.</para></listitem>
127 <listitem><para>The base repository is cloned, and the actions
128 listed in the <filename>meta-*</filename> directories are applied to the
129 tree.</para></listitem>
130 <listitem><para>The Git repository is left with the desired branch checked out and any
131 required branching, patching and tagging has been performed.</para></listitem>
132 </orderedlist>
133 </para>
134 <para>
135 The kernel tree is now ready for developer consumption to be locally cloned,
136 configured, and built into a Yocto Project kernel specific to some target hardware.
137 <note><para>The generated <filename>meta-*</filename> directories add to the kernel
138 as shipped with the Yocto Project release.
139 Any add-ons and configuration data are applied to the end of an existing branch.
140 The full repository generation that is found in the
141 official Yocto Project kernel repositories at
142 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
143 is the combination of all supported boards and configurations.</para>
144 <para>The technique the Yocto Project team uses is flexible and allows for seamless
145 blending of an immutable history with additional patches specific to a
146 deployment.
147 Any additions to the kernel become an integrated part of the branches.</para>
148 </note>
149 </para>
150 </section>
151
152 <section id='build-strategy'>
153 <title>Build Strategy</title>
154 <para>
155 Once a local Git repository of the Yocto Project kernel exists on a development system,
156 you can consider the compilation phase of kernel development - building a kernel image.
157 Some prerequisites exist that are validated by the build process before compilation
158 starts:
159 </para>
160
161 <itemizedlist>
162 <listitem><para>The
163 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
164 to the kernel Git repository.</para></listitem>
165 <listitem><para>A BSP build branch exists.
166 This branch has the following form:
167 <literallayout class='monospaced'>
168 &lt;kernel_type&gt;/&lt;bsp_name&gt;
169 </literallayout></para></listitem>
170 </itemizedlist>
171
172 <para>
173 The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
174 Other means, however, do exist, such as as bootstrapping a BSP, see
175 the "<link linkend='workflow-examples'>Workflow Examples</link>".
176 </para>
177
178 <para>
179 Before building a kernel, the build process verifies the tree
180 and configures the kernel by processing all of the
181 configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
182 files.
183 As the features are compiled, associated kernel configuration fragments are noted
184 and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
185 The fragments are migrated, pre-processed and passed to the Linux Kernel
186 Configuration subsystem (<filename>lkc</filename>) as raw input in the form
187 of a <filename>.config</filename> file.
188 The <filename>lkc</filename> uses its own internal dependency constraints to do the final
189 processing of that information and generates the final <filename>.config</filename> file
190 that is used during compilation.
191 </para>
192
193 <para>
194 Using the board's architecture and other relevant values from the board's template,
195 kernel compilation is started and a kernel image is produced.
196 </para>
197
198 <para>
199 The other thing that you notice once you configure a kernel is that
200 the build process generates a build tree that is separate from your kernel's local Git
201 source repository tree.
202 This build tree has a name that uses the following form, where
203 <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
204 of the Yocto Project supported kernel types (e.g. "standard"):
205 <literallayout class='monospaced'>
206 linux-${MACHINE}-&lt;kernel_type&gt;-build
207 </literallayout>
208 </para>
209
210 <para>
211 The existing support in the <filename>kernel.org</filename> tree achieves this
212 default functionality.
213 </para>
214
215 <para>
216 This behavior means that all the generated files for a particular machine or BSP are now in
217 the build tree directory.
218 The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
219 files, the <filename>.a</filename> files, and so forth.
220 Since each machine or BSP has its own separate build directory in its own separate branch
221 of the Git repository, you can easily switch between different builds.
222 </para>
223 </section>
224
225 <section id='workflow-examples'>
226 <title>Workflow Examples</title>
227
228 <para>
229 As previously noted, the Yocto Project kernel has built-in Git integration.
230 However, these utilities are not the only way to work with the kernel repository.
231 The Yocto Project has not made changes to Git or to other tools that
232 would invalidate alternate workflows.
233 Additionally, the way the kernel repository is constructed results in using
234 only core Git functionality, thus allowing any number of tools or front ends to use the
235 resulting tree.
236 </para>
237
238 <para>
239 This section contains several workflow examples.
240 Many of the examples use Git commands.
241 You can find Git documentation at
242 <ulink url='http://git-scm.com/documentation'></ulink>.
243 You can find a simple overview of using Git with the Yocto Project in the
244 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
245 section of the Yocto Project Development Manual.
246 </para>
247
248 <section id='change-inspection-kernel-changes-commits'>
249 <title>Change Inspection: Changes/Commits</title>
250
251 <para> 10 <para>
252 A common question when working with a kernel is: 11 How does Poky differ from <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>?
253 "What changes have been applied to this tree?"
254 </para> 12 </para>
255 13 </question>
14 <answer>
256 <para> 15 <para>
257 In projects that have a collection of directories that 16 The term "Poky" refers to the specific reference build system that
258 contain patches to the kernel, it is possible to inspect or "grep" the contents 17 the Yocto Project provides.
259 of the directories to get a general feel for the changes. 18 Poky is based on <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink>
260 This sort of patch inspection is not an efficient way to determine what has been 19 and BitBake.
261 done to the kernel. 20 Thus, the generic term used here for the build system is
262 The reason it is inefficient is because there are many optional patches that are 21 the "OpenEmbedded build system."
263 selected based on the kernel type and the feature description. 22 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
264 Additionally, patches could exist in directories that are not included in the search. 23 changes always being merged to OE-Core or BitBake first before being pulled back
24 into Poky.
25 This practice benefits both projects immediately.
26 For a fuller description of the term "Poky", see the
27 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> term in the Yocto Project
28 Development Manual.
265 </para> 29 </para>
30 </answer>
31 </qandaentry>
266 32
33 <qandaentry>
34 <question>
267 <para> 35 <para>
268 A more efficient way to determine what has changed in the branch is to use 36 I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
269 Git and inspect or search the kernel tree. 37 Can I still use the Yocto Project?
270 This method gives you a full view of not only the source code modifications,
271 but also provides the reasons for the changes.
272 </para> 38 </para>
273 39 </question>
274 <section id='what-changed-in-a-kernel'> 40 <answer>
275 <title>What Changed in a Kernel?</title>
276
277 <para>
278 Following are a few examples that show how to use Git commands to examine changes.
279 Because Git repositories in the Yocto Project do not break existing Git
280 functionality, and because there exists many permutations of these types of
281 Git commands, many methods exist by which you can discover changes.
282 <note>
283 In the following examples, unless you provide a commit range,
284 <filename>kernel.org</filename> history is blended with Yocto Project
285 kernel changes.
286 You can form ranges by using branch names from the kernel tree as the
287 upper and lower commit markers with the Git commands.
288 You can see the branch names through the web interface to the
289 Yocto Project source repositories at
290 <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
291 For example, the branch names for the <filename>linux-yocto-3.4</filename>
292 kernel repository can be seen at
293 <ulink url='http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
294 </note>
295 To see a full range of the changes, use the
296 <filename>git whatchanged</filename> command and specify a commit range
297 for the branch (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
298 </para>
299
300 <para>
301 Here is an example that looks at what has changed in the
302 <filename>emenlow</filename> branch of the
303 <filename>linux-yocto-3.4</filename> kernel.
304 The lower commit range is the commit associated with the
305 <filename>standard/base</filename> branch, while
306 the upper commit range is the commit associated with the
307 <filename>standard/emenlow</filename> branch.
308 <literallayout class='monospaced'>
309 $ git whatchanged origin/standard/base..origin/standard/emenlow
310 </literallayout>
311 </para>
312
313 <para>
314 To see a summary of changes use the <filename>git log</filename> command.
315 Here is an example using the same branches:
316 <literallayout class='monospaced'>
317 $ git log --oneline origin/standard/base..origin/standard/emenlow
318 </literallayout>
319 The <filename>git log</filename> output might be more useful than
320 the <filename>git whatchanged</filename> as you get
321 a short, one-line summary of each change and not the entire commit.
322 </para>
323
324 <para>
325 If you want to see code differences associated with all the changes, use
326 the <filename>git diff</filename> command.
327 Here is an example:
328 <literallayout class='monospaced'>
329 $ git diff origin/standard/base..origin/standard/emenlow
330 </literallayout>
331 </para>
332
333 <para>
334 You can see the commit log messages and the text differences using the
335 <filename>git show</filename> command:
336 Here is an example:
337 <literallayout class='monospaced'>
338 $ git show origin/standard/base..origin/standard/emenlow
339 </literallayout>
340 </para>
341
342 <para>
343 You can create individual patches for each change by using the
344 <filename>git format-patch</filename> command.
345 Here is an example that that creates patch files for each commit and
346 places them in your <filename>Documents</filename> directory:
347 <literallayout class='monospaced'>
348 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
349 </literallayout>
350 </para>
351 </section>
352
353 <section id='show-a-particular-feature-or-branch-change'>
354 <title>Show a Particular Feature or Branch Change</title>
355
356 <para>
357 Developers use tags in the Yocto Project kernel tree to divide changes for significant
358 features or branches.
359 Once you know a particular tag, you can use Git commands
360 to show changes associated with the tag and find the branches that contain
361 the feature.
362 <note>
363 Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
364 present, there could be many tags.
365 </note>
366 The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by
367 a feature.
368 Here is an example that shows changes tagged by the <filename>systemtap</filename>
369 feature:
370 <literallayout class='monospaced'>
371 $ git show systemtap
372 </literallayout>
373 You can use the <filename>git branch --contains &lt;tag&gt;</filename> command
374 to show the branches that contain a particular feature.
375 This command shows the branches that contain the <filename>systemtap</filename>
376 feature:
377 <literallayout class='monospaced'>
378 $ git branch --contains systemtap
379 </literallayout>
380 </para>
381
382 <para>
383 You can use many other comparisons to isolate BSP and kernel changes.
384 For example, you can compare against <filename>kernel.org</filename> tags
385 such as the <filename>v3.4</filename> tag.
386 </para>
387 </section>
388 </section>
389
390 <section id='development-saving-kernel-modifications'>
391 <title>Development: Saving Kernel Modifications</title>
392
393 <para> 41 <para>
394 Another common operation is to build a BSP supplied by the Yocto Project, make some 42 You can use a stand-alone tarball to provide Python 2.6.
395 changes, rebuild, and then test. 43 You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations:
396 Those local changes often need to be exported, shared or otherwise maintained. 44 <itemizedlist>
45 <listitem><para><ulink url='&YOCTO_PYTHON-i686_DL_URL;'>32-bit tarball</ulink></para></listitem>
46 <listitem><para><ulink url='&YOCTO_PYTHON-x86_64_DL_URL;'>64-bit tarball</ulink></para></listitem>
47 </itemizedlist>
397 </para> 48 </para>
398
399 <para> 49 <para>
400 Since the Yocto Project kernel source tree is backed by Git, this activity is 50 These tarballs are self-contained with all required libraries and should work
401 much easier as compared to with previous releases. 51 on most Linux systems.
402 Because Git tracks file modifications, additions and deletions, it is easy 52 To use the tarballs extract them into the root
403 to modify the code and later realize that you need to save the changes. 53 directory and run the appropriate command:
404 It is also easy to determine what has changed. 54 <literallayout class='monospaced'>
405 This method also provides many tools to commit, undo and export those modifications. 55 $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH
56 $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH
57 </literallayout>
406 </para> 58 </para>
407
408 <para> 59 <para>
409 This section and its sub-sections, describe general application of Git's 60 Once you run the command, BitBake uses Python 2.6.
410 <filename>push</filename> and <filename>pull</filename> commands, which are used to
411 get your changes upstream or source your code from an upstream repository.
412 The Yocto Project provides scripts that help you work in a collaborative development
413 environment.
414 For information on these scripts, see the
415 "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
416 Upstream and Request a Pull</ulink>" and
417 "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
418 sections in the Yocto Project Development Manual.
419 </para> 61 </para>
62 </answer>
63 </qandaentry>
420 64
65 <qandaentry>
66 <question>
421 <para> 67 <para>
422 There are many ways to save kernel modifications. 68 How can you claim Poky / OpenEmbedded-Core is stable?
423 The technique employed
424 depends on the destination for the patches:
425
426 <itemizedlist>
427 <listitem><para>Bulk storage</para></listitem>
428 <listitem><para>Internal sharing either through patches or by using Git</para></listitem>
429 <listitem><para>External submissions</para></listitem>
430 <listitem><para>Exporting for integration into another Source Code
431 Manager (SCM)</para></listitem>
432 </itemizedlist>
433 </para> 69 </para>
434 70 </question>
71 <answer>
435 <para> 72 <para>
436 Because of the following list of issues, the destination of the patches also influences 73 There are three areas that help with stability;
437 the method for gathering them:
438
439 <itemizedlist> 74 <itemizedlist>
440 <listitem><para>Bisectability</para></listitem> 75 <listitem><para>The Yocto Project team keeps
441 <listitem><para>Commit headers</para></listitem> 76 <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> small
442 <listitem><para>Division of subsystems for separate submission or review</para></listitem> 77 and focused, containing around 830 recipes as opposed to the thousands
78 available in other OpenEmbedded community layers.
79 Keeping it small makes it easy to test and maintain.</para></listitem>
80 <listitem><para>The Yocto Project team runs manual and automated tests
81 using a small, fixed set of reference hardware as well as emulated
82 targets.</para></listitem>
83 <listitem><para>The Yocto Project uses an an autobuilder,
84 which provides continuous build and integration tests.</para></listitem>
443 </itemizedlist> 85 </itemizedlist>
444 </para> 86 </para>
87 </answer>
88 </qandaentry>
445 89
446 <section id='bulk-export'> 90 <qandaentry>
447 <title>Bulk Export</title> 91 <question>
448 92 <para>
449 <para> 93 How do I get support for my board added to the Yocto Project?
450 This section describes how you can "bulk" export changes that have not 94 </para>
451 been separated or divided. 95 </question>
452 This situation works well when you are simply storing patches outside of the kernel 96 <answer>
453 source repository, either permanently or temporarily, and you are not committing 97 <para>
454 incremental changes during development. 98 Support for an additional board is added by creating a BSP layer for it.
455 <note> 99 For more information on how to create a BSP layer, see the
456 This technique is not appropriate for full integration of upstream submission 100 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
457 because changes are not properly divided and do not provide an avenue for per-change 101 </para>
458 commit messages. 102 <para>
459 Therefore, this example assumes that changes have not been committed incrementally 103 Usually, if the board is not completely exotic, adding support in
460 during development and that you simply must gather and export them. 104 the Yocto Project is fairly straightforward.
461 </note> 105 </para>
462 <literallayout class='monospaced'> 106 </answer>
463 # bulk export of ALL modifications without separation or division 107 </qandaentry>
464 # of the changes
465
466 $ git add .
467 $ git commit -s -a -m &lt;msg&gt;
468 or
469 $ git commit -s -a # and interact with $EDITOR
470 </literallayout>
471 </para>
472
473 <para>
474 The previous operations capture all the local changes in the project source
475 tree in a single Git commit.
476 And, that commit is also stored in the project's source tree.
477 </para>
478
479 <para>
480 Once the changes are exported, you can restore them manually using a template
481 or through integration with the <filename>default_kernel</filename>.
482 </para>
483
484 </section>
485
486 <section id='incremental-planned-sharing'>
487 <title>Incremental/Planned Sharing</title>
488
489 <para>
490 This section describes how to save modifications when you are making incremental
491 commits or practicing planned sharing.
492 The examples in this section assume that you have incrementally committed
493 changes to the tree during development and now need to export them.
494 The sections that follow
495 describe how you can export your changes internally through either patches or by
496 using Git commands.
497 </para>
498
499 <para>
500 During development, the following commands are of interest.
501 For full Git documentation, refer to the Git documentation at
502 <ulink url='http://github.com'></ulink>.
503
504 <literallayout class='monospaced'>
505 # edit a file
506 $ vi &lt;path&gt;/file
507 # stage the change
508 $ git add &lt;path&gt;/file
509 # commit the change
510 $ git commit -s
511 # remove a file
512 $ git rm &lt;path&gt;/file
513 # commit the change
514 $ git commit -s
515
516 ... etc.
517 </literallayout>
518 </para>
519
520 <para>
521 Distributed development with Git is possible when you use a universally
522 agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
523 specific change set with a specific parent.
524 This identifier is created for you when
525 you create a commit, and is re-created when you amend, alter or re-apply
526 a commit.
527 As an individual in isolation, this is of no interest.
528 However, if you
529 intend to share your tree with normal Git <filename>push</filename> and
530 <filename>pull</filename> operations for
531 distributed development, you should consider the ramifications of changing a
532 commit that you have already shared with others.
533 </para>
534
535 <para>
536 Assuming that the changes have not been pushed upstream, or pulled into
537 another repository, you can update both the commit content and commit messages
538 associated with development by using the following commands:
539
540 <literallayout class='monospaced'>
541 $ Git add &lt;path&gt;/file
542 $ Git commit --amend
543 $ Git rebase or Git rebase -i
544 </literallayout>
545 </para>
546
547 <para>
548 Again, assuming that the changes have not been pushed upstream, and that
549 no pending works-in-progress exist (use <filename>git status</filename> to check), then
550 you can revert (undo) commits by using the following commands:
551
552 <literallayout class='monospaced'>
553 # remove the commit, update working tree and remove all
554 # traces of the change
555 $ git reset --hard HEAD^
556 # remove the commit, but leave the files changed and staged for re-commit
557 $ git reset --soft HEAD^
558 # remove the commit, leave file change, but not staged for commit
559 $ git reset --mixed HEAD^
560 </literallayout>
561 </para>
562
563 <para>
564 You can create branches, "cherry-pick" changes, or perform any number of Git
565 operations until the commits are in good order for pushing upstream
566 or for pull requests.
567 After a <filename>push</filename> or <filename>pull</filename> command,
568 commits are normally considered
569 "permanent" and you should not modify them.
570 If the commits need to be changed, you can incrementally do so with new commits.
571 These practices follow standard Git workflow and the <filename>kernel.org</filename> best
572 practices, which is recommended.
573 <note>
574 It is recommended to tag or branch before adding changes to a Yocto Project
575 BSP or before creating a new one.
576 The reason for this recommendation is because the branch or tag provides a
577 reference point to facilitate locating and exporting local changes.
578 </note>
579 </para>
580
581 <section id='export-internally-via-patches'>
582 <title>Exporting Changes Internally by Using Patches</title>
583
584 <para>
585 This section describes how you can extract committed changes from a working directory
586 by exporting them as patches.
587 Once the changes have been extracted, you can use the patches for upstream submission,
588 place them in a Yocto Project template for automatic kernel patching,
589 or apply them in many other common uses.
590 </para>
591
592 <para>
593 This example shows how to create a directory with sequentially numbered patches.
594 Once the directory is created, you can apply it to a repository using the
595 <filename>git am</filename> command to reproduce the original commit and all
596 the related information such as author, date, commit log, and so forth.
597 <note>
598 The new commit identifiers (ID) will be generated upon re-application.
599 This action reflects that the commit is now applied to an underlying commit
600 with a different ID.
601 </note>
602 <literallayout class='monospaced'>
603 # &lt;first-commit&gt; can be a tag if one was created before development
604 # began. It can also be the parent branch if a branch was created
605 # before development began.
606
607 $ git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
608 </literallayout>
609 </para>
610
611 <para>
612 In other words:
613 <literallayout class='monospaced'>
614 # Identify commits of interest.
615
616 # If the tree was tagged before development
617 $ git format-patch -o &lt;save dir&gt; &lt;tag&gt;
618
619 # If no tags are available
620 $ git format-patch -o &lt;save dir&gt; HEAD^ # last commit
621 $ git format-patch -o &lt;save dir&gt; HEAD^^ # last 2 commits
622 $ git whatchanged # identify last commit
623 $ git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
624 $ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
625 </literallayout>
626 </para>
627 </section>
628
629 <section id='export-internally-via-git'>
630 <title>Exporting Changes Internally by Using Git</title>
631
632 <para>
633 This section describes how you can export changes from a working directory
634 by pushing the changes into a master repository or by making a pull request.
635 Once you have pushed the changes to the master repository, you can then
636 pull those same changes into a new kernel build at a later time.
637 </para>
638
639 <para>
640 Use this command form to push the changes:
641 <literallayout class='monospaced'>
642 $ git push ssh://&lt;master_server&gt;/&lt;path_to_repo&gt;
643 &lt;local_branch&gt;:&lt;remote_branch&gt;
644 </literallayout>
645 </para>
646
647 <para>
648 For example, the following command pushes the changes from your local branch
649 <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
650 in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
651 <literallayout class='monospaced'>
652 $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
653 yocto/standard/common-pc/base:yocto/standard/common-pc/base
654 </literallayout>
655 </para>
656
657 <para>
658 A pull request entails using the <filename>git request-pull</filename> command to compose
659 an email to the
660 maintainer requesting that a branch be pulled into the master repository, see
661 <ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
662 <note>
663 Other commands such as <filename>git stash</filename> or branching can also be used to save
664 changes, but are not covered in this document.
665 </note>
666 </para>
667 </section>
668 </section>
669
670 <section id='export-for-external-upstream-submission'>
671 <title>Exporting Changes for External (Upstream) Submission</title>
672
673 <para>
674 This section describes how to export changes for external upstream submission.
675 If the patch series is large or the maintainer prefers to pull
676 changes, you can submit these changes by using a pull request.
677 However, it is common to send patches as an email series.
678 This method allows easy review and integration of the changes.
679 <note>
680 Before sending patches for review be sure you understand the
681 community standards for submitting and documenting changes and follow their best practices.
682 For example, kernel patches should follow standards such as:
683 <itemizedlist>
684 <listitem><para>
685 <ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
686 <listitem><para>Documentation/SubmittingPatches (in any linux
687 kernel source tree)</para></listitem>
688 </itemizedlist>
689 </note>
690 </para>
691
692 <para>
693 The messages used to commit changes are a large part of these standards.
694 Consequently, be sure that the headers for each commit have the required information.
695 For information on how to follow the Yocto Project commit message standards, see the
696 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
697 Change</ulink>" section in the Yocto Project Development Manual.
698 </para>
699
700 <para>
701 If the initial commits were not properly documented or do not meet those standards,
702 you can re-base by using the <filename>git rebase -i</filename> command to
703 manipulate the commits and
704 get them into the required format.
705 Other techniques such as branching and cherry-picking commits are also viable options.
706 </para>
707 108
708 <para> 109 <qandaentry>
709 Once you complete the commits, you can generate the email that sends the patches 110 <question>
710 to the maintainer(s) or lists that review and integrate changes. 111 <para>
711 The command <filename>git send-email</filename> is commonly used to ensure 112 Are there any products built using the OpenEmbedded build system?
712 that patches are properly 113 </para>
713 formatted for easy application and avoid mailer-induced patch damage. 114 </question>
714 </para> 115 <answer>
116 <para>
117 The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink>
118 is built using the OpenEmbedded build system.
119 See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
120 website for more information.
121 There are a number of pre-production devices using the OpenEmbedded build system
122 and the Yocto Project team
123 announces them as soon as they are released.
124 </para>
125 </answer>
126 </qandaentry>
715 127
716 <para> 128 <qandaentry>
717 The following is an example of dumping patches for external submission: 129 <question>
718 <literallayout class='monospaced'> 130 <para>
719 # dump the last 4 commits 131 What does the OpenEmbedded build system produce as output?
720 $ git format-patch --thread -n -o ~/rr/ HEAD^^^^ 132 </para>
721 $ git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \ 133 </question>
722 --to foo@yoctoproject.org --to bar@yoctoproject.org \ 134 <answer>
723 --cc list@yoctoproject.org ~/rr 135 <para>
724 # the editor is invoked for the 0/N patch, and when complete the entire 136 Because the same set of recipes can be used to create output of various formats, the
725 # series is sent via email for review 137 output of an OpenEmbedded build depends on how it was started.
726 </literallayout> 138 Usually, the output is a flashable image ready for the target device.
727 </para> 139 </para>
728 </section> 140 </answer>
141 </qandaentry>
729 142
730 <section id='export-for-import-into-other-scm'> 143 <qandaentry>
731 <title>Exporting Changes for Import into Another SCM</title> 144 <question>
145 <para>
146 How do I add my package to the Yocto Project?
147 </para>
148 </question>
149 <answer>
150 <para>
151 To add a package, you need to create a BitBake recipe.
152 For information on how to add a package, see the section
153 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg'>Adding a Package</ulink>"
154 in the Yocto Project Development Manual.
155 </para>
156 </answer>
157 </qandaentry>
732 158
733 <para> 159 <qandaentry>
734 When you want to export changes for import into another 160 <question>
735 Source Code Manager (SCM), you can use any of the previously discussed 161 <para>
736 techniques. 162 Do I have to reflash my entire board with a new Yocto Project image when recompiling
737 However, if the patches are manually applied to a secondary tree and then 163 a package?
738 that tree is checked into the SCM, you can lose change information such as 164 </para>
739 commit logs. 165 </question>
740 This process is not recommended. 166 <answer>
741 </para> 167 <para>
168 The OpenEmbedded build system can build packages in various formats such as
169 <filename>ipk</filename> for <filename>opkg</filename>,
170 Debian package (<filename>.deb</filename>), or RPM.
171 The packages can then be upgraded using the package tools on the device, much like
172 on a desktop distribution such as Ubuntu or Fedora.
173 </para>
174 </answer>
175 </qandaentry>
742 176
743 <para> 177 <qandaentry>
744 Many SCMs can directly import Git commits, or can translate Git patches so that 178 <question>
745 information is not lost. 179 <para>
746 Those facilities are SCM-dependent and you should use them whenever possible. 180 What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
747 </para> 181 </para>
748 </section> 182 </question>
749 </section> 183 <answer>
184 <para>
185 GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink>
186 platform targeted at mobile and embedded devices.
187 The the main difference between GNOME Mobile and standard GNOME is that
188 desktop-orientated libraries have been removed, along with deprecated libraries,
189 creating a much smaller footprint.
190 </para>
191 </answer>
192 </qandaentry>
750 193
751 <section id='scm-working-with-the-yocto-project-kernel-in-another-scm'> 194 <qandaentry>
752 <title>Working with the Yocto Project Kernel in Another SCM</title> 195 <question>
196 <para>
197 I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'.
198 What is wrong?
199 </para>
200 </question>
201 <answer>
202 <para>
203 You are probably running the build on an NTFS filesystem.
204 Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
205 </para>
206 </answer>
207 </qandaentry>
753 208
209 <qandaentry>
210 <question>
211 <para>
212 How do I make the Yocto Project work in RHEL/CentOS?
213 </para>
214 </question>
215 <answer>
754 <para> 216 <para>
755 This section describes kernel development in an SCM other than Git, 217 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
756 which is not the same as exporting changes to another SCM described earlier. 218 install some required packages.
757 For this scenario, you use the OpenEmbedded build system to 219 The standard CentOS packages needed are:
758 develop the kernel in a different SCM. 220 <itemizedlist>
759 The following must be true for you to accomplish this: 221 <listitem><para>"Development tools" (selected during installation)</para></listitem>
222 <listitem><para><filename>texi2html</filename></para></listitem>
223 <listitem><para><filename>compat-gcc-34</filename></para></listitem>
224 </itemizedlist>
225 On top of these, you need the following external packages:
760 <itemizedlist> 226 <itemizedlist>
761 <listitem><para>The delivered Yocto Project kernel must be exported into the second 227 <listitem><para><filename>python-sqlite2</filename> from
762 SCM.</para></listitem> 228 <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
763 <listitem><para>Development must be exported from that secondary SCM into a 229 </para></listitem>
764 format that can be used by the OpenEmbedded build system.</para></listitem> 230 <listitem><para><filename>help2man</filename> from
231 <ulink url='http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html'>Karan repository</ulink></para></listitem>
765 </itemizedlist> 232 </itemizedlist>
766 </para> 233 </para>
767 234
768 <section id='exporting-delivered-kernel-to-scm'> 235 <para>
769 <title>Exporting the Delivered Kernel to the SCM</title> 236 Once these packages are installed, the OpenEmbedded build system will be able
237 to build standard images.
238 However, there might be a problem with the QEMU emulator segfaulting.
239 You can either disable the generation of binary locales by setting
240 <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
241 </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename>
242 from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
243 </para>
244 </answer>
245 </qandaentry>
770 246
771 <para> 247 <qandaentry>
772 Depending on the SCM, it might be possible to export the entire Yocto Project 248 <question>
773 kernel Git repository, branches and all, into a new environment. 249 <para>
774 This method is preferred because it has the most flexibility and potential to maintain 250 I see lots of 404 responses for files on
775 the meta data associated with each commit. 251 <filename>http://www.yoctoproject.org/sources/*</filename>. Is something wrong?
776 </para> 252 </para>
253 </question>
254 <answer>
255 <para>
256 Nothing is wrong.
257 The OpenEmbedded build system checks any configured source mirrors before downloading
258 from the upstream sources.
259 The build system does this searching for both source archives and
260 pre-checked out versions of SCM managed software.
261 These checks help in large installations because it can reduce load on the SCM servers
262 themselves.
263 The address above is one of the default mirrors configured into the
264 build system.
265 Consequently, if an upstream source disappears, the team
266 can place sources there so builds continue to work.
267 </para>
268 </answer>
269 </qandaentry>
270
271 <qandaentry>
272 <question>
273 <para>
274 I have machine-specific data in a package for one machine only but the package is
275 being marked as machine-specific in all cases, how do I prevent this?
276 </para>
277 </question>
278 <answer>
279 <para>
280 Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
281 </filename> = "0" in the <filename>.bb</filename> file but make sure the package is
282 manually marked as
283 machine-specific in the case that needs it.
284 The code that handles <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in <filename>base.bbclass</filename>.
285 </para>
286 </answer>
287 </qandaentry>
777 288
778 <para> 289 <qandaentry>
779 When a direct import mechanism is not available, it is still possible to 290 <question>
780 export a branch (or series of branches) and check them into a new repository. 291 <para>
781 </para> 292 I'm behind a firewall and need to use a proxy server. How do I do that?
293 </para>
294 </question>
295 <answer>
296 <para>
297 Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename>
298 and you therefore need to specify the proxy settings in a
299 <filename>.wgetrc</filename> file in your home directory.
300 Example settings in that file would be
301 <literallayout class='monospaced'>
302 http_proxy = http://proxy.yoyodyne.com:18023/
303 ftp_proxy = http://proxy.yoyodyne.com:18023/
304 </literallayout>
305 The Yocto Project also includes a <filename>site.conf.sample</filename>
306 file that shows how to configure CVS and Git proxy servers
307 if needed.
308 </para>
309 </answer>
310 </qandaentry>
782 311
783 <para> 312 <qandaentry>
784 The following commands illustrate some of the steps you could use to 313 <question>
785 import the <filename>yocto/standard/common-pc/base</filename> 314 <para>
786 kernel into a secondary SCM: 315 What’s the difference between <filename>foo</filename> and <filename>foo-native</filename>?
787 <literallayout class='monospaced'> 316 </para>
788 $ git checkout yocto/standard/common-pc/base 317 </question>
789 $ cd .. ; echo linux/.git &gt; .cvsignore 318 <answer>
790 $ cvs import -m "initial import" linux MY_COMPANY start 319 <para>
791 </literallayout> 320 The <filename>*-native</filename> targets are designed to run on the system
792 </para> 321 being used for the build.
322 These are usually tools that are needed to assist the build in some way such as
323 <filename>quilt-native</filename>, which is used to apply patches.
324 The non-native version is the one that runs on the target device.
325 </para>
326 </answer>
327 </qandaentry>
793 328
794 <para> 329 <qandaentry>
795 You could now relocate the CVS repository and use it in a centralized manner. 330 <question>
796 </para> 331 <para>
332 I'm seeing random build failures. Help?!
333 </para>
334 </question>
335 <answer>
336 <para>
337 If the same build is failing in totally different and random ways,
338 the most likely explanation is that either the hardware you're running the
339 build on has some problem, or, if you are running the build under virtualisation,
340 the virtualisation probably has bugs.
341 The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and
342 CPU activity and is sensitive to even single bit failures in any of these areas.
343 True random failures have always been traced back to hardware or virtualisation issues.
344 </para>
345 </answer>
346 </qandaentry>
797 347
798 <para> 348 <qandaentry>
799 The following commands illustrate how you can condense and merge two BSPs into a 349 <question>
800 second SCM: 350 <para>
801 <literallayout class='monospaced'> 351 What do we need to ship for license compliance?
802 $ git checkout yocto/standard/common-pc/base 352 </para>
803 $ git merge yocto/standard/common-pc-64/base 353 </question>
804 # resolve any conflicts and commit them 354 <answer>
805 $ cd .. ; echo linux/.git &gt; .cvsignore 355 <para>
806 $ cvs import -m "initial import" linux MY_COMPANY start 356 This is a difficult question and you need to consult your lawyer for the answer
807 </literallayout> 357 for your specific case.
808 </para> 358 It is worth bearing in mind that for GPL compliance there needs to be enough
809 </section> 359 information shipped to allow someone else to rebuild the same end result
360 you are shipping.
361 This means sharing the source code, any patches applied to it, and also any
362 configuration information about how that package was configured and built.
363 </para>
364 </answer>
365 </qandaentry>
810 366
811 <section id='importing-changes-for-build'> 367 <qandaentry>
812 <title>Importing Changes for the Build</title> 368 <question>
369 <para>
370 How do I disable the cursor on my touchscreen device?
371 </para>
372 </question>
373 <answer>
374 <para>
375 You need to create a form factor file as described in the
376 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>"
377 section and set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to one as follows:
378 <literallayout class='monospaced'>
379 HAVE_TOUCHSCREEN=1
380 </literallayout>
381 </para>
382 </answer>
383 </qandaentry>
813 384
814 <para> 385 <qandaentry>
815 Once development has reached a suitable point in the second development 386 <question>
816 environment, you need to export the changes as patches. 387 <para>
817 To export them, place the changes in a recipe and 388 How do I make sure connected network interfaces are brought up by default?
818 automatically apply them to the kernel during patching. 389 </para>
819 </para> 390 </question>
820 </section> 391 <answer>
821 </section> 392 <para>
393 The default interfaces file provided by the netbase recipe does not
394 automatically bring up network interfaces.
395 Therefore, you will need to add a BSP-specific netbase that includes an interfaces
396 file.
397 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>"
398 section for information on creating these types of miscellaneous recipe files.
399 </para>
400 <para>
401 For example, add the following files to your layer:
402 <literallayout class='monospaced'>
403 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
404 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
405 </literallayout>
406 </para>
407 </answer>
408 </qandaentry>
822 409
823 <section id='bsp-creating'> 410 <qandaentry>
824 <title>Creating a BSP Based on an Existing Similar BSP</title> 411 <question>
412 <para>
413 How do I create images with more free space?
414 </para>
415 </question>
416 <answer>
417 <para>
418 Images are created to be 1.2 times the size of the populated root filesystem.
419 To modify this ratio so that there is more free space available, you need to
420 set the configuration value <filename>IMAGE_OVERHEAD_FACTOR</filename>.
421 For example, setting <filename>IMAGE_OVERHEAD_FACTOR</filename> to 1.5 sets
422 the image size ratio to one and a half times the size of the populated
423 root filesystem.
424 <literallayout class='monospaced'>
425 IMAGE_OVERHEAD_FACTOR = "1.5"
426 </literallayout>
427 </para>
428 </answer>
429 </qandaentry>
825 430
431 <qandaentry>
432 <question>
826 <para> 433 <para>
827 This section overviews the process of creating a BSP based on an 434 Why don't you support directories with spaces in the pathnames?
828 existing similar BSP.
829 The information is introductory in nature and does not provide step-by-step examples.
830 For detailed information on how to create a new BSP, see
831 the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
832 Yocto Project Board Support Package (BSP) Developer's Guide, or see the
833 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
834 wiki page.
835 </para> 435 </para>
436 </question>
437 <answer>
438 <para>
439 The Yocto Project team has tried to do this before but too many of the tools
440 the OpenEmbedded build system depends on such as <filename>autoconf</filename>
441 break when they find spaces in pathnames.
442 Until that situation changes, the team will not support spaces in pathnames.
443 </para>
444 </answer>
445 </qandaentry>
836 446
447 <qandaentry>
448 <question>
449 <para>
450 How do I use an external toolchain?
451 </para>
452 </question>
453 <answer>
837 <para> 454 <para>
838 The basic steps you need to follow are: 455 The toolchain configuration is very flexible and customizable.
839 <orderedlist> 456 It is primarily controlled with the
840 <listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis> 457 <filename><link linkend='var-TCMODE'>TCMODE</link></filename> variable.
841 You must create a local 458 This variable controls which <filename>tcmode-*.inc</filename> file to include
842 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> 459 from the <filename>meta/conf/distro/include</filename> directory within the
843 by either creating a Git repository (recommended) or 460 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
844 extracting a Yocto Project release tarball.</para></listitem> 461 </para>
845 <listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
846 Try to map your board features as closely to the features of a BSP that is
847 already supported and exists in the Yocto Project.
848 Starting with something as close as possible to your board makes developing
849 your BSP easier.
850 You can find all the BSPs that are supported and ship with the Yocto Project
851 on the Yocto Project's Download page at
852 <ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
853 <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
854 You need to either have a local Git repository of the base BSP set up or
855 have downloaded and extracted the files from a release BSP tarball.
856 Either method gives you access to the BSP source files.</para></listitem>
857 <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
858 BSP work:</emphasis>
859 Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
860 <listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
861 Configuration changes involve the files in the BSP's <filename>conf</filename>
862 directory.
863 Changes include creating a machine-specific configuration file and editing the
864 <filename>layer.conf</filename> file.
865 The configuration changes identify the kernel you will be using.
866 Recipe changes include removing, modifying, or adding new recipe files that
867 instruct the build process on what features to include in the image.</para></listitem>
868 <listitem><para><emphasis>Prepare for the build:</emphasis>
869 Before you actually initiate the build, you need to set up the build environment
870 by sourcing the environment initialization script.
871 After setting up the environment, you need to make some build configuration
872 changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
873 files.</para></listitem>
874 <listitem><para><emphasis>Build the image:</emphasis>
875 The OpenEmbedded build system uses BitBake to create the image.
876 You need to decide on the type of image you are going to build (e.g. minimal, base,
877 core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
878 command.</para></listitem>
879 </orderedlist>
880 </para>
881 </section>
882 462
883 <section id='tip-dirty-string'> 463 <para>
884 <title>"-dirty" String</title> 464 The default value of <filename>TCMODE</filename> is "default"
465 (i.e. <filename>tcmode-default.inc</filename>).
466 However, other patterns are accepted.
467 In particular, "external-*" refers to external toolchains of which there are some
468 basic examples included in the OpenEmbedded Core (<filename>meta</filename>).
469 You can use your own custom toolchain definition in your own layer
470 (or as defined in the <filename>local.conf</filename> file) at the location
471 <filename>conf/distro/include/tcmode-*.inc</filename>.
472 </para>
885 473
886 <para> 474 <para>
887 If kernel images are being built with "-dirty" on the end of the version 475 In addition to the toolchain configuration, you also need a corresponding toolchain recipe file.
888 string, this simply means that modifications in the source 476 This recipe file needs to package up any pre-built objects in the toolchain such as
889 directory have not been committed. 477 <filename>libgcc</filename>, <filename>libstdcc++</filename>,
478 any locales, and <filename>libc</filename>.
479 An example is the <filename>external-sourcery-toolchain.bb</filename>, which is located
480 in <filename>meta/recipes-core/meta/</filename> within the source directory.
481 </para>
482 </answer>
483 </qandaentry>
484
485 <qandaentry>
486 <question>
487 <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>
488 How does the OpenEmbedded build system obtain source code and will it work behind my
489 firewall or proxy server?
490 </para>
491 </question>
492 <answer>
493 <para>
494 The way the build system obtains source code is highly configurable.
495 You can setup the build system to get source code in most environments if
496 HTTP transport is available.
497 </para>
498 <para>
499 When the build system searches for source code, it first tries the local download directory.
500 If that location fails, Poky tries PREMIRRORS, the upstream source,
501 and then MIRRORS in that order.
502 </para>
503 <para>
504 By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS
505 for SCM-based sources,
506 upstreams for normal tarballs, and then falls back to a number of other mirrors
507 including the Yocto Project source mirror if those fail.
508 </para>
509 <para>
510 As an example, you could add a specific server for Poky to attempt before any
511 others by adding something like the following to the <filename>local.conf</filename>
512 configuration file:
890 <literallayout class='monospaced'> 513 <literallayout class='monospaced'>
891 $ git status 514 PREMIRRORS_prepend = "\
515 git://.*/.* http://www.yoctoproject.org/sources/ \n \
516 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
517 http://.*/.* http://www.yoctoproject.org/sources/ \n \
518 https://.*/.* http://www.yoctoproject.org/sources/ \n"
892 </literallayout> 519 </literallayout>
893 </para> 520 </para>
894
895 <para> 521 <para>
896 You can use the above Git command to report modified, removed, or added files. 522 These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS
897 You should commit those changes to the tree regardless of whether they will be saved, 523 requests and direct them to the <filename>http://</filename> sources mirror.
898 exported, or used. 524 You can use <filename>file://</filename> URLs to point to local directories
899 Once you commit the changes you need to rebuild the kernel. 525 or network shares as well.
900 </para> 526 </para>
901
902 <para> 527 <para>
903 To brute force pickup and commit all such pending changes, enter the following: 528 Aside from the previous technique, these options also exist:
904 <literallayout class='monospaced'> 529 <literallayout class='monospaced'>
905 $ git add . 530 BB_NO_NETWORK = "1"
906 $ git commit -s -a -m "getting rid of -dirty"
907 </literallayout> 531 </literallayout>
532 This statement tells BitBake to throw an error instead of trying to access the
533 Internet.
534 This technique is useful if you want to ensure code builds only from local sources.
535 </para>
536 <para>
537 Here is another technique:
538 <literallayout class='monospaced'>
539 BB_FETCH_PREMIRRORONLY = "1"
540 </literallayout>
541 This statement limits Poky to pulling source from the PREMIRRORS only.
542 Again, this technique is useful for reproducing builds.
543 </para>
544 <para>
545 Here is another technique:
546 <literallayout class='monospaced'>
547 BB_GENERATE_MIRROR_TARBALLS = "1"
548 </literallayout>
549 This statement tells Poky to generate mirror tarballs.
550 This technique is useful if you want to create a mirror server.
551 If not, however, the technique can simply waste time during the build.
552 </para>
553 <para>
554 Finally, consider an example where you are behind an HTTP-only firewall.
555 You could make the following changes to the <filename>local.conf</filename>
556 configuration file as long as the PREMIRROR server is up to date:
557 <literallayout class='monospaced'>
558 PREMIRRORS_prepend = "\
559 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
560 http://.*/.* http://www.yoctoproject.org/sources/ \n \
561 https://.*/.* http://www.yoctoproject.org/sources/ \n"
562 BB_FETCH_PREMIRRORONLY = "1"
563 </literallayout>
564 These changes would cause Poky to successfully fetch source over HTTP and
565 any network accesses to anything other than the PREMIRROR would fail.
566 </para>
567 <para>
568 The build system also honors the standard shell environment variables
569 <filename>http_proxy</filename>, <filename>ftp_proxy</filename>,
570 <filename>https_proxy</filename>, and <filename>all_proxy</filename>
571 to redirect requests through proxy servers.
572 </para>
573 </answer>
574 </qandaentry>
575
576 <qandaentry>
577 <question>
578 <para>
579 Can I get rid of build output so I can start over?
580 </para>
581 </question>
582 <answer>
583 <para>
584 Yes - you can easily do this.
585 When you use BitBake to build an image, all the build output goes into the
586 directory created when you source the <filename>oe-init-build-env</filename>
587 setup file.
588 By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>
589 is named <filename>build</filename> but can be named
590 anything you want.
908 </para> 591 </para>
909 592
910 <para> 593 <para>
911 Next, rebuild the kernel. 594 Within the build directory is the <filename>tmp</filename> directory.
595 To remove all the build output yet preserve any source code or downloaded files
596 from previous builds, simply remove the <filename>tmp</filename> directory.
912 </para> 597 </para>
913 </section> 598 </answer>
914 </section> 599 </qandaentry>
600
601
602</qandaset>
915</chapter> 603</chapter>
916<!-- 604<!--
917vim: expandtab tw=80 ts=4 605vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-11-20 17:47:25 +0000