1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3************************ 4Using the Extensible SDK 5************************ 6 7This chapter describes the extensible SDK and how to install it. 8Information covers the pieces of the SDK, how to install it, and 9presents a look at using the ``devtool`` functionality. The extensible 10SDK makes it easy to add new applications and libraries to an image, 11modify the source for an existing component, test changes on the target 12hardware, and ease integration into the rest of the 13:term:`OpenEmbedded Build System`. 14 15.. note:: 16 17 For a side-by-side comparison of main features supported for an 18 extensible SDK as compared to a standard SDK, see the 19 :ref:`sdk-manual/intro:introduction` section. 20 21In addition to the functionality available through ``devtool``, you can 22alternatively make use of the toolchain directly, for example from 23Makefile and Autotools. See the 24":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter 25for more information. 26 27Why use the Extensible SDK and What is in It? 28============================================= 29 30The extensible SDK provides a cross-development toolchain and libraries 31tailored to the contents of a specific image. You would use the 32Extensible SDK if you want a toolchain experience supplemented with the 33powerful set of ``devtool`` commands tailored for the Yocto Project 34environment. 35 36The installed extensible SDK consists of several files and directories. 37Basically, it contains an SDK environment setup script, some 38configuration files, an internal build system, and the ``devtool`` 39functionality. 40 41Installing the Extensible SDK 42============================= 43 44Two ways to install the Extensible SDK 45-------------------------------------- 46 47Extensible SDK can be installed in two different ways, and both have 48their own pros and cons: 49 50#. *Setting up the Extensible SDK environment directly in a Yocto build*. This 51 avoids having to produce, test, distribute and maintain separate SDK 52 installer archives, which can get very large. There is only one environment 53 for the regular Yocto build and the SDK and less code paths where things can 54 go not according to plan. It's easier to update the SDK: it simply means 55 updating the Yocto layers with git fetch or layer management tooling. The 56 SDK extensibility is better than in the second option: just run ``bitbake`` 57 again to add more things to the sysroot, or add layers if even more things 58 are required. 59 60#. *Setting up the Extensible SDK from a standalone installer*. This has the 61 benefit of having a single, self-contained archive that includes all the 62 needed binary artifacts. So nothing needs to be rebuilt, and there is no 63 need to provide a well-functioning binary artefact cache over the network 64 for developers with underpowered laptops. 65 66.. _setting_up_ext_sdk_in_build: 67 68Setting up the Extensible SDK environment directly in a Yocto build 69------------------------------------------------------------------- 70 71#. Set up all the needed layers and a Yocto :term:`Build Directory`, e.g. a regular Yocto 72 build where ``bitbake`` can be executed. 73 74#. Run:: 75 76 $ bitbake meta-ide-support 77 $ bitbake -c populate_sysroot gtk+3 78 # or any other target or native item that the application developer would need 79 $ bitbake build-sysroots -c build_native_sysroot && bitbake build-sysroots -c build_target_sysroot 80 81Setting up the Extensible SDK from a standalone installer 82--------------------------------------------------------- 83 84The first thing you need to do is install the SDK on your :term:`Build 85Host` by running the ``*.sh`` installation script. 86 87You can download a tarball installer, which includes the pre-built 88toolchain, the ``runqemu`` script, the internal build system, 89``devtool``, and support files from the appropriate 90:yocto_dl:`toolchain </releases/yocto/&DISTRO_REL_LATEST_TAG;/toolchain/>` directory within the Index of 91Releases. Toolchains are available for several 32-bit and 64-bit 92architectures with the ``x86_64`` directories, respectively. The 93toolchains the Yocto Project provides are based off the 94``core-image-sato`` and ``core-image-minimal`` images and contain 95libraries appropriate for developing against that image. 96 97The names of the tarball installer scripts are such that a string 98representing the host system appears first in the filename and then is 99immediately followed by a string representing the target architecture. 100An extensible SDK has the string "-ext" as part of the name. Following 101is the general form:: 102 103 poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh 104 105 Where: 106 host_system is a string representing your development system: 107 108 i686 or x86_64. 109 110 image_type is the image for which the SDK was built: 111 112 core-image-sato or core-image-minimal 113 114 arch is a string representing the tuned target architecture: 115 116 aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon 117 118 release_version is a string representing the release number of the Yocto Project: 119 120 &DISTRO;, &DISTRO;+snapshot 121 122For example, the following SDK installer is for a 64-bit 123development host system and a i586-tuned target architecture based off 124the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot:: 125 126 poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh 127 128.. note:: 129 130 As an alternative to downloading an SDK, you can build the SDK 131 installer. For information on building the installer, see the 132 :ref:`sdk-manual/appendix-obtain:building an sdk installer` 133 section. 134 135The SDK and toolchains are self-contained and by default are installed 136into the ``poky_sdk`` folder in your home directory. You can choose to 137install the extensible SDK in any location when you run the installer. 138However, because files need to be written under that directory during 139the normal course of operation, the location you choose for installation 140must be writable for whichever users need to use the SDK. 141 142The following command shows how to run the installer given a toolchain 143tarball for a 64-bit x86 development host system and a 64-bit x86 target 144architecture. The example assumes the SDK installer is located in 145``~/Downloads/`` and has execution rights:: 146 147 $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh 148 Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5 149 ========================================================================== 150 Enter target directory for SDK (default: poky_sdk): 151 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y 152 Extracting SDK..............done 153 Setting it up... 154 Extracting buildtools... 155 Preparing build system... 156 Parsing recipes: 100% |##################################################################| Time: 0:00:52 157 Initialising tasks: 100% |###############################################################| Time: 0:00:00 158 Checking sstate mirror object availability: 100% |#######################################| Time: 0:00:00 159 Loading cache: 100% |####################################################################| Time: 0:00:00 160 Initialising tasks: 100% |###############################################################| Time: 0:00:00 161 done 162 SDK has been successfully set up and is ready to be used. 163 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. 164 $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux 165 166.. note:: 167 168 If you do not have write permissions for the directory into which you 169 are installing the SDK, the installer notifies you and exits. For 170 that case, set up the proper permissions in the directory and run the 171 installer again. 172 173.. _running_the_ext_sdk_env: 174 175Running the Extensible SDK Environment Setup Script 176=================================================== 177 178Once you have the SDK installed, you must run the SDK environment setup 179script before you can actually use the SDK. 180 181When using an SDK directly in a Yocto build, you will find the script in 182``tmp/deploy/images/qemux86-64/`` in your :term:`Build Directory`. 183 184When using a standalone SDK installer, this setup script resides in 185the directory you chose when you installed the SDK, which is either the 186default ``poky_sdk`` directory or the directory you chose during 187installation. 188 189Before running the script, be sure it is the one that matches the 190architecture for which you are developing. Environment setup scripts 191begin with the string "``environment-setup``" and include as part of 192their name the tuned target architecture. As an example, the following 193commands set the working directory to where the SDK was installed and 194then source the environment setup script. In this example, the setup 195script is for an IA-based target machine using i586 tuning:: 196 197 $ cd /home/scottrif/poky_sdk 198 $ source environment-setup-core2-64-poky-linux 199 SDK environment now set up; additionally you may now run devtool to perform development tasks. 200 Run devtool --help for further details. 201 202When using the environment script directly in a Yocto build, it can 203be run similarly:: 204 205 $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux 206 207Running the setup script defines many environment variables needed in order to 208use the SDK (e.g. ``PATH``, :term:`CC`, :term:`LD`, and so forth). If you want 209to see all the environment variables the script exports, examine the 210installation file itself. 211 212.. _using_devtool: 213 214Using ``devtool`` in Your SDK Workflow 215====================================== 216 217The cornerstone of the extensible SDK is a command-line tool called 218``devtool``. This tool provides a number of features that help you 219build, test and package software within the extensible SDK, and 220optionally integrate it into an image built by the OpenEmbedded build 221system. 222 223.. note:: 224 225 The use of ``devtool`` is not limited to the extensible SDK. You can use 226 ``devtool`` to help you easily develop any project whose build output must be 227 part of an image built using the build system. 228 229The ``devtool`` command line is organized similarly to 230:ref:`overview-manual/development-environment:git` in that it has a number of 231sub-commands for each function. You can run ``devtool --help`` to see 232all the commands. 233 234.. note:: 235 236 See the ":doc:`/ref-manual/devtool-reference`" 237 section in the Yocto Project Reference Manual. 238 239``devtool`` subcommands provide entry-points into development: 240 241- *devtool add*: Assists in adding new software to be built. 242 243- *devtool modify*: Sets up an environment to enable you to modify 244 the source of an existing component. 245 246- *devtool ide-sdk*: Generates a configuration for an IDE. 247 248- *devtool upgrade*: Updates an existing recipe so that you can 249 build it for an updated set of source files. 250 251As with the build system, "recipes" represent software packages within 252``devtool``. When you use ``devtool add``, a recipe is automatically 253created. When you use ``devtool modify``, the specified existing recipe 254is used in order to determine where to get the source code and how to 255patch it. In both cases, an environment is set up so that when you build 256the recipe a source tree that is under your control is used in order to 257allow you to make changes to the source as desired. By default, new 258recipes and the source go into a "workspace" directory under the SDK. 259 260To learn how to use ``devtool`` to add, modify, upgrade recipes and more, see 261the :ref:`dev-manual/devtool:Using the \`\`devtool\`\` command-line tool` 262section of the Yocto Project Development Tasks Manual. 263 264Installing Additional Items Into the Extensible SDK 265=================================================== 266 267Out of the box the extensible SDK typically only comes with a small 268number of tools and libraries. A minimal SDK starts mostly empty and is 269populated on-demand. Sometimes you must explicitly install extra items 270into the SDK. If you need these extra items, you can first search for 271the items using the ``devtool search`` command. For example, suppose you 272need to link to libGL but you are not sure which recipe provides libGL. 273You can use the following command to find out:: 274 275 $ devtool search libGL mesa 276 A free implementation of the OpenGL API 277 278Once you know the recipe 279(i.e. ``mesa`` in this example), you can install it. 280 281When using the extensible SDK directly in a Yocto build 282------------------------------------------------------- 283 284In this scenario, the Yocto build tooling, e.g. ``bitbake`` 285is directly accessible to build additional items, and it 286can simply be executed directly:: 287 288 $ bitbake curl-native 289 # Add newly built native items to native sysroot 290 $ bitbake build-sysroots -c build_native_sysroot 291 $ bitbake mesa 292 # Add newly built target items to target sysroot 293 $ bitbake build-sysroots -c build_target_sysroot 294 295When using a standalone installer for the Extensible SDK 296-------------------------------------------------------- 297 298:: 299 300 $ devtool sdk-install mesa 301 302By default, the ``devtool sdk-install`` command assumes 303the item is available in pre-built form from your SDK provider. If the 304item is not available and it is acceptable to build the item from 305source, you can add the "-s" option as follows:: 306 307 $ devtool sdk-install -s mesa 308 309It is important to remember that building the item from source 310takes significantly longer than installing the pre-built artifact. Also, 311if there is no recipe for the item you want to add to the SDK, you must 312instead add the item using the ``devtool add`` command. 313 314Applying Updates to an Installed Extensible SDK 315=============================================== 316 317If you are working with an installed extensible SDK that gets 318occasionally updated (e.g. a third-party SDK), then you will need to 319manually "pull down" the updates into the installed SDK. 320 321To update your installed SDK, use ``devtool`` as follows:: 322 323 $ devtool sdk-update 324 325The previous command assumes your SDK provider has set the default update URL 326for you through the :term:`SDK_UPDATE_URL` variable as described in the 327":ref:`sdk-manual/appendix-customizing:Providing Updates to the Extensible SDK After Installation`" 328section. If the SDK provider has not set that default URL, you need to 329specify it yourself in the command as follows:: 330 331 $ devtool sdk-update path_to_update_directory 332 333.. note:: 334 335 The URL needs to point specifically to a published SDK and not to an 336 SDK installer that you would download and install. 337 338Creating a Derivative SDK With Additional Components 339==================================================== 340 341You might need to produce an SDK that contains your own custom 342libraries. A good example would be if you were a vendor with customers 343that use your SDK to build their own platform-specific software and 344those customers need an SDK that has custom libraries. In such a case, 345you can produce a derivative SDK based on the currently installed SDK 346fairly easily by following these steps: 347 348#. If necessary, install an extensible SDK that you want to use as a 349 base for your derivative SDK. 350 351#. Source the environment script for the SDK. 352 353#. Add the extra libraries or other components you want by using the 354 ``devtool add`` command. 355 356#. Run the ``devtool build-sdk`` command. 357 358The previous steps take the recipes added to the workspace and construct 359a new SDK installer that contains those recipes and the resulting binary 360artifacts. The recipes go into their own separate layer in the 361constructed derivative SDK, which leaves the workspace clean and ready 362for users to add their own recipes. 363