diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-intro.xml')
-rw-r--r-- | documentation/sdk-manual/sdk-intro.xml | 353 |
1 files changed, 0 insertions, 353 deletions
diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml deleted file mode 100644 index f42670ea6e..0000000000 --- a/documentation/sdk-manual/sdk-intro.xml +++ /dev/null | |||
@@ -1,353 +0,0 @@ | |||
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 | <!--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 | <!-- | ||
352 | vim: expandtab tw=80 ts=4 | ||
353 | --> | ||