blob: f42670ea6edd777c5c1195063413fae2c73aeca5 [file] [log] [blame]
Andrew Geissler4873add2020-11-02 18:44:49 -06001<!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<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='sdk-intro'>
7<title>Introduction</title>
8
9<section id='sdk-manual-intro'>
10 <title>Introduction</title>
11
12 <para>
13 Welcome to the Yocto Project Application Development and the
14 Extensible Software Development Kit (eSDK) manual.
15 This manual provides information that explains how to use both the
16 Yocto Project extensible and standard SDKs to develop
17 applications and images.
18 <note>
19 Prior to the 2.0 Release of the Yocto Project, application
20 development was primarily accomplished through the use of the
21 Application Development Toolkit (ADT) and the availability
22 of stand-alone cross-development toolchains and other tools.
23 With the 2.1 Release of the Yocto Project, application development
24 has transitioned to within a tool-rich extensible SDK and the more
25 traditional standard SDK.
26 </note>
27 </para>
28
29 <para>
30 All SDKs consist of the following:
31 <itemizedlist>
32 <listitem><para>
33 <emphasis>Cross-Development Toolchain</emphasis>:
34 This toolchain contains a compiler, debugger, and various
35 miscellaneous tools.
36 </para></listitem>
37 <listitem><para>
38 <emphasis>Libraries, Headers, and Symbols</emphasis>:
39 The libraries, headers, and symbols are specific to the image
40 (i.e. they match the image).
41 </para></listitem>
42 <listitem><para>
43 <emphasis>Environment Setup Script</emphasis>:
44 This <filename>*.sh</filename> file, once run, sets up the
45 cross-development environment by defining variables and
46 preparing for SDK use.
47 </para></listitem>
48 </itemizedlist>
49 </para>
50
51 <para>
52 Additionally, an extensible SDK has tools that allow you to easily add
53 new applications and libraries to an image, modify the source of an
54 existing component, test changes on the target hardware, and easily
55 integrate an application into the
56 <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
57 </para>
58
59 <para>
60 You can use an SDK to independently develop and test code
61 that is destined to run on some target machine.
62 SDKs are completely self-contained.
63 The binaries are linked against their own copy of
64 <filename>libc</filename>, which results in no dependencies
65 on the target system.
66 To achieve this, the pointer to the dynamic loader is
67 configured at install time since that path cannot be dynamically
68 altered.
69 This is the reason for a wrapper around the
70 <filename>populate_sdk</filename> and
71 <filename>populate_sdk_ext</filename> archives.
72 </para>
73
74 <para>
75 Another feature for the SDKs is that only one set of cross-compiler
76 toolchain binaries are produced for any given architecture.
77 This feature takes advantage of the fact that the target hardware can
78 be passed to <filename>gcc</filename> as a set of compiler options.
79 Those options are set up by the environment script and contained in
80 variables such as
81 <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
82 and
83 <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>.
84 This reduces the space needed for the tools.
85 Understand, however, that every target still needs a sysroot because
86 those binaries are target-specific.
87 </para>
88
89 <para>
90 The SDK development environment consists of the following:
91 <itemizedlist>
92 <listitem><para>
93 The self-contained SDK, which is an
94 architecture-specific cross-toolchain and
95 matching sysroots (target and native) all built by the
96 OpenEmbedded build system (e.g. the SDK).
97 The toolchain and sysroots are based on a
98 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
99 configuration and extensions,
100 which allows you to cross-develop on the host machine for the
101 target hardware.
102 Additionally, the extensible SDK contains the
103 <filename>devtool</filename> functionality.
104 </para></listitem>
105 <listitem><para>
106 The Quick EMUlator (QEMU), which lets you simulate
107 target hardware.
108 QEMU is not literally part of the SDK.
109 You must build and include this emulator separately.
110 However, QEMU plays an important role in the development
111 process that revolves around use of the SDK.
112 </para></listitem>
113 </itemizedlist>
114 </para>
115
116 <para>
117 In summary, the extensible and standard SDK share many features.
118 However, the extensible SDK has powerful development tools to help you
119 more quickly develop applications.
120 Following is a table that summarizes the primary differences between
121 the standard and extensible SDK types when considering which to
122 build:
123 <informaltable frame='none'>
124 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
125 <colspec colname='c1' colwidth='1*'/>
126 <colspec colname='c2' colwidth='1*'/>
127 <colspec colname='c3' colwidth='1*'/>
128 <thead>
129 <row>
130 <entry align="left"><emphasis>Feature</emphasis></entry>
131 <entry align="left"><emphasis>Standard SDK</emphasis></entry>
132 <entry align="left"><emphasis>Extensible SDK</emphasis></entry>
133 </row>
134 </thead>
135 <tbody>
136 <row>
137 <entry align="left">Toolchain</entry>
138 <entry align="left">Yes</entry>
139 <entry align="left">Yes*</entry>
140 </row>
141 <row>
142 <entry align="left">Debugger</entry>
143 <entry align="left">Yes</entry>
144 <entry align="left">Yes*</entry>
145 </row>
146 <row>
147 <entry align="left">Size</entry>
148 <entry align="left">100+ MBytes</entry>
149 <entry align="left">1+ GBytes (or 300+ MBytes for minimal w/toolchain)</entry>
150 </row>
151 <row>
152 <entry align="left"><filename>devtool</filename></entry>
153 <entry align="left">No</entry>
154 <entry align="left">Yes</entry>
155 </row>
156 <row>
157 <entry align="left">Build Images</entry>
158 <entry align="left">No</entry>
159 <entry align="left">Yes</entry>
160 </row>
161 <row>
162 <entry align="left">Updateable</entry>
163 <entry align="left">No</entry>
164 <entry align="left">Yes</entry>
165 </row>
166 <row>
167 <entry align="left">Managed Sysroot**</entry>
168 <entry align="left">No</entry>
169 <entry align="left">Yes</entry>
170 </row>
171 <row>
172 <entry align="left">Installed Packages</entry>
173 <entry align="left">No***</entry>
174 <entry align="left">Yes****</entry>
175 </row>
176 <row>
177 <entry align="left">Construction</entry>
178 <entry align="left">Packages</entry>
179 <entry align="left">Shared State</entry>
180 </row>
181 </tbody>
182 </tgroup>
183 </informaltable>
184 <literallayout class='monospaced'>
185 * Extensible SDK contains the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default.
186
187 ** Sysroot is managed through the use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries.
188
189 *** You can add runtime package management to the standard SDK but it is not supported by default.
190
191 **** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install.
192 </literallayout>
193 </para>
194
195 <section id='the-cross-development-toolchain'>
196 <title>The Cross-Development Toolchain</title>
197
198 <para>
199 The
200 <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink>
201 consists of a cross-compiler, cross-linker, and cross-debugger
202 that are used to develop user-space applications for targeted
203 hardware.
204 Additionally, for an extensible SDK, the toolchain also has
205 built-in <filename>devtool</filename> functionality.
206 This toolchain is created by running a SDK installer script
207 or through a
208 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
209 that is based on your metadata configuration or extension for
210 your targeted device.
211 The cross-toolchain works with a matching target sysroot.
212 </para>
213 </section>
214
215 <section id='sysroot'>
216 <title>Sysroots</title>
217
218 <para>
219 The native and target sysroots contain needed headers and libraries
220 for generating binaries that run on the target architecture.
221 The target sysroot is based on the target root filesystem image
222 that is built by the OpenEmbedded build system and uses the same
223 metadata configuration used to build the cross-toolchain.
224 </para>
225 </section>
226
227 <section id='the-qemu-emulator'>
228 <title>The QEMU Emulator</title>
229
230 <para>
231 The QEMU emulator allows you to simulate your hardware while
232 running your application or image.
233 QEMU is not part of the SDK but is made available a number of
234 different ways:
235 <itemizedlist>
236 <listitem><para>
237 If you have cloned the <filename>poky</filename> Git
238 repository to create a
239 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
240 and you have sourced the environment setup script, QEMU is
241 installed and automatically available.
242 </para></listitem>
243 <listitem><para>
244 If you have downloaded a Yocto Project release and unpacked
245 it to create a Source Directory and you have sourced the
246 environment setup script, QEMU is installed and
247 automatically available.
248 </para></listitem>
249 <listitem><para>
250 If you have installed the cross-toolchain tarball and you
251 have sourced the toolchain's setup environment script, QEMU
252 is also installed and automatically available.
253 </para></listitem>
254 </itemizedlist>
255 </para>
256 </section>
257</section>
258
259<section id='sdk-development-model'>
260 <title>SDK Development Model</title>
261
262 <para>
263 Fundamentally, the SDK fits into the development process as follows:
264 <imagedata fileref="figures/sdk-environment.png" align="center" width="6in" depth="5in" scalefit="100" />
265 The SDK is installed on any machine and can be used to develop
266 applications, images, and kernels.
267 An SDK can even be used by a QA Engineer or Release Engineer.
268 The fundamental concept is that the machine that has the SDK installed
269 does not have to be associated with the machine that has the
270 Yocto Project installed.
271 A developer can independently compile and test an object on their
272 machine and then, when the object is ready for integration into an
273 image, they can simply make it available to the machine that has the
274 Yocto Project.
275 Once the object is available, the image can be rebuilt using the
276 Yocto Project to produce the modified image.
277 </para>
278
279 <para>
280 You just need to follow these general steps:
281 <orderedlist>
282 <listitem><para>
283 <emphasis>Install the SDK for your target hardware:</emphasis>
284 For information on how to install the SDK, see the
285 "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
286 section.
287 </para></listitem>
288 <listitem><para>
289 <emphasis>Download or Build the Target Image:</emphasis>
290 The Yocto Project supports several target architectures
291 and has many pre-built kernel images and root filesystem
292 images.</para>
293
294 <para>If you are going to develop your application on
295 hardware, go to the
296 <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
297 download area and choose a target machine area
298 from which to download the kernel image and root filesystem.
299 This download area could have several files in it that
300 support development using actual hardware.
301 For example, the area might contain
302 <filename>.hddimg</filename> files that combine the
303 kernel image with the filesystem, boot loaders, and
304 so forth.
305 Be sure to get the files you need for your particular
306 development process.</para>
307
308 <para>If you are going to develop your application and
309 then run and test it using the QEMU emulator, go to the
310 <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink>
311 download area.
312 From this area, go down into the directory for your
313 target architecture (e.g. <filename>qemux86_64</filename>
314 for an <trademark class='registered'>Intel</trademark>-based
315 64-bit architecture).
316 Download the kernel, root filesystem, and any other files you
317 need for your process.
318 <note>
319 To use the root filesystem in QEMU, you need to extract it.
320 See the
321 "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
322 section for information on how to extract the root
323 filesystem.
324 </note>
325 </para></listitem>
326 <listitem><para>
327 <emphasis>Develop and Test your Application:</emphasis>
328 At this point, you have the tools to develop your application.
329 If you need to separately install and use the QEMU emulator,
330 you can go to
331 <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink>
332 to download and learn about the emulator.
333 See the
334 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
335 chapter in the Yocto Project Development Tasks Manual
336 for information on using QEMU within the Yocto
337 Project.
338 </para></listitem>
339 </orderedlist>
340 </para>
341
342 <para>
343 The remainder of this manual describes how to use the extensible
344 and standard SDKs.
345 Information also exists in appendix form that describes how you can
346 build, install, and modify an SDK.
347 </para>
348</section>
349
350</chapter>
351<!--
352vim: expandtab tw=80 ts=4
353-->