diff options
Diffstat (limited to 'documentation/overview-manual/overview-manual-development-environment.xml')
| -rw-r--r-- | documentation/overview-manual/overview-manual-development-environment.xml | 954 |
1 files changed, 0 insertions, 954 deletions
diff --git a/documentation/overview-manual/overview-manual-development-environment.xml b/documentation/overview-manual/overview-manual-development-environment.xml deleted file mode 100644 index 8415d1dd70..0000000000 --- a/documentation/overview-manual/overview-manual-development-environment.xml +++ /dev/null @@ -1,954 +0,0 @@ -<!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 ---> |