summaryrefslogtreecommitdiffstats
path: root/documentation/sdk-manual/sdk-appendix-obtain.xml
blob: 0bb5dd2497c605169de086332b447379b1b5f9c0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

<appendix id='sdk-appendix-obtain'>

<title>Obtaining the SDK</title>

<section id='sdk-locating-pre-built-sdk-installers'>
    <title>Locating Pre-Built SDK Installers</title>

    <para>
        You can use existing, pre-built toolchains by locating and running
        an SDK installer script that ships with the Yocto Project.
        Using this method, you select and download an architecture-specific
        SDK installer and then run the script to hand-install the
        toolchain.
    </para>

    <para>
        Follow these steps to locate and hand-install the toolchain:
        <orderedlist>
            <listitem><para>
                <emphasis>Go to the Installers Directory:</emphasis>
                Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
                </para></listitem>
            <listitem><para>
                <emphasis>Open the Folder for Your Development System:</emphasis>
                Open the folder that matches your host development system
                (i.e. <filename>i686</filename> for 32-bit machines or
                <filename>x86_64</filename> for 64-bit machines).
                </para></listitem>
            <listitem><para>
                <emphasis>Locate and Download the SDK Installer:</emphasis>
                You need to find and download the installer appropriate for
                your development system, target hardware, and image type.
                </para>

                <para>The installer files (<filename>*.sh</filename>) follow
                this naming convention:
                <literallayout class='monospaced'>
     poky-eglibc-<replaceable>host_system</replaceable>-core-image-<replaceable>type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release</replaceable>.sh

     Where:
         <replaceable>host_system</replaceable> is a string representing your development system:
                i686 or x86_64.

         <replaceable>type</replaceable> is a string representing either a "sato" or "minimal"
                image.

         <replaceable>arch</replaceable> is a string representing the target architecture:
                aarch64, armv5e, core2-64, coretexa8hf-neon, i586, mips3242,
                mips64, or ppc7400.

         <replaceable>release</replaceable> is the version of Yocto Project.

         NOTE:
            The standard SDK installer does not have the "-ext" string as
            part of the filename.

                </literallayout>
                The toolchains provided by the Yocto Project are based off of
                the <filename>core-image-sato</filename> and
                <filename>core-image-minimal</filename> images and contain
                libraries appropriate for developing against those images.
                </para>

                <para>For example, if your host development system is a
                64-bit x86 system and you are need an extended SDK for a
                64-bit core2 target, go into the <filename>x86_64</filename>
                folder and download the following installer:
                <literallayout class='monospaced'>
     poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
                </literallayout>
                </para></listitem>
            <listitem><para>
                <emphasis>Run the Installer:</emphasis>
                Be sure you have execution privileges and run the installer.
                Following is an example from the <filename>Downloads</filename>
                directory:
                <literallayout class='monospaced'>
     $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
                </literallayout>
                During execution of the script, you choose the root location
                for the toolchain.
                See the
                "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
                section and the
                "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>"
                section for more information.
                </para></listitem>
        </orderedlist>
    </para>
</section>

