blob: fc6b8b9d5c2dd3ba985352605366ecf8f1443ddc [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3*****************
4Obtaining the SDK
5*****************
6
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007Locating Pre-Built SDK Installers
8=================================
9
10You can use existing, pre-built toolchains by locating and running an
11SDK installer script that ships with the Yocto Project. Using this
12method, you select and download an architecture-specific SDK installer
13and then run the script to hand-install the toolchain.
14
15Follow these steps to locate and hand-install the toolchain:
16
171. *Go to the Installers Directory:* Go to
Andrew Geissler09209ee2020-12-13 08:44:15 -060018 :yocto_dl:`/releases/yocto/yocto-&DISTRO;/toolchain/`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050019
202. *Open the Folder for Your Build Host:* Open the folder that matches
21 your :term:`Build Host` (i.e.
22 ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines).
23
243. *Locate and Download the SDK Installer:* You need to find and
25 download the installer appropriate for your build host, target
26 hardware, and image type.
27
Andrew Geisslerc926e172021-05-07 16:11:35 -050028 The installer files (``*.sh``) follow this naming convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050029
30 poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh
31
32 Where:
33 host_system is a string representing your development system:
34 "i686" or "x86_64"
35
36 type is a string representing the image:
37 "sato" or "minimal"
38
39 arch is a string representing the target architecture:
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050040 "aarch64", "armv5e", "core2-64", "cortexa8hf-neon", "i586", "mips32r2",
Andrew Geisslerc9f78652020-09-18 14:11:35 -050041 "mips64", or "ppc7400"
42
43 release is the version of Yocto Project.
44
45 NOTE:
46 The standard SDK installer does not have the "-ext" string as
47 part of the filename.
48
49
50 The toolchains provided by the Yocto
51 Project are based off of the ``core-image-sato`` and
52 ``core-image-minimal`` images and contain libraries appropriate for
53 developing against those images.
54
55 For example, if your build host is a 64-bit x86 system and you need
56 an extended SDK for a 64-bit core2 target, go into the ``x86_64``
Andrew Geisslerc926e172021-05-07 16:11:35 -050057 folder and download the following installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050058
Andrew Geisslerd1e89492021-02-12 15:35:20 -060059 poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
Andrew Geisslerc9f78652020-09-18 14:11:35 -050060
614. *Run the Installer:* Be sure you have execution privileges and run
62 the installer. Following is an example from the ``Downloads``
Andrew Geisslerc926e172021-05-07 16:11:35 -050063 directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050064
Andrew Geisslerd1e89492021-02-12 15:35:20 -060065 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
Andrew Geisslerc9f78652020-09-18 14:11:35 -050066
67 During execution of the script, you choose the root location for the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050068 toolchain. See the
69 ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
70 section and the
71 ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050072 section for more information.
73
74Building an SDK Installer
75=========================
76
77As an alternative to locating and downloading an SDK installer, you can
78build the SDK installer. Follow these steps:
79
801. *Set Up the Build Environment:* Be sure you are set up to use BitBake
Andrew Geissler09209ee2020-12-13 08:44:15 -060081 in a shell. See the ":ref:`dev-manual/start:preparing the build host`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -050082 in the Yocto Project Development Tasks Manual for information on how
83 to get a build host ready that is either a native Linux machine or a
84 machine that uses CROPS.
85
862. *Clone the ``poky`` Repository:* You need to have a local copy of the
87 Yocto Project :term:`Source Directory`
88 (i.e. a local
Andrew Geissler09209ee2020-12-13 08:44:15 -060089 ``poky`` repository). See the ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and
90 possibly the ":ref:`dev-manual/start:checking out by branch in poky`" and
91 ":ref:`dev-manual/start:checking out by tag in poky`" sections
Andrew Geisslerc9f78652020-09-18 14:11:35 -050092 all in the Yocto Project Development Tasks Manual for information on
93 how to clone the ``poky`` repository and check out the appropriate
94 branch for your work.
95
963. *Initialize the Build Environment:* While in the root directory of
97 the Source Directory (i.e. ``poky``), run the
98 :ref:`structure-core-script` environment
99 setup script to define the OpenEmbedded build environment on your
100 build host.
101 ::
102
103 $ source oe-init-build-env
104
105 Among other things, the script
106 creates the :term:`Build Directory`,
107 which is
108 ``build`` in this case and is located in the Source Directory. After
109 the script runs, your current working directory is set to the
110 ``build`` directory.
111
1124. *Make Sure You Are Building an Installer for the Correct Machine:*
113 Check to be sure that your
114 :term:`MACHINE` variable in the
115 ``local.conf`` file in your Build Directory matches the architecture
116 for which you are building.
117
1185. *Make Sure Your SDK Machine is Correctly Set:* If you are building a
119 toolchain designed to run on an architecture that differs from your
120 current development host machine (i.e. the build host), be sure that
121 the :term:`SDKMACHINE` variable
122 in the ``local.conf`` file in your Build Directory is correctly set.
123
124 .. note::
125
126 If you are building an SDK installer for the Extensible SDK, the
127 SDKMACHINE
128 value must be set for the architecture of the machine you are
129 using to build the installer. If
130 SDKMACHINE
131 is not set appropriately, the build fails and provides an error
Andrew Geisslerc926e172021-05-07 16:11:35 -0500132 message similar to the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500133
134 The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is
135 set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64).
136 Unable to continue.
137
138
1396. *Build the SDK Installer:* To build the SDK installer for a standard
140 SDK and populate the SDK image, use the following command form. Be
Andrew Geisslerc926e172021-05-07 16:11:35 -0500141 sure to replace ``image`` with an image (e.g. "core-image-sato")::
142
143 $ bitbake image -c populate_sdk
144
145 You can do the same for the extensible SDK using this command form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500146
147 $ bitbake image -c populate_sdk_ext
148
149 These commands produce an SDK installer that contains the sysroot
150 that matches your target root filesystem.
151
152 When the ``bitbake`` command completes, the SDK installer will be in
153 ``tmp/deploy/sdk`` in the Build Directory.
154
155 .. note::
156
157 - By default, the previous BitBake command does not build static
158 binaries. If you want to use the toolchain to build these types
159 of libraries, you need to be sure your SDK has the appropriate
160 static development libraries. Use the
161 :term:`TOOLCHAIN_TARGET_TASK`
162 variable inside your ``local.conf`` file before building the
163 SDK installer. Doing so ensures that the eventual SDK
164 installation process installs the appropriate library packages
165 as part of the SDK. Following is an example using ``libc``
166 static development libraries: TOOLCHAIN_TARGET_TASK_append = "
167 libc-staticdev"
168
1697. *Run the Installer:* You can now run the SDK installer from
Andrew Geisslerc926e172021-05-07 16:11:35 -0500170 ``tmp/deploy/sdk`` in the Build Directory. Following is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500171
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500172 $ cd poky/build/tmp/deploy/sdk
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600173 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500174
175 During execution of the script, you choose the root location for the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500176 toolchain. See the
177 ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
178 section and the
179 ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500180 section for more information.
181
182Extracting the Root Filesystem
183==============================
184
185After installing the toolchain, for some use cases you might need to
186separately extract a root filesystem:
187
188- You want to boot the image using NFS.
189
190- You want to use the root filesystem as the target sysroot.
191
192- You want to develop your target application using the root filesystem
193 as the target sysroot.
194
195Follow these steps to extract the root filesystem:
196
1971. *Locate and Download the Tarball for the Pre-Built Root Filesystem
198 Image File:* You need to find and download the root filesystem image
199 file that is appropriate for your target system. These files are kept
200 in machine-specific folders in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600201 :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500202 in the "machines" directory.
203
204 The machine-specific folders of the "machines" directory contain
205 tarballs (``*.tar.bz2``) for supported machines. These directories
206 also contain flattened root filesystem image files (``*.ext4``),
207 which you can use with QEMU directly.
208
209 The pre-built root filesystem image files follow these naming
Andrew Geisslerc926e172021-05-07 16:11:35 -0500210 conventions::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500211
212 core-image-profile-arch.tar.bz2
213
214 Where:
215 profile is the filesystem image's profile:
216 lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs,
217 sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on
218 these types of image profiles, see the "Images" chapter in
219 the Yocto Project Reference Manual.
220
221 arch is a string representing the target architecture:
222 beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb,
223 genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*.
224
225 The root filesystems
226 provided by the Yocto Project are based off of the
227 ``core-image-sato`` and ``core-image-minimal`` images.
228
229 For example, if you plan on using a BeagleBone device as your target
230 hardware and your image is a ``core-image-sato-sdk`` image, you can
Andrew Geisslerc926e172021-05-07 16:11:35 -0500231 download the following file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500232
233 core-image-sato-sdk-beaglebone-yocto.tar.bz2
234
2352. *Initialize the Cross-Development Environment:* You must ``source``
236 the cross-development environment setup script to establish necessary
237 environment variables.
238
239 This script is located in the top-level directory in which you
240 installed the toolchain (e.g. ``poky_sdk``).
241
242 Following is an example based on the toolchain installed in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500243 ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500244
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500245 $ source poky_sdk/environment-setup-core2-64-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500246
2473. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk``
248 command and provide the root filesystem image.
249
250 Following is an example command that extracts the root filesystem
251 from a previously built root filesystem image that was downloaded
Andrew Geissler09209ee2020-12-13 08:44:15 -0600252 from the :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500253 This command extracts the root filesystem into the ``core2-64-sato``
Andrew Geisslerc926e172021-05-07 16:11:35 -0500254 directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500255
256 $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
257
Andrew Geisslerc926e172021-05-07 16:11:35 -0500258 You could now point to the target sysroot at ``beaglebone-sato``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500259
260Installed Standard SDK Directory Structure
261==========================================
262
263The following figure shows the resulting directory structure after you
264install the Standard SDK by running the ``*.sh`` SDK installation
265script:
266
267.. image:: figures/sdk-installed-standard-sdk-directory.png
268 :scale: 80%
269 :align: center
270
271The installed SDK consists of an environment setup script for the SDK, a
272configuration file for the target, a version file for the target, and
273the root filesystem (``sysroots``) needed to develop objects for the
274target system.
275
276Within the figure, italicized text is used to indicate replaceable
277portions of the file or directory name. For example, install_dir/version
278is the directory where the SDK is installed. By default, this directory
279is ``/opt/poky/``. And, version represents the specific snapshot of the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600280SDK (e.g. &DISTRO;). Furthermore, target represents the target architecture
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500281(e.g. ``i586``) and host represents the development system's
282architecture (e.g. ``x86_64``). Thus, the complete names of the two
283directories within the ``sysroots`` could be ``i586-poky-linux`` and
284``x86_64-pokysdk-linux`` for the target and host, respectively.
285
286Installed Extensible SDK Directory Structure
287============================================
288
289The following figure shows the resulting directory structure after you
290install the Extensible SDK by running the ``*.sh`` SDK installation
291script:
292
293.. image:: figures/sdk-installed-extensible-sdk-directory.png
294 :scale: 80%
295 :align: center
296
297The installed directory structure for the extensible SDK is quite
298different than the installed structure for the standard SDK. The
299extensible SDK does not separate host and target parts in the same
300manner as does the standard SDK. The extensible SDK uses an embedded
301copy of the OpenEmbedded build system, which has its own sysroots.
302
303Of note in the directory structure are an environment setup script for
304the SDK, a configuration file for the target, a version file for the
305target, and log files for the OpenEmbedded build system preparation
306script run by the installer and BitBake.
307
308Within the figure, italicized text is used to indicate replaceable
309portions of the file or directory name. For example, install_dir is the
310directory where the SDK is installed, which is ``poky_sdk`` by default,
311and target represents the target architecture (e.g. ``i586``).