diff options
Diffstat (limited to 'poky/documentation/adt-manual')
-rw-r--r-- | poky/documentation/adt-manual/adt-command.xml | 265 | ||||
-rw-r--r-- | poky/documentation/adt-manual/adt-intro.xml | 180 | ||||
-rw-r--r-- | poky/documentation/adt-manual/adt-manual-customization.xsl | 27 | ||||
-rw-r--r-- | poky/documentation/adt-manual/adt-manual-eclipse-customization.xsl | 35 | ||||
-rw-r--r-- | poky/documentation/adt-manual/adt-manual-intro.xml | 33 | ||||
-rw-r--r-- | poky/documentation/adt-manual/adt-manual.xml | 140 | ||||
-rw-r--r-- | poky/documentation/adt-manual/adt-package.xml | 102 | ||||
-rw-r--r-- | poky/documentation/adt-manual/adt-prepare.xml | 999 | ||||
-rw-r--r-- | poky/documentation/adt-manual/adt-style.css | 984 | ||||
-rw-r--r-- | poky/documentation/adt-manual/figures/adt-title.png | bin | 0 -> 13498 bytes | |||
-rw-r--r-- | poky/documentation/adt-manual/figures/using-a-pre-built-image.png | bin | 0 -> 12733 bytes |
11 files changed, 2765 insertions, 0 deletions
diff --git a/poky/documentation/adt-manual/adt-command.xml b/poky/documentation/adt-manual/adt-command.xml new file mode 100644 index 000000000..c78d18a16 --- /dev/null +++ b/poky/documentation/adt-manual/adt-command.xml @@ -0,0 +1,265 @@ +<!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; ] > + +<chapter id='using-the-command-line'> +<title>Using the Command Line</title> + + <para> + Recall that earlier the manual discussed how to use an existing toolchain + tarball that had been installed into the default installation + directory, <filename>/opt/poky/&DISTRO;</filename>, which is outside of the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + (see the section "<link linkend='using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball)</link>". + And, that sourcing your architecture-specific environment setup script + initializes a suitable cross-toolchain development environment. + </para> + + <para> + During this setup, locations for the compiler, QEMU scripts, QEMU binary, + a special version of <filename>pkgconfig</filename> and other useful + utilities are added to the <filename>PATH</filename> variable. + Also, variables to assist + <filename>pkgconfig</filename> and <filename>autotools</filename> + are also defined so that, for example, <filename>configure.sh</filename> + can find pre-generated test results for tests that need target hardware + on which to run. + You can see the + "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>" + section for the list of cross-toolchain environment variables + established by the script. + </para> + + <para> + Collectively, these conditions allow you to easily use the toolchain + outside of the OpenEmbedded build environment on both Autotools-based + projects and Makefile-based projects. + This chapter provides information for both these types of projects. + </para> + + +<section id='autotools-based-projects'> +<title>Autotools-Based Projects</title> + + <para> + Once you have a suitable cross-toolchain installed, it is very easy to + develop a project outside of the OpenEmbedded build system. + This section presents a simple "Helloworld" example that shows how + to set up, compile, and run the project. + </para> + + <section id='creating-and-running-a-project-based-on-gnu-autotools'> + <title>Creating and Running a Project Based on GNU Autotools</title> + + <para> + Follow these steps to create a simple Autotools-based project: + <orderedlist> + <listitem><para><emphasis>Create your directory:</emphasis> + Create a clean directory for your project and then make + that directory your working location: + <literallayout class='monospaced'> + $ mkdir $HOME/helloworld + $ cd $HOME/helloworld + </literallayout></para></listitem> + <listitem><para><emphasis>Populate the directory:</emphasis> + Create <filename>hello.c</filename>, <filename>Makefile.am</filename>, + and <filename>configure.in</filename> files as follows: + <itemizedlist> + <listitem><para>For <filename>hello.c</filename>, include + these lines: + <literallayout class='monospaced'> + #include <stdio.h> + + main() + { + printf("Hello World!\n"); + } + </literallayout></para></listitem> + <listitem><para>For <filename>Makefile.am</filename>, + include these lines: + <literallayout class='monospaced'> + bin_PROGRAMS = hello + hello_SOURCES = hello.c + </literallayout></para></listitem> + <listitem><para>For <filename>configure.in</filename>, + include these lines: + <literallayout class='monospaced'> + AC_INIT(hello.c) + AM_INIT_AUTOMAKE(hello,0.1) + AC_PROG_CC + AC_PROG_INSTALL + AC_OUTPUT(Makefile) + </literallayout></para></listitem> + </itemizedlist></para></listitem> + <listitem><para><emphasis>Source the cross-toolchain + environment setup file:</emphasis> + Installation of the cross-toolchain creates a cross-toolchain + environment setup script in the directory that the ADT + was installed. + Before you can use the tools to develop your project, you must + source this setup script. + The script begins with the string "environment-setup" and contains + the machine architecture, which is followed by the string + "poky-linux". + Here is an example that sources a script from the + default ADT installation directory that uses the + 32-bit Intel x86 Architecture and the + &DISTRO_NAME; Yocto Project release: + <literallayout class='monospaced'> + $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + </literallayout></para></listitem> + <listitem><para><emphasis>Generate the local aclocal.m4 + files and create the configure script:</emphasis> + The following GNU Autotools generate the local + <filename>aclocal.m4</filename> files and create the + configure script: + <literallayout class='monospaced'> + $ aclocal + $ autoconf + </literallayout></para></listitem> + <listitem><para><emphasis>Generate files needed by GNU + coding standards:</emphasis> + GNU coding standards require certain files in order for the + project to be compliant. + This command creates those files: + <literallayout class='monospaced'> + $ touch NEWS README AUTHORS ChangeLog + </literallayout></para></listitem> + <listitem><para><emphasis>Generate the configure + file:</emphasis> + This command generates the <filename>configure</filename>: + <literallayout class='monospaced'> + $ automake -a + </literallayout></para></listitem> + <listitem><para><emphasis>Cross-compile the project:</emphasis> + This command compiles the project using the cross-compiler. + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> + environment variable provides the minimal arguments for + GNU configure: + <literallayout class='monospaced'> + $ ./configure ${CONFIGURE_FLAGS} + </literallayout></para></listitem> + <listitem><para><emphasis>Make and install the project:</emphasis> + These two commands generate and install the project into the + destination directory: + <literallayout class='monospaced'> + $ make + $ make install DESTDIR=./tmp + </literallayout></para></listitem> + <listitem><para><emphasis>Verify the installation:</emphasis> + This command is a simple way to verify the installation + of your project. + Running the command prints the architecture on which + the binary file can run. + This architecture should be the same architecture that + the installed cross-toolchain supports. + <literallayout class='monospaced'> + $ file ./tmp/usr/local/bin/hello + </literallayout></para></listitem> + <listitem><para><emphasis>Execute your project:</emphasis> + To execute the project in the shell, simply enter the name. + You could also copy the binary to the actual target hardware + and run the project there as well: + <literallayout class='monospaced'> + $ ./hello + </literallayout> + As expected, the project displays the "Hello World!" message. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='passing-host-options'> + <title>Passing Host Options</title> + + <para> + For an Autotools-based project, you can use the cross-toolchain by just + passing the appropriate host option to <filename>configure.sh</filename>. + The host option you use is derived from the name of the environment setup + script found in the directory in which you installed the cross-toolchain. + For example, the host option for an ARM-based target that uses the GNU EABI + is <filename>armv5te-poky-linux-gnueabi</filename>. + You will notice that the name of the script is + <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>. + Thus, the following command works to update your project and + rebuild it using the appropriate cross-toolchain tools: + <literallayout class='monospaced'> + $ ./configure --host=armv5te-poky-linux-gnueabi \ + --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable> + </literallayout> + <note> + If the <filename>configure</filename> script results in problems recognizing the + <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option, + regenerate the script to enable the support by doing the following and then + run the script again: + <literallayout class='monospaced'> + $ libtoolize --automake + $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \ + [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>] + $ autoconf + $ autoheader + $ automake -a + </literallayout> + </note> + </para> + </section> +</section> + +<section id='makefile-based-projects'> +<title>Makefile-Based Projects</title> + + <para> + For Makefile-based projects, the cross-toolchain environment variables + established by running the cross-toolchain environment setup script + are subject to general <filename>make</filename> rules. + </para> + + <para> + To illustrate this, consider the following four cross-toolchain + environment variables: + <literallayout class='monospaced'> + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux + <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux + <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types + <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types + </literallayout> + Now, consider the following three cases: + <itemizedlist> + <listitem><para><emphasis>Case 1 - No Variables Set in the <filename>Makefile</filename>:</emphasis> + Because these variables are not specifically set in the + <filename>Makefile</filename>, the variables retain their + values based on the environment. + </para></listitem> + <listitem><para><emphasis>Case 2 - Variables Set in the <filename>Makefile</filename>:</emphasis> + Specifically setting variables in the + <filename>Makefile</filename> during the build results in the + environment settings of the variables being overwritten. + </para></listitem> + <listitem><para><emphasis>Case 3 - Variables Set when the <filename>Makefile</filename> is Executed from the Command Line:</emphasis> + Executing the <filename>Makefile</filename> from the command + line results in the variables being overwritten with + command-line content regardless of what is being set in the + <filename>Makefile</filename>. + In this case, environment variables are not considered unless + you use the "-e" flag during the build: + <literallayout class='monospaced'> + $ make -e <replaceable>file</replaceable> + </literallayout> + If you use this flag, then the environment values of the + variables override any variables specifically set in the + <filename>Makefile</filename>. + </para></listitem> + </itemizedlist> + <note> + For the list of variables set up by the cross-toolchain environment + setup script, see the + "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>" + section. + </note> + </para> +</section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/poky/documentation/adt-manual/adt-intro.xml b/poky/documentation/adt-manual/adt-intro.xml new file mode 100644 index 000000000..597c7120b --- /dev/null +++ b/poky/documentation/adt-manual/adt-intro.xml @@ -0,0 +1,180 @@ +<!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; ] > + +<chapter id='adt-intro'> + <title>The Application Development Toolkit (ADT)</title> + + <para> + Part of the Yocto Project development solution is an Application Development + Toolkit (ADT). + The ADT provides you with a custom-built, cross-development + platform suited for developing a user-targeted product application. + </para> + + <para> + Fundamentally, the ADT consists of the following: + <itemizedlist> + <listitem><para>An architecture-specific cross-toolchain and matching + sysroot both built by the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. + The toolchain and sysroot are based on a + <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> + configuration and extensions, + which allows you to cross-develop on the host machine for the target hardware. + </para></listitem> + <listitem><para>The Eclipse IDE Yocto Plug-in.</para></listitem> + <listitem><para>The Quick EMUlator (QEMU), which lets you simulate target hardware. + </para></listitem> + <listitem><para>Various user-space tools that greatly enhance your application + development experience.</para></listitem> + </itemizedlist> + </para> + + <section id='the-cross-development-toolchain'> + <title>The Cross-Development Toolchain</title> + + <para> + The + <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink> + consists of a cross-compiler, cross-linker, and cross-debugger + that are used to develop user-space applications for targeted + hardware. + This toolchain is created either by running the ADT Installer + script, a toolchain installer script, or through a + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + that is based on your Metadata configuration or extension for + your targeted device. + The cross-toolchain works with a matching target sysroot. + </para> + </section> + + <section id='sysroot'> + <title>Sysroot</title> + + <para> + The matching target sysroot contains needed headers and libraries for generating + binaries that run on the target architecture. + The sysroot is based on the target root filesystem image that is built by + the OpenEmbedded build system and uses the same Metadata configuration + used to build the cross-toolchain. + </para> + </section> + + <section id='eclipse-overview'> + <title>Eclipse Yocto Plug-in</title> + + <para> + The Eclipse IDE is a popular development environment and it fully supports + development using the Yocto Project. + When you install and configure the Eclipse Yocto Project Plug-in into + the Eclipse IDE, you maximize your Yocto Project experience. + Installing and configuring the Plug-in results in an environment that + has extensions specifically designed to let you more easily develop software. + These extensions allow for cross-compilation, deployment, and execution of + your output into a QEMU emulation session. + You can also perform cross-debugging and profiling. + The environment also supports a suite of tools that allows you to perform + remote profiling, tracing, collection of power data, collection of + latency data, and collection of performance data. + </para> + + <para> + For information about the application development workflow that uses the Eclipse + IDE and for a detailed example of how to install and configure the Eclipse + Yocto Project Plug-in, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working Within Eclipse</ulink>" section + of the Yocto Project Development Manual. + </para> + </section> + + <section id='the-qemu-emulator'> + <title>The QEMU Emulator</title> + + <para> + The QEMU emulator allows you to simulate your hardware while running your + application or image. + QEMU is made available a number of ways: + <itemizedlist> + <listitem><para> + If you use the ADT Installer script to install ADT, you can + specify whether or not to install QEMU. + </para></listitem> + <listitem><para> + If you have cloned the <filename>poky</filename> Git + repository to create a + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + and you have sourced the environment setup script, QEMU is + installed and automatically available. + </para></listitem> + <listitem><para> + If you have downloaded a Yocto Project release and unpacked + it to create a + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + and you have sourced the environment setup script, QEMU is + installed and automatically available. + </para></listitem> + <listitem><para> + If you have installed the cross-toolchain tarball and you + have sourced the toolchain's setup environment script, QEMU + is also installed and automatically available. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='user-space-tools'> + <title>User-Space Tools</title> + + <para> + User-space tools are included as part of the Yocto Project. + You will find these tools helpful during development. + The tools include LatencyTOP, PowerTOP, OProfile, Perf, SystemTap, and Lttng-ust. + These tools are common development tools for the Linux platform. + <itemizedlist> + <listitem><para><emphasis>LatencyTOP:</emphasis> LatencyTOP focuses on latency + that causes skips in audio, + stutters in your desktop experience, or situations that overload your server + even when you have plenty of CPU power left. + </para></listitem> + <listitem><para><emphasis>PowerTOP:</emphasis> Helps you determine what + software is using the most power. + You can find out more about PowerTOP at + <ulink url='https://01.org/powertop/'></ulink>.</para></listitem> + <listitem><para><emphasis>OProfile:</emphasis> A system-wide profiler for Linux + systems that is capable of profiling all running code at low overhead. + You can find out more about OProfile at + <ulink url='http://oprofile.sourceforge.net/about/'></ulink>. + For examples on how to setup and use this tool, see the + "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>OProfile</ulink>" + section in the Yocto Project Profiling and Tracing Manual. + </para></listitem> + <listitem><para><emphasis>Perf:</emphasis> Performance counters for Linux used + to keep track of certain types of hardware and software events. + For more information on these types of counters see + <ulink url='https://perf.wiki.kernel.org/'></ulink>. + For examples on how to setup and use this tool, see the + "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>" + section in the Yocto Project Profiling and Tracing Manual. + </para></listitem> + <listitem><para><emphasis>SystemTap:</emphasis> A free software infrastructure + that simplifies information gathering about a running Linux system. + This information helps you diagnose performance or functional problems. + SystemTap is not available as a user-space tool through the Eclipse IDE Yocto Plug-in. + See <ulink url='http://sourceware.org/systemtap'></ulink> for more information + on SystemTap. + For examples on how to setup and use this tool, see the + "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-systemtap'>SystemTap</ulink>" + section in the Yocto Project Profiling and Tracing Manual.</para></listitem> + <listitem><para><emphasis>Lttng-ust:</emphasis> A User-space Tracer designed to + provide detailed information on user-space activity. + See <ulink url='http://lttng.org/ust'></ulink> for more information on Lttng-ust. + </para></listitem> + </itemizedlist> + </para> + </section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/poky/documentation/adt-manual/adt-manual-customization.xsl b/poky/documentation/adt-manual/adt-manual-customization.xsl new file mode 100644 index 000000000..b86be519b --- /dev/null +++ b/poky/documentation/adt-manual/adt-manual-customization.xsl @@ -0,0 +1,27 @@ +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> + + <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> + +<!-- + + <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> + + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> + +--> + + <xsl:include href="../template/permalinks.xsl"/> + <xsl:include href="../template/section.title.xsl"/> + <xsl:include href="../template/component.title.xsl"/> + <xsl:include href="../template/division.title.xsl"/> + <xsl:include href="../template/formal.object.heading.xsl"/> + + <xsl:param name="html.stylesheet" select="'adt-style.css'" /> + <xsl:param name="chapter.autolabel" select="1" /> + <xsl:param name="appendix.autolabel" select="A" /> + <xsl:param name="section.autolabel" select="1" /> + <xsl:param name="section.label.includes.component.label" select="1" /> + <xsl:param name="generate.id.attributes" select="1" /> + +</xsl:stylesheet> diff --git a/poky/documentation/adt-manual/adt-manual-eclipse-customization.xsl b/poky/documentation/adt-manual/adt-manual-eclipse-customization.xsl new file mode 100644 index 000000000..77ba5f571 --- /dev/null +++ b/poky/documentation/adt-manual/adt-manual-eclipse-customization.xsl @@ -0,0 +1,35 @@ +<?xml version='1.0'?> +<xsl:stylesheet + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns="http://www.w3.org/1999/xhtml" + xmlns:fo="http://www.w3.org/1999/XSL/Format" + version="1.0"> + + <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" /> + +<!-- + + <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" /> + + <xsl:import + href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" /> + +--> + + <xsl:param name="chunker.output.indent" select="'yes'"/> + <xsl:param name="chunk.quietly" select="1"/> + <xsl:param name="chunk.first.sections" select="1"/> + <xsl:param name="chunk.section.depth" select="10"/> + <xsl:param name="use.id.as.filename" select="1"/> + <xsl:param name="ulink.target" select="'_self'" /> + <xsl:param name="base.dir" select="'html/adt-manual/'"/> + <xsl:param name="html.stylesheet" select="'../book.css'"/> + <xsl:param name="eclipse.manifest" select="0"/> + <xsl:param name="create.plugin.xml" select="0"/> + <xsl:param name="suppress.navigation" select="1"/> + <xsl:param name="generate.index" select="0"/> + <xsl:param name="chapter.autolabel" select="1" /> + <xsl:param name="appendix.autolabel" select="1" /> + <xsl:param name="section.autolabel" select="1" /> + <xsl:param name="section.label.includes.component.label" select="1" /> +</xsl:stylesheet> diff --git a/poky/documentation/adt-manual/adt-manual-intro.xml b/poky/documentation/adt-manual/adt-manual-intro.xml new file mode 100644 index 000000000..034fdff60 --- /dev/null +++ b/poky/documentation/adt-manual/adt-manual-intro.xml @@ -0,0 +1,33 @@ +<!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; ] > + +<chapter id='adt-manual-intro'> +<title>Introduction</title> + + <para> + Welcome to the Yocto Project Application Developer's Guide. + This manual provides information that lets you begin developing applications + using the Yocto Project. + </para> + + <para> + The Yocto Project provides an application development environment based on + an Application Development Toolkit (ADT) and the availability of stand-alone + cross-development toolchains and other tools. + This manual describes the ADT and how you can configure and install it, + how to access and use the cross-development toolchains, how to + customize the development packages installation, + how to use command-line development for both Autotools-based and + Makefile-based projects, and an introduction to the + <trademark class='trade'>Eclipse</trademark> IDE Yocto Plug-in. + <note> + The ADT is distribution-neutral and does not require the Yocto + Project reference distribution, which is called Poky. + This manual, however, uses examples that use the Poky distribution. + </note> + </para> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/poky/documentation/adt-manual/adt-manual.xml b/poky/documentation/adt-manual/adt-manual.xml new file mode 100644 index 000000000..972f8bf08 --- /dev/null +++ b/poky/documentation/adt-manual/adt-manual.xml @@ -0,0 +1,140 @@ +<!DOCTYPE book 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; ] > + +<book id='adt-manual' lang='en' + xmlns:xi="http://www.w3.org/2003/XInclude" + xmlns="http://docbook.org/ns/docbook" + > + <bookinfo> + + <mediaobject> + <imageobject> + <imagedata fileref='figures/adt-title.png' + format='SVG' + align='left' scalefit='1' width='100%'/> + </imageobject> + </mediaobject> + + <title> + Yocto Project Application Developer's Guide + </title> + + <authorgroup> + <author> + <firstname>Jessica</firstname> <surname>Zhang</surname> + <affiliation> + <orgname>Intel Corporation</orgname> + </affiliation> + <email>jessica.zhang@intel.com</email> + </author> + </authorgroup> + + <revhistory> + <revision> + <revnumber>1.0</revnumber> + <date>6 April 2011</date> + <revremark>Released with the Yocto Project 1.0 Release.</revremark> + </revision> + <revision> + <revnumber>1.0.1</revnumber> + <date>23 May 2011</date> + <revremark>Released with the Yocto Project 1.0.1 Release.</revremark> + </revision> + <revision> + <revnumber>1.1</revnumber> + <date>6 October 2011</date> + <revremark>Released with the Yocto Project 1.1 Release.</revremark> + </revision> + <revision> + <revnumber>1.2</revnumber> + <date>April 2012</date> + <revremark>Released with the Yocto Project 1.2 Release.</revremark> + </revision> + <revision> + <revnumber>1.3</revnumber> + <date>October 2012</date> + <revremark>Released with the Yocto Project 1.3 Release.</revremark> + </revision> + <revision> + <revnumber>1.4</revnumber> + <date>April 2013</date> + <revremark>Released with the Yocto Project 1.4 Release.</revremark> + </revision> + <revision> + <revnumber>1.5</revnumber> + <date>October 2013</date> + <revremark>Released with the Yocto Project 1.5 Release.</revremark> + </revision> + <revision> + <revnumber>1.5.1</revnumber> + <date>January 2014</date> + <revremark>Released with the Yocto Project 1.5.1 Release.</revremark> + </revision> + <revision> + <revnumber>1.6</revnumber> + <date>April 2014</date> + <revremark>Released with the Yocto Project 1.6 Release.</revremark> + </revision> + <revision> + <revnumber>1.7</revnumber> + <date>October 2014</date> + <revremark>Released with the Yocto Project 1.7 Release.</revremark> + </revision> + <revision> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> + <revision> + <revnumber>2.0</revnumber> + <date>October 2015</date> + <revremark>Released with the Yocto Project 2.0 Release.</revremark> + </revision> + <revision> + <revnumber>2.1</revnumber> + <date>Sometime in 2016</date> + <revremark>Released with the future Yocto Project 2.1 Release.</revremark> + </revision> + </revhistory> + + <copyright> + <year>©RIGHT_YEAR;</year> + <holder>Linux Foundation</holder> + </copyright> + + <legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. + </para> + <note> + For the latest version of this manual associated with this + Yocto Project release, see the + <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink> + from the Yocto Project website. + </note> + + </legalnotice> + + </bookinfo> + + <xi:include href="adt-manual-intro.xml"/> + + <xi:include href="adt-intro.xml"/> + + <xi:include href="adt-prepare.xml"/> + + <xi:include href="adt-package.xml"/> + + <xi:include href="adt-command.xml"/> + +<!-- <index id='index'> + <title>Index</title> + </index> +--> + +</book> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/poky/documentation/adt-manual/adt-package.xml b/poky/documentation/adt-manual/adt-package.xml new file mode 100644 index 000000000..68eee9b38 --- /dev/null +++ b/poky/documentation/adt-manual/adt-package.xml @@ -0,0 +1,102 @@ +<!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; ] > + +<chapter id='adt-package'> +<title>Optionally Customizing the Development Packages Installation</title> + + <para> + Because the Yocto Project is suited for embedded Linux development, it is + likely that you will need to customize your development packages installation. + For example, if you are developing a minimal image, then you might not need + certain packages (e.g. graphics support packages). + Thus, you would like to be able to remove those packages from your target sysroot. + </para> + +<section id='package-management-systems'> + <title>Package Management Systems</title> + + <para> + The OpenEmbedded build system supports the generation of sysroot files using + three different Package Management Systems (PMS): + <itemizedlist> + <listitem><para><emphasis>OPKG:</emphasis> A less well known PMS whose use + originated in the OpenEmbedded and OpenWrt embedded Linux projects. + This PMS works with files packaged in an <filename>.ipk</filename> format. + See <ulink url='http://en.wikipedia.org/wiki/Opkg'></ulink> for more + information about OPKG.</para></listitem> + <listitem><para><emphasis>RPM:</emphasis> A more widely known PMS intended for GNU/Linux + distributions. + This PMS works with files packaged in an <filename>.rpm</filename> format. + The build system currently installs through this PMS by default. + See <ulink url='http://en.wikipedia.org/wiki/RPM_Package_Manager'></ulink> + for more information about RPM.</para></listitem> + <listitem><para><emphasis>Debian:</emphasis> The PMS for Debian-based systems + is built on many PMS tools. + The lower-level PMS tool <filename>dpkg</filename> forms the base of the Debian PMS. + For information on dpkg see + <ulink url='http://en.wikipedia.org/wiki/Dpkg'></ulink>.</para></listitem> + </itemizedlist> + </para> +</section> + +<section id='configuring-the-pms'> + <title>Configuring the PMS</title> + + <para> + Whichever PMS you are using, you need to be sure that the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink> + variable in the <filename>conf/local.conf</filename> + file is set to reflect that system. + The first value you choose for the variable specifies the package file format for the root + filesystem at sysroot. + Additional values specify additional formats for convenience or testing. + See the <filename>conf/local.conf</filename> configuration file for + details. + </para> + + <note> + For build performance information related to the PMS, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package.bbclass</filename></ulink>" + section in the Yocto Project Reference Manual. + </note> + + <para> + As an example, consider a scenario where you are using OPKG and you want to add + the <filename>libglade</filename> package to the target sysroot. + </para> + + <para> + First, you should generate the IPK file for the + <filename>libglade</filename> package and add it + into a working <filename>opkg</filename> repository. + Use these commands: + <literallayout class='monospaced'> + $ bitbake libglade + $ bitbake package-index + </literallayout> + </para> + + <para> + Next, source the cross-toolchain environment setup script found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + Follow that by setting up the installation destination to point to your + sysroot as <replaceable>sysroot_dir</replaceable>. + Finally, have an OPKG configuration file <replaceable>conf_file</replaceable> + that corresponds to the <filename>opkg</filename> repository you have just created. + The following command forms should now work: + <literallayout class='monospaced'> + $ opkg-cl –f <replaceable>conf_file</replaceable> -o <replaceable>sysroot_dir</replaceable> update + $ opkg-cl –f <replaceable>cconf_file</replaceable> -o <replaceable>sysroot_dir</replaceable> \ + --force-overwrite install libglade + $ opkg-cl –f <replaceable>cconf_file</replaceable> -o <replaceable>sysroot_dir</replaceable> \ + --force-overwrite install libglade-dbg + $ opkg-cl –f <replaceable>conf_file> -o </replaceable>sysroot_dir> \ + --force-overwrite install libglade-dev + </literallayout> + </para> +</section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/poky/documentation/adt-manual/adt-prepare.xml b/poky/documentation/adt-manual/adt-prepare.xml new file mode 100644 index 000000000..65df1d03e --- /dev/null +++ b/poky/documentation/adt-manual/adt-prepare.xml @@ -0,0 +1,999 @@ +<!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; ] > + +<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 +--> diff --git a/poky/documentation/adt-manual/adt-style.css b/poky/documentation/adt-manual/adt-style.css new file mode 100644 index 000000000..d722ad4b7 --- /dev/null +++ b/poky/documentation/adt-manual/adt-style.css @@ -0,0 +1,984 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/adt-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/poky/documentation/adt-manual/figures/adt-title.png b/poky/documentation/adt-manual/figures/adt-title.png Binary files differnew file mode 100644 index 000000000..6e71e41f1 --- /dev/null +++ b/poky/documentation/adt-manual/figures/adt-title.png diff --git a/poky/documentation/adt-manual/figures/using-a-pre-built-image.png b/poky/documentation/adt-manual/figures/using-a-pre-built-image.png Binary files differnew file mode 100644 index 000000000..b03130d12 --- /dev/null +++ b/poky/documentation/adt-manual/figures/using-a-pre-built-image.png |