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