<section id='sdk-building-an-sdk-installer'>
    <title>Building an SDK Installer</title>

    <para>
        As an alternative to locating and downloading a SDK installer,
        you can build the SDK installer.
        Follow these steps:
        <orderedlist>
            <listitem><para>
                <emphasis>Set Up the Build Environment:</emphasis>
                Be sure you are set up to use BitBake in a shell.
                See the
                "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
                section in the Yocto Project Quick Start for steps that
                show you how to set up the Yocto Project environment.
                </para></listitem>
            <listitem><para>
                <emphasis>Make Sure You Are Building an Installer for the Correct Machine:</emphasis>
                Check to be sure that your
                <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
                variable in the <filename>local.conf</filename> file in your
                <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
                matches the architecture for which you are building.
                </para></listitem>
            <listitem><para>
                <emphasis>Make Sure Your SDK Machine is Correctly Set:</emphasis>
                If you are building a toolchain designed to run on an
                architecture that differs from your current development host
                machine (i.e. the build machine), be sure that the
                <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
                variable in the <filename>local.conf</filename> file in your
                Build Directory is correctly set.
                </para></listitem>
            <listitem><para>
                <emphasis>Build the SDK Installer:</emphasis>
                To build the SDK installer for a standard SDK and populate
                the SDK image, use the following command form.
                Be sure to replace <replaceable>image</replaceable> with
                an image (e.g. "core-image-sato"):
                <literallayout class='monospaced'>
     $ bitbake <replaceable>image</replaceable> -c populate_sdk
                </literallayout>
                You can do the same for the extensible SDK using this command
                form:
                <literallayout class='monospaced'>
     $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext
                </literallayout>
                These commands result in a SDK installer that contains the
                sysroot that matches your target root filesystem.</para>

                <para>When the <filename>bitbake</filename> command completes,
                the SDK installer will be in
                <filename>tmp/deploy/sdk</filename> in the Build Directory.
                <note><title>Notes</title>
                    <itemizedlist>
                        <listitem><para>
                            By default, this toolchain does not build static
                            binaries.
                            If you want to use the toolchain to build these
                            types of libraries, you need to be sure your SDK
                            has the appropriate static development libraries.
                            Use the
                            <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>
                            variable inside your <filename>local.conf</filename>
                            file to install the appropriate library packages
                            in the SDK.
                            Following is an example using
                            <filename>libc</filename> static development
                            libraries:
                            <literallayout class='monospaced'>
     TOOLCHAIN_TARGET_TASK_append = " libc-staticdev"
                            </literallayout>
                            </para></listitem>
                        <listitem><para>
                            For additional information on building the
                            installer, see the
                            <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
                            wiki page.
                            </para></listitem>
                    </itemizedlist>
                </note>
            </para></listitem>
            <listitem><para>
                <emphasis>Run the Installer:</emphasis>
                You can now run the SDK installer from
                <filename>tmp/deploy/sdk</filename> in the Build Directory.
                Following is an example:
                <literallayout class='monospaced'>
     $ cd ~/poky/build/tmp/deploy/sdk
     $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
                </literallayout>
                During execution of the script, you choose the root location
                for the toolchain.
                See the
                "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
                section and the
                "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>"
                section for more information.
                </para></listitem>
        </orderedlist>
    </para>
</section>

<section id='sdk-extracting-the-root-filesystem'>
    <title>Extracting the Root Filesystem</title>

    <para>
        After installing the toolchain, for some use cases you
        might need to separately extract a root filesystem:
        <itemizedlist>
            <listitem><para>
                You want to boot the image using NFS.
                </para></listitem>
            <listitem><para>
                You want to use the root filesystem as the
                target sysroot.
                For example, the Eclipse IDE environment with the Eclipse
                Yocto Plug-in installed allows you to use QEMU to boot
                under NFS.
                </para></listitem>
            <listitem><para>
                You want to develop your target application
                using the root filesystem as the target sysroot.
                </para></listitem>
        </itemizedlist>
    </para>

    <para>
        Follow these steps to extract the root filesystem:
        <orderedlist>
            <listitem><para>
                <emphasis>Locate and Download the Tarball for the Pre-Built
                Root Filesystem Image File:</emphasis>
                You need to find and download the root filesystem image
                file that is appropriate for your target system.
                These files are kept in the
                <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/machines/'>Index of Releases</ulink>
                in the "machines" directory.</para>

                <para>The "machines" directory contains tarballs
                (<filename>*.tar.bz2</filename>) for supported machines.
                The directory also contains flattened root filesystem
                image files (<filename>*.ext4</filename>), which you can use
                with QEMU directly.</para>

                <para>The pre-built root filesystem image files
                follow these naming conventions:
                <literallayout class='monospaced'>
     core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>.tar.bz2

     Where:
         <replaceable>profile</replaceable> is the filesystem image's profile:
                   lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato,
                   sato-dev, sato-sdk, minimal-initramfs, or sdk-ptest. For
                   information on these types of image profiles, see the
                   "Images" chapter in the Yocto Project Reference Manual.

         <replaceable>arch</replaceable> is a string representing the target architecture:
                beaglebone, edgerouter, genericx86, genericx86-64, mpc8315e-rdb,
                qemuarm, qemuarm64, qemumips, qemumips64, qemuppc, qemux86, or
                qemux86-64.

                </literallayout>
                The root filesystems provided by the Yocto Project are based
                off of the <filename>core-image-sato</filename> and
                <filename>core-image-minimal</filename> images.
                </para>

                <para>For example, if your target hardware system is a
                BeagleBone board and your image is a
                <filename>core-image-minimal</filename> image, you need
                to download the following root filesystem image file:
                <literallayout class='monospaced'>
     core-image-minimal-beaglebone.tar.bz2
                </literallayout>
                </para></listitem>
            <listitem><para>
                <emphasis>Initialize the Cross-Development Environment:</emphasis>
                You must <filename>source</filename>
                the cross-development environment setup script to establish
                necessary environment variables.</para>

                <para>This script is located in the top-level directory in
                which you installed the toolchain (e.g.
                <filename>poky_sdk</filename>).</para>

                <para>Following is an example for the Core2 64-bit
                architecture:
                <literallayout class='monospaced'>
     $ source ~/poky_sdk/environment-setup-core2-64-poky-linux
                </literallayout>
                </para></listitem>
            <listitem><para>
                <emphasis>Extract the Root Filesystem:</emphasis>
                Use the <filename>runqemu-extract-sdk</filename> command
                and provide the root filesystem image.</para>

                <para>Following is an example command that extracts the root
                filesystem from a previously built root filesystem image that
                was downloaded from the
                <ulink url='&YOCTO_DOCS_REF_URL;#index-downloads'>Index of Releases</ulink>.
                This command extracts the root filesystem into the
                <filename>core2-64-sato</filename> directory:
                <literallayout class='monospaced'>
     $ runqemu-extract-sdk ~/Downloads/core-image-sato-core2-64.tar.bz2 ~/core2-64-sato
                </literallayout>
                You could now point to the target sysroot at
                <filename>core2-64-sato</filename>.
                </para></listitem>
        </orderedlist>
    </para>
</section>

<section id='sdk-installed-standard-sdk-directory-structure'>
    <title>Installed Standard SDK Directory Structure</title>

    <para>
        The following figure shows the resulting directory structure after
        you install the Standard SDK by running the <filename>*.sh</filename>
        SDK installation script:
    </para>

    <para>
        <imagedata fileref="figures/sdk-installed-standard-sdk-directory.png" scale="60" align="center" />
    </para>

    <para>
        The installed SDK consists of an environment setup script for the SDK,
        a configuration file for the target, a version file for the target,
        and the root filesystem (<filename>sysroots</filename>) needed to
        develop objects for the target system.
    </para>

    <para>
        Within the figure, italicized text is used to indicate replaceable
        portions of the file or directory name.
        For example,
        <replaceable>install_dir</replaceable>/<replaceable>version</replaceable>
        is the directory where the SDK is installed.
        By default, this directory is <filename>/opt/poky/</filename>.
        And, <replaceable>version</replaceable> represents the specific
        snapshot of the SDK (e.g. <filename>&DISTRO;</filename>).
        Furthermore, <replaceable>target</replaceable> represents the target
        architecture (e.g. <filename>i586</filename>) and
        <replaceable>host</replaceable> represents the development system's
        architecture (e.g. <filename>x86_64</filename>).
        Thus, the complete names of the two directories within the
        <filename>sysroots</filename> could be
        <filename>i586-poky-linux</filename> and
        <filename>x86_64-pokysdk-linux</filename> for the target and host,
        respectively.
    </para>
</section>

<section id='sdk-installed-extensible-sdk-directory-structure'>
    <title>Installed Extensible SDK Directory Structure</title>

    <para>
        The following figure shows the resulting directory structure after
        you install the Extensible SDK by running the <filename>*.sh</filename>
        SDK installation script:
    </para>

    <para>
        <imagedata fileref="figures/sdk-installed-extensible-sdk-directory.png" scale="60" align="center" />
    </para>

    <para>
        The installed directory structure for the extensible SDK is quite
        different than the installed structure for the standard SDK.
        The extensible SDK does not separate host and target parts in the
        same manner as does the standard SDK.
        The extensible SDK uses an embedded copy of the OpenEmbedded
        build system, which has its own sysroots.
    </para>

    <para>
        Of note in the directory structure are an environment setup script
        for the SDK, a configuration file for the target, a version file for
        the target, and a log file for the OpenEmbedded build system
        preparation script run by the installer.
    </para>

    <para>
        Within the figure, italicized text is used to indicate replaceable
        portions of the file or directory name.
        For example,
        <replaceable>install_dir</replaceable> is the directory where the SDK
        is installed, which is <filename>poky_sdk</filename> by default.
        <replaceable>target</replaceable> represents the target
        architecture (e.g. <filename>i586</filename>) and
        <replaceable>host</replaceable> represents the development system's
        architecture (e.g. <filename>x86_64</filename>).
    </para>
</section>

</appendix>
<!--
vim: expandtab tw=80 ts=4
-->