From 14b00ff23a912494edc7f146e668c40ca82b8508 Mon Sep 17 00:00:00 2001 From: Adrian Dudau Date: Thu, 12 Dec 2013 13:46:05 +0100 Subject: initial commit of Enea Linux 3.1 Migrated from the internal git server on the dora-enea branch Signed-off-by: Adrian Dudau --- documentation/dev-manual/dev-manual-start.xml | 445 ++++++++++++++++++++++++++ 1 file changed, 445 insertions(+) create mode 100644 documentation/dev-manual/dev-manual-start.xml (limited to 'documentation/dev-manual/dev-manual-start.xml') diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml new file mode 100644 index 0000000..c1d89bc --- /dev/null +++ b/documentation/dev-manual/dev-manual-start.xml @@ -0,0 +1,445 @@ + %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 that is + referred to as the OpenEmbedded build system in the Yocto Project documentation. + The Yocto Project provides various ancillary tools 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. + + By default, using the Yocto Project creates a Poky distribution. + However, you can create your own distribution by providing key + Metadata. + See the "Creating Your Own Distribution" + section for more information. + + 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 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 that 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 and the + "Required Packages for the Host Development System" + section in the Yocto Project Reference Manual 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 installed locally on + your development system. + This local area is referred to as the + Source Directory + and is created when you use + Git to clone a local copy + of the upstream poky repository, + or when you download an official release of the corresponding + tarball. + Working from a copy of the upstream repository allows you + to contribute back into the Yocto Project or simply work with + the latest software on a development branch. + Because Git maintains and creates an upstream repository with + a complete history of changes and you are working with a local + clone of that repository, you have access to all the Yocto + Project development branches and tag names used in the upstream + repository. + You can view the Yocto Project Source Repositories at + + + + Tarball Extraction: + If you are not going to contribute back into the Yocto + Project, you can simply go to the + Yocto Project Website, + select the "Downloads" tab, and choose what you want. + 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 clone the repository, you have access to all + the Yocto Project development branches and tag names + used in the upstream repository. + You can view the Yocto Project Source Repositories + at + + + The following transcript shows how to clone the + poky Git repository into the + current working directory. + 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 + Cloning into 'poky'... + remote: Counting objects: 203728, done. + remote: Compressing objects: 100% (52371/52371), done. + remote: Total 203728 (delta 147444), reused 202891 (delta 146614) + Receiving objects: 100% (203728/203728), 95.54 MiB | 308 KiB/s, done. + Resolving deltas: 100% (147444/147444), 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.10 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.10.git, while the + copy is named my-linux-yocto-3.10-work: + + $ git clone ‐‐bare git://git.yoctoproject.org/linux-yocto-3.10 linux-yocto-3.10.git + Cloning into bare repository 'linux-yocto-3.10.git'... + remote: Counting objects: 3364487, done. + remote: Compressing objects: 100% (507178/507178), done. + remote: Total 3364487 (delta 2827715), reused 3364481 (delta 2827709) + Receiving objects: 100% (3364487/3364487), 722.95 MiB | 423 KiB/s, done. + Resolving deltas: 100% (2827715/2827715), done. + + Now create a clone of the bare clone just created: + + $ git clone linux-yocto-3.10.git my-linux-yocto-3.10-work + Cloning into 'my-linux-yocto-3.10-work'... + done. + + + The meta-yocto-kernel-extras Git Repository: + The meta-yocto-kernel-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 meta-yocto-kernel-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 meta-yocto-kernel-extras Git + repository inside the Source Directory, which is named poky + in this case: + + $ cd ~/poky + $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras + Cloning into 'meta-yocto-kernel-extras'... + remote: Counting objects: 727, done. + remote: Compressing objects: 100% (452/452), done. + remote: Total 727 (delta 260), reused 719 (delta 252) + Receiving objects: 100% (727/727), 536.36 KiB | 102 KiB/s, done. + Resolving deltas: 100% (260/260), 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 + "Downloads" page of the Yocto Project + Website + to get the Yocto Project release. + Once on the "Download" page, look to the right of the + page and scroll down to find the BSP tarballs. + 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 + . + Using + Git to create a local clone + of the upstream repository can be helpful if you are + working with BSPs. + Typically, you set up the + meta-intel Git repository inside + the Source Directory. + For example, the following transcript shows the steps + to clone meta-intel. + + $ cd ~/poky + $ git clone git://git.yoctoproject.org/meta-intel.git + Cloning into 'meta-intel'... + remote: Counting objects: 7366, done. + remote: Compressing objects: 100% (2491/2491), done. + remote: Total 7366 (delta 3997), reused 7299 (delta 3930) + Receiving objects: 100% (7366/7366), 2.31 MiB | 95 KiB/s, done. + Resolving deltas: 100% (3997/3997), 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 included 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 file systems 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, + 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. + + +
+ + -- cgit v1.2.3-54-g00ecf