blob: ce00538b2a1fd172e04cbcce8c0723c37c2b5800 [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************
4Introduction
5************
6
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007eSDK Introduction
8=================
9
10Welcome to the Yocto Project Application Development and the Extensible
William A. Kennington IIIac69b482021-06-02 12:28:27 -070011Software Development Kit (eSDK) manual. This manual
12explains how to use both the Yocto Project extensible and standard
Andrew Geisslerc9f78652020-09-18 14:11:35 -050013SDKs to develop applications and images.
14
Andrew Geisslerc9f78652020-09-18 14:11:35 -050015All SDKs consist of the following:
16
17- *Cross-Development Toolchain*: This toolchain contains a compiler,
William A. Kennington IIIac69b482021-06-02 12:28:27 -070018 debugger, and various associated tools.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050019
20- *Libraries, Headers, and Symbols*: The libraries, headers, and
William A. Kennington IIIac69b482021-06-02 12:28:27 -070021 symbols are specific to the image (i.e. they match the image
22 against which the SDK was built).
Andrew Geisslerc9f78652020-09-18 14:11:35 -050023
William A. Kennington IIIac69b482021-06-02 12:28:27 -070024- *Environment Setup Script*: This ``*.sh`` file, once sourced, sets up the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050025 cross-development environment by defining variables and preparing for
26 SDK use.
27
28Additionally, an extensible SDK has tools that allow you to easily add
29new applications and libraries to an image, modify the source of an
30existing component, test changes on the target hardware, and easily
31integrate an application into the :term:`OpenEmbedded Build System`.
32
33You can use an SDK to independently develop and test code that is
34destined to run on some target machine. SDKs are completely
35self-contained. The binaries are linked against their own copy of
36``libc``, which results in no dependencies on the target system. To
37achieve this, the pointer to the dynamic loader is configured at install
38time since that path cannot be dynamically altered. This is the reason
39for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext``
40archives.
41
William A. Kennington IIIac69b482021-06-02 12:28:27 -070042Another feature of the SDKs is that only one set of cross-compiler
Andrew Geisslerc9f78652020-09-18 14:11:35 -050043toolchain binaries are produced for any given architecture. This feature
44takes advantage of the fact that the target hardware can be passed to
45``gcc`` as a set of compiler options. Those options are set up by the
46environment script and contained in variables such as
47:term:`CC` and
48:term:`LD`. This reduces the space needed
William A. Kennington IIIac69b482021-06-02 12:28:27 -070049for the tools. Understand, however, that every target still needs its own
Andrew Geisslerc9f78652020-09-18 14:11:35 -050050sysroot because those binaries are target-specific.
51
52The SDK development environment consists of the following:
53
54- The self-contained SDK, which is an architecture-specific
55 cross-toolchain and matching sysroots (target and native) all built
56 by the OpenEmbedded build system (e.g. the SDK). The toolchain and
57 sysroots are based on a :term:`Metadata`
58 configuration and extensions, which allows you to cross-develop on
59 the host machine for the target hardware. Additionally, the
60 extensible SDK contains the ``devtool`` functionality.
61
62- The Quick EMUlator (QEMU), which lets you simulate target hardware.
63 QEMU is not literally part of the SDK. You must build and include
64 this emulator separately. However, QEMU plays an important role in
65 the development process that revolves around use of the SDK.
66
67In summary, the extensible and standard SDK share many features.
68However, the extensible SDK has powerful development tools to help you
69more quickly develop applications. Following is a table that summarizes
70the primary differences between the standard and extensible SDK types
71when considering which to build:
72
73+-----------------------+-----------------------+-----------------------+
74| *Feature* | *Standard SDK* | *Extensible SDK* |
75+=======================+=======================+=======================+
Andrew Geissler4c19ea12020-10-27 13:52:24 -050076| Toolchain | Yes | Yes [1]_ |
Andrew Geisslerc9f78652020-09-18 14:11:35 -050077+-----------------------+-----------------------+-----------------------+
Andrew Geissler4c19ea12020-10-27 13:52:24 -050078| Debugger | Yes | Yes [1]_ |
Andrew Geisslerc9f78652020-09-18 14:11:35 -050079+-----------------------+-----------------------+-----------------------+
80| Size | 100+ MBytes | 1+ GBytes (or 300+ |
81| | | MBytes for minimal |
82| | | w/toolchain) |
83+-----------------------+-----------------------+-----------------------+
84| ``devtool`` | No | Yes |
85+-----------------------+-----------------------+-----------------------+
86| Build Images | No | Yes |
87+-----------------------+-----------------------+-----------------------+
88| Updateable | No | Yes |
89+-----------------------+-----------------------+-----------------------+
Andrew Geissler4c19ea12020-10-27 13:52:24 -050090| Managed Sysroot [2]_ | No | Yes |
Andrew Geisslerc9f78652020-09-18 14:11:35 -050091+-----------------------+-----------------------+-----------------------+
Andrew Geissler4c19ea12020-10-27 13:52:24 -050092| Installed Packages | No [3]_ | Yes [4]_ |
Andrew Geisslerc9f78652020-09-18 14:11:35 -050093+-----------------------+-----------------------+-----------------------+
94| Construction | Packages | Shared State |
95+-----------------------+-----------------------+-----------------------+
96
Andrew Geissler4c19ea12020-10-27 13:52:24 -050097.. [1] Extensible SDK contains the toolchain and debugger if :term:`SDK_EXT_TYPE`
98 is "full" or :term:`SDK_INCLUDE_TOOLCHAIN` is "1", which is the default.
99.. [2] Sysroot is managed through the use of ``devtool``. Thus, it is less
100 likely that you will corrupt your SDK sysroot when you try to add
101 additional libraries.
102.. [3] You can add runtime package management to the standard SDK but it is not
103 supported by default.
104.. [4] You must build and make the shared state available to extensible SDK
105 users for "packages" you want to enable users to install.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500106
107The Cross-Development Toolchain
108-------------------------------
109
110The :term:`Cross-Development Toolchain` consists
111of a cross-compiler, cross-linker, and cross-debugger that are used to
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700112develop user-space applications for targeted hardware; in addition,
113the extensible SDK comes with built-in ``devtool``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500114functionality. This toolchain is created by running a SDK installer
115script or through a :term:`Build Directory` that is based on
116your metadata configuration or extension for your targeted device. The
117cross-toolchain works with a matching target sysroot.
118
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500119Sysroots
120--------
121
122The native and target sysroots contain needed headers and libraries for
123generating binaries that run on the target architecture. The target
124sysroot is based on the target root filesystem image that is built by
125the OpenEmbedded build system and uses the same metadata configuration
126used to build the cross-toolchain.
127
128The QEMU Emulator
129-----------------
130
131The QEMU emulator allows you to simulate your hardware while running
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700132your application or image. QEMU is not part of the SDK but is
133automatically installed and available if you have done any one of
134the following:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500135
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700136- cloned the ``poky`` Git repository to create a
137 :term:`Source Directory` and sourced the environment setup script.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500138
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700139- downloaded a Yocto Project release and unpacked it to
140 create a Source Directory and sourced the environment setup
141 script.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500142
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700143- installed the cross-toolchain tarball and
144 sourced the toolchain's setup environment script.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500145
146SDK Development Model
147=====================
148
149Fundamentally, the SDK fits into the development process as follows:
150
151.. image:: figures/sdk-environment.png
Andrew Geisslerd5838332022-05-27 11:33:10 -0500152 :width: 100%
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500153
154The SDK is installed on any machine and can be used to develop applications,
155images, and kernels. An SDK can even be used by a QA Engineer or Release
156Engineer. The fundamental concept is that the machine that has the SDK
157installed does not have to be associated with the machine that has the
158Yocto Project installed. A developer can independently compile and test
159an object on their machine and then, when the object is ready for
160integration into an image, they can simply make it available to the
161machine that has the Yocto Project. Once the object is available, the
162image can be rebuilt using the Yocto Project to produce the modified
163image.
164
165You just need to follow these general steps:
166
1671. *Install the SDK for your target hardware:* For information on how to
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500168 install the SDK, see the ":ref:`sdk-manual/using:installing the sdk`"
169 section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500170
1712. *Download or Build the Target Image:* The Yocto Project supports
172 several target architectures and has many pre-built kernel images and
173 root filesystem images.
174
175 If you are going to develop your application on hardware, go to the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600176 :yocto_dl:`machines </releases/yocto/yocto-&DISTRO;/machines/>` download area and choose a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500177 target machine area from which to download the kernel image and root
178 filesystem. This download area could have several files in it that
179 support development using actual hardware. For example, the area
180 might contain ``.hddimg`` files that combine the kernel image with
181 the filesystem, boot loaders, and so forth. Be sure to get the files
182 you need for your particular development process.
183
184 If you are going to develop your application and then run and test it
185 using the QEMU emulator, go to the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600186 :yocto_dl:`machines/qemu </releases/yocto/yocto-&DISTRO;/machines/qemu>` download area. From this
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500187 area, go down into the directory for your target architecture (e.g.
188 ``qemux86_64`` for an Intel-based 64-bit architecture). Download the
189 kernel, root filesystem, and any other files you need for your
190 process.
191
192 .. note::
193
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700194 To use the root filesystem in QEMU, you need to extract it. See the
195 ":ref:`sdk-manual/appendix-obtain:extracting the root filesystem`"
196 section for information on how to do this extraction.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500197
1983. *Develop and Test your Application:* At this point, you have the
199 tools to develop your application. If you need to separately install
200 and use the QEMU emulator, you can go to `QEMU Home
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600201 Page <https://wiki.qemu.org/Main_Page>`__ to download and learn about
Andrew Geissler09209ee2020-12-13 08:44:15 -0600202 the emulator. See the ":doc:`/dev-manual/qemu`" chapter in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500203 Yocto Project Development Tasks Manual for information on using QEMU
204 within the Yocto Project.
205
206The remainder of this manual describes how to use the extensible and
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700207standard SDKs. There is also information in appendix form describing
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500208how you can build, install, and modify an SDK.