diff --git a/documentation/poky-ref-manual/development.xml b/documentation/poky-ref-manual/development.xml
index e9e00fa3cc..83531bc1dc 100644
--- a/documentation/poky-ref-manual/development.xml
+++ b/documentation/poky-ref-manual/development.xml
@@ -15,40 +15,56 @@
- External Development Using the Application Development Toolkit (ADT)
+ External Development Using the Meta-Toolchain
- The meta-toolchain and meta-toolchain-sdk targets build tarballs that contain toolchains and
- libraries suitable for application development outside of Poky.
- For information on these targets see the Reference: Images
- appendix.
+ The Yocto Project provides toolchains that allow you to develop your application
+ outside of the Yocto Project build system for specific hardware.
+ These toolchains (called meta-toolchains) contain cross-development tools like compilers,
+ linkers, and debuggers that build your application for your target.
+ The Yocto Project also provides images that have toolchains set up for supported
+ architectures.
+ See
+ Reference: Images for a listing of the image
+ types that Yocto Project supports.
+
+
+ Using the BitBake tool you can build a meta-toolchain or meta-toolchain-sdk target,
+ which is in the form of a tarball.
+ Unpacking this tarball into the /opt/poky directory
+ on your host produces a setup script
+ (e.g. /opt/poky/environment-setup-i586-poky-linux) that
+ you can source to initialize your build environment.
+ Sourcing this script adds the compiler, QEMU scripts, QEMU binary, a special version of
+ pkgconfig and other
+ useful utilities to the PATH variable used by the Yocto Project
+ build environment.
+ Variables to assist pkgconfig and
+ Autotools are also defined so that, for example, configure
+ can find pre-generated test results for tests that need target hardware on which to run.
- These tarballs unpack into the
- /opt/poky directory and contain
- a setup script (e.g.
- /opt/poky/environment-setup-i586-poky-linux), from which
- you can source to initialize a suitable environment. Sourcing these files adds the
- compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other
- useful utilities to the PATH variable. Variables to assist pkgconfig and
- autotools are also defined so that, for example, configure can find pre-generated test
- results for tests that need target hardware on which to run.
-
-
- Using the toolchain with autotool-enabled packages is straightforward - just pass the
- appropriate host option to configure.
+ Using the toolchain with Autotool-enabled packages is straightforward - just pass the
+ appropriate host option to configure.
Following is an example:
$ ./configure --host=arm-poky-linux-gnueabi
- For other projects it is usually a case of ensuring the cross tools are used:
+ For projects that are not Autotool-enabled, it is usually just a case of ensuring
+ you point to and use the cross-toolchain.
+ For example, the following two lines of code in a Makefile
+ that builds your application
+ specify to use the cross-compiler arm-poky-linux-gnueabi-gcc
+ and linker arm-poky-linux-gnueabi-ld, which are part of the
+ meta-toolchain you have previously established:
- CC=arm-poky-linux-gnueabi-gcc and LD=arm-poky-linux-gnueabi-ld
+ CC=arm-poky-linux-gnueabi-gcc;
+ LD=arm-poky-linux-gnueabi-ld;
- Using the Eclipse Plug-in
+ External Development Using the Eclipse Plug-in
The current release of the Yocto Project supports the Eclipse IDE plug-in
to make developing software easier for the application developer.
@@ -79,420 +95,74 @@
"Application Development Toolkit (ADT) User's Guide."
-
-
-
-
-
-
+
- Developing Externally in QEMU
+ External Development Using the QEMU Emulator
Running Poky QEMU images is covered in the
Yocto Project Quick Start in the "A Quick Test Run" section.
- Poky's QEMU images contain a complete native toolchain. This means
- you can develop applications within QEMU similar to the way you would in a normal system.
- Using qemux86 on an x86 machine is fast since the
- guest and host architectures match.
- On the other hand, using qemuarm can be 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. If "runqemu" was used to start
- QEMU, and "distccd" is present on the host system, any Bitbake cross-compiling
- toolchain available from the build system is automatically
- used from within QEMU simply by calling "distcc". You can accomplish this by defining the
- cross-compiler variable (e.g. export CC="distcc").
- Alternatively, if a suitable SDK/toolchain is present in
- /opt/poky it is also
- automatically be used.
+ The QEMU images shipped with the Yocto Project contain complete toolchains
+ native to specific target architectures.
+ This support allows you to develop applications within QEMU similar to the way
+ you would using a normal host development system.
+
+
+
+ Speed can be an issue depending on the target and host architecture mix.
+ For example, using the qemux86 image in the emulator
+ on an Intel-based 32-bit (x86) host machine is fast because the target and
+ host architectures match.
+ On the other hand, using the qemuarm image on the same Intel-based
+ host can be slower.
+ But, you still achieve faithful emulation of ARM-specific issues.
- There are several options for connecting into the emulated system.
- QEMU provides a framebuffer interface that has standard consoles
- available. There is also a serial connection available that has a
- console to the system running on it and uses standard IP networking.
- The images have a dropbear ssh server running with the root password
- disabled to allow standard ssh and scp commands to work. The images
- also contain an NFS server that exports the guest's root filesystem, which
- allows it to be made available to the host.
+ To speed things up, the QEMU images support using distcc
+ to call a cross-compiler outside the emulated system.
+ If you used runqemu to start QEMU, and
+ distccd is present on the host system, any BitBake cross-compiling
+ toolchain available from the build system is automatically
+ used from within QEMU simply by calling distcc.
+ You can accomplish this by defining the cross-compiler variable
+ (e.g. export CC="distcc").
+ Alternatively, if a suitable SDK/toolchain is present in
+ /opt/poky the toolchain is also automatically used.
+
+
+
+ Several mechanisms exist that let you connect into the system running on the
+ QEMU emulator:
+
+ QEMU provides a framebuffer interface that makes standard
+ consoles available.
+ Generally, headless embedded devices have a serial port.
+ If so, you can configure the operating system of the running image
+ to use that port to run a console.
+ The connection uses standard IP networking.
+ The QEMU images have a Dropbear secure shell (ssh) server
+ that runs with the root password disabled.
+ This allows you to use standard ssh and
+ scp commands.
+ The QEMU images also contain an embedded Network Files
+ System (NFS) server that exports the image's root filesystem.
+ This allows you to make the filesystem available to the
+ host.
+
- Developing in Poky Directly
+ Development Using Yocto Project Directly
- Working directly in Poky is a fast and effective development technique.
- The idea is that you can directly edit files in
- WORKDIR
- or the source directory S
+ Working directly with the Yocto Project is a fast and effective development technique.
+ The idea is that you can directly edit files in a working directory
+ (WORKDIR)
+ or the source directory (S)
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:
@@ -505,6 +175,11 @@
$ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/
$ cd matchbox-desktop-2
$ vi src/main.c
+ .
+ .
+ [Make your changes]
+ .
+ .
$ exit
$ bitbake matchbox-desktop -c compile -f
$ bitbake matchbox-desktop
@@ -512,34 +187,56 @@
- This example builds the package, changes into the work directory for the package,
- changes a file, then recompiles the package. Instead of using "sh" as it is in the example,
- you can also use two different terminals. However, the risk of using two terminals
- is that a command like "unpack" could destroy the changes you've made to the
- work directory. Consequently, you need to work carefully.
+ This example builds the matchbox-desktop package,
+ creates a new terminal, changes into the work directory for the package,
+ changes a file, exits out of the terminal, and then recompiles the
+ package.
+ Instead of using sh,
+ you can also use two different terminals.
+ However, the risk of using two terminals is that a command like
+ unpack could destroy your changes in the
+ work directory.
+ Consequently, you need to work carefully.
It is useful when making changes directly to the work directory files to do
- so using "quilt" as detailed in the
- modifying packages with quilt section. You can copy the resulting patches
- into the recipe directory and use them directly in the SRC_URI.
+ so using the Quilt tool as detailed in the
+
+ Modifying Package Source Code with Quilt section.
+ Using Quilt, you can copy patches into the recipe directory and use the patches directly
+ through use of the SRC_URI variable.
+
- For a review of the skills used in this section see the Bitbake and Running Specific Tasks Sections.
+ For a review of the skills used in this section, see the
+ BitBake and
+ Running Specific Tasks sections
+ in this manual.
- Developing with 'devshell'
+ Development Within a Development Shell
- When debugging certain commands or even when just editing packages, the
- 'devshell' can be a useful tool.
- Use a command like the following to start this tool.
+ When debugging certain commands or even when just editing packages,
+ devshell can be a useful tool.
+ Using devshell differs from the example shown in the previous
+ section in that when you invoke devshell source files are
+ extracted into your working directory and patches are applied.
+ Then, a new terminal is opened and you are placed in the working directory.
+ In the new terminal all the Yocto Project build-related environment variables are
+ still defined so you can use commands such as configure and
+ make.
+ The commands execute just as if the Yocto Project build system were executing them.
+ Consequently, workng this way can be helpful when debugging a build or preparing
+ software to be used with the Yocto Project build system.
+
+
+
+ Following is an example that uses devshell on a target named
+ matchbox-desktop:
@@ -550,62 +247,77 @@
This command opens a terminal with a shell prompt within the Poky
- environment. Consequently, the following occurs:
+ environment.
+ The following occurs:
- The PATH variable includes the cross toolchain.
- The pkgconfig variables find the correct .pc files.
- "configure" finds the Poky site files as well as any other necessary files.
+ The PATH variable includes the
+ cross-toolchain.
+ The pkgconfig variables find the correct
+ .pc files.
+ The configure command finds the
+ Yocto Project site files as well as any other necessary files.
- Within this environment, you can run "configure" or "compile" commands as if they
- were being run by Poky itself.
- The working directory also automatically changes to the (S)
- directory.
+ Within this environment, you can run configure
+ or compile commands as if they were being run by
+ the Yocto Project build system itself.
+ As noted earlier, the working directory also automatically changes to the
+ source directory (S).
+
+
+
When you are finished, you just exit the shell or close the terminal window.
- The default shell used by "devshell" is the gnome-terminal.
- You can use other forms of terminal can by setting the
- TERMCMD and
- TERMCMDRUN variables
- in local.conf.
- For examples of the other options available, see
- meta/conf/bitbake.conf.
-
-
- An external shell is launched rather than opening directly into the original terminal
- window.
- This allows easier interaction with Bitbake's multiple threads as well as
- for a future client/server split.
- Note that "devshell" will still work over X11 forwarding or similar situations.
+ The default shell used by devshell is the GNOME Terminal.
+ You can use other terminal forms by setting the
+ TERMCMD and
+ TERMCMDRUN variables
+ in the Yocto Project's local.conf file found in the build
+ directory.
+ For examples of the other options available, see the "UI/Interaction Configuration"
+ section of the
+ meta/conf/bitbake.conf configuration file in the Yocto Project
+ files.
- It is worth remembering that inside "devshell" you need to use the full
- compiler name such as arm-poky-linux-gnueabi-gcc
- instead of just gcc.
- The same applies to other applications such as gcc, bintuils, libtool and so forth.
- Poky will have setup environmental variables such as CC to assist applications, such as make,
- find the correct tools.
+ Because an external shell is launched rather than opening directly into the
+ original terminal window, it allows easier interaction with Bitbake's multiple
+ threads as well as accomodates a future client/server split.
+
+
+ It is worth remembering that when using devshell
+ you need to use the full compiler name such as arm-poky-linux-gnueabi-gcc
+ instead of just using gcc.
+ The same applies to other applications such as bintuils,
+ libtool and so forth.
+ The Yocto Project has setup environment variables such as CC
+ to assist applications, such as make to find the correct tools.
+ It is also worth noting that devshell still works over
+ X11 forwarding and similar situations
+
- Developing within Poky with an External SCM-based Package
+ Development Within Yocto Project for a Package that Uses an External SCM
- If you're working on a recipe that pulls from an external SCM it
- is possible to have Poky notice new changes added to the
- SCM and then build the latest version using them.
+ If you're working on a recipe that pulls from an external Source Code Manager (SCM), it
+ is possible to have the Yocto Project build system notice new changes added to the
+ SCM and then build the package that depends on them using the latest version.
This only works for SCMs from which it is possible to get a sensible revision number for changes.
- Currently it works for svn, git and bzr repositories.
+ Currently, you can do this with Apache Subversion (SVN), Git, and Bazaar (BZR) repositories.
- To enable this behavior simply add
- SRCREV_pn-
- PN = "${AUTOREV}" to
- local.conf, where PN
+ To enable this behavior, simply add the following to the local.conf
+ configuration file in the build directory of the Yocto Project files:
+
+ SRCREV_pn-<PN> = "${AUTOREV}"
+
+ where PN
is the name of the package for which you want to enable automatic source
revision updating.