diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-appendix-obtain.xml')
| -rw-r--r-- | documentation/sdk-manual/sdk-appendix-obtain.xml | 444 |
1 files changed, 0 insertions, 444 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml deleted file mode 100644 index de7f75e2bb..0000000000 --- a/documentation/sdk-manual/sdk-appendix-obtain.xml +++ /dev/null @@ -1,444 +0,0 @@ -<!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--> - -<appendix id='sdk-appendix-obtain'> - -<title>Obtaining the SDK</title> - -<section id='sdk-locating-pre-built-sdk-installers'> - <title>Locating Pre-Built SDK Installers</title> - - <para> - 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. - </para> - - <para> - Follow these steps to locate and hand-install the toolchain: - <orderedlist> - <listitem><para> - <emphasis>Go to the Installers Directory:</emphasis> - Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink> - </para></listitem> - <listitem><para> - <emphasis>Open the Folder for Your Build Host:</emphasis> - Open the folder that matches your - <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>build host</ulink> - (i.e. <filename>i686</filename> for 32-bit machines or - <filename>x86_64</filename> for 64-bit machines). - </para></listitem> - <listitem><para> - <emphasis>Locate and Download the SDK Installer:</emphasis> - You need to find and download the installer appropriate for - your build host, target hardware, and image type. - </para> - - <para>The installer files (<filename>*.sh</filename>) follow - this naming convention: - <literallayout class='monospaced'> - poky-glibc-<replaceable>host_system</replaceable>-core-image-<replaceable>type</replaceable>-<replaceable>arch</replaceable>-toolchain[-ext]-<replaceable>release</replaceable>.sh - - Where: - <replaceable>host_system</replaceable> is a string representing your development system: - "i686" or "x86_64" - - <replaceable>type</replaceable> is a string representing the image: - "sato" or "minimal" - - <replaceable>arch</replaceable> is a string representing the target architecture: - "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2", - "mips64", or "ppc7400" - - <replaceable>release</replaceable> is the version of Yocto Project. - - NOTE: - The standard SDK installer does not have the "-ext" string as - part of the filename. - - </literallayout> - The toolchains provided by the Yocto Project are based off of - the <filename>core-image-sato</filename> and - <filename>core-image-minimal</filename> images and contain - libraries appropriate for developing against those images. - </para> - - <para>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 <filename>x86_64</filename> folder and download the - following installer: - <literallayout class='monospaced'> - poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Run the Installer:</emphasis> - Be sure you have execution privileges and run the installer. - Following is an example from the <filename>Downloads</filename> - directory: - <literallayout class='monospaced'> - $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh - </literallayout> - During execution of the script, you choose the root location - for the toolchain. - See the - "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" - section and the - "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>" - section for more information. - </para></listitem> - </orderedlist> - </para> -</section> - -<section id='sdk-building-an-sdk-installer'> - <title>Building an SDK Installer</title> - - <para> - As an alternative to locating and downloading an SDK installer, - you can build the SDK installer. - Follow these steps: - <orderedlist> - <listitem><para> - <emphasis>Set Up the Build Environment:</emphasis> - Be sure you are set up to use BitBake in a shell. - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>" - 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. - </para></listitem> - <listitem><para> - <emphasis>Clone the <filename>poky</filename> Repository:</emphasis> - You need to have a local copy of the Yocto Project - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> - (i.e. a local <filename>poky</filename> repository). - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>" - and possibly the - "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>" - and - "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>" - sections all in the Yocto Project Development Tasks Manual for - information on how to clone the <filename>poky</filename> - repository and check out the appropriate branch for your work. - </para></listitem> - <listitem><para> - <emphasis>Initialize the Build Environment:</emphasis> - While in the root directory of the Source Directory (i.e. - <filename>poky</filename>), run the - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - environment setup script to define the OpenEmbedded - build environment on your build host. - <literallayout class='monospaced'> - $ source &OE_INIT_FILE; - </literallayout> - Among other things, the script creates the - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, - which is <filename>build</filename> in this case - and is located in the Source Directory. - After the script runs, your current working directory - is set to the <filename>build</filename> directory. - </para></listitem> - <listitem><para> - <emphasis>Make Sure You Are Building an Installer for the Correct Machine:</emphasis> - Check to be sure that your - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - variable in the <filename>local.conf</filename> file in your - Build Directory matches the architecture for which you are - building. - </para></listitem> - <listitem><para> - <emphasis>Make Sure Your SDK Machine is Correctly Set:</emphasis> - 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 - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink> - variable in the <filename>local.conf</filename> file in your - Build Directory is correctly set. - <note> - If you are building an SDK installer for the Extensible - SDK, the <filename>SDKMACHINE</filename> value must be - set for the architecture of the machine you are using to - build the installer. - If <filename>SDKMACHINE</filename> is not set appropriately, - the build fails and provides an error message similar to - the following: - <literallayout class='monospaced'> - 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. - </literallayout> - </note> - </para></listitem> - <listitem><para> - <emphasis>Build the SDK Installer:</emphasis> - To build the SDK installer for a standard SDK and populate - the SDK image, use the following command form. - Be sure to replace <replaceable>image</replaceable> with - an image (e.g. "core-image-sato"): - <literallayout class='monospaced'> - $ bitbake <replaceable>image</replaceable> -c populate_sdk - </literallayout> - You can do the same for the extensible SDK using this command - form: - <literallayout class='monospaced'> - $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext - </literallayout> - These commands produce an SDK installer that contains the - sysroot that matches your target root filesystem.</para> - - <para>When the <filename>bitbake</filename> command completes, - the SDK installer will be in - <filename>tmp/deploy/sdk</filename> in the Build Directory. - <note><title>Notes</title> - <itemizedlist> - <listitem><para> - 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 - <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink> - variable inside your <filename>local.conf</filename> - 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 - <filename>libc</filename> static development - libraries: - <literallayout class='monospaced'> - TOOLCHAIN_TARGET_TASK_append = " libc-staticdev" - </literallayout> - </para></listitem> - </itemizedlist> - </note> - </para></listitem> - <listitem><para> - <emphasis>Run the Installer:</emphasis> - You can now run the SDK installer from - <filename>tmp/deploy/sdk</filename> in the Build Directory. - Following is an example: - <literallayout class='monospaced'> - $ cd ~/poky/build/tmp/deploy/sdk - $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh - </literallayout> - During execution of the script, you choose the root location - for the toolchain. - See the - "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" - section and the - "<link linkend='sdk-installed-extensible-sdk-directory-structure'>Installed Extensible SDK Directory Structure</link>" - section for more information. - </para></listitem> - </orderedlist> - </para> -</section> - -<section id='sdk-extracting-the-root-filesystem'> - <title>Extracting the Root Filesystem</title> - - <para> - After installing the toolchain, for some use cases you - might need to separately extract a root filesystem: - <itemizedlist> - <listitem><para> - You want to boot the image using NFS. - </para></listitem> - <listitem><para> - You want to use the root filesystem as the - target sysroot. - </para></listitem> - <listitem><para> - You want to develop your target application - using the root filesystem as the target sysroot. - </para></listitem> - </itemizedlist> - </para> - - <para> - Follow these steps to extract the root filesystem: - <orderedlist> - <listitem><para> - <emphasis>Locate and Download the Tarball for the Pre-Built - Root Filesystem Image File:</emphasis> - 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 - <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/machines/'>Index of Releases</ulink> - in the "machines" directory.</para> - - <para>The machine-specific folders of the "machines" directory - contain tarballs (<filename>*.tar.bz2</filename>) for supported - machines. - These directories also contain flattened root filesystem - image files (<filename>*.ext4</filename>), which you can use - with QEMU directly.</para> - - <para>The pre-built root filesystem image files - follow these naming conventions: - <literallayout class='monospaced'> -<!-- - core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>-<replaceable>date_time</replaceable>.rootfs.tar.bz2 ---> - core-image-<replaceable>profile</replaceable>-<replaceable>arch</replaceable>.tar.bz2 - - Where: - <replaceable>profile</replaceable> 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 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in - the Yocto Project Reference Manual. - - <replaceable>arch</replaceable> 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*. - -<!--> - <replaceable>date_time</replaceable> is a date and time stamp. ---> - - </literallayout> - The root filesystems provided by the Yocto Project are based - off of the <filename>core-image-sato</filename> and - <filename>core-image-minimal</filename> images. - </para> - - <para>For example, if you plan on using a BeagleBone device - as your target hardware and your image is a - <filename>core-image-sato-sdk</filename> - image, you can download the following file: - <literallayout class='monospaced'> - core-image-sato-sdk-beaglebone-yocto.tar.bz2 - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Initialize the Cross-Development Environment:</emphasis> - You must <filename>source</filename> the cross-development - environment setup script to establish necessary environment - variables.</para> - - <para>This script is located in the top-level directory in - which you installed the toolchain (e.g. - <filename>poky_sdk</filename>).</para> - - <para>Following is an example based on the toolchain installed - in the - "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>" - section: - <literallayout class='monospaced'> - $ source ~/poky_sdk/environment-setup-core2-64-poky-linux - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>Extract the Root Filesystem:</emphasis> - Use the <filename>runqemu-extract-sdk</filename> command - and provide the root filesystem image.</para> - - <para>Following is an example command that extracts the root - filesystem from a previously built root filesystem image that - was downloaded from the - <ulink url='&YOCTO_DOCS_OM_URL;#index-downloads'>Index of Releases</ulink>. - This command extracts the root filesystem into the - <filename>core2-64-sato</filename> directory: - <literallayout class='monospaced'> - $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato - </literallayout> - You could now point to the target sysroot at - <filename>beablebone-sato</filename>. - </para></listitem> - </orderedlist> - </para> -</section> - -<section id='sdk-installed-standard-sdk-directory-structure'> - <title>Installed Standard SDK Directory Structure</title> - - <para> - The following figure shows the resulting directory structure after - you install the Standard SDK by running the <filename>*.sh</filename> - SDK installation script: - </para> - - <para> - <imagedata fileref="figures/sdk-installed-standard-sdk-directory.png" scale="80" align="center" /> - </para> - - <para> - 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 (<filename>sysroots</filename>) needed to - develop objects for the target system. - </para> - - <para> - Within the figure, italicized text is used to indicate replaceable - portions of the file or directory name. - For example, - <replaceable>install_dir</replaceable>/<replaceable>version</replaceable> - is the directory where the SDK is installed. - By default, this directory is <filename>/opt/poky/</filename>. - And, <replaceable>version</replaceable> represents the specific - snapshot of the SDK (e.g. <filename>&DISTRO;</filename>). - Furthermore, <replaceable>target</replaceable> represents the target - architecture (e.g. <filename>i586</filename>) and - <replaceable>host</replaceable> represents the development system's - architecture (e.g. <filename>x86_64</filename>). - Thus, the complete names of the two directories within the - <filename>sysroots</filename> could be - <filename>i586-poky-linux</filename> and - <filename>x86_64-pokysdk-linux</filename> for the target and host, - respectively. - </para> -</section> - -<section id='sdk-installed-extensible-sdk-directory-structure'> - <title>Installed Extensible SDK Directory Structure</title> - - <para> - The following figure shows the resulting directory structure after - you install the Extensible SDK by running the <filename>*.sh</filename> - SDK installation script: - </para> - - <para> - <imagedata fileref="figures/sdk-installed-extensible-sdk-directory.png" scale="80" align="center" /> - </para> - - <para> - 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. - </para> - - <para> - 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. - </para> - - <para> - Within the figure, italicized text is used to indicate replaceable - portions of the file or directory name. - For example, - <replaceable>install_dir</replaceable> is the directory where the SDK - is installed, which is <filename>poky_sdk</filename> by default, and - <replaceable>target</replaceable> represents the target - architecture (e.g. <filename>i586</filename>). - </para> -</section> - -</appendix> -<!-- -vim: expandtab tw=80 ts=4 ---> |