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