diff options
Diffstat (limited to 'documentation/adt-manual/adt-prepare.xml')
| -rw-r--r-- | documentation/adt-manual/adt-prepare.xml | 1000 |
1 files changed, 0 insertions, 1000 deletions
diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml deleted file mode 100644 index 684eb75c56..0000000000 --- a/documentation/adt-manual/adt-prepare.xml +++ /dev/null @@ -1,1000 +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--> - -<chapter id='adt-prepare'> - -<title>Preparing for Application Development</title> - -<para> - In order to develop applications, you need set up your host development system. - Several ways exist that allow you to install cross-development tools, QEMU, the - Eclipse Yocto Plug-in, and other tools. - This chapter describes how to prepare for application development. -</para> - -<section id='installing-the-adt'> - <title>Installing the ADT and Toolchains</title> - - <para> - The following list describes installation methods that set up varying - degrees of tool availability on your system. - Regardless of the installation method you choose, - you must <filename>source</filename> the cross-toolchain - environment setup script, which establishes several key - environment variables, before you use a toolchain. - See the - "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>" - section for more information. - </para> - - <note> - <para> - Avoid mixing installation methods when installing toolchains for - different architectures. - For example, avoid using the ADT Installer to install some - toolchains and then hand-installing cross-development toolchains - by running the toolchain installer for different architectures. - Mixing installation methods can result in situations where the - ADT Installer becomes unreliable and might not install the - toolchain. - </para> - - <para> - If you must mix installation methods, you might avoid problems by - deleting <filename>/var/lib/opkg</filename>, thus purging the - <filename>opkg</filename> package metadata. - </para> - </note> - - <para> - <itemizedlist> - <listitem><para><emphasis>Use the ADT installer script:</emphasis> - This method is the recommended way to install the ADT because it - automates much of the process for you. - For example, you can configure the installation to install the QEMU emulator - and the user-space NFS, specify which root filesystem profiles to download, - and define the target sysroot location.</para></listitem> - <listitem><para><emphasis>Use an existing toolchain:</emphasis> - Using this method, you select and download an architecture-specific - toolchain installer and then run the script to hand-install the toolchain. - If you use this method, you just get the cross-toolchain and QEMU - you do not - get any of the other mentioned benefits had you run the ADT Installer script.</para></listitem> - <listitem><para><emphasis>Use the toolchain from within the Build Directory:</emphasis> - If you already have a - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, - you can build the cross-toolchain within the directory. - However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you - do not get any of the other benefits without taking separate steps.</para></listitem> - </itemizedlist> - </para> - - <section id='using-the-adt-installer'> - <title>Using the ADT Installer</title> - - <para> - To run the ADT Installer, you need to get the ADT Installer tarball, be sure - you have the necessary host development packages that support the ADT Installer, - and then run the ADT Installer Script. - </para> - - <para> - For a list of the host packages needed to support ADT installation and use, see the - "ADT Installer Extras" lists in the - "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" section - of the Yocto Project Reference Manual. - </para> - - <section id='getting-the-adt-installer-tarball'> - <title>Getting the ADT Installer Tarball</title> - - <para> - The ADT Installer is contained in the ADT Installer tarball. - You can get the tarball using either of these methods: - <itemizedlist> - <listitem><para><emphasis>Download the Tarball:</emphasis> - You can download the tarball from - <ulink url='&YOCTO_ADTINSTALLER_DL_URL;'></ulink> into - any directory.</para></listitem> - <listitem><para><emphasis>Build the Tarball:</emphasis> - You can use - <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> - to generate the tarball inside an existing - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. - </para> - <para>If you use BitBake to generate the ADT Installer - tarball, you must <filename>source</filename> the - environment setup script - (<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 before running the - <filename>bitbake</filename> command that creates the - tarball.</para> - <para>The following example commands establish - the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, - check out the current release branch, set up the - build environment while also creating the default - Build Directory, and run the - <filename>bitbake</filename> command that results in the - tarball - <filename>poky/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>: - <note> - Before using BitBake to build the ADT tarball, be - sure to make sure your - <filename>local.conf</filename> file is properly - configured. - See the - "<ulink url='&YOCTO_DOCS_REF_URL;#user-configuration'>User Configuration</ulink>" - section in the Yocto Project Reference Manual for - general configuration information. - </note> - <literallayout class='monospaced'> - $ cd ~ - $ git clone git://git.yoctoproject.org/poky - $ cd poky - $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; - $ source &OE_INIT_FILE; - $ bitbake adt-installer - </literallayout></para></listitem> - </itemizedlist> - </para> - </section> - - <section id='configuring-and-running-the-adt-installer-script'> - <title>Configuring and Running the ADT Installer Script</title> - - <para> - Before running the ADT Installer script, you need to unpack the tarball. - You can unpack the tarball in any directory you wish. - For example, this command copies the ADT Installer tarball from where - it was built into the home directory and then unpacks the tarball into - a top-level directory named <filename>adt-installer</filename>: - <literallayout class='monospaced'> - $ cd ~ - $ cp poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME - $ tar -xjf adt_installer.tar.bz2 - </literallayout> - Unpacking it creates the directory <filename>adt-installer</filename>, - which contains the ADT Installer script (<filename>adt_installer</filename>) - and its configuration file (<filename>adt_installer.conf</filename>). - </para> - - <para> - Before you run the script, however, you should examine the ADT Installer configuration - file and be sure you are going to get what you want. - Your configurations determine which kernel and filesystem image are downloaded. - </para> - - <para> - The following list describes the configurations you can define for the ADT Installer. - For configuration values and restrictions, see the comments in - the <filename>adt-installer.conf</filename> file: - - <itemizedlist> - <listitem><para><filename>YOCTOADT_REPO</filename>: This area - includes the IPKG-based packages and the root filesystem upon which - the installation is based. - If you want to set up your own IPKG repository pointed to by - <filename>YOCTOADT_REPO</filename>, you need to be sure that the - directory structure follows the same layout as the reference directory - set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>. - Also, your repository needs to be accessible through HTTP.</para></listitem> - <listitem><para><filename>YOCTOADT_TARGETS</filename>: The machine - target architectures for which you want to set up cross-development - environments.</para></listitem> - <listitem><para><filename>YOCTOADT_QEMU</filename>: Indicates whether - or not to install the emulator QEMU.</para></listitem> - <listitem><para><filename>YOCTOADT_NFS_UTIL</filename>: Indicates whether - or not to install user-mode NFS. - If you plan to use the Eclipse IDE Yocto plug-in against QEMU, - you should install NFS. - <note>To boot QEMU images using our userspace NFS server, you need - to be running <filename>portmap</filename> or <filename>rpcbind</filename>. - If you are running <filename>rpcbind</filename>, you will also need to add the - <filename>-i</filename> option when <filename>rpcbind</filename> starts up. - Please make sure you understand the security implications of doing this. - You might also have to modify your firewall settings to allow - NFS booting to work.</note></para></listitem> - <listitem><para><filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>: The root - filesystem images you want to download from the - <filename>YOCTOADT_IPKG_REPO</filename> repository.</para></listitem> - <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_</filename><replaceable>arch</replaceable>: The - particular root filesystem used to extract and create the target sysroot. - The value of this variable must have been specified with - <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>. - For example, if you downloaded both <filename>minimal</filename> and - <filename>sato-sdk</filename> images by setting - <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable> - to "minimal sato-sdk", then <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable> - must be set to either "minimal" or "sato-sdk". - </para></listitem> - <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_</filename><replaceable>arch</replaceable>: The - location on the development host where the target sysroot is created. - </para></listitem> - </itemizedlist> - </para> - - <para> - After you have configured the <filename>adt_installer.conf</filename> file, - run the installer using the following command: - <literallayout class='monospaced'> - $ cd adt-installer - $ ./adt_installer - </literallayout> - Once the installer begins to run, you are asked to enter the - location for cross-toolchain installation. - The default location is - <filename>/opt/poky/</filename><replaceable>release</replaceable>. - After either accepting the default location or selecting your - own location, you are prompted to run the installation script - interactively or in silent mode. - If you want to closely monitor the installation, - choose “I” for interactive mode rather than “S” for silent mode. - Follow the prompts from the script to complete the installation. - </para> - - <para> - Once the installation completes, the ADT, which includes the - cross-toolchain, is installed in the selected installation - directory. - You will notice environment setup files for the cross-toolchain - in the installation directory, and image tarballs in the - <filename>adt-installer</filename> directory according to your - installer configurations, and the target sysroot located - according to the - <filename>YOCTOADT_TARGET_SYSROOT_LOC_</filename><replaceable>arch</replaceable> - variable also in your configuration file. - </para> - </section> - </section> - - <section id='using-an-existing-toolchain-tarball'> - <title>Using a Cross-Toolchain Tarball</title> - - <para> - If you want to simply install a cross-toolchain by hand, you can - do so by running the toolchain installer. - The installer includes the pre-built cross-toolchain, the - <filename>runqemu</filename> script, and support files. - If you use this method to install the cross-toolchain, you - might still need to install the target sysroot by installing and - extracting it separately. - For information on how to install the sysroot, see the - "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section. - </para> - - <para> - Follow these steps: - <orderedlist> - <listitem><para><emphasis>Get your toolchain installer using one of the following methods:</emphasis> - <itemizedlist> - <listitem><para>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>Build your own toolchain installer. - For cases where you cannot use an installer - from the download area, you can build your own as - described in the - "<link linkend='optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</link>" - section.</para></listitem> - </itemizedlist></para></listitem> - <listitem><para><emphasis>Once you have the installer, run it to install the toolchain:</emphasis> - <note> - You must change the permissions on the toolchain - installer script so that it is executable. - </note></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 32-bit x86 target architecture. - The example assumes the toolchain installer is located - in <filename>~/Downloads/</filename>. - <literallayout class='monospaced'> - $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh - </literallayout> - The first thing the installer prompts you for is the - directory into which you want to install the toolchain. - The default directory used is - <filename>/opt/poky/&DISTRO;</filename>. - If you do not have write permissions for the directory - into which you are installing the toolchain, the - toolchain installer notifies you and exits. - Be sure you have write permissions in the directory and - run the installer again.</para> - <para>When the script finishes, the cross-toolchain is - installed. - You will notice environment setup files for the - cross-toolchain in the installation directory. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='using-the-toolchain-from-within-the-build-tree'> - <title>Using BitBake and the Build Directory</title> - - <para> - A final way of making the cross-toolchain available is to use BitBake - to generate the toolchain within an existing - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. - This method does not install the toolchain into the default - <filename>/opt</filename> directory. - As with the previous method, if you need to install the target sysroot, you must - do that separately as well. - </para> - - <para> - Follow these steps to generate the toolchain into the Build Directory: - <orderedlist> - <listitem><para><emphasis>Set up the Build Environment:</emphasis> - Source the OpenEmbedded 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 - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. - </para></listitem> - <listitem><para><emphasis>Check your Local Configuration File:</emphasis> - At this point, you should be sure that the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable - in the <filename>local.conf</filename> file found in the - <filename>conf</filename> directory of the Build Directory - is set for the target architecture. - Comments within the <filename>local.conf</filename> file - list the values you can use for the - <filename>MACHINE</filename> variable. - If you do not change the <filename>MACHINE</filename> - variable, the OpenEmbedded build system uses - <filename>qemux86</filename> as the default target - machine when building the cross-toolchain. - <note> - You can populate the Build Directory with the - cross-toolchains for more than a single architecture. - You just need to edit the <filename>MACHINE</filename> - variable in the <filename>local.conf</filename> file and - re-run the <filename>bitbake</filename> command. - </note></para></listitem> - <listitem><para><emphasis>Make Sure Your Layers are Enabled:</emphasis> - Examine the <filename>conf/bblayers.conf</filename> file - and make sure that you have enabled all the compatible - layers for your target machine. - The OpenEmbedded build system needs to be aware of each - layer you want included when building images and - cross-toolchains. - For information on how to enable a layer, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>" - section in the Yocto Project Development Manual. - </para></listitem> - <listitem><para><emphasis>Generate the Cross-Toolchain:</emphasis> - Run <filename>bitbake meta-ide-support</filename> to - complete the cross-toolchain generation. - Once the <filename>bitbake</filename> command finishes, - the cross-toolchain is - generated and populated within the Build Directory. - You will notice environment setup files for the - cross-toolchain that contain the string - "<filename>environment-setup</filename>" in the - Build Directory's <filename>tmp</filename> folder.</para> - <para>Be aware that when you use this method to install the - toolchain, you still need to separately extract and install - the sysroot filesystem. - For information on how to do this, see the - "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section. - </para></listitem> - </orderedlist> - </para> - </section> -</section> - -<section id='setting-up-the-cross-development-environment'> - <title>Setting Up the Cross-Development Environment</title> - - <para> - Before you can develop using the cross-toolchain, you need to set up the - cross-development environment by sourcing the toolchain's environment setup script. - If you used the ADT Installer or hand-installed cross-toolchain, - then you can find this script in the directory you chose for installation. - For this release, the default installation directory is - <filename>&YOCTO_ADTPATH_DIR;</filename>. - If you installed the toolchain in the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, - you can find the environment setup - script for the toolchain in the Build Directory's <filename>tmp</filename> directory. - </para> - - <para> - Be sure to run the environment setup script 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 architecture. - For example, the toolchain environment setup script for a 64-bit - IA-based architecture installed in the default installation directory - would be the following: - <literallayout class='monospaced'> - &YOCTO_ADTPATH_DIR;/environment-setup-x86_64-poky-linux - </literallayout> - When you run the setup script, many environment variables are - defined: - <literallayout class='monospaced'> - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation - <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files - <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target - <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler - <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler - <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor - <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler - <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker - <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger - <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols - <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib' - <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy' - <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump' - <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar' - <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm' - <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools - <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools - <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure - <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags - <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags - <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link - <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags - </literallayout> - </para> -</section> - -<section id='securing-kernel-and-filesystem-images'> - <title>Securing Kernel and Filesystem Images</title> - - <para> - You will need to have a kernel and filesystem image to boot using your - hardware or the QEMU emulator. - Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem - as the target sysroot, you need to extract the root filesystem. - </para> - - <section id='getting-the-images'> - <title>Getting the Images</title> - - <para> - To get the kernel and filesystem images, you either have to build them or download - pre-built versions. - For an example of how to build these images, see the - "<ulink url='&YOCTO_DOCS_QS_URL;#qs-buiding-images'>Buiding Images</ulink>" - section of the Yocto Project Quick Start. - For an example of downloading pre-build versions, see the - "<link linkend='using-pre-built'>Example Using Pre-Built Binaries and QEMU</link>" - section. - </para> - - <para> - The Yocto Project ships basic kernel and filesystem images for several - architectures (<filename>x86</filename>, <filename>x86-64</filename>, - <filename>mips</filename>, <filename>powerpc</filename>, and <filename>arm</filename>) - that you can use unaltered in the QEMU emulator. - These kernel images reside in the release - area - <ulink url='&YOCTO_MACHINES_DL_URL;'></ulink> - and are ideal for experimentation using Yocto Project. - For information on the image types you can build using the OpenEmbedded build system, - see the - "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" - chapter in the Yocto Project Reference Manual. - </para> - - <para> - If you are planning on developing against your image and you are not - building or using one of the Yocto Project development images - (e.g. <filename>core-image-*-dev</filename>), you must be sure to - include the development packages as part of your image recipe. - </para> - - <para> - If you plan on remotely deploying and debugging your - application from within the Eclipse IDE, you must have an image - that contains the Yocto Target Communication Framework (TCF) agent - (<filename>tcf-agent</filename>). - You can do this by including the <filename>eclipse-debug</filename> - image feature. - <note> - See the - "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>" - section in the Yocto Project Reference Manual for information on - image features. - </note> - To include the <filename>eclipse-debug</filename> image feature, - modify your <filename>local.conf</filename> file in the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> - so that the - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink> - variable includes the "eclipse-debug" feature. - After modifying the configuration file, you can rebuild the image. - Once the image is rebuilt, the <filename>tcf-agent</filename> - will be included in the image and is launched automatically after - the boot. - </para> - </section> - - <section id='extracting-the-root-filesystem'> - <title>Extracting the Root Filesystem</title> - - <para> - If you install your toolchain by hand or build it using BitBake and - you need a root filesystem, you need to extract it separately. - If you use the ADT Installer to install the ADT, the root - filesystem is automatically extracted and installed. - </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> -</section> - -<section id='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='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" - section. - </note> - </para> - - <para> - To build the toolchain installer and populate the SDK image, use the - following command: - <literallayout class='monospaced'> - $ bitbake <replaceable>image</replaceable> -c populate_sdk - </literallayout> - The command results 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> archive. - </para> - - <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> - 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='optionally-using-an-external-toolchain'> - <title>Optionally Using an External Toolchain</title> - - <para> - You might want to use an external toolchain as part of your - development. - If this is the case, the fundamental steps you need to accomplish - are as follows: - <itemizedlist> - <listitem><para> - Understand where the installed toolchain resides. - For cases where you need to build the external toolchain, you - would need to take separate steps to build and install the - toolchain. - </para></listitem> - <listitem><para> - Make sure you add the layer that contains the toolchain to - your <filename>bblayers.conf</filename> file through the - <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> - variable. - </para></listitem> - <listitem><para> - Set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNAL_TOOLCHAIN'><filename>EXTERNAL_TOOLCHAIN</filename></ulink> - variable in your <filename>local.conf</filename> file - to the location in which you installed the toolchain. - </para></listitem> - </itemizedlist> - A good example of an external toolchain used with the Yocto Project - is <trademark class='registered'>Mentor Graphics</trademark> - Sourcery G++ Toolchain. - You can see information on how to use that particular layer in the - <filename>README</filename> file at - <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>. - You can find further information by reading about the - <ulink url='&YOCTO_DOCS_REF_URL;#var-TCMODE'><filename>TCMODE</filename></ulink> - variable in the Yocto Project Reference Manual's variable glossary. - </para> -</section> - - <section id='using-pre-built'> - <title>Example Using Pre-Built Binaries and QEMU</title> - - <para> - If hardware, libraries and services are stable, you can get started by using a pre-built binary - of the filesystem image, kernel, and toolchain and run it using the QEMU emulator. - This scenario is useful for developing application software. - </para> - - <mediaobject> - <imageobject> - <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/> - </imageobject> - <caption> - <para>Using a Pre-Built Image</para> - </caption> - </mediaobject> - - <para> - For this scenario, you need to do several things: - </para> - - <itemizedlist> - <listitem><para>Install the appropriate stand-alone toolchain tarball.</para></listitem> - <listitem><para>Download the pre-built image that will boot with QEMU. - You need to be sure to get the QEMU image that matches your target machine’s - architecture (e.g. x86, ARM, etc.).</para></listitem> - <listitem><para>Download the filesystem image for your target machine's architecture. - </para></listitem> - <listitem><para>Set up the environment to emulate the hardware and then start the QEMU emulator. - </para></listitem> - </itemizedlist> - - <section id='installing-the-toolchain'> - <title>Installing the Toolchain</title> - - <para> - You can download a tarball installer, which includes the - pre-built toolchain, the <filename>runqemu</filename> - script, and support files from the appropriate directory under - <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. - Toolchains are available for 32-bit and 64-bit x86 development - systems from the <filename>i686</filename> and - <filename>x86_64</filename> directories, respectively. - The toolchains the Yocto Project provides are based off the - <filename>core-image-sato</filename> image and contain - libraries appropriate for developing against that image. - Each type of development system supports five or more target - architectures. - </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. - </para> - - <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 a string representing the image you wish to - develop a Software Development Toolkit (SDK) for use against. - The Yocto Project builds toolchain installers using the - following BitBake command: - - bitbake core-image-sato -c populate_sdk - - <replaceable>arch</replaceable> is a string representing the tuned target architecture: - - i586, x86_64, powerpc, mips, armv7a or armv5te - - <replaceable>release_version</replaceable> is a string representing the release number of the - Yocto Project: - - &DISTRO;, &DISTRO;+snapshot - </literallayout> - - <para> - For example, the following toolchain 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>: - <literallayout class='monospaced'> - poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh - </literallayout> - </para> - - <para> - Toolchains are self-contained and by default are installed into - <filename>/opt/poky</filename>. - However, when you run the toolchain installer, you can choose an - installation directory. - </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 32-bit x86 target architecture. - You must change the permissions on the toolchain - installer script so that it is executable. - </para> - - <para> - The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>. - <note> - If you do not have write permissions for the directory into which you are installing - the toolchain, the toolchain installer notifies you and exits. - Be sure you have write permissions in the directory and run the installer again. - </note> - </para> - - <para> - <literallayout class='monospaced'> - $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh - </literallayout> - </para> - - <para> - For more information on how to install tarballs, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and - "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" sections in the Yocto Project Application Developer's Guide. - </para> - </section> - - <section id='downloading-the-pre-built-linux-kernel'> - <title>Downloading the Pre-Built Linux Kernel</title> - - <para> - You can download the pre-built Linux kernel suitable for running in the QEMU emulator from - <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>. - Be sure to use the kernel that matches the architecture you want to simulate. - Download areas exist for the five supported machine architectures: - <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>, - <filename>qemux86</filename>, and <filename>qemux86-64</filename>. - </para> - - <para> - Most kernel files have one of the following forms: - <literallayout class='monospaced'> - *zImage-qemu<replaceable>arch</replaceable>.bin - vmlinux-qemu<replaceable>arch</replaceable>.bin - - Where: - <replaceable>arch</replaceable> is a string representing the target architecture: - x86, x86-64, ppc, mips, or arm. - </literallayout> - </para> - - <para> - You can learn more about downloading a Yocto Project kernel in the - "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" - bulleted item in the Yocto Project Development Manual. - </para> - </section> - - <section id='downloading-the-filesystem'> - <title>Downloading the Filesystem</title> - - <para> - You can also download the filesystem image suitable for your target architecture from - <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>. - Again, be sure to use the filesystem that matches the architecture you want - to simulate. - </para> - - <para> - The filesystem image has two tarball forms: <filename>ext3</filename> and - <filename>tar</filename>. - You must use the <filename>ext3</filename> form when booting an image using the - QEMU emulator. - The <filename>tar</filename> form can be flattened out in your host development system - and used for build purposes with the Yocto Project. - <literallayout class='monospaced'> - core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.ext3 - core-image-<replaceable>profile</replaceable>-qemu<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, or sato-sdk. 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: - x86, x86-64, ppc, mips, or arm. - </literallayout> - </para> - </section> - - <section id='setting-up-the-environment-and-starting-the-qemu-emulator'> - <title>Setting Up the Environment and Starting the QEMU Emulator</title> - - <para> - Before you start the QEMU emulator, you need to set up the emulation environment. - The following command form sets up the emulation environment. - <literallayout class='monospaced'> - $ source &YOCTO_ADTPATH_DIR;/environment-setup-<replaceable>arch</replaceable>-poky-linux-<replaceable>if</replaceable> - - Where: - <replaceable>arch</replaceable> is a string representing the target architecture: - i586, x86_64, ppc603e, mips, or armv5te. - - <replaceable>if</replaceable> is a string representing an embedded application binary interface. - Not all setup scripts include this string. - </literallayout> - </para> - - <para> - Finally, this command form invokes the QEMU emulator - <literallayout class='monospaced'> - $ runqemu <replaceable>qemuarch</replaceable> <replaceable>kernel-image</replaceable> <replaceable>filesystem-image</replaceable> - - Where: - <replaceable>qemuarch</replaceable> is a string representing the target architecture: qemux86, qemux86-64, - qemuppc, qemumips, or qemuarm. - - <replaceable>kernel-image</replaceable> is the architecture-specific kernel image. - - <replaceable>filesystem-image</replaceable> is the .ext3 filesystem image. - - </literallayout> - </para> - - <para> - Continuing with the example, the following two commands setup the emulation - environment and launch QEMU. - This example assumes the root filesystem (<filename>.ext3</filename> file) and - the pre-built kernel image file both reside in your home directory. - The kernel and filesystem are for a 32-bit target architecture. - <literallayout class='monospaced'> - $ cd $HOME - $ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux - $ runqemu qemux86 bzImage-qemux86.bin \ - core-image-sato-qemux86.ext3 - </literallayout> - </para> - - <para> - The environment in which QEMU launches varies depending on the filesystem image and on the - target architecture. - For example, if you source the environment for the ARM target - architecture and then boot the minimal QEMU image, the emulator comes up in a new - shell in command-line mode. - However, if you boot the SDK image, QEMU comes up with a GUI. - <note>Booting the PPC image results in QEMU launching in the same shell in - command-line mode.</note> - </para> - </section> -</section> - -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> |