<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
<!--SPDX-License-Identifier: CC-BY-2.0-UK-->

<chapter id='sdk-using-the-standard-sdk'>
    <title>Using the Standard SDK</title>

    <para>
        This chapter describes the standard SDK and how to install it.
        Information includes unique installation and setup aspects for the
        standard SDK.
        <note>
            For a side-by-side comparison of main features supported for a
            standard SDK as compared to an extensible SDK, see the
            "<link linkend='sdk-manual-intro'>Introduction</link>"
            section.
        </note>
    </para>

    <para>
        You can use a standard SDK to work on Makefile and Autotools-based
        projects.
        See the
        "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>"
        chapter for more information.
    </para>

    <section id='sdk-standard-sdk-intro'>
        <title>Why use the Standard SDK and What is in It?</title>

        <para>
            The Standard SDK provides a cross-development toolchain and
            libraries tailored to the contents of a specific image.
            You would use the Standard SDK if you want a more traditional
            toolchain experience as compared to the extensible SDK, which
            provides an internal build system and the
            <filename>devtool</filename> functionality.
        </para>

        <para>
            The installed Standard SDK consists of several files and
            directories.
            Basically, it contains an SDK environment setup script, some
            configuration files, and host and target root filesystems to
            support usage.
            You can see the directory structure in the
            "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
            section.
        </para>
    </section>

    <section id='sdk-installing-the-sdk'>
        <title>Installing the SDK</title>

        <para>
            The first thing you need to do is install the SDK on your
            <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink>
            by running the <filename>*.sh</filename> installation script.
        </para>

        <para>
            You can download a tarball installer, which includes the
            pre-built toolchain, the <filename>runqemu</filename>
            script, and support files from the appropriate
            <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink>
            directory within the Index of Releases.
            Toolchains are available for several 32-bit and 64-bit
            architectures with the <filename>x86_64</filename> directories,
            respectively.
            The toolchains the Yocto Project provides are based off the
            <filename>core-image-sato</filename> and
            <filename>core-image-minimal</filename> images and contain
            libraries appropriate for developing against that image.
        </para>

        <para>
            The names of the tarball installer scripts are such that a
            string representing the host system appears first in the
            filename and then is immediately followed by a string
            representing the target architecture.
            <literallayout class='monospaced'>
     poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh

     Where:
         <replaceable>host_system</replaceable> is a string representing your development system:

                    i686 or x86_64.

         <replaceable>image_type</replaceable> is the image for which the SDK was built:

                    core-image-minimal or core-image-sato.

         <replaceable>arch</replaceable> is a string representing the tuned target architecture:

                    aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon.

         <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project:

                    &DISTRO;, &DISTRO;+snapshot
            </literallayout>
            For example, the following SDK installer is for a 64-bit
            development host system and a i586-tuned target architecture
            based off the SDK for <filename>core-image-sato</filename> and
            using the current &DISTRO; snapshot:
            <literallayout class='monospaced'>
     poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
            </literallayout>
            <note>
                As an alternative to downloading an SDK, you can build the
                SDK installer.
                For information on building the installer, see the
                "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
                section.
            </note>
        </para>

        <para>
            The SDK and toolchains are self-contained and by default are
            installed into the <filename>poky_sdk</filename> folder in your
            home directory.
            You can choose to install the extensible SDK in any location when
            you run the installer.
            However, because files need to be written under that directory
            during the normal course of operation, the location you choose
            for installation must be writable for whichever
            users need to use the SDK.
        </para>

        <para>
            The following command shows how to run the installer given a
            toolchain tarball for a 64-bit x86 development host system and
            a 64-bit x86 target architecture.
            The example assumes the SDK installer is located in
            <filename>~/Downloads/</filename> and has execution rights.
            <note>
                If you do not have write permissions for the directory
                into which you are installing the SDK, the installer
                notifies you and exits.
                For that case, set up the proper permissions in the directory
                and run the installer again.
            </note>
            <literallayout class='monospaced'>
     $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
     Poky (Yocto Project Reference Distro) SDK installer version &DISTRO;
     ===============================================================
     Enter target directory for SDK (default: /opt/poky/&DISTRO;):
     You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed [Y/n]? Y
     Extracting SDK........................................ ..............................done
     Setting it up...done
     SDK has been successfully set up and is ready to be used.
     Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
      $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
            </literallayout>
        </para>

        <para>
            Again, reference the
            "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
            section for more details on the resulting directory structure of
            the installed SDK.
        </para>
    </section>

    <section id='sdk-running-the-sdk-environment-setup-script'>
        <title>Running the SDK Environment Setup Script</title>

        <para>
            Once you have the SDK installed, you must run the SDK environment
            setup script before you can actually use the SDK.
            This setup script resides in the directory you chose when you
            installed the SDK, which is either the default
            <filename>/opt/poky/&DISTRO;</filename> directory or the directory
            you chose during installation.
        </para>

        <para>
            Before running the script, be sure it is the one that matches the
            architecture for which you are developing.
            Environment setup scripts begin with the string
            "<filename>environment-setup</filename>" and include as part of
            their name the tuned target architecture.
            As an example, the following commands set the working directory
            to where the SDK was installed and then source the environment
            setup script.
            In this example, the setup script is for an IA-based
            target machine using i586 tuning:
            <literallayout class='monospaced'>
     $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
            </literallayout>
            When you run the setup script, the same environment variables are
            defined as are when you run the setup script for an extensible SDK.
            See the
            "<link linkend='sdk-running-the-extensible-sdk-environment-setup-script'>Running the Extensible SDK Environment Setup Script</link>"
            section for more information.
        </para>
    </section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->