diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml index 928a09100b..77999b8b42 100644 --- a/documentation/adt-manual/adt-prepare.xml +++ b/documentation/adt-manual/adt-prepare.xml @@ -3,53 +3,232 @@ -Yocto Project Kernel Architecture and Use Manual +Preparing to Use the Application Development Toolkit (ADT) -
- Introduction + + 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. + + +
+ Installing the ADT - The Yocto Project presents the kernel as a fully patched, history-clean git - repository. - The git tree represents the selected features, board support, - and configurations extensively tested by Yocto Project. - The Yocto Project kernel allows the end user to leverage community - best practices to seamlessly manage the development, build and debug cycles. + 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. - - This manual describes the Yocto Project kernel by providing information - on its history, organization, benefits, and use. - The manual consists of two sections: - - Concepts - Describes concepts behind the kernel. - You will understand how the kernel is organized and why it is organized in - the way it is. You will understand the benefits of the kernel's organization - and the mechanisms used to work with the kernel and how to apply it in your - design process. - Using the Kernel - Describes best practices and "how-to" information - that lets you put the kernel to practical use. Some examples are "How to Build a - Project Specific Tree", "How to Examine Changes in a Branch", and "Saving Kernel - Modifications." - - - - For more information on the kernel, see the following links: - - - - - - - You can find more information on Yocto Project by visiting the website at - . + +
+ Configuring and Running 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. + + + You can install and run the ADT Installer tarball in any directory you want. + + + + 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: + + + 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. + If you are running rpcbind, you will also need to add the -i + option when rpcbind starts up. + Please make sure you understand the security implications of doing this. + 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. + + + + + + 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. + + + + Once the installation completes, the cross-toolchain is installed in + /opt/poky/$SDKVERSION. + + + + 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. + +
+ +
+ Using an Existing Toolchain Tarball + + If you don’t 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. 'i586' for 32-bit machines or 'x86_64' + for 64-bit machines). + Then, select the toolchain tarball whose name includes the appropriate + target architecture. + + 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. + + + 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. + + + +
+ +
+ Using the Toolchain from Within the 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. + +
+
+ +
+ Setting Up the Environment + + Before you can use the cross-toolchain you need to set up the 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 + directory. + If you are using the ADT from a Poky build tree, then look in the build + directory in tmp for the setup script. + + + + Be sure to run the environment setup script that matches the architecture for + which you are developing. + Environment setup scripts begin with the string “environment-setup” and include as + part of their name the architecture. + For example, the environment setup script for a 64-bit IA-based architecture would + be the following: + + /opt/poky/environment-setup-x86_64-poky-linux +
- - - - - +
+ Kernels and Filesystem Images + + You will need to have a kernel and filesystem image to boot using your + hardware or the QEMU emulator. + That means you either have to build them or know where to get them. + You can find lots of details on how to get or build images and kernels for your + architecture in the "Yocto Project Quick Start" found at + . + + Yocto Project provides basic kernels and filesystem images for several + architectures (x86, x86-64, mips, powerpc, and arm) that can be used + unaltered in the QEMU emulator. + These kernels and filesystem images reside in the Yocto Project release + area - + and are ideal for experimentation within Yocto Project. + + +