Andrew Geissler | 4873add | 2020-11-02 18:44:49 -0600 | [diff] [blame^] | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| 4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> |
| 5 | |
| 6 | <chapter id='sdk-intro'> |
| 7 | <title>Introduction</title> |
| 8 | |
| 9 | <section id='sdk-manual-intro'> |
| 10 | <title>Introduction</title> |
| 11 | |
| 12 | <para> |
| 13 | Welcome to the Yocto Project Application Development and the |
| 14 | Extensible Software Development Kit (eSDK) manual. |
| 15 | This manual provides information that explains how to use both the |
| 16 | Yocto Project extensible and standard SDKs to develop |
| 17 | applications and images. |
| 18 | <note> |
| 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 |
| 22 | of stand-alone cross-development toolchains and other tools. |
| 23 | With the 2.1 Release of the Yocto Project, application development |
| 24 | has transitioned to within a tool-rich extensible SDK and the more |
| 25 | traditional standard SDK. |
| 26 | </note> |
| 27 | </para> |
| 28 | |
| 29 | <para> |
| 30 | All SDKs consist of the following: |
| 31 | <itemizedlist> |
| 32 | <listitem><para> |
| 33 | <emphasis>Cross-Development Toolchain</emphasis>: |
| 34 | This toolchain contains a compiler, debugger, and various |
| 35 | miscellaneous tools. |
| 36 | </para></listitem> |
| 37 | <listitem><para> |
| 38 | <emphasis>Libraries, Headers, and Symbols</emphasis>: |
| 39 | The libraries, headers, and symbols are specific to the image |
| 40 | (i.e. they match the image). |
| 41 | </para></listitem> |
| 42 | <listitem><para> |
| 43 | <emphasis>Environment Setup Script</emphasis>: |
| 44 | This <filename>*.sh</filename> file, once run, sets up the |
| 45 | cross-development environment by defining variables and |
| 46 | preparing for SDK use. |
| 47 | </para></listitem> |
| 48 | </itemizedlist> |
| 49 | </para> |
| 50 | |
| 51 | <para> |
| 52 | Additionally, an extensible SDK has tools that allow you to easily add |
| 53 | new applications and libraries to an image, modify the source of an |
| 54 | existing component, test changes on the target hardware, and easily |
| 55 | integrate an application into the |
| 56 | <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>. |
| 57 | </para> |
| 58 | |
| 59 | <para> |
| 60 | You can use an SDK to independently develop and test code |
| 61 | that is destined to run on some target machine. |
| 62 | SDKs are completely self-contained. |
| 63 | The binaries are linked against their own copy of |
| 64 | <filename>libc</filename>, which results in no dependencies |
| 65 | on the target system. |
| 66 | To achieve this, the pointer to the dynamic loader is |
| 67 | configured at install time since that path cannot be dynamically |
| 68 | altered. |
| 69 | This is the reason for a wrapper around the |
| 70 | <filename>populate_sdk</filename> and |
| 71 | <filename>populate_sdk_ext</filename> archives. |
| 72 | </para> |
| 73 | |
| 74 | <para> |
| 75 | Another feature for the SDKs is that only one set of cross-compiler |
| 76 | toolchain binaries are produced for any given architecture. |
| 77 | This feature takes advantage of the fact that the target hardware can |
| 78 | be passed to <filename>gcc</filename> as a set of compiler options. |
| 79 | Those options are set up by the environment script and contained in |
| 80 | variables such as |
| 81 | <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> |
| 82 | and |
| 83 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>. |
| 84 | This reduces the space needed for the tools. |
| 85 | Understand, however, that every target still needs a sysroot because |
| 86 | those binaries are target-specific. |
| 87 | </para> |
| 88 | |
| 89 | <para> |
| 90 | The SDK development environment consists of the following: |
| 91 | <itemizedlist> |
| 92 | <listitem><para> |
| 93 | The self-contained SDK, which is an |
| 94 | architecture-specific cross-toolchain and |
| 95 | matching sysroots (target and native) all built by the |
| 96 | OpenEmbedded build system (e.g. the SDK). |
| 97 | The toolchain and sysroots are based on a |
| 98 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> |
| 99 | configuration and extensions, |
| 100 | which allows you to cross-develop on the host machine for the |
| 101 | target hardware. |
| 102 | Additionally, the extensible SDK contains the |
| 103 | <filename>devtool</filename> functionality. |
| 104 | </para></listitem> |
| 105 | <listitem><para> |
| 106 | The Quick EMUlator (QEMU), which lets you simulate |
| 107 | target hardware. |
| 108 | QEMU is not literally part of the SDK. |
| 109 | You must build and include this emulator separately. |
| 110 | However, QEMU plays an important role in the development |
| 111 | process that revolves around use of the SDK. |
| 112 | </para></listitem> |
| 113 | </itemizedlist> |
| 114 | </para> |
| 115 | |
| 116 | <para> |
| 117 | In summary, the extensible and standard SDK share many features. |
| 118 | However, the extensible SDK has powerful development tools to help you |
| 119 | more quickly develop applications. |
| 120 | Following is a table that summarizes the primary differences between |
| 121 | the standard and extensible SDK types when considering which to |
| 122 | build: |
| 123 | <informaltable frame='none'> |
| 124 | <tgroup cols='3' align='left' colsep='1' rowsep='1'> |
| 125 | <colspec colname='c1' colwidth='1*'/> |
| 126 | <colspec colname='c2' colwidth='1*'/> |
| 127 | <colspec colname='c3' colwidth='1*'/> |
| 128 | <thead> |
| 129 | <row> |
| 130 | <entry align="left"><emphasis>Feature</emphasis></entry> |
| 131 | <entry align="left"><emphasis>Standard SDK</emphasis></entry> |
| 132 | <entry align="left"><emphasis>Extensible SDK</emphasis></entry> |
| 133 | </row> |
| 134 | </thead> |
| 135 | <tbody> |
| 136 | <row> |
| 137 | <entry align="left">Toolchain</entry> |
| 138 | <entry align="left">Yes</entry> |
| 139 | <entry align="left">Yes*</entry> |
| 140 | </row> |
| 141 | <row> |
| 142 | <entry align="left">Debugger</entry> |
| 143 | <entry align="left">Yes</entry> |
| 144 | <entry align="left">Yes*</entry> |
| 145 | </row> |
| 146 | <row> |
| 147 | <entry align="left">Size</entry> |
| 148 | <entry align="left">100+ MBytes</entry> |
| 149 | <entry align="left">1+ GBytes (or 300+ MBytes for minimal w/toolchain)</entry> |
| 150 | </row> |
| 151 | <row> |
| 152 | <entry align="left"><filename>devtool</filename></entry> |
| 153 | <entry align="left">No</entry> |
| 154 | <entry align="left">Yes</entry> |
| 155 | </row> |
| 156 | <row> |
| 157 | <entry align="left">Build Images</entry> |
| 158 | <entry align="left">No</entry> |
| 159 | <entry align="left">Yes</entry> |
| 160 | </row> |
| 161 | <row> |
| 162 | <entry align="left">Updateable</entry> |
| 163 | <entry align="left">No</entry> |
| 164 | <entry align="left">Yes</entry> |
| 165 | </row> |
| 166 | <row> |
| 167 | <entry align="left">Managed Sysroot**</entry> |
| 168 | <entry align="left">No</entry> |
| 169 | <entry align="left">Yes</entry> |
| 170 | </row> |
| 171 | <row> |
| 172 | <entry align="left">Installed Packages</entry> |
| 173 | <entry align="left">No***</entry> |
| 174 | <entry align="left">Yes****</entry> |
| 175 | </row> |
| 176 | <row> |
| 177 | <entry align="left">Construction</entry> |
| 178 | <entry align="left">Packages</entry> |
| 179 | <entry align="left">Shared State</entry> |
| 180 | </row> |
| 181 | </tbody> |
| 182 | </tgroup> |
| 183 | </informaltable> |
| 184 | <literallayout class='monospaced'> |
| 185 | * Extensible SDK contains the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default. |
| 186 | |
| 187 | ** Sysroot is managed through the use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries. |
| 188 | |
| 189 | *** You can add runtime package management to the standard SDK but it is not supported by default. |
| 190 | |
| 191 | **** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install. |
| 192 | </literallayout> |
| 193 | </para> |
| 194 | |
| 195 | <section id='the-cross-development-toolchain'> |
| 196 | <title>The Cross-Development Toolchain</title> |
| 197 | |
| 198 | <para> |
| 199 | The |
| 200 | <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink> |
| 201 | consists of a cross-compiler, cross-linker, and cross-debugger |
| 202 | that are used to develop user-space applications for targeted |
| 203 | hardware. |
| 204 | Additionally, for an extensible SDK, the toolchain also has |
| 205 | built-in <filename>devtool</filename> functionality. |
| 206 | This toolchain is created by running a SDK installer script |
| 207 | or through a |
| 208 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> |
| 209 | that is based on your metadata configuration or extension for |
| 210 | your targeted device. |
| 211 | The cross-toolchain works with a matching target sysroot. |
| 212 | </para> |
| 213 | </section> |
| 214 | |
| 215 | <section id='sysroot'> |
| 216 | <title>Sysroots</title> |
| 217 | |
| 218 | <para> |
| 219 | The native and target sysroots contain needed headers and libraries |
| 220 | for generating binaries that run on the target architecture. |
| 221 | The target sysroot is based on the target root filesystem image |
| 222 | that is built by the OpenEmbedded build system and uses the same |
| 223 | metadata configuration used to build the cross-toolchain. |
| 224 | </para> |
| 225 | </section> |
| 226 | |
| 227 | <section id='the-qemu-emulator'> |
| 228 | <title>The QEMU Emulator</title> |
| 229 | |
| 230 | <para> |
| 231 | The QEMU emulator allows you to simulate your hardware while |
| 232 | running your application or image. |
| 233 | QEMU is not part of the SDK but is made available a number of |
| 234 | different ways: |
| 235 | <itemizedlist> |
| 236 | <listitem><para> |
| 237 | If you have cloned the <filename>poky</filename> Git |
| 238 | repository to create a |
| 239 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> |
| 240 | and you have sourced the environment setup script, QEMU is |
| 241 | installed and automatically available. |
| 242 | </para></listitem> |
| 243 | <listitem><para> |
| 244 | If you have downloaded a Yocto Project release and unpacked |
| 245 | it to create a Source Directory and you have sourced the |
| 246 | environment setup script, QEMU is installed and |
| 247 | automatically available. |
| 248 | </para></listitem> |
| 249 | <listitem><para> |
| 250 | If you have installed the cross-toolchain tarball and you |
| 251 | have sourced the toolchain's setup environment script, QEMU |
| 252 | is also installed and automatically available. |
| 253 | </para></listitem> |
| 254 | </itemizedlist> |
| 255 | </para> |
| 256 | </section> |
| 257 | </section> |
| 258 | |
| 259 | <section id='sdk-development-model'> |
| 260 | <title>SDK Development Model</title> |
| 261 | |
| 262 | <para> |
| 263 | Fundamentally, the SDK fits into the development process as follows: |
| 264 | <imagedata fileref="figures/sdk-environment.png" align="center" width="6in" depth="5in" scalefit="100" /> |
| 265 | The SDK is installed on any machine and can be used to develop |
| 266 | applications, images, and kernels. |
| 267 | An SDK can even be used by a QA Engineer or Release Engineer. |
| 268 | The fundamental concept is that the machine that has the SDK installed |
| 269 | does not have to be associated with the machine that has the |
| 270 | Yocto Project installed. |
| 271 | A developer can independently compile and test an object on their |
| 272 | machine and then, when the object is ready for integration into an |
| 273 | image, they can simply make it available to the machine that has the |
| 274 | Yocto Project. |
| 275 | Once the object is available, the image can be rebuilt using the |
| 276 | Yocto Project to produce the modified image. |
| 277 | </para> |
| 278 | |
| 279 | <para> |
| 280 | You just need to follow these general steps: |
| 281 | <orderedlist> |
| 282 | <listitem><para> |
| 283 | <emphasis>Install the SDK for your target hardware:</emphasis> |
| 284 | For information on how to install the SDK, see the |
| 285 | "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" |
| 286 | section. |
| 287 | </para></listitem> |
| 288 | <listitem><para> |
| 289 | <emphasis>Download or Build the Target Image:</emphasis> |
| 290 | The Yocto Project supports several target architectures |
| 291 | and has many pre-built kernel images and root filesystem |
| 292 | images.</para> |
| 293 | |
| 294 | <para>If you are going to develop your application on |
| 295 | hardware, go to the |
| 296 | <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> |
| 297 | download area and choose a target machine area |
| 298 | from which to download the kernel image and root filesystem. |
| 299 | This download area could have several files in it that |
| 300 | support development using actual hardware. |
| 301 | For example, the area might contain |
| 302 | <filename>.hddimg</filename> files that combine the |
| 303 | kernel image with the filesystem, boot loaders, and |
| 304 | so forth. |
| 305 | Be sure to get the files you need for your particular |
| 306 | development process.</para> |
| 307 | |
| 308 | <para>If you are going to develop your application and |
| 309 | then run and test it using the QEMU emulator, go to the |
| 310 | <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink> |
| 311 | download area. |
| 312 | From this area, go down into the directory for your |
| 313 | target architecture (e.g. <filename>qemux86_64</filename> |
| 314 | for an <trademark class='registered'>Intel</trademark>-based |
| 315 | 64-bit architecture). |
| 316 | Download the kernel, root filesystem, and any other files you |
| 317 | need for your process. |
| 318 | <note> |
| 319 | To use the root filesystem in QEMU, you need to extract it. |
| 320 | See the |
| 321 | "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" |
| 322 | section for information on how to extract the root |
| 323 | filesystem. |
| 324 | </note> |
| 325 | </para></listitem> |
| 326 | <listitem><para> |
| 327 | <emphasis>Develop and Test your Application:</emphasis> |
| 328 | At this point, you have the tools to develop your application. |
| 329 | If you need to separately install and use the QEMU emulator, |
| 330 | you can go to |
| 331 | <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink> |
| 332 | to download and learn about the emulator. |
| 333 | See the |
| 334 | "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" |
| 335 | chapter in the Yocto Project Development Tasks Manual |
| 336 | for information on using QEMU within the Yocto |
| 337 | Project. |
| 338 | </para></listitem> |
| 339 | </orderedlist> |
| 340 | </para> |
| 341 | |
| 342 | <para> |
| 343 | The remainder of this manual describes how to use the extensible |
| 344 | and standard SDKs. |
| 345 | Information also exists in appendix form that describes how you can |
| 346 | build, install, and modify an SDK. |
| 347 | </para> |
| 348 | </section> |
| 349 | |
| 350 | </chapter> |
| 351 | <!-- |
| 352 | vim: expandtab tw=80 ts=4 |
| 353 | --> |