documentation/adt-manual/adt-prepare.xml: Initial draft of preparation chapter

This commit is the initial draft of the preparation chapter (chapter 2).

(From OE-Core rev: c32b215eb37828cd31c0c9ba288c2216fcd034de)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 216 insertions, 37 deletions

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 @@
 
 <chapter id='adt-prepare'>
 
-<title>Yocto Project Kernel Architecture and Use Manual</title>
+<title>Preparing to Use the Application Development Toolkit (ADT)</title>
 
-<section id='prepare'>
-    <title>Introduction</title>
-    <para>
-        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.
-    </para>
+<para>
+    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.
+</para>
+
+<section id='installing-the-adt'>
+    <title>Installing the ADT</title>
     <para>
-        This manual describes the Yocto Project kernel by providing information
-        on its history, organization, benefits, and use.
-        The manual consists of two sections:
-        <itemizedlist>
-            <listitem><para>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.</para></listitem>
-            <listitem><para>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."</para></listitem>
-        </itemizedlist>
+        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.
     </para>
-    <para>
-        For more information on the kernel, see the following links:
-        <itemizedlist>
-            <listitem><para><ulink url='http://ldn.linuxfoundation.org/book/1-a-guide-kernel-development-process'></ulink></para></listitem>
-            <listitem><para><ulink url='http://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem>
-            <listitem><para><ulink url='http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD'></ulink></para></listitem> 
-        </itemizedlist>
-        <para> 
-        You can find more information on Yocto Project by visiting the website at
-        <ulink url='http://www.yoctoproject.org'></ulink>.
+
+    <section id='configuring-and-running-the-adt-installer'>
+        <title>Configuring and Running the ADT Installer</title>
+        <para>
+            The ADT Installer is contained in a tarball that can be built using 
+            <filename>bitbake adt-installer</filename>. 
+            Yocto Project has a pre-built ADT Installer tarball that you can download 
+            from <filename>tmp/deploy/sdk</filename> located in the build directory.
         </para>
-    </para>
-</section>
 
+        <note>
+            You can install and run the ADT Installer tarball in any directory you want.
+        </note>
+
+        <para>
+            Before running the ADT Installer you need to configure it by editing 
+            the <filename>adt-installer.conf</filename> 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 <filename>adt-installer.conf</filename> file:
 
+            <itemizedlist>
+                <listitem><para><filename>YOCTOADT_IPKG_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_IPKG_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 Yocto Eclipse IDE plug-in against QEMU, 
+                you should install NFS.
+                    <note>
+                    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.
+                    </note>
+                </para></listitem>
+                <listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename> - The root 
+                filesystem images you want to download.
+                </para></listitem>
+                <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename> - The 
+                root filesystem used to extract and create the target sysroot.
+                </para></listitem>
+                <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename> - The 
+                location of the target sysroot that will be set up on the development machine.
+                </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'>
+     $ adt_installer
+            </literallayout>
+        </para>
+
+        <para>
+            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.
+        </para>
 
+        <para>
+            Once the installation completes, the cross-toolchain is installed in 
+            <filename>/opt/poky/$SDKVERSION</filename>.
+        </para>
 
+        <para>
+            Before using the ADT you need to run the environment setup script for 
+            your target architecture also located in <filename>/opt/poky/$SDKVERSION</filename>.
+            See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref> 
+            section for information.
+        </para>
+    </section>
 
+    <section id='using-an-existing-toolchain-tarball'>
+        <title>Using an Existing Toolchain Tarball</title>
+        <para>
+            If you don’t want to use the ADT Installer you can install the toolchain 
+            and the sysroot by hand.  
+            Follow these steps:
+            <orderedlist>
+                <listitem><para>Locate and download the architecture-specific toolchain 
+                tarball from <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-0.9'></ulink>.
+                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.
+                <note>
+                    If you need to build the toolchain tarball use the 
+                    <filename>bitbake meta-toolchain</filename> command after you have 
+                    sourced the poky-build-init script.  
+                    The tarball will be located in the build directory at 
+                    <filename>tmp/deploy/sdk</filename> after the build.
+                </note>
+                </para></listitem>
+                <listitem><para>Make sure you are in the root directory and then expand 
+                the tarball.  
+                The tarball expands into the <filename>/opt/poky/$SDKVERSION</filename> directory.
+                </para></listitem>
+                <listitem><para>Set up the environment by sourcing the environment set up 
+                script.  
+                See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref>
+                for information.
+                </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
 
+    <section id='using-the-toolchain-from-within-the-build-tree'>
+        <title>Using the Toolchain from Within the Build Tree</title>
+        <para>
+            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:
+            <literallayout class='monospaced'>  
+     $ bitbake meta-ide-support
+            </literallayout>
+        </para>
+ 
+        <para>
+            Before running the command you need to be sure that the 
+            <filename>conf/local.conf</filename> file in the build directory has 
+            the desired architecture specified for the <filename>MACHINE</filename> 
+            variable.
+            See the <filename>local.conf</filename> 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 <filename>local.conf</filename> file and re-run 
+            the BitBake command.
+        </para>
+
+        <para>
+            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 <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref>
+            for information.
+        </para>
+    </section>
+</section>
+
+<section id='setting-up-the-environment'>
+    <title>Setting Up the Environment</title>
+    <para>
+        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 <filename>/opt/poky/$SDKVERSION</filename>
+        directory.  
+        If you are using the ADT from a Poky build tree, then look in the build 
+        directory in <filename>tmp</filename> for the setup script.
+    </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 “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: 
+        <literallayout class='monospaced'>
+     /opt/poky/environment-setup-x86_64-poky-linux
+        </literallayout>
+    </para>
+</section>
+
+<section id='kernels-and-filesystem-images'>
+    <title>Kernels and Filesystem Images</title>
+    <para>
+        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 
+        <ulink url='http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html'></ulink>.
+        <note> 
+            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 - <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-0.9/'></ulink>
+            and are ideal for experimentation within Yocto Project.
+        </note>
+    </para>
+</section>
 
 </chapter>
 <!--