diff options
Diffstat (limited to 'documentation/sdk-manual/appendix-obtain.rst')
| -rw-r--r-- | documentation/sdk-manual/appendix-obtain.rst | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/documentation/sdk-manual/appendix-obtain.rst b/documentation/sdk-manual/appendix-obtain.rst new file mode 100644 index 0000000000..cdfe2cc85e --- /dev/null +++ b/documentation/sdk-manual/appendix-obtain.rst @@ -0,0 +1,319 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +***************** +Obtaining the SDK +***************** + +Locating Pre-Built SDK Installers +================================= + +You can use existing, pre-built toolchains by locating and running an +SDK installer script that ships with the Yocto Project. Using this +method, you select and download an architecture-specific SDK installer +and then run the script to hand-install the toolchain. + +Follow these steps to locate and hand-install the toolchain: + +1. *Go to the Installers Directory:* Go to + :yocto_dl:`/releases/yocto/yocto-&DISTRO;/toolchain/` + +2. *Open the Folder for Your Build Host:* Open the folder that matches + your :term:`Build Host` (i.e. + ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines). + +3. *Locate and Download the SDK Installer:* You need to find and + download the installer appropriate for your build host, target + hardware, and image type. + + The installer files (``*.sh``) follow this naming convention: + :: + + poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh + + Where: + host_system is a string representing your development system: + "i686" or "x86_64" + + type is a string representing the image: + "sato" or "minimal" + + arch is a string representing the target architecture: + "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2", + "mips64", or "ppc7400" + + release is the version of Yocto Project. + + NOTE: + The standard SDK installer does not have the "-ext" string as + part of the filename. + + + The toolchains provided by the Yocto + Project are based off of the ``core-image-sato`` and + ``core-image-minimal`` images and contain libraries appropriate for + developing against those images. + + For example, if your build host is a 64-bit x86 system and you need + an extended SDK for a 64-bit core2 target, go into the ``x86_64`` + folder and download the following installer: + :: + + poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh + +4. *Run the Installer:* Be sure you have execution privileges and run + the installer. Following is an example from the ``Downloads`` + directory: + :: + + $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh + + During execution of the script, you choose the root location for the + toolchain. See the "`Installed Standard SDK Directory + Structure <#sdk-installed-standard-sdk-directory-structure>`__" + section and the "`Installed Extensible SDK Directory + Structure <#sdk-installed-extensible-sdk-directory-structure>`__" + section for more information. + +Building an SDK Installer +========================= + +As an alternative to locating and downloading an SDK installer, you can +build the SDK installer. Follow these steps: + +1. *Set Up the Build Environment:* Be sure you are set up to use BitBake + in a shell. See the ":ref:`dev-manual/start:preparing the build host`" section + in the Yocto Project Development Tasks Manual for information on how + to get a build host ready that is either a native Linux machine or a + machine that uses CROPS. + +2. *Clone the ``poky`` Repository:* You need to have a local copy of the + Yocto Project :term:`Source Directory` + (i.e. a local + ``poky`` repository). See the ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and + possibly the ":ref:`dev-manual/start:checking out by branch in poky`" and + ":ref:`dev-manual/start:checking out by tag in poky`" sections + all in the Yocto Project Development Tasks Manual for information on + how to clone the ``poky`` repository and check out the appropriate + branch for your work. + +3. *Initialize the Build Environment:* While in the root directory of + the Source Directory (i.e. ``poky``), run the + :ref:`structure-core-script` environment + setup script to define the OpenEmbedded build environment on your + build host. + :: + + $ source oe-init-build-env + + Among other things, the script + creates the :term:`Build Directory`, + which is + ``build`` in this case and is located in the Source Directory. After + the script runs, your current working directory is set to the + ``build`` directory. + +4. *Make Sure You Are Building an Installer for the Correct Machine:* + Check to be sure that your + :term:`MACHINE` variable in the + ``local.conf`` file in your Build Directory matches the architecture + for which you are building. + +5. *Make Sure Your SDK Machine is Correctly Set:* If you are building a + toolchain designed to run on an architecture that differs from your + current development host machine (i.e. the build host), be sure that + the :term:`SDKMACHINE` variable + in the ``local.conf`` file in your Build Directory is correctly set. + + .. note:: + + If you are building an SDK installer for the Extensible SDK, the + SDKMACHINE + value must be set for the architecture of the machine you are + using to build the installer. If + SDKMACHINE + is not set appropriately, the build fails and provides an error + message similar to the following: + :: + + The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is + set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64). + Unable to continue. + + +6. *Build the SDK Installer:* To build the SDK installer for a standard + SDK and populate the SDK image, use the following command form. Be + sure to replace image with an image (e.g. "core-image-sato"): $ + bitbake image -c populate_sdk You can do the same for the extensible + SDK using this command form: + :: + + $ bitbake image -c populate_sdk_ext + + These commands produce an SDK installer that contains the sysroot + that matches your target root filesystem. + + When the ``bitbake`` command completes, the SDK installer will be in + ``tmp/deploy/sdk`` in the Build Directory. + + .. note:: + + - By default, the previous BitBake command does not build static + binaries. If you want to use the toolchain to build these types + of libraries, you need to be sure your SDK has the appropriate + static development libraries. Use the + :term:`TOOLCHAIN_TARGET_TASK` + variable inside your ``local.conf`` file before building the + SDK installer. Doing so ensures that the eventual SDK + installation process installs the appropriate library packages + as part of the SDK. Following is an example using ``libc`` + static development libraries: TOOLCHAIN_TARGET_TASK_append = " + libc-staticdev" + +7. *Run the Installer:* You can now run the SDK installer from + ``tmp/deploy/sdk`` in the Build Directory. Following is an example: + :: + + $ cd ~/poky/build/tmp/deploy/sdk + $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh + + During execution of the script, you choose the root location for the + toolchain. See the "`Installed Standard SDK Directory + Structure <#sdk-installed-standard-sdk-directory-structure>`__" + section and the "`Installed Extensible SDK Directory + Structure <#sdk-installed-extensible-sdk-directory-structure>`__" + section for more information. + +Extracting the Root Filesystem +============================== + +After installing the toolchain, for some use cases you might need to +separately extract a root filesystem: + +- You want to boot the image using NFS. + +- You want to use the root filesystem as the target sysroot. + +- You want to develop your target application using the root filesystem + as the target sysroot. + +Follow these steps to extract the root filesystem: + +1. *Locate and Download the Tarball for the Pre-Built Root Filesystem + Image File:* You need to find and download the root filesystem image + file that is appropriate for your target system. These files are kept + in machine-specific folders in the + :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>` + in the "machines" directory. + + The machine-specific folders of the "machines" directory contain + tarballs (``*.tar.bz2``) for supported machines. These directories + also contain flattened root filesystem image files (``*.ext4``), + which you can use with QEMU directly. + + The pre-built root filesystem image files follow these naming + conventions: + :: + + core-image-profile-arch.tar.bz2 + + Where: + profile is the filesystem image's profile: + lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs, + sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on + these types of image profiles, see the "Images" chapter in + the Yocto Project Reference Manual. + + arch is a string representing the target architecture: + beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb, + genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*. + + The root filesystems + provided by the Yocto Project are based off of the + ``core-image-sato`` and ``core-image-minimal`` images. + + For example, if you plan on using a BeagleBone device as your target + hardware and your image is a ``core-image-sato-sdk`` image, you can + download the following file: + :: + + core-image-sato-sdk-beaglebone-yocto.tar.bz2 + +2. *Initialize the Cross-Development Environment:* You must ``source`` + the cross-development environment setup script to establish necessary + environment variables. + + This script is located in the top-level directory in which you + installed the toolchain (e.g. ``poky_sdk``). + + Following is an example based on the toolchain installed in the + ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section: + :: + + $ source ~/poky_sdk/environment-setup-core2-64-poky-linux + +3. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk`` + command and provide the root filesystem image. + + Following is an example command that extracts the root filesystem + from a previously built root filesystem image that was downloaded + from the :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>`. + This command extracts the root filesystem into the ``core2-64-sato`` + directory: + :: + + $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato + + You could now point to the target sysroot at ``beablebone-sato``. + +Installed Standard SDK Directory Structure +========================================== + +The following figure shows the resulting directory structure after you +install the Standard SDK by running the ``*.sh`` SDK installation +script: + +.. image:: figures/sdk-installed-standard-sdk-directory.png + :scale: 80% + :align: center + +The installed SDK consists of an environment setup script for the SDK, a +configuration file for the target, a version file for the target, and +the root filesystem (``sysroots``) needed to develop objects for the +target system. + +Within the figure, italicized text is used to indicate replaceable +portions of the file or directory name. For example, install_dir/version +is the directory where the SDK is installed. By default, this directory +is ``/opt/poky/``. And, version represents the specific snapshot of the +SDK (e.g. &DISTRO;). Furthermore, target represents the target architecture +(e.g. ``i586``) and host represents the development system's +architecture (e.g. ``x86_64``). Thus, the complete names of the two +directories within the ``sysroots`` could be ``i586-poky-linux`` and +``x86_64-pokysdk-linux`` for the target and host, respectively. + +Installed Extensible SDK Directory Structure +============================================ + +The following figure shows the resulting directory structure after you +install the Extensible SDK by running the ``*.sh`` SDK installation +script: + +.. image:: figures/sdk-installed-extensible-sdk-directory.png + :scale: 80% + :align: center + +The installed directory structure for the extensible SDK is quite +different than the installed structure for the standard SDK. The +extensible SDK does not separate host and target parts in the same +manner as does the standard SDK. The extensible SDK uses an embedded +copy of the OpenEmbedded build system, which has its own sysroots. + +Of note in the directory structure are an environment setup script for +the SDK, a configuration file for the target, a version file for the +target, and log files for the OpenEmbedded build system preparation +script run by the installer and BitBake. + +Within the figure, italicized text is used to indicate replaceable +portions of the file or directory name. For example, install_dir is the +directory where the SDK is installed, which is ``poky_sdk`` by default, +and target represents the target architecture (e.g. ``i586``). |