diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-intro.rst')
-rw-r--r-- | documentation/sdk-manual/sdk-intro.rst | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/documentation/sdk-manual/sdk-intro.rst b/documentation/sdk-manual/sdk-intro.rst new file mode 100644 index 0000000000..82b7bcf3cf --- /dev/null +++ b/documentation/sdk-manual/sdk-intro.rst | |||
@@ -0,0 +1,231 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ************ | ||
4 | Introduction | ||
5 | ************ | ||
6 | |||
7 | .. _sdk-manual-intro: | ||
8 | |||
9 | eSDK Introduction | ||
10 | ================= | ||
11 | |||
12 | Welcome to the Yocto Project Application Development and the Extensible | ||
13 | Software Development Kit (eSDK) manual. This manual provides information | ||
14 | that explains how to use both the Yocto Project extensible and standard | ||
15 | SDKs 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 | |||
27 | All 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 | |||
39 | Additionally, an extensible SDK has tools that allow you to easily add | ||
40 | new applications and libraries to an image, modify the source of an | ||
41 | existing component, test changes on the target hardware, and easily | ||
42 | integrate an application into the :term:`OpenEmbedded Build System`. | ||
43 | |||
44 | You can use an SDK to independently develop and test code that is | ||
45 | destined to run on some target machine. SDKs are completely | ||
46 | self-contained. The binaries are linked against their own copy of | ||
47 | ``libc``, which results in no dependencies on the target system. To | ||
48 | achieve this, the pointer to the dynamic loader is configured at install | ||
49 | time since that path cannot be dynamically altered. This is the reason | ||
50 | for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext`` | ||
51 | archives. | ||
52 | |||
53 | Another feature for the SDKs is that only one set of cross-compiler | ||
54 | toolchain binaries are produced for any given architecture. This feature | ||
55 | takes 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 | ||
57 | environment script and contained in variables such as | ||
58 | :term:`CC` and | ||
59 | :term:`LD`. This reduces the space needed | ||
60 | for the tools. Understand, however, that every target still needs a | ||
61 | sysroot because those binaries are target-specific. | ||
62 | |||
63 | The 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 | |||
78 | In summary, the extensible and standard SDK share many features. | ||
79 | However, the extensible SDK has powerful development tools to help you | ||
80 | more quickly develop applications. Following is a table that summarizes | ||
81 | the primary differences between the standard and extensible SDK types | ||
82 | when 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" | ||
110 | or | ||
111 | :term:`SDK_INCLUDE_TOOLCHAIN` | ||
112 | is "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 | ||
116 | sysroot when you try to add additional libraries. | ||
117 | |||
118 | \*\*\* You can add | ||
119 | runtime package management to the standard SDK but it is not supported | ||
120 | by default. | ||
121 | |||
122 | \*\*\*\* You must build and make the shared state available to | ||
123 | extensible SDK users for "packages" you want to enable users to install. | ||
124 | |||
125 | The Cross-Development Toolchain | ||
126 | ------------------------------- | ||
127 | |||
128 | The :term:`Cross-Development Toolchain` consists | ||
129 | of a cross-compiler, cross-linker, and cross-debugger that are used to | ||
130 | develop user-space applications for targeted hardware. Additionally, for | ||
131 | an extensible SDK, the toolchain also has built-in ``devtool`` | ||
132 | functionality. This toolchain is created by running a SDK installer | ||
133 | script or through a :term:`Build Directory` that is based on | ||
134 | your metadata configuration or extension for your targeted device. The | ||
135 | cross-toolchain works with a matching target sysroot. | ||
136 | |||
137 | .. _sysroot: | ||
138 | |||
139 | Sysroots | ||
140 | -------- | ||
141 | |||
142 | The native and target sysroots contain needed headers and libraries for | ||
143 | generating binaries that run on the target architecture. The target | ||
144 | sysroot is based on the target root filesystem image that is built by | ||
145 | the OpenEmbedded build system and uses the same metadata configuration | ||
146 | used to build the cross-toolchain. | ||
147 | |||
148 | The QEMU Emulator | ||
149 | ----------------- | ||
150 | |||
151 | The QEMU emulator allows you to simulate your hardware while running | ||
152 | your application or image. QEMU is not part of the SDK but is made | ||
153 | available 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 | |||
168 | SDK Development Model | ||
169 | ===================== | ||
170 | |||
171 | Fundamentally, the SDK fits into the development process as follows: | ||
172 | |||
173 | .. image:: figures/sdk-environment.png | ||
174 | :align: center | ||
175 | |||
176 | The SDK is installed on any machine and can be used to develop applications, | ||
177 | images, and kernels. An SDK can even be used by a QA Engineer or Release | ||
178 | Engineer. The fundamental concept is that the machine that has the SDK | ||
179 | installed does not have to be associated with the machine that has the | ||
180 | Yocto Project installed. A developer can independently compile and test | ||
181 | an object on their machine and then, when the object is ready for | ||
182 | integration into an image, they can simply make it available to the | ||
183 | machine that has the Yocto Project. Once the object is available, the | ||
184 | image can be rebuilt using the Yocto Project to produce the modified | ||
185 | image. | ||
186 | |||
187 | You just need to follow these general steps: | ||
188 | |||
189 | 1. *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 | |||
193 | 2. *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 | |||
221 | 3. *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 | |||
229 | The remainder of this manual describes how to use the extensible and | ||
230 | standard SDKs. Information also exists in appendix form that describes | ||
231 | how you can build, install, and modify an SDK. | ||