diff options
Diffstat (limited to 'documentation/sdk-manual/sdk-appendix-obtain.xml')
| -rw-r--r-- | documentation/sdk-manual/sdk-appendix-obtain.xml | 256 |
1 files changed, 241 insertions, 15 deletions
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml index eada4cc8ed..8b245615c9 100644 --- a/documentation/sdk-manual/sdk-appendix-obtain.xml +++ b/documentation/sdk-manual/sdk-appendix-obtain.xml @@ -6,26 +6,210 @@ <title>Obtaining the SDK</title> -<section id='sdk-appendix-obtain-manual-development-notes'> - <title>Manual Development Notes for Scott and Paul</title> +<section id='sdk-locating-pre-built-sdk-installers'> + <title>Locating Pre-Built SDK Installers</title> - <para role='writernotes'> - This chapter is going to cover details about the installed SDK and perhaps - stuff on locating it (e.g. the naming scheme used to identify the - <filename>.sh</filename> installation script. + <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 + toolchain installer and then run the script to hand-install the + toolchain. + </para> + + <para> + You can find SDK installers here: + <itemizedlist> + <listitem><para><emphasis>Standard SDK Installers</emphasis> + Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink> + and find 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> + + <para>Go into that folder and download the toolchain installer + whose name includes the appropriate target architecture. + The toolchains provided by the Yocto Project are based off of + the <filename>core-image-sato</filename> image and contain + libraries appropriate for developing against that image. + For example, if your host development system is a 64-bit x86 + system and you are going to use your cross-toolchain for a + 32-bit x86 target, go into the <filename>x86_64</filename> + folder and download the following installer: + <literallayout class='monospaced'> + poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + </literallayout> + </para></listitem> + <listitem><para><emphasis>Extensible SDK Installers</emphasis> + Installers for the extensible SDK are in + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. + </para></listitem> + </itemizedlist> + </para> +</section> + +<section id='sdk-optionally-building-a-toolchain-installer'> + <title>Optionally Building a Toolchain Installer</title> + + <para> + As an alternative to locating and downloading a toolchain installer, + you can build the toolchain installer if you have a + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + <note> + Although not the preferred method, it is also possible to use + <filename>bitbake meta-toolchain</filename> to build the toolchain + installer. + If you do use this method, you must separately install and extract + the target sysroot. + For information on how to install the sysroot, see the + "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" + section. + </note> + </para> + + <para> + To build the toolchain installer for a standard SDK and populate + the SDK image, use the following command: + <literallayout class='monospaced'> + $ bitbake <replaceable>image</replaceable> -c populate_sdk + </literallayout> + You can do the same for the extensible SDK using this command: + <literallayout class='monospaced'> + $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext + </literallayout> + These commands result in a toolchain installer that contains the sysroot + that matches your target root filesystem. + </para> + + <para> + Another powerful feature is that the toolchain is completely + self-contained. + The binaries are linked against their own copy of + <filename>libc</filename>, which results in no dependencies + on the target system. + To achieve this, the pointer to the dynamic loader is + configured at install time since that path cannot be dynamically + altered. + This is the reason for a wrapper around the + <filename>populate_sdk</filename> and + <filename>populate_sdk_ext</filename> archives. </para> - <para role='writernotes'> - The idea here is to gather all the current information in the regular - YP doc set that describes how to locate, download, or build out the SDK. + <para> + Another feature is that only one set of cross-canadian toolchain + binaries are produced per architecture. + This feature takes advantage of the fact that the target hardware can + be passed to <filename>gcc</filename> as a set of compiler options. + Those options are set up by the environment script and contained in + variables such as + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>. + This reduces the space needed for the tools. + Understand, however, that a sysroot is still needed for every target + since those binaries are target-specific. + </para> + + <para> + Remember, before using any BitBake command, you + must source the build environment setup script + (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>) + located in the Source Directory and you must make sure your + <filename>conf/local.conf</filename> variables are correct. + In particular, you need to be sure the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable matches the architecture for which you are building and that + the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink> + variable 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 machine). </para> - <para role='writernotes'> - One thing that needs discussed is any differences between getting the - standard SDK as compared to the extended SDK. - Do we have pre-build extensible SDKs laying around? - Where do we get any pre-built SDKs from? - Show the methods by which the user builds out the SDK? + <para> + When the <filename>bitbake</filename> command completes, the toolchain + installer will be in + <filename>tmp/deploy/sdk</filename> in the Build Directory. + <note> + 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 image has the appropriate static + development libraries. + Use the + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink> + variable inside your <filename>local.conf</filename> file to + install the appropriate library packages. + Following is an example using <filename>glibc</filename> static + development libraries: + <literallayout class='monospaced'> + IMAGE_INSTALL_append = " glibc-staticdev" + </literallayout> + </note> + </para> +</section> + +<section id='sdk-extracting-the-root-filesystem'> + <title>Extracting the Root Filesystem</title> + + <para> + After installing the toolchain or building it using BitBake, + you need a root filesystem, which you need to separately extract. + </para> + + <para> + Here are some cases where you need to extract the 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> + To extract the root filesystem, first <filename>source</filename> + the cross-development environment setup script to establish + necessary environment variables. + If you built the toolchain in the Build Directory, you will find + the toolchain environment script in the + <filename>tmp</filename> directory. + If you installed the toolchain by hand, the environment setup + script is located in <filename>/opt/poky/&DISTRO;</filename>. + </para> + + <para> + After sourcing the environment script, use the + <filename>runqemu-extract-sdk</filename> command and provide the + filesystem image. + </para> + + <para> + Following is an example. + The second command sets up the environment. + In this case, the setup script is located in the + <filename>/opt/poky/&DISTRO;</filename> directory. + The third command extracts the root filesystem from a previously + built filesystem that is located in the + <filename>~/Downloads</filename> directory. + Furthermore, this command extracts the root filesystem into the + <filename>qemux86-sato</filename> directory: + <literallayout class='monospaced'> + $ cd ~ + $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + $ runqemu-extract-sdk \ + ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \ + $HOME/qemux86-sato + </literallayout> + You could now point to the target sysroot at + <filename>qemux86-sato</filename>. </para> </section> @@ -70,6 +254,48 @@ </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 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 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 |