1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3***************** 4Obtaining the SDK 5***************** 6 7Working with the SDK components directly in a Yocto build 8========================================================= 9 10Please refer to section 11":ref:`sdk-manual/extensible:Setting up the Extensible SDK environment directly in a Yocto build`" 12 13Note that to use this feature effectively either a powerful build 14machine, or a well-functioning sstate cache infrastructure is required: 15otherwise significant time could be spent waiting for components to be built 16by BitBake from source code. 17 18Working with standalone SDK Installers 19====================================== 20 21Locating Pre-Built SDK Installers 22--------------------------------- 23 24You can use existing, pre-built toolchains by locating and running an 25SDK installer script that ships with the Yocto Project. Using this 26method, you select and download an architecture-specific SDK installer 27and then run the script to hand-install the toolchain. 28 29Follow these steps to locate and hand-install the toolchain: 30 311. *Go to the Installers Directory:* Go to 32 :yocto_dl:`/releases/yocto/yocto-&DISTRO;/toolchain/` 33 342. *Open the Folder for Your Build Host:* Open the folder that matches 35 your :term:`Build Host` (i.e. 36 ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines). 37 383. *Locate and Download the SDK Installer:* You need to find and 39 download the installer appropriate for your build host, target 40 hardware, and image type. 41 42 The installer files (``*.sh``) follow this naming convention:: 43 44 poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh 45 46 Where: 47 host_system is a string representing your development system: 48 "i686" or "x86_64" 49 50 type is a string representing the image: 51 "sato" or "minimal" 52 53 arch is a string representing the target architecture: 54 "aarch64", "armv5e", "core2-64", "cortexa8hf-neon", "i586", "mips32r2", 55 "mips64", or "ppc7400" 56 57 release is the version of Yocto Project. 58 59 NOTE: 60 The standard SDK installer does not have the "-ext" string as 61 part of the filename. 62 63 64 The toolchains provided by the Yocto 65 Project are based off of the ``core-image-sato`` and 66 ``core-image-minimal`` images and contain libraries appropriate for 67 developing against those images. 68 69 For example, if your build host is a 64-bit x86 system and you need 70 an extended SDK for a 64-bit core2 target, go into the ``x86_64`` 71 folder and download the following installer:: 72 73 poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh 74 754. *Run the Installer:* Be sure you have execution privileges and run 76 the installer. Following is an example from the ``Downloads`` 77 directory:: 78 79 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh 80 81 During execution of the script, you choose the root location for the 82 toolchain. See the 83 ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`" 84 section and the 85 ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`" 86 section for more information. 87 88Building an SDK Installer 89------------------------- 90 91As an alternative to locating and downloading an SDK installer, you can 92build the SDK installer. Follow these steps: 93 941. *Set Up the Build Environment:* Be sure you are set up to use BitBake 95 in a shell. See the ":ref:`dev-manual/start:preparing the build host`" section 96 in the Yocto Project Development Tasks Manual for information on how 97 to get a build host ready that is either a native Linux machine or a 98 machine that uses CROPS. 99 1002. *Clone the ``poky`` Repository:* You need to have a local copy of the 101 Yocto Project :term:`Source Directory` 102 (i.e. a local 103 ``poky`` repository). See the ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and 104 possibly the ":ref:`dev-manual/start:checking out by branch in poky`" and 105 ":ref:`dev-manual/start:checking out by tag in poky`" sections 106 all in the Yocto Project Development Tasks Manual for information on 107 how to clone the ``poky`` repository and check out the appropriate 108 branch for your work. 109 1103. *Initialize the Build Environment:* While in the root directory of 111 the Source Directory (i.e. ``poky``), run the 112 :ref:`structure-core-script` environment 113 setup script to define the OpenEmbedded build environment on your 114 build host. 115 :: 116 117 $ source oe-init-build-env 118 119 Among other things, the script 120 creates the :term:`Build Directory`, 121 which is 122 ``build`` in this case and is located in the Source Directory. After 123 the script runs, your current working directory is set to the 124 ``build`` directory. 125 1264. *Make Sure You Are Building an Installer for the Correct Machine:* 127 Check to be sure that your 128 :term:`MACHINE` variable in the 129 ``local.conf`` file in your Build Directory matches the architecture 130 for which you are building. 131 1325. *Make Sure Your SDK Machine is Correctly Set:* If you are building a 133 toolchain designed to run on an architecture that differs from your 134 current development host machine (i.e. the build host), be sure that 135 the :term:`SDKMACHINE` variable 136 in the ``local.conf`` file in your Build Directory is correctly set. 137 138 .. note:: 139 140 If you are building an SDK installer for the Extensible SDK, the 141 SDKMACHINE 142 value must be set for the architecture of the machine you are 143 using to build the installer. If 144 SDKMACHINE 145 is not set appropriately, the build fails and provides an error 146 message similar to the following:: 147 148 The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is 149 set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64). 150 Unable to continue. 151 152 1536. *Build the SDK Installer:* To build the SDK installer for a standard 154 SDK and populate the SDK image, use the following command form. Be 155 sure to replace ``image`` with an image (e.g. "core-image-sato"):: 156 157 $ bitbake image -c populate_sdk 158 159 You can do the same for the extensible SDK using this command form:: 160 161 $ bitbake image -c populate_sdk_ext 162 163 These commands produce an SDK installer that contains the sysroot 164 that matches your target root filesystem. 165 166 When the ``bitbake`` command completes, the SDK installer will be in 167 ``tmp/deploy/sdk`` in the Build Directory. 168 169 .. note:: 170 171 - By default, the previous BitBake command does not build static 172 binaries. If you want to use the toolchain to build these types 173 of libraries, you need to be sure your SDK has the appropriate 174 static development libraries. Use the 175 :term:`TOOLCHAIN_TARGET_TASK` 176 variable inside your ``local.conf`` file before building the 177 SDK installer. Doing so ensures that the eventual SDK 178 installation process installs the appropriate library packages 179 as part of the SDK. Following is an example using ``libc`` 180 static development libraries: TOOLCHAIN_TARGET_TASK:append = " 181 libc-staticdev" 182 1837. *Run the Installer:* You can now run the SDK installer from 184 ``tmp/deploy/sdk`` in the Build Directory. Following is an example:: 185 186 $ cd poky/build/tmp/deploy/sdk 187 $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh 188 189 During execution of the script, you choose the root location for the 190 toolchain. See the 191 ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`" 192 section and the 193 ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`" 194 section for more information. 195 196Extracting the Root Filesystem 197============================== 198 199After installing the toolchain, for some use cases you might need to 200separately extract a root filesystem: 201 202- You want to boot the image using NFS. 203 204- You want to use the root filesystem as the target sysroot. 205 206- You want to develop your target application using the root filesystem 207 as the target sysroot. 208 209Follow these steps to extract the root filesystem: 210 2111. *Locate and Download the Tarball for the Pre-Built Root Filesystem 212 Image File:* You need to find and download the root filesystem image 213 file that is appropriate for your target system. These files are kept 214 in machine-specific folders in the 215 :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>` 216 in the "machines" directory. 217 218 The machine-specific folders of the "machines" directory contain 219 tarballs (``*.tar.bz2``) for supported machines. These directories 220 also contain flattened root filesystem image files (``*.ext4``), 221 which you can use with QEMU directly. 222 223 The pre-built root filesystem image files follow these naming 224 conventions:: 225 226 core-image-profile-arch.tar.bz2 227 228 Where: 229 profile is the filesystem image's profile: 230 lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs, 231 sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on 232 these types of image profiles, see the "Images" chapter in 233 the Yocto Project Reference Manual. 234 235 arch is a string representing the target architecture: 236 beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb, 237 genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*. 238 239 The root filesystems 240 provided by the Yocto Project are based off of the 241 ``core-image-sato`` and ``core-image-minimal`` images. 242 243 For example, if you plan on using a BeagleBone device as your target 244 hardware and your image is a ``core-image-sato-sdk`` image, you can 245 download the following file:: 246 247 core-image-sato-sdk-beaglebone-yocto.tar.bz2 248 2492. *Initialize the Cross-Development Environment:* You must ``source`` 250 the cross-development environment setup script to establish necessary 251 environment variables. 252 253 This script is located in the top-level directory in which you 254 installed the toolchain (e.g. ``poky_sdk``). 255 256 Following is an example based on the toolchain installed in the 257 ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section:: 258 259 $ source poky_sdk/environment-setup-core2-64-poky-linux 260 2613. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk`` 262 command and provide the root filesystem image. 263 264 Following is an example command that extracts the root filesystem 265 from a previously built root filesystem image that was downloaded 266 from the :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>`. 267 This command extracts the root filesystem into the ``core2-64-sato`` 268 directory:: 269 270 $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato 271 272 You could now point to the target sysroot at ``beaglebone-sato``. 273 274Installed Standard SDK Directory Structure 275========================================== 276 277The following figure shows the resulting directory structure after you 278install the Standard SDK by running the ``*.sh`` SDK installation 279script: 280 281.. image:: figures/sdk-installed-standard-sdk-directory.png 282 :scale: 100% 283 284The installed SDK consists of an environment setup script for the SDK, a 285configuration file for the target, a version file for the target, and 286the root filesystem (``sysroots``) needed to develop objects for the 287target system. 288 289Within the figure, italicized text is used to indicate replaceable 290portions of the file or directory name. For example, install_dir/version 291is the directory where the SDK is installed. By default, this directory 292is ``/opt/poky/``. And, version represents the specific snapshot of the 293SDK (e.g. &DISTRO;). Furthermore, target represents the target architecture 294(e.g. ``i586``) and host represents the development system's 295architecture (e.g. ``x86_64``). Thus, the complete names of the two 296directories within the ``sysroots`` could be ``i586-poky-linux`` and 297``x86_64-pokysdk-linux`` for the target and host, respectively. 298 299Installed Extensible SDK Directory Structure 300============================================ 301 302The following figure shows the resulting directory structure after you 303install the Extensible SDK by running the ``*.sh`` SDK installation 304script: 305 306.. image:: figures/sdk-installed-extensible-sdk-directory.png 307 :scale: 80% 308 :align: center 309 310The installed directory structure for the extensible SDK is quite 311different than the installed structure for the standard SDK. The 312extensible SDK does not separate host and target parts in the same 313manner as does the standard SDK. The extensible SDK uses an embedded 314copy of the OpenEmbedded build system, which has its own sysroots. 315 316Of note in the directory structure are an environment setup script for 317the SDK, a configuration file for the target, a version file for the 318target, and log files for the OpenEmbedded build system preparation 319script run by the installer and BitBake. 320 321Within the figure, italicized text is used to indicate replaceable 322portions of the file or directory name. For example, install_dir is the 323directory where the SDK is installed, which is ``poky_sdk`` by default, 324and target represents the target architecture (e.g. ``i586``). 325
