blob: 301627812ca8e1b445306c259f20db1476334276 [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**********************
4Using the Standard SDK
5**********************
6
7This chapter describes the standard SDK and how to install it.
8Information includes unique installation and setup aspects for the
9standard SDK.
10
11.. note::
12
13 For a side-by-side comparison of main features supported for a
William A. Kennington IIIac69b482021-06-02 12:28:27 -070014 standard SDK as compared to an extensible SDK, see the
15 ":ref:`sdk-manual/intro:introduction`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050016
17You can use a standard SDK to work on Makefile and Autotools-based
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050018projects. See the
19":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter
20for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050021
Andrew Geisslerc9f78652020-09-18 14:11:35 -050022Why use the Standard SDK and What is in It?
23===========================================
24
25The Standard SDK provides a cross-development toolchain and libraries
26tailored to the contents of a specific image. You would use the Standard
27SDK if you want a more traditional toolchain experience as compared to
28the extensible SDK, which provides an internal build system and the
29``devtool`` functionality.
30
31The installed Standard SDK consists of several files and directories.
32Basically, it contains an SDK environment setup script, some
33configuration files, and host and target root filesystems to support
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050034usage. You can see the directory structure in the
35":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
36section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050037
Andrew Geisslerc9f78652020-09-18 14:11:35 -050038Installing the SDK
39==================
40
41The first thing you need to do is install the SDK on your :term:`Build
42Host` by running the ``*.sh`` installation script.
43
44You can download a tarball installer, which includes the pre-built
45toolchain, the ``runqemu`` script, and support files from the
Andrew Geissler09209ee2020-12-13 08:44:15 -060046appropriate :yocto_dl:`toolchain </releases/yocto/yocto-&DISTRO;/toolchain/>` directory within
Andrew Geisslerc9f78652020-09-18 14:11:35 -050047the Index of Releases. Toolchains are available for several 32-bit and
4864-bit architectures with the ``x86_64`` directories, respectively. The
49toolchains the Yocto Project provides are based off the
50``core-image-sato`` and ``core-image-minimal`` images and contain
William A. Kennington IIIac69b482021-06-02 12:28:27 -070051libraries appropriate for developing against the corresponding image.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050052
53The names of the tarball installer scripts are such that a string
54representing the host system appears first in the filename and then is
55immediately followed by a string representing the target architecture.
56::
57
58 poky-glibc-host_system-image_type-arch-toolchain-release_version.sh
59
60 Where:
61 host_system is a string representing your development system:
62
63 i686 or x86_64.
64
65 image_type is the image for which the SDK was built:
66
67 core-image-minimal or core-image-sato.
68
69 arch is a string representing the tuned target architecture:
70
71 aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon.
72
73 release_version is a string representing the release number of the Yocto Project:
74
Andrew Geissler09209ee2020-12-13 08:44:15 -060075 &DISTRO;, &DISTRO;+snapshot
Andrew Geisslerc9f78652020-09-18 14:11:35 -050076
77For example, the following SDK installer is for a 64-bit
78development host system and a i586-tuned target architecture based off
Andrew Geisslerc926e172021-05-07 16:11:35 -050079the SDK for ``core-image-sato`` and using the current DISTRO snapshot::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050080
81 poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh
82
83.. note::
84
85 As an alternative to downloading an SDK, you can build the SDK
William A. Kennington IIIac69b482021-06-02 12:28:27 -070086 installer. For information on building the installer, see the
87 ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
88 section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050089
90The SDK and toolchains are self-contained and by default are installed
91into the ``poky_sdk`` folder in your home directory. You can choose to
92install the extensible SDK in any location when you run the installer.
93However, because files need to be written under that directory during
94the normal course of operation, the location you choose for installation
95must be writable for whichever users need to use the SDK.
96
97The following command shows how to run the installer given a toolchain
98tarball for a 64-bit x86 development host system and a 64-bit x86 target
99architecture. The example assumes the SDK installer is located in
100``~/Downloads/`` and has execution rights.
101
102.. note::
103
104 If you do not have write permissions for the directory into which you
105 are installing the SDK, the installer notifies you and exits. For
106 that case, set up the proper permissions in the directory and run the
107 installer again.
108
109::
110
Andrew Geissler09209ee2020-12-13 08:44:15 -0600111 $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
112 Poky (Yocto Project Reference Distro) SDK installer version &DISTRO;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500113 ===============================================================
Andrew Geissler09209ee2020-12-13 08:44:15 -0600114 Enter target directory for SDK (default: /opt/poky/&DISTRO;):
115 You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed [Y/n]? Y
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500116 Extracting SDK........................................ ..............................done
117 Setting it up...done
118 SDK has been successfully set up and is ready to be used.
119 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
Andrew Geissler09209ee2020-12-13 08:44:15 -0600120 $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500121
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500122Again, reference the
123":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
124section for more details on the resulting directory structure of the installed
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500125SDK.
126
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500127Running the SDK Environment Setup Script
128========================================
129
130Once you have the SDK installed, you must run the SDK environment setup
131script before you can actually use the SDK. This setup script resides in
132the directory you chose when you installed the SDK, which is either the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600133default ``/opt/poky/&DISTRO;`` directory or the directory you chose during
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500134installation.
135
136Before running the script, be sure it is the one that matches the
137architecture for which you are developing. Environment setup scripts
138begin with the string "``environment-setup``" and include as part of
139their name the tuned target architecture. As an example, the following
140commands set the working directory to where the SDK was installed and
141then source the environment setup script. In this example, the setup
Andrew Geisslerc926e172021-05-07 16:11:35 -0500142script is for an IA-based target machine using i586 tuning::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500143
Andrew Geissler09209ee2020-12-13 08:44:15 -0600144 $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500145
146When you run the
147setup script, the same environment variables are defined as are when you
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500148run the setup script for an extensible SDK. See the
149":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500150section for more information.