blob: bb2c8e72e79c7b0c9f5289acabd31dacd084bc9a [file] [log] [blame]
Andrew Geissler4873add2020-11-02 18:44:49 -06001.. SPDX-License-Identifier: CC-BY-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3*****************************************
4The Yocto Project Development Environment
5*****************************************
6
7This chapter takes a look at the Yocto Project development environment.
8The chapter provides Yocto Project Development environment concepts that
9help you understand how work is accomplished in an open source
10environment, which is very different as compared to work accomplished in
11a closed, proprietary environment.
12
13Specifically, this chapter addresses open source philosophy, source
14repositories, workflows, Git, and licensing.
15
16Open Source Philosophy
17======================
18
19Open source philosophy is characterized by software development directed
20by peer production and collaboration through an active community of
21developers. Contrast this to the more standard centralized development
22models used by commercial software companies where a finite set of
23developers produces a product for sale using a defined set of procedures
24that ultimately result in an end product whose architecture and source
25material are closed to the public.
26
27Open source projects conceptually have differing concurrent agendas,
28approaches, and production. These facets of the development process can
29come from anyone in the public (community) who has a stake in the
30software project. The open source environment contains new copyright,
31licensing, domain, and consumer issues that differ from the more
32traditional development environment. In an open source environment, the
33end product, source material, and documentation are all available to the
34public at no cost.
35
36A benchmark example of an open source project is the Linux kernel, which
37was initially conceived and created by Finnish computer science student
38Linus Torvalds in 1991. Conversely, a good example of a non-open source
39project is the Windows family of operating systems developed by
40Microsoft Corporation.
41
42Wikipedia has a good historical description of the Open Source
43Philosophy `here <http://en.wikipedia.org/wiki/Open_source>`__. You can
44also find helpful information on how to participate in the Linux
45Community
Andrew Geisslerc3d88e42020-10-02 09:45:00 -050046`here <https://www.kernel.org/doc/html/latest/process/index.html>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050047
48.. _gs-the-development-host:
49
50The Development Host
51====================
52
53A development host or :term:`Build Host` is key to
54using the Yocto Project. Because the goal of the Yocto Project is to
55develop images or applications that run on embedded hardware,
56development of those images and applications generally takes place on a
57system not intended to run the software - the development host.
58
59You need to set up a development host in order to use it with the Yocto
60Project. Most find that it is best to have a native Linux machine
61function as the development host. However, it is possible to use a
62system that does not run Linux as its operating system as your
63development host. When you have a Mac or Windows-based system, you can
64set it up as the development host by using
65`CROPS <https://github.com/crops/poky-container>`__, which leverages
66`Docker Containers <https://www.docker.com/>`__. Once you take the steps
67to set up a CROPS machine, you effectively have access to a shell
68environment that is similar to what you see when using a Linux-based
69development host. For the steps needed to set up a system using CROPS,
70see the
71":ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)`"
72section in
73the Yocto Project Development Tasks Manual.
74
75If your development host is going to be a system that runs a Linux
76distribution, steps still exist that you must take to prepare the system
77for use with the Yocto Project. You need to be sure that the Linux
78distribution on the system is one that supports the Yocto Project. You
79also need to be sure that the correct set of host packages are installed
80that allow development using the Yocto Project. For the steps needed to
81set up a development host that runs Linux, see the
82":ref:`dev-manual/dev-manual-start:setting up a native linux host`"
83section in the Yocto Project Development Tasks Manual.
84
85Once your development host is set up to use the Yocto Project, several
86methods exist for you to do work in the Yocto Project environment:
87
88- *Command Lines, BitBake, and Shells:* Traditional development in the
89 Yocto Project involves using the :term:`OpenEmbedded Build System`,
90 which uses
91 BitBake, in a command-line environment from a shell on your
92 development host. You can accomplish this from a host that is a
93 native Linux machine or from a host that has been set up with CROPS.
94 Either way, you create, modify, and build images and applications all
95 within a shell-based environment using components and tools available
96 through your Linux distribution and the Yocto Project.
97
98 For a general flow of the build procedures, see the
99 ":ref:`dev-manual/dev-manual-common-tasks:building a simple image`"
100 section in the Yocto Project Development Tasks Manual.
101
102- *Board Support Package (BSP) Development:* Development of BSPs
103 involves using the Yocto Project to create and test layers that allow
104 easy development of images and applications targeted for specific
105 hardware. To development BSPs, you need to take some additional steps
106 beyond what was described in setting up a development host.
107
108 The :doc:`../bsp-guide/bsp-guide` provides BSP-related development
109 information. For specifics on development host preparation, see the
110 ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`"
111 section in the Yocto Project Board Support Package (BSP) Developer's
112 Guide.
113
114- *Kernel Development:* If you are going to be developing kernels using
115 the Yocto Project you likely will be using ``devtool``. A workflow
116 using ``devtool`` makes kernel development quicker by reducing
117 iteration cycle times.
118
119 The :doc:`../kernel-dev/kernel-dev` provides kernel-related
120 development information. For specifics on development host
121 preparation, see the
122 ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`"
123 section in the Yocto Project Linux Kernel Development Manual.
124
125- *Using Toaster:* The other Yocto Project development method that
126 involves an interface that effectively puts the Yocto Project into
127 the background is Toaster. Toaster provides an interface to the
128 OpenEmbedded build system. The interface enables you to configure and
129 run your builds. Information about builds is collected and stored in
130 a database. You can use Toaster to configure and start builds on
131 multiple remote build servers.
132
133 For steps that show you how to set up your development host to use
134 Toaster and on how to use Toaster in general, see the
135 :doc:`../toaster-manual/toaster-manual`.
136
137.. _yocto-project-repositories:
138
139Yocto Project Source Repositories
140=================================
141
142The Yocto Project team maintains complete source repositories for all
143Yocto Project files at :yocto_git:`/`. This web-based source
144code browser is organized into categories by function such as IDE
145Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. From the
146interface, you can click on any particular item in the "Name" column and
147see the URL at the bottom of the page that you need to clone a Git
148repository for that particular item. Having a local Git repository of
149the :term:`Source Directory`, which
150is usually named "poky", allows you to make changes, contribute to the
151history, and ultimately enhance the Yocto Project's tools, Board Support
152Packages, and so forth.
153
154For any supported release of Yocto Project, you can also go to the
155:yocto_home:`Yocto Project Website <>` and select the "DOWNLOADS"
156item from the "SOFTWARE" menu and get a released tarball of the ``poky``
157repository, any supported BSP tarball, or Yocto Project tools. Unpacking
158these tarballs gives you a snapshot of the released files.
159
160.. note::
161
162 - The recommended method for setting up the Yocto Project
163 :term:`Source Directory` and the files
164 for supported BSPs (e.g., ``meta-intel``) is to use `Git <#git>`__
165 to create a local copy of the upstream repositories.
166
167 - Be sure to always work in matching branches for both the selected
168 BSP repository and the Source Directory (i.e. ``poky``)
169 repository. For example, if you have checked out the "master"
170 branch of ``poky`` and you are going to use ``meta-intel``, be
171 sure to checkout the "master" branch of ``meta-intel``.
172
173In summary, here is where you can get the project files needed for
174development:
175
176- :yocto_git:`Source Repositories: <>` This area contains IDE
177 Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and
178 Yocto Metadata Layers. You can create local copies of Git
179 repositories for each of these areas.
180
181 .. image:: figures/source-repos.png
182 :align: center
183
184 For steps on how to view and access these upstream Git repositories,
185 see the ":ref:`dev-manual/dev-manual-start:accessing source repositories`"
186 Section in the Yocto Project Development Tasks Manual.
187
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500188- :yocto_dl:`Index of /releases: </releases>` This is an index
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500189 of releases such as Poky, Pseudo, installers for cross-development
190 toolchains, miscellaneous support and all released versions of Yocto
191 Project in the form of images or tarballs. Downloading and extracting
192 these files does not produce a local copy of the Git repository but
193 rather a snapshot of a particular release or image.
194
195 .. image:: figures/index-downloads.png
196 :align: center
197
198 For steps on how to view and access these files, see the
199 ":ref:`dev-manual/dev-manual-start:accessing index of releases`"
200 section in the Yocto Project Development Tasks Manual.
201
202- *"DOWNLOADS" page for the* :yocto_home:`Yocto Project Website <>` *:*
203
204 The Yocto Project website includes a "DOWNLOADS" page accessible
205 through the "SOFTWARE" menu that allows you to download any Yocto
206 Project release, tool, and Board Support Package (BSP) in tarball
207 form. The tarballs are similar to those found in the
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500208 :yocto_dl:`Index of /releases: </releases>` area.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500209
210 .. image:: figures/yp-download.png
211 :align: center
212
213 For steps on how to use the "DOWNLOADS" page, see the
214 ":ref:`dev-manual/dev-manual-start:using the downloads page`"
215 section in the Yocto Project Development Tasks Manual.
216
217.. _gs-git-workflows-and-the-yocto-project:
218
219Git Workflows and the Yocto Project
220===================================
221
222Developing using the Yocto Project likely requires the use of
223`Git <#git>`__. Git is a free, open source distributed version control
224system used as part of many collaborative design environments. This
225section provides workflow concepts using the Yocto Project and Git. In
226particular, the information covers basic practices that describe roles
227and actions in a collaborative development environment.
228
229.. note::
230
231 If you are familiar with this type of development environment, you
232 might not want to read this section.
233
234The Yocto Project files are maintained using Git in "branches" whose Git
235histories track every change and whose structures provide branches for
236all diverging functionality. Although there is no need to use Git, many
237open source projects do so.
238
239For the Yocto Project, a key individual called the "maintainer" is
240responsible for the integrity of the "master" branch of a given Git
241repository. The "master" branch is the "upstream" repository from which
242final or most recent builds of a project occur. The maintainer is
243responsible for accepting changes from other developers and for
244organizing the underlying branch structure to reflect release strategies
245and so forth.
246
247.. note::
248
249 For information on finding out who is responsible for (maintains) a
250 particular area of code in the Yocto Project, see the
251 ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
252 section of the Yocto Project Development Tasks Manual.
253
254The Yocto Project ``poky`` Git repository also has an upstream
255contribution Git repository named ``poky-contrib``. You can see all the
256branches in this repository using the web interface of the
257:yocto_git:`Source Repositories <>` organized within the "Poky Support"
258area. These branches hold changes (commits) to the project that have
259been submitted or committed by the Yocto Project development team and by
260community members who contribute to the project. The maintainer
261determines if the changes are qualified to be moved from the "contrib"
262branches into the "master" branch of the Git repository.
263
264Developers (including contributing community members) create and
265maintain cloned repositories of upstream branches. The cloned
266repositories are local to their development platforms and are used to
267develop changes. When a developer is satisfied with a particular feature
268or change, they "push" the change to the appropriate "contrib"
269repository.
270
271Developers are responsible for keeping their local repository up-to-date
272with whatever upstream branch they are working against. They are also
273responsible for straightening out any conflicts that might arise within
274files that are being worked on simultaneously by more than one person.
275All this work is done locally on the development host before anything is
276pushed to a "contrib" area and examined at the maintainer's level.
277
278A somewhat formal method exists by which developers commit changes and
279push them into the "contrib" area and subsequently request that the
280maintainer include them into an upstream branch. This process is called
281"submitting a patch" or "submitting a change." For information on
282submitting patches and changes, see the
283":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
284section in the Yocto Project Development Tasks Manual.
285
286In summary, a single point of entry exists for changes into a "master"
287or development branch of the Git repository, which is controlled by the
288project's maintainer. And, a set of developers exist who independently
289develop, test, and submit changes to "contrib" areas for the maintainer
290to examine. The maintainer then chooses which changes are going to
291become a permanent part of the project.
292
293.. image:: figures/git-workflow.png
294 :align: center
295
296While each development environment is unique, there are some best
297practices or methods that help development run smoothly. The following
298list describes some of these practices. For more information about Git
299workflows, see the workflow topics in the `Git Community
300Book <http://book.git-scm.com>`__.
301
302- *Make Small Changes:* It is best to keep the changes you commit small
303 as compared to bundling many disparate changes into a single commit.
304 This practice not only keeps things manageable but also allows the
305 maintainer to more easily include or refuse changes.
306
307- *Make Complete Changes:* It is also good practice to leave the
308 repository in a state that allows you to still successfully build
309 your project. In other words, do not commit half of a feature, then
310 add the other half as a separate, later commit. Each commit should
311 take you from one buildable project state to another buildable state.
312
313- *Use Branches Liberally:* It is very easy to create, use, and delete
314 local branches in your working Git repository on the development
315 host. You can name these branches anything you like. It is helpful to
316 give them names associated with the particular feature or change on
317 which you are working. Once you are done with a feature or change and
318 have merged it into your local master branch, simply discard the
319 temporary branch.
320
321- *Merge Changes:* The ``git merge`` command allows you to take the
322 changes from one branch and fold them into another branch. This
323 process is especially helpful when more than a single developer might
324 be working on different parts of the same feature. Merging changes
325 also automatically identifies any collisions or "conflicts" that
326 might happen as a result of the same lines of code being altered by
327 two different developers.
328
329- *Manage Branches:* Because branches are easy to use, you should use a
330 system where branches indicate varying levels of code readiness. For
331 example, you can have a "work" branch to develop in, a "test" branch
332 where the code or change is tested, a "stage" branch where changes
333 are ready to be committed, and so forth. As your project develops,
334 you can merge code across the branches to reflect ever-increasing
335 stable states of the development.
336
337- *Use Push and Pull:* The push-pull workflow is based on the concept
338 of developers "pushing" local commits to a remote repository, which
339 is usually a contribution repository. This workflow is also based on
340 developers "pulling" known states of the project down into their
341 local development repositories. The workflow easily allows you to
342 pull changes submitted by other developers from the upstream
343 repository into your work area ensuring that you have the most recent
344 software on which to develop. The Yocto Project has two scripts named
345 ``create-pull-request`` and ``send-pull-request`` that ship with the
346 release to facilitate this workflow. You can find these scripts in
347 the ``scripts`` folder of the
348 :term:`Source Directory`. For information
349 on how to use these scripts, see the
350 ":ref:`dev-manual/dev-manual-common-tasks:using scripts to push a change upstream and request a pull`"
351 section in the Yocto Project Development Tasks Manual.
352
353- *Patch Workflow:* This workflow allows you to notify the maintainer
354 through an email that you have a change (or patch) you would like
355 considered for the "master" branch of the Git repository. To send
356 this type of change, you format the patch and then send the email
357 using the Git commands ``git format-patch`` and ``git send-email``.
358 For information on how to use these scripts, see the
359 ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
360 section in the Yocto Project Development Tasks Manual.
361
362Git
363===
364
365The Yocto Project makes extensive use of Git, which is a free, open
366source distributed version control system. Git supports distributed
367development, non-linear development, and can handle large projects. It
368is best that you have some fundamental understanding of how Git tracks
369projects and how to work with Git if you are going to use the Yocto
370Project for development. This section provides a quick overview of how
371Git works and provides you with a summary of some essential Git
372commands.
373
374.. note::
375
376 - For more information on Git, see
377 http://git-scm.com/documentation.
378
379 - If you need to download Git, it is recommended that you add Git to
380 your system through your distribution's "software store" (e.g. for
381 Ubuntu, use the Ubuntu Software feature). For the Git download
382 page, see http://git-scm.com/download.
383
384 - For information beyond the introductory nature in this section,
385 see the ":ref:`dev-manual/dev-manual-start:locating yocto project source files`"
386 section in the Yocto Project Development Tasks Manual.
387
388Repositories, Tags, and Branches
389--------------------------------
390
391As mentioned briefly in the previous section and also in the "`Git
392Workflows and the Yocto
393Project <#gs-git-workflows-and-the-yocto-project>`__" section, the Yocto
394Project maintains source repositories at :yocto_git:`/`. If you
395look at this web-interface of the repositories, each item is a separate
396Git repository.
397
398Git repositories use branching techniques that track content change (not
399files) within a project (e.g. a new feature or updated documentation).
400Creating a tree-like structure based on project divergence allows for
401excellent historical information over the life of a project. This
402methodology also allows for an environment from which you can do lots of
403local experimentation on projects as you develop changes or new
404features.
405
406A Git repository represents all development efforts for a given project.
407For example, the Git repository ``poky`` contains all changes and
408developments for that repository over the course of its entire life.
409That means that all changes that make up all releases are captured. The
410repository maintains a complete history of changes.
411
412You can create a local copy of any repository by "cloning" it with the
413``git clone`` command. When you clone a Git repository, you end up with
414an identical copy of the repository on your development system. Once you
415have a local copy of a repository, you can take steps to develop
416locally. For examples on how to clone Git repositories, see the
417":ref:`dev-manual/dev-manual-start:locating yocto project source files`"
418section in the Yocto Project Development Tasks Manual.
419
420It is important to understand that Git tracks content change and not
421files. Git uses "branches" to organize different development efforts.
422For example, the ``poky`` repository has several branches that include
423the current "&DISTRO_NAME_NO_CAP;" branch, the "master" branch, and many
424branches for past Yocto Project releases. You can see all the branches
425by going to https://git.yoctoproject.org/cgit.cgi/poky/ and clicking on the
426``[...]`` link beneath the "Branch" heading.
427
428Each of these branches represents a specific area of development. The
429"master" branch represents the current or most recent development. All
430other branches represent offshoots of the "master" branch.
431
432When you create a local copy of a Git repository, the copy has the same
433set of branches as the original. This means you can use Git to create a
434local working area (also called a branch) that tracks a specific
435development branch from the upstream source Git repository. in other
436words, you can define your local Git environment to work on any
437development branch in the repository. To help illustrate, consider the
438following example Git commands:
439::
440
441 $ cd ~
442 $ git clone git://git.yoctoproject.org/poky
443 $ cd poky
444 $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
445
446In the previous example
447after moving to the home directory, the ``git clone`` command creates a
448local copy of the upstream ``poky`` Git repository. By default, Git
449checks out the "master" branch for your work. After changing the working
450directory to the new local repository (i.e. ``poky``), the
451``git checkout`` command creates and checks out a local branch named
452"&DISTRO_NAME_NO_CAP;", which tracks the upstream
453"origin/&DISTRO_NAME_NO_CAP;" branch. Changes you make while in this
454branch would ultimately affect the upstream "&DISTRO_NAME_NO_CAP;" branch
455of the ``poky`` repository.
456
457It is important to understand that when you create and checkout a local
458working branch based on a branch name, your local environment matches
459the "tip" of that particular development branch at the time you created
460your local branch, which could be different from the files in the
461"master" branch of the upstream repository. In other words, creating and
462checking out a local branch based on the "&DISTRO_NAME_NO_CAP;" branch
463name is not the same as checking out the "master" branch in the
464repository. Keep reading to see how you create a local snapshot of a
465Yocto Project Release.
466
467Git uses "tags" to mark specific changes in a repository branch
468structure. Typically, a tag is used to mark a special point such as the
469final change (or commit) before a project is released. You can see the
470tags used with the ``poky`` Git repository by going to
471https://git.yoctoproject.org/cgit.cgi/poky/ and clicking on the ``[...]`` link
472beneath the "Tag" heading.
473
474Some key tags for the ``poky`` repository are ``jethro-14.0.3``,
475``morty-16.0.1``, ``pyro-17.0.0``, and
476``&DISTRO_NAME_NO_CAP;-&POKYVERSION;``. These tags represent Yocto Project
477releases.
478
479When you create a local copy of the Git repository, you also have access
480to all the tags in the upstream repository. Similar to branches, you can
481create and checkout a local working Git branch based on a tag name. When
482you do this, you get a snapshot of the Git repository that reflects the
483state of the files when the change was made associated with that tag.
484The most common use is to checkout a working branch that matches a
485specific Yocto Project release. Here is an example:
486::
487
488 $ cd ~
489 $ git clone git://git.yoctoproject.org/poky
490 $ cd poky
491 $ git fetch --tags
492 $ git checkout tags/rocko-18.0.0 -b my_rocko-18.0.0
493
494In this example, the name
495of the top-level directory of your local Yocto Project repository is
496``poky``. After moving to the ``poky`` directory, the ``git fetch``
497command makes all the upstream tags available locally in your
498repository. Finally, the ``git checkout`` command creates and checks out
499a branch named "my-rocko-18.0.0" that is based on the upstream branch
500whose "HEAD" matches the commit in the repository associated with the
501"rocko-18.0.0" tag. The files in your repository now exactly match that
502particular Yocto Project release as it is tagged in the upstream Git
503repository. It is important to understand that when you create and
504checkout a local working branch based on a tag, your environment matches
505a specific point in time and not the entire development branch (i.e.
506from the "tip" of the branch backwards).
507
508Basic Commands
509--------------
510
511Git has an extensive set of commands that lets you manage changes and
512perform collaboration over the life of a project. Conveniently though,
513you can manage with a small set of basic operations and workflows once
514you understand the basic philosophy behind Git. You do not have to be an
515expert in Git to be functional. A good place to look for instruction on
516a minimal set of Git commands is
517`here <http://git-scm.com/documentation>`__.
518
519The following list of Git commands briefly describes some basic Git
520operations as a way to get started. As with any set of commands, this
521list (in most cases) simply shows the base command and omits the many
522arguments it supports. See the Git documentation for complete
523descriptions and strategies on how to use these commands:
524
525- *git init:* Initializes an empty Git repository. You cannot use
526 Git commands unless you have a ``.git`` repository.
527
528- *git clone:* Creates a local clone of a Git repository that is on
529 equal footing with a fellow developer's Git repository or an upstream
530 repository.
531
532- *git add:* Locally stages updated file contents to the index that
533 Git uses to track changes. You must stage all files that have changed
534 before you can commit them.
535
536- *git commit:* Creates a local "commit" that documents the changes
537 you made. Only changes that have been staged can be committed.
538 Commits are used for historical purposes, for determining if a
539 maintainer of a project will allow the change, and for ultimately
540 pushing the change from your local Git repository into the project's
541 upstream repository.
542
543- *git status:* Reports any modified files that possibly need to be
544 staged and gives you a status of where you stand regarding local
545 commits as compared to the upstream repository.
546
547- *git checkout branch-name:* Changes your local working branch and
548 in this form assumes the local branch already exists. This command is
549 analogous to "cd".
550
551- *git checkout –b working-branch upstream-branch:* Creates and
552 checks out a working branch on your local machine. The local branch
553 tracks the upstream branch. You can use your local branch to isolate
554 your work. It is a good idea to use local branches when adding
555 specific features or changes. Using isolated branches facilitates
556 easy removal of changes if they do not work out.
557
558- *git branch:* Displays the existing local branches associated
559 with your local repository. The branch that you have currently
560 checked out is noted with an asterisk character.
561
562- *git branch -D branch-name:* Deletes an existing local branch.
563 You need to be in a local branch other than the one you are deleting
564 in order to delete branch-name.
565
566- *git pull --rebase:* Retrieves information from an upstream Git
567 repository and places it in your local Git repository. You use this
568 command to make sure you are synchronized with the repository from
569 which you are basing changes (.e.g. the "master" branch). The
570 "--rebase" option ensures that any local commits you have in your
571 branch are preserved at the top of your local branch.
572
573- *git push repo-name local-branch:upstream-branch:* Sends
574 all your committed local changes to the upstream Git repository that
575 your local repository is tracking (e.g. a contribution repository).
576 The maintainer of the project draws from these repositories to merge
577 changes (commits) into the appropriate branch of project's upstream
578 repository.
579
580- *git merge:* Combines or adds changes from one local branch of
581 your repository with another branch. When you create a local Git
582 repository, the default branch is named "master". A typical workflow
583 is to create a temporary branch that is based off "master" that you
584 would use for isolated work. You would make your changes in that
585 isolated branch, stage and commit them locally, switch to the
586 "master" branch, and then use the ``git merge`` command to apply the
587 changes from your isolated branch into the currently checked out
588 branch (e.g. "master"). After the merge is complete and if you are
589 done with working in that isolated branch, you can safely delete the
590 isolated branch.
591
592- *git cherry-pick commits:* Choose and apply specific commits from
593 one branch into another branch. There are times when you might not be
594 able to merge all the changes in one branch with another but need to
595 pick out certain ones.
596
597- *gitk:* Provides a GUI view of the branches and changes in your
598 local Git repository. This command is a good way to graphically see
599 where things have diverged in your local repository.
600
601 .. note::
602
603 You need to install the
604 gitk
605 package on your development system to use this command.
606
607- *git log:* Reports a history of your commits to the repository.
608 This report lists all commits regardless of whether you have pushed
609 them upstream or not.
610
611- *git diff:* Displays line-by-line differences between a local
612 working file and the same file as understood by Git. This command is
613 useful to see what you have changed in any given file.
614
615Licensing
616=========
617
618Because open source projects are open to the public, they have different
619licensing structures in place. License evolution for both Open Source
620and Free Software has an interesting history. If you are interested in
621this history, you can find basic information here:
622
623- `Open source license
624 history <http://en.wikipedia.org/wiki/Open-source_license>`__
625
626- `Free software license
627 history <http://en.wikipedia.org/wiki/Free_software_license>`__
628
629In general, the Yocto Project is broadly licensed under the
630Massachusetts Institute of Technology (MIT) License. MIT licensing
631permits the reuse of software within proprietary software as long as the
632license is distributed with that software. MIT is also compatible with
633the GNU General Public License (GPL). Patches to the Yocto Project
634follow the upstream licensing scheme. You can find information on the
635MIT license
636`here <http://www.opensource.org/licenses/mit-license.php>`__. You can
637find information on the GNU GPL
638`here <http://www.opensource.org/licenses/LGPL-3.0>`__.
639
640When you build an image using the Yocto Project, the build process uses
641a known list of licenses to ensure compliance. You can find this list in
642the :term:`Source Directory` at
643``meta/files/common-licenses``. Once the build completes, the list of
644all licenses found and used during that build are kept in the
645:term:`Build Directory` at
646``tmp/deploy/licenses``.
647
648If a module requires a license that is not in the base list, the build
649process generates a warning during the build. These tools make it easier
650for a developer to be certain of the licenses with which their shipped
651products must comply. However, even with these tools it is still up to
652the developer to resolve potential licensing issues.
653
654The base list of licenses used by the build process is a combination of
655the Software Package Data Exchange (SPDX) list and the Open Source
656Initiative (OSI) projects. `SPDX Group <http://spdx.org>`__ is a working
657group of the Linux Foundation that maintains a specification for a
658standard format for communicating the components, licenses, and
659copyrights associated with a software package.
660`OSI <http://opensource.org>`__ is a corporation dedicated to the Open
661Source Definition and the effort for reviewing and approving licenses
662that conform to the Open Source Definition (OSD).
663
664You can find a list of the combined SPDX and OSI licenses that the Yocto
665Project uses in the ``meta/files/common-licenses`` directory in your
666:term:`Source Directory`.
667
668For information that can help you maintain compliance with various open
669source licensing during the lifecycle of a product created using the
670Yocto Project, see the
671":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
672section in the Yocto Project Development Tasks Manual.