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