diff options
Diffstat (limited to 'poky/documentation/sdk-manual/sdk-appendix-obtain.xml')
| -rw-r--r-- | poky/documentation/sdk-manual/sdk-appendix-obtain.xml | 429 |
1 files changed, 429 insertions, 0 deletions
diff --git a/poky/documentation/sdk-manual/sdk-appendix-obtain.xml b/poky/documentation/sdk-manual/sdk-appendix-obtain.xml new file mode 100644 index 000000000..aa06358a0 --- /dev/null +++ b/poky/documentation/sdk-manual/sdk-appendix-obtain.xml @@ -0,0 +1,429 @@ +<!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; ] > + +<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 Development System:</emphasis> + Open the folder that matches your host development system + (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 development system, target hardware, and image type. + </para> + + <para>The installer files (<filename>*.sh</filename>) follow + this naming convention: + <literallayout class='monospaced'> + poky-eglibc-<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 either a "sato" or "minimal" + image. + + <replaceable>arch</replaceable> is a string representing the target architecture: + aarch64, armv5e, core2-64, coretexa8hf-neon, i586, mips3242, + 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 host development system is a + 64-bit x86 system and you are 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 a 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;#setting-up-the-development-host-to-use-the-yocto-project'>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 + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. + 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 + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + 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 machine), 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. + </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 result in a 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, this toolchain 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 to install the appropriate library packages + in 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> + <listitem><para> + For additional information on building the + installer, see the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an <trademark class='trade'>Eclipse</trademark> Debug Capable Image</ulink> + wiki page. + </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. + For example, the Eclipse IDE environment with the Eclipse + Yocto Plug-in installed allows you to use QEMU to boot + under NFS. + </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 the + <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/machines/'>Index of Releases</ulink> + in the "machines" directory.</para> + + <para>The "machines" directory contains tarballs + (<filename>*.tar.bz2</filename>) for supported machines. + The directory also contains 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>.tar.bz2 + + Where: + <replaceable>profile</replaceable> is the filesystem image's profile: + lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato, + sato-dev, sato-sdk, minimal-initramfs, or sdk-ptest. For + information on these types of image profiles, see the + "Images" chapter in the Yocto Project Reference Manual. + + <replaceable>arch</replaceable> is a string representing the target architecture: + beaglebone, edgerouter, genericx86, genericx86-64, mpc8315e-rdb, + qemuarm, qemuarm64, qemumips, qemumips64, qemuppc, qemux86, or + qemux86-64. + + </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 your target hardware system is a + BeagleBone board and your image is a + <filename>core-image-minimal</filename> image, you need + to download the following root filesystem image file: + <literallayout class='monospaced'> + core-image-minimal-beaglebone.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 for the Core2 64-bit + architecture: + <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-core2-64.tar.bz2 ~/core2-64-sato + </literallayout> + You could now point to the target sysroot at + <filename>core2-64-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="60" 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="60" 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 a log file for the OpenEmbedded build system + preparation script run by the installer. + </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. + <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>). + </para> +</section> + +</appendix> +<!-- +vim: expandtab tw=80 ts=4 +--> |
