diff options
Diffstat (limited to 'poky/documentation/overview-manual/overview-manual-development-environment.xml')
| -rw-r--r-- | poky/documentation/overview-manual/overview-manual-development-environment.xml | 970 |
1 files changed, 970 insertions, 0 deletions
diff --git a/poky/documentation/overview-manual/overview-manual-development-environment.xml b/poky/documentation/overview-manual/overview-manual-development-environment.xml new file mode 100644 index 000000000..bba93ccef --- /dev/null +++ b/poky/documentation/overview-manual/overview-manual-development-environment.xml @@ -0,0 +1,970 @@ +<!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; ] > + +<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://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>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 the <trademark class='trade'>Eclipse</trademark> IDE:</emphasis> + One of two Yocto Project development methods that involves an + interface that effectively puts the Yocto Project into the + background is the popular Eclipse IDE. + This method of development is advantageous if you are already + familiar with working within Eclipse. + Development is supported through a plugin that you install + onto your development host.</para> + + <para>For steps that show you how to set up your development + host to use the Eclipse Yocto Project plugin, see the + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-eclipse-project'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></ulink>" + Chapter in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) 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 + the <trademark class='trade'>Eclipse</trademark> + 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.</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 +--> |
