From 1e789e60b5bffc2947e421129fc2ad8ea543874d Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 16 Aug 2011 09:17:55 -0700 Subject: [PATCH] documentation/dev-manual: Incorporated Joshua Lock's review comments. (From yocto-docs rev: d4bf6343d7575ff96030242e2025570db52b515b) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-model.xml | 4 +- .../dev-manual/dev-manual-newbie.xml | 55 +++++++++++-------- documentation/dev-manual/dev-manual-start.xml | 30 +++++----- 3 files changed, 52 insertions(+), 37 deletions(-) diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index c6662d3199..2dfc46e740 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -170,8 +170,8 @@ - You can view a video presentation of the BSP creation process - here. + 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. diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index ad5f3c9ecf..fbb9d5faef 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -82,7 +82,7 @@ For any supported release of Yocto Project you can go to the Yocto Project website’s download page and get a - .bz2 tarball of the release. + tarball of the release. You can also go to this site to download any supported BSP tarballs. Unpacking the tarball gives you a hierarchical directory structure of Yocto Project files that lets you develop using the Yocto Project. @@ -133,50 +133,57 @@ Some terms are universal but are included here just in case: Image - An image is a collection of recipes created - with BitBake (baked) and made part of a root filesystem. + with BitBake (baked) and made part of a root filesystem. + Images are both the binary output that runs on specific hardware and for specific + use cases as well as a metadata recipe that BitBake processes to generate the + binary output. 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 also let you customize how software is installed into images. - Recipes contain the logical unit of execution, the software/images to build and + Recipes contain the logical unit of execution, the software/images to build, and use the .bb file extension. BitBake - The task executor and scheduler used by Yocto Project to build images. For more information on BitBake, see the BitBake documentation. - Package - The output from a baked recipe. + Package - 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. - Layer - A logical collection of recipes representing the core, + Layer - A collection of recipes representing the core, a BSP, or an application stack. - Metadata - Information for a build that is generally - architecture-independent. - This information includes Task definitions in recipes, classes, and configuration - information. + Metadata - A term used throughout the Yocto Project + documentation that refers to the files that BitBake parses when building an image. + Metadata includes recipes, classes, and configuration files. Configuration File: Configuration information in the .conf files provides global definitions of variables. - The build/conf/local.conf configuration file defines local user-defined variables. + The build/conf/local.conf configuration file defines user-defined variables + that effect each build. The distro/poky.conf configuration file defines Yocto ‘distro’ configuration - variables. - The machine/beagleboard.conf configuration file defines machine-specific variables - (i.e. Texas Instruments ARM Cortex-A8 development board in this example. + variables used only when building with this policy. + The machine/beagleboard.conf configuration file defines variables + for the Beagleboard and are only used when building for that target + (i.e. Texas Instruments ARM Cortex-A8 development board). Configuration files end with a .conf filename extension. - Classes - Files that encapsulate and inherit logic. + Classes - Files that provide for logic encapsulation + and inheritance allowing commonly used pattrerns to be defined once and easily used + in multiple recipes. Class files end with the .bbclass filename extension. Append Files - Files that append build information to a recipe file. Information in append files override the information in the similarly-named recipe file. Append files use the .bbappend filename suffix. - Tasks - Arbitrary groups of software used to contain Recipes. - You simply use Tasks to hold recipes that when build usually accomplished a single task. + 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. OE-Core - A core set of metadata originating - with OpenEmbedded (OE) that is shared between OE and the Yocto Project. + with OpenEmbedded (OE) that is shared between OE and the Yocto Project. + This metadata is found in the meta directory of the Yocto Project + files. 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. @@ -223,7 +230,9 @@ <build_directory>/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. - It is up to the developer to resolve potential licensing issues. + These tools make it easier for a developer to be certain of the licenses with which + their shipped products must comply. + However, it is still up to the developer to resolve potential licensing issues. @@ -470,8 +479,10 @@ - Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself. - While normally this is a process relevant only to Yocto Project developers, you can find information + 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 expectations. + You can find information for Bugzilla configuration and bug tracking procedures specific to the Yocto Project here. @@ -487,7 +498,7 @@ Here are some things to remember when dealing with bugs against the Yocto Project: The Yocto Project follows a naming bug-naming convention: - [YOCTO <number>], where <number> is the + [YOCTO #<number>], where <number> is the assigned defect ID used in Bugzilla. So, for example, a valid way to refer to a defect when creating a commit comment would be [YOCTO 1011]. diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml index 48f98b50b5..07caed3132 100644 --- a/documentation/dev-manual/dev-manual-start.xml +++ b/documentation/dev-manual/dev-manual-start.xml @@ -24,15 +24,16 @@ The Yocto Project is an open-source collaboration project focused on embedded Linux development. - The project provides a recent Linux kernel along with a set of system commands, libraries, - and system components suitable for the embedded developer. - The Yocto Project also features the Sato reference User Interface should you be dealing with - devices with restricted screens. + The project currently provides a build system and various ancillary tools suitable for the + embedded developer. + The Yocto Project also features the Sato reference User Interface, which is optimized for + stylus driven, low-resolution screens. You can use the Yocto Project, which uses the BitBake build tool, to develop complete Linux - images and user-space applications for architectures based on ARM, MIPS, PowerPC, x86 and x86-64. + images and associated user-space applications for architectures based on ARM, MIPS, PowerPC, + x86 and x86-64. You can perform target-level testing and debugging as well as test in a hardware emulated environment. And, if you are an Eclipse user, you can install an Eclipse Yocto Plug-in to allow you to develop within that familiar environment. @@ -45,16 +46,18 @@ Here is what you need to get set up to use the Yocto Project: - Host System: You need a recent release of Fedora, - OpenSUSE, Debian, or Ubuntu. - You should have a reasonably current Linux-based host system. + 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, or Ubuntu as these releases are frequently tested and officially supported + host systems. You should also have about 100 gigabytes of free disk space for building images. Packages: The Yocto Project requires certain packages - exist on your development system. - See the + 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. + requirements and the installation commands for the supported distributions. Yocto Project Release: You need a release of the Yocto Project. You can get set up with local Yocto Project files one of two ways depending on whether you @@ -210,7 +213,8 @@ wiki page referenced earlier covers how to set up the meta-intel Git repository. - Eclipse Yocto Plug-in: If you are developing using the + Eclipse Yocto Plug-in: If you are developing + applications using the Eclipse Integrated Development Environment (IDE) you will need this plug-in. See the @@ -237,7 +241,7 @@ previous section. Initialize the build environment by sourcing a build environment script. - Make sure the conf/local.conf configuration file is set + Optionally ensure the conf/local.conf configuration file is set up how you want it. This file defines the target machine architecture and and other build options. Build the image using the BitBake command.