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