diff --git a/documentation/profile-manual/profile-manual-arch.xml b/documentation/profile-manual/profile-manual-arch.xml
new file mode 100644
index 0000000000..b9401e9017
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-arch.xml
@@ -0,0 +1,391 @@
+ %poky; ] >
+
+
+
+Getting Started with the Yocto Project
+
+
+ This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
+ You can find enough information to set up your development host and build or use images for
+ hardware supported by the Yocto Project by reading the
+ Yocto Project Quick Start.
+
+
+
+ The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
+ some higher-level concepts you might want to consider.
+
+
+
+ Introducing the Yocto Project
+
+
+ The Yocto Project is an open-source collaboration project focused on embedded Linux development.
+ The project currently provides a build system, which is
+ referred to as the OpenEmbedded build system in the Yocto Project documentation.
+ The Yocto Project provides various ancillary tools suitable for the embedded developer
+ and also features the Sato reference User Interface, which is optimized for
+ stylus driven, low-resolution screens.
+
+
+
+ You can use the OpenEmbedded build system, which uses
+ BitBake to develop complete Linux
+ images and associated user-space applications for architectures based on ARM, MIPS, PowerPC,
+ x86 and x86-64.
+ While the Yocto Project does not provide a strict testing framework,
+ it does provide or generate for you artifacts that let you perform target-level and
+ emulated testing and debugging.
+ Additionally, if you are an Eclipse
+ IDE user, you can install an Eclipse Yocto Plug-in to allow you to
+ develop within that familiar environment.
+
+
+
+
+ Getting Set Up
+
+
+ Here is what you need to get set up to use the Yocto Project:
+
+ Host System: You should have a reasonably current
+ Linux-based host system.
+ You will have the best results with a recent release of Fedora,
+ OpenSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
+ and officially supported.
+ For a list of the distributions under validation and their status, see the
+ "Supported Linux Distributions" section
+ in the Yocto Project Reference Manual and the wiki page at
+ Distribution Support.
+
+ You should also have about 100 gigabytes of free disk space for building images.
+
+ Packages: The OpenEmbedded build system
+ requires certain packages exist on your development system (e.g. Python 2.6 or 2.7).
+ See "The Packages"
+ section in the Yocto Project Quick Start for the exact package
+ requirements and the installation commands to install them
+ for the supported distributions.
+ Yocto Project Release:
+ You need a release of the Yocto Project.
+ You set that up with a local Source Directory
+ one of two ways depending on whether you
+ are going to contribute back into the Yocto Project or not.
+
+ Regardless of the method you use, this manual refers to the resulting local
+ hierarchical set of files as the "Source Directory."
+
+
+ Tarball Extraction: If you are not going to contribute
+ back into the Yocto Project, you can simply download a Yocto Project release you want
+ from the website’s download page.
+ Once you have the tarball, just extract it into a directory of your choice.
+ For example, the following command extracts the Yocto Project &DISTRO;
+ release tarball
+ into the current working directory and sets up the local Source Directory
+ with a top-level folder named &YOCTO_POKY;:
+
+ $ tar xfj &YOCTO_POKY_TARBALL;
+
+ This method does not produce a local Git repository.
+ Instead, you simply end up with a snapshot of the release.
+ Git Repository Method: If you are going to be contributing
+ back into the Yocto Project or you simply want to keep up
+ with the latest developments, you should use Git commands to set up a local
+ Git repository of the upstream poky source repository.
+ Doing so creates a repository with a complete history of changes and allows
+ you to easily submit your changes upstream to the project.
+ Because you cloned the repository, you have access to all the Yocto Project development
+ branches and tag names used in the upstream repository.
+ The following transcript shows how to clone the poky
+ Git repository into the current working directory.
+ You can view the Yocto Project Source Repositories at
+
+ The command creates the local repository in a directory named poky.
+ For information on Git used within the Yocto Project, see the
+ "Git" section.
+
+ $ git clone git://git.yoctoproject.org/poky
+ Initialized empty Git repository in /home/scottrif/poky/.git/
+ remote: Counting objects: 141863, done.
+ remote: Compressing objects: 100% (38624/38624), done.
+ remote: Total 141863 (delta 99661), reused 141816 (delta 99614)
+ Receiving objects: 100% (141863/141863), 76.64 MiB | 126 KiB/s, done.
+ Resolving deltas: 100% (99661/99661), done.
+
+ For another example of how to set up your own local Git repositories, see this
+
+ wiki page, which describes how to create both poky
+ and meta-intel Git repositories.
+
+ Yocto Project Kernel:
+ If you are going to be making modifications to a supported Yocto Project kernel, you
+ need to establish local copies of the source.
+ You can find Git repositories of supported Yocto Project Kernels organized under
+ "Yocto Linux Kernel" in the Yocto Project Source Repositories at
+ .
+ This setup can involve creating a bare clone of the Yocto Project kernel and then
+ copying that cloned repository.
+ You can create the bare clone and the copy of the bare clone anywhere you like.
+ For simplicity, it is recommended that you create these structures outside of the
+ Source Directory (usually poky).
+ As an example, the following transcript shows how to create the bare clone
+ of the linux-yocto-3.4 kernel and then create a copy of
+ that clone.
+ When you have a local Yocto Project kernel Git repository, you can
+ reference that repository rather than the upstream Git repository as
+ part of the clone command.
+ Doing so can speed up the process.
+ In the following example, the bare clone is named
+ linux-yocto-3.4.git, while the
+ copy is named my-linux-yocto-3.4-work:
+
+ $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.4 linux-yocto-3.4.git
+ Initialized empty Git repository in /home/scottrif/linux-yocto-3.4.git/
+ remote: Counting objects: 2468027, done.
+ remote: Compressing objects: 100% (392255/392255), done.
+ remote: Total 2468027 (delta 2071693), reused 2448773 (delta 2052498)
+ Receiving objects: 100% (2468027/2468027), 530.46 MiB | 129 KiB/s, done.
+ Resolving deltas: 100% (2071693/2071693), done.
+
+ Now create a clone of the bare clone just created:
+
+ $ git clone linux-yocto-3.4.git my-linux-yocto-3.4-work
+ Cloning into 'my-linux-yocto-3.4-work'...
+ done.
+
+
+ The poky-extras Git Repository:
+ The poky-extras Git repository contains metadata needed
+ only if you are modifying and building the kernel image.
+ In particular, it contains the kernel BitBake append (.bbappend)
+ files that you
+ edit to point to your locally modified kernel source files and to build the kernel
+ image.
+ Pointing to these local files is much more efficient than requiring a download of the
+ kernel's source files from upstream each time you make changes to the kernel.
+ You can find the poky-extras Git Repository in the
+ "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
+ .
+ It is good practice to create this Git repository inside the Source Directory.
+ Following is an example that creates the poky-extras Git
+ repository inside the Source Directory, which is named poky
+ in this case:
+
+ $ cd ~/poky
+ $ git clone git://git.yoctoproject.org/poky-extras poky-extras
+ Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
+ remote: Counting objects: 618, done.
+ remote: Compressing objects: 100% (558/558), done.
+ remote: Total 618 (delta 192), reused 307 (delta 39)
+ Receiving objects: 100% (618/618), 526.26 KiB | 111 KiB/s, done.
+ Resolving deltas: 100% (192/192), done.
+
+ Supported Board
+ Support Packages (BSPs):
+ The Yocto Project provides a layer called meta-intel and
+ it is maintained in its own separate Git repository.
+ The meta-intel layer contains many supported
+ BSP Layers.
+ Similar considerations exist for setting up the meta-intel
+ layer.
+ You can get set up for BSP development one of two ways: tarball extraction or
+ with a local Git repository.
+ It is a good idea to use the same method that you used to set up the Source Directory.
+ Regardless of the method you use, the Yocto Project uses the following BSP layer
+ naming scheme:
+
+ meta-<BSP_name>
+
+ where <BSP_name> is the recognized BSP name.
+ Here are some examples:
+
+ meta-crownbay
+ meta-emenlow
+ meta-n450
+
+ See the
+ "BSP Layers"
+ section in the Yocto Project Board Support Package (BSP) Developer's Guide for more
+ information on BSP Layers.
+
+ Tarball Extraction: You can download any released
+ BSP tarball from the same
+ download site used
+ to get the Yocto Project release.
+ Once you have the tarball, just extract it into a directory of your choice.
+ Again, this method just produces a snapshot of the BSP layer in the form
+ of a hierarchical directory structure.
+ Git Repository Method: If you are working
+ with a local Git repository for your Source Directory, you should also use this method
+ to set up the meta-intel Git repository.
+ You can locate the meta-intel Git repository in the
+ "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
+ .
+ Typically, you set up the meta-intel Git repository inside
+ the Source Directory.
+ For example, the following transcript shows the steps to clone the
+ meta-intel
+ Git repository inside the local poky Git repository.
+
+ $ cd ~/poky
+ $ git clone git://git.yoctoproject.org/meta-intel.git
+ Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/
+ remote: Counting objects: 3380, done.
+ remote: Compressing objects: 100% (2750/2750), done.
+ remote: Total 3380 (delta 1689), reused 227 (delta 113)
+ Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done.
+ Resolving deltas: 100% (1689/1689), done.
+
+ The same
+
+ wiki page referenced earlier covers how to
+ set up the meta-intel Git repository.
+
+ Eclipse Yocto Plug-in: If you are developing
+ applications using the Eclipse Integrated Development Environment (IDE),
+ you will need this plug-in.
+ See the
+ "Setting up the Eclipse IDE"
+ section for more information.
+
+
+
+
+
+ Building Images
+
+
+ The build process creates an entire Linux distribution, including the toolchain, from source.
+ For more information on this topic, see the
+ "Building an Image"
+ section in the Yocto Project Quick Start.
+
+
+
+ The build process is as follows:
+
+ Make sure you have set up the Source Directory described in the
+ previous section.
+ Initialize the build environment by sourcing a build environment
+ script.
+ Optionally ensure the conf/local.conf configuration file,
+ which is found in the
+ Build Directory,
+ is set up how you want it.
+ This file defines many aspects of the build environment including
+ the target machine architecture through the
+ MACHINE variable,
+ the development machine's processor use through the
+ BB_NUMBER_THREADS and
+ PARALLEL_MAKE variables, and
+ a centralized tarball download directory through the
+ DL_DIR variable.
+ Build the image using the bitbake command.
+ If you want information on BitBake, see the user manual inculded in the
+ bitbake/doc/manual directory of the
+ Source Directory.
+ Run the image either on the actual hardware or using the QEMU
+ emulator.
+
+
+
+
+
+ Using Pre-Built Binaries and QEMU
+
+
+ Another option you have to get started is to use pre-built binaries.
+ The Yocto Project provides many types of binaries with each release.
+ See the "Images"
+ chapter in the Yocto Project Reference Manual
+ for descriptions of the types of binaries that ship with a Yocto Project
+ release.
+
+
+
+ Using a pre-built binary is ideal for developing software applications to run on your
+ target hardware.
+ To do this, you need to be able to access the appropriate cross-toolchain tarball for
+ the architecture on which you are developing.
+ If you are using an SDK type image, the image ships with the complete toolchain native to
+ the architecture.
+ If you are not using an SDK type image, you need to separately download and
+ install the stand-alone Yocto Project cross-toolchain tarball.
+
+
+
+ Regardless of the type of image you are using, you need to download the pre-built kernel
+ that you will boot in the QEMU emulator and then download and extract the target root
+ filesystem for your target machine’s architecture.
+ You can get architecture-specific binaries and filesystems from
+ machines.
+ You can get installation scripts for stand-alone toolchains from
+ toolchains.
+ Once you have all your files, you set up the environment to emulate the hardware
+ by sourcing an environment setup script.
+ Finally, you start the QEMU emulator.
+ You can find details on all these steps in the
+ "Using Pre-Built Binaries and QEMU"
+ section of the Yocto Project Quick Start.
+
+
+
+ Using QEMU to emulate your hardware can result in speed issues
+ 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.
+
+
+
+ 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 the
+ distccd application 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 you are using a suitable SDK image or the appropriate
+ stand-alone toolchain is present in /opt/poky,
+ the toolchain is also automatically used.
+
+
+
+ Several mechanisms exist that let you connect to 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.
+ SSH servers exist in some QEMU images.
+ The core-image-sato QEMU image has a Dropbear secure
+ shell (ssh) server that runs with the root password disabled.
+ The core-image-basic and core-image-lsb QEMU images
+ have OpenSSH instead of Dropbear.
+ Including these SSH servers allow you to use standard ssh and
+ scp commands.
+ The core-image-minimal QEMU image, however, contains no ssh
+ server.
+ You can use a provided, user-space NFS server to boot the QEMU session
+ using a local copy of the root filesystem on the host.
+ In order to make this connection, you must extract a root filesystem tarball by using the
+ runqemu-extract-sdk command.
+ After running the command, you must then point the runqemu
+ script to the extracted directory instead of a root filesystem image file.
+
+
+
+
+
diff --git a/documentation/profile-manual/profile-manual-customization.xsl b/documentation/profile-manual/profile-manual-customization.xsl
new file mode 100644
index 0000000000..8eb69050ba
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-customization.xsl
@@ -0,0 +1,8 @@
+
+
+
+
+
+
+
+
diff --git a/documentation/profile-manual/profile-manual-examples.xml b/documentation/profile-manual/profile-manual-examples.xml
new file mode 100644
index 0000000000..442cab3036
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-examples.xml
@@ -0,0 +1,1915 @@
+ %poky; ] >
+
+
+
+Common Development Models
+
+
+ Many development models exist for which you can use the Yocto Project.
+ This chapter overviews simple methods that use tools provided by the
+ Yocto Project:
+
+ System Development:
+ System Development covers Board Support Package (BSP) development and kernel
+ modification or configuration.
+ For an example on how to create a BSP, see the
+ "Creating a New BSP Layer Using the yocto-bsp Script"
+ section in the Yocto Project Board Support Package (BSP) Developer's Guide.
+
+ User Application Development:
+ User Application Development covers development of applications that you intend
+ to run on some target hardware.
+ For information on how to set up your host development system for user-space
+ application development, see the
+ Yocto Project Application Developer's Guide.
+ For a simple example of user-space application development using the
+ Eclipse IDE, see the
+ "Application
+ Development Workflow" section.
+
+ Temporary Source Code Modification:
+ Direct modification of temporary source code is a convenient development model
+ to quickly iterate and develop towards a solution.
+ Once the solution has been implemented, you should of course take steps to
+ get the changes upstream and applied in the affected recipes.
+ Image Development using Hob:
+ You can use the Hob to build
+ custom operating system images within the build environment.
+ Hob provides an efficient interface to the OpenEmbedded build system.
+ Using a Development Shell:
+ You can use a devshell to efficiently debug commands or simply
+ edit packages.
+ Working inside a development shell is a quick way to set up the OpenEmbedded build
+ environment to work on parts of a project.
+
+
+
+
+ System Development Workflow
+
+
+ System development involves modification or creation of an image that you want to run on
+ a specific hardware target.
+ Usually, when you want to create an image that runs on embedded hardware, the image does
+ not require the same number of features that a full-fledged Linux distribution provides.
+ Thus, you can create a much smaller image that is designed to use only the
+ features for your particular hardware.
+
+
+
+ To help you understand how system development works in the Yocto Project, this section
+ covers two types of image development: BSP creation and kernel modification or
+ configuration.
+
+
+
+ Developing a Board Support Package (BSP)
+
+
+ A BSP is a package of recipes that, when applied during a build, results in
+ an image that you can run on a particular board.
+ Thus, the package when compiled into the new image, supports the operation of the board.
+
+
+
+ For a brief list of terms used when describing the development process in the Yocto Project,
+ see the "Yocto Project Terms" section.
+
+
+
+ The remainder of this section presents the basic steps used to create a BSP
+ using the Yocto Project's
+ BSP Tools.
+ For an example that shows how to create a new layer using the tools, see the
+ "Creating a New BSP Layer Using the yocto-bsp Script"
+ section in the Yocto Project Board Support Package (BSP) Developer's Guide.
+
+
+
+ The following illustration and list summarize the BSP creation general workflow.
+
+
+
+
+
+
+
+
+ Set up your host development system to support
+ development using the Yocto Project: See the
+ "The Linux Distributions"
+ and the
+ "The Packages" sections both
+ in the Yocto Project Quick Start for requirements.
+ Establish a local copy of the project files on your
+ system: You need this Source
+ Directory available on your host system.
+ Having these files on your system gives you access to the build
+ process and to the tools you need.
+ For information on how to set up the
+ Source Directory, see the
+ "Getting Setup" section.
+ Establish the meta-intel
+ repository on your system: Having local copies of the
+ supported BSP layers on your system gives you access to the build
+ process and to the tools you need for creating a BSP.
+ For information on how to get these files, see the
+ "Getting Setup" section.
+ Create your own BSP layer using the
+ yocto-bsp script:
+ Layers are ideal for
+ isolating and storing work for a given piece of hardware.
+ A layer is really just a location or area in which you place the recipes for your BSP.
+ In fact, a BSP is, in itself, a special type of layer.
+ The simplest way to create a new BSP layer that is compliant with the
+ Yocto Project is to use the yocto-bsp script.
+ For information about that script, see the
+ "Creating a New BSP Layer Using the yocto-bsp Script"
+ section in the Yocto Project Board Support (BSP) Developer's Guide.
+
+
+ Another example that illustrates a layer is an application.
+ Suppose you are creating an application that has library or other dependencies in
+ order for it to compile and run.
+ The layer, in this case, would be where all the recipes that define those dependencies
+ are kept.
+ The key point for a layer is that it is an isolated area that contains
+ all the relevant information for the project that the OpenEmbedded build
+ system knows about.
+ For more information on layers, see the
+ "Understanding and Creating Layers"
+ section.
+ For more information on BSP layers, see the
+ "BSP Layers" section in the
+ Yocto Project Board Support Package (BSP) Developer's Guide.
+ Four BSPs exist that are part of the
+ Yocto Project release: atom-pc, beagleboard,
+ mpc8315e, and routerstationpro.
+ The recipes and configurations for these four BSPs are located and dispersed
+ within the Source Directory.
+ On the other hand, BSP layers for Cedar Trail, Chief River, Crown Bay,
+ Crystal Forest, Emenlow, Fish River, Fish River 2, Jasper Forest, N450,
+ Romley, sys940x, Sugar Bay, and tlk exist in their own separate layers
+ within the larger meta-intel layer.
+ When you set up a layer for a new BSP, you should follow a standard layout.
+ This layout is described in the section
+ "Example Filesystem Layout"
+ section of the Board Support Package (BSP) Development Guide.
+ In the standard layout, you will notice a suggested structure for recipes and
+ configuration information.
+ You can see the standard layout for a BSP by examining
+ any supported BSP found in the meta-intel layer inside
+ the Source Directory.
+ Make configuration changes to your new BSP
+ layer: The standard BSP layer structure organizes the files you need
+ to edit in conf and several recipes-*
+ directories within the BSP layer.
+ Configuration changes identify where your new layer is on the local system
+ and identify which kernel you are going to use.
+ When you run the yocto-bsp script you are able to interactively
+ configure many things for the BSP (e.g. keyboard, touchscreen, and so forth).
+
+ Make recipe changes to your new BSP layer: Recipe
+ changes include altering recipes (.bb files), removing
+ recipes you don't use, and adding new recipes or append files
+ (.bbappend) that you need to support your hardware.
+
+ Prepare for the build: Once you have made all the
+ changes to your BSP layer, there remains a few things
+ you need to do for the OpenEmbedded build system in order for it to create your image.
+ You need to get the build environment ready by sourcing an environment setup script
+ and you need to be sure two key configuration files are configured appropriately:
+ the conf/local.conf and the
+ conf/bblayers.conf file.
+ You must make the OpenEmbedded build system aware of your new layer.
+ See the
+ "Enabling Your Layer" section
+ for information on how to let the build system know about your new layer.
+ The entire process for building an image is overviewed in the section
+ "Building an Image" section
+ of the Yocto Project Quick Start.
+ You might want to reference this information.
+ Build the image: The OpenEmbedded build system
+ uses the BitBake tool to build images based on the type of image you want to create.
+ You can find more information about BitBake in the user manual, which is found in the
+ bitbake/doc/manual directory of the
+ Source Directory.
+ The build process supports several types of images to satisfy different needs.
+ See the
+ "Images" chapter
+ in the Yocto Project Reference Manual for information on
+ supported images.
+
+
+
+
+ You can view a video presentation on "Building Custom Embedded Images with Yocto"
+ at Free Electrons.
+ You can also find supplemental information in
+
+ The Board Support Package (BSP) Development Guide.
+ Finally, there is wiki page write up of the example also located
+
+ here that you might find helpful.
+
+
+
+
+ Modifying the Kernel
+
+
+ Kernel modification involves changing the Yocto Project kernel, which could involve changing
+ configuration options as well as adding new kernel recipes.
+ Configuration changes can be added in the form of configuration fragments, while recipe
+ modification comes through the kernel's recipes-kernel area
+ in a kernel layer you create.
+
+
+
+ The remainder of this section presents a high-level overview of the Yocto Project
+ kernel architecture and the steps to modify the kernel.
+ For a complete discussion of the kernel, see the
+ Yocto Project Kernel Architecture and Use Manual.
+ You can reference the
+ "Patching the Kernel" section
+ for an example that changes the source code of the kernel.
+ For information on how to configure the kernel, see the
+ "Configuring the Kernel" section.
+
+
+
+ Kernel Overview
+
+
+ Traditionally, when one thinks of a patched kernel, they think of a base kernel
+ source tree and a fixed structure that contains kernel patches.
+ The Yocto Project, however, employs mechanisms, that in a sense, result in a kernel source
+ generator.
+ By the end of this section, this analogy will become clearer.
+
+
+
+ You can find a web interface to the Yocto Project kernel source repositories at
+ .
+ If you look at the interface, you will see to the left a grouping of
+ Git repositories titled "Yocto Linux Kernel."
+ Within this group, you will find several kernels supported by
+ the Yocto Project:
+
+ linux-yocto-2.6.34 - The
+ stable Yocto Project kernel that is based on the Linux 2.6.34 released kernel.
+ linux-yocto-2.6.37 - The
+ stable Yocto Project kernel that is based on the Linux 2.6.37 released kernel.
+ linux-yocto-3.0 - The stable
+ Yocto Project kernel that is based on the Linux 3.0 released kernel.
+ linux-yocto-3.0-1.1.x - The
+ stable Yocto Project kernel to use with the Yocto Project Release 1.1.x. This kernel
+ is based on the Linux 3.0 released kernel.
+ linux-yocto-3.2 - The
+ stable Yocto Project kernel to use with the Yocto Project Release 1.2. This kernel
+ is based on the Linux 3.2 released kernel.
+ linux-yocto-3.4 - The
+ stable Yocto Project kernel to use with the Yocto Project Release 1.3. This kernel
+ is based on the Linux 3.4 released kernel.
+ linux-yocto-dev - A development
+ kernel based on the latest upstream release candidate available.
+
+
+
+
+ The kernels are maintained using the Git revision control system
+ that structures them using the familiar "tree", "branch", and "leaf" scheme.
+ Branches represent diversions from general code to more specific code, while leaves
+ represent the end-points for a complete and unique kernel whose source files
+ when gathered from the root of the tree to the leaf accumulate to create the files
+ necessary for a specific piece of hardware and its features.
+ The following figure displays this concept:
+
+
+
+
+
+ Within the figure, the "Kernel.org Branch Point" represents the point in the tree
+ where a supported base kernel is modified from the Linux kernel.
+ For example, this could be the branch point for the linux-yocto-3.0
+ kernel.
+ Thus, everything further to the right in the structure is based on the
+ linux-yocto-3.0 kernel.
+ Branch points to right in the figure represent where the
+ linux-yocto-3.0 kernel is modified for specific hardware
+ or types of kernels, such as real-time kernels.
+ Each leaf thus represents the end-point for a kernel designed to run on a specific
+ targeted device.
+
+
+
+ The overall result is a Git-maintained repository from which all the supported
+ kernel types can be derived for all the supported devices.
+ A big advantage to this scheme is the sharing of common features by keeping them in
+ "larger" branches within the tree.
+ This practice eliminates redundant storage of similar features shared among kernels.
+
+
+
+ Keep in mind the figure does not take into account all the supported Yocto
+ Project kernel types, but rather shows a single generic kernel just for conceptual purposes.
+ Also keep in mind that this structure represents the Yocto Project source repositories
+ that are either pulled from during the build or established on the host development system
+ prior to the build by either cloning a particular kernel's Git repository or by
+ downloading and unpacking a tarball.
+
+
+
+ Upstream storage of all the available kernel source code is one thing, while
+ representing and using the code on your host development system is another.
+ Conceptually, you can think of the kernel source repositories as all the
+ source files necessary for all the supported kernels.
+ As a developer, you are just interested in the source files for the kernel on
+ on which you are working.
+ And, furthermore, you need them available on your host system.
+
+
+
+ Kernel source code is available on your host system a couple of different
+ ways.
+ If you are working in the kernel all the time, you probably would want
+ to set up your own local Git repository of the kernel tree.
+ If you just need to make some patches to the kernel, you can get at
+ temporary kernel source files extracted and used during the OpenEmbedded
+ build system.
+ We will just talk about working with the temporary source code.
+
+
+
+ What happens during the build?
+ When you build the kernel on your development system, all files needed for the build
+ are taken from the source repositories pointed to by the
+ SRC_URI variable
+ and gathered in a temporary work area
+ where they are subsequently used to create the unique kernel.
+ Thus, in a sense, the process constructs a local source tree specific to your
+ kernel to generate the new kernel image - a source generator if you will.
+
+ The following figure shows the temporary file structure
+ created on your host system when the build occurs.
+ This
+ Build Directory contains all the
+ source files used during the build.
+
+
+
+
+
+
+
+ Again, for a complete discussion of the Yocto Project kernel's architecture and its
+ branching strategy, see the
+ Yocto Project Kernel Architecture and Use Manual.
+ You can also reference the
+ "Patching the Kernel"
+ section for a detailed example that modifies the kernel.
+
+
+
+
+ Kernel Modification Workflow
+
+
+ This illustration and the following list summarizes the kernel modification general workflow.
+
+
+
+
+
+
+
+
+ Set up your host development system to support
+ development using the Yocto Project: See
+ "The Linux Distributions" and
+ "The Packages" sections both
+ in the Yocto Project Quick Start for requirements.
+ Establish a local copy of project files on your
+ system: Having the Source
+ Directory on your system gives you access to the build process and tools
+ you need.
+ For information on how to get these files, see the bulleted item
+ "Yocto Project Release" earlier in this manual.
+
+ Establish the temporary kernel source files:
+ Temporary kernel source files are kept in the Build Directory created by the
+ OpenEmbedded build system when you run BitBake.
+ If you have never built the kernel you are interested in, you need to run
+ an initial build to establish local kernel source files.
+ If you are building an image for the first time, you need to get the build
+ environment ready by sourcing
+ the environment setup script.
+ You also need to be sure two key configuration files
+ (local.conf and bblayers.conf)
+ are configured appropriately.
+ The entire process for building an image is overviewed in the
+ "Building an Image"
+ section of the Yocto Project Quick Start.
+ You might want to reference this information.
+ You can find more information on BitBake in the user manual, which is found in the
+ bitbake/doc/manual directory of the
+ Source Directory.
+ The build process supports several types of images to satisfy different needs.
+ See the "Images" chapter in
+ the Yocto Project Reference Manual for information on supported images.
+
+ Make changes to the kernel source code if
+ applicable: Modifying the kernel does not always mean directly
+ changing source files.
+ However, if you have to do this, you make the changes to the files in the
+ Build directory.
+ Make kernel configuration changes
+ if applicable:
+ If your situation calls for changing the kernel's configuration, you can
+ use the yocto-kernel script or menuconfig
+ to enable and disable kernel configurations.
+ Using the script lets you interactively set up kernel configurations.
+ Using menuconfig allows you to interactively develop and test the
+ configuration changes you are making to the kernel.
+ When saved, changes using menuconfig update the kernel's
+ .config.
+ Try to resist the temptation of directly editing the .config
+ file found in the
+ Build Directory at
+ tmp/sysroots/<machine-name>/kernel.
+ Doing so, can produce unexpected results when the OpenEmbedded build system
+ regenerates the configuration file.
+ Once you are satisfied with the configuration changes made using
+ menuconfig, you can directly examine the
+ .config file against a saved original and gather those
+ changes into a config fragment to be referenced from within the kernel's
+ .bbappend file.
+ Rebuild the kernel image with your changes:
+ Rebuilding the kernel image applies your changes.
+
+
+
+
+
+
+
+ Application Development Workflow
+
+
+ Application development involves creating an application that you want
+ to run on your target hardware, which is running a kernel image created using the
+ OpenEmbedded build system.
+ The Yocto Project provides an Application Development Toolkit (ADT) and
+ stand-alone cross-development toolchains that
+ facilitate quick development and integration of your application into its run-time environment.
+ Using the ADT and toolchains, you can compile and link your application.
+ You can then deploy your application to the actual hardware or to the QEMU emulator for testing.
+ If you are familiar with the popular Eclipse IDE,
+ you can use an Eclipse Yocto Plug-in to
+ allow you to develop, deploy, and test your application all from within Eclipse.
+
+
+
+ While we strongly suggest using the ADT to develop your application, this option might not
+ be best for you.
+ If this is the case, you can still use pieces of the Yocto Project for your development process.
+ However, because the process can vary greatly, this manual does not provide detail on the process.
+
+
+
+ Workflow Using the ADT and Eclipse
+
+
+ To help you understand how application development works using the ADT, this section
+ provides an overview of the general development process and a detailed example of the process
+ as it is used from within the Eclipse IDE.
+
+
+
+ The following illustration and list summarize the application development general workflow.
+
+
+
+
+
+
+
+
+ Prepare the Host System for the Yocto Project:
+ See
+ "The Linux Distributions" and
+ "The Packages" sections both
+ in the Yocto Project Quick Start for requirements.
+ Secure the Yocto Project Kernel Target Image:
+ You must have a target kernel image that has been built using the OpenEmbeded
+ build system.
+ Depending on whether the Yocto Project has a pre-built image that matches your target
+ architecture and where you are going to run the image while you develop your application
+ (QEMU or real hardware), the area from which you get the image differs.
+
+ Download the image from
+ machines
+ if your target architecture is supported and you are going to develop
+ and test your application on actual hardware.
+ Download the image from the
+
+ machines/qemu if your target architecture is supported
+ and you are going to develop and test your application using the QEMU
+ emulator.
+ Build your image if you cannot find a pre-built image that matches
+ your target architecture.
+ If your target architecture is similar to a supported architecture, you can
+ modify the kernel image before you build it.
+ See the
+ "Patching the Kernel"
+ section for an example.
+
+ For information on pre-built kernel image naming schemes for images
+ that can run on the QEMU emulator, see the
+ "Downloading the Pre-Built Linux Kernel"
+ section in the Yocto Project Quick Start.
+ Install the ADT:
+ The ADT provides a target-specific cross-development toolchain, the root filesystem,
+ the QEMU emulator, and other tools that can help you develop your application.
+ While it is possible to get these pieces separately, the ADT Installer provides an
+ easy method.
+ You can get these pieces by running an ADT installer script, which is configurable.
+ For information on how to install the ADT, see the
+ "Using the ADT Installer"
+ section
+ in the Yocto Project Application Developer's Guide.
+ If Applicable, Secure the Target Root Filesystem
+ and the Cross-development Toolchain:
+ If you choose not to install the ADT using the ADT Installer,
+ you need to find and download the appropriate root filesystem and
+ the cross-development toolchain.
+ You can find the tarballs for the root filesystem in the same area used
+ for the kernel image.
+ Depending on the type of image you are running, the root filesystem you need differs.
+ For example, if you are developing an application that runs on an image that
+ supports Sato, you need to get root filesystem that supports Sato.
+ You can find the cross-development toolchains at
+ toolchains.
+ Be sure to get the correct toolchain for your development host and your
+ target architecture.
+ See the "Using a Cross-Toolchain Tarball"
+ section in the Yocto Project Application Developer's Guide for information
+ and the
+ "Installing the Toolchain"
+ in the Yocto Project Quick Start for information on finding and installing
+ the correct toolchain based on your host development system and your target
+ architecture.
+
+ Create and Build your Application:
+ At this point, you need to have source files for your application.
+ Once you have the files, you can use the Eclipse IDE to import them and build the
+ project.
+ If you are not using Eclipse, you need to use the cross-development tools you have
+ installed to create the image.
+ Deploy the Image with the Application:
+ If you are using the Eclipse IDE, you can deploy your image to the hardware or to
+ QEMU through the project's preferences.
+ If you are not using the Eclipse IDE, then you need to deploy the application
+ to the hardware using other methods.
+ Or, if you are using QEMU, you need to use that tool and load your image in for testing.
+
+ Test and Debug the Application:
+ Once your application is deployed, you need to test it.
+ Within the Eclipse IDE, you can use the debugging environment along with the
+ set of user-space tools installed along with the ADT to debug your application.
+ Of course, the same user-space tools are available separately if you choose
+ not to use the Eclipse IDE.
+
+
+
+
+
+ Working Within Eclipse
+
+
+ The Eclipse IDE is a popular development environment and it fully supports
+ development using the Yocto Project.
+ This release of the Yocto Project supports both the Juno and Indigo versions
+ of the Eclipse IDE.
+ Thus, the following information provides setup information for both versions.
+
+
+
+
+ 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.
+
+
+
+ This section describes how to install and configure the Eclipse IDE
+ Yocto Plug-in and how to use it to develop your application.
+
+
+
+ Setting Up the Eclipse IDE
+
+
+ To develop within the Eclipse IDE, you need to do the following:
+
+ Install the optimal version of the Eclipse IDE.
+ Configure the Eclipse IDE.
+ Install the Eclipse Yocto Plug-in.
+ Configure the Eclipse Yocto Plug-in.
+
+
+ Do not install Eclipse from your distribution's package repository.
+ Be sure to install Eclipse from the official Eclipse download site as directed
+ in the next section.
+
+
+
+
+ Installing the Eclipse IDE
+
+
+ It is recommended that you have the Juno 4.2 version of the
+ Eclipse IDE installed on your development system.
+ However, if you currently have the Indigo 3.7.2 version installed and you do
+ not want to upgrade the IDE, you can configure Indigo to work with the
+ Yocto Project.
+ See the
+ "Configuring the Eclipse IDE (Indigo)"
+ section.
+
+
+
+ If you don’t have the Juno 4.2 Eclipse IDE installed, you can find the tarball at
+ .
+ From that site, choose the Eclipse Classic version particular to your development
+ host.
+ This version contains the Eclipse Platform, the Java Development
+ Tools (JDT), and the Plug-in Development Environment.
+
+
+
+ Once you have downloaded the tarball, extract it into a clean
+ directory.
+ For example, the following commands unpack and install the
+ downloaded Eclipse IDE tarball into a clean directory
+ using the default name eclipse:
+
+ $ cd ~
+ $ tar -xzvf ~/Downloads/eclipse-SDK-4.2-linux-gtk-x86_64.tar.gz
+
+
+
+
+ If you have the Indigo 3.7.2 Eclipse IDE already installed and you want to use that
+ version, one issue exists that you need to be aware of regarding the Java
+ Virtual machine’s garbage collection (GC) process.
+ The GC process does not clean up the permanent generation
+ space (PermGen).
+ This space stores metadata descriptions of classes.
+ The default value is set too small and it could trigger an
+ out-of-memory error such as the following:
+
+ Java.lang.OutOfMemoryError: PermGen space
+
+
+
+
+ This error causes the application to hang.
+
+
+
+ To fix this issue, you can use the --vmargs
+ option when you start the Indigo 3.7.2 Eclipse IDE
+ to increase the size of the permanent generation space:
+
+ eclipse --vmargs --XX:PermSize=256M
+
+
+
+
+
+ Configuring the Eclipse IDE (Juno)
+
+
+ This section presents the steps needed to configure the Juno 4.2 Eclipse IDE.
+ If you are using Indigo 3.7.2, see the
+ "Configuring the Eclipse IDE (Indigo)".
+
+
+
+ Before installing and configuring the Eclipse Yocto Plug-in, you need to configure
+ the Juno 4.2 Eclipse IDE.
+ Follow these general steps:
+
+ Start the Eclipse IDE.
+ Make sure you are in your Workbench and select
+ "Install New Software" from the "Help" pull-down menu.
+
+ Select Juno - &ECLIPSE_JUNO_URL;
+ from the "Work with:" pull-down menu.
+ Expand the box next to "Linux Tools" and select the
+ "LTTng - Linux Tracing Toolkit" boxes.
+ Expand the box next to "Mobile and Device Development" and select the
+ following boxes:
+
+ C/C++ Remote Launch
+ Remote System Explorer End-user Runtime
+ Remote System Explorer User Actions
+ Target Management Terminal
+ TCF Remote System Explorer add-in
+ TCF Target Explorer
+
+ Expand the box next to Programming Languages
+ and select the Autotools Support for CDT
+ and C/C++ Development Tools boxes.
+ Complete the installation and restart the Eclipse IDE.
+
+
+
+
+
+ Configuring the Eclipse IDE (Indigo)
+
+
+ This section presents the steps needed to configure the Indigo 3.7.2 Eclipse IDE.
+ If you are using Juno 4.2, see the
+ "Configuring the Eclipse IDE (Juno)".
+
+
+
+ Before installing and configuring the Eclipse Yocto Plug-in, you need to configure
+ the Indigo 3.7.2 Eclipse IDE.
+ Follow these general steps:
+
+ Start the Eclipse IDE.
+ Make sure you are in your Workbench and select
+ "Install New Software" from the "Help" pull-down menu.
+
+ Select indigo - &ECLIPSE_INDIGO_URL;
+ from the "Work with:" pull-down menu.
+ Expand the box next to Programming Languages
+ and select the Autotools Support for CDT (incubation)
+ and C/C++ Development Tools boxes.
+ Expand the box next to "Linux Tools" and select the
+ "LTTng - Linux Tracing Toolkit(incubation)" boxes.
+ Complete the installation and restart the Eclipse IDE.
+ After the Eclipse IDE restarts and from the Workbench, select
+ "Install New Software" from the "Help" pull-down menu.
+ Click the
+ "Available Software Sites" link.
+ Check the box next to
+ &ECLIPSE_UPDATES_URL;
+ and click "OK".
+ Select &ECLIPSE_UPDATES_URL;
+ from the "Work with:" pull-down menu.
+ Check the box next to TM and RSE Main Features.
+
+ Expand the box next to TM and RSE Optional Add-ons
+ and select every item except RSE Unit Tests and
+ RSE WinCE Services (incubation).
+ Complete the installation and restart the Eclipse IDE.
+ If necessary, select
+ "Install New Software" from the "Help" pull-down menu so you can click the
+ "Available Software Sites" link again.
+ After clicking "Available Software Sites", check the box next to
+ http://download.eclipse.org/tools/cdt/releases/indigo
+ and click "OK".
+ Select &ECLIPSE_INDIGO_CDT_URL;
+ from the "Work with:" pull-down menu.
+ Check the box next to CDT Main Features.
+
+ Expand the box next to CDT Optional Features
+ and select C/C++ Remote Launch and
+ Target Communication Framework (incubation).
+ Complete the installation and restart the Eclipse IDE.
+
+
+
+
+
+ Installing or Accessing the Eclipse Yocto Plug-in
+
+
+ You can install the Eclipse Yocto Plug-in into the Eclipse IDE
+ one of two ways: use the Yocto Project's Eclipse Update site to install the pre-built plug-in,
+ or build and install the plug-in from the latest source code.
+ If you don't want to permanently install the plug-in but just want to try it out
+ within the Eclipse environment, you can import the plug-in project from the
+ Yocto Project's Source Repositories.
+
+
+
+ Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site
+
+
+ To install the Eclipse Yocto Plug-in from the update site,
+ follow these steps:
+
+ Start up the Eclipse IDE.
+ In Eclipse, select "Install New Software" from the "Help" menu.
+ Click "Add..." in the "Work with:" area.
+ Enter
+ &ECLIPSE_DL_PLUGIN_URL;
+ in the URL field and provide a meaningful name in the "Name" field.
+ Click "OK" to have the entry added to the "Work with:"
+ drop-down list.
+ Select the entry for the plug-in from the "Work with:" drop-down
+ list.
+ Check the box next to Development tools and SDKs for Yocto Linux.
+
+ Complete the remaining software installation steps and
+ then restart the Eclipse IDE to finish the installation of the plug-in.
+
+
+
+
+
+
+ Installing the Plug-in Using the Latest Source Code
+
+
+ To install the Eclipse Yocto Plug-in from the latest source code, follow these steps:
+
+ Open a shell and create a Git repository with:
+
+ $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse
+
+ For this example, the repository is named
+ ~/yocto-eclipse.
+ Change to the directory where you set up
+ the Git repository:
+
+ $ cd ~/yocto-eclipse
+
+ Be sure you are in the right branch for your Git repository.
+ For this release set the branch to &DISTRO_NAME;:
+
+ $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
+
+ Change to the scripts
+ directory within the Git repository:
+
+ $ cd scripts
+
+ Set up the local build environment by running the
+ setup script:
+
+ $ ./setup.sh
+
+ When the script finishes execution, it prompts
+ you with instructions on how to run the
+ build.sh script, which is also in
+ the scripts of the
+ Git repository created earlier.
+
+ Run the build.sh script
+ as directed.
+ Be sure to provide the name of the Git branch along with the
+ Yocto Project release you are using.
+ Here is an example that uses the &DISTRO_NAME; branches:
+
+ $ ECLIPSE_HOME=/home/scottrif/yocto-eclipse/scripts/eclipse ./build.sh &DISTRO_NAME; &DISTRO_NAME;
+
+ After running the script, the file
+ org.yocto.sdk-<release>-<date>-archive.zip
+ is in the current directory.
+ If necessary, start the Eclipse IDE and be sure you are in the
+ Workbench.
+ Select "Install New Software" from the "Help" pull-down menu.
+
+ Click "Add".
+ Provide anything you want in the "Name" field.
+ Click "Archive" and browse to the ZIP file you built
+ in step seven.
+ This ZIP file should not be "unzipped", and must be the
+ *archive.zip file created by running the
+ build.sh script.
+ Click through the "Okay" buttons.
+ Check the box next to the new entry in the installation window and complete
+ the installation.
+ Restart the Eclipse IDE if necessary.
+
+
+
+
+ At this point you should be able to configure the Eclipse Yocto Plug-in as described in the
+ "Configuring the Eclipse Yocto Plug-in"
+ section.
+
+
+
+ Importing the Plug-in Project into the Eclipse Environment
+
+
+ Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories
+ is useful when you want to try out the latest plug-in from the tip of plug-in's
+ development tree.
+ It is important to understand when you import the plug-in you are not installing
+ it into the Eclipse application.
+ Rather, you are importing the project and just using it.
+ To import the plug-in project, follow these steps:
+
+ Open a shell and create a Git repository with:
+
+ $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse
+
+ For this example, the repository is named
+ ~/yocto-eclipse.
+ In Eclipse, select "Import" from the "File" menu.
+ Expand the "General" box and select "existing projects into workspace"
+ and then click "Next".
+ Select the root directory and browse to
+ ~/yocto-eclipse/plugins.
+ Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and
+ "org.yocto.sdk.remotetools".
+ Select and import all of them.
+
+
+
+
+ The left navigation pane in the Eclipse application shows the default projects.
+ Right-click on one of these projects and run it as an Eclipse application.
+ This brings up a second instance of Eclipse IDE that has the Yocto Plug-in.
+
+
+
+
+
+ Configuring the Eclipse Yocto Plug-in
+
+
+ Configuring the Eclipse Yocto Plug-in involves setting the Cross
+ Compiler options and the Target options.
+ The configurations you choose become the default settings for all projects.
+ You do have opportunities to change them later when
+ you configure the project (see the following section).
+
+
+
+ To start, you need to do the following from within the Eclipse IDE:
+
+ Choose Windows -> Preferences to display
+ the Preferences Dialog
+ Click Yocto Project ADT
+
+
+
+
+ Configuring the Cross-Compiler Options
+
+
+ To configure the Cross Compiler Options, you must select the type of toolchain,
+ point to the toolchain, specify the sysroot location, and select the target architecture.
+
+ Selecting the Toolchain Type:
+ Choose between Standalone pre-built toolchain
+ and Build system derived toolchain for Cross
+ Compiler Options.
+
+
+ Standalone Pre-built Toolchain:
+ Select this mode when you are using a stand-alone cross-toolchain.
+ For example, suppose you are an application developer and do not
+ need to build a target image.
+ Instead, you just want to use an architecture-specific toolchain on an
+ existing kernel and target root filesystem.
+
+
+ Build System Derived Toolchain:
+ Select this mode if the cross-toolchain has been installed and built
+ as part of the Build Directory.
+ When you select Build system derived toolchain,
+ you are using the toolchain bundled
+ inside the Build Directory.
+
+
+
+ Point to the Toolchain:
+ If you are using a stand-alone pre-built toolchain, you should be pointing to the
+ &YOCTO_ADTPATH_DIR; directory.
+ This is the location for toolchains installed by the ADT Installer or by hand.
+ Sections "Configuring
+ and Running the ADT Installer Script" and
+ "Using a Cross-Toolchain Tarball"
+ in the Yocto Project Application Developer's Guide
+ describe two ways to install a stand-alone cross-toolchain in the
+ /opt/poky directory.
+ It is possible to install a stand-alone cross-toolchain in a directory
+ other than /opt/poky.
+ However, doing so is discouraged.
+ If you are using a system-derived toolchain, the path you provide
+ for the Toolchain Root Location
+ field is the Build Directory.
+ See the "Using
+ BitBake and the Build Directory" section in the Yocto Project Application
+ Developer's Guide for information on how to install the toolchain into the build
+directory.
+ Specify the Sysroot Location:
+ This location is where the root filesystem for the target hardware resides.
+ If you used the ADT Installer, then the location is
+ /opt/poky/<release>.
+ Additionally, when you use the ADT Installer, the same location is used for
+ the QEMU user-space tools and the NFS boot process.
+ If you used either of the other two methods to install the toolchain, then the
+ location of the sysroot filesystem depends on where you separately
+ extracted and intalled the filesystem.
+ For information on how to install the toolchain and on how to extract
+ and install the sysroot filesystem, see the
+ "Installing the ADT and Toolchains" section.
+
+ Select the Target Architecture:
+ The target architecture is the type of hardware you are
+ going to use or emulate.
+ Use the pull-down Target Architecture menu to make
+ your selection.
+ The pull-down menu should have the supported architectures.
+ If the architecture you need is not listed in the menu, you
+ will need to build the image.
+ See the "Building an Image" section
+ of the Yocto Project Quick Start for more information.
+
+
+
+
+
+ Configuring the Target Options
+
+
+ You can choose to emulate hardware using the QEMU emulator, or you
+ can choose to run your image on actual hardware.
+
+ QEMU: Select this option if
+ you will be using the QEMU emulator.
+ If you are using the emulator, you also need to locate the kernel
+ and specify any custom options.
+ If you selected Build system derived toolchain,
+ the target kernel you built will be located in the
+ Build Directory in tmp/deploy/images directory.
+ If you selected Standalone pre-built toolchain, the
+ pre-built image you downloaded is located
+ in the directory you specified when you downloaded the image.
+ Most custom options are for advanced QEMU users to further
+ customize their QEMU instance.
+ These options are specified between paired angled brackets.
+ Some options must be specified outside the brackets.
+ In particular, the options serial,
+ nographic, and kvm must all
+ be outside the brackets.
+ Use the man qemu command to get help on all the options
+ and their use.
+ The following is an example:
+
+ serial ‘<-m 256 -full-screen>’
+
+
+ Regardless of the mode, Sysroot is already defined as part of the
+ Cross Compiler Options configuration in the
+ Sysroot Location: field.
+ External HW: Select this option
+ if you will be using actual hardware.
+
+
+
+
+ Click the OK button to save your plug-in configurations.
+
+
+
+
+
+
+ Creating the Project
+
+
+ You can create two types of projects: Autotools-based, or Makefile-based.
+ This section describes how to create Autotools-based projects from within
+ the Eclipse IDE.
+ For information on creating Makefile-based projects in a terminal window, see the section
+ "Using the Command Line"
+ in the Yocto Project Application Developer's Guide.
+
+
+
+ To create a project based on a Yocto template and then display the source code,
+ follow these steps:
+
+ Select File -> New -> Project.
+ Double click CC++.
+ Double click C Project to create the project.
+ Expand Yocto Project ADT Project.
+ Select Hello World ANSI C Autotools Project.
+ This is an Autotools-based project based on a Yocto template.
+ Put a name in the Project name: field.
+ Do not use hyphens as part of the name.
+ Click Next.
+ Add information in the Author and
+ Copyright notice fields.
+ Be sure the License field is correct.
+ Click Finish.
+ If the "open perspective" prompt appears, click "Yes" so that you
+ in the C/C++ perspective.
+ The left-hand navigation pane shows your project.
+ You can display your source by double clicking the project's source file.
+
+
+
+
+
+
+ Configuring the Cross-Toolchains
+
+
+ The earlier section, "Configuring
+ the Eclipse Yocto Plug-in", sets up the default project
+ configurations.
+ You can override these settings for a given project by following these steps:
+
+ Select Project -> Change Yocto Project Settings:
+ This selection brings up the Yocot Project Settings Dialog
+ and allows you to make changes specific to an individual project.
+
+ By default, the Cross Compiler Options and Target Options for a project
+ are inherited from settings you provide using the Preferences
+ Dialog as described earlier
+ in the "Configuring the Eclipse
+ Yocto Plug-in" section.
+ The Yocto Project Settings
+ Dialog allows you to override those default settings
+ for a given project.
+ Make your configurations for the project and click "OK".
+ If you are running the Juno version of Eclipse, you can skip down to the next
+ section where you build the project.
+ If you are not working with Juno, you need to reconfigure the project as
+ described in the next step.
+ Select Project -> Reconfigure Project:
+ This selection reconfigures the project by running
+ autogen.sh in the workspace for your project.
+ The script also runs libtoolize, aclocal,
+ autoconf, autoheader,
+ automake --a, and
+ ./configure.
+ Click on the Console tab beneath your source code to
+ see the results of reconfiguring your project.
+
+
+
+
+
+ Building the Project
+
+
+ To build the project in Juno, right click on the project in the navigator pane and select
+ Build Project.
+ If you are not running Juno, select Project -> Build Project.
+ The console should update and you can note the cross-compiler you are using.
+
+
+
+
+ Starting QEMU in User Space NFS Mode
+
+
+ To start the QEMU emulator from within Eclipse, follow these steps:
+
+ Expose the Run -> External Tools menu.
+ Your image should appear as a selectable menu item.
+
+ Select your image from the menu to launch the
+ emulator in a new window.
+ If needed, enter your host root password in the shell window at the prompt.
+ This sets up a Tap 0 connection needed for running in user-space
+ NFS mode.
+ Wait for QEMU to launch.
+ Once QEMU launches, you can begin operating within that
+ environment.
+ For example, you could determine the IP Address
+ for the user-space NFS by using the ifconfig command.
+
+
+
+
+
+
+ Deploying and Debugging the Application
+
+
+ Once the QEMU emulator is running the image, using the Eclipse IDE
+ you can deploy your application and use the emulator to perform debugging.
+ Follow these steps to deploy the application.
+
+ Select Run -> Debug Configurations...
+ In the left area, expand C/C++Remote Application.
+ Locate your project and select it to bring up a new
+ tabbed view in the Debug Configurations Dialog.
+ Enter the absolute path into which you want to deploy
+ the application.
+ Use the Remote Absolute File Path for C/C++Application: field.
+ For example, enter /usr/bin/<programname>.
+ Click on the Debugger tab to see the cross-tool debugger
+ you are using.
+ Click on the Main tab.
+ Create a new connection to the QEMU instance
+ by clicking on new.
+ Select TCF, which means Target Communication
+ Framework.
+ Click Next.
+ Clear out the host name field and enter the IP Address
+ determined earlier.
+ Click Finish to close the
+ New Connections Dialog.
+ Use the drop-down menu now in the Connection field and pick
+ the IP Address you entered.
+ Click Run to bring up a login screen
+ and login.
+ Accept the debug perspective.
+
+
+
+
+
+ Running User-Space Tools
+
+
+ As mentioned earlier in the manual, several tools exist that enhance
+ your development experience.
+ These tools are aids in developing and debugging applications and images.
+ You can run these user-space tools from within the Eclipse IDE through the
+ YoctoTools menu.
+
+
+
+ Once you pick a tool, you need to configure it for the remote target.
+ Every tool needs to have the connection configured.
+ You must select an existing TCF-based RSE connection to the remote target.
+ If one does not exist, click New to create one.
+
+
+
+ Here are some specifics about the remote tools:
+
+ OProfile: Selecting this tool causes
+ the oprofile-server on the remote target to launch on
+ the local host machine.
+ The oprofile-viewer must be installed on the local host machine and the
+ oprofile-server must be installed on the remote target,
+ respectively, in order to use.
+ You must compile and install the oprofile-viewer from the source code
+ on your local host machine.
+ Furthermore, in order to convert the target's sample format data into a form that the
+ host can use, you must have oprofile version 0.9.4 or
+ greater installed on the host.
+ You can locate both the viewer and server from
+ .
+ The oprofile-server is installed by default on
+ the core-image-sato-sdk image.
+ Lttng2.0 ust trace import:
+ Selecting this tool transfers the remote target's
+ Lttng tracing data back to the local host machine
+ and uses the Lttng Eclipse plug-in to graphically
+ display the output.
+ For information on how to use Lttng to trace an application,
+ see .
+ Do not use Lttng-user space (legacy) tool.
+ This tool no longer has any upstream support.
+
+ Before you use the Lttng2.0 ust trace import tool,
+ you need to setup the Lttng Eclipse plug-in and create a
+ Tracing project.
+ Do the following:
+
+ Select Window -> Open Perspective -> Other
+ and then select Tracing.
+ Click OK to change the Eclipse perspective
+ into the Tracing perspective.
+ Create a new Tracing project by selecting
+ File -> New -> Project.
+ Choose Tracing -> Tracing Project.
+
+ Generate your tracing data on the remote target.
+
+ Click
+ Yocto Project Tools -> Lttng2.0 ust trace import
+ to start the data import process.
+ Specify your remote connection name.
+ For the Ust directory path, specify the location of
+ your remote tracing data.
+ Make sure the location ends with ust (e.g.
+ /usr/mysession/ust.
+ Click OK to complete the import process.
+ The data is now in the local tracing project you created.
+ Right click on the data and then use the menu to
+ Select Trace Type... -> Common Trace Format -> Generic CTF Trace
+ to map the tracing type.
+ Right click the mouse and select Open
+ to bring up the Eclipse Lttng Trace Viewer so you
+ view the tracing data.
+
+ PowerTOP: Selecting this tool runs
+ powertop on the remote target machine and displays the results in a
+ new view called powertop.
+ Time to gather data(sec): is the time passed in seconds before data
+ is gathered from the remote target for analysis.
+ show pids in wakeups list: corresponds to the
+ -p argument
+ passed to powertop.
+ LatencyTOP and Perf:
+ latencytop identifies system latency, while
+ perf monitors the system's
+ performance counter registers.
+ Selecting either of these tools causes an RSE terminal view to appear
+ from which you can run the tools.
+ Both tools refresh the entire screen to display results while they run.
+
+
+
+
+
+ Customizing an Image Using a BitBake Commander Project and Hob
+
+
+ Within Eclipse, you can create a Yocto BitBake Commander project,
+ edit the metadata, and then use the
+ Hob to build a customized
+ image all within one IDE.
+
+
+
+ Creating the Yocto BitBake Commander Project
+
+
+ To create a Yocto BitBake Commander project, follow these steps:
+
+ Select Window -> Open Perspective -> Other
+ and then choose Bitbake Commander.
+ Click OK to change the Eclipse perspective into the
+ Bitbake Commander perspective.
+ Select File -> New -> Project to create a new Yocto
+ Bitbake Commander project.
+ Choose Yocto Project Bitbake Commander -> New Yocto Project
+ and click Next.
+ Enter the Project Name and choose the Project Location.
+ The Yocto project's metadata files will be put under the directory
+ <project_location>/<project_name>.
+ If that directory does not exist, you need to check
+ the "Clone from Yocto Git Repository" box, which would execute a
+ git clone command to get the project's metadata files.
+
+ Select Finish to create the project.
+
+
+
+
+
+ Editing the Metadata Files
+
+
+ After you create the Yocto Bitbake Commander project, you can modify the metadata files
+ by opening them in the project.
+ When editing recipe files (.bb files), you can view BitBake
+ variable values and information by hovering the mouse pointer over the variable name and
+ waiting a few seconds.
+
+
+
+ To edit the metadata, follow these steps:
+
+ Select your Yocto Bitbake Commander project.
+ Select File -> New -> Yocto BitBake Commander -> BitBake Recipe
+ to open a new recipe wizard.
+ Point to your source by filling in the "SRC_URL" field.
+ For example, you can add a recipe to your
+ Source Directory
+ by defining "SRC_URL" as follows:
+
+ ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz
+
+ Click "Populate" to calculate the archive md5, sha256,
+ license checksum values and to auto-generate the recipe filename.
+ Fill in the "Description" field.
+ Be sure values for all required fields exist.
+ Click Finish.
+
+
+
+
+
+ Building and Customizing the Image
+
+
+ To build and customize the image in Eclipse, follow these steps:
+
+ Select your Yocto Bitbake Commander project.
+ Select Project -> Launch HOB.
+ Enter the Build Directory where you want to put your final images.
+ Click OK to launch Hob.
+ Use Hob to customize and build your own images.
+ For information on Hob, see the
+ Hob Project Page on the
+ Yocto Project website.
+
+
+
+
+
+
+
+ Workflow Using Stand-alone Cross-development Toolchains
+
+
+ If you want to develop an application without prior installation of the ADT, you
+ still can employ the cross-development toolchain, the QEMU emulator, and a number of supported
+ target image files.
+ You just need to follow these general steps:
+
+ Install the cross-development toolchain for your target hardware:
+ For information on how to install the toolchain, see the
+ "Using a Cross-Toolchain Tarball"
+ section
+ in the Yocto Project Application Developer's Guide.
+ Download the Target Image: The Yocto Project supports
+ several target architectures and has many pre-built kernel images and root filesystem
+ images.
+ If you are going to develop your application on hardware, go to the
+ machines
+ download area and choose a target machine area
+ from which to download the kernel image and root filesystem.
+ This download area could have several files in it that support development using
+ actual hardware.
+ For example, the area might contain .hddimg files that combine the
+ kernel image with the filesystem, boot loaders, etc.
+ Be sure to get the files you need for your particular development process.
+ If you are going to develop your application and then run and test it using the QEMU
+ emulator, go to the
+ machines/qemu
+ download area.
+ From this area, go down into the directory for your target architecture
+ (e.g. qemux86_64 for an
+ Intel-based 64-bit architecture).
+ Download kernel, root filesystem, and any other files you need for your process.
+ In order to use the root filesystem in QEMU, you need to extract it.
+ See the
+ "Extracting the Root Filesystem"
+ section for information on how to extract the root filesystem.
+ Develop and Test your Application: At this point,
+ you have the tools to develop your application.
+ If you need to separately install and use the QEMU emulator, you can go to
+ QEMU Home Page to download and learn about the
+ emulator.
+
+
+
+
+
+
+ Modifying Temporary Source Code
+
+
+ You might
+ find it helpful during development to modify the temporary source code used by recipes
+ to build packages.
+ For example, suppose you are developing a patch and you need to experiment a bit
+ to figure out your solution.
+ After you have initially built the package, you can iteratively tweak the
+ source code, which is located in the
+ Build Directory, and then
+ you can force a re-compile and quickly test your altered code.
+ Once you settle on a solution, you can then preserve your changes in the form of
+ patches.
+ You can accomplish these steps all within either a
+ Quilt or
+ Git workflow.
+
+
+
+ Finding the Temporary Source Code
+
+
+ During a build, the unpacked temporary source code used by recipes
+ to build packages is available in the Build Directory as
+ defined by the
+ S variable.
+ Below is the default value for the S variable as defined in the
+ meta/conf/bitbake.conf configuration file in the
+ Source Directory:
+
+ S = ${WORKDIR}/${BP}
+
+ You should be aware that many recipes override the S variable.
+ For example, recipes that fetch their source from Git usually set
+ S to ${WORKDIR}/git.
+
+ The
+ BP
+ represents the base recipe name, which consists of the name and version:
+
+ BP = ${BPN}-${PV}
+
+
+
+
+
+ The path to the work directory for the recipe
+ (WORKDIR) depends
+ on the recipe name and the architecture of the target device.
+ For example, here is the work directory for recipes and resulting packages that are
+ not device-dependent:
+
+ ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
+
+ Let's look at an example without variables.
+ Assuming a top-level Source Directory
+ named poky
+ and a default Build Directory of poky/build,
+ the following is the work directory for the acl recipe that
+ creates the acl package:
+
+ ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3
+
+
+
+
+ If your resulting package is dependent on the target device,
+ the work directory varies slightly:
+
+ ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
+
+ Again, assuming top-level Source Directory named poky
+ and a default Build Directory of poky/build, the
+ following are the work and temporary source directories, respectively,
+ for the acl package that is being
+ built for a MIPS-based device:
+
+ ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
+ ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2/acl-2.2.51
+
+
+
+
+ To better understand how the OpenEmbedded build system resolves directories during the
+ build process, see the glossary entries for the
+ WORKDIR,
+ TMPDIR,
+ TOPDIR,
+ PACKAGE_ARCH,
+ TARGET_OS,
+ PN,
+ PV,
+ and
+ PR
+ variables in the Yocto Project Reference Manual.
+
+
+
+ Now that you know where to locate the directory that has the temporary source code,
+ you can use a Quilt or Git workflow to make your edits, test the changes,
+ and preserve the changes in the form of patches.
+
+
+
+
+ Using a Quilt Workflow
+
+
+ Quilt
+ is a powerful tool that allows you to capture source code changes without having
+ a clean source tree.
+ This section outlines the typical workflow you can use to modify temporary source code,
+ test changes, and then preserve the changes in the form of a patch all using Quilt.
+
+
+
+ Follow these general steps:
+
+ Find the Source Code:
+ The temporary source code used by the OpenEmbedded build system is kept in the
+ Build Directory.
+ See the
+ "Finding the Temporary Source Code"
+ section to learn how to locate the directory that has the temporary source code for a
+ particular package.
+ Change Your Working Directory:
+ You need to be in the directory that has the temporary source code.
+ That directory is defined by the
+ S
+ variable.
+ Create a New Patch:
+ Before modifying source code, you need to create a new patch.
+ To create a new patch file, use quilt new as below:
+
+ $ quilt new my_changes.patch
+
+ Notify Quilt and Add Files:
+ After creating the patch, you need to notify Quilt about the files
+ you plan to edit.
+ You notify Quilt by adding the files to the patch you just created:
+
+ $ quilt add file1.c file2.c file3.c
+
+
+ Edit the Files:
+ Make your changes in the temporary source code to the files you added
+ to the patch.
+ Test Your Changes:
+ Once you have modified the source code, the easiest way to test your changes
+ is by calling the compile task as shown in the following example:
+
+ $ bitbake -c compile -f <name_of_package>
+
+ The -f or --force
+ option forces re-execution of the specified task.
+ If you find problems with your code, you can just keep editing and
+ re-testing iteratively until things work as expected.
+ All the modifications you make to the temporary source code
+ disappear once you -c clean or
+ -c cleanall with BitBake for the package.
+ Modifications will also disappear if you use the rm_work
+ feature as described in the
+ "Building an Image"
+ section of the Yocto Project Quick Start.
+
+ Generate the Patch:
+ Once your changes work as expected, you need to use Quilt to generate the final patch that
+ contains all your modifications.
+
+ $ quilt refresh
+
+ At this point the my_changes.patch file has all your edits made
+ to the file1.c, file2.c, and
+ file3.c files.
+ You can find the resulting patch file in the patches/
+ subdirectory of the source (S) directory.
+ Copy the Patch File:
+ For simplicity, copy the patch file into a directory named files,
+ which you can create in the same directory that holds the recipe
+ (.bb) file or the
+ append (.bbappend) file.
+ Placing the patch here guarantees that the OpenEmbedded build system will find
+ the patch.
+ Next, add the patch into the
+ SRC_URI
+ of the recipe.
+ Here is an example:
+
+ SRC_URI += "file://my_changes.patch"
+
+ Increment the Recipe Revision Number:
+ Finally, don't forget to 'bump' the
+ PR
+ value in the recipe since the resulting packages have changed.
+
+
+
+
+ Using a Git Workflow
+
+ Git is an even more powerful tool that allows you to capture source code changes without having
+ a clean source tree.
+ This section outlines the typical workflow you can use to modify temporary source code,
+ test changes, and then preserve the changes in the form of a patch all using Git.
+ For general information on Git as it is used in the Yocto Project, see the
+ "Git" section.
+
+
+
+ This workflow uses Git only for its ability to manage local changes to the source code
+ and produce patches independent of any version control system used with the Yocto Project.
+
+
+
+ Follow these general steps:
+
+ Find the Source Code:
+ The temporary source code used by the OpenEmbedded build system is kept in the
+ Build Directory.
+ See the
+ "Finding the Temporary Source Code"
+ section to learn how to locate the directory that has the temporary source code for a
+ particular package.
+ Change Your Working Directory:
+ You need to be in the directory that has the temporary source code.
+ That directory is defined by the
+ S
+ variable.
+ If needed, initialize a Git Repository:
+ If the recipe you are working with does not use a Git fetcher,
+ you need to set up a Git repository as follows:
+
+ $ git init
+ $ git add *
+ $ git commit -m "initial revision"
+
+ The above Git commands initialize a Git repository that is based on the
+ files in your current working directory, stage all the files, and commit
+ the files.
+ At this point, your Git repository is aware of all the source code files.
+ Any edits you now make to files can be committed later and will be tracked by
+ Git.
+ Edit the Files:
+ Make your changes to the temporary source code.
+ Test Your Changes:
+ Once you have modified the source code, the easiest way to test your changes
+ is by calling the compile task as shown in the following example:
+
+ $ bitbake -c compile -f <name_of_package>
+
+ The -f or --force
+ option forces re-execution of the specified task.
+ If you find problems with your code, you can just keep editing and
+ re-testing iteratively until things work as expected.
+ All the modifications you make to the temporary source code
+ disappear once you -c clean, -c cleansstate,
+ or -c cleanall with BitBake for the package.
+ Modifications will also disappear if you use the rm_work
+ feature as described in the
+ "Building an Image"
+ section of the Yocto Project Quick Start.
+
+ See the List of Files You Changed:
+ Use the git status command to see what files you have actually edited.
+ The ability to have Git track the files you have changed is an advantage that this
+ workflow has over the Quilt workflow.
+ Here is the Git command to list your changed files:
+
+ $ git status
+
+ Stage the Modified Files:
+ Use the git add command to stage the changed files so they
+ can be committed as follows:
+
+ $ git add file1.c file2.c file3.c
+
+ Commit the Staged Files and View Your Changes:
+ Use the git commit command to commit the changes to the
+ local repository.
+ Once you have committed the files, you can use the git log
+ command to see your changes:
+
+ $ git commit -m "<commit-summary-message>"
+ $ git log
+
+ The name of the patch file created in the next step is based on your
+ commit-summary-message.
+ Generate the Patch:
+ Once the changes are committed, use the git format-patch
+ command to generate a patch file:
+
+ $ git format-patch -1
+
+ Specifying "-1" causes Git to generate the
+ patch file for the most recent commit.
+ At this point, the patch file has all your edits made
+ to the file1.c, file2.c, and
+ file3.c files.
+ You can find the resulting patch file in the current directory and it
+ is named according to the git commit summary line.
+ The patch file ends with .patch.
+ Copy the Patch File:
+ For simplicity, copy the patch file into a directory named files,
+ which you can create in the same directory that holds the recipe
+ (.bb) file or the
+ append (.bbappend) file.
+ Placing the patch here guarantees that the OpenEmbedded build system will find
+ the patch.
+ Next, add the patch into the
+ SRC_URI
+ of the recipe.
+ Here is an example:
+
+ SRC_URI += "file://0001-<commit-summary-message>.patch"
+
+ Increment the Recipe Revision Number:
+ Finally, don't forget to 'bump' the
+ PR
+ value in the recipe since the resulting packages have changed.
+
+
+
+
+
+
+ Image Development Using Hob
+
+
+ The Hob is a graphical user interface for the
+ OpenEmbedded build system, which is based on BitBake.
+ You can use the Hob to build custom operating system images within the Yocto Project build environment.
+ Hob simply provides a friendly interface over the build system used during system development.
+ In other words, building images with the Hob lets you take care of common build tasks more easily.
+
+
+
+ For a better understanding of Hob, see the project page at
+ on the Yocto Project website.
+ The page has a short introductory training video on Hob.
+ The following lists some features of Hob:
+
+ You can setup and run Hob using these commands:
+
+ $ source oe-init-build-env
+ $ hob
+
+ You can set the
+ MACHINE
+ for which you are building the image.
+ You can modify various policy settings such as the package format used to build with,
+ the parrallelism BitBake uses, whether or not to build an external toolchain, and which host
+ to build against.
+ You can manage
+ layers.
+ You can select a base image and then add extra packages for your custom build.
+
+ You can launch and monitor the build from within Hob.
+
+
+
+
+
+ Using a Development Shell
+
+
+ When debugging certain commands or even when just editing packages,
+ devshell can be a useful tool.
+ 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 OpenEmbedded build-related environment variables are
+ still defined so you can use commands such as configure and
+ make.
+ The commands execute just as if the OpenEmbedded build system were executing them.
+ Consequently, working this way can be helpful when debugging a build or preparing
+ software to be used with the OpenEmbedded build system.
+
+
+
+ Following is an example that uses devshell on a target named
+ matchbox-desktop:
+
+ $ bitbake matchbox-desktop -c devshell
+
+
+
+
+ This command spawns a terminal with a shell prompt within the OpenEmbedded build environment.
+ The OE_TERMINAL
+ controls what type of shell is opened.
+
+
+
+ For spawned terminals, the following occurs:
+
+ 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
+ the OpenEmbedded 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.
+
+
+
+
+ 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 binutils,
+ libtool and so forth.
+ BitBake sets up 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
+
+
+
+
+
+
diff --git a/documentation/profile-manual/profile-manual-intro.xml b/documentation/profile-manual/profile-manual-intro.xml
new file mode 100644
index 0000000000..dca24602ed
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-intro.xml
@@ -0,0 +1,190 @@
+ %poky; ] >
+
+
+
+The Yocto Project Development Manual
+
+ Introduction
+
+
+ Welcome to the Yocto Project Development Manual!
+ This manual gives you an idea of how to use the Yocto Project to develop embedded Linux
+ images and user-space applications to run on targeted devices.
+ Reading this manual gives you an overview of image, kernel, and user-space application development
+ using the Yocto Project.
+ Because much of the information in this manual is general, it contains many references to other
+ sources where you can find more detail.
+ For example, detailed information on Git, repositories and open source in general
+ can be found in many places.
+ Another example is how to get set up to use the Yocto Project, which our Yocto Project
+ Quick Start covers.
+
+
+
+ The Yocto Project Development Manual, however, does provide detailed examples
+ on how to change the kernel source code, reconfigure the kernel, and develop
+ an application using the popular Eclipse IDE.
+
+
+
+
+ What this Manual Provides
+
+
+ The following list describes what you can get from this guide:
+
+ Information that lets you get set
+ up to develop using the Yocto Project.
+ Information to help developers who are new to the open source environment
+ and to the distributed revision control system Git, which the Yocto Project
+ uses.
+ An understanding of common end-to-end development models and tasks.
+ Development case overviews for both system development and user-space
+ applications.
+ An overview and understanding of the emulation environment used with
+ the Yocto Project - the Quick EMUlator (QEMU).
+ An understanding of basic kernel architecture and concepts.
+ Many references to other sources of related information.
+
+
+
+
+
+ What this Manual Does Not Provide
+
+
+ This manual will not give you the following:
+
+ Step-by-step instructions if those instructions exist in other Yocto
+ Project documentation.
+ For example, the Yocto Project Application Developer's Guide contains detailed
+ instruction on how to run the
+ Installing the ADT and Toolchains,
+ which is used to set up a cross-development environment.
+ Reference material.
+ This type of material resides in an appropriate reference manual.
+ For example, system variables are documented in the
+ Yocto Project Reference Manual.
+ Detailed public information that is not specific to the Yocto Project.
+ For example, exhaustive information on how to use Git is covered better through the
+ Internet than in this manual.
+
+
+
+
+
+ Other Information
+
+
+ Because this manual presents overview information for many different topics, you will
+ need to supplement it with other information.
+ The following list presents other sources of information you might find helpful:
+
+ The Yocto Project Website:
+ The home page for the Yocto Project provides lots of information on the project
+ as well as links to software and documentation.
+
+ Yocto Project Quick Start: This short document lets you get started
+ with the Yocto Project quickly and start building an image.
+
+ Yocto Project Reference Manual: This manual is a reference
+ guide to the OpenEmbedded build system known as "Poky."
+ The manual also contains a reference chapter on Board Support Package (BSP)
+ layout.
+
+ Yocto Project Application Developer's Guide:
+ This guide provides information that lets you get going with the Application
+ Development Toolkit (ADT) and stand-alone cross-development toolchains to
+ develop projects using the Yocto Project.
+
+ Yocto Project Board Support Package (BSP) Developer's Guide:
+ This guide defines the structure for BSP components.
+ Having a commonly understood structure encourages standardization.
+
+ Yocto Project Kernel Architecture and Use Manual:
+ This manual describes the architecture of the Yocto Project kernel and provides
+ some work flow examples.
+
+
+ Eclipse IDE Yocto Plug-in: A step-by-step instructional video that
+ demonstrates how an application developer uses Yocto Plug-in features within
+ the Eclipse IDE.
+
+ FAQ:
+ A list of commonly asked questions and their answers.
+
+
+ Release Notes: Features, updates and known issues for the current
+ release of the Yocto Project.
+
+
+ Hob: A graphical user interface for BitBake.
+ Hob's primary goal is to enable a user to perform common tasks more easily.
+
+
+ Build Appliance: A bootable custom embedded Linux image you can
+ either build using a non-Linux development system (VMware applications) or download
+ from the Yocto Project website.
+ See the Build Appliance
+ page for more information.
+
+ Bugzilla:
+ The bug tracking application the Yocto Project uses.
+ If you find problems with the Yocto Project, you should report them using this
+ application.
+
+ Yocto Project Mailing Lists: To subscribe to the Yocto Project mailing
+ lists, click on the following URLs and follow the instructions:
+
+ for a
+ Yocto Project Discussions mailing list.
+ for a
+ Yocto Project Discussions mailing list about the Poky build system.
+
+ for a mailing list to receive official Yocto Project announcements for developments and
+ as well as Yocto Project milestones.
+ for a
+ listing of all public mailing lists on lists.yoctoproject.org.
+
+
+ Internet Relay Chat (IRC):
+ Two IRC channels on freenode are available
+ for Yocto Project and Poky discussions: #yocto and
+ #poky, respectively.
+
+ OpenedHand:
+ The company that initially developed the Poky project, which is the basis
+ for the OpenEmbedded build system used by the Yocto Project.
+ OpenedHand was acquired by Intel Corporation in 2008.
+
+ Intel Corporation:
+ A multinational semiconductor chip manufacturer company whose Software and
+ Services Group created and supports the Yocto Project.
+ Intel acquired OpenedHand in 2008.
+
+ OpenEmbedded:
+ The build system used by the Yocto Project.
+ This project is the upstream, generic, embedded distribution from which the Yocto
+ Project derives its build system (Poky) from and to which it contributes.
+
+
+ BitBake: The tool used by the OpenEmbedded build system
+ to process project metadata.
+
+ BitBake User Manual:
+ A comprehensive guide to the BitBake tool.
+ If you want information on BitBake, see the user manual inculded in the
+ bitbake/doc/manual directory of the
+ Source Directory.
+
+ Quick EMUlator (QEMU):
+ An open-source machine emulator and virtualizer.
+
+
+
+
+
diff --git a/documentation/profile-manual/profile-manual-style.css b/documentation/profile-manual/profile-manual-style.css
new file mode 100644
index 0000000000..23c8e74c1e
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-style.css
@@ -0,0 +1,979 @@
+/*
+ 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/dev-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;*/
+}
+
+
+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-image: url("figures/yocto-project-bw.png");
+ 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/profile-manual/profile-manual-usage.xml b/documentation/profile-manual/profile-manual-usage.xml
new file mode 100644
index 0000000000..65e17e24a0
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-usage.xml
@@ -0,0 +1,1218 @@
+ %poky; ] >
+
+
+
+The Yocto Project Open Source Development Environment
+
+
+ This chapter helps you understand the Yocto Project as an open source development project.
+ In general, working in an open source environment is very different from working in a
+ closed, proprietary environment.
+ Additionally, the Yocto Project uses specific tools and constructs as part of its development
+ environment.
+ This chapter specifically addresses open source philosophy, licensing issues, code repositories,
+ the open source distributed version control system Git, and best practices using the Yocto Project.
+
+
+
+ Open Source Philosophy
+
+
+ Open source philosophy is characterized by software development directed by peer production
+ and collaboration through an active community of developers.
+ Contrast this to the more standard centralized development models used by commercial software
+ companies where a finite set of developers produces a product for sale using a defined set
+ of procedures that ultimately result in an end product whose architecture and source material
+ are closed to the public.
+
+
+
+ Open source projects conceptually have differing concurrent agendas, approaches, and production.
+ These facets of the development process can come from anyone in the public (community) that has a
+ stake in the software project.
+ The open source environment contains new copyright, licensing, domain, and consumer issues
+ that differ from the more traditional development environment.
+ In an open source environment, the end product, source material, and documentation are
+ all available to the public at no cost.
+
+
+
+ A benchmark example of an open source project is the Linux Kernel, which was initially conceived
+ and created by Finnish computer science student Linus Torvalds in 1991.
+ Conversely, a good example of a non-open source project is the
+ Windows family of operating
+ systems developed by Microsoft Corporation.
+
+
+
+ Wikipedia has a good historical description of the Open Source Philosophy
+ here.
+ You can also find helpful information on how to participate in the Linux Community
+ here.
+
+
+
+
+ Using the Yocto Project in a Team Environment
+
+
+ It might not be immediately clear how you can use the Yocto Project in a team environment,
+ or scale it for a large team of developers.
+ The specifics of any situation determine the best solution.
+ Granted that the Yocto Project offers immense flexibility regarding this, practices do exist
+ that experience has shown work well.
+
+
+
+ The core component of any development effort with the Yocto Project is often an
+ automated build and testing framework along with an image generation process.
+ You can use these core components to check that the metadata can be built,
+ highlight when commits break the build, and provide up-to-date images that
+ allow developers to test the end result and use it as a base platform for further
+ development.
+ Experience shows that buildbot is a good fit for this role.
+ What works well is to configure buildbot to make two types of builds:
+ incremental and full (from scratch).
+ See "Welcome to the buildbot for the Yocto Project"
+ for an example implementation that uses buildbot.
+
+
+
+ You can tie an incremental build to a commit hook that triggers the build
+ each time a commit is made to the metadata.
+ This practice results in useful acid tests that determine whether a given commit
+ breaks the build in some serious way.
+ Associating a build to a commit can catch a lot of simple errors.
+ Furthermore, the tests are fast so developers can get quick feedback on changes.
+
+
+
+ Full builds build and test everything from the ground up.
+ These types of builds usually happen at predetermined times like during the
+ night when the machine load is low.
+
+
+
+ Most teams have many pieces of software undergoing active development at any given time.
+ You can derive large benefits by putting these pieces under the control of a source
+ control system that is compatible (i.e. Git or Subversion (SVN)) with the OpenEmbedded
+ build system that the Yocto Project uses.
+ You can then set the autobuilder to pull the latest revisions of the packages
+ and test the latest commits by the builds.
+ This practice quickly highlights issues.
+ The build system easily supports testing configurations that use both a
+ stable known good revision and a floating revision.
+ The build system can also take just the changes from specific source control branches.
+ This capability allows you to track and test specific changes.
+
+
+
+ Perhaps the hardest part of setting this up is defining the software project or
+ the metadata policies that surround the different source control systems.
+ Of course circumstances will be different in each case.
+ However, this situation reveals one of the Yocto Project's advantages -
+ the system itself does not
+ force any particular policy on users, unlike a lot of build systems.
+ The system allows the best policies to be chosen for the given circumstances.
+
+
+
+ In general, best practices exist that make your work with the Yocto
+ Project easier in a team environment.
+ This list presents some of these practices you might consider following.
+ Of course, you need to understand that you do not have to follow these
+ practices and your setup can be totally controlled and customized by
+ your team:
+
+ Use Git
+ as the source control system.
+ Maintain your metadata in layers that make sense
+ for your situation.
+ See the "Understanding
+ and Creating Layers" section for more information on
+ layers.
+ Separate the project's metadata and code by using
+ separate Git repositories.
+ See the "Yocto Project
+ Source Repositories" section for information on these
+ repositories.
+ See the "Getting Set Up" section
+ for information on how to set up various Yocto Project related
+ Git repositories.
+ Set up the directory for the shared state cache
+ (SSTATE_DIR)
+ where they make sense.
+ For example, set up the sstate cache for developers using the
+ same office and share source directories on the developer's
+ machines.
+ Set up an autobuilder and have it populate the
+ sstate cache and source directories.
+
+
+
+
+
+ Yocto Project Source Repositories
+
+
+ The Yocto Project team maintains complete source repositories for all Yocto Project files
+ at .
+ This web-based source code browser is organized into categories by function such as
+ IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth.
+ From the interface, you can click on any particular item in the "Name" column and
+ see the URL at the bottom of the page that you need to set up a Git repository for
+ that particular item.
+ Having a local Git repository of the Source Directory (poky) allows you to
+ make changes, contribute to the history, and ultimately enhance the Yocto Project's
+ tools, Board Support Packages, and so forth.
+
+
+
+ Conversely, if you are a developer that is not interested in contributing back to the
+ Yocto Project, you have the ability to simply download and extract release tarballs
+ and use them within the Yocto Project environment.
+ All that is required is a particular release of the Yocto Project and
+ your application source code.
+
+
+
+ For any supported release of Yocto Project, you can go to the Yocto Project website’s
+ download page and get a
+ tarball of the release.
+ You can also go to this site to download any supported BSP tarballs.
+ Unpacking the tarball gives you a hierarchical Source Directory that lets you develop
+ using the Yocto Project.
+
+
+
+ Once you are set up through either tarball extraction or a checkout of Git repositories,
+ you are ready to develop.
+
+
+
+ In summary, here is where you can get the project files needed for development:
+
+ Source Repositories:
+ This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto
+ Metadata Layers.
+ You can create local copies of Git repositories for each of these areas.
+
+
+
+ Index of /releases:
+ This area contains index releases such as
+ the Eclipse
+ Yocto Plug-in, miscellaneous support, poky, pseudo, installers for cross-development toolchains,
+ and all released versions of Yocto Project in the form of images or tarballs.
+ Downloading and extracting these files does not produce a local copy of the
+ Git repository but rather a snapshot of a particular release or image.
+
+
+
+ Yocto Project Download Page
+ This page on the Yocto Project website allows you to download any Yocto Project
+ release or Board Support Package (BSP) in tarball form.
+ The tarballs are similar to those found in the
+ Index of /releases: area.
+
+
+
+
+
+
+
+
+ Yocto Project Terms
+
+
+ Following is a list of terms and definitions users new to the Yocto Project development
+ environment might find helpful.
+ While some of these terms are universal, the list includes them just in case:
+
+ Append Files: Files that append build information to
+ a recipe file.
+ Append files are known as BitBake append files and .bbappend files.
+ The OpenEmbedded build system expects every append file to have a corresponding and
+ underlying recipe (.bb) file.
+ Furthermore, the append file and the underlying recipe must have the same root filename.
+ The filenames can differ only in the file type suffix used (e.g.
+ formfactor_0.0.bb and formfactor_0.0.bbappend).
+
+ Information in append files overrides the information in the similarly-named recipe file.
+ For an example of an append file in use, see the
+ "Using .bbappend Files" section.
+
+ BitBake:
+ The task executor and scheduler used by
+ the OpenEmbedded build system to build images.
+ For more information on BitBake, see the BitBake documentation
+ in the bitbake/doc/manual directory of the
+ Source Directory.
+
+ Build Directory:
+ This term refers to the area used by the OpenEmbedded build system for builds.
+ The area is created when you source the setup
+ environment script that is found in the Source Directory
+ (i.e. &OE_INIT_FILE;).
+ The TOPDIR
+ variable points to the Build Directory.
+
+ You have a lot of flexibility when creating the Build Directory.
+ Following are some examples that show how to create the directory:
+
+ Create the Build Directory in your current working directory
+ and name it build.
+ This is the default behavior.
+
+ $ source &OE_INIT_PATH;
+
+ Provide a directory path and specifically name the build
+ directory.
+ This next example creates a Build Directory named YP-&POKYVERSION;
+ in your home directory within the directory mybuilds.
+ If mybuilds does not exist, the directory is created for you:
+
+ $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION;
+
+ Provide an existing directory to use as the Build Directory.
+ This example uses the existing mybuilds directory
+ as the Build Directory.
+
+ $ source &OE_INIT_PATH; $HOME/mybuilds/
+
+
+
+ Build System: In the context of the Yocto Project
+ this term refers to the OpenEmbedded build system used by the project.
+ This build system is based on the project known as "Poky."
+ For some historical information about Poky, see the
+ Poky term further along in this section.
+
+ Classes: Files that provide for logic encapsulation
+ and inheritance allowing commonly used patterns to be defined once and easily used
+ in multiple recipes.
+ Class files end with the .bbclass filename extension.
+
+ Configuration File: Configuration information in various
+ .conf files provides global definitions of variables.
+ The conf/local.conf configuration file in the
+ Build Directory
+ contains user-defined variables that affect each build.
+ The meta-yocto/conf/distro/poky.conf configuration file
+ defines Yocto ‘distro’ configuration
+ variables used only when building with this policy.
+ Machine configuration files, which
+ are located throughout the
+ Source Directory, define
+ variables for specific hardware and are only used when building for that target
+ (e.g. the machine/beagleboard.conf configuration file defines
+ variables for the Texas Instruments ARM Cortex-A8 development board).
+ Configuration files end with a .conf filename extension.
+
+ Cross-Development Toolchain:
+ A collection of software development
+ tools and utilities that allow you to develop software for targeted architectures.
+ This toolchain contains cross-compilers, linkers, and debuggers that are specific to
+ an architecture.
+ You can use the OpenEmbedded build system to build a cross-development toolchain
+ installer that when run installs the toolchain that contains the development tools you
+ need to cross-compile and test your software.
+ The Yocto Project ships with images that contain installers for
+ toolchains for supported architectures as well.
+ Sometimes this toolchain is referred to as the meta-toolchain.
+ Image: An image is the result produced when
+ BitBake processes a given collection of recipes and related metadata.
+ Images are the binary output that run on specific hardware or QEMU
+ and for specific use cases.
+ For a list of the supported image types that the Yocto Project provides, see the
+ "Images"
+ chapter in the Yocto Project Reference Manual.
+ Layer: A collection of recipes representing the core,
+ a BSP, or an application stack.
+ For a discussion on BSP Layers, see the
+ "BSP Layers"
+ section in the Yocto Project Board Support Packages (BSP) Developer's Guide.
+ Metadata: The files that BitBake parses when
+ building an image.
+ Metadata includes recipes, classes, and configuration files.
+ OE-Core: A core set of metadata originating
+ with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
+ This metadata is found in the meta directory of the source
+ directory.
+ Package: In the context of the Yocto Project,
+ this term refers to the packaged output from a baked recipe.
+ A package is generally the compiled binaries produced from the recipe's sources.
+ You ‘bake’ something by running it through BitBake.
+ It is worth noting that the term "package" can, in general, have subtle
+ meanings. For example, the packages refered to in the
+ "The Packages" section are
+ compiled binaries that when installed add functionality to your Linux
+ distribution.
+ Another point worth noting is that historically within the Yocto Project,
+ recipes were referred to as packages - thus, the existence of several BitBake
+ variables that are seemingly mis-named,
+ (e.g. PR,
+ PRINC,
+ PV, and
+ PE).
+
+ Poky: The term "poky" can mean several things.
+ In its most general sense, it is an open-source project that was initially developed
+ by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded
+ build system becoming a build system for embedded images.
+ After Intel Corporation acquired OpenedHand, the project poky became the basis for
+ the Yocto Project's build system.
+ Within the Yocto Project source repositories, poky exists as a separate Git repository
+ that can be cloned to yield a local copy on the host system.
+ Thus, "poky" can refer to the local copy of the Source Directory used to develop within
+ the Yocto Project.
+ Recipe: A set of instructions for building packages.
+ A recipe describes where you get source code and which patches to apply.
+ Recipes describe dependencies for libraries or for other recipes, and they
+ also contain configuration and compilation options.
+ Recipes contain the logical unit of execution, the software/images to build, and
+ use the .bb file extension.
+
+ Source Directory:
+ This term refers to the directory structure created as a result of either downloading
+ and unpacking a Yocto Project release tarball or creating a local copy of
+ the poky Git repository
+ git://git.yoctoproject.org/poky.
+ Sometimes you might hear the term "poky directory" used to refer to this
+ directory structure.
+
+ The OpenEmbedded build system does not support file or directory names that
+ contain spaces.
+ Be sure that the Source Directory you use does not contain these types
+ of names.
+
+ The Source Directory contains BitBake, Documentation, metadata and
+ other files that all support the Yocto Project.
+ Consequently, you must have the Source Directory in place on your development
+ system in order to do any development using the Yocto Project.
+
+ For tarball expansion, the name of the top-level directory of the Source Directory
+ is derived from the Yocto Project release tarball.
+ For example, downloading and unpacking &YOCTO_POKY_TARBALL;
+ results in a Source Directory whose top-level folder is named
+ &YOCTO_POKY;.
+ If you create a local copy of the Git repository, then you can name the repository
+ anything you like.
+ Throughout much of the documentation, poky is used as the name of
+ the top-level folder of the local copy of the poky Git repository.
+ So, for example, cloning the poky Git repository results in a
+ local Git repository whose top-level folder is also named poky.
+
+ It is important to understand the differences between the Source Directory created
+ by unpacking a released tarball as compared to cloning
+ git://git.yoctoproject.org/poky.
+ When you unpack a tarball, you have an exact copy of the files based on the time of
+ release - a fixed release point.
+ Any changes you make to your local files in the Source Directory are on top of the release.
+ On the other hand, when you clone the poky Git repository, you have an
+ active development repository.
+ In this case, any local changes you make to the Source Directory can be later applied
+ to active development branches of the upstream poky Git
+ repository.
+
+ Finally, if you want to track a set of local changes while starting from the same point
+ as a release tarball, you can create a local Git branch that
+ reflects the exact copy of the files at the time of their release.
+ You do this by using Git tags that are part of the repository.
+
+ For more information on concepts related to Git repositories, branches, and tags,
+ see the
+ "Repositories, Tags, and Branches"
+ section.
+ Tasks: Arbitrary groups of software Recipes.
+ You simply use Tasks to hold recipes that, when built, usually accomplish a single task.
+ For example, a task could contain the recipes for a company’s proprietary or value-add software.
+ Or, the task could contain the recipes that enable graphics.
+ A task is really just another recipe.
+ Because task files are recipes, they end with the .bb filename
+ extension.
+ Upstream: A reference to source code or repositories
+ that are not local to the development system but located in a master area that is controlled
+ by the maintainer of the source code.
+ For example, in order for a developer to work on a particular piece of code, they need to
+ first get a copy of it from an "upstream" source.
+
+
+
+
+
+ Licensing
+
+
+ Because open source projects are open to the public, they have different licensing structures in place.
+ License evolution for both Open Source and Free Software has an interesting history.
+ If you are interested in this history, you can find basic information here:
+
+ Open source license history
+
+ Free software license
+ history
+
+
+
+
+ In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology
+ (MIT) License.
+ MIT licensing permits the reuse of software within proprietary software as long as the
+ license is distributed with that software.
+ MIT is also compatible with the GNU General Public License (GPL).
+ Patches to the Yocto Project follow the upstream licensing scheme.
+ You can find information on the MIT license at
+ here.
+ You can find information on the GNU GPL
+ here.
+
+
+
+ When you build an image using the Yocto Project, the build process uses a
+ known list of licenses to ensure compliance.
+ You can find this list in the Yocto Project files directory at
+ meta/files/common-licenses.
+ Once the build completes, the list of all licenses found and used during that build are
+ kept in the
+ Build Directory at
+ tmp/deploy/images/licenses.
+
+
+
+ If a module requires a license that is not in the base list, the build process
+ generates a warning during the build.
+ These tools make it easier for a developer to be certain of the licenses with which
+ their shipped products must comply.
+ However, even with these tools it is still up to the developer to resolve potential licensing issues.
+
+
+
+ The base list of licenses used by the build process is a combination of the Software Package
+ Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects.
+ SPDX Group is a working group of the Linux Foundation
+ that maintains a specification
+ for a standard format for communicating the components, licenses, and copyrights
+ associated with a software package.
+ OSI is a corporation dedicated to the Open Source
+ Definition and the effort for reviewing and approving licenses that are OSD-conformant.
+
+
+
+ You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses
+ here.
+ This wiki page discusses the license infrastructure used by the Yocto Project.
+
+
+
+ For information that can help you to maintain compliance with various open source licensing
+ during the lifecycle of a product created using the Yocto Project, see the
+ "Maintaining Open Source License Compliance During Your Product's Lifecycle" section.
+
+
+
+
+ Git
+
+
+ The Yocto Project uses Git, which is a free, open source distributed version control system.
+ Git supports distributed development, non-linear development, and can handle large projects.
+ It is best that you have some fundamental understanding of how Git tracks projects and
+ how to work with Git if you are going to use Yocto Project for development.
+ This section provides a quick overview of how Git works and provides you with a summary
+ of some essential Git commands.
+
+
+
+ For more information on Git, see
+ .
+ If you need to download Git, go to .
+
+
+
+ Repositories, Tags, and Branches
+
+
+ As mentioned earlier in section
+ "Yocto Project Source Repositories",
+ the Yocto Project maintains source repositories at
+ .
+ If you look at this web-interface of the repositories, each item is a separate
+ Git repository.
+
+
+
+ Git repositories use branching techniques that track content change (not files)
+ within a project (e.g. a new feature or updated documentation).
+ Creating a tree-like structure based on project divergence allows for excellent historical
+ information over the life of a project.
+ This methodology also allows for an environment in which you can do lots of
+ local experimentation on a project as you develop changes or new features.
+
+
+
+ A Git repository represents all development efforts for a given project.
+ For example, the Git repository poky contains all changes
+ and developments for Poky over the course of its entire life.
+ That means that all changes that make up all releases are captured.
+ The repository maintains a complete history of changes.
+
+
+
+ You can create a local copy of any repository by "cloning" it with the Git
+ clone command.
+ When you clone a Git repository, you end up with an identical copy of the
+ repository on your development system.
+ Once you have a local copy of a repository, you can take steps to develop locally.
+ For examples on how to clone Git repositories, see the section
+ "Getting Set Up" earlier in this manual.
+
+
+
+ It is important to understand that Git tracks content change and not files.
+ Git uses "branches" to organize different development efforts.
+ For example, the poky repository has
+ bernard,
+ edison, denzil, danny
+ and master branches among others.
+ You can see all the branches by going to
+ and
+ clicking on the
+ [...]
+ link beneath the "Branch" heading.
+
+
+
+ Each of these branches represents a specific area of development.
+ The master branch represents the current or most recent
+ development.
+ All other branches represent off-shoots of the master
+ branch.
+
+
+
+ When you create a local copy of a Git repository, the copy has the same set
+ of branches as the original.
+ This means you can use Git to create a local working area (also called a branch)
+ that tracks a specific development branch from the source Git repository.
+ in other words, you can define your local Git environment to work on any development
+ branch in the repository.
+ To help illustrate, here is a set of commands that creates a local copy of the
+ poky Git repository and then creates and checks out a local
+ Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development:
+
+ $ cd ~
+ $ git clone git://git.yoctoproject.org/poky
+ $ cd poky
+ $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
+
+ In this example, the name of the top-level directory of your local Yocto Project
+ Files Git repository is poky,
+ and the name of the local working area (or local branch) you have created and checked
+ out is &DISTRO_NAME;.
+ The files in your repository now reflect the same files that are in the
+ &DISTRO_NAME; development branch of the Yocto Project's
+ poky repository.
+ It is important to understand that when you create and checkout a
+ local working branch based on a branch name,
+ your local environment matches the "tip" of that development branch
+ at the time you created your local branch, which could be
+ different than the files at the time of a similarly named release.
+ In other words, creating and checking out a local branch based on the
+ &DISTRO_NAME; branch name is not the same as
+ cloning and checking out the master branch.
+ Keep reading to see how you create a local snapshot of a Yocto Project Release.
+
+
+
+ Git uses "tags" to mark specific changes in a repository.
+ Typically, a tag is used to mark a special point such as the final change
+ before a project is released.
+ You can see the tags used with the poky Git repository
+ by going to and
+ clicking on the
+ [...]
+ link beneath the "Tag" heading.
+
+
+
+ Some key tags are bernard-5.0, denzil-7.0,
+ and &DISTRO_NAME;-&POKYVERSION;.
+ These tags represent Yocto Project releases.
+
+
+
+ When you create a local copy of the Git repository, you also have access to all the
+ tags.
+ Similar to branches, you can create and checkout a local working Git branch based
+ on a tag name.
+ When you do this, you get a snapshot of the Git repository that reflects
+ the state of the files when the change was made associated with that tag.
+ The most common use is to checkout a working branch that matches a specific
+ Yocto Project release.
+ Here is an example:
+
+ $ cd ~
+ $ git clone git://git.yoctoproject.org/poky
+ $ cd poky
+ $ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION;
+
+ In this example, the name of the top-level directory of your local Yocto Project
+ Files Git repository is poky.
+ And, the name of the local branch you have created and checked out is
+ my-&DISTRO_NAME;-&POKYVERSION;.
+ The files in your repository now exactly match the Yocto Project &DISTRO;
+ Release tag (&DISTRO_NAME;-&POKYVERSION;).
+ It is important to understand that when you create and checkout a local
+ working branch based on a tag, your environment matches a specific point
+ in time and not a development branch.
+
+
+
+
+ Basic Commands
+
+
+ Git has an extensive set of commands that lets you manage changes and perform
+ collaboration over the life of a project.
+ Conveniently though, you can manage with a small set of basic operations and workflows
+ once you understand the basic philosophy behind Git.
+ You do not have to be an expert in Git to be functional.
+ A good place to look for instruction on a minimal set of Git commands is
+ here.
+ If you need to download Git, you can do so
+ here.
+
+
+
+ If you don’t know much about Git, we suggest you educate
+ yourself by visiting the links previously mentioned.
+
+
+
+ The following list briefly describes some basic Git operations as a way to get started.
+ As with any set of commands, this list (in most cases) simply shows the base command and
+ omits the many arguments they support.
+ See the Git documentation for complete descriptions and strategies on how to use these commands:
+
+ git init: Initializes an empty Git repository.
+ You cannot use Git commands unless you have a .git repository.
+ git clone: Creates a clone of a repository.
+ During collaboration, this command allows you to create a local repository that is on
+ equal footing with a fellow developer’s repository.
+ git add: Adds updated file contents
+ to the index that
+ Git uses to track changes.
+ You must add all files that have changed before you can commit them.
+ git commit: Creates a “commit” that documents
+ the changes you made.
+ Commits are used for historical purposes, for determining if a maintainer of a project
+ will allow the change, and for ultimately pushing the change from your local Git repository
+ into the project’s upstream (or master) repository.
+ git status: Reports any modified files that
+ possibly need to be added and committed.
+ git checkout <branch-name>: Changes
+ your working branch.
+ This command is analogous to “cd”.
+ git checkout –b <working-branch>: Creates
+ a working branch on your local machine where you can isolate work.
+ It is a good idea to use local branches when adding specific features or changes.
+ This way if you don’t like what you have done you can easily get rid of the work.
+ git branch: Reports
+ existing local branches and
+ tells you the branch in which you are currently working.
+ git branch -D <branch-name>:
+ Deletes an existing local branch.
+ You need to be in a local branch other than the one you are deleting
+ in order to delete <branch-name>.
+ git pull: Retrieves information
+ from an upstream Git
+ repository and places it in your local Git repository.
+ You use this command to make sure you are synchronized with the repository
+ from which you are basing changes (.e.g. the master branch).
+ git push: Sends all your local changes you
+ have committed to an upstream Git repository (e.g. a contribution repository).
+ The maintainer of the project draws from these repositories when adding your changes to the
+ project’s master repository.
+ git merge: Combines or adds changes from one
+ local branch of your repository with another branch.
+ When you create a local Git repository, the default branch is named “master”.
+ A typical workflow is to create a temporary branch for isolated work, make and commit your
+ changes, switch to your local master branch, merge the changes from the temporary branch into the
+ local master branch, and then delete the temporary branch.
+ git cherry-pick: Choose and apply specific
+ commits from one branch into another branch.
+ There are times when you might not be able to merge all the changes in one branch with
+ another but need to pick out certain ones.
+ gitk: Provides a GUI view of the branches
+ and changes in your local Git repository.
+ This command is a good way to graphically see where things have diverged in your
+ local repository.
+ git log: Reports a history of your changes to the
+ repository.
+ git diff: Displays line-by-line differences
+ between your local working files and the same files in the upstream Git repository that your
+ branch currently tracks.
+
+
+
+
+
+
+ Workflows
+
+
+ This section provides some overview on workflows using Git.
+ In particular, the information covers basic practices that describe roles and actions in a
+ collaborative development environment.
+ Again, if you are familiar with this type of development environment, you might want to just
+ skip this section.
+
+
+
+ The Yocto Project files are maintained using Git in a "master" branch whose Git history
+ tracks every change and whose structure provides branches for all diverging functionality.
+ Although there is no need to use Git, many open source projects do so.
+ For the Yocto Project, a key individual called the "maintainer" is responsible for the "master"
+ branch of the Git repository.
+ The "master" branch is the “upstream” repository where the final builds of the project occur.
+ The maintainer is responsible for allowing changes in from other developers and for
+ organizing the underlying branch structure to reflect release strategies and so forth.
+ You can see who is the maintainer for Yocto Project files by examining the
+ maintainers.inc file in the Yocto Project
+ meta-yocto/conf/distro/include directory.
+
+
+
+ The project also has contribution repositories known as “contrib” areas.
+ These areas temporarily hold changes to the project that have been submitted or committed
+ by the Yocto Project development team and by community members that contribute to the project.
+ The maintainer determines if the changes are qualified to be moved from the "contrib" areas
+ into the "master" branch of the Git repository.
+
+
+
+ Developers (including contributing community members) create and maintain cloned repositories
+ of the upstream "master" branch.
+ These repositories are local to their development platforms and are used to develop changes.
+ When a developer is satisfied with a particular feature or change, they “push” the changes
+ to the appropriate "contrib" repository.
+
+
+
+ Developers are responsible for keeping their local repository up-to-date with "master".
+ They are also responsible for straightening out any conflicts that might arise within files
+ that are being worked on simultaneously by more than one person.
+ All this work is done locally on the developer’s machine before anything is pushed to a
+ "contrib" area and examined at the maintainer’s level.
+
+
+
+ A somewhat formal method exists by which developers commit changes and push them into the
+ "contrib" area and subsequently request that the maintainer include them into "master"
+ This process is called “submitting a patch” or “submitting a change.”
+ For information on submitting patches and changes, see the
+ "How to Submit a Change" section.
+
+
+
+ To summarize the environment: we have a single point of entry for changes into the project’s
+ "master" branch of the Git repository, which is controlled by the project’s maintainer.
+ And, we have a set of developers who independently develop, test, and submit changes
+ to "contrib" areas for the maintainer to examine.
+ The maintainer then chooses which changes are going to become a permanent part of the project.
+
+
+
+
+
+
+
+ While each development environment is unique, there are some best practices or methods
+ that help development run smoothly.
+ The following list describes some of these practices.
+ For more information about Git workflows, see the workflow topics in the
+ Git Community Book.
+
+ Make Small Changes: It is best to keep the changes you commit
+ small as compared to bundling many disparate changes into a single commit.
+ This practice not only keeps things manageable but also allows the maintainer
+ to more easily include or refuse changes.
+ It is also good practice to leave the repository in a state that allows you to
+ still successfully build your project. In other words, do not commit half of a feature,
+ then add the other half in a separate, later commit.
+ Each commit should take you from one buildable project state to another
+ buildable state.
+ Use Branches Liberally: It is very easy to create, use, and
+ delete local branches in your working Git repository.
+ You can name these branches anything you like.
+ It is helpful to give them names associated with the particular feature or change
+ on which you are working.
+ Once you are done with a feature or change, simply discard the branch.
+ Merge Changes: The git merge
+ command allows you to take the
+ changes from one branch and fold them into another branch.
+ This process is especially helpful when more than a single developer might be working
+ on different parts of the same feature.
+ Merging changes also automatically identifies any collisions or “conflicts”
+ that might happen as a result of the same lines of code being altered by two different
+ developers.
+ Manage Branches: Because branches are easy to use, you should
+ use a system where branches indicate varying levels of code readiness.
+ For example, you can have a “work” branch to develop in, a “test” branch where the code or
+ change is tested, a “stage” branch where changes are ready to be committed, and so forth.
+ As your project develops, you can merge code across the branches to reflect ever-increasing
+ stable states of the development.
+ Use Push and Pull: The push-pull workflow is based on the
+ concept of developers “pushing” local commits to a remote repository, which is
+ usually a contribution repository.
+ This workflow is also based on developers “pulling” known states of the project down into their
+ local development repositories.
+ The workflow easily allows you to pull changes submitted by other developers from the
+ upstream repository into your work area ensuring that you have the most recent software
+ on which to develop.
+ The Yocto Project has two scripts named create-pull-request and
+ send-pull-request that ship with the release to facilitate this
+ workflow.
+ You can find these scripts in the local Yocto Project files Git repository in
+ the scripts directory.
+ You can find more information on these scripts in the
+ "Using
+ Scripts to Push a Change Upstream and Request a Pull" section.
+
+ Patch Workflow: This workflow allows you to notify the
+ maintainer through an email that you have a change (or patch) you would like considered
+ for the "master" branch of the Git repository.
+ To send this type of change you format the patch and then send the email using the Git commands
+ git format-patch and git send-email.
+ You can find information on how to submit changes
+ later in this chapter.
+
+
+
+
+
+ Tracking Bugs
+
+
+ The Yocto Project uses its own implementation of
+ Bugzilla to track bugs.
+ Implementations of Bugzilla work well for group development because they track bugs and code
+ changes, can be used to communicate changes and problems with developers, can be used to
+ submit and review patches, and can be used to manage quality assurance.
+ The home page for the Yocto Project implementation of Bugzilla is
+ &YOCTO_BUGZILLA_URL;.
+
+
+
+ Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself
+ such as when discovering an issue with some component of the build system that acts contrary
+ to the documentation or your expectations.
+ Following is the general procedure for submitting a new bug using the Yocto Project
+ Bugzilla.
+ You can find more information on defect management, bug tracking, and feature request
+ processes all accomplished through the Yocto Project Bugzilla on the wiki page
+ here.
+
+ Always use the Yocto Project implementation of Bugzilla to submit
+ a bug.
+ When submitting a new bug, be sure to choose the appropriate
+ Classification, Product, and Component for which the issue was found.
+ Defects for Yocto Project fall into one of six classifications: Yocto Project
+ Components, Infrastructure, Build System & Metadata, Documentation,
+ QA/Testing, and Runtime.
+ Each of these Classifications break down into multiple Products and, in some
+ cases, multiple Components.
+ Use the bug form to choose the correct Hardware and Architecture
+ for which the bug applies.
+ Indicate the Yocto Project version you were using when the issue
+ occurred.
+ Be sure to indicate the Severity of the bug.
+ Severity communicates how the bug impacted your work.
+ Provide a brief summary of the issue.
+ Try to limit your summary to just a line or two and be sure to capture the
+ essence of the issue.
+ Provide a detailed description of the issue.
+ You should provide as much detail as you can about the context, behavior, output,
+ and so forth that surround the issue.
+ You can even attach supporting files for output or log by using the "Add an attachment"
+ button.
+ Submit the bug by clicking the "Submit Bug" button.
+
+
+
+
+
+ How to Submit a Change
+
+
+ Contributions to the Yocto Project and OpenEmbedded are very welcome.
+ Because the system is extremely configurable and flexible, we recognize that developers
+ will want to extend, configure or optimize it for their specific uses.
+ You should send patches to the appropriate mailing list so that they
+ can be reviewed and merged by the appropriate maintainer.
+ For a list of the Yocto Project and related mailing lists, see the
+ "Mailing lists" section in
+ the Yocto Project Reference Manual.
+
+
+
+ The following is some guidance on which mailing list to use for what type of change:
+
+ For changes to the core metadata, send your patch to the
+ openembedded-core mailing list.
+ For example, a change to anything under the meta or
+ scripts directories
+ should be sent to this mailing list.
+ For changes to BitBake (anything under the bitbake
+ directory), send your patch to the
+ bitbake-devel mailing list.
+ For changes to meta-yocto, send your patch to the
+ poky mailing list.
+ For changes to other layers hosted on
+ yoctoproject.org (unless the
+ layer's documentation specifies otherwise), tools, and Yocto Project
+ documentation, use the
+ yocto mailing list.
+ For additional recipes that do not fit into the core metadata,
+ you should determine which layer the recipe should go into and submit the
+ change in the manner recommended by the documentation (e.g. README) supplied
+ with the layer. If in doubt, please ask on the
+ yocto or
+ openembedded-devel
+ mailing lists.
+
+
+
+
+ When you send a patch, be sure to include a "Signed-off-by:"
+ line in the same style as required by the Linux kernel.
+ Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1
+ as follows:
+
+ Developer's Certificate of Origin 1.1
+
+ By making a contribution to this project, I certify that:
+
+ (a) The contribution was created in whole or in part by me and I
+ have the right to submit it under the open source license
+ indicated in the file; or
+
+ (b) The contribution is based upon previous work that, to the best
+ of my knowledge, is covered under an appropriate open source
+ license and I have the right under that license to submit that
+ work with modifications, whether created in whole or in part
+ by me, under the same open source license (unless I am
+ permitted to submit under a different license), as indicated
+ in the file; or
+
+ (c) The contribution was provided directly to me by some other
+ person who certified (a), (b) or (c) and I have not modified
+ it.
+
+ (d) I understand and agree that this project and the contribution
+ are public and that a record of the contribution (including all
+ personal information I submit with it, including my sign-off) is
+ maintained indefinitely and may be redistributed consistent with
+ this project or the open source license(s) involved.
+
+
+
+
+ In a collaborative environment, it is necessary to have some sort of standard
+ or method through which you submit changes.
+ Otherwise, things could get quite chaotic.
+ One general practice to follow is to make small, controlled changes.
+ Keeping changes small and isolated aids review, makes merging/rebasing easier
+ and keeps the change history clean when anyone needs to refer to it in future.
+
+
+
+ When you make a commit, you must follow certain standards established by the
+ OpenEmbedded and Yocto Project development teams.
+ For each commit, you must provide a single-line summary of the change and you
+ should almost always provide a more detailed description of what you did (i.e.
+ the body of the commit message).
+ The only exceptions for not providing a detailed description would be if your
+ change is a simple, self-explanatory change that needs no further description
+ beyond the summary.
+ Here are the guidelines for composing a commit message:
+
+ Provide a single-line, short summary of the change.
+ This summary is typically viewable in the "shortlist" of changes.
+ Thus, providing something short and descriptive that gives the reader
+ a summary of the change is useful when viewing a list of many commits.
+ This should be prefixed by the recipe name (if changing a recipe), or
+ else the short form path to the file being changed.
+
+ For the body of the commit message, provide detailed information
+ that describes what you changed, why you made the change, and the approach
+ you used. It may also be helpful if you mention how you tested the change.
+ Provide as much detail as you can in the body of the commit message.
+
+ If the change addresses a specific bug or issue that is
+ associated with a bug-tracking ID, include a reference to that ID in
+ your detailed description.
+ For example, the Yocto Project uses a specific convention for bug
+ references - any commit that addresses a specific bug should include the
+ bug ID in the description (typically at the beginning) as follows:
+
+ [YOCTO #<bug-id>]
+
+ <detailed description of change>
+
+ Where <bug-id> is replaced with the specific bug ID from the
+ Yocto Project Bugzilla instance.
+
+
+
+
+ You can find more guidance on creating well-formed commit messages at this OpenEmbedded
+ wiki page:
+ .
+
+
+
+ Following are general instructions for both pushing changes upstream and for submitting
+ changes as patches.
+
+
+
+ Using Scripts to Push a Change Upstream and Request a Pull
+
+
+ The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
+
+ Make your changes in your local Git repository.
+ Stage your changes by using the git add
+ command on each file you changed.
+ Commit the change by using the git commit
+ command and push it to the "contrib" repository.
+ Be sure to provide a commit message that follows the project’s commit message standards
+ as described earlier.
+ Notify the maintainer that you have pushed a change by making a pull
+ request.
+ The Yocto Project provides two scripts that conveniently let you generate and send
+ pull requests to the Yocto Project.
+ These scripts are create-pull-request and
+ send-pull-request.
+ You can find these scripts in the scripts directory
+ within the Source Directory.
+ Using these scripts correctly formats the requests without introducing any
+ whitespace or HTML formatting.
+ The maintainer that receives your patches needs to be able to save and apply them
+ directly from your emails.
+ Using these scripts is the preferred method for sending patches.
+ For help on using these scripts, simply provide the
+ -h argument as follows:
+
+ $ ~/poky/scripts/create-pull-request -h
+ $ ~/poky/scripts/send-pull-request -h
+
+
+
+
+
+ You can find general Git information on how to push a change upstream in the
+ Git Community Book.
+
+
+
+
+ Using Email to Submit a Patch
+
+
+ You can submit patches without using the create-pull-request and
+ send-pull-request scripts described in the previous section.
+ Keep in mind, the preferred method is to use the scripts, however.
+
+
+
+ Depending on the components changed, you need to submit the email to a specific
+ mailing list.
+ For some guidance on which mailing list to use, see the list in the
+ "How to Submit a Change" section
+ earlier in this manual.
+ For a description of the available mailing lists, see
+ "Mailing Lists"
+ section in the Yocto Project Reference Manual.
+
+
+
+ Here is the general procedure on how to submit a patch through email without using the
+ scripts:
+
+ Make your changes in your local Git repository.
+ Stage your changes by using the git add
+ command on each file you changed.
+ Commit the change by using the
+ git commit --signoff command.
+ Using the --signoff option identifies you as the person
+ making the change and also satisfies the Developer's Certificate of
+ Origin (DCO) shown earlier.
+ When you form a commit you must follow certain standards established by the
+ Yocto Project development team.
+ See the earlier section
+ "How to Submit a Change"
+ for Yocto Project commit message standards.
+ Format the commit into an email message.
+ To format commits, use the git format-patch command.
+ When you provide the command, you must include a revision list or a number of patches
+ as part of the command.
+ For example, these two commands each take the most recent single commit and
+ format it as an email message in the current directory:
+
+ $ git format-patch -1
+ $ git format-patch HEAD~
+
+ After the command is run, the current directory contains a
+ numbered .patch file for the commit.
+ If you provide several commits as part of the command,
+ the git format-patch command produces a numbered
+ series of files in the current directory – one for each commit.
+ If you have more than one patch, you should also use the
+ --cover option with the command, which generates a
+ cover letter as the first "patch" in the series.
+ You can then edit the cover letter to provide a description for
+ the series of patches.
+ For information on the git format-patch command,
+ see GIT_FORMAT_PATCH(1) displayed using the
+ man git-format-patch command.
+ If you are or will be a frequent contributor to the Yocto Project
+ or to OpenEmbedded, you might consider requesting a contrib area and the
+ necessary associated rights.
+ Import the files into your mail client by using the
+ git send-email command.
+ In order to use git send-email, you must have the
+ the proper Git packages installed.
+ For Ubuntu and Fedora the package is git-email.
+ The git send-email command sends email by using a local
+ or remote Mail Transport Agent (MTA) such as
+ msmtp, sendmail, or through a direct
+ smtp configuration in your Git config
+ file.
+ If you are submitting patches through email only, it is very important
+ that you submit them without any whitespace or HTML formatting that
+ either you or your mailer introduces.
+ The maintainer that receives your patches needs to be able to save and
+ apply them directly from your emails.
+ A good way to verify that what you are sending will be applicable by the
+ maintainer is to do a dry run and send them to yourself and then
+ save and apply them as the maintainer would.
+ The git send-email command is the preferred method
+ for sending your patches since there is no risk of compromising whitespace
+ in the body of the message, which can occur when you use your own mail client.
+ The command also has several options that let you
+ specify recipients and perform further editing of the email message.
+ For information on how to use the git send-email command,
+ use the man git-send-email command.
+
+
+
+
+
+
diff --git a/documentation/profile-manual/profile-manual.xml b/documentation/profile-manual/profile-manual.xml
new file mode 100644
index 0000000000..5eea2e22aa
--- /dev/null
+++ b/documentation/profile-manual/profile-manual.xml
@@ -0,0 +1,91 @@
+ %poky; ] >
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ScottRifenbark
+
+ Intel Corporation
+
+ scott.m.rifenbark@intel.com
+
+
+
+
+
+ 1.1
+ 6 October 2011
+ The initial document released with the Yocto Project 1.1 Release.
+
+
+ 1.2
+ April 2012
+ Released with the Yocto Project 1.2 Release.
+
+
+ 1.3
+ October 2012
+ Released with the Yocto Project 1.3 Release.
+
+
+ 1.4
+ Sometime in 2013
+ Released with the Yocto Project 1.4 Release.
+
+
+
+
+ ©RIGHT_YEAR;
+ Linux Foundation
+
+
+
+
+ Permission is granted to copy, distribute and/or modify this document under
+ the terms of the
+ Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by
+ Creative Commons.
+
+
+
+ Due to production processes, there could be differences between the Yocto Project
+ documentation bundled in the release tarball and the
+ Yocto Project Development Manual on
+ the Yocto Project website.
+ For the latest version of this manual, see the manual on the website.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+