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