blob: 66b12cdff9eb3add1c7706edaf996adede2d9445 [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
11Software Development Kit (eSDK) manual. This manual provides information
12that explains how to use both the Yocto Project extensible and standard
13SDKs to develop applications and images.
14
15.. note::
16
17 Prior to the 2.0 Release of the Yocto Project, application
18 development was primarily accomplished through the use of the
19 Application Development Toolkit (ADT) and the availability of
20 stand-alone cross-development toolchains and other tools. With the
21 2.1 Release of the Yocto Project, application development has
22 transitioned to within a tool-rich extensible SDK and the more
23 traditional standard SDK.
24
25All SDKs consist of the following:
26
27- *Cross-Development Toolchain*: This toolchain contains a compiler,
28 debugger, and various miscellaneous tools.
29
30- *Libraries, Headers, and Symbols*: The libraries, headers, and
31 symbols are specific to the image (i.e. they match the image).
32
33- *Environment Setup Script*: This ``*.sh`` file, once run, sets up the
34 cross-development environment by defining variables and preparing for
35 SDK use.
36
37Additionally, an extensible SDK has tools that allow you to easily add
38new applications and libraries to an image, modify the source of an
39existing component, test changes on the target hardware, and easily
40integrate an application into the :term:`OpenEmbedded Build System`.
41
42You can use an SDK to independently develop and test code that is
43destined to run on some target machine. SDKs are completely
44self-contained. The binaries are linked against their own copy of
45``libc``, which results in no dependencies on the target system. To
46achieve this, the pointer to the dynamic loader is configured at install
47time since that path cannot be dynamically altered. This is the reason
48for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext``
49archives.
50
51Another feature for the SDKs is that only one set of cross-compiler
52toolchain binaries are produced for any given architecture. This feature
53takes advantage of the fact that the target hardware can be passed to
54``gcc`` as a set of compiler options. Those options are set up by the
55environment script and contained in variables such as
56:term:`CC` and
57:term:`LD`. This reduces the space needed
58for the tools. Understand, however, that every target still needs a
59sysroot because those binaries are target-specific.
60
61The SDK development environment consists of the following:
62
63- The self-contained SDK, which is an architecture-specific
64 cross-toolchain and matching sysroots (target and native) all built
65 by the OpenEmbedded build system (e.g. the SDK). The toolchain and
66 sysroots are based on a :term:`Metadata`
67 configuration and extensions, which allows you to cross-develop on
68 the host machine for the target hardware. Additionally, the
69 extensible SDK contains the ``devtool`` functionality.
70
71- The Quick EMUlator (QEMU), which lets you simulate target hardware.
72 QEMU is not literally part of the SDK. You must build and include
73 this emulator separately. However, QEMU plays an important role in
74 the development process that revolves around use of the SDK.
75
76In summary, the extensible and standard SDK share many features.
77However, the extensible SDK has powerful development tools to help you
78more quickly develop applications. Following is a table that summarizes
79the primary differences between the standard and extensible SDK types
80when considering which to build:
81
82+-----------------------+-----------------------+-----------------------+
83| *Feature* | *Standard SDK* | *Extensible SDK* |
84+=======================+=======================+=======================+
Andrew Geissler4c19ea12020-10-27 13:52:24 -050085| Toolchain | Yes | Yes [1]_ |
Andrew Geisslerc9f78652020-09-18 14:11:35 -050086+-----------------------+-----------------------+-----------------------+
Andrew Geissler4c19ea12020-10-27 13:52:24 -050087| Debugger | Yes | Yes [1]_ |
Andrew Geisslerc9f78652020-09-18 14:11:35 -050088+-----------------------+-----------------------+-----------------------+
89| Size | 100+ MBytes | 1+ GBytes (or 300+ |
90| | | MBytes for minimal |
91| | | w/toolchain) |
92+-----------------------+-----------------------+-----------------------+
93| ``devtool`` | No | Yes |
94+-----------------------+-----------------------+-----------------------+
95| Build Images | No | Yes |
96+-----------------------+-----------------------+-----------------------+
97| Updateable | No | Yes |
98+-----------------------+-----------------------+-----------------------+
Andrew Geissler4c19ea12020-10-27 13:52:24 -050099| Managed Sysroot [2]_ | No | Yes |
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500100+-----------------------+-----------------------+-----------------------+
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500101| Installed Packages | No [3]_ | Yes [4]_ |
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500102+-----------------------+-----------------------+-----------------------+
103| Construction | Packages | Shared State |
104+-----------------------+-----------------------+-----------------------+
105
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500106.. [1] Extensible SDK contains the toolchain and debugger if :term:`SDK_EXT_TYPE`
107 is "full" or :term:`SDK_INCLUDE_TOOLCHAIN` is "1", which is the default.
108.. [2] Sysroot is managed through the use of ``devtool``. Thus, it is less
109 likely that you will corrupt your SDK sysroot when you try to add
110 additional libraries.
111.. [3] You can add runtime package management to the standard SDK but it is not
112 supported by default.
113.. [4] You must build and make the shared state available to extensible SDK
114 users for "packages" you want to enable users to install.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500115
116The Cross-Development Toolchain
117-------------------------------
118
119The :term:`Cross-Development Toolchain` consists
120of a cross-compiler, cross-linker, and cross-debugger that are used to
121develop user-space applications for targeted hardware. Additionally, for
122an extensible SDK, the toolchain also has built-in ``devtool``
123functionality. This toolchain is created by running a SDK installer
124script or through a :term:`Build Directory` that is based on
125your metadata configuration or extension for your targeted device. The
126cross-toolchain works with a matching target sysroot.
127
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500128Sysroots
129--------
130
131The native and target sysroots contain needed headers and libraries for
132generating binaries that run on the target architecture. The target
133sysroot is based on the target root filesystem image that is built by
134the OpenEmbedded build system and uses the same metadata configuration
135used to build the cross-toolchain.
136
137The QEMU Emulator
138-----------------
139
140The QEMU emulator allows you to simulate your hardware while running
141your application or image. QEMU is not part of the SDK but is made
142available a number of different ways:
143
144- If you have cloned the ``poky`` Git repository to create a
145 :term:`Source Directory` and you have
146 sourced the environment setup script, QEMU is installed and
147 automatically available.
148
149- If you have downloaded a Yocto Project release and unpacked it to
150 create a Source Directory and you have sourced the environment setup
151 script, QEMU is installed and automatically available.
152
153- If you have installed the cross-toolchain tarball and you have
154 sourced the toolchain's setup environment script, QEMU is also
155 installed and automatically available.
156
157SDK Development Model
158=====================
159
160Fundamentally, the SDK fits into the development process as follows:
161
162.. image:: figures/sdk-environment.png
163 :align: center
164
165The SDK is installed on any machine and can be used to develop applications,
166images, and kernels. An SDK can even be used by a QA Engineer or Release
167Engineer. The fundamental concept is that the machine that has the SDK
168installed does not have to be associated with the machine that has the
169Yocto Project installed. A developer can independently compile and test
170an object on their machine and then, when the object is ready for
171integration into an image, they can simply make it available to the
172machine that has the Yocto Project. Once the object is available, the
173image can be rebuilt using the Yocto Project to produce the modified
174image.
175
176You just need to follow these general steps:
177
1781. *Install the SDK for your target hardware:* For information on how to
179 install the SDK, see the "`Installing the
180 SDK <#sdk-installing-the-sdk>`__" section.
181
1822. *Download or Build the Target Image:* The Yocto Project supports
183 several target architectures and has many pre-built kernel images and
184 root filesystem images.
185
186 If you are going to develop your application on hardware, go to the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600187 :yocto_dl:`machines </releases/yocto/yocto-&DISTRO;/machines/>` download area and choose a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500188 target machine area from which to download the kernel image and root
189 filesystem. This download area could have several files in it that
190 support development using actual hardware. For example, the area
191 might contain ``.hddimg`` files that combine the kernel image with
192 the filesystem, boot loaders, and so forth. Be sure to get the files
193 you need for your particular development process.
194
195 If you are going to develop your application and then run and test it
196 using the QEMU emulator, go to the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600197 :yocto_dl:`machines/qemu </releases/yocto/yocto-&DISTRO;/machines/qemu>` download area. From this
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500198 area, go down into the directory for your target architecture (e.g.
199 ``qemux86_64`` for an Intel-based 64-bit architecture). Download the
200 kernel, root filesystem, and any other files you need for your
201 process.
202
203 .. note::
204
205 To use the root filesystem in QEMU, you need to extract it. See
206 the "
207 Extracting the Root Filesystem
208 " section for information on how to extract the root filesystem.
209
2103. *Develop and Test your Application:* At this point, you have the
211 tools to develop your application. If you need to separately install
212 and use the QEMU emulator, you can go to `QEMU Home
213 Page <http://wiki.qemu.org/Main_Page>`__ to download and learn about
Andrew Geissler09209ee2020-12-13 08:44:15 -0600214 the emulator. See the ":doc:`/dev-manual/qemu`" chapter in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500215 Yocto Project Development Tasks Manual for information on using QEMU
216 within the Yocto Project.
217
218The remainder of this manual describes how to use the extensible and
219standard SDKs. Information also exists in appendix form that describes
220how you can build, install, and modify an SDK.