From 72d01bf43da4d6761ee1b5997307c64152ec3517 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 7 Dec 2012 17:23:56 -0600 Subject: documentation: dev-manual - Removed all trailing whitespace. (From yocto-docs rev: d117584a589460412a7fc4df15512b0d9c9448c7) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-start.xml | 238 +++++++++++++------------- 1 file changed, 119 insertions(+), 119 deletions(-) (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 index 11d4adca9f..299a02d581 100644 --- a/documentation/dev-manual/dev-manual-start.xml +++ b/documentation/dev-manual/dev-manual-start.xml @@ -7,14 +7,14 @@ 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 + 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 + 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. @@ -22,24 +22,24 @@ 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 + 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 + 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. + 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. + 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 + IDE user, you can install an Eclipse Yocto Plug-in to allow you to develop within that familiar environment. @@ -50,59 +50,59 @@ Here is what you need to get set up to use the Yocto Project: - Host System: You should have a reasonably current + Host System: You should have a reasonably current Linux-based host system. - You will have the best results with a recent release of Fedora, + You will have the best results with a recent release of Fedora, OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project - and officially supported. + 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 + 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" + 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 + requirements and the installation commands to install them for the supported distributions. - Yocto Project Release: - You need a release of the Yocto Project. + Yocto Project Release: + You need a release of the Yocto Project. You set up a with local Source Directory - one of two ways depending on whether you + 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 + 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 + 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. + 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 + 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 + 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. @@ -120,27 +120,27 @@ 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 + 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 + 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 + 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 + 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 + 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: + 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/ @@ -158,20 +158,20 @@ The poky-extras Git Repository: - The poky-extras Git repository contains metadata needed + 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 + 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 + 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 + 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 + Following is an example that creates the poky-extras Git + repository inside the Source Directory, which is named poky in this case: $ cd ~/poky @@ -183,21 +183,21 @@ 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 + 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 + The meta-intel layer contains many supported BSP Layers. Similar considerations exist for setting up the meta-intel - layer. + 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 + Regardless of the method you use, the Yocto Project uses the following BSP layer naming scheme: - - meta-<BSP_name> + + meta-<BSP_name> where <BSP_name> is the recognized BSP name. Here are some examples: @@ -211,22 +211,22 @@ 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. + 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 + 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 + 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 + For example, the following transcript shows the steps to clone the meta-intel Git repository inside the local poky Git repository. @@ -239,15 +239,15 @@ Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done. Resolving deltas: 100% (1689/1689), done. - The same + The same - wiki page referenced earlier covers how to + wiki page referenced earlier covers how to set up the meta-intel Git repository. - Eclipse Yocto Plug-in: If you are developing + Eclipse Yocto Plug-in: If you are developing applications using the Eclipse Integrated Development Environment (IDE), - you will need this plug-in. - See the + you will need this plug-in. + See the "Setting up the Eclipse IDE" section for more information. @@ -258,8 +258,8 @@ Building Images - The build process creates an entire Linux distribution, including the toolchain, from source. - For more information on this topic, see the + 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. @@ -267,27 +267,27 @@ The build process is as follows: - Make sure you have set up the Source Directory described in the + Make sure you have set up the Source Directory described in the previous section. - Initialize the build environment by sourcing a build environment + 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 + 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 + 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 + 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 + Run the image either on the actual hardware or using the QEMU emulator. @@ -297,8 +297,8 @@ 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. + 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 @@ -306,51 +306,51 @@ - 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 + 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 + 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. + 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 + You can find details on all these steps in the "Using Pre-Built Binaries and QEMU" - section of the Yocto Project Quick Start. + 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 + 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. + 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. + 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 + 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 + 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, @@ -358,27 +358,27 @@ - Several mechanisms exist that let you connect to the system running on the + Several mechanisms exist that let you connect to the system running on the QEMU emulator: - QEMU provides a framebuffer interface that makes standard + 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. + 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 + 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 + 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 + Including these SSH servers allow you to use standard ssh and scp commands. - The core-image-minimal QEMU image, however, contains no ssh + 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 + 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 + 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