diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml index f27f603e1d..99085d2ae5 100644 --- a/documentation/adt-manual/adt-prepare.xml +++ b/documentation/adt-manual/adt-prepare.xml @@ -6,74 +6,159 @@ Preparing to Use the Application Development Toolkit (ADT) - In order to use the ADT it must be installed, the environment setup script must be - sourced, and the kernel and filesystem image specific to the target architecture must exist. - This section describes how to install the ADT, set up the environment, and provides - some reference information on kernels and filesystem images. + In order to use the ADT you must install it, source a script to set up the + environment, and be sure the kernel and filesystem image specific to the target architecture + exists. + + + + This section describes how to be sure you meet these requirements. + Througout this section two important terms are used: + + Yocto Project Source Tree: + This term refers to the directory structure created as a result of downloading + and unpacking a Yocto Project release tarball. + The Yocto Project source tree contains Bitbake, Documentation, Meta-data and + other files. + The name of the top-level directory of the Yocto Project source tree + is derived from the Yocto Project release tarball. + For example, downloading and unpacking poky-bernard-5.0.1.tar.bz2 + results in a Yocto Project source tree whose Yocto Project source directory is named + poky-bernard-5.0.1. + Yocto Project Build Tree: + This term refers to the area where you run your builds. + The area is created when you source the Yocto Project setup environment script + that is found in the Yocto Project source directory + (e.g. poky-init-build-env). + You can create the Yocto Project build tree anywhere you want on your + development system. + Here is an example that creates the tree in mybuilds + and names the Yocto Project build directory YP-5.0.1: + + $ source poky-bernard-5.0.1/poky-init-build-env $HOME/mybuilds/YP-5.0.1 + + If you don't specifically name the build directory then Bitbake creates it + in the current directory and uses the name build. + Also, if you supply an existing directory then Bitbake uses that + directory as the Yocto Project build directory and populates the build tree + beneath it. +
Installing the ADT - - You can install the ADT three ways. - However, we recommend configuring and running the ADT Installer script. - Running this script automates much of the process for you. - For example, the script allows you to install the QEMU emulator and - user-space NFS, define which root filesystem profiles to download, - and allows you to define the target sysroot location. - - - If you need to generate the ADT tarball you can do so using the following command: - - $ bitbake adt-installer - - This command generates the file adt-installer.tar.bz2 - in the ../build/tmp/deploy/sdk directory. - -
- Configuring and Running the ADT Installer + + The following list describes how you can install the ADT, which includes the cross-toolchain. + Regardless of the installation you choose, however, you must source the cross-toolchain + environment setup script before you use the toolchain. + See the “Setting Up the Environment” + section for more information. + + Use the ADT Installer Script: + 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. + + Use an Existing Toolchain Tarball: + Using this method you select and download an architecture-specific + toolchain tarball and then 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. + Use the Toolchain from Within a Yocto Project Build Tree: + If you already have a Yocto Project build tree you can install the cross-toolchain + using that tree. + 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. + + + +
+ Using the ADT Installer + - The ADT Installer is contained in a tarball that can be built using - bitbake adt-installer. - Yocto Project has a pre-built ADT Installer tarball that you can download - from tmp/deploy/sdk located in the build directory. + To run the ADT Installer you need to first get the ADT Installer tarball and then run the ADT + Installer Script. - - You can install and run the ADT Installer tarball in any directory you want. - +
+ Getting the ADT Installer Tarball - - Before running the ADT Installer you need to configure it by editing - the adt-installer.conf file, which is located in the - directory where the ADT Installer tarball was installed. - Your configurations determine which kernel and filesystem image are downloaded. - The following list describes the variables you can define for the ADT Installer. - For configuration values and restrictions see the comments in - the adt-installer.conf file: + + The ADT Installer is contained in the ADT Installer tarball. + You can download the tarball into any directory from + . + Or, you can use Bitbake to generate the tarball inside the existing Yocto Project build tree. + - - YOCTOADT_IPKG_REPO – 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 - YOCTOADT_IPKG_REPO, you need to be sure that the - directory structure follows the same layout as the reference directory - set up at . - Also, your repository needs to be accessible through HTTP. - - YOCTOADT-TARGETS – The machine - target architectures for which you want to set up cross-development - environments. - - YOCTOADT_QEMU – Indicates whether - or not to install the emulator QEMU. - - YOCTOADT_NFS_UTIL – Indicates whether - or not to install user-mode NFS. - If you plan to use the Yocto Eclipse IDE plug-in against QEMU, - you should install NFS. + + If you use Bitbake to generate the ADT Installer tarball, you must + source the Yocto Project environment setup script located in the Yocto Project + source directory before running the Bitbake command that creates the tarball. + + + + The following example commands download the Yocto Project release tarball, create the Yocto + Project source tree, set up the environment while also creating the Yocto Project build tree, + and finally run the Bitbake command that results in the tarball + ~/yocto-project/build/tmp/deploy/sdk/adt_installer.tar.bz2: + + $ cd ~ + $ mkdir yocto-project + $ cd yocto-project + $ wget http://www.yoctoproject.org/downloads/poky/poky-bernard-5.0.1.tar.bz2 + $ tar xjf poky-bernard-5.0.1.tar.bz2 + $ source poky-bernard-5.0.1/poky-init-build-env poky-5.0.1-build + $ bitbake adt-installer + + + +
+ +
+ Configuring and Running the ADT Installer Script + + + Before running the ADT Installer script you need to unpack the tarball. + You can unpack the tarball in any directory you wish. + Unpacking it creates the directory adt-installer, + which contains the ADT Installer script and its configuration file. + + + + Before you run the script, however, you should examine the ADT Installer configuration + file (adt_installer) and be sure you are going to get what you want. + Your configurations determine which kernel and filesystem image are downloaded. + + + + The following list describes the configurations you can define for the ADT Installer. + For configuration values and restrictions see the comments in + the adt-installer.conf file: + + + YOCTOADT_IPKG_REPO – 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 + YOCTOADT_IPKG_REPO, you need to be sure that the + directory structure follows the same layout as the reference directory + set up at . + Also, your repository needs to be accessible through HTTP. + + YOCTOADT-TARGETS – The machine + target architectures for which you want to set up cross-development + environments. + + YOCTOADT_QEMU – Indicates whether + or not to install the emulator QEMU. + + YOCTOADT_NFS_UTIL – Indicates whether + or not to install user-mode NFS. + If you plan to use the Yocto Eclipse IDE plug-in against QEMU, + you should install NFS. To boot QEMU images using our userspace NFS server, you need to be running portmap or rpcbind. @@ -83,112 +168,131 @@ Your firewall settings may also have to be modified to allow NFS booting to work. - - YOCTOADT_ROOTFS_<arch> - The root - filesystem images you want to download. - - YOCTOADT_TARGET_SYSROOT_IMAGE_<arch> - The - root filesystem used to extract and create the target sysroot. - - YOCTOADT_TARGET_SYSROOT_LOC_<arch> - The - location of the target sysroot that will be set up on the development machine. - - - + + YOCTOADT_ROOTFS_<arch> - The root + filesystem images you want to download. + + YOCTOADT_TARGET_SYSROOT_IMAGE_<arch> - The + root filesystem used to extract and create the target sysroot. + + YOCTOADT_TARGET_SYSROOT_LOC_<arch> - The + location of the target sysroot that will be set up on the development machine. + + + - - After you have configured the adt-installer.conf file, - run the installer using the following command: - + + After you have configured the adt_installer.conf file, + run the installer using the following command: + $ adt_installer - - + + - - Once the installer begins to run you are asked whether you want to run in - interactive or silent mode. - If you want to closely monitor the installation then choose “I” for interactive - mode rather than “S” for silent mode. - Follow the prompts from the script to complete the installation. - + + The ADT Installer requires the libtool package to complete. + If you install the recommended packages as described in the + + Yocto Project Quick Start then you will have libtool installed. + - - Once the installation completes, the cross-toolchain is installed in - /opt/poky/$SDKVERSION. - + + Once the installer begins to run you are asked whether you want to run in + interactive or silent mode. + If you want to closely monitor the installation then choose “I” for interactive + mode rather than “S” for silent mode. + Follow the prompts from the script to complete the installation. + - - Before using the ADT you need to run the environment setup script for - your target architecture also located in /opt/poky/$SDKVERSION. - See the “Setting Up the Environment” - section for information. - + + Once the installation completes, the ADT, which includes the cross-toolchain, is installed. + You will notice environment setup files for the cross-toolchain in + /opt/poky/$SDKVERSION, + and image tarballs in the adt-installer + directory according to your installer configurations, and the target sysroot located + according to the YOCTOADT_TARGET_SYSROOT_LOC_<arch> variable + also in your configuration file. + + +
- Using an Existing Toolchain Tarball + Using a Cross-Toolchain Tarball + + If you want to simply install the cross-toolchain by hand you can do so by using an existing + cross-toolchain tarball. + If you install the cross-toolchain by hand you will have to set up the sysroot separately. + + - If you do not want to use the ADT Installer you can install the toolchain - and the sysroot by hand. Follow these steps: - Locate and download the architecture-specific toolchain - tarball from . - Look in the ‘toolchain’ folder and then open up the folder that matches your - host development system (i.e. 'i686' for 32-bit machines or 'x86_64' - for 64-bit machines). - Then, select the toolchain tarball whose name includes the appropriate - target architecture. + Go to + + and find the folder that matches your host development system + (i.e. 'i686' for 32-bit machines or 'x86_64' for 64-bit machines). + + Go into that folder and download the toolchain tarball whose name + includes the appropriate target architecture. + For example, if your host development system is an Intel-based 64-bit system and + you are going to use your cross-toolchain for an arm target go into the + x86_64 folder and download the following tarball: + + yocto-eglibc-x86_64-arm-toolchain-gmae-1.0.tar.bz2 + - If you need to build the toolchain tarball use the - bitbake meta-toolchain command after you have - sourced the poky-build-init script. - The tarball will be located in the build directory at - tmp/deploy/sdk after the build. - - + Alternatively you can build the toolchain tarball if you have a Yocto Project build tree. + Use the bitbake meta-toolchain command after you have + sourced the poky-build-init script located in the Yocto Project + source directory. + When the bitbake command completes the toolchain tarball will + be in tmp/deploy/sdk in the Yocto Project build tree. + Make sure you are in the root directory and then expand the tarball. - The tarball expands into the /opt/poky/$SDKVERSION directory. - - Set up the environment by sourcing the environment set up - script. - See the “Setting Up the Environment” - for information. + The tarball expands into /opt/poky/$SDKVERSION. + Once the tarball in unpacked the cross-toolchain is installed. + You will notice environment setup files for the cross-toolchain in the directory.
- Using the Toolchain from Within the Build Tree + Using Bitbake and the Yocto Project Build Tree - A final way of accessing the toolchain is from the build tree. - The build tree can be set up to contain the architecture-specific cross toolchain. - To populate the build tree with the toolchain you need to run the following command: - - $ bitbake meta-ide-support - - - - - Before running the command you need to be sure that the - conf/local.conf file in the build directory has - the desired architecture specified for the MACHINE - variable. - See the local.conf file for a list of values you - can supply for this variable. - You can populate the build tree with the cross-toolchains for more - than a single architecture. - You just need to edit the local.conf file and re-run - the BitBake command. - - - - Once the build tree has the toolchain you need to source the environment - setup script so that you can run the cross-tools without having to locate them. - See the “Setting Up the Environment” - for information. + A final way of installing just the cross-toolchain is to use Bitbake within an existing + Yocto Project build tree. + Follow these steps: + + Source the environment setup script located in the Yocto Project + source directory. + The script has the string init-build-env + as part of the name. + At this point you should be sure that the + MACHINE variable + in the local.conf file is set for the target architecture. + You can find the local.conf file in the Yocto Project source + directory. + Comments within the local.conf file list the values you + can use for the MACHINE variable. + You can populate the build tree with the cross-toolchains for more + than a single architecture. + You just need to edit the MACHINE variable in the + local.conf file and re-run the BitBake command. + Run bitbake meta-ide-support to complete the + cross-toolchain installation. + If you change your working directory after you source the environment + setup script and before you run the Bitbake command the command will not work. + Be sure to run the Bitbake command immediately after checking or editing the + local.conf but without changing your working directory. + Once Bitbake finishes, the cross-toolchain is installed. + You will notice environment setup files for the cross-toolchain in the + Yocto Project build tree in the tmp directory. + Setup script filenames contain the strings environment-setup. + +
@@ -196,7 +300,7 @@
Setting Up the Environment - Before you can use the cross-toolchain you need to set up the environment by + Before you can use the cross-toolchain you need to set up the toolchain environment by sourcing the environment setup script. If you used adt_installer or used an existing ADT tarball to install the ADT, then you can find this script in the /opt/poky/$SDKVERSION