| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| <!--SPDX-License-Identifier: CC-BY-2.0-UK--> |
| |
| <chapter id='overview-development-environment'> |
| <title>The Yocto Project Development Environment</title> |
| |
| <para> |
| This chapter takes a look at the Yocto Project development |
| environment. |
| The chapter provides Yocto Project Development environment concepts that |
| help you understand how work is accomplished in an open source environment, |
| which is very different as compared to work accomplished in a closed, |
| proprietary environment. |
| </para> |
| |
| <para> |
| Specifically, this chapter addresses open source philosophy, source |
| repositories, workflows, Git, and licensing. |
| </para> |
| |
| <section id='open-source-philosophy'> |
| <title>Open Source Philosophy</title> |
| |
| <para> |
| 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. |
| </para> |
| |
| <para> |
| 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) who 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. |
| </para> |
| |
| <para> |
| 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 |
| <trademark class='registered'>Windows</trademark> family of operating |
| systems developed by |
| <trademark class='registered'>Microsoft</trademark> Corporation. |
| </para> |
| |
| <para> |
| Wikipedia has a good historical description of the Open Source |
| Philosophy |
| <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>. |
| You can also find helpful information on how to participate in the |
| Linux Community |
| <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>. |
| </para> |
| </section> |
| |
| <section id='gs-the-development-host'> |
| <title>The Development Host</title> |
| |
| <para> |
| A development host or |
| <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink> |
| is key to using the Yocto Project. |
| Because the goal of the Yocto Project is to develop images or |
| applications that run on embedded hardware, development of those |
| images and applications generally takes place on a system not |
| intended to run the software - the development host. |
| </para> |
| |
| <para> |
| You need to set up a development host in order to use it with the |
| Yocto Project. |
| Most find that it is best to have a native Linux machine function as |
| the development host. |
| However, it is possible to use a system that does not run Linux |
| as its operating system as your development host. |
| When you have a Mac or Windows-based system, you can set it up |
| as the development host by using |
| <ulink url='https://github.com/crops/poky-container'>CROPS</ulink>, |
| which leverages |
| <ulink url='https://www.docker.com/'>Docker Containers</ulink>. |
| Once you take the steps to set up a CROPS machine, you effectively |
| have access to a shell environment that is similar to what you see |
| when using a Linux-based development host. |
| For the steps needed to set up a system using CROPS, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para> |
| |
| <para> |
| If your development host is going to be a system that runs a Linux |
| distribution, steps still exist that you must take to prepare the |
| system for use with the Yocto Project. |
| You need to be sure that the Linux distribution on the system is |
| one that supports the Yocto Project. |
| You also need to be sure that the correct set of host packages are |
| installed that allow development using the Yocto Project. |
| For the steps needed to set up a development host that runs Linux, |
| see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host'>Setting Up a Native Linux Host</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para> |
| |
| <para> |
| Once your development host is set up to use the Yocto Project, |
| several methods exist for you to do work in the Yocto Project |
| environment: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Command Lines, BitBake, and Shells:</emphasis> |
| Traditional development in the Yocto Project involves using the |
| <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>, |
| which uses BitBake, in a command-line environment from a shell |
| on your development host. |
| You can accomplish this from a host that is a native Linux |
| machine or from a host that has been set up with CROPS. |
| Either way, you create, modify, and build images and |
| applications all within a shell-based environment using |
| components and tools available through your Linux distribution |
| and the Yocto Project.</para> |
| |
| <para>For a general flow of the build procedures, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image'>Building a Simple Image</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Board Support Package (BSP) Development:</emphasis> |
| Development of BSPs involves using the Yocto Project to |
| create and test layers that allow easy development of |
| images and applications targeted for specific hardware. |
| To development BSPs, you need to take some additional steps |
| beyond what was described in setting up a development host. |
| </para> |
| |
| <para>The |
| <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink> |
| provides BSP-related development information. |
| For specifics on development host preparation, see the |
| "<ulink url='&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work With BSP Layers</ulink>" |
| section in the Yocto Project Board Support Package (BSP) |
| Developer's Guide. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Kernel Development:</emphasis> |
| If you are going to be developing kernels using the Yocto |
| Project you likely will be using <filename>devtool</filename>. |
| A workflow using <filename>devtool</filename> makes kernel |
| development quicker by reducing iteration cycle times.</para> |
| |
| <para>The |
| <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink> |
| provides kernel-related development information. |
| For specifics on development host preparation, see the |
| "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</ulink>" |
| section in the Yocto Project Linux Kernel Development Manual. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Using Toaster:</emphasis> |
| The other Yocto Project development method that involves an |
| interface that effectively puts the Yocto Project into the |
| background is Toaster. |
| Toaster provides an interface to the OpenEmbedded build system. |
| The interface enables you to configure and run your builds. |
| Information about builds is collected and stored in a database. |
| You can use Toaster to configure and start builds on multiple |
| remote build servers.</para> |
| |
| <para>For steps that show you how to set up your development |
| host to use Toaster and on how to use Toaster in general, |
| see the |
| <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='yocto-project-repositories'> |
| <title>Yocto Project Source Repositories</title> |
| |
| <para> |
| The Yocto Project team maintains complete source repositories for all |
| Yocto Project files at |
| <ulink url='&YOCTO_GIT_URL;'></ulink>. |
| 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 |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>, |
| 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. |
| </para> |
| |
| <para> |
| For any supported release of Yocto Project, you can also go to the |
| <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and |
| select the "DOWNLOADS" item from the "SOFTWARE" menu and get a |
| released tarball of the <filename>poky</filename> repository, any |
| supported BSP tarball, or Yocto Project tools. |
| Unpacking these tarballs gives you a snapshot of the released |
| files. |
| <note><title>Notes</title> |
| <itemizedlist> |
| <listitem><para> |
| The recommended method for setting up the Yocto Project |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> |
| and the files for supported BSPs |
| (e.g., <filename>meta-intel</filename>) is to use |
| <link linkend='git'>Git</link> to create a local copy of |
| the upstream repositories. |
| </para></listitem> |
| <listitem><para> |
| Be sure to always work in matching branches for both |
| the selected BSP repository and the Source Directory |
| (i.e. <filename>poky</filename>) repository. |
| For example, if you have checked out the "master" branch |
| of <filename>poky</filename> and you are going to use |
| <filename>meta-intel</filename>, be sure to checkout the |
| "master" branch of <filename>meta-intel</filename>. |
| </para></listitem> |
| </itemizedlist> |
| </note> |
| </para> |
| |
| <para> |
| In summary, here is where you can get the project files needed for |
| development: |
| <itemizedlist> |
| <listitem><para id='source-repositories'> |
| <emphasis> |
| <ulink url='&YOCTO_GIT_URL;'>Source Repositories:</ulink> |
| </emphasis> |
| 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.</para> |
| |
| <para> |
| <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" /> |
| For steps on how to view and access these upstream Git |
| repositories, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-source-repositories'>Accessing Source Repositories</ulink>" |
| Section in the Yocto Project Development Tasks Manual. |
| </para></listitem> |
| <listitem><para><anchor id='index-downloads' /> |
| <emphasis> |
| <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> |
| </emphasis> |
| This is an index of releases such as Poky, Pseudo, installers |
| for cross-development toolchains, miscellaneous support |
| 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.</para> |
| |
| <para> |
| <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" /> |
| For steps on how to view and access these files, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-index-of-releases'>Accessing Index of Releases</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para></listitem> |
| <listitem><para id='downloads-page'> |
| <emphasis>"DOWNLOADS" page for the |
| <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>: |
| </emphasis></para> |
| |
| <para>The Yocto Project website includes a "DOWNLOADS" page |
| accessible through the "SOFTWARE" menu that allows you to |
| download any Yocto Project release, tool, and Board Support |
| Package (BSP) in tarball form. |
| The tarballs are similar to those found in the |
| <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> |
| area.</para> |
| |
| <para> |
| <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" /> |
| For steps on how to use the "DOWNLOADS" page, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-downloads-page'>Using the Downloads Page</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='gs-git-workflows-and-the-yocto-project'> |
| <title>Git Workflows and the Yocto Project</title> |
| |
| <para> |
| Developing using the Yocto Project likely requires the use of |
| <link linkend='git'>Git</link>. |
| Git is a free, open source distributed version control system |
| used as part of many collaborative design environments. |
| This section provides workflow concepts using the Yocto Project and |
| Git. |
| In particular, the information covers basic practices that describe |
| roles and actions in a collaborative development environment. |
| <note> |
| If you are familiar with this type of development environment, you |
| might not want to read this section. |
| </note> |
| </para> |
| |
| <para> |
| The Yocto Project files are maintained using Git in "branches" |
| whose Git histories track every change and whose structures |
| provide branches for all diverging functionality. |
| Although there is no need to use Git, many open source projects do so. |
| <para> |
| |
| </para> |
| For the Yocto Project, a key individual called the "maintainer" is |
| responsible for the integrity of the "master" branch of a given Git |
| repository. |
| The "master" branch is the "upstream" repository from which final or |
| most recent builds of a project occur. |
| The maintainer is responsible for accepting changes from other |
| developers and for organizing the underlying branch structure to |
| reflect release strategies and so forth. |
| <note> |
| For information on finding out who is responsible for (maintains) |
| a particular area of code in the Yocto Project, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>" |
| section of the Yocto Project Development Tasks Manual. |
| </note> |
| </para> |
| |
| <para> |
| The Yocto Project <filename>poky</filename> Git repository also has an |
| upstream contribution Git repository named |
| <filename>poky-contrib</filename>. |
| You can see all the branches in this repository using the web interface |
| of the |
| <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized |
| within the "Poky Support" area. |
| These branches hold changes (commits) 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. |
| </para> |
| |
| <para> |
| Developers (including contributing community members) create and |
| maintain cloned repositories of upstream branches. |
| The cloned 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 change to the appropriate "contrib" repository. |
| </para> |
| |
| <para> |
| Developers are responsible for keeping their local repository |
| up-to-date with whatever upstream branch they are working against. |
| 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 development host before |
| anything is pushed to a "contrib" area and examined at the maintainer's |
| level. |
| </para> |
| |
| <para> |
| 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 an upstream branch. |
| This process is called "submitting a patch" or "submitting a change." |
| For information on submitting patches and changes, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para> |
| |
| <para> |
| In summary, a single point of entry |
| exists for changes into a "master" or development 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. |
| </para> |
| |
| <para> |
| <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" /> |
| </para> |
| |
| <para> |
| 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 |
| <ulink url='http://book.git-scm.com'>Git Community Book</ulink>. |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Make Small Changes:</emphasis> |
| 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. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Make Complete Changes:</emphasis> |
| 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. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Use Branches Liberally:</emphasis> |
| It is very easy to create, use, and delete local branches in |
| your working Git repository on the development host. |
| 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. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Merge Changes:</emphasis> |
| The <filename>git merge</filename> 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. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Manage Branches:</emphasis> |
| 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. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Use Push and Pull:</emphasis> |
| 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 |
| <filename>create-pull-request</filename> and |
| <filename>send-pull-request</filename> that ship with the |
| release to facilitate this workflow. |
| You can find these scripts in the <filename>scripts</filename> |
| folder of the |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. |
| For information on how to use these scripts, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Patch Workflow:</emphasis> |
| 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 |
| <filename>git format-patch</filename> and |
| <filename>git send-email</filename>. |
| For information on how to use these scripts, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='git'> |
| <title>Git</title> |
| |
| <para> |
| 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. |
| <note><title>Notes</title> |
| <itemizedlist> |
| <listitem><para> |
| For more information on Git, see |
| <ulink url='http://git-scm.com/documentation'></ulink>. |
| </para></listitem> |
| <listitem><para> |
| If you need to download Git, it is recommended that you add |
| Git to your system through your distribution's "software |
| store" (e.g. for Ubuntu, use the Ubuntu Software feature). |
| For the Git download page, see |
| <ulink url='http://git-scm.com/download'></ulink>. |
| </para></listitem> |
| <listitem><para> |
| For information beyond the introductory nature in this |
| section, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para></listitem> |
| </itemizedlist> |
| </note> |
| </para> |
| |
| <section id='repositories-tags-and-branches'> |
| <title>Repositories, Tags, and Branches</title> |
| |
| <para> |
| As mentioned briefly in the previous section and also in the |
| "<link linkend='gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</link>" |
| section, the Yocto Project maintains source repositories at |
| <ulink url='&YOCTO_GIT_URL;'></ulink>. |
| If you look at this web-interface of the repositories, each item |
| is a separate Git repository. |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| |
| <para> |
| A Git repository represents all development efforts for a given |
| project. |
| For example, the Git repository <filename>poky</filename> contains |
| all changes and developments for that repository 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. |
| </para> |
| |
| <para> |
| You can create a local copy of any repository by "cloning" it |
| with the <filename>git clone</filename> 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 |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para> |
| |
| <para> |
| It is important to understand that Git tracks content change and |
| not files. |
| Git uses "branches" to organize different development efforts. |
| For example, the <filename>poky</filename> repository has |
| several branches that include the current "&DISTRO_NAME_NO_CAP;" |
| branch, the "master" branch, and many branches for past |
| Yocto Project releases. |
| You can see all the branches by going to |
| <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and |
| clicking on the |
| <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename> |
| link beneath the "Branch" heading. |
| </para> |
| |
| <para> |
| Each of these branches represents a specific area of development. |
| The "master" branch represents the current or most recent |
| development. |
| All other branches represent offshoots of the "master" branch. |
| </para> |
| |
| <para> |
| 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 upstream 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, consider the following example Git commands: |
| <literallayout class='monospaced'> |
| $ cd ~ |
| $ git clone git://git.yoctoproject.org/poky |
| $ cd poky |
| $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; |
| </literallayout> |
| In the previous example after moving to the home directory, the |
| <filename>git clone</filename> command creates a |
| local copy of the upstream <filename>poky</filename> Git repository. |
| By default, Git checks out the "master" branch for your work. |
| After changing the working directory to the new local repository |
| (i.e. <filename>poky</filename>), the |
| <filename>git checkout</filename> command creates |
| and checks out a local branch named "&DISTRO_NAME_NO_CAP;", which |
| tracks the upstream "origin/&DISTRO_NAME_NO_CAP;" branch. |
| Changes you make while in this branch would ultimately affect |
| the upstream "&DISTRO_NAME_NO_CAP;" branch of the |
| <filename>poky</filename> repository. |
| </para> |
| |
| <para> |
| 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 particular |
| development branch at the time you created your local branch, |
| which could be different from the files in the "master" branch |
| of the upstream repository. |
| In other words, creating and checking out a local branch based on |
| the "&DISTRO_NAME_NO_CAP;" branch name is not the same as |
| checking out the "master" branch in the repository. |
| Keep reading to see how you create a local snapshot of a Yocto |
| Project Release. |
| </para> |
| |
| <para> |
| Git uses "tags" to mark specific changes in a repository branch |
| structure. |
| Typically, a tag is used to mark a special point such as the final |
| change (or commit) before a project is released. |
| You can see the tags used with the <filename>poky</filename> Git |
| repository by going to |
| <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and |
| clicking on the |
| <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename> |
| link beneath the "Tag" heading. |
| </para> |
| |
| <para> |
| Some key tags for the <filename>poky</filename> repository are |
| <filename>jethro-14.0.3</filename>, |
| <filename>morty-16.0.1</filename>, |
| <filename>pyro-17.0.0</filename>, and |
| <filename>&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>. |
| These tags represent Yocto Project releases. |
| </para> |
| |
| <para> |
| When you create a local copy of the Git repository, you also |
| have access to all the tags in the upstream repository. |
| 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: |
| <literallayout class='monospaced'> |
| $ cd ~ |
| $ git clone git://git.yoctoproject.org/poky |
| $ cd poky |
| $ git fetch --tags |
| $ git checkout tags/rocko-18.0.0 -b my_rocko-18.0.0 |
| </literallayout> |
| In this example, the name of the top-level directory of your |
| local Yocto Project repository is <filename>poky</filename>. |
| After moving to the <filename>poky</filename> directory, the |
| <filename>git fetch</filename> command makes all the upstream |
| tags available locally in your repository. |
| Finally, the <filename>git checkout</filename> command |
| creates and checks out a branch named "my-rocko-18.0.0" that is |
| based on the upstream branch whose "HEAD" matches the |
| commit in the repository associated with the "rocko-18.0.0" tag. |
| The files in your repository now exactly match that particular |
| Yocto Project release as it is tagged in the upstream Git |
| repository. |
| 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 (i.e. from the "tip" of the branch backwards). |
| </para> |
| </section> |
| |
| <section id='basic-commands'> |
| <title>Basic Commands</title> |
| |
| <para> |
| 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 |
| <ulink url='http://git-scm.com/documentation'>here</ulink>. |
| </para> |
| |
| <para> |
| The following list of Git commands 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 it supports. |
| See the Git documentation for complete descriptions and strategies |
| on how to use these commands: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis><filename>git init</filename>:</emphasis> |
| Initializes an empty Git repository. |
| You cannot use Git commands unless you have a |
| <filename>.git</filename> repository. |
| </para></listitem> |
| <listitem><para id='git-commands-clone'> |
| <emphasis><filename>git clone</filename>:</emphasis> |
| Creates a local clone of a Git repository that is on |
| equal footing with a fellow developer's Git repository |
| or an upstream repository. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>git add</filename>:</emphasis> |
| Locally 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. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>git commit</filename>:</emphasis> |
| Creates a local "commit" that documents the changes you |
| made. |
| Only changes that have been staged can be committed. |
| 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 repository. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>git status</filename>:</emphasis> |
| Reports any modified files that possibly need to be |
| staged and gives you a status of where you stand regarding |
| local commits as compared to the upstream repository. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>git checkout</filename> <replaceable>branch-name</replaceable>:</emphasis> |
| Changes your local working branch and in this form |
| assumes the local branch already exists. |
| This command is analogous to "cd". |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>git checkout –b</filename> <replaceable>working-branch</replaceable> <replaceable>upstream-branch</replaceable>:</emphasis> |
| Creates and checks out a working branch on your local |
| machine. |
| The local branch tracks the upstream branch. |
| You can use your local branch to isolate your work. |
| It is a good idea to use local branches when adding |
| specific features or changes. |
| Using isolated branches facilitates easy removal of |
| changes if they do not work out. |
| </para></listitem> |
| <listitem><para><emphasis><filename>git branch</filename>:</emphasis> |
| Displays the existing local branches associated with your |
| local repository. |
| The branch that you have currently checked out is noted |
| with an asterisk character. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>git branch -D</filename> <replaceable>branch-name</replaceable>:</emphasis> |
| Deletes an existing local branch. |
| You need to be in a local branch other than the one you |
| are deleting in order to delete |
| <replaceable>branch-name</replaceable>. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>git pull --rebase</filename>:</emphasis> |
| 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). |
| The "--rebase" option ensures that any local commits you |
| have in your branch are preserved at the top of your |
| local branch. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>git push</filename> <replaceable>repo-name</replaceable> <replaceable>local-branch</replaceable><filename>:</filename><replaceable>upstream-branch</replaceable>:</emphasis> |
| Sends all your committed local changes to the upstream Git |
| repository that your local repository is tracking |
| (e.g. a contribution repository). |
| The maintainer of the project draws from these repositories |
| to merge changes (commits) into the appropriate branch |
| of project's upstream repository. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>git merge</filename>:</emphasis> |
| 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 that is |
| based off "master" that you would use for isolated work. |
| You would make your changes in that isolated branch, |
| stage and commit them locally, switch to the "master" |
| branch, and then use the <filename>git merge</filename> |
| command to apply the changes from your isolated branch |
| into the currently checked out branch (e.g. "master"). |
| After the merge is complete and if you are done with |
| working in that isolated branch, you can safely delete |
| the isolated branch. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>git cherry-pick</filename> <replaceable>commits</replaceable>:</emphasis> |
| 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. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>gitk</filename>:</emphasis> |
| 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. |
| <note> |
| You need to install the <filename>gitk</filename> |
| package on your development system to use this |
| command. |
| </note> |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>git log</filename>:</emphasis> |
| Reports a history of your commits to the repository. |
| This report lists all commits regardless of whether you |
| have pushed them upstream or not. |
| </para></listitem> |
| <listitem><para> |
| <emphasis><filename>git diff</filename>:</emphasis> |
| Displays line-by-line differences between a local |
| working file and the same file as understood by Git. |
| This command is useful to see what you have changed |
| in any given file. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| </section> |
| |
| <section id='licensing'> |
| <title>Licensing</title> |
| |
| <para> |
| 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: |
| <itemizedlist> |
| <listitem><para> |
| <ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink> |
| </para></listitem> |
| <listitem><para> |
| <ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license history</ulink> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| 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 |
| <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>. |
| You can find information on the GNU GPL |
| <ulink url='http://www.opensource.org/licenses/LGPL-3.0'>here</ulink>. |
| </para> |
| |
| <para> |
| 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 |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> |
| at <filename>meta/files/common-licenses</filename>. |
| Once the build completes, the list of all licenses found and used |
| during that build are kept in the |
| <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> |
| at <filename>tmp/deploy/licenses</filename>. |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| |
| <para> |
| 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. |
| <ulink url='http://spdx.org'>SPDX Group</ulink> 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. |
| <ulink url='http://opensource.org'>OSI</ulink> 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). |
| </para> |
| |
| <para> |
| You can find a list of the combined SPDX and OSI licenses that the |
| Yocto Project uses in the |
| <filename>meta/files/common-licenses</filename> directory in your |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. |
| </para> |
| |
| <para> |
| 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 |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para> |
| </section> |
| </chapter> |
| <!-- |
| vim: expandtab tw=80 ts=4 |
| --> |