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