From dd72756230788dcd88ab14ab32757dd427d67e78 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 17 Mar 2014 14:36:17 -0600 Subject: dev-manual: Read-through edits to Chapter 3. The changes are a result of a detailed read-through prior to releasing YP 1.6. The changes are varied and random. (From yocto-docs rev: 04c09abf96a04c3ffeea8cdf7be8e1bb1b9055c6) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-newbie.xml | 263 +++++++++++++++---------- 1 file changed, 159 insertions(+), 104 deletions(-) (limited to 'documentation/dev-manual/dev-manual-newbie.xml') diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index eab563f3d0..77c14a6611 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -171,7 +171,7 @@ pool similarly to how the developer workstations contribute. For information, see the - Autobuilders + "Autobuilders" section. Build stand-alone tarballs that contain "missing" system requirements if for some reason @@ -184,8 +184,8 @@ on most distributions. Use a small number of shared, high performance systems for testing purposes - (e.g. dual six core Xeons with 24GB RAM and plenty of - disk space). + (e.g. dual, six-core Xeons with 24 Gbytes of RAM + and plenty of disk space). Developers can use these systems for wider, more extensive testing while they continue to develop locally using their primary development system. @@ -222,10 +222,8 @@ allows you to work remotely, and then connects back to the infrastructure. - For information about BitBake and SCMs, see the - BitBake manual located in the - bitbake/doc/manual directory of the - Source Directory. + For information about BitBake, see the + BitBake User Manual. @@ -238,7 +236,7 @@ being used to generate the web interface that lets you view the repositories. The gitolite software identifies users - using ssh keys and allows branch-based + using SSH keys and allows branch-based access controls to repositories that you can control as little or as much as necessary. @@ -298,8 +296,8 @@ Allows triggering of automated image booting and testing under the QuickEMUlator (QEMU). - Supports incremental build testing and from - scratch builds. + Supports incremental build testing and + from-scratch builds. Shares output that allows developer testing and historical regression investigation. @@ -365,14 +363,18 @@ See the "Understanding and Creating Layers" section for more information on layers. - Separate the project's Metadata and code by using + + 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. + 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 local Git + repositories for related upstream Yocto Project + Git repositories. + Set up the directory for the shared state cache (SSTATE_DIR) where it makes sense. @@ -389,7 +391,7 @@ See the "How to Submit a Change" section. Send changes to the core sooner than later - as others likely run into the same issues. + as others are likely to run into the same issues. For some guidance on mailing lists to use, see the list in the "How to Submit a Change" section. @@ -415,7 +417,9 @@ 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 clone a Git repository for that particular item. - Having a local Git repository of the Source Directory (poky) allows + Having a local Git repository of the + Source Directory, which is + usually named "poky", allows you to make changes, contribute to the history, and ultimately enhance the Yocto Project's tools, Board Support Packages, and so forth. @@ -447,9 +451,9 @@ Index of /releases: - This area contains index releases such as + This is an index of releases such as the Eclipse - Yocto Plug-in, miscellaneous support, poky, pseudo, installers for cross-development toolchains, + 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. @@ -494,11 +498,11 @@ "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. + The task executor and scheduler used by the OpenEmbedded build + system to build images. + For more information on BitBake, see the + BitBake User Manual. + Build Directory: This term refers to the area used by the OpenEmbedded build system for builds. @@ -533,8 +537,9 @@ $ cd $HOME $ source poky/&OE_INIT_FILE; test-builds - Provide a directory path and - specifically name the build directory. + + Provide a directory path and + specifically name the Build Directory. Any intermediate folders in the pathname must exist. This next example creates a Build Directory named @@ -557,23 +562,31 @@ Classes: Files that provide for logic encapsulation and inheritance so that commonly used patterns can be defined once and then easily used in multiple recipes. + For reference information on the Yocto Project classes, see the + "Classes" chapter of the + Yocto Project Reference Manual. 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 + 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 + contains user-defined variables that affect every 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. + 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: @@ -611,10 +624,11 @@ Yocto Project Application Developer's Guide. - 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. + 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 are used 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. @@ -640,9 +654,12 @@ 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. + Package: + In the context of the Yocto Project, this term refers a + recipe's packaged output produced by BitBake (i.e. 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 referred to in the @@ -673,24 +690,35 @@ 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. + 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. + 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 + to build, the images to build, and use the + .bb file extension. + Source Directory: This term refers to the directory structure created as a result of creating a local copy of the poky Git repository git://git.yoctoproject.org/poky or expanding a released poky tarball. + + Creating a local copy of the poky + Git repository is the recommended method for setting up + your Source Directory. + Sometimes you might hear the term "poky directory" used to refer to this directory structure. @@ -708,12 +736,12 @@ When you create a local copy of the Git repository, you can name the repository anything you like. - Throughout much of the documentation, poky + 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. + folder is also named "poky". While it is not recommended that you use tarball expansion to setup the Source Directory, if you do, the top-level @@ -815,18 +843,23 @@ 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. + Definition and the effort for reviewing and approving licenses that + conform to the Open Source Definition (OSD). - You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses - here. + You can find a list of the combined SPDX and OSI licenses that the + Yocto Project uses in the + meta/files/common-licenses directory in your + Source Directory. - 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. + For information that can help you 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. @@ -889,12 +922,14 @@ - It is important to understand that Git tracks content change and not files. + 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 denzil, danny, dylan, dora, - and master branches among others. + daisy, and master branches + among others. You can see all the branches by going to and clicking on the @@ -928,37 +963,38 @@ In this example, the name of the top-level directory of your local Source Directory - is poky, - and the name of that local working area (local branch) you just - created and checked out is &DISTRO_NAME;. + is "poky" and the name of that local working area (local branch) + you just created and checked out is "&DISTRO_NAME;". The files in your local repository now reflect the same files that - are in the &DISTRO_NAME; development - branch of the Yocto Project's poky - upstream repository. + are in the "&DISTRO_NAME;" development branch of the + Yocto Project's "poky" upstream 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 from 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. + 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 + 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, + Some key tags are dylan-9.0.0, + dora-10.0.0, and &DISTRO_NAME;-&POKYVERSION;. These tags represent Yocto Project releases. @@ -1007,7 +1043,7 @@ - If you don’t know much about Git, you should educate + If you do not know much about Git, you should educate yourself by visiting the links previously mentioned. @@ -1019,9 +1055,12 @@ 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 clone: + Creates a local clone of a Git repository. + During collaboration, this command allows you to create a + local Git repository that is on equal footing with a fellow + developer’s Git repository. + git add: Stages updated file contents to the index that Git uses to track changes. @@ -1111,11 +1150,18 @@ - 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. + The project also has an upstream contribution Git repository named + poky-contrib. + You can see all the branches in this repository using the web interface + of the + Source Repositories organized + within the "Poky Support" area. + These branches temporarily hold changes to the project that have been + submitted or committed by the Yocto Project development team and by + community members who contribute to the project. + The maintainer determines if the changes are qualified to be moved + from the "contrib" branches into the "master" branch of the Git + repository. @@ -1143,11 +1189,13 @@ - 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. + To summarize the environment: a single point of entry exists for + changes into the project’s "master" branch of the Git repository, + which is controlled by the project’s maintainer. + And, a set of developers exist 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. @@ -1430,19 +1478,20 @@ 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: + + 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 + use the following form for the detailed description: - [YOCTO #<bug-id>] + Fixes [YOCTO #<bug-id>] <detailed description of change> - Where <bug-id> is replaced with the specific bug ID from the - Yocto Project Bugzilla instance. + Where <bug-id> is replaced with the specific bug ID from + the Yocto Project Bugzilla instance. @@ -1466,10 +1515,16 @@ 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. + + Commit the change by using the + git commit command. + Be sure to provide a commit message that follows the + project’s commit message standards as described earlier. + + + Push the change to the upstream "contrib" repository by + using the git push command. + 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 -- cgit v1.2.3-54-g00ecf