blob: a51c22e399578acad72f8c34f1ef5d0c52f1bb53 [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
7.. _sdk-locating-pre-built-sdk-installers:
8
9Locating Pre-Built SDK Installers
10=================================
11
12You can use existing, pre-built toolchains by locating and running an
13SDK installer script that ships with the Yocto Project. Using this
14method, you select and download an architecture-specific SDK installer
15and then run the script to hand-install the toolchain.
16
17Follow these steps to locate and hand-install the toolchain:
18
191. *Go to the Installers Directory:* Go to
Andrew Geisslerc3d88e42020-10-02 09:45:00 -050020 :yocto_dl:`/releases/yocto/yocto-3.1.2/toolchain/`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050021
222. *Open the Folder for Your Build Host:* Open the folder that matches
23 your :term:`Build Host` (i.e.
24 ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines).
25
263. *Locate and Download the SDK Installer:* You need to find and
27 download the installer appropriate for your build host, target
28 hardware, and image type.
29
30 The installer files (``*.sh``) follow this naming convention:
31 ::
32
33 poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh
34
35 Where:
36 host_system is a string representing your development system:
37 "i686" or "x86_64"
38
39 type is a string representing the image:
40 "sato" or "minimal"
41
42 arch is a string representing the target architecture:
43 "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2",
44 "mips64", or "ppc7400"
45
46 release is the version of Yocto Project.
47
48 NOTE:
49 The standard SDK installer does not have the "-ext" string as
50 part of the filename.
51
52
53 The toolchains provided by the Yocto
54 Project are based off of the ``core-image-sato`` and
55 ``core-image-minimal`` images and contain libraries appropriate for
56 developing against those images.
57
58 For example, if your build host is a 64-bit x86 system and you need
59 an extended SDK for a 64-bit core2 target, go into the ``x86_64``
60 folder and download the following installer:
61 ::
62
63 poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
64
654. *Run the Installer:* Be sure you have execution privileges and run
66 the installer. Following is an example from the ``Downloads``
67 directory:
68 ::
69
70 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
71
72 During execution of the script, you choose the root location for the
73 toolchain. See the "`Installed Standard SDK Directory
74 Structure <#sdk-installed-standard-sdk-directory-structure>`__"
75 section and the "`Installed Extensible SDK Directory
76 Structure <#sdk-installed-extensible-sdk-directory-structure>`__"
77 section for more information.
78
79Building an SDK Installer
80=========================
81
82As an alternative to locating and downloading an SDK installer, you can
83build the SDK installer. Follow these steps:
84
851. *Set Up the Build Environment:* Be sure you are set up to use BitBake
86 in a shell. See the ":ref:`dev-manual/dev-manual-start:preparing the build host`" section
87 in the Yocto Project Development Tasks Manual for information on how
88 to get a build host ready that is either a native Linux machine or a
89 machine that uses CROPS.
90
912. *Clone the ``poky`` Repository:* You need to have a local copy of the
92 Yocto Project :term:`Source Directory`
93 (i.e. a local
94 ``poky`` repository). See the ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" and
95 possibly the ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" and
96 ":ref:`checkout-out-by-tag-in-poky`" sections
97 all in the Yocto Project Development Tasks Manual for information on
98 how to clone the ``poky`` repository and check out the appropriate
99 branch for your work.
100
1013. *Initialize the Build Environment:* While in the root directory of
102 the Source Directory (i.e. ``poky``), run the
103 :ref:`structure-core-script` environment
104 setup script to define the OpenEmbedded build environment on your
105 build host.
106 ::
107
108 $ source oe-init-build-env
109
110 Among other things, the script
111 creates the :term:`Build Directory`,
112 which is
113 ``build`` in this case and is located in the Source Directory. After
114 the script runs, your current working directory is set to the
115 ``build`` directory.
116
1174. *Make Sure You Are Building an Installer for the Correct Machine:*
118 Check to be sure that your
119 :term:`MACHINE` variable in the
120 ``local.conf`` file in your Build Directory matches the architecture
121 for which you are building.
122
1235. *Make Sure Your SDK Machine is Correctly Set:* If you are building a
124 toolchain designed to run on an architecture that differs from your
125 current development host machine (i.e. the build host), be sure that
126 the :term:`SDKMACHINE` variable
127 in the ``local.conf`` file in your Build Directory is correctly set.
128
129 .. note::
130
131 If you are building an SDK installer for the Extensible SDK, the
132 SDKMACHINE
133 value must be set for the architecture of the machine you are
134 using to build the installer. If
135 SDKMACHINE
136 is not set appropriately, the build fails and provides an error
137 message similar to the following:
138 ::
139
140 The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is
141 set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64).
142 Unable to continue.
143
144
1456. *Build the SDK Installer:* To build the SDK installer for a standard
146 SDK and populate the SDK image, use the following command form. Be
147 sure to replace image with an image (e.g. "core-image-sato"): $
148 bitbake image -c populate_sdk You can do the same for the extensible
149 SDK using this command form:
150 ::
151
152 $ bitbake image -c populate_sdk_ext
153
154 These commands produce an SDK installer that contains the sysroot
155 that matches your target root filesystem.
156
157 When the ``bitbake`` command completes, the SDK installer will be in
158 ``tmp/deploy/sdk`` in the Build Directory.
159
160 .. note::
161
162 - By default, the previous BitBake command does not build static
163 binaries. If you want to use the toolchain to build these types
164 of libraries, you need to be sure your SDK has the appropriate
165 static development libraries. Use the
166 :term:`TOOLCHAIN_TARGET_TASK`
167 variable inside your ``local.conf`` file before building the
168 SDK installer. Doing so ensures that the eventual SDK
169 installation process installs the appropriate library packages
170 as part of the SDK. Following is an example using ``libc``
171 static development libraries: TOOLCHAIN_TARGET_TASK_append = "
172 libc-staticdev"
173
1747. *Run the Installer:* You can now run the SDK installer from
175 ``tmp/deploy/sdk`` in the Build Directory. Following is an example:
176 ::
177
178 $ cd ~/poky/build/tmp/deploy/sdk
179 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
180
181 During execution of the script, you choose the root location for the
182 toolchain. See the "`Installed Standard SDK Directory
183 Structure <#sdk-installed-standard-sdk-directory-structure>`__"
184 section and the "`Installed Extensible SDK Directory
185 Structure <#sdk-installed-extensible-sdk-directory-structure>`__"
186 section for more information.
187
188Extracting the Root Filesystem
189==============================
190
191After installing the toolchain, for some use cases you might need to
192separately extract a root filesystem:
193
194- You want to boot the image using NFS.
195
196- You want to use the root filesystem as the target sysroot.
197
198- You want to develop your target application using the root filesystem
199 as the target sysroot.
200
201Follow these steps to extract the root filesystem:
202
2031. *Locate and Download the Tarball for the Pre-Built Root Filesystem
204 Image File:* You need to find and download the root filesystem image
205 file that is appropriate for your target system. These files are kept
206 in machine-specific folders in the
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500207 :yocto_dl:`Index of Releases </releases/yocto/yocto-3.1.2/machines/>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500208 in the "machines" directory.
209
210 The machine-specific folders of the "machines" directory contain
211 tarballs (``*.tar.bz2``) for supported machines. These directories
212 also contain flattened root filesystem image files (``*.ext4``),
213 which you can use with QEMU directly.
214
215 The pre-built root filesystem image files follow these naming
216 conventions:
217 ::
218
219 core-image-profile-arch.tar.bz2
220
221 Where:
222 profile is the filesystem image's profile:
223 lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs,
224 sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on
225 these types of image profiles, see the "Images" chapter in
226 the Yocto Project Reference Manual.
227
228 arch is a string representing the target architecture:
229 beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb,
230 genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*.
231
232 The root filesystems
233 provided by the Yocto Project are based off of the
234 ``core-image-sato`` and ``core-image-minimal`` images.
235
236 For example, if you plan on using a BeagleBone device as your target
237 hardware and your image is a ``core-image-sato-sdk`` image, you can
238 download the following file:
239 ::
240
241 core-image-sato-sdk-beaglebone-yocto.tar.bz2
242
2432. *Initialize the Cross-Development Environment:* You must ``source``
244 the cross-development environment setup script to establish necessary
245 environment variables.
246
247 This script is located in the top-level directory in which you
248 installed the toolchain (e.g. ``poky_sdk``).
249
250 Following is an example based on the toolchain installed in the
251 ":ref:`sdk-locating-pre-built-sdk-installers`" section:
252 ::
253
254 $ source ~/poky_sdk/environment-setup-core2-64-poky-linux
255
2563. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk``
257 command and provide the root filesystem image.
258
259 Following is an example command that extracts the root filesystem
260 from a previously built root filesystem image that was downloaded
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500261 from the :yocto_dl:`Index of Releases </releases/yocto/yocto-3.1.2/machines/>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500262 This command extracts the root filesystem into the ``core2-64-sato``
263 directory:
264 ::
265
266 $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
267
268 You could now point to the target sysroot at ``beablebone-sato``.
269
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
278 :scale: 80%
279 :align: center
280
281The installed SDK consists of an environment setup script for the SDK, a
282configuration file for the target, a version file for the target, and
283the root filesystem (``sysroots``) needed to develop objects for the
284target system.
285
286Within the figure, italicized text is used to indicate replaceable
287portions of the file or directory name. For example, install_dir/version
288is the directory where the SDK is installed. By default, this directory
289is ``/opt/poky/``. And, version represents the specific snapshot of the
290SDK (e.g. 3.1.2). Furthermore, target represents the target architecture
291(e.g. ``i586``) and host represents the development system's
292architecture (e.g. ``x86_64``). Thus, the complete names of the two
293directories within the ``sysroots`` could be ``i586-poky-linux`` and
294``x86_64-pokysdk-linux`` for the target and host, respectively.
295
296Installed Extensible SDK Directory Structure
297============================================
298
299The following figure shows the resulting directory structure after you
300install the Extensible SDK by running the ``*.sh`` SDK installation
301script:
302
303.. image:: figures/sdk-installed-extensible-sdk-directory.png
304 :scale: 80%
305 :align: center
306
307The installed directory structure for the extensible SDK is quite
308different than the installed structure for the standard SDK. The
309extensible SDK does not separate host and target parts in the same
310manner as does the standard SDK. The extensible SDK uses an embedded
311copy of the OpenEmbedded build system, which has its own sysroots.
312
313Of note in the directory structure are an environment setup script for
314the SDK, a configuration file for the target, a version file for the
315target, and log files for the OpenEmbedded build system preparation
316script run by the installer and BitBake.
317
318Within the figure, italicized text is used to indicate replaceable
319portions of the file or directory name. For example, install_dir is the
320directory where the SDK is installed, which is ``poky_sdk`` by default,
321and target represents the target architecture (e.g. ``i586``).