From c527fd1f14c27855a37f2e8ac5346ce8d940ced2 Mon Sep 17 00:00:00 2001 From: Tudor Florea Date: Thu, 16 Oct 2014 03:05:19 +0200 Subject: initial commit for Enea Linux 4.0-140929 Migrated from the internal git server on the daisy-enea-point-release branch Signed-off-by: Tudor Florea --- documentation/dev-manual/dev-manual-newbie.xml | 1687 ++++++++++++++++++++++++ 1 file changed, 1687 insertions(+) create mode 100644 documentation/dev-manual/dev-manual-newbie.xml (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 new file mode 100644 index 0000000000..37fa5afdd5 --- /dev/null +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -0,0 +1,1687 @@ + %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, using the + Yocto Project in a team environment, source repositories, Yocto Project + terms, licensing, the open source distributed version control system Git, + workflows, bug tracking, and how to submit changes. + + +
+ 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. + One of the strengths of the Yocto Project is that it is extremely + flexible. + Thus, you can adapt it to many different use cases and scenarios. + However, these characteristics can cause a struggle if you are trying + to create a working setup that scales across a large team. + + + + To help with these types of situations, this section presents + some of the project's most successful experiences, + practices, solutions, and available technologies that work well. + Keep in mind, the information here is a starting point. + You can build off it and customize it to fit any + particular working environment and set of practices. + + +
+ System Configurations + + + Systems across a large team should meet the needs of + two types of developers: those working on the contents of the + operating system image itself and those developing applications. + Regardless of the type of developer, their workstations must + be both reasonably powerful and run Linux. + + +
+ Application Development + + + For developers who mainly do application level work + on top of an existing software stack, + here are some practices that work best: + + Use a pre-built toolchain that + contains the software stack itself. + Then, develop the application code on top of the + stack. + This method works well for small numbers of relatively + isolated applications. + When possible, use the Yocto Project + plug-in for the Eclipse IDE + and other pieces of Application Development + Technology (ADT). + For more information, see the + "Application + Development Workflow" section as well as the + Yocto Project Application Developer's Guide. + + Keep your cross-development toolchains + updated. + You can do this through provisioning either as new + toolchain downloads or as updates through a package + update mechanism using opkg + to provide updates to an existing toolchain. + The exact mechanics of how and when to do this are a + question for local policy. + Use multiple toolchains installed locally + into different locations to allow development across + versions. + + +
+ +
+ Core System Development + + + For core system development, it is often best to have the + build system itself available on the developer workstations + so developers can run their own builds and directly + rebuild the software stack. + You should keep the core system unchanged as much as + possible and do your work in layers on top of the core system. + Doing so gives you a greater level of portability when + upgrading to new versions of the core system or Board + Support Packages (BSPs). + You can share layers amongst the developers of a particular + project and contain the policy configuration that defines + the project. + + + + Aside from the previous best practices, there exists a number + of tips and tricks that can help speed up core development + projects: + + Use a + Shared State Cache + (sstate) among groups of developers who are on a + fast network. + The best way to share sstate is through a + Network File System (NFS) share. + The first user to build a given component for the + first time contributes that object to the sstate, + while subsequent builds from other developers then + reuse the object rather than rebuild it themselves. + + Although it is possible to use other protocols for the + sstate such as HTTP and FTP, you should avoid these. + Using HTTP limits the sstate to read-only and + FTP provides poor performance. + + Have autobuilders contribute to the sstate + pool similarly to how the developer workstations + contribute. + For information, see the + "Autobuilders" + section. + Build stand-alone tarballs that contain + "missing" system requirements if for some reason + developer workstations do not meet minimum system + requirements such as latest Python versions, + chrpath, or other tools. + You can install and relocate the tarball exactly as you + would the usual cross-development toolchain so that + all developers can meet minimum version requirements + on most distributions. + Use a small number of shared, + high performance systems for testing purposes + (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. + + Enable the PR Service when package feeds + need to be incremental with continually increasing + PR + values. + Typically, this situation occurs when you use or + publish package feeds and use a shared state. + You should enable the PR Service for all users who + use the shared state pool. + For more information on the PR Service, see the + "Working With a PR Service". + + + +
+
+ +
+ Source Control Management (SCM) + + + Keeping your + Metadata + and any software you are developing under the + control of an SCM system that is compatible + with the OpenEmbedded build system is advisable. + Of the SCMs BitBake supports, the + Yocto Project team strongly recommends using + Git. + Git is a distributed system that is easy to backup, + allows you to work remotely, and then connects back to the + infrastructure. + + For information about BitBake, see the + BitBake User Manual. + + + + + It is relatively easy to set up Git services and create + infrastructure like + http://git.yoctoproject.org, + which is based on server software called + gitolite with cgit + 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 + access controls to repositories that you can control as little + or as much as necessary. + + + + The setup of these services is beyond the scope of this manual. + However, sites such as these exist that describe how to perform + setup: + + Git documentation: + Describes how to install gitolite + on the server. + The gitolite master index: + All topics for gitolite. + + Interfaces, frontends, and tools: + Documentation on how to create interfaces and frontends + for Git. + + +
+ +
+ Autobuilders + + + Autobuilders are often the core of a development project. + It is here that changes from individual developers are brought + together and centrally tested and subsequent decisions about + releases can be made. + Autobuilders also allow for "continuous integration" style + testing of software components and regression identification + and tracking. + + + + See "Yocto Project Autobuilder" + for more information and links to buildbot. + The Yocto Project team has found this implementation + works well in this role. + A public example of this is the Yocto Project + Autobuilders, which we use to test the overall health of the + project. + + + + The features of this system are: + + Highlights when commits break the build. + + Populates an sstate cache from which + developers can pull rather than requiring local + builds. + Allows commit hook triggers, + which trigger builds when commits are made. + + Allows triggering of automated image booting + and testing under the QuickEMUlator (QEMU). + + Supports incremental build testing and + from-scratch builds. + Shares output that allows developer + testing and historical regression investigation. + + Creates output that can be used for releases. + + Allows scheduling of builds so that resources + can be used efficiently. + + +
+ +
+ Policies and Change Flow + + + The Yocto Project itself uses a hierarchical structure and a + pull model. + Scripts exist to create and send pull requests + (i.e. create-pull-request and + send-pull-request). + This model is in line with other open source projects where + maintainers are responsible for specific areas of the project + and a single maintainer handles the final "top-of-tree" merges. + + + + You can also use a more collective push model. + The gitolite software supports both the + push and pull models quite easily. + + + + As with any development environment, it is important + to document the policy used as well as any main project + guidelines so they are understood by everyone. + It is also a good idea to have well structured + commit messages, which are usually a part of a project's + guidelines. + Good commit messages are essential when looking back in time and + trying to understand why changes were made. + + + + If you discover that changes are needed to the core layer of the + project, it is worth sharing those with the community as soon + as possible. + Chances are if you have discovered the need for changes, someone + else in the community needs them also. + +
+ +
+ Summary + + + This section summarizes the key recommendations described in the + previous sections: + + 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 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. + For example, set up the sstate cache on a system used + by developers in the same organization and share the + same source directories on their machines. + + Set up an Autobuilder and have it populate the + sstate cache and source directories. + The Yocto Project community encourages you + to send patches to the project to fix bugs or add features. + If you do submit patches, follow the project commit + guidelines for writing good commit messages. + See the "How to Submit a Change" + section. + Send changes to the core sooner than later + 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. + For a description of the available mailing lists, see the + "Mailing Lists" + section in the Yocto Project Reference Manual. + + + +
+
+ +
+ 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 clone + a Git repository for that particular item. + 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. + + + + For any supported release of Yocto Project, you can also go to the + Yocto Project Website and + select the "Downloads" tab and get a released tarball of the + poky repository or any supported BSP tarballs. + Unpacking these tarballs gives you a snapshot of the released + files. + Notes + + + The recommended method for setting up the Yocto Project + Source Directory + and the files for supported BSPs + (e.g., meta-intel) is to use + Git to create a local copy of + the upstream repositories. + + + Be sure to always work in matching branches for both + the meta-intel repository and the + Source Directory + (i.e. poky) repository. + For example, if you have checked out the "master" branch + of poky and you are going to use + meta-intel, be sure to checkout the + "master" branch of meta-intel. + + + + + + + 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 is an index of 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. + + + + "Downloads" page for the + Yocto Project Website: + Access this page by going to the website and then selecting + the "Downloads" tab. + This page 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 + recipe (.bb) file. + Furthermore, the append file and corresponding recipe file + must use 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 User Manual. + + + 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; + or + oe-init-build-env-memres). + 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. + The examples assume your + Source Directory is + named poky: + + Create the Build Directory inside your + Source Directory and let the name of the Build + Directory default to build: + + $ cd $HOME/poky + $ source &OE_INIT_FILE; + + Create the Build Directory inside your + home directory and specifically name it + test-builds: + + $ cd $HOME + $ source poky/&OE_INIT_FILE; test-builds + + + 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 + YP-&POKYVERSION; + in your home directory within the existing + directory mybuilds: + + $cd $HOME + $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION; + + + + By default, the Build Directory contains + TMPDIR, + which is a temporary directory the build system uses for + its work. + TMPDIR cannot be under NFS. + Thus, by default, the Build Directory cannot be under NFS. + However, if you need the Build Directory to be under NFS, + you can set this up by setting TMPDIR + in your local.conf file + to use a local drive. + Doing so effectively separates TMPDIR + from TOPDIR, which is the Build + Directory. + + + 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. + + 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 + Build Directory + 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/beaglebone.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: + In general, a cross-development toolchain is a collection of + software development tools and utilities that run on one + architecture and allow you to develop software for a + different, or targeted, architecture. + These toolchains contain cross-compilers, linkers, and + debuggers that are specific to the target architecture. + + + The Yocto Project supports two different cross-development + toolchains: + + A toolchain only used by and within + BitBake when building an image for a target + architecture. + A relocatable toolchain used outside of + BitBake by developers when developing applications + that will run on a targeted device. + Sometimes this relocatable cross-development + toolchain is referred to as the meta-toolchain. + + + + + + Creation of these toolchains is simple and automated. + For information on toolchain concepts as they apply to the + Yocto Project, see the + "Cross-Development Toolchain Generation" + section in the Yocto Project Reference Manual. + You can also find more information on using the + relocatable toolchain in the + 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 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. + 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. + Meta-Toolchain: + A term sometimes used for + Cross-Development Toolchain. + + Metadata: + The files that BitBake parses when building an image. + In general, Metadata includes recipes, classes, and + configuration files. + In the context of the kernel ("kernel Metadata"), + it refers to Metadata in the meta + branches of the kernel source Git repositories. + + 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 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 + "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, + PV, and + PE). + + Package Groups: + Arbitrary groups of software Recipes. + You use package groups to hold recipes that, when built, + usually accomplish a single task. + For example, a package group could contain the recipes for a + company’s proprietary or value-add software. + Or, the package group could contain the recipes that enable + graphics. + A package group is really just another recipe. + Because package group files are recipes, they end with the + .bb filename extension. + 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 + 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. + + 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. + + When you create a local copy of the Git repository, 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". + + While it is not recommended that you use tarball expansion + to setup the Source Directory, if you do, the top-level + directory name 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 root folder is named + &YOCTO_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 and will remain local only. + On the other hand, when you clone the poky + Git repository, you have an active development repository with + access to the upstream repository's branches and tags. + In this case, any local changes you make to the local + Source Directory can be later applied to active development + branches of the upstream poky Git + repository. + + For more information on concepts related to Git + repositories, branches, and tags, see the + "Repositories, Tags, and Branches" + section. + Task: + A unit of execution for BitBake (e.g. + do_compile, + do_fetch, do_patch, + and so forth). + + 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 + Source 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/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 + conform to the Open Source Definition (OSD). + + + + 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 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 makes extensive use of 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 the 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 the 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 from which you can do lots of + local experimentation on projects 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 + "Getting Set Up" section. + + + + 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, + daisy, 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 + Source Directory + 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. + 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. + + + + 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 dylan-9.0.0, + dora-10.0.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 the entire 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 do not know much about Git, you should 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 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. + You must stage 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 staged 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 do not 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 committed local changes to an upstream Git + repository (e.g. a contribution repository). + The maintainer of the project draws from these repositories + when adding changes to the project’s master repository or + other development branch. + + 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 a given 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. + For information on finding out who is responsible (maintains) + for a particular area of code, see the + "How to Submit a Change" + section. + + + + + 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. + + + + 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 machines 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: 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. + + + + + + + + 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 as 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 and have merged it + into your local master branch, simply discard the temporary + 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 scripts + folder of the + Source Directory. + For information on how to use these scripts, see 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. + For information on how to use these scripts, see the + "How to Submit a Change" + section. + + + +
+ +
+ 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 the 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. + Select the appropriate "Documentation change" item + for the bug. + Fixing a bug may or may not affect the Yocto Project + documentation. + 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 surrounds the issue. + You can even attach supporting files for output from logs by + using the "Add an attachment" button. + Be sure to copy the appropriate people in the + "CC List" for the bug. + See the "How to Submit a Change" + section for information about finding out who is responsible + for code. + 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. + + + + Before submitting any change, be sure to find out who you should be + notifying. + Several methods exist through which you find out who you should be copying + or notifying: + + Maintenance File: + Examine the maintainers.inc file, which is + located in the + Source Directory + at meta-yocto/conf/distro/include, to + see who is responsible for code. + + Board Support Package (BSP) README Files: + For BSP maintainers of supported BSPs, you can examine + individual BSP README files. + In addition, some layers (such as the meta-intel layer), + include a MAINTAINERS file which contains + a list of all supported BSP maintainers for that layer. + + Search by File: + Using Git, you can enter the + following command to bring up a short list of all commits + against a specific file: + + git shortlog -- <filename> + + Just provide the name of the file for which you are interested. + The information returned is not ordered by history but does + include a list of all committers grouped by name. + From the list, you can see who is responsible for the bulk of + the changes against the file. + + + + + + For a list of the Yocto Project and related mailing lists, see the + "Mailing lists" section in + the Yocto Project Reference Manual. + + + + Here 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 short description 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 + use the following form for the detailed description: + + Fixes [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: + . + + + + The next two sections describe 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. + 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 + 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. + However, keep in mind, the preferred method is to use the scripts. + + + + 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. + For a description of the available mailing lists, see the + "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, either of these two commands takes your most + recent single commit and formats it as an email message in + the current directory: + + $ git format-patch -1 + + or + + $ 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 + series of numbered 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, Debian, 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, + see GIT-SEND-EMAIL(1) displayed using + the man git-send-email command. + + + +
+
+ + -- cgit v1.2.3-54-g00ecf