diff options
Diffstat (limited to 'documentation/adt-manual')
17 files changed, 0 insertions, 3957 deletions
diff --git a/documentation/adt-manual/adt-command.rst b/documentation/adt-manual/adt-command.rst deleted file mode 100644 index de854772bb..0000000000 --- a/documentation/adt-manual/adt-command.rst +++ /dev/null @@ -1,180 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK - -********************** -Using the Command Line -********************** - -Recall that earlier the manual discussed how to use an existing -toolchain tarball that had been installed into the default installation -directory, ``/opt/poky/DISTRO``, which is outside of the :term:`Build Directory` -(see the section -"`Using a Cross-Toolchain -Tarball) <#using-an-existing-toolchain-tarball>`__". And, that sourcing -your architecture-specific environment setup script initializes a -suitable cross-toolchain development environment. - -During this setup, locations for the compiler, QEMU scripts, QEMU -binary, a special version of ``pkgconfig`` and other useful utilities -are added to the ``PATH`` variable. Also, variables to assist -``pkgconfig`` and ``autotools`` are also defined so that, for example, -``configure.sh`` can find pre-generated test results for tests that need -target hardware on which to run. You can see the "`Setting Up the -Cross-Development -Environment <#setting-up-the-cross-development-environment>`__" section -for the list of cross-toolchain environment variables established by the -script. - -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. - -Autotools-Based Projects -======================== - -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. - -Creating and Running a Project Based on GNU Autotools ------------------------------------------------------ - -Follow these steps to create a simple Autotools-based project: - -1. *Create your directory:* Create a clean directory for your project - and then make that directory your working location: $ mkdir - $HOME/helloworld $ cd $HOME/helloworld - -2. *Populate the directory:* Create ``hello.c``, ``Makefile.am``, and - ``configure.in`` files as follows: - - - For ``hello.c``, include these lines: #include <stdio.h> main() { - printf("Hello World!\n"); } - - - For ``Makefile.am``, include these lines: bin_PROGRAMS = hello - hello_SOURCES = hello.c - - - For ``configure.in``, include these lines: AC_INIT(hello.c) - AM_INIT_AUTOMAKE(hello,0.1) AC_PROG_CC AC_PROG_INSTALL - AC_OUTPUT(Makefile) - -3. *Source the cross-toolchain environment setup file:* 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: $ source - /opt/poky/DISTRO/environment-setup-i586-poky-linux - -4. *Generate the local aclocal.m4 files and create the configure - script:* The following GNU Autotools generate the local - ``aclocal.m4`` files and create the configure script: $ aclocal $ - autoconf - -5. *Generate files needed by GNU coding standards:* GNU coding - standards require certain files in order for the project to be - compliant. This command creates those files: $ touch NEWS README - AUTHORS ChangeLog - -6. *Generate the configure file:* This command generates the - ``configure``: $ automake -a - -7. *Cross-compile the project:* This command compiles the project using - the cross-compiler. The - :term:`CONFIGURE_FLAGS` - environment variable provides the minimal arguments for GNU - configure: $ ./configure ${CONFIGURE_FLAGS} - -8. *Make and install the project:* These two commands generate and - install the project into the destination directory: $ make $ make - install DESTDIR=./tmp - -9. *Verify the installation:* 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. $ file ./tmp/usr/local/bin/hello - -10. *Execute your project:* 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: $ ./hello As expected, - the project displays the "Hello World!" message. - -Passing Host Options --------------------- - -For an Autotools-based project, you can use the cross-toolchain by just -passing the appropriate host option to ``configure.sh``. 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 ``armv5te-poky-linux-gnueabi``. You will notice that the name of the -script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the -following command works to update your project and rebuild it using the -appropriate cross-toolchain tools: $ ./configure ---host=armv5te-poky-linux-gnueabi \\ --with-libtool-sysroot=sysroot_dir - -.. note:: - - If the - configure - script results in problems recognizing the - --with-libtool-sysroot= - sysroot-dir - option, regenerate the script to enable the support by doing the - following and then run the script again: - :: - - $ libtoolize --automake - $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \ - [-I dir_containing_your_project-specific_m4_macros] - $ autoconf - $ autoheader - $ automake -a - - -Makefile-Based Projects -======================= - -For Makefile-based projects, the cross-toolchain environment variables -established by running the cross-toolchain environment setup script are -subject to general ``make`` rules. - -To illustrate this, consider the following four cross-toolchain -environment variables: -:term:`CC`\ =i586-poky-linux-gcc -m32 --march=i586 --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux -:term:`LD`\ =i586-poky-linux-ld ---sysroot=/opt/poky/1.8/sysroots/i586-poky-linux -:term:`CFLAGS`\ =-O2 -pipe -g --feliminate-unused-debug-types -:term:`CXXFLAGS`\ =-O2 -pipe -g --feliminate-unused-debug-types Now, consider the following three cases: - -- *Case 1 - No Variables Set in the ``Makefile``:* Because these - variables are not specifically set in the ``Makefile``, the variables - retain their values based on the environment. - -- *Case 2 - Variables Set in the ``Makefile``:* Specifically setting - variables in the ``Makefile`` during the build results in the - environment settings of the variables being overwritten. - -- *Case 3 - Variables Set when the ``Makefile`` is Executed from the - Command Line:* Executing the ``Makefile`` from the command line - results in the variables being overwritten with command-line content - regardless of what is being set in the ``Makefile``. In this case, - environment variables are not considered unless you use the "-e" flag - during the build: $ make -e file If you use this flag, then the - environment values of the variables override any variables - specifically set in the ``Makefile``. - -.. note:: - - For the list of variables set up by the cross-toolchain environment - setup script, see the " - Setting Up the Cross-Development Environment - " section. diff --git a/documentation/adt-manual/adt-command.xml b/documentation/adt-manual/adt-command.xml deleted file mode 100644 index b88c0ac682..0000000000 --- a/documentation/adt-manual/adt-command.xml +++ /dev/null @@ -1,266 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<chapter id='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/documentation/adt-manual/adt-intro.rst b/documentation/adt-manual/adt-intro.rst deleted file mode 100644 index 5372f4f54f..0000000000 --- a/documentation/adt-manual/adt-intro.rst +++ /dev/null @@ -1,138 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK - -***************************************** -The Application Development Toolkit (ADT) -***************************************** - -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. - -Fundamentally, the ADT consists of the following: - -- An architecture-specific cross-toolchain and matching sysroot both - built by the :term:`OpenEmbedded Build System`. - The toolchain and - sysroot are based on a `Metadata <&YOCTO_DOCS_DEV_URL;#metadata>`__ - configuration and extensions, which allows you to cross-develop on - the host machine for the target hardware. - -- The Eclipse IDE Yocto Plug-in. - -- The Quick EMUlator (QEMU), which lets you simulate target hardware. - -- Various user-space tools that greatly enhance your application - development experience. - -The Cross-Development Toolchain -=============================== - -The `Cross-Development -Toolchain <&YOCTO_DOCS_DEV_URL;#cross-development-toolchain>`__ 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 :term:`Build Directory` -that is based on -your Metadata configuration or extension for your targeted device. The -cross-toolchain works with a matching target sysroot. - -Sysroot -======= - -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. - -.. _eclipse-overview: - -Eclipse Yocto Plug-in -===================== - -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. - -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 "`Working Within -Eclipse <&YOCTO_DOCS_DEV_URL;#adt-eclipse>`__" section of the Yocto -Project Development Manual. - -The QEMU Emulator -================= - -The QEMU emulator allows you to simulate your hardware while running -your application or image. QEMU is made available a number of ways: - -- If you use the ADT Installer script to install ADT, you can specify - whether or not to install QEMU. - -- If you have cloned the ``poky`` Git repository to create a - :term:`Source Directory` and you have - sourced the environment setup script, QEMU is installed and - automatically available. - -- If you have downloaded a Yocto Project release and unpacked it to - create a :term:`Source Directory` - and you have sourced the environment setup script, QEMU is installed - and automatically available. - -- 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. - -User-Space Tools -================ - -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. - -- *LatencyTOP:* 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. - -- *PowerTOP:* Helps you determine what software is using the most - power. You can find out more about PowerTOP at - https://01.org/powertop/. - -- *OProfile:* 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 http://oprofile.sourceforge.net/about/. For - examples on how to setup and use this tool, see the - "`OProfile <&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile>`__" - section in the Yocto Project Profiling and Tracing Manual. - -- *Perf:* 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 https://perf.wiki.kernel.org/. For - examples on how to setup and use this tool, see the - "`perf <&YOCTO_DOCS_PROF_URL;#profile-manual-perf>`__" section in the - Yocto Project Profiling and Tracing Manual. - -- *SystemTap:* 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 http://sourceware.org/systemtap for more - information on SystemTap. For examples on how to setup and use this - tool, see the - "`SystemTap <&YOCTO_DOCS_PROF_URL;#profile-manual-systemtap>`__" - section in the Yocto Project Profiling and Tracing Manual. - -- *Lttng-ust:* A User-space Tracer designed to provide detailed - information on user-space activity. See http://lttng.org/ust - for more information on Lttng-ust. diff --git a/documentation/adt-manual/adt-intro.xml b/documentation/adt-manual/adt-intro.xml deleted file mode 100644 index eb75763db3..0000000000 --- a/documentation/adt-manual/adt-intro.xml +++ /dev/null @@ -1,181 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<chapter id='adt-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/documentation/adt-manual/adt-manual-customization.xsl b/documentation/adt-manual/adt-manual-customization.xsl deleted file mode 100644 index 551f7e9e94..0000000000 --- a/documentation/adt-manual/adt-manual-customization.xsl +++ /dev/null @@ -1,28 +0,0 @@ -<?xml version='1.0'?> -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> -<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/documentation/adt-manual/adt-manual-eclipse-customization.xsl b/documentation/adt-manual/adt-manual-eclipse-customization.xsl deleted file mode 100644 index 3d536d5473..0000000000 --- a/documentation/adt-manual/adt-manual-eclipse-customization.xsl +++ /dev/null @@ -1,37 +0,0 @@ -<?xml version='1.0'?> -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<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/documentation/adt-manual/adt-manual-intro.rst b/documentation/adt-manual/adt-manual-intro.rst deleted file mode 100644 index 4e98da16df..0000000000 --- a/documentation/adt-manual/adt-manual-intro.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK - -************ -Introduction -************ - -Welcome to the Yocto Project Application Developer's Guide. This manual -provides information that lets you begin developing applications using -the Yocto Project. - -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 Eclipse 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. diff --git a/documentation/adt-manual/adt-manual-intro.xml b/documentation/adt-manual/adt-manual-intro.xml deleted file mode 100644 index b7a25a54bd..0000000000 --- a/documentation/adt-manual/adt-manual-intro.xml +++ /dev/null @@ -1,34 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<chapter id='adt-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/documentation/adt-manual/adt-manual.rst b/documentation/adt-manual/adt-manual.rst deleted file mode 100644 index 695230c5c4..0000000000 --- a/documentation/adt-manual/adt-manual.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK - -=========================================== -Yocto Project Application Developer's Guide -=========================================== - -| - -.. toctree:: - :caption: Table of Contents - :numbered: - - adt-manual-intro - adt-intro - adt-prepare - adt-package - adt-command diff --git a/documentation/adt-manual/adt-manual.xml b/documentation/adt-manual/adt-manual.xml deleted file mode 100644 index 13202cc0de..0000000000 --- a/documentation/adt-manual/adt-manual.xml +++ /dev/null @@ -1,141 +0,0 @@ -<!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; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<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/documentation/adt-manual/adt-package.rst b/documentation/adt-manual/adt-package.rst deleted file mode 100644 index 787d406e65..0000000000 --- a/documentation/adt-manual/adt-package.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK - -************************************************************ -Optionally Customizing the Development Packages Installation -************************************************************ - -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. - -Package Management Systems -========================== - -The OpenEmbedded build system supports the generation of sysroot files -using three different Package Management Systems (PMS): - -- *OPKG:* A less well known PMS whose use originated in the - OpenEmbedded and OpenWrt embedded Linux projects. This PMS works with - files packaged in an ``.ipk`` format. See - http://en.wikipedia.org/wiki/Opkg for more information about - OPKG. - -- *RPM:* A more widely known PMS intended for GNU/Linux distributions. - This PMS works with files packaged in an ``.rpm`` format. The build - system currently installs through this PMS by default. See - http://en.wikipedia.org/wiki/RPM_Package_Manager for more - information about RPM. - -- *Debian:* The PMS for Debian-based systems is built on many PMS - tools. The lower-level PMS tool ``dpkg`` forms the base of the Debian - PMS. For information on dpkg see - http://en.wikipedia.org/wiki/Dpkg. - -Configuring the PMS -=================== - -Whichever PMS you are using, you need to be sure that the -:term:`PACKAGE_CLASSES` -variable in the ``conf/local.conf`` 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 -``conf/local.conf`` configuration file for details. - -.. note:: - - For build performance information related to the PMS, see the " - package.bbclass - " section in the Yocto Project Reference Manual. - -As an example, consider a scenario where you are using OPKG and you want -to add the ``libglade`` package to the target sysroot. - -First, you should generate the IPK file for the ``libglade`` package and -add it into a working ``opkg`` repository. Use these commands: $ bitbake -libglade $ bitbake package-index - -Next, source the cross-toolchain environment setup script found in the -:term:`Source Directory`. Follow -that by setting up the installation destination to point to your sysroot -as sysroot_dir. Finally, have an OPKG configuration file conf_file that -corresponds to the ``opkg`` repository you have just created. The -following command forms should now work: $ opkg-cl –f conf_file -o -sysroot_dir update $ opkg-cl –f cconf_file -o sysroot_dir \\ ---force-overwrite install libglade $ opkg-cl –f cconf_file -o -sysroot_dir \\ --force-overwrite install libglade-dbg $ opkg-cl –f -conf_file> -osysroot_dir> \\ --force-overwrite install libglade-dev diff --git a/documentation/adt-manual/adt-package.xml b/documentation/adt-manual/adt-package.xml deleted file mode 100644 index eaed0447b6..0000000000 --- a/documentation/adt-manual/adt-package.xml +++ /dev/null @@ -1,103 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<chapter id='adt-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/documentation/adt-manual/adt-prepare.rst b/documentation/adt-manual/adt-prepare.rst deleted file mode 100644 index 9b6bd05147..0000000000 --- a/documentation/adt-manual/adt-prepare.rst +++ /dev/null @@ -1,752 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-2.0-UK - -************************************* -Preparing for Application Development -************************************* - -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. - -.. _installing-the-adt: - -Installing the ADT and Toolchains -================================= - -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 ``source`` the cross-toolchain -environment setup script, which establishes several key environment -variables, before you use a toolchain. See the "`Setting Up the -Cross-Development -Environment <#setting-up-the-cross-development-environment>`__" section -for more information. - -.. note:: - - 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. - - If you must mix installation methods, you might avoid problems by - deleting ``/var/lib/opkg``, thus purging the ``opkg`` package - metadata. - -- *Use the ADT installer script:* This method is the recommended way to - install the ADT because it automates much of the process for you. For - example, you can configure the installation to install the QEMU - emulator and the user-space NFS, specify which root filesystem - profiles to download, and define the target sysroot location. - -- *Use an existing toolchain:* 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. - -- *Use the toolchain from within the Build Directory:* If you already - have a :term:`Build Directory`, - 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. - -Using the ADT Installer ------------------------ - -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. - -For a list of the host packages needed to support ADT installation and -use, see the "ADT Installer Extras" lists in the "`Required Packages for -the Host Development -System <&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system>`__" -section of the Yocto Project Reference Manual. - -Getting the ADT Installer Tarball -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ADT Installer is contained in the ADT Installer tarball. You can get -the tarball using either of these methods: - -- *Download the Tarball:* You can download the tarball from - ` <&YOCTO_ADTINSTALLER_DL_URL;>`__ into any directory. - -- *Build the Tarball:* You can use - :term:`BitBake` to generate the - tarball inside an existing :term:`Build Directory`. - - If you use BitBake to generate the ADT Installer tarball, you must - ``source`` the environment setup script - (````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ or - ```oe-init-build-env-memres`` <&YOCTO_DOCS_REF_URL;#structure-memres-core-script>`__) - located in the Source Directory before running the ``bitbake`` - command that creates the tarball. - - The following example commands establish the - :term:`Source Directory`, check out the - current release branch, set up the build environment while also - creating the default Build Directory, and run the ``bitbake`` command - that results in the tarball - ``poky/build/tmp/deploy/sdk/adt_installer.tar.bz2``: - - .. note:: - - Before using BitBake to build the ADT tarball, be sure to make - sure your - local.conf - file is properly configured. See the " - User Configuration - " section in the Yocto Project Reference Manual for general - configuration information. - - $ 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 - -Configuring and Running the ADT Installer Script -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before running the ADT Installer script, you need to unpack the tarball. -You can unpack the tarball in any directory you wish. 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 ``adt-installer``: $ cd ~ $ cp -poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME $ tar -xjf -adt_installer.tar.bz2 Unpacking it creates the directory -``adt-installer``, which contains the ADT Installer script -(``adt_installer``) and its configuration file (``adt_installer.conf``). - -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. - -The following list describes the configurations you can define for the -ADT Installer. For configuration values and restrictions, see the -comments in the ``adt-installer.conf`` file: - -- ``YOCTOADT_REPO``: This area includes the IPKG-based packages and the - root filesystem upon which the installation is based. If you want to - set up your own IPKG repository pointed to by ``YOCTOADT_REPO``, you - need to be sure that the directory structure follows the same layout - as the reference directory set up at - http://adtrepo.yoctoproject.org. Also, your repository needs - to be accessible through HTTP. - -- ``YOCTOADT_TARGETS``: The machine target architectures for which you - want to set up cross-development environments. - -- ``YOCTOADT_QEMU``: Indicates whether or not to install the emulator - QEMU. - -- ``YOCTOADT_NFS_UTIL``: Indicates whether or not to install user-mode - NFS. If you plan to use the 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 - portmap - or - rpcbind - . If you are running - rpcbind - , you will also need to add the - -i - option when - rpcbind - starts up. Please make sure you understand the security - implications of doing this. You might also have to modify your - firewall settings to allow NFS booting to work. - -- ``YOCTOADT_ROOTFS_``\ arch: The root filesystem images you want to - download from the ``YOCTOADT_IPKG_REPO`` repository. - -- ``YOCTOADT_TARGET_SYSROOT_IMAGE_``\ arch: The particular root - filesystem used to extract and create the target sysroot. The value - of this variable must have been specified with - ``YOCTOADT_ROOTFS_``\ arch. For example, if you downloaded both - ``minimal`` and ``sato-sdk`` images by setting - ``YOCTOADT_ROOTFS_``\ arch to "minimal sato-sdk", then - ``YOCTOADT_ROOTFS_``\ arch must be set to either "minimal" or - "sato-sdk". - -- ``YOCTOADT_TARGET_SYSROOT_LOC_``\ arch: The location on the - development host where the target sysroot is created. - -After you have configured the ``adt_installer.conf`` file, run the -installer using the following command: $ cd adt-installer $ -./adt_installer Once the installer begins to run, you are asked to enter -the location for cross-toolchain installation. The default location is -``/opt/poky/``\ release. 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. - -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 ``adt-installer`` -directory according to your installer configurations, and the target -sysroot located according to the ``YOCTOADT_TARGET_SYSROOT_LOC_``\ arch -variable also in your configuration file. - -.. _using-an-existing-toolchain-tarball: - -Using a Cross-Toolchain Tarball -------------------------------- - -If you want to simply install a cross-toolchain by hand, you can do so -by running the toolchain installer. The installer includes the pre-built -cross-toolchain, the ``runqemu`` 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 "`Extracting the -Root Filesystem <#extracting-the-root-filesystem>`__" section. - -Follow these steps: - -1. *Get your toolchain installer using one of the following methods:* - - - Go to ` <&YOCTO_TOOLCHAIN_DL_URL;>`__ and find the folder that - matches your host development system (i.e. ``i686`` for 32-bit - machines or ``x86_64`` for 64-bit machines). - - Go into that folder and download the toolchain installer whose - name includes the appropriate target architecture. The toolchains - provided by the Yocto Project are based off of the - ``core-image-sato`` 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 - ``x86_64`` folder and download the following installer: - poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh - - - 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 "`Optionally Building a Toolchain - Installer <#optionally-building-a-toolchain-installer>`__" - section. - -2. *Once you have the installer, run it to install the toolchain:* - - .. note:: - - You must change the permissions on the toolchain installer script - so that it is executable. - - 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 ``~/Downloads/``. $ - ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh - The first thing the installer prompts you for is the directory into - which you want to install the toolchain. The default directory used - is ``/opt/poky/DISTRO``. 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. - - When the script finishes, the cross-toolchain is installed. You will - notice environment setup files for the cross-toolchain in the - installation directory. - -.. _using-the-toolchain-from-within-the-build-tree: - -Using BitBake and the Build Directory -------------------------------------- - -A final way of making the cross-toolchain available is to use BitBake to -generate the toolchain within an existing :term:`Build Directory`. -This method does -not install the toolchain into the default ``/opt`` directory. As with -the previous method, if you need to install the target sysroot, you must -do that separately as well. - -Follow these steps to generate the toolchain into the Build Directory: - -1. *Set up the Build Environment:* Source the OpenEmbedded build - environment setup script (i.e. - ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ or - ```oe-init-build-env-memres`` <&YOCTO_DOCS_REF_URL;#structure-memres-core-script>`__) - located in the :term:`Source Directory`. - -2. *Check your Local Configuration File:* At this point, you should be - sure that the :term:`MACHINE` - variable in the ``local.conf`` file found in the ``conf`` directory - of the Build Directory is set for the target architecture. Comments - within the ``local.conf`` file list the values you can use for the - ``MACHINE`` variable. If you do not change the ``MACHINE`` variable, - the OpenEmbedded build system uses ``qemux86`` 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 - MACHINE - variable in the - local.conf - file and re-run the - bitbake - command. - -3. *Make Sure Your Layers are Enabled:* Examine the - ``conf/bblayers.conf`` 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 "`Enabling Your - Layer <&YOCTO_DOCS_DEV_URL;#enabling-your-layer>`__" section in the - Yocto Project Development Manual. - -4. *Generate the Cross-Toolchain:* Run ``bitbake meta-ide-support`` to - complete the cross-toolchain generation. Once the ``bitbake`` 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 "``environment-setup``" in - the Build Directory's ``tmp`` folder. - - 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 "`Extracting the Root - Filesystem <#extracting-the-root-filesystem>`__" section. - -Setting Up the Cross-Development Environment -============================================ - -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 ````. If you installed the toolchain in the -:term:`Build Directory`, you can find the -environment setup script for the toolchain in the Build Directory's -``tmp`` directory. - -Be sure to run the environment setup script that matches the -architecture for which you are developing. Environment setup scripts -begin with the string "``environment-setup``" and include as part of -their name the architecture. For example, the toolchain environment -setup script for a 64-bit IA-based architecture installed in the default -installation directory would be the following: -YOCTO_ADTPATH_DIR/environment-setup-x86_64-poky-linux When you run the -setup script, many environment variables are defined: -:term:`SDKTARGETSYSROOT` - -The path to the sysroot used for cross-compilation -:term:`PKG_CONFIG_PATH` - The -path to the target pkg-config files -:term:`CONFIG_SITE` - A GNU -autoconf site file preconfigured for the target -:term:`CC` - The minimal command and -arguments to run the C compiler -:term:`CXX` - The minimal command and -arguments to run the C++ compiler -:term:`CPP` - The minimal command and -arguments to run the C preprocessor -:term:`AS` - The minimal command and -arguments to run the assembler :term:`LD` -- The minimal command and arguments to run the linker -:term:`GDB` - The minimal command and -arguments to run the GNU Debugger -:term:`STRIP` - The minimal command and -arguments to run 'strip', which strips symbols -:term:`RANLIB` - The minimal command -and arguments to run 'ranlib' -:term:`OBJCOPY` - The minimal command -and arguments to run 'objcopy' -:term:`OBJDUMP` - The minimal command -and arguments to run 'objdump' :term:`AR` -- The minimal command and arguments to run 'ar' -:term:`NM` - The minimal command and -arguments to run 'nm' -:term:`TARGET_PREFIX` - The -toolchain binary prefix for the target tools -:term:`CROSS_COMPILE` - The -toolchain binary prefix for the target tools -:term:`CONFIGURE_FLAGS` - The -minimal arguments for GNU configure -:term:`CFLAGS` - Suggested C flags -:term:`CXXFLAGS` - Suggested C++ -flags :term:`LDFLAGS` - Suggested -linker flags when you use CC to link -:term:`CPPFLAGS` - Suggested -preprocessor flags - -Securing Kernel and Filesystem Images -===================================== - -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. - -Getting the Images ------------------- - -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 "`Buiding -Images <&YOCTO_DOCS_QS_URL;#qs-buiding-images>`__" section of the Yocto -Project Quick Start. For an example of downloading pre-build versions, -see the "`Example Using Pre-Built Binaries and -QEMU <#using-pre-built>`__" section. - -The Yocto Project ships basic kernel and filesystem images for several -architectures (``x86``, ``x86-64``, ``mips``, ``powerpc``, and ``arm``) -that you can use unaltered in the QEMU emulator. These kernel images -reside in the release area - ` <&YOCTO_MACHINES_DL_URL;>`__ and are -ideal for experimentation using Yocto Project. For information on the -image types you can build using the OpenEmbedded build system, see the -":ref:`ref-manual/ref-images:Images`" chapter in the Yocto -Project Reference Manual. - -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. -``core-image-*-dev``), you must be sure to include the development -packages as part of your image recipe. - -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 (``tcf-agent``). You can do -this by including the ``eclipse-debug`` image feature. - -.. note:: - - See the " - Image Features - " section in the Yocto Project Reference Manual for information on - image features. - -To include the ``eclipse-debug`` image feature, modify your -``local.conf`` file in the :term:`Build Directory` -so that the -:term:`EXTRA_IMAGE_FEATURES` -variable includes the "eclipse-debug" feature. After modifying the -configuration file, you can rebuild the image. Once the image is -rebuilt, the ``tcf-agent`` will be included in the image and is launched -automatically after the boot. - -Extracting the Root Filesystem ------------------------------- - -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. - -Here are some cases where you need to extract the root filesystem: - -- You want to boot the image using NFS. - -- 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. - -- You want to develop your target application using the root filesystem - as the target sysroot. - -To extract the root filesystem, first ``source`` 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 ``tmp`` directory. If you installed -the toolchain by hand, the environment setup script is located in -``/opt/poky/DISTRO``. - -After sourcing the environment script, use the ``runqemu-extract-sdk`` -command and provide the filesystem image. - -Following is an example. The second command sets up the environment. In -this case, the setup script is located in the ``/opt/poky/DISTRO`` -directory. The third command extracts the root filesystem from a -previously built filesystem that is located in the ``~/Downloads`` -directory. Furthermore, this command extracts the root filesystem into -the ``qemux86-sato`` directory: $ 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 You could now point to the target sysroot at -``qemux86-sato``. - -Optionally Building a Toolchain Installer -========================================= - -As an alternative to locating and downloading a toolchain installer, you -can build the toolchain installer if you have a :term:`Build Directory`. - -.. note:: - - Although not the preferred method, it is also possible to use - bitbake meta-toolchain - 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 " - Extracting the Root Filesystem - " section. - -To build the toolchain installer and populate the SDK image, use the -following command: $ bitbake image -c populate_sdk The command results -in a toolchain installer that contains the sysroot that matches your -target root filesystem. - -Another powerful feature is that the toolchain is completely -self-contained. The binaries are linked against their own copy of -``libc``, 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 ``populate_sdk`` archive. - -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 ``gcc`` as a set of -compiler options. Those options are set up by the environment script and -contained in variables such as :term:`CC` -and :term:`LD`. 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. - -Remember, before using any BitBake command, you must source the build -environment setup script (i.e. -````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ or -```oe-init-build-env-memres`` <&YOCTO_DOCS_REF_URL;#structure-memres-core-script>`__) -located in the Source Directory and you must make sure your -``conf/local.conf`` variables are correct. In particular, you need to be -sure the :term:`MACHINE` variable -matches the architecture for which you are building and that the -:term:`SDKMACHINE` 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). - -When the ``bitbake`` command completes, the toolchain installer will be -in ``tmp/deploy/sdk`` 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 - IMAGE_INSTALL - variable inside your - local.conf - file to install the appropriate library packages. Following is an - example using - glibc - static development libraries: - :: - - IMAGE_INSTALL_append = " glibc-staticdev" - - -Optionally Using an External Toolchain -====================================== - -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: - -- 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. - -- Make sure you add the layer that contains the toolchain to your - ``bblayers.conf`` file through the - :term:`BBLAYERS` variable. - -- Set the - :term:`EXTERNAL_TOOLCHAIN` - variable in your ``local.conf`` file to the location in which you - installed the toolchain. - -A good example of an external toolchain used with the Yocto Project is -Mentor Graphics Sourcery G++ Toolchain. You can see information on how -to use that particular layer in the ``README`` file at -http://github.com/MentorEmbedded/meta-sourcery/. You can find -further information by reading about the -:term:`TCMODE` variable in the Yocto -Project Reference Manual's variable glossary. - -.. _using-pre-built: - -Example Using Pre-Built Binaries and QEMU -========================================= - -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. - -|Using a Pre-Built Image| - -For this scenario, you need to do several things: - -- Install the appropriate stand-alone toolchain tarball. - -- 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.). - -- Download the filesystem image for your target machine's architecture. - -- Set up the environment to emulate the hardware and then start the - QEMU emulator. - -Installing the Toolchain ------------------------- - -You can download a tarball installer, which includes the pre-built -toolchain, the ``runqemu`` script, and support files from the -appropriate directory under ` <&YOCTO_TOOLCHAIN_DL_URL;>`__. Toolchains -are available for 32-bit and 64-bit x86 development systems from the -``i686`` and ``x86_64`` directories, respectively. The toolchains the -Yocto Project provides are based off the ``core-image-sato`` image and -contain libraries appropriate for developing against that image. Each -type of development system supports five or more target architectures. - -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. - -:: - - poky-glibc-host_system-image_type-arch-toolchain-release_version.sh - - Where: - host_system is a string representing your development system: - - i686 or x86_64. - - image_type 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 - - arch is a string representing the tuned target architecture: - - i586, x86_64, powerpc, mips, armv7a or armv5te - - release_version is a string representing the release number of the - Yocto Project: - - DISTRO, DISTRO+snapshot - - -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 ``core-image-sato``: -poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh - -Toolchains are self-contained and by default are installed into -``/opt/poky``. However, when you run the toolchain installer, you can -choose an installation directory. - -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. - -The example assumes the toolchain installer is located in -``~/Downloads/``. - -.. 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. - -$ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh - -For more information on how to install tarballs, see the "`Using a -Cross-Toolchain -Tarball <&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball>`__" -and "`Using BitBake and the Build -Directory <&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree>`__" -sections in the Yocto Project Application Developer's Guide. - -Downloading the Pre-Built Linux Kernel --------------------------------------- - -You can download the pre-built Linux kernel suitable for running in the -QEMU emulator from ` <&YOCTO_QEMU_DL_URL;>`__. Be sure to use the kernel -that matches the architecture you want to simulate. Download areas exist -for the five supported machine architectures: ``qemuarm``, ``qemumips``, -``qemuppc``, ``qemux86``, and ``qemux86-64``. - -Most kernel files have one of the following forms: \*zImage-qemuarch.bin -vmlinux-qemuarch.bin Where: arch is a string representing the target -architecture: x86, x86-64, ppc, mips, or arm. - -You can learn more about downloading a Yocto Project kernel in the -"`Yocto Project Kernel <&YOCTO_DOCS_DEV_URL;#local-kernel-files>`__" -bulleted item in the Yocto Project Development Manual. - -Downloading the Filesystem --------------------------- - -You can also download the filesystem image suitable for your target -architecture from ` <&YOCTO_QEMU_DL_URL;>`__. Again, be sure to use the -filesystem that matches the architecture you want to simulate. - -The filesystem image has two tarball forms: ``ext3`` and ``tar``. You -must use the ``ext3`` form when booting an image using the QEMU -emulator. The ``tar`` form can be flattened out in your host development -system and used for build purposes with the Yocto Project. -core-image-profile-qemuarch.ext3 core-image-profile-qemuarch.tar.bz2 -Where: profile 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 -":ref:`ref-manual/ref-images:Images`" chapter in the Yocto -Project Reference Manual. arch is a string representing the target -architecture: x86, x86-64, ppc, mips, or arm. - -Setting Up the Environment and Starting the QEMU Emulator ---------------------------------------------------------- - -Before you start the QEMU emulator, you need to set up the emulation -environment. The following command form sets up the emulation -environment. $ source -YOCTO_ADTPATH_DIR/environment-setup-arch-poky-linux-if Where: arch is a -string representing the target architecture: i586, x86_64, ppc603e, -mips, or armv5te. if is a string representing an embedded application -binary interface. Not all setup scripts include this string. - -Finally, this command form invokes the QEMU emulator $ runqemu qemuarch -kernel-image filesystem-image Where: qemuarch is a string representing -the target architecture: qemux86, qemux86-64, qemuppc, qemumips, or -qemuarm. kernel-image is the architecture-specific kernel image. -filesystem-image is the .ext3 filesystem image. - -Continuing with the example, the following two commands setup the -emulation environment and launch QEMU. This example assumes the root -filesystem (``.ext3`` 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. $ cd $HOME $ source -YOCTO_ADTPATH_DIR/environment-setup-i586-poky-linux $ runqemu qemux86 -bzImage-qemux86.bin \\ core-image-sato-qemux86.ext3 - -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. - -.. |Using a Pre-Built Image| image:: figures/using-a-pre-built-image.png diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml deleted file mode 100644 index 2dc9843259..0000000000 --- a/documentation/adt-manual/adt-prepare.xml +++ /dev/null @@ -1,1000 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" -[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<chapter id='adt-prepare'> - -<title>Preparing for Application Development</title> - -<para> - In order to develop applications, you need set up your host development system. - Several ways exist that allow you to install cross-development tools, QEMU, the - Eclipse Yocto Plug-in, and other tools. - This chapter describes how to prepare for application development. -</para> - -<section id='installing-the-adt'> - <title>Installing the ADT and Toolchains</title> - - <para> - The following list describes installation methods that set up varying - degrees of tool availability on your system. - Regardless of the installation method you choose, - you must <filename>source</filename> the cross-toolchain - environment setup script, which establishes several key - environment variables, before you use a toolchain. - See the - "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>" - section for more information. - </para> - - <note> - <para> - Avoid mixing installation methods when installing toolchains for - different architectures. - For example, avoid using the ADT Installer to install some - toolchains and then hand-installing cross-development toolchains - by running the toolchain installer for different architectures. - Mixing installation methods can result in situations where the - ADT Installer becomes unreliable and might not install the - toolchain. - </para> - - <para> - If you must mix installation methods, you might avoid problems by - deleting <filename>/var/lib/opkg</filename>, thus purging the - <filename>opkg</filename> package metadata. - </para> - </note> - - <para> - <itemizedlist> - <listitem><para><emphasis>Use the ADT installer script:</emphasis> - This method is the recommended way to install the ADT because it - automates much of the process for you. - For example, you can configure the installation to install the QEMU emulator - and the user-space NFS, specify which root filesystem profiles to download, - and define the target sysroot location.</para></listitem> - <listitem><para><emphasis>Use an existing toolchain:</emphasis> - Using this method, you select and download an architecture-specific - toolchain installer and then run the script to hand-install the toolchain. - If you use this method, you just get the cross-toolchain and QEMU - you do not - get any of the other mentioned benefits had you run the ADT Installer script.</para></listitem> - <listitem><para><emphasis>Use the toolchain from within the Build Directory:</emphasis> - If you already have a - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, - you can build the cross-toolchain within the directory. - However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you - do not get any of the other benefits without taking separate steps.</para></listitem> - </itemizedlist> - </para> - - <section id='using-the-adt-installer'> - <title>Using the ADT Installer</title> - - <para> - To run the ADT Installer, you need to get the ADT Installer tarball, be sure - you have the necessary host development packages that support the ADT Installer, - and then run the ADT Installer Script. - </para> - - <para> - For a list of the host packages needed to support ADT installation and use, see the - "ADT Installer Extras" lists in the - "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" section - of the Yocto Project Reference Manual. - </para> - - <section id='getting-the-adt-installer-tarball'> - <title>Getting the ADT Installer Tarball</title> - - <para> - The ADT Installer is contained in the ADT Installer tarball. - You can get the tarball using either of these methods: - <itemizedlist> - <listitem><para><emphasis>Download the Tarball:</emphasis> - You can download the tarball from - <ulink url='&YOCTO_ADTINSTALLER_DL_URL;'></ulink> into - any directory.</para></listitem> - <listitem><para><emphasis>Build the Tarball:</emphasis> - You can use - <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> - to generate the tarball inside an existing - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. - </para> - <para>If you use BitBake to generate the ADT Installer - tarball, you must <filename>source</filename> the - environment setup script - (<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>) - located in the Source Directory before running the - <filename>bitbake</filename> command that creates the - tarball.</para> - <para>The following example commands establish - the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, - check out the current release branch, set up the - build environment while also creating the default - Build Directory, and run the - <filename>bitbake</filename> command that results in the - tarball - <filename>poky/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>: - <note> - Before using BitBake to build the ADT tarball, be - sure to make sure your - <filename>local.conf</filename> file is properly - configured. - See the - "<ulink url='&YOCTO_DOCS_REF_URL;#user-configuration'>User Configuration</ulink>" - section in the Yocto Project Reference Manual for - general configuration information. - </note> - <literallayout class='monospaced'> - $ cd ~ - $ git clone git://git.yoctoproject.org/poky - $ cd poky - $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; - $ source &OE_INIT_FILE; - $ bitbake adt-installer - </literallayout></para></listitem> - </itemizedlist> - </para> - </section> - - <section id='configuring-and-running-the-adt-installer-script'> - <title>Configuring and Running the ADT Installer Script</title> - - <para> - Before running the ADT Installer script, you need to unpack the tarball. - You can unpack the tarball in any directory you wish. - For example, this command copies the ADT Installer tarball from where - it was built into the home directory and then unpacks the tarball into - a top-level directory named <filename>adt-installer</filename>: - <literallayout class='monospaced'> - $ cd ~ - $ cp poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME - $ tar -xjf adt_installer.tar.bz2 - </literallayout> - Unpacking it creates the directory <filename>adt-installer</filename>, - which contains the ADT Installer script (<filename>adt_installer</filename>) - and its configuration file (<filename>adt_installer.conf</filename>). - </para> - - <para> - Before you run the script, however, you should examine the ADT Installer configuration - file and be sure you are going to get what you want. - Your configurations determine which kernel and filesystem image are downloaded. - </para> - - <para> - The following list describes the configurations you can define for the ADT Installer. - For configuration values and restrictions, see the comments in - the <filename>adt-installer.conf</filename> file: - - <itemizedlist> - <listitem><para><filename>YOCTOADT_REPO</filename>: This area - includes the IPKG-based packages and the root filesystem upon which - the installation is based. - If you want to set up your own IPKG repository pointed to by - <filename>YOCTOADT_REPO</filename>, you need to be sure that the - directory structure follows the same layout as the reference directory - set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>. - Also, your repository needs to be accessible through HTTP.</para></listitem> - <listitem><para><filename>YOCTOADT_TARGETS</filename>: The machine - target architectures for which you want to set up cross-development - environments.</para></listitem> - <listitem><para><filename>YOCTOADT_QEMU</filename>: Indicates whether - or not to install the emulator QEMU.</para></listitem> - <listitem><para><filename>YOCTOADT_NFS_UTIL</filename>: Indicates whether - or not to install user-mode NFS. - If you plan to use the Eclipse IDE Yocto plug-in against QEMU, - you should install NFS. - <note>To boot QEMU images using our userspace NFS server, you need - to be running <filename>portmap</filename> or <filename>rpcbind</filename>. - If you are running <filename>rpcbind</filename>, you will also need to add the - <filename>-i</filename> option when <filename>rpcbind</filename> starts up. - Please make sure you understand the security implications of doing this. - You might also have to modify your firewall settings to allow - NFS booting to work.</note></para></listitem> - <listitem><para><filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>: The root - filesystem images you want to download from the - <filename>YOCTOADT_IPKG_REPO</filename> repository.</para></listitem> - <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_</filename><replaceable>arch</replaceable>: The - particular root filesystem used to extract and create the target sysroot. - The value of this variable must have been specified with - <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>. - For example, if you downloaded both <filename>minimal</filename> and - <filename>sato-sdk</filename> images by setting - <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable> - to "minimal sato-sdk", then <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable> - must be set to either "minimal" or "sato-sdk". - </para></listitem> - <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_</filename><replaceable>arch</replaceable>: The - location on the development host where the target sysroot is created. - </para></listitem> - </itemizedlist> - </para> - - <para> - After you have configured the <filename>adt_installer.conf</filename> file, - run the installer using the following command: - <literallayout class='monospaced'> - $ cd adt-installer - $ ./adt_installer - </literallayout> - Once the installer begins to run, you are asked to enter the - location for cross-toolchain installation. - The default location is - <filename>/opt/poky/</filename><replaceable>release</replaceable>. - After either accepting the default location or selecting your - own location, you are prompted to run the installation script - interactively or in silent mode. - If you want to closely monitor the installation, - choose "I" for interactive mode rather than "S" for silent mode. - Follow the prompts from the script to complete the installation. - </para> - - <para> - Once the installation completes, the ADT, which includes the - cross-toolchain, is installed in the selected installation - directory. - You will notice environment setup files for the cross-toolchain - in the installation directory, and image tarballs in the - <filename>adt-installer</filename> directory according to your - installer configurations, and the target sysroot located - according to the - <filename>YOCTOADT_TARGET_SYSROOT_LOC_</filename><replaceable>arch</replaceable> - variable also in your configuration file. - </para> - </section> - </section> - - <section id='using-an-existing-toolchain-tarball'> - <title>Using a Cross-Toolchain Tarball</title> - - <para> - If you want to simply install a cross-toolchain by hand, you can - do so by running the toolchain installer. - The installer includes the pre-built cross-toolchain, the - <filename>runqemu</filename> script, and support files. - If you use this method to install the cross-toolchain, you - might still need to install the target sysroot by installing and - extracting it separately. - For information on how to install the sysroot, see the - "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section. - </para> - - <para> - Follow these steps: - <orderedlist> - <listitem><para><emphasis>Get your toolchain installer using one of the following methods:</emphasis> - <itemizedlist> - <listitem><para>Go to - <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink> - and find the folder that matches your host - development system (i.e. <filename>i686</filename> - for 32-bit machines or <filename>x86_64</filename> - for 64-bit machines).</para> - <para>Go into that folder and download the toolchain - installer whose name includes the appropriate target - architecture. - The toolchains provided by the Yocto Project - are based off of the - <filename>core-image-sato</filename> image and - contain libraries appropriate for developing - against that image. - For example, if your host development system is a - 64-bit x86 system and you are going to use - your cross-toolchain for a 32-bit x86 - target, go into the <filename>x86_64</filename> - folder and download the following installer: - <literallayout class='monospaced'> - poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh - </literallayout></para></listitem> - <listitem><para>Build your own toolchain installer. - For cases where you cannot use an installer - from the download area, you can build your own as - described in the - "<link linkend='optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</link>" - section.</para></listitem> - </itemizedlist></para></listitem> - <listitem><para><emphasis>Once you have the installer, run it to install the toolchain:</emphasis> - <note> - You must change the permissions on the toolchain - installer script so that it is executable. - </note></para> - <para>The following command shows how to run the installer - given a toolchain tarball for a 64-bit x86 development host - system and a 32-bit x86 target architecture. - The example assumes the toolchain installer is located - in <filename>~/Downloads/</filename>. - <literallayout class='monospaced'> - $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh - </literallayout> - The first thing the installer prompts you for is the - directory into which you want to install the toolchain. - The default directory used is - <filename>/opt/poky/&DISTRO;</filename>. - If you do not have write permissions for the directory - into which you are installing the toolchain, the - toolchain installer notifies you and exits. - Be sure you have write permissions in the directory and - run the installer again.</para> - <para>When the script finishes, the cross-toolchain is - installed. - You will notice environment setup files for the - cross-toolchain in the installation directory. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='using-the-toolchain-from-within-the-build-tree'> - <title>Using BitBake and the Build Directory</title> - - <para> - A final way of making the cross-toolchain available is to use BitBake - to generate the toolchain within an existing - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. - This method does not install the toolchain into the default - <filename>/opt</filename> directory. - As with the previous method, if you need to install the target sysroot, you must - do that separately as well. - </para> - - <para> - Follow these steps to generate the toolchain into the Build Directory: - <orderedlist> - <listitem><para><emphasis>Set up the Build Environment:</emphasis> - Source the OpenEmbedded build environment setup - script (i.e. - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>) - located in the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. - </para></listitem> - <listitem><para><emphasis>Check your Local Configuration File:</emphasis> - At this point, you should be sure that the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable - in the <filename>local.conf</filename> file found in the - <filename>conf</filename> directory of the Build Directory - is set for the target architecture. - Comments within the <filename>local.conf</filename> file - list the values you can use for the - <filename>MACHINE</filename> variable. - If you do not change the <filename>MACHINE</filename> - variable, the OpenEmbedded build system uses - <filename>qemux86</filename> as the default target - machine when building the cross-toolchain. - <note> - You can populate the Build Directory with the - cross-toolchains for more than a single architecture. - You just need to edit the <filename>MACHINE</filename> - variable in the <filename>local.conf</filename> file and - re-run the <filename>bitbake</filename> command. - </note></para></listitem> - <listitem><para><emphasis>Make Sure Your Layers are Enabled:</emphasis> - Examine the <filename>conf/bblayers.conf</filename> file - and make sure that you have enabled all the compatible - layers for your target machine. - The OpenEmbedded build system needs to be aware of each - layer you want included when building images and - cross-toolchains. - For information on how to enable a layer, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>" - section in the Yocto Project Development Manual. - </para></listitem> - <listitem><para><emphasis>Generate the Cross-Toolchain:</emphasis> - Run <filename>bitbake meta-ide-support</filename> to - complete the cross-toolchain generation. - Once the <filename>bitbake</filename> command finishes, - the cross-toolchain is - generated and populated within the Build Directory. - You will notice environment setup files for the - cross-toolchain that contain the string - "<filename>environment-setup</filename>" in the - Build Directory's <filename>tmp</filename> folder.</para> - <para>Be aware that when you use this method to install the - toolchain, you still need to separately extract and install - the sysroot filesystem. - For information on how to do this, see the - "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section. - </para></listitem> - </orderedlist> - </para> - </section> -</section> - -<section id='setting-up-the-cross-development-environment'> - <title>Setting Up the Cross-Development Environment</title> - - <para> - Before you can develop using the cross-toolchain, you need to set up the - cross-development environment by sourcing the toolchain's environment setup script. - If you used the ADT Installer or hand-installed cross-toolchain, - then you can find this script in the directory you chose for installation. - For this release, the default installation directory is - <filename>&YOCTO_ADTPATH_DIR;</filename>. - If you installed the toolchain in the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, - you can find the environment setup - script for the toolchain in the Build Directory's <filename>tmp</filename> directory. - </para> - - <para> - Be sure to run the environment setup script that matches the - architecture for which you are developing. - Environment setup scripts begin with the string - "<filename>environment-setup</filename>" and include as part of their - name the architecture. - For example, the toolchain environment setup script for a 64-bit - IA-based architecture installed in the default installation directory - would be the following: - <literallayout class='monospaced'> - &YOCTO_ADTPATH_DIR;/environment-setup-x86_64-poky-linux - </literallayout> - When you run the setup script, many environment variables are - defined: - <literallayout class='monospaced'> - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation - <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files - <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target - <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler - <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler - <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor - <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler - <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker - <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger - <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols - <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib' - <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy' - <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump' - <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar' - <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm' - <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools - <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools - <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure - <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags - <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags - <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link - <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags - </literallayout> - </para> -</section> - -<section id='securing-kernel-and-filesystem-images'> - <title>Securing Kernel and Filesystem Images</title> - - <para> - You will need to have a kernel and filesystem image to boot using your - hardware or the QEMU emulator. - Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem - as the target sysroot, you need to extract the root filesystem. - </para> - - <section id='getting-the-images'> - <title>Getting the Images</title> - - <para> - To get the kernel and filesystem images, you either have to build them or download - pre-built versions. - For an example of how to build these images, see the - "<ulink url='&YOCTO_DOCS_QS_URL;#qs-buiding-images'>Buiding Images</ulink>" - section of the Yocto Project Quick Start. - For an example of downloading pre-build versions, see the - "<link linkend='using-pre-built'>Example Using Pre-Built Binaries and QEMU</link>" - section. - </para> - - <para> - The Yocto Project ships basic kernel and filesystem images for several - architectures (<filename>x86</filename>, <filename>x86-64</filename>, - <filename>mips</filename>, <filename>powerpc</filename>, and <filename>arm</filename>) - that you can use unaltered in the QEMU emulator. - These kernel images reside in the release - area - <ulink url='&YOCTO_MACHINES_DL_URL;'></ulink> - and are ideal for experimentation using Yocto Project. - For information on the image types you can build using the OpenEmbedded build system, - see the - "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" - chapter in the Yocto Project Reference Manual. - </para> - - <para> - If you are planning on developing against your image and you are not - building or using one of the Yocto Project development images - (e.g. <filename>core-image-*-dev</filename>), you must be sure to - include the development packages as part of your image recipe. - </para> - - <para> - If you plan on remotely deploying and debugging your - application from within the Eclipse IDE, you must have an image - that contains the Yocto Target Communication Framework (TCF) agent - (<filename>tcf-agent</filename>). - You can do this by including the <filename>eclipse-debug</filename> - image feature. - <note> - See the - "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>" - section in the Yocto Project Reference Manual for information on - image features. - </note> - To include the <filename>eclipse-debug</filename> image feature, - modify your <filename>local.conf</filename> file in the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> - so that the - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink> - variable includes the "eclipse-debug" feature. - After modifying the configuration file, you can rebuild the image. - Once the image is rebuilt, the <filename>tcf-agent</filename> - will be included in the image and is launched automatically after - the boot. - </para> - </section> - - <section id='extracting-the-root-filesystem'> - <title>Extracting the Root Filesystem</title> - - <para> - If you install your toolchain by hand or build it using BitBake and - you need a root filesystem, you need to extract it separately. - If you use the ADT Installer to install the ADT, the root - filesystem is automatically extracted and installed. - </para> - - <para> - Here are some cases where you need to extract the root filesystem: - <itemizedlist> - <listitem><para>You want to boot the image using NFS. - </para></listitem> - <listitem><para>You want to use the root filesystem as the - target sysroot. - For example, the Eclipse IDE environment with the Eclipse - Yocto Plug-in installed allows you to use QEMU to boot - under NFS.</para></listitem> - <listitem><para>You want to develop your target application - using the root filesystem as the target sysroot. - </para></listitem> - </itemizedlist> - </para> - - <para> - To extract the root filesystem, first <filename>source</filename> - the cross-development environment setup script to establish - necessary environment variables. - If you built the toolchain in the Build Directory, you will find - the toolchain environment script in the - <filename>tmp</filename> directory. - If you installed the toolchain by hand, the environment setup - script is located in <filename>/opt/poky/&DISTRO;</filename>. - </para> - - <para> - After sourcing the environment script, use the - <filename>runqemu-extract-sdk</filename> command and provide the - filesystem image. - </para> - - <para> - Following is an example. - The second command sets up the environment. - In this case, the setup script is located in the - <filename>/opt/poky/&DISTRO;</filename> directory. - The third command extracts the root filesystem from a previously - built filesystem that is located in the - <filename>~/Downloads</filename> directory. - Furthermore, this command extracts the root filesystem into the - <filename>qemux86-sato</filename> directory: - <literallayout class='monospaced'> - $ cd ~ - $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux - $ runqemu-extract-sdk \ - ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \ - $HOME/qemux86-sato - </literallayout> - You could now point to the target sysroot at - <filename>qemux86-sato</filename>. - </para> - </section> -</section> - -<section id='optionally-building-a-toolchain-installer'> - <title>Optionally Building a Toolchain Installer</title> - - <para> - As an alternative to locating and downloading a toolchain installer, - you can build the toolchain installer if you have a - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. - <note> - Although not the preferred method, it is also possible to use - <filename>bitbake meta-toolchain</filename> to build the toolchain - installer. - If you do use this method, you must separately install and extract - the target sysroot. - For information on how to install the sysroot, see the - "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" - section. - </note> - </para> - - <para> - To build the toolchain installer and populate the SDK image, use the - following command: - <literallayout class='monospaced'> - $ bitbake <replaceable>image</replaceable> -c populate_sdk - </literallayout> - The command results in a toolchain installer that contains the sysroot - that matches your target root filesystem. - </para> - - <para> - Another powerful feature is that the toolchain is completely - self-contained. - The binaries are linked against their own copy of - <filename>libc</filename>, which results in no dependencies - on the target system. - To achieve this, the pointer to the dynamic loader is - configured at install time since that path cannot be dynamically - altered. - This is the reason for a wrapper around the - <filename>populate_sdk</filename> archive. - </para> - - <para> - Another feature is that only one set of cross-canadian toolchain - binaries are produced per architecture. - This feature takes advantage of the fact that the target hardware can - be passed to <filename>gcc</filename> as a set of compiler options. - Those options are set up by the environment script and contained in - variables such as - <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>. - This reduces the space needed for the tools. - Understand, however, that a sysroot is still needed for every target - since those binaries are target-specific. - </para> - - <para> - Remember, before using any BitBake command, you - must source the build environment setup script - (i.e. - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>) - located in the Source Directory and you must make sure your - <filename>conf/local.conf</filename> variables are correct. - In particular, you need to be sure the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - variable matches the architecture for which you are building and that - the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink> - variable is correctly set if you are building a toolchain designed to - run on an architecture that differs from your current development host - machine (i.e. the build machine). - </para> - - <para> - When the <filename>bitbake</filename> command completes, the toolchain - installer will be in - <filename>tmp/deploy/sdk</filename> in the Build Directory. - <note> - By default, this toolchain does not build static binaries. - If you want to use the toolchain to build these types of libraries, - you need to be sure your image has the appropriate static - development libraries. - Use the - <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink> - variable inside your <filename>local.conf</filename> file to - install the appropriate library packages. - Following is an example using <filename>glibc</filename> static - development libraries: - <literallayout class='monospaced'> - IMAGE_INSTALL_append = " glibc-staticdev" - </literallayout> - </note> - </para> -</section> - -<section id='optionally-using-an-external-toolchain'> - <title>Optionally Using an External Toolchain</title> - - <para> - You might want to use an external toolchain as part of your - development. - If this is the case, the fundamental steps you need to accomplish - are as follows: - <itemizedlist> - <listitem><para> - Understand where the installed toolchain resides. - For cases where you need to build the external toolchain, you - would need to take separate steps to build and install the - toolchain. - </para></listitem> - <listitem><para> - Make sure you add the layer that contains the toolchain to - your <filename>bblayers.conf</filename> file through the - <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> - variable. - </para></listitem> - <listitem><para> - Set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNAL_TOOLCHAIN'><filename>EXTERNAL_TOOLCHAIN</filename></ulink> - variable in your <filename>local.conf</filename> file - to the location in which you installed the toolchain. - </para></listitem> - </itemizedlist> - A good example of an external toolchain used with the Yocto Project - is <trademark class='registered'>Mentor Graphics</trademark> - Sourcery G++ Toolchain. - You can see information on how to use that particular layer in the - <filename>README</filename> file at - <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>. - You can find further information by reading about the - <ulink url='&YOCTO_DOCS_REF_URL;#var-TCMODE'><filename>TCMODE</filename></ulink> - variable in the Yocto Project Reference Manual's variable glossary. - </para> -</section> - - <section id='using-pre-built'> - <title>Example Using Pre-Built Binaries and QEMU</title> - - <para> - If hardware, libraries and services are stable, you can get started by using a pre-built binary - of the filesystem image, kernel, and toolchain and run it using the QEMU emulator. - This scenario is useful for developing application software. - </para> - - <mediaobject> - <imageobject> - <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/> - </imageobject> - <caption> - <para>Using a Pre-Built Image</para> - </caption> - </mediaobject> - - <para> - For this scenario, you need to do several things: - </para> - - <itemizedlist> - <listitem><para>Install the appropriate stand-alone toolchain tarball.</para></listitem> - <listitem><para>Download the pre-built image that will boot with QEMU. - You need to be sure to get the QEMU image that matches your target machine's - architecture (e.g. x86, ARM, etc.).</para></listitem> - <listitem><para>Download the filesystem image for your target machine's architecture. - </para></listitem> - <listitem><para>Set up the environment to emulate the hardware and then start the QEMU emulator. - </para></listitem> - </itemizedlist> - - <section id='installing-the-toolchain'> - <title>Installing the Toolchain</title> - - <para> - You can download a tarball installer, which includes the - pre-built toolchain, the <filename>runqemu</filename> - script, and support files from the appropriate directory under - <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. - Toolchains are available for 32-bit and 64-bit x86 development - systems from the <filename>i686</filename> and - <filename>x86_64</filename> directories, respectively. - The toolchains the Yocto Project provides are based off the - <filename>core-image-sato</filename> image and contain - libraries appropriate for developing against that image. - Each type of development system supports five or more target - architectures. - </para> - - <para> - The names of the tarball installer scripts are such that a - string representing the host system appears first in the - filename and then is immediately followed by a string - representing the target architecture. - </para> - - <literallayout class='monospaced'> - poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh - - Where: - <replaceable>host_system</replaceable> is a string representing your development system: - - i686 or x86_64. - - <replaceable>image_type</replaceable> is a string representing the image you wish to - develop a Software Development Toolkit (SDK) for use against. - The Yocto Project builds toolchain installers using the - following BitBake command: - - bitbake core-image-sato -c populate_sdk - - <replaceable>arch</replaceable> is a string representing the tuned target architecture: - - i586, x86_64, powerpc, mips, armv7a or armv5te - - <replaceable>release_version</replaceable> is a string representing the release number of the - Yocto Project: - - &DISTRO;, &DISTRO;+snapshot - </literallayout> - - <para> - For example, the following toolchain installer is for a 64-bit - development host system and a i586-tuned target architecture - based off the SDK for <filename>core-image-sato</filename>: - <literallayout class='monospaced'> - poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh - </literallayout> - </para> - - <para> - Toolchains are self-contained and by default are installed into - <filename>/opt/poky</filename>. - However, when you run the toolchain installer, you can choose an - installation directory. - </para> - - <para> - The following command shows how to run the installer given a toolchain tarball - for a 64-bit x86 development host system and a 32-bit x86 target architecture. - You must change the permissions on the toolchain - installer script so that it is executable. - </para> - - <para> - The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>. - <note> - If you do not have write permissions for the directory into which you are installing - the toolchain, the toolchain installer notifies you and exits. - Be sure you have write permissions in the directory and run the installer again. - </note> - </para> - - <para> - <literallayout class='monospaced'> - $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh - </literallayout> - </para> - - <para> - For more information on how to install tarballs, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and - "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" sections in the Yocto Project Application Developer's Guide. - </para> - </section> - - <section id='downloading-the-pre-built-linux-kernel'> - <title>Downloading the Pre-Built Linux Kernel</title> - - <para> - You can download the pre-built Linux kernel suitable for running in the QEMU emulator from - <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>. - Be sure to use the kernel that matches the architecture you want to simulate. - Download areas exist for the five supported machine architectures: - <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>, - <filename>qemux86</filename>, and <filename>qemux86-64</filename>. - </para> - - <para> - Most kernel files have one of the following forms: - <literallayout class='monospaced'> - *zImage-qemu<replaceable>arch</replaceable>.bin - vmlinux-qemu<replaceable>arch</replaceable>.bin - - Where: - <replaceable>arch</replaceable> is a string representing the target architecture: - x86, x86-64, ppc, mips, or arm. - </literallayout> - </para> - - <para> - You can learn more about downloading a Yocto Project kernel in the - "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" - bulleted item in the Yocto Project Development Manual. - </para> - </section> - - <section id='downloading-the-filesystem'> - <title>Downloading the Filesystem</title> - - <para> - You can also download the filesystem image suitable for your target architecture from - <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>. - Again, be sure to use the filesystem that matches the architecture you want - to simulate. - </para> - - <para> - The filesystem image has two tarball forms: <filename>ext3</filename> and - <filename>tar</filename>. - You must use the <filename>ext3</filename> form when booting an image using the - QEMU emulator. - The <filename>tar</filename> form can be flattened out in your host development system - and used for build purposes with the Yocto Project. - <literallayout class='monospaced'> - core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.ext3 - core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.tar.bz2 - - Where: - <replaceable>profile</replaceable> is the filesystem image's profile: - lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato, - sato-dev, or sato-sdk. For information on these types of image - profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" - chapter in the Yocto Project Reference Manual. - - <replaceable>arch</replaceable> is a string representing the target architecture: - x86, x86-64, ppc, mips, or arm. - </literallayout> - </para> - </section> - - <section id='setting-up-the-environment-and-starting-the-qemu-emulator'> - <title>Setting Up the Environment and Starting the QEMU Emulator</title> - - <para> - Before you start the QEMU emulator, you need to set up the emulation environment. - The following command form sets up the emulation environment. - <literallayout class='monospaced'> - $ source &YOCTO_ADTPATH_DIR;/environment-setup-<replaceable>arch</replaceable>-poky-linux-<replaceable>if</replaceable> - - Where: - <replaceable>arch</replaceable> is a string representing the target architecture: - i586, x86_64, ppc603e, mips, or armv5te. - - <replaceable>if</replaceable> is a string representing an embedded application binary interface. - Not all setup scripts include this string. - </literallayout> - </para> - - <para> - Finally, this command form invokes the QEMU emulator - <literallayout class='monospaced'> - $ runqemu <replaceable>qemuarch</replaceable> <replaceable>kernel-image</replaceable> <replaceable>filesystem-image</replaceable> - - Where: - <replaceable>qemuarch</replaceable> is a string representing the target architecture: qemux86, qemux86-64, - qemuppc, qemumips, or qemuarm. - - <replaceable>kernel-image</replaceable> is the architecture-specific kernel image. - - <replaceable>filesystem-image</replaceable> is the .ext3 filesystem image. - - </literallayout> - </para> - - <para> - Continuing with the example, the following two commands setup the emulation - environment and launch QEMU. - This example assumes the root filesystem (<filename>.ext3</filename> file) and - the pre-built kernel image file both reside in your home directory. - The kernel and filesystem are for a 32-bit target architecture. - <literallayout class='monospaced'> - $ cd $HOME - $ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux - $ runqemu qemux86 bzImage-qemux86.bin \ - core-image-sato-qemux86.ext3 - </literallayout> - </para> - - <para> - The environment in which QEMU launches varies depending on the filesystem image and on the - target architecture. - For example, if you source the environment for the ARM target - architecture and then boot the minimal QEMU image, the emulator comes up in a new - shell in command-line mode. - However, if you boot the SDK image, QEMU comes up with a GUI. - <note>Booting the PPC image results in QEMU launching in the same shell in - command-line mode.</note> - </para> - </section> -</section> - -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/adt-manual/adt-style.css b/documentation/adt-manual/adt-style.css deleted file mode 100644 index 9d6221ae51..0000000000 --- a/documentation/adt-manual/adt-style.css +++ /dev/null @@ -1,986 +0,0 @@ -/* - SPDX-License-Identifier: CC-BY-2.0-UK - - 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/documentation/adt-manual/figures/adt-title.png b/documentation/adt-manual/figures/adt-title.png Binary files differdeleted file mode 100644 index 6e71e41f1a..0000000000 --- a/documentation/adt-manual/figures/adt-title.png +++ /dev/null diff --git a/documentation/adt-manual/figures/using-a-pre-built-image.png b/documentation/adt-manual/figures/using-a-pre-built-image.png Binary files differdeleted file mode 100644 index b03130d123..0000000000 --- a/documentation/adt-manual/figures/using-a-pre-built-image.png +++ /dev/null |
