blob: f40ea6d4abc6b5f31a2ab031c2fa202f8dc7a9e9 [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
Patrick Williams92b42cb2022-09-03 06:53:57 -05007Working with the SDK components directly in a Yocto build
8=========================================================
9
10Please refer to section
11":ref:`sdk-manual/extensible:Setting up the Extensible SDK environment directly in a Yocto build`"
12
13Note that to use this feature effectively either a powerful build
14machine, or a well-functioning sstate cache infrastructure is required:
15otherwise significant time could be spent waiting for components to be built
16by BitBake from source code.
17
18Working with standalone SDK Installers
19======================================
20
Andrew Geisslerc9f78652020-09-18 14:11:35 -050021Locating Pre-Built SDK Installers
Patrick Williams92b42cb2022-09-03 06:53:57 -050022---------------------------------
Andrew Geisslerc9f78652020-09-18 14:11:35 -050023
24You can use existing, pre-built toolchains by locating and running an
25SDK installer script that ships with the Yocto Project. Using this
26method, you select and download an architecture-specific SDK installer
27and then run the script to hand-install the toolchain.
28
29Follow these steps to locate and hand-install the toolchain:
30
Andrew Geissler517393d2023-01-13 08:55:19 -060031#. *Go to the Installers Directory:* Go to
Andrew Geissler09209ee2020-12-13 08:44:15 -060032 :yocto_dl:`/releases/yocto/yocto-&DISTRO;/toolchain/`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050033
Andrew Geissler517393d2023-01-13 08:55:19 -060034#. *Open the Folder for Your Build Host:* Open the folder that matches
Andrew Geisslerc9f78652020-09-18 14:11:35 -050035 your :term:`Build Host` (i.e.
36 ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines).
37
Andrew Geissler517393d2023-01-13 08:55:19 -060038#. *Locate and Download the SDK Installer:* You need to find and
Andrew Geisslerc9f78652020-09-18 14:11:35 -050039 download the installer appropriate for your build host, target
40 hardware, and image type.
41
Andrew Geisslerc926e172021-05-07 16:11:35 -050042 The installer files (``*.sh``) follow this naming convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050043
44 poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh
45
46 Where:
47 host_system is a string representing your development system:
48 "i686" or "x86_64"
49
50 type is a string representing the image:
51 "sato" or "minimal"
52
53 arch is a string representing the target architecture:
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050054 "aarch64", "armv5e", "core2-64", "cortexa8hf-neon", "i586", "mips32r2",
Andrew Geisslerc9f78652020-09-18 14:11:35 -050055 "mips64", or "ppc7400"
56
57 release is the version of Yocto Project.
58
59 NOTE:
60 The standard SDK installer does not have the "-ext" string as
61 part of the filename.
62
63
64 The toolchains provided by the Yocto
65 Project are based off of the ``core-image-sato`` and
66 ``core-image-minimal`` images and contain libraries appropriate for
67 developing against those images.
68
69 For example, if your build host is a 64-bit x86 system and you need
70 an extended SDK for a 64-bit core2 target, go into the ``x86_64``
Andrew Geisslerc926e172021-05-07 16:11:35 -050071 folder and download the following installer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050072
Andrew Geisslerd1e89492021-02-12 15:35:20 -060073 poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
Andrew Geisslerc9f78652020-09-18 14:11:35 -050074
Andrew Geissler517393d2023-01-13 08:55:19 -060075#. *Run the Installer:* Be sure you have execution privileges and run
Andrew Geisslerc9f78652020-09-18 14:11:35 -050076 the installer. Following is an example from the ``Downloads``
Andrew Geisslerc926e172021-05-07 16:11:35 -050077 directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050078
Andrew Geisslerd1e89492021-02-12 15:35:20 -060079 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
Andrew Geisslerc9f78652020-09-18 14:11:35 -050080
81 During execution of the script, you choose the root location for the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050082 toolchain. See the
83 ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
84 section and the
85 ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050086 section for more information.
87
88Building an SDK Installer
Patrick Williams92b42cb2022-09-03 06:53:57 -050089-------------------------
Andrew Geisslerc9f78652020-09-18 14:11:35 -050090
91As an alternative to locating and downloading an SDK installer, you can
92build the SDK installer. Follow these steps:
93
Andrew Geissler517393d2023-01-13 08:55:19 -060094#. *Set Up the Build Environment:* Be sure you are set up to use BitBake
Andrew Geissler09209ee2020-12-13 08:44:15 -060095 in a shell. See the ":ref:`dev-manual/start:preparing the build host`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -050096 in the Yocto Project Development Tasks Manual for information on how
97 to get a build host ready that is either a native Linux machine or a
98 machine that uses CROPS.
99
Andrew Geissler517393d2023-01-13 08:55:19 -0600100#. *Clone the ``poky`` Repository:* You need to have a local copy of the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500101 Yocto Project :term:`Source Directory`
102 (i.e. a local
Andrew Geissler09209ee2020-12-13 08:44:15 -0600103 ``poky`` repository). See the ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and
104 possibly the ":ref:`dev-manual/start:checking out by branch in poky`" and
105 ":ref:`dev-manual/start:checking out by tag in poky`" sections
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500106 all in the Yocto Project Development Tasks Manual for information on
107 how to clone the ``poky`` repository and check out the appropriate
108 branch for your work.
109
Andrew Geissler517393d2023-01-13 08:55:19 -0600110#. *Initialize the Build Environment:* While in the root directory of
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500111 the Source Directory (i.e. ``poky``), run the
112 :ref:`structure-core-script` environment
113 setup script to define the OpenEmbedded build environment on your
Andrew Geissler517393d2023-01-13 08:55:19 -0600114 build host::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500115
116 $ source oe-init-build-env
117
Patrick Williams2390b1b2022-11-03 13:47:49 -0500118 Among other things, the script creates the :term:`Build Directory`, which
119 is ``build`` in this case and is located in the Source Directory. After
120 the script runs, your current working directory is set to the ``build``
121 directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500122
Andrew Geissler517393d2023-01-13 08:55:19 -0600123#. *Make Sure You Are Building an Installer for the Correct Machine:*
Patrick Williams2390b1b2022-11-03 13:47:49 -0500124 Check to be sure that your :term:`MACHINE` variable in the ``local.conf``
125 file in your :term:`Build Directory` matches the architecture
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500126 for which you are building.
127
Andrew Geissler517393d2023-01-13 08:55:19 -0600128#. *Make Sure Your SDK Machine is Correctly Set:* If you are building a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500129 toolchain designed to run on an architecture that differs from your
130 current development host machine (i.e. the build host), be sure that
Patrick Williams2390b1b2022-11-03 13:47:49 -0500131 the :term:`SDKMACHINE` variable in the ``local.conf`` file in your
132 :term:`Build Directory` is correctly set.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500133
134 .. note::
135
136 If you are building an SDK installer for the Extensible SDK, the
Patrick Williams2390b1b2022-11-03 13:47:49 -0500137 :term:`SDKMACHINE` value must be set for the architecture of the
138 machine you are using to build the installer. If :term:`SDKMACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500139 is not set appropriately, the build fails and provides an error
Andrew Geisslerc926e172021-05-07 16:11:35 -0500140 message similar to the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500141
Patrick Williams2390b1b2022-11-03 13:47:49 -0500142 The extensible SDK can currently only be built for the same
Patrick Williams2a254922023-08-11 09:48:11 -0500143 architecture as the machine being built on - SDK_ARCH
144 is set to i686 (likely via setting SDKMACHINE) which is
145 different from the architecture of the build machine (x86_64).
146 Unable to continue.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500147
148
Andrew Geissler517393d2023-01-13 08:55:19 -0600149#. *Build the SDK Installer:* To build the SDK installer for a standard
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500150 SDK and populate the SDK image, use the following command form. Be
Andrew Geisslerc926e172021-05-07 16:11:35 -0500151 sure to replace ``image`` with an image (e.g. "core-image-sato")::
152
153 $ bitbake image -c populate_sdk
154
155 You can do the same for the extensible SDK using this command form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500156
157 $ bitbake image -c populate_sdk_ext
158
159 These commands produce an SDK installer that contains the sysroot
160 that matches your target root filesystem.
161
162 When the ``bitbake`` command completes, the SDK installer will be in
Patrick Williams2390b1b2022-11-03 13:47:49 -0500163 ``tmp/deploy/sdk`` in the :term:`Build Directory`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500164
165 .. note::
166
167 - By default, the previous BitBake command does not build static
168 binaries. If you want to use the toolchain to build these types
169 of libraries, you need to be sure your SDK has the appropriate
170 static development libraries. Use the
171 :term:`TOOLCHAIN_TARGET_TASK`
172 variable inside your ``local.conf`` file before building the
173 SDK installer. Doing so ensures that the eventual SDK
174 installation process installs the appropriate library packages
175 as part of the SDK. Following is an example using ``libc``
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500176 static development libraries: TOOLCHAIN_TARGET_TASK:append = "
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500177 libc-staticdev"
178
Andrew Geissler517393d2023-01-13 08:55:19 -0600179#. *Run the Installer:* You can now run the SDK installer from
Patrick Williams2390b1b2022-11-03 13:47:49 -0500180 ``tmp/deploy/sdk`` in the :term:`Build Directory`. Following is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500181
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500182 $ cd poky/build/tmp/deploy/sdk
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600183 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500184
185 During execution of the script, you choose the root location for the
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500186 toolchain. See the
187 ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
188 section and the
189 ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500190 section for more information.
191
192Extracting the Root Filesystem
193==============================
194
195After installing the toolchain, for some use cases you might need to
196separately extract a root filesystem:
197
198- You want to boot the image using NFS.
199
200- You want to use the root filesystem as the target sysroot.
201
202- You want to develop your target application using the root filesystem
203 as the target sysroot.
204
205Follow these steps to extract the root filesystem:
206
Andrew Geissler517393d2023-01-13 08:55:19 -0600207#. *Locate and Download the Tarball for the Pre-Built Root Filesystem
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500208 Image File:* You need to find and download the root filesystem image
209 file that is appropriate for your target system. These files are kept
210 in machine-specific folders in the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600211 :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500212 in the "machines" directory.
213
214 The machine-specific folders of the "machines" directory contain
215 tarballs (``*.tar.bz2``) for supported machines. These directories
216 also contain flattened root filesystem image files (``*.ext4``),
217 which you can use with QEMU directly.
218
219 The pre-built root filesystem image files follow these naming
Andrew Geisslerc926e172021-05-07 16:11:35 -0500220 conventions::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500221
222 core-image-profile-arch.tar.bz2
223
224 Where:
225 profile is the filesystem image's profile:
226 lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs,
227 sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on
228 these types of image profiles, see the "Images" chapter in
229 the Yocto Project Reference Manual.
230
231 arch is a string representing the target architecture:
232 beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb,
233 genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*.
234
235 The root filesystems
236 provided by the Yocto Project are based off of the
237 ``core-image-sato`` and ``core-image-minimal`` images.
238
239 For example, if you plan on using a BeagleBone device as your target
240 hardware and your image is a ``core-image-sato-sdk`` image, you can
Andrew Geisslerc926e172021-05-07 16:11:35 -0500241 download the following file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500242
243 core-image-sato-sdk-beaglebone-yocto.tar.bz2
244
Andrew Geissler517393d2023-01-13 08:55:19 -0600245#. *Initialize the Cross-Development Environment:* You must ``source``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500246 the cross-development environment setup script to establish necessary
247 environment variables.
248
249 This script is located in the top-level directory in which you
250 installed the toolchain (e.g. ``poky_sdk``).
251
252 Following is an example based on the toolchain installed in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500253 ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500254
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500255 $ source poky_sdk/environment-setup-core2-64-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500256
Andrew Geissler517393d2023-01-13 08:55:19 -0600257#. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500258 command and provide the root filesystem image.
259
260 Following is an example command that extracts the root filesystem
261 from a previously built root filesystem image that was downloaded
Andrew Geissler09209ee2020-12-13 08:44:15 -0600262 from the :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500263 This command extracts the root filesystem into the ``core2-64-sato``
Andrew Geisslerc926e172021-05-07 16:11:35 -0500264 directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500265
266 $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
267
Andrew Geisslerc926e172021-05-07 16:11:35 -0500268 You could now point to the target sysroot at ``beaglebone-sato``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500269
270Installed Standard SDK Directory Structure
271==========================================
272
273The following figure shows the resulting directory structure after you
274install the Standard SDK by running the ``*.sh`` SDK installation
275script:
276
277.. image:: figures/sdk-installed-standard-sdk-directory.png
Andrew Geisslerd5838332022-05-27 11:33:10 -0500278 :scale: 100%
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500279
280The installed SDK consists of an environment setup script for the SDK, a
281configuration file for the target, a version file for the target, and
282the root filesystem (``sysroots``) needed to develop objects for the
283target system.
284
285Within the figure, italicized text is used to indicate replaceable
286portions of the file or directory name. For example, install_dir/version
287is the directory where the SDK is installed. By default, this directory
288is ``/opt/poky/``. And, version represents the specific snapshot of the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600289SDK (e.g. &DISTRO;). Furthermore, target represents the target architecture
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500290(e.g. ``i586``) and host represents the development system's
291architecture (e.g. ``x86_64``). Thus, the complete names of the two
292directories within the ``sysroots`` could be ``i586-poky-linux`` and
293``x86_64-pokysdk-linux`` for the target and host, respectively.
294
295Installed Extensible SDK Directory Structure
296============================================
297
298The following figure shows the resulting directory structure after you
299install the Extensible SDK by running the ``*.sh`` SDK installation
300script:
301
302.. image:: figures/sdk-installed-extensible-sdk-directory.png
303 :scale: 80%
304 :align: center
305
306The installed directory structure for the extensible SDK is quite
307different than the installed structure for the standard SDK. The
308extensible SDK does not separate host and target parts in the same
309manner as does the standard SDK. The extensible SDK uses an embedded
310copy of the OpenEmbedded build system, which has its own sysroots.
311
312Of note in the directory structure are an environment setup script for
313the SDK, a configuration file for the target, a version file for the
314target, and log files for the OpenEmbedded build system preparation
315script run by the installer and BitBake.
316
317Within the figure, italicized text is used to indicate replaceable
318portions of the file or directory name. For example, install_dir is the
319directory where the SDK is installed, which is ``poky_sdk`` by default,
320and target represents the target architecture (e.g. ``i586``).