diff options
Diffstat (limited to 'handbook')
54 files changed, 0 insertions, 8741 deletions
diff --git a/handbook/ChangeLog b/handbook/ChangeLog deleted file mode 100644 index e0b51d4a12..0000000000 --- a/handbook/ChangeLog +++ /dev/null @@ -1,38 +0,0 @@ -2008-02-29 Matthew Allum <mallum@openedhand.com> - - * development.xml: - Disable images too big / lack context for now. - * introduction.xml: - Remove some OH specific stuff. - * style.css: - Remove limit on image size - -2008-02-15 Matthew Allum <mallum@openedhand.com> - - * introduction.xml: - Minor tweaks to 'What is Poky' - -2008-02-15 Matthew Allum <mallum@openedhand.com> - - * poky-handbook.xml: - * poky-handbook.png - * poky-beaver.png - * poky-logo.svg: - * style.css: - Add some title images. - -2008-02-14 Matthew Allum <mallum@openedhand.com> - - * development.xml: - remove uri's - * style.css: - Fix glossary - -2008-02-06 Matthew Allum <mallum@openedhand.com> - - * Makefile: - Add various xslto options for html. - * introduction.xml: - Remove link in title. - * style.css: - Add initial version diff --git a/handbook/Makefile b/handbook/Makefile deleted file mode 100644 index 4a4dd7e83f..0000000000 --- a/handbook/Makefile +++ /dev/null @@ -1,31 +0,0 @@ -all: html pdf tarball - -pdf: - - ./poky-doc-tools/poky-docbook-to-pdf poky-handbook.xml -# -- old way -- -# dblatex poky-handbook.xml - -html: -# See http://www.sagehill.net/docbookxsl/HtmlOutput.html - xsltproc --stringparam html.stylesheet style.css \ - --stringparam chapter.autolabel 1 \ - --stringparam appendix.autolabel 1 \ - --stringparam section.autolabel 1 \ - -o poky-handbook.html \ - --xinclude /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl \ - poky-handbook.xml -# -- old way -- -# xmlto xhtml-nochunks poky-handbook.xml - -tarball: html - tar -cvzf poky-handbook.tgz poky-handbook.html style.css screenshots/ss-sato.png poky-beaver.png poky-handbook.png - -validate: - xmllint --postvalid --xinclude --noout poky-handbook.xml - -OUTPUTS = poky-handbook.tgz poky-handbook.html poky-handbook.pdf -SOURCES = *.png *.xml *.css *.svg - -publish: - scp -r $(OUTPUTS) $(SOURCES) o-hand.com:/srv/www/pokylinux.org/doc/ diff --git a/handbook/TODO b/handbook/TODO deleted file mode 100644 index ee0db977cc..0000000000 --- a/handbook/TODO +++ /dev/null @@ -1,11 +0,0 @@ -Handbook Todo List: - - * Document adding a new IMAGE_FEATURE to the customising images section - * Add instructions about using zaurus/openmoko emulation - * Add component overview/block diagrams - * Software Deevelopment intro should mention its software development for - intended target and could be a different arch etc and thus special case. - * Expand insane.bbclass documentation to cover tests - * Document remaining classes (see list in ref-classes) - * Document formfactor - diff --git a/handbook/development.xml b/handbook/development.xml deleted file mode 100644 index 346bb85bf5..0000000000 --- a/handbook/development.xml +++ /dev/null @@ -1,856 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<chapter id="platdev"> -<title>Platform Development with Poky</title> - -<section id="platdev-appdev"> - <title>Software development</title> - <para> - Poky supports several methods of software development. These different - forms of development are explained below and can be switched - between as needed. - </para> - - <section id="platdev-appdev-external-sdk"> - <title>Developing externally using the Poky SDK</title> - - <para> - The meta-toolchain and meta-toolchain-sdk targets (<link linkend='ref-images'>see - the images section</link>) build tarballs which contain toolchains and - libraries suitable for application development outside Poky. These unpack into the - <filename class="directory">/usr/local/poky</filename> directory and contain - a setup script, e.g. - <filename>/usr/local/poky/eabi-glibc/arm/environment-setup</filename> which - can be sourced to initialise a suitable environment. After sourcing this, the - compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other - useful utilities are added to the PATH. Variables to assist pkgconfig and - autotools are also set so that, for example, configure can find pre-generated test - results for tests which need target hardware to run. - </para> - - <para> - Using the toolchain with autotool enabled packages is straightforward, just pass the - appropriate host option to configure e.g. "./configure --host=arm-poky-linux-gnueabi". - For other projects it is usually a case of ensuring the cross tools are used e.g. - CC=arm-poky-linux-gnueabi-gcc and LD=arm-poky-linux-gnueabi-ld. - </para> - </section> - - <section id="platdev-appdev-external-anjuta"> - <title>Developing externally using the Anjuta plugin</title> - - <para> - An Anjuta IDE plugin exists to make developing software within the Poky framework - easier for the application developer. It presents a graphical IDE from which the - developer can cross compile an application then deploy and execute the output in a QEMU - emulation session. It also supports cross debugging and profiling. - </para> -<!-- DISBALED, TOO BIG! - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="screenshots/ss-anjuta-poky-1.png" format="PNG"/> - </imageobject> - <caption> - <para>The Anjuta Poky SDK plugin showing an active QEMU session running Sato</para> - </caption> - </mediaobject> - </screenshot> ---> - <para> - To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta it's development - headers and the Anjuta plugin. The Poky Anjuta plugin is available to download as a tarball at the - <ulink url='http://labs.o-hand.com/sources/anjuta-plugin-sdk/'>OpenedHand labs</ulink> page or - directly from the Poky Git repository located at git://git.pokylinux.org/anjuta-poky; a web interface - to the repository can be accessed at <ulink url='http://git.pokylinux.org/cgit.cgi/anjuta-poky/'/>. - </para> - <para> - See the README file contained in the project for more information on dependencies and building - the plugin. It's recommended you enable the experimental gdb integration by passing configure the - --enable-gdb-integration switch. - </para> - - <section id="platdev-appdev-external-anjuta-setup"> - <title>Setting up the Anjuta plugin</title> - - <para>Extract the tarball for the toolchain into / as root. The - toolchain will be installed into - <filename class="directory">/usr/local/poky</filename>.</para> - - <para>To use the plugin, first open or create an existing - project. If creating a new project the "C GTK+" project type - will allow itself to be cross-compiled. However you should be - aware that this uses glade for the UI.</para> - - <para>To activate the plugin go to - <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>, - then choose <guilabel>General</guilabel> from the left hand side. Choose the - Installed plugins tab, scroll down to <guilabel>Poky - SDK</guilabel> and check the - box. The plugin is now activated but first it must be - configured.</para> - </section> - - <section id="platdev-appdev-external-anjuta-configuration"> - <title>Configuring the Anjuta plugin</title> - - <para>The configuration options for the SDK can be found by choosing - the <guilabel>Poky SDK</guilabel> icon from the left hand side. The following options - need to be set:</para> - - <itemizedlist> - - <listitem><para><guilabel>SDK root</guilabel>: this is the root directory of the SDK - for an ARM EABI SDK this will be <filename - class="directory">/usr/local/poky/eabi-glibc/arm</filename>. - This directory will contain directories named like "bin", - "include", "var", etc. With the file chooser it is important - to enter into the "arm" subdirectory for this - example.</para></listitem> - - <listitem><para><guilabel>Toolchain triplet</guilabel>: this is the cross compile - triplet, e.g. "arm-poky-linux-gnueabi".</para></listitem> - - <listitem><para><guilabel>Kernel</guilabel>: use the file chooser to select the kernel - to use with QEMU</para></listitem> - - <listitem><para><guilabel>Root filesystem</guilabel>: use the file chooser to select - the root filesystem image, this should be an image (not a - tarball)</para></listitem> - </itemizedlist> -<!-- DISBALED, TOO BIG! - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="screenshots/ss-anjuta-poky-2.png" format="PNG"/> - </imageobject> - <caption> - <para>Anjuta Preferences Dialog</para> - </caption> - </mediaobject> - </screenshot> ---> - - </section> - - <section id="platdev-appdev-external-anjuta-usage"> - <title>Using the Anjuta plugin</title> - - <para>As an example, cross-compiling a project, deploying it into - QEMU and running a debugger against it and then doing a system - wide profile.</para> - - <para>Choose <menuchoice><guimenu>Build</guimenu><guimenuitem>Run - Configure</guimenuitem></menuchoice> or - <menuchoice><guimenu>Build</guimenu><guimenuitem>Run - Autogenerate</guimenuitem></menuchoice> to run "configure" - (or to run "autogen") for the project. This passes command line - arguments to instruct it to cross-compile.</para> - - <para>Next do - <menuchoice><guimenu>Build</guimenu><guimenuitem>Build - Project</guimenuitem></menuchoice> to build and compile the - project. If you have previously built the project in the same - tree without using the cross-compiler you may find that your - project fails to link. Simply do - <menuchoice><guimenu>Build</guimenu><guimenuitem>Clean - Project</guimenuitem></menuchoice> to remove the old - binaries. You may then try building again.</para> - - <para>Next start QEMU by using - <menuchoice><guimenu>Tools</guimenu><guimenuitem>Start - QEMU</guimenuitem></menuchoice>, this will start QEMU and - will show any error messages in the message view. Once Poky has - fully booted within QEMU you may now deploy into it.</para> - - <para>Once built and QEMU is running, choose - <menuchoice><guimenu>Tools</guimenu><guimenuitem>Deploy</guimenuitem></menuchoice>, - this will install the package into a temporary directory and - then copy using rsync over SSH into the target. Progress and - messages will be shown in the message view.</para> - - <para>To debug a program installed into onto the target choose - <menuchoice><guimenu>Tools</guimenu><guimenuitem>Debug - remote</guimenuitem></menuchoice>. This prompts for the - local binary to debug and also the command line to run on the - target. The command line to run should include the full path to - the to binary installed in the target. This will start a - gdbserver over SSH on the target and also an instance of a - cross-gdb in a local terminal. This will be preloaded to connect - to the server and use the <guilabel>SDK root</guilabel> to find - symbols. This gdb will connect to the target and load in - various libraries and the target program. You should setup any - breakpoints or watchpoints now since you might not be able to - interrupt the execution later. You may stop - the debugger on the target using - <menuchoice><guimenu>Tools</guimenu><guimenuitem>Stop - debugger</guimenuitem></menuchoice>.</para> - - <para>It is also possible to execute a command in the target over - SSH, the appropriate environment will be be set for the - execution. Choose - <menuchoice><guimenu>Tools</guimenu><guimenuitem>Run - remote</guimenuitem></menuchoice> to do this. This will open - a terminal with the SSH command inside.</para> - - <para>To do a system wide profile against the system running in - QEMU choose - <menuchoice><guimenu>Tools</guimenu><guimenuitem>Profile - remote</guimenuitem></menuchoice>. This will start up - OProfileUI with the appropriate parameters to connect to the - server running inside QEMU and will also supply the path to the - debug information necessary to get a useful profile.</para> - - </section> - </section> - - - <section id="platdev-appdev-qemu"> - <title>Developing externally in QEMU</title> - <para> - Running Poky QEMU images is covered in the <link - linkend='intro-quickstart-qemu'>Running an Image</link> section. - </para> - <para> - Poky's QEMU images contain a complete native toolchain. This means - that applications can be developed within QEMU in the same was as a - normal system. Using qemux86 on an x86 machine is fast since the - guest and host architectures match, qemuarm is slower but gives - faithful emulation of ARM specific issues. To speed things up these - images support using distcc to call a cross-compiler outside the - emulated system too. If <command>runqemu</command> was used to start - QEMU, and distccd is present on the host system, any bitbake cross - compiling toolchain available from the build system will automatically - be used from within qemu simply by calling distcc - (<command>export CC="distcc"</command> can be set in the enviroment). - Alterntatively, if a suitable SDK/toolchain is present in - <filename class="directory">/usr/local/poky</filename> it will also - automatically be used. - </para> - - <para> - There are several options for connecting into the emulated system. - QEMU provides a framebuffer interface which has standard consoles - available. There is also a serial connection available which has a - console to the system running on it and IP networking as standard. - The images have a dropbear ssh server running with the root password - disabled allowing standard ssh and scp commands to work. The images - also contain an NFS server exporting the guest's root filesystem - allowing that to be made available to the host. - </para> - </section> - - <section id="platdev-appdev-chroot"> - <title>Developing externally in a chroot</title> - <para> - If you have a system that matches the architecture of the Poky machine you're using, - such as qemux86, you can run binaries directly from the image on the host system - using a chroot combined with tools like <ulink url='http://projects.o-hand.com/xephyr'>Xephyr</ulink>. - </para> - <para> - Poky has some scripts to make using its qemux86 images within a chroot easier. To use - these you need to install the poky-scripts package or otherwise obtain the - <filename>poky-chroot-setup</filename> and <filename>poky-chroot-run</filename> scripts. - You also need Xephyr and chrootuid binaries available. To initialize a system use the setup script: - </para> - <para> - <literallayout class='monospaced'> -# poky-chroot-setup <qemux86-rootfs.tgz> <target-directory> -</literallayout> - </para> - <para> - which will unpack the specified qemux86 rootfs tarball into the target-directory. - You can then start the system with: - </para> - <para> - <literallayout class='monospaced'> -# poky-chroot-run <target-directory> <command> -</literallayout> - </para> - <para> - where the target-directory is the place the rootfs was unpacked to and command is - an optional command to run. If no command is specified, the system will drop you - within a bash shell. A Xephyr window will be displayed containing the emulated - system and you may be asked for a password since some of the commands used for - bind mounting directories need to be run using sudo. - </para> - <para> - There are limits as to how far the the realism of the chroot environment extends. - It is useful for simple development work or quick tests but full system emulation - with QEMU offers a much more realistic environment for more complex development - tasks. Note that chroot support within Poky is still experimental. - </para> - </section> - - <section id="platdev-appdev-insitu"> - <title>Developing in Poky directly</title> - <para> - Working directly in Poky is a fast and effective development technique. - The idea is that you can directly edit files in - <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> - or the source directory <glossterm><link linkend='var-S'>S</link></glossterm> - and then force specific tasks to rerun in order to test the changes. - An example session working on the matchbox-desktop package might - look like this: - </para> - - <para> - <literallayout class='monospaced'> -$ bitbake matchbox-desktop -$ sh -$ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/ -$ cd matchbox-desktop-2 -$ vi src/main.c -$ exit -$ bitbake matchbox-desktop -c compile -f -$ bitbake matchbox-desktop -</literallayout> - </para> - - <para> - Here, we build the package, change into the work directory for the package, - change a file, then recompile the package. Instead of using sh like this, - you can also use two different terminals. The risk with working like this - is that a command like unpack could wipe out the changes you've made to the - work directory so you need to work carefully. - </para> - - <para> - It is useful when making changes directly to the work directory files to do - so using quilt as detailed in the <link linkend='usingpoky-modifying-packages-quilt'> - modifying packages with quilt</link> section. The resulting patches can be copied - into the recipe directory and used directly in the <glossterm><link - linkend='var-SRC_URI'>SRC_URI</link></glossterm>. - </para> - <para> - For a review of the skills used in this section see Sections <link - linkend="usingpoky-components-bitbake">2.1.1</link> and <link - linkend="usingpoky-debugging-taskrunning">2.4.2</link>. - </para> - - </section> - - <section id="platdev-appdev-devshell"> - <title>Developing with 'devshell'</title> - - <para> - When debugging certain commands or even to just edit packages, the - 'devshell' can be a useful tool. To start it you run a command like: - </para> - - <para> - <literallayout class='monospaced'> -$ bitbake matchbox-desktop -c devshell -</literallayout> - </para> - - <para> - which will open a terminal with a shell prompt within the Poky - environment. This means PATH is setup to include the cross toolchain, - the pkgconfig variables are setup to find the right .pc files, - configure will be able to find the Poky site files etc. Within this - environment, you can run configure or compile command as if they - were being run by Poky itself. You are also changed into the - source (<glossterm><link linkend='var-S'>S</link></glossterm>) - directory automatically. When finished with the shell just exit it - or close the terminal window. - </para> - - <para> - The default shell used by devshell is the gnome-terminal. Other - forms of terminal can also be used by setting the <glossterm> - <link linkend='var-TERMCMD'>TERMCMD</link></glossterm> and <glossterm> - <link linkend='var-TERMCMDRUN'>TERMCMDRUN</link></glossterm> variables - in local.conf. For examples of the other options available, see - <filename>meta/conf/bitbake.conf</filename>. An external shell is - launched rather than opening directly into the original terminal - window to make interaction with bitbakes multiple threads easier - and also allow a client/server split of bitbake in the future - (devshell will still work over X11 forwarding or similar). - </para> - - <para> - It is worth remembering that inside devshell you need to use the full - compiler name such as <command>arm-poky-linux-gnueabi-gcc</command> - instead of just <command>gcc</command> and the same applies to other - applications from gcc, bintuils, libtool etc. Poky will have setup - environmental variables such as CC to assist applications, such as make, - find the correct tools. - </para> - - </section> - - <section id="platdev-appdev-srcrev"> - <title>Developing within Poky with an external SCM based package</title> - - <para> - If you're working on a recipe which pulls from an external SCM it - is possible to have Poky notice new changes added to the - SCM and then build the latest version. This only works for SCMs - where its possible to get a sensible revision number for changes. - Currently it works for svn, git and bzr repositories. - </para> - - <para> - To enable this behaviour it is simply a case of adding <glossterm> - <link linkend='var-SRCREV'>SRCREV</link></glossterm>_pn-<glossterm> - <link linkend='var-PN'>PN</link></glossterm> = "${AUTOREV}" to - local.conf where <glossterm><link linkend='var-PN'>PN</link></glossterm> - is the name of the package for which you want to enable automatic source - revision updating. - </para> - </section> - - </section> - -<section id="platdev-gdb-remotedebug"> - <title>Debugging with GDB Remotely</title> - - <para> - <ulink url="http://sourceware.org/gdb/">GDB</ulink> (The GNU Project Debugger) - allows you to examine running programs to understand and fix problems and - also to perform postmortem style analsys of program crashes. It is available - as a package within poky and installed by default in sdk images. It works best - when -dbg packages for the application being debugged are installed as the |