summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-start.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-start.xml')
-rw-r--r--documentation/dev-manual/dev-manual-start.xml445
1 files changed, 445 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
new file mode 100644
index 0000000..c1d89bc
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -0,0 +1,445 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='dev-manual-start'>
6
7<title>Getting Started with the Yocto Project</title>
8
9<para>
10 This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
11 You can find enough information to set up your development host and build or use images for
12 hardware supported by the Yocto Project by reading the
13 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
14</para>
15
16<para>
17 The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
18 some higher-level concepts you might want to consider.
19</para>
20
21<section id='introducing-the-yocto-project'>
22 <title>Introducing the Yocto Project</title>
23
24 <para>
25 The Yocto Project is an open-source collaboration project focused on embedded Linux development.
26 The project currently provides a build system that is
27 referred to as the OpenEmbedded build system in the Yocto Project documentation.
28 The Yocto Project provides various ancillary tools for the embedded developer
29 and also features the Sato reference User Interface, which is optimized for
30 stylus driven, low-resolution screens.
31 </para>
32
33 <para>
34 You can use the OpenEmbedded build system, which uses
35 BitBake, to develop complete Linux
36 images and associated user-space applications for architectures based
37 on ARM, MIPS, PowerPC, x86 and x86-64.
38 <note>
39 By default, using the Yocto Project creates a Poky distribution.
40 However, you can create your own distribution by providing key
41 <link linkend='metadata'>Metadata</link>.
42 See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
43 section for more information.
44 </note>
45 While the Yocto Project does not provide a strict testing framework,
46 it does provide or generate for you artifacts that let you perform target-level and
47 emulated testing and debugging.
48 Additionally, if you are an <trademark class='trade'>Eclipse</trademark>
49 IDE user, you can install an Eclipse Yocto Plug-in to allow you to
50 develop within that familiar environment.
51 </para>
52</section>
53
54<section id='getting-setup'>
55 <title>Getting Set Up</title>
56
57 <para>
58 Here is what you need to use the Yocto Project:
59 <itemizedlist>
60 <listitem><para><emphasis>Host System:</emphasis>
61 You should have a reasonably current Linux-based host system.
62 You will have the best results with a recent release of Fedora,
63 openSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
64 and officially supported.
65 For a list of the distributions under validation and their status, see the
66 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
67 in the Yocto Project Reference Manual and the wiki page at
68 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para>
69 <para>
70 You should also have about 100 gigabytes of free disk space for building images.
71 </para></listitem>
72 <listitem><para><emphasis>Packages:</emphasis>
73 The OpenEmbedded build system requires that certain packages
74 exist on your development system (e.g. Python 2.6 or 2.7).
75 See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
76 section in the Yocto Project Quick Start and the
77 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
78 section in the Yocto Project Reference Manual for the exact
79 package requirements and the installation commands to install
80 them for the supported distributions.</para></listitem>
81 <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
82 You need a release of the Yocto Project installed locally on
83 your development system.
84 This local area is referred to as the
85 <link linkend='source-directory'>Source Directory</link>
86 and is created when you use
87 <link linkend='git'>Git</link> to clone a local copy
88 of the upstream <filename>poky</filename> repository,
89 or when you download an official release of the corresponding
90 tarball.</para>
91 <para>Working from a copy of the upstream repository allows you
92 to contribute back into the Yocto Project or simply work with
93 the latest software on a development branch.
94 Because Git maintains and creates an upstream repository with
95 a complete history of changes and you are working with a local
96 clone of that repository, you have access to all the Yocto
97 Project development branches and tag names used in the upstream
98 repository.
99 <note>You can view the Yocto Project Source Repositories at
100 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>
101 </note>
102 <itemizedlist>
103 <listitem><para><emphasis>Tarball Extraction:</emphasis>
104 If you are not going to contribute back into the Yocto
105 Project, you can simply go to the
106 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>,
107 select the "Downloads" tab, and choose what you want.
108 Once you have the tarball, just extract it into a
109 directory of your choice.</para>
110 <para>For example, the following command extracts the
111 Yocto Project &DISTRO; release tarball
112 into the current working directory and sets up the local
113 Source Directory
114 with a top-level folder named
115 <filename>&YOCTO_POKY;</filename>:
116 <literallayout class='monospaced'>
117 $ tar xfj &YOCTO_POKY_TARBALL;
118 </literallayout></para>
119 <para>This method does not produce a local Git
120 repository.
121 Instead, you simply end up with a snapshot of the
122 release.</para></listitem>
123 <listitem><para><emphasis>Git Repository Method:</emphasis>
124 If you are going to be contributing back into the Yocto
125 Project or you simply want to keep up with the latest
126 developments, you should use Git commands to set up a
127 local Git repository of the upstream
128 <filename>poky</filename> source repository.
129 Doing so creates a repository with a complete history
130 of changes and allows you to easily submit your changes
131 upstream to the project.
132 Because you clone the repository, you have access to all
133 the Yocto Project development branches and tag names
134 used in the upstream repository.
135 <note>You can view the Yocto Project Source Repositories
136 at
137 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>
138 </note></para>
139 <para>The following transcript shows how to clone the
140 <filename>poky</filename> Git repository into the
141 current working directory.
142 The command creates the local repository in a directory
143 named <filename>poky</filename>.
144 For information on Git used within the Yocto Project,
145 see the
146 "<link linkend='git'>Git</link>" section.
147 <literallayout class='monospaced'>
148 $ git clone git://git.yoctoproject.org/poky
149 Cloning into 'poky'...
150 remote: Counting objects: 203728, done.
151 remote: Compressing objects: 100% (52371/52371), done.
152 remote: Total 203728 (delta 147444), reused 202891 (delta 146614)
153 Receiving objects: 100% (203728/203728), 95.54 MiB | 308 KiB/s, done.
154 Resolving deltas: 100% (147444/147444), done.
155 </literallayout>
156 For another example of how to set up your own local
157 Git repositories, see this
158 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>wiki page</ulink>,
159 which describes how to create both
160 <filename>poky</filename> and
161 <filename>meta-intel</filename> Git repositories.
162 </para></listitem>
163 </itemizedlist></para></listitem>
164 <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
165 If you are going to be making modifications to a supported Yocto Project kernel, you
166 need to establish local copies of the source.
167 You can find Git repositories of supported Yocto Project kernels organized under
168 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
169 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
170 <para>This setup can involve creating a bare clone of the Yocto Project kernel and then
171 copying that cloned repository.
172 You can create the bare clone and the copy of the bare clone anywhere you like.
173 For simplicity, it is recommended that you create these structures outside of the
174 Source Directory (usually <filename>poky</filename>).</para>
175 <para>As an example, the following transcript shows how to create the bare clone
176 of the <filename>linux-yocto-3.10</filename> kernel and then create a copy of
177 that clone.
178 <note>When you have a local Yocto Project kernel Git repository, you can
179 reference that repository rather than the upstream Git repository as
180 part of the <filename>clone</filename> command.
181 Doing so can speed up the process.</note></para>
182 <para>In the following example, the bare clone is named
183 <filename>linux-yocto-3.10.git</filename>, while the
184 copy is named <filename>my-linux-yocto-3.10-work</filename>:
185 <literallayout class='monospaced'>
186 $ git clone &dash;&dash;bare git://git.yoctoproject.org/linux-yocto-3.10 linux-yocto-3.10.git
187 Cloning into bare repository 'linux-yocto-3.10.git'...
188 remote: Counting objects: 3364487, done.
189 remote: Compressing objects: 100% (507178/507178), done.
190 remote: Total 3364487 (delta 2827715), reused 3364481 (delta 2827709)
191 Receiving objects: 100% (3364487/3364487), 722.95 MiB | 423 KiB/s, done.
192 Resolving deltas: 100% (2827715/2827715), done.
193 </literallayout></para>
194 <para>Now create a clone of the bare clone just created:
195 <literallayout class='monospaced'>
196 $ git clone linux-yocto-3.10.git my-linux-yocto-3.10-work
197 Cloning into 'my-linux-yocto-3.10-work'...
198 done.
199 </literallayout></para></listitem>
200 <listitem id='meta-yocto-kernel-extras-repo'><para><emphasis>
201 The <filename>meta-yocto-kernel-extras</filename> Git Repository</emphasis>:
202 The <filename>meta-yocto-kernel-extras</filename> Git repository contains Metadata needed
203 only if you are modifying and building the kernel image.
204 In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>)
205 files that you
206 edit to point to your locally modified kernel source files and to build the kernel
207 image.
208 Pointing to these local files is much more efficient than requiring a download of the
209 kernel's source files from upstream each time you make changes to the kernel.</para>
210 <para>You can find the <filename>meta-yocto-kernel-extras</filename> Git Repository in the
211 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
212 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
213 It is good practice to create this Git repository inside the Source Directory.</para>
214 <para>Following is an example that creates the <filename>meta-yocto-kernel-extras</filename> Git
215 repository inside the Source Directory, which is named <filename>poky</filename>
216 in this case:
217 <literallayout class='monospaced'>
218 $ cd ~/poky
219 $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
220 Cloning into 'meta-yocto-kernel-extras'...
221 remote: Counting objects: 727, done.
222 remote: Compressing objects: 100% (452/452), done.
223 remote: Total 727 (delta 260), reused 719 (delta 252)
224 Receiving objects: 100% (727/727), 536.36 KiB | 102 KiB/s, done.
225 Resolving deltas: 100% (260/260), done.
226 </literallayout></para></listitem>
227 <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board
228 Support Packages (BSPs):</emphasis>
229 The Yocto Project provides a layer called <filename>meta-intel</filename> and
230 it is maintained in its own separate Git repository.
231 The <filename>meta-intel</filename> layer contains many supported
232 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.</para>
233 <para>Similar considerations exist for setting up the <filename>meta-intel</filename>
234 layer.
235 You can get set up for BSP development one of two ways: tarball extraction or
236 with a local Git repository.
237 It is a good idea to use the same method that you used to set up the Source Directory.
238 Regardless of the method you use, the Yocto Project uses the following BSP layer
239 naming scheme:
240 <literallayout class='monospaced'>
241 meta-&lt;BSP_name&gt;
242 </literallayout>
243 where <filename>&lt;BSP_name&gt;</filename> is the recognized BSP name.
244 Here are some examples:
245 <literallayout class='monospaced'>
246 meta-crownbay
247 meta-emenlow
248 meta-n450
249 </literallayout>
250 See the
251 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
252 section in the Yocto Project Board Support Package (BSP)
253 Developer's Guide for more information on BSP Layers.
254 <itemizedlist>
255 <listitem><para><emphasis>Tarball Extraction:</emphasis>
256 You can download any released BSP tarball from the same
257 "Downloads" page of the Yocto Project
258 <ulink url='https://www.yoctoproject.org/downloads'>Website</ulink>
259 to get the Yocto Project release.
260 Once on the "Download" page, look to the right of the
261 page and scroll down to find the BSP tarballs.</para>
262 <para>Once you have the tarball, just extract it into a
263 directory of your choice.
264 Again, this method just produces a snapshot of the BSP
265 layer in the form of a hierarchical directory
266 structure.</para></listitem>
267 <listitem><para><emphasis>Git Repository Method:</emphasis>
268 If you are working with a local Git repository for your
269 Source Directory, you should also use this method to
270 set up the <filename>meta-intel</filename> Git
271 repository.
272 You can locate the <filename>meta-intel</filename> Git
273 repository in the "Yocto Metadata Layers" area of the
274 Yocto Project Source Repositories at
275 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
276 <para>Using
277 <link linkend='git'>Git</link> to create a local clone
278 of the upstream repository can be helpful if you are
279 working with BSPs.
280 Typically, you set up the
281 <filename>meta-intel</filename> Git repository inside
282 the Source Directory.
283 For example, the following transcript shows the steps
284 to clone <filename>meta-intel</filename>.
285 <literallayout class='monospaced'>
286 $ cd ~/poky
287 $ git clone git://git.yoctoproject.org/meta-intel.git
288 Cloning into 'meta-intel'...
289 remote: Counting objects: 7366, done.
290 remote: Compressing objects: 100% (2491/2491), done.
291 remote: Total 7366 (delta 3997), reused 7299 (delta 3930)
292 Receiving objects: 100% (7366/7366), 2.31 MiB | 95 KiB/s, done.
293 Resolving deltas: 100% (3997/3997), done.
294 </literallayout>
295 The same
296 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>wiki page</ulink>
297 referenced earlier covers how to
298 set up the <filename>meta-intel</filename> Git
299 repository.</para></listitem>
300 </itemizedlist></para></listitem>
301 <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing
302 applications using the Eclipse Integrated Development Environment (IDE),
303 you will need this plug-in.
304 See the
305 "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>"
306 section for more information.</para></listitem>
307 </itemizedlist>
308 </para>
309</section>
310
311<section id='building-images'>
312 <title>Building Images</title>
313
314 <para>
315 The build process creates an entire Linux distribution, including the toolchain, from source.
316 For more information on this topic, see the
317 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
318 section in the Yocto Project Quick Start.
319 </para>
320
321 <para>
322 The build process is as follows:
323 <orderedlist>
324 <listitem><para>Make sure you have set up the Source Directory described in the
325 previous section.</para></listitem>
326 <listitem><para>Initialize the build environment by sourcing a build environment
327 script.</para></listitem>
328 <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file,
329 which is found in the
330 <link linkend='build-directory'>Build Directory</link>,
331 is set up how you want it.
332 This file defines many aspects of the build environment including
333 the target machine architecture through the
334 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
335 the development machine's processor use through the
336 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and
337 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and
338 a centralized tarball download directory through the
339 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem>
340 <listitem><para>Build the image using the <filename>bitbake</filename> command.
341 If you want information on BitBake, see the user manual included in the
342 <filename>bitbake/doc/manual</filename> directory of the
343 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
344 <listitem><para>Run the image either on the actual hardware or using the QEMU
345 emulator.</para></listitem>
346 </orderedlist>
347 </para>
348</section>
349
350<section id='using-pre-built-binaries-and-qemu'>
351 <title>Using Pre-Built Binaries and QEMU</title>
352
353 <para>
354 Another option you have to get started is to use pre-built binaries.
355 The Yocto Project provides many types of binaries with each release.
356 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
357 chapter in the Yocto Project Reference Manual
358 for descriptions of the types of binaries that ship with a Yocto Project
359 release.
360 </para>
361
362 <para>
363 Using a pre-built binary is ideal for developing software applications to run on your
364 target hardware.
365 To do this, you need to be able to access the appropriate cross-toolchain tarball for
366 the architecture on which you are developing.
367 If you are using an SDK type image, the image ships with the complete toolchain native to
368 the architecture.
369 If you are not using an SDK type image, you need to separately download and
370 install the stand-alone Yocto Project cross-toolchain tarball.
371 </para>
372
373 <para>
374 Regardless of the type of image you are using, you need to download the pre-built kernel
375 that you will boot in the QEMU emulator and then download and extract the target root
376 filesystem for your target machine’s architecture.
377 You can get architecture-specific binaries and file systems from
378 <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>.
379 You can get installation scripts for stand-alone toolchains from
380 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>.
381 Once you have all your files, you set up the environment to emulate the hardware
382 by sourcing an environment setup script.
383 Finally, you start the QEMU emulator.
384 You can find details on all these steps in the
385 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
386 section of the Yocto Project Quick Start.
387 </para>
388
389 <para>
390 Using QEMU to emulate your hardware can result in speed issues
391 depending on the target and host architecture mix.
392 For example, using the <filename>qemux86</filename> image in the emulator
393 on an Intel-based 32-bit (x86) host machine is fast because the target and
394 host architectures match.
395 On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based
396 host can be slower.
397 But, you still achieve faithful emulation of ARM-specific issues.
398 </para>
399
400 <para>
401 To speed things up, the QEMU images support using <filename>distcc</filename>
402 to call a cross-compiler outside the emulated system.
403 If you used <filename>runqemu</filename> to start QEMU, and the
404 <filename>distccd</filename> application is present on the host system, any
405 BitBake cross-compiling toolchain available from the build system is automatically
406 used from within QEMU simply by calling <filename>distcc</filename>.
407 You can accomplish this by defining the cross-compiler variable
408 (e.g. <filename>export CC="distcc"</filename>).
409 Alternatively, if you are using a suitable SDK image or the appropriate
410 stand-alone toolchain is present,
411 the toolchain is also automatically used.
412 </para>
413
414 <note>
415 Several mechanisms exist that let you connect to the system running on the
416 QEMU emulator:
417 <itemizedlist>
418 <listitem><para>QEMU provides a framebuffer interface that makes standard
419 consoles available.</para></listitem>
420 <listitem><para>Generally, headless embedded devices have a serial port.
421 If so, you can configure the operating system of the running image
422 to use that port to run a console.
423 The connection uses standard IP networking.</para></listitem>
424 <listitem><para>SSH servers exist in some QEMU images.
425 The <filename>core-image-sato</filename> QEMU image has a Dropbear secure
426 shell (SSH) server that runs with the root password disabled.
427 The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images
428 have OpenSSH instead of Dropbear.
429 Including these SSH servers allow you to use standard <filename>ssh</filename> and
430 <filename>scp</filename> commands.
431 The <filename>core-image-minimal</filename> QEMU image, however, contains no SSH
432 server.</para></listitem>
433 <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session
434 using a local copy of the root filesystem on the host.
435 In order to make this connection, you must extract a root filesystem tarball by using the
436 <filename>runqemu-extract-sdk</filename> command.
437 After running the command, you must then point the <filename>runqemu</filename>
438 script to the extracted directory instead of a root filesystem image file.</para></listitem>
439 </itemizedlist>
440 </note>
441</section>
442</chapter>
443<!--
444vim: expandtab tw=80 ts=4
445-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-05-13 07:39:59 +0000