blob: a33f89e4fa89639f7a5da09dc542c0da11b59f47 [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
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500160 for supported BSPs (e.g., ``meta-intel``) is to use
161 :ref:`overview-manual/development-environment:git`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500162 to create a local copy of the upstream repositories.
163
164 - Be sure to always work in matching branches for both the selected
165 BSP repository and the Source Directory (i.e. ``poky``)
166 repository. For example, if you have checked out the "master"
167 branch of ``poky`` and you are going to use ``meta-intel``, be
168 sure to checkout the "master" branch of ``meta-intel``.
169
170In summary, here is where you can get the project files needed for
171development:
172
173- :yocto_git:`Source Repositories: <>` This area contains IDE
174 Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and
175 Yocto Metadata Layers. You can create local copies of Git
176 repositories for each of these areas.
177
178 .. image:: figures/source-repos.png
179 :align: center
180
181 For steps on how to view and access these upstream Git repositories,
Andrew Geissler09209ee2020-12-13 08:44:15 -0600182 see the ":ref:`dev-manual/start:accessing source repositories`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500183 Section in the Yocto Project Development Tasks Manual.
184
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500185- :yocto_dl:`Index of /releases: </releases>` This is an index
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500186 of releases such as Poky, Pseudo, installers for cross-development
187 toolchains, miscellaneous support and all released versions of Yocto
188 Project in the form of images or tarballs. Downloading and extracting
189 these files does not produce a local copy of the Git repository but
190 rather a snapshot of a particular release or image.
191
192 .. image:: figures/index-downloads.png
193 :align: center
194
195 For steps on how to view and access these files, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600196 ":ref:`dev-manual/start:accessing index of releases`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500197 section in the Yocto Project Development Tasks Manual.
198
199- *"DOWNLOADS" page for the* :yocto_home:`Yocto Project Website <>` *:*
200
201 The Yocto Project website includes a "DOWNLOADS" page accessible
202 through the "SOFTWARE" menu that allows you to download any Yocto
203 Project release, tool, and Board Support Package (BSP) in tarball
204 form. The tarballs are similar to those found in the
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500205 :yocto_dl:`Index of /releases: </releases>` area.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500206
207 .. image:: figures/yp-download.png
208 :align: center
209
210 For steps on how to use the "DOWNLOADS" page, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600211 ":ref:`dev-manual/start:using the downloads page`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500212 section in the Yocto Project Development Tasks Manual.
213
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500214Git Workflows and the Yocto Project
215===================================
216
217Developing using the Yocto Project likely requires the use of
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500218:ref:`overview-manual/development-environment:git`.
219Git is a free, open source distributed version control
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500220system used as part of many collaborative design environments. This
221section provides workflow concepts using the Yocto Project and Git. In
222particular, the information covers basic practices that describe roles
223and actions in a collaborative development environment.
224
225.. note::
226
227 If you are familiar with this type of development environment, you
228 might not want to read this section.
229
230The Yocto Project files are maintained using Git in "branches" whose Git
231histories track every change and whose structures provide branches for
232all diverging functionality. Although there is no need to use Git, many
233open source projects do so.
234
235For the Yocto Project, a key individual called the "maintainer" is
236responsible for the integrity of the "master" branch of a given Git
237repository. The "master" branch is the "upstream" repository from which
238final or most recent builds of a project occur. The maintainer is
239responsible for accepting changes from other developers and for
240organizing the underlying branch structure to reflect release strategies
241and so forth.
242
243.. note::
244
245 For information on finding out who is responsible for (maintains) a
246 particular area of code in the Yocto Project, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600247 ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500248 section of the Yocto Project Development Tasks Manual.
249
250The Yocto Project ``poky`` Git repository also has an upstream
251contribution Git repository named ``poky-contrib``. You can see all the
252branches in this repository using the web interface of the
253:yocto_git:`Source Repositories <>` organized within the "Poky Support"
254area. These branches hold changes (commits) to the project that have
255been submitted or committed by the Yocto Project development team and by
256community members who contribute to the project. The maintainer
257determines if the changes are qualified to be moved from the "contrib"
258branches into the "master" branch of the Git repository.
259
260Developers (including contributing community members) create and
261maintain cloned repositories of upstream branches. The cloned
262repositories are local to their development platforms and are used to
263develop changes. When a developer is satisfied with a particular feature
264or change, they "push" the change to the appropriate "contrib"
265repository.
266
267Developers are responsible for keeping their local repository up-to-date
268with whatever upstream branch they are working against. They are also
269responsible for straightening out any conflicts that might arise within
270files that are being worked on simultaneously by more than one person.
271All this work is done locally on the development host before anything is
272pushed to a "contrib" area and examined at the maintainer's level.
273
274A somewhat formal method exists by which developers commit changes and
275push them into the "contrib" area and subsequently request that the
276maintainer include them into an upstream branch. This process is called
277"submitting a patch" or "submitting a change." For information on
278submitting patches and changes, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600279":ref:`dev-manual/common-tasks:submitting a change to the yocto project`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500280section in the Yocto Project Development Tasks Manual.
281
282In summary, a single point of entry exists for changes into a "master"
283or development branch of the Git repository, which is controlled by the
284project's maintainer. And, a set of developers exist who independently
285develop, test, and submit changes to "contrib" areas for the maintainer
286to examine. The maintainer then chooses which changes are going to
287become a permanent part of the project.
288
289.. image:: figures/git-workflow.png
290 :align: center
291
292While each development environment is unique, there are some best
293practices or methods that help development run smoothly. The following
294list describes some of these practices. For more information about Git
295workflows, see the workflow topics in the `Git Community
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600296Book <https://book.git-scm.com>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500297
298- *Make Small Changes:* It is best to keep the changes you commit small
299 as compared to bundling many disparate changes into a single commit.
300 This practice not only keeps things manageable but also allows the
301 maintainer to more easily include or refuse changes.
302
303- *Make Complete Changes:* It is also good practice to leave the
304 repository in a state that allows you to still successfully build
305 your project. In other words, do not commit half of a feature, then
306 add the other half as a separate, later commit. Each commit should
307 take you from one buildable project state to another buildable state.
308
309- *Use Branches Liberally:* It is very easy to create, use, and delete
310 local branches in your working Git repository on the development
311 host. You can name these branches anything you like. It is helpful to
312 give them names associated with the particular feature or change on
313 which you are working. Once you are done with a feature or change and
314 have merged it into your local master branch, simply discard the
315 temporary branch.
316
317- *Merge Changes:* The ``git merge`` command allows you to take the
318 changes from one branch and fold them into another branch. This
319 process is especially helpful when more than a single developer might
320 be working on different parts of the same feature. Merging changes
321 also automatically identifies any collisions or "conflicts" that
322 might happen as a result of the same lines of code being altered by
323 two different developers.
324
325- *Manage Branches:* Because branches are easy to use, you should use a
326 system where branches indicate varying levels of code readiness. For
327 example, you can have a "work" branch to develop in, a "test" branch
328 where the code or change is tested, a "stage" branch where changes
329 are ready to be committed, and so forth. As your project develops,
330 you can merge code across the branches to reflect ever-increasing
331 stable states of the development.
332
333- *Use Push and Pull:* The push-pull workflow is based on the concept
334 of developers "pushing" local commits to a remote repository, which
335 is usually a contribution repository. This workflow is also based on
336 developers "pulling" known states of the project down into their
337 local development repositories. The workflow easily allows you to
338 pull changes submitted by other developers from the upstream
339 repository into your work area ensuring that you have the most recent
340 software on which to develop. The Yocto Project has two scripts named
341 ``create-pull-request`` and ``send-pull-request`` that ship with the
342 release to facilitate this workflow. You can find these scripts in
343 the ``scripts`` folder of the
344 :term:`Source Directory`. For information
345 on how to use these scripts, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600346 ":ref:`dev-manual/common-tasks:using scripts to push a change upstream and request a pull`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500347 section in the Yocto Project Development Tasks Manual.
348
349- *Patch Workflow:* This workflow allows you to notify the maintainer
350 through an email that you have a change (or patch) you would like
351 considered for the "master" branch of the Git repository. To send
352 this type of change, you format the patch and then send the email
353 using the Git commands ``git format-patch`` and ``git send-email``.
354 For information on how to use these scripts, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600355 ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500356 section in the Yocto Project Development Tasks Manual.
357
358Git
359===
360
361The Yocto Project makes extensive use of Git, which is a free, open
362source distributed version control system. Git supports distributed
363development, non-linear development, and can handle large projects. It
364is best that you have some fundamental understanding of how Git tracks
365projects and how to work with Git if you are going to use the Yocto
366Project for development. This section provides a quick overview of how
367Git works and provides you with a summary of some essential Git
368commands.
369
370.. note::
371
372 - For more information on Git, see
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600373 https://git-scm.com/documentation.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500374
375 - If you need to download Git, it is recommended that you add Git to
376 your system through your distribution's "software store" (e.g. for
377 Ubuntu, use the Ubuntu Software feature). For the Git download
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600378 page, see https://git-scm.com/download.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500379
380 - For information beyond the introductory nature in this section,
Andrew Geissler09209ee2020-12-13 08:44:15 -0600381 see the ":ref:`dev-manual/start:locating yocto project source files`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500382 section in the Yocto Project Development Tasks Manual.
383
384Repositories, Tags, and Branches
385--------------------------------
386
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500387As mentioned briefly in the previous section and also in the
388":ref:`overview-manual/development-environment:git workflows and the yocto project`"
389section, the Yocto Project maintains source repositories at :yocto_git:`/`.
390If you look at this web-interface of the repositories, each item is a separate
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500391Git repository.
392
393Git repositories use branching techniques that track content change (not
394files) within a project (e.g. a new feature or updated documentation).
395Creating a tree-like structure based on project divergence allows for
396excellent historical information over the life of a project. This
397methodology also allows for an environment from which you can do lots of
398local experimentation on projects as you develop changes or new
399features.
400
401A Git repository represents all development efforts for a given project.
402For example, the Git repository ``poky`` contains all changes and
403developments for that repository over the course of its entire life.
404That means that all changes that make up all releases are captured. The
405repository maintains a complete history of changes.
406
407You can create a local copy of any repository by "cloning" it with the
408``git clone`` command. When you clone a Git repository, you end up with
409an identical copy of the repository on your development system. Once you
410have a local copy of a repository, you can take steps to develop
411locally. For examples on how to clone Git repositories, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600412":ref:`dev-manual/start:locating yocto project source files`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500413section in the Yocto Project Development Tasks Manual.
414
415It is important to understand that Git tracks content change and not
416files. Git uses "branches" to organize different development efforts.
417For example, the ``poky`` repository has several branches that include
418the current "&DISTRO_NAME_NO_CAP;" branch, the "master" branch, and many
419branches for past Yocto Project releases. You can see all the branches
Andrew Geissler09209ee2020-12-13 08:44:15 -0600420by going to :yocto_git:`/poky/` and clicking on the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500421``[...]`` link beneath the "Branch" heading.
422
423Each of these branches represents a specific area of development. The
424"master" branch represents the current or most recent development. All
425other branches represent offshoots of the "master" branch.
426
427When you create a local copy of a Git repository, the copy has the same
428set of branches as the original. This means you can use Git to create a
429local working area (also called a branch) that tracks a specific
430development branch from the upstream source Git repository. in other
431words, you can define your local Git environment to work on any
432development branch in the repository. To help illustrate, consider the
433following example Git commands:
434::
435
436 $ cd ~
437 $ git clone git://git.yoctoproject.org/poky
438 $ cd poky
439 $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
440
441In the previous example
442after moving to the home directory, the ``git clone`` command creates a
443local copy of the upstream ``poky`` Git repository. By default, Git
444checks out the "master" branch for your work. After changing the working
445directory to the new local repository (i.e. ``poky``), the
446``git checkout`` command creates and checks out a local branch named
447"&DISTRO_NAME_NO_CAP;", which tracks the upstream
448"origin/&DISTRO_NAME_NO_CAP;" branch. Changes you make while in this
449branch would ultimately affect the upstream "&DISTRO_NAME_NO_CAP;" branch
450of the ``poky`` repository.
451
452It is important to understand that when you create and checkout a local
453working branch based on a branch name, your local environment matches
454the "tip" of that particular development branch at the time you created
455your local branch, which could be different from the files in the
456"master" branch of the upstream repository. In other words, creating and
457checking out a local branch based on the "&DISTRO_NAME_NO_CAP;" branch
458name is not the same as checking out the "master" branch in the
459repository. Keep reading to see how you create a local snapshot of a
460Yocto Project Release.
461
462Git uses "tags" to mark specific changes in a repository branch
463structure. Typically, a tag is used to mark a special point such as the
464final change (or commit) before a project is released. You can see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600465tags used with the ``poky`` Git repository by going to :yocto_git:`/poky/`
466and clicking on the ``[...]`` link beneath the "Tag" heading.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500467
468Some key tags for the ``poky`` repository are ``jethro-14.0.3``,
469``morty-16.0.1``, ``pyro-17.0.0``, and
470``&DISTRO_NAME_NO_CAP;-&POKYVERSION;``. These tags represent Yocto Project
471releases.
472
473When you create a local copy of the Git repository, you also have access
474to all the tags in the upstream repository. Similar to branches, you can
475create and checkout a local working Git branch based on a tag name. When
476you do this, you get a snapshot of the Git repository that reflects the
477state of the files when the change was made associated with that tag.
478The most common use is to checkout a working branch that matches a
479specific Yocto Project release. Here is an example:
480::
481
482 $ cd ~
483 $ git clone git://git.yoctoproject.org/poky
484 $ cd poky
485 $ git fetch --tags
486 $ git checkout tags/rocko-18.0.0 -b my_rocko-18.0.0
487
488In this example, the name
489of the top-level directory of your local Yocto Project repository is
490``poky``. After moving to the ``poky`` directory, the ``git fetch``
491command makes all the upstream tags available locally in your
492repository. Finally, the ``git checkout`` command creates and checks out
493a branch named "my-rocko-18.0.0" that is based on the upstream branch
494whose "HEAD" matches the commit in the repository associated with the
495"rocko-18.0.0" tag. The files in your repository now exactly match that
496particular Yocto Project release as it is tagged in the upstream Git
497repository. It is important to understand that when you create and
498checkout a local working branch based on a tag, your environment matches
499a specific point in time and not the entire development branch (i.e.
500from the "tip" of the branch backwards).
501
502Basic Commands
503--------------
504
505Git has an extensive set of commands that lets you manage changes and
506perform collaboration over the life of a project. Conveniently though,
507you can manage with a small set of basic operations and workflows once
508you understand the basic philosophy behind Git. You do not have to be an
509expert in Git to be functional. A good place to look for instruction on
510a minimal set of Git commands is
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600511`here <https://git-scm.com/documentation>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500512
513The following list of Git commands briefly describes some basic Git
514operations as a way to get started. As with any set of commands, this
515list (in most cases) simply shows the base command and omits the many
516arguments it supports. See the Git documentation for complete
517descriptions and strategies on how to use these commands:
518
519- *git init:* Initializes an empty Git repository. You cannot use
520 Git commands unless you have a ``.git`` repository.
521
522- *git clone:* Creates a local clone of a Git repository that is on
523 equal footing with a fellow developer's Git repository or an upstream
524 repository.
525
526- *git add:* Locally stages updated file contents to the index that
527 Git uses to track changes. You must stage all files that have changed
528 before you can commit them.
529
530- *git commit:* Creates a local "commit" that documents the changes
531 you made. Only changes that have been staged can be committed.
532 Commits are used for historical purposes, for determining if a
533 maintainer of a project will allow the change, and for ultimately
534 pushing the change from your local Git repository into the project's
535 upstream repository.
536
537- *git status:* Reports any modified files that possibly need to be
538 staged and gives you a status of where you stand regarding local
539 commits as compared to the upstream repository.
540
541- *git checkout branch-name:* Changes your local working branch and
542 in this form assumes the local branch already exists. This command is
543 analogous to "cd".
544
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500545- *git checkout -b working-branch upstream-branch:* Creates and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500546 checks out a working branch on your local machine. The local branch
547 tracks the upstream branch. You can use your local branch to isolate
548 your work. It is a good idea to use local branches when adding
549 specific features or changes. Using isolated branches facilitates
550 easy removal of changes if they do not work out.
551
552- *git branch:* Displays the existing local branches associated
553 with your local repository. The branch that you have currently
554 checked out is noted with an asterisk character.
555
556- *git branch -D branch-name:* Deletes an existing local branch.
557 You need to be in a local branch other than the one you are deleting
558 in order to delete branch-name.
559
560- *git pull --rebase:* Retrieves information from an upstream Git
561 repository and places it in your local Git repository. You use this
562 command to make sure you are synchronized with the repository from
563 which you are basing changes (.e.g. the "master" branch). The
564 "--rebase" option ensures that any local commits you have in your
565 branch are preserved at the top of your local branch.
566
567- *git push repo-name local-branch:upstream-branch:* Sends
568 all your committed local changes to the upstream Git repository that
569 your local repository is tracking (e.g. a contribution repository).
570 The maintainer of the project draws from these repositories to merge
571 changes (commits) into the appropriate branch of project's upstream
572 repository.
573
574- *git merge:* Combines or adds changes from one local branch of
575 your repository with another branch. When you create a local Git
576 repository, the default branch is named "master". A typical workflow
577 is to create a temporary branch that is based off "master" that you
578 would use for isolated work. You would make your changes in that
579 isolated branch, stage and commit them locally, switch to the
580 "master" branch, and then use the ``git merge`` command to apply the
581 changes from your isolated branch into the currently checked out
582 branch (e.g. "master"). After the merge is complete and if you are
583 done with working in that isolated branch, you can safely delete the
584 isolated branch.
585
586- *git cherry-pick commits:* Choose and apply specific commits from
587 one branch into another branch. There are times when you might not be
588 able to merge all the changes in one branch with another but need to
589 pick out certain ones.
590
591- *gitk:* Provides a GUI view of the branches and changes in your
592 local Git repository. This command is a good way to graphically see
593 where things have diverged in your local repository.
594
595 .. note::
596
597 You need to install the
598 gitk
599 package on your development system to use this command.
600
601- *git log:* Reports a history of your commits to the repository.
602 This report lists all commits regardless of whether you have pushed
603 them upstream or not.
604
605- *git diff:* Displays line-by-line differences between a local
606 working file and the same file as understood by Git. This command is
607 useful to see what you have changed in any given file.
608
609Licensing
610=========
611
612Because open source projects are open to the public, they have different
613licensing structures in place. License evolution for both Open Source
614and Free Software has an interesting history. If you are interested in
615this history, you can find basic information here:
616
617- `Open source license
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600618 history <https://en.wikipedia.org/wiki/Open-source_license>`__
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500619
620- `Free software license
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600621 history <https://en.wikipedia.org/wiki/Free_software_license>`__
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500622
623In general, the Yocto Project is broadly licensed under the
624Massachusetts Institute of Technology (MIT) License. MIT licensing
625permits the reuse of software within proprietary software as long as the
626license is distributed with that software. MIT is also compatible with
627the GNU General Public License (GPL). Patches to the Yocto Project
628follow the upstream licensing scheme. You can find information on the
629MIT license
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600630`here <https://www.opensource.org/licenses/mit-license.php>`__. You can
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500631find information on the GNU GPL
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600632`here <https://www.opensource.org/licenses/LGPL-3.0>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500633
634When you build an image using the Yocto Project, the build process uses
635a known list of licenses to ensure compliance. You can find this list in
636the :term:`Source Directory` at
637``meta/files/common-licenses``. Once the build completes, the list of
638all licenses found and used during that build are kept in the
639:term:`Build Directory` at
640``tmp/deploy/licenses``.
641
642If a module requires a license that is not in the base list, the build
643process generates a warning during the build. These tools make it easier
644for a developer to be certain of the licenses with which their shipped
645products must comply. However, even with these tools it is still up to
646the developer to resolve potential licensing issues.
647
648The base list of licenses used by the build process is a combination of
649the Software Package Data Exchange (SPDX) list and the Open Source
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600650Initiative (OSI) projects. `SPDX Group <https://spdx.org>`__ is a working
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500651group of the Linux Foundation that maintains a specification for a
652standard format for communicating the components, licenses, and
653copyrights associated with a software package.
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600654`OSI <https://opensource.org>`__ is a corporation dedicated to the Open
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500655Source Definition and the effort for reviewing and approving licenses
656that conform to the Open Source Definition (OSD).
657
658You can find a list of the combined SPDX and OSI licenses that the Yocto
659Project uses in the ``meta/files/common-licenses`` directory in your
660:term:`Source Directory`.
661
662For information that can help you maintain compliance with various open
663source licensing during the lifecycle of a product created using the
664Yocto Project, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600665":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500666section in the Yocto Project Development Tasks Manual.