blob: 7d5953db337cf1ceca5d7cb78ca23e527ec471c2 [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
Patrick Williams7784c422022-11-17 07:29:11 -060042Wikipedia has a good :wikipedia:`historical description of the Open Source
43Philosophy <Open_source>`. You can also find helpful information on how
44to participate in the Linux Community
Andrew Geisslerc3d88e42020-10-02 09:45:00 -050045`here <https://www.kernel.org/doc/html/latest/process/index.html>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050046
Andrew Geisslerc9f78652020-09-18 14:11:35 -050047The Development Host
48====================
49
50A development host or :term:`Build Host` is key to
51using the Yocto Project. Because the goal of the Yocto Project is to
52develop images or applications that run on embedded hardware,
53development of those images and applications generally takes place on a
Andrew Geissler615f2f12022-07-15 14:00:58 -050054system not intended to run the software --- the development host.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050055
56You need to set up a development host in order to use it with the Yocto
57Project. Most find that it is best to have a native Linux machine
58function as the development host. However, it is possible to use a
59system that does not run Linux as its operating system as your
60development host. When you have a Mac or Windows-based system, you can
61set it up as the development host by using
62`CROPS <https://github.com/crops/poky-container>`__, which leverages
63`Docker Containers <https://www.docker.com/>`__. Once you take the steps
64to set up a CROPS machine, you effectively have access to a shell
65environment that is similar to what you see when using a Linux-based
66development host. For the steps needed to set up a system using CROPS,
67see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060068":ref:`dev-manual/start:setting up to use cross platforms (crops)`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050069section in
70the Yocto Project Development Tasks Manual.
71
72If your development host is going to be a system that runs a Linux
William A. Kennington IIIac69b482021-06-02 12:28:27 -070073distribution, you must still take steps to prepare the system
Andrew Geisslerc9f78652020-09-18 14:11:35 -050074for use with the Yocto Project. You need to be sure that the Linux
75distribution on the system is one that supports the Yocto Project. You
76also need to be sure that the correct set of host packages are installed
77that allow development using the Yocto Project. For the steps needed to
78set up a development host that runs Linux, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060079":ref:`dev-manual/start:setting up a native linux host`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050080section in the Yocto Project Development Tasks Manual.
81
William A. Kennington IIIac69b482021-06-02 12:28:27 -070082Once your development host is set up to use the Yocto Project, there
83are several ways of working in the Yocto Project environment:
Andrew Geisslerc9f78652020-09-18 14:11:35 -050084
85- *Command Lines, BitBake, and Shells:* Traditional development in the
86 Yocto Project involves using the :term:`OpenEmbedded Build System`,
87 which uses
88 BitBake, in a command-line environment from a shell on your
89 development host. You can accomplish this from a host that is a
90 native Linux machine or from a host that has been set up with CROPS.
91 Either way, you create, modify, and build images and applications all
92 within a shell-based environment using components and tools available
93 through your Linux distribution and the Yocto Project.
94
95 For a general flow of the build procedures, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060096 ":ref:`dev-manual/common-tasks:building a simple image`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050097 section in the Yocto Project Development Tasks Manual.
98
99- *Board Support Package (BSP) Development:* Development of BSPs
100 involves using the Yocto Project to create and test layers that allow
101 easy development of images and applications targeted for specific
102 hardware. To development BSPs, you need to take some additional steps
103 beyond what was described in setting up a development host.
104
Andrew Geissler09209ee2020-12-13 08:44:15 -0600105 The :doc:`/bsp-guide/index` provides BSP-related development
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500106 information. For specifics on development host preparation, see the
107 ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`"
108 section in the Yocto Project Board Support Package (BSP) Developer's
109 Guide.
110
111- *Kernel Development:* If you are going to be developing kernels using
112 the Yocto Project you likely will be using ``devtool``. A workflow
113 using ``devtool`` makes kernel development quicker by reducing
114 iteration cycle times.
115
Andrew Geissler09209ee2020-12-13 08:44:15 -0600116 The :doc:`/kernel-dev/index` provides kernel-related
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500117 development information. For specifics on development host
118 preparation, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600119 ":ref:`kernel-dev/common:preparing the build host to work on the kernel`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500120 section in the Yocto Project Linux Kernel Development Manual.
121
122- *Using Toaster:* The other Yocto Project development method that
123 involves an interface that effectively puts the Yocto Project into
124 the background is Toaster. Toaster provides an interface to the
125 OpenEmbedded build system. The interface enables you to configure and
126 run your builds. Information about builds is collected and stored in
127 a database. You can use Toaster to configure and start builds on
128 multiple remote build servers.
129
130 For steps that show you how to set up your development host to use
131 Toaster and on how to use Toaster in general, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600132 :doc:`/toaster-manual/index`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500133
134Yocto Project Source Repositories
135=================================
136
137The Yocto Project team maintains complete source repositories for all
138Yocto Project files at :yocto_git:`/`. This web-based source
139code browser is organized into categories by function such as IDE
140Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. From the
141interface, you can click on any particular item in the "Name" column and
142see the URL at the bottom of the page that you need to clone a Git
143repository for that particular item. Having a local Git repository of
144the :term:`Source Directory`, which
145is usually named "poky", allows you to make changes, contribute to the
146history, and ultimately enhance the Yocto Project's tools, Board Support
147Packages, and so forth.
148
149For any supported release of Yocto Project, you can also go to the
150:yocto_home:`Yocto Project Website <>` and select the "DOWNLOADS"
151item from the "SOFTWARE" menu and get a released tarball of the ``poky``
152repository, any supported BSP tarball, or Yocto Project tools. Unpacking
153these tarballs gives you a snapshot of the released files.
154
155.. note::
156
157 - The recommended method for setting up the Yocto Project
158 :term:`Source Directory` and the files
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500159 for supported BSPs (e.g., ``meta-intel``) is to use
160 :ref:`overview-manual/development-environment:git`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500161 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``)
Andrew Geissler595f6302022-01-24 19:11:47 +0000165 repository. For example, if you have checked out the "&DISTRO_NAME_NO_CAP;"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500166 branch of ``poky`` and you are going to use ``meta-intel``, be
Andrew Geissler595f6302022-01-24 19:11:47 +0000167 sure to checkout the "&DISTRO_NAME_NO_CAP;" branch of ``meta-intel``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500168
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
Andrew Geisslerd5838332022-05-27 11:33:10 -0500178 :width: 100%
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500179
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
Andrew Geisslerd5838332022-05-27 11:33:10 -0500193 :width: 50%
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500194
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
Andrew Geisslerd5838332022-05-27 11:33:10 -0500208 :width: 100%
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500209
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
Andrew Geissler595f6302022-01-24 19:11:47 +0000236responsible for the integrity of the development branch of a given Git
237repository. The development branch is the "upstream" repository from which
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500238final 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
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700274There is a somewhat formal method by which developers commit changes and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500275push 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
Andrew Geissler595f6302022-01-24 19:11:47 +0000282In summary, there is a single point of entry for changes into the
283development branch of the Git repository, which is controlled by the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700284project's maintainer. A set of developers independently
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500285develop, 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
Andrew Geisslereff27472021-10-29 15:35:00 -0500289.. image:: svg/git-workflow.*
290 :width: 100%
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500291
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
Andrew Geissler595f6302022-01-24 19:11:47 +0000314 have merged it into your local development branch, simply discard the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500315 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
Andrew Geissler595f6302022-01-24 19:11:47 +0000351 considered for the development branch of the Git repository. To send
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500352 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
Patrick Williams45852732022-04-02 08:58:32 -0500430development branch from the upstream source Git repository. In other
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500431words, you can define your local Git environment to work on any
432development branch in the repository. To help illustrate, consider the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500433following example Git commands::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500434
435 $ cd ~
Andrew Geissler595f6302022-01-24 19:11:47 +0000436 $ git clone git://git.yoctoproject.org/poky -b &DISTRO_NAME_NO_CAP;
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500437
438In the previous example
439after moving to the home directory, the ``git clone`` command creates a
Andrew Geissler595f6302022-01-24 19:11:47 +0000440local copy of the upstream ``poky`` Git repository and checks out a
441local branch named "&DISTRO_NAME_NO_CAP;", which tracks the upstream
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500442"origin/&DISTRO_NAME_NO_CAP;" branch. Changes you make while in this
443branch would ultimately affect the upstream "&DISTRO_NAME_NO_CAP;" branch
444of the ``poky`` repository.
445
446It is important to understand that when you create and checkout a local
447working branch based on a branch name, your local environment matches
448the "tip" of that particular development branch at the time you created
449your local branch, which could be different from the files in the
450"master" branch of the upstream repository. In other words, creating and
451checking out a local branch based on the "&DISTRO_NAME_NO_CAP;" branch
452name is not the same as checking out the "master" branch in the
453repository. Keep reading to see how you create a local snapshot of a
454Yocto Project Release.
455
456Git uses "tags" to mark specific changes in a repository branch
457structure. Typically, a tag is used to mark a special point such as the
458final change (or commit) before a project is released. You can see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600459tags used with the ``poky`` Git repository by going to :yocto_git:`/poky/`
460and clicking on the ``[...]`` link beneath the "Tag" heading.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500461
462Some key tags for the ``poky`` repository are ``jethro-14.0.3``,
463``morty-16.0.1``, ``pyro-17.0.0``, and
Andrew Geissler9aee5002022-03-30 16:27:02 +0000464``&DISTRO_NAME_NO_CAP;-&DISTRO;``. These tags represent Yocto Project
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500465releases.
466
467When you create a local copy of the Git repository, you also have access
468to all the tags in the upstream repository. Similar to branches, you can
469create and checkout a local working Git branch based on a tag name. When
470you do this, you get a snapshot of the Git repository that reflects the
471state of the files when the change was made associated with that tag.
472The most common use is to checkout a working branch that matches a
Andrew Geisslerc926e172021-05-07 16:11:35 -0500473specific Yocto Project release. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500474
475 $ cd ~
476 $ git clone git://git.yoctoproject.org/poky
477 $ cd poky
478 $ git fetch --tags
479 $ git checkout tags/rocko-18.0.0 -b my_rocko-18.0.0
480
481In this example, the name
482of the top-level directory of your local Yocto Project repository is
483``poky``. After moving to the ``poky`` directory, the ``git fetch``
484command makes all the upstream tags available locally in your
485repository. Finally, the ``git checkout`` command creates and checks out
486a branch named "my-rocko-18.0.0" that is based on the upstream branch
487whose "HEAD" matches the commit in the repository associated with the
488"rocko-18.0.0" tag. The files in your repository now exactly match that
489particular Yocto Project release as it is tagged in the upstream Git
490repository. It is important to understand that when you create and
491checkout a local working branch based on a tag, your environment matches
492a specific point in time and not the entire development branch (i.e.
493from the "tip" of the branch backwards).
494
495Basic Commands
496--------------
497
498Git has an extensive set of commands that lets you manage changes and
499perform collaboration over the life of a project. Conveniently though,
500you can manage with a small set of basic operations and workflows once
501you understand the basic philosophy behind Git. You do not have to be an
502expert in Git to be functional. A good place to look for instruction on
503a minimal set of Git commands is
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600504`here <https://git-scm.com/documentation>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500505
506The following list of Git commands briefly describes some basic Git
507operations as a way to get started. As with any set of commands, this
508list (in most cases) simply shows the base command and omits the many
509arguments it supports. See the Git documentation for complete
510descriptions and strategies on how to use these commands:
511
512- *git init:* Initializes an empty Git repository. You cannot use
513 Git commands unless you have a ``.git`` repository.
514
515- *git clone:* Creates a local clone of a Git repository that is on
516 equal footing with a fellow developer's Git repository or an upstream
517 repository.
518
519- *git add:* Locally stages updated file contents to the index that
520 Git uses to track changes. You must stage all files that have changed
521 before you can commit them.
522
523- *git commit:* Creates a local "commit" that documents the changes
524 you made. Only changes that have been staged can be committed.
525 Commits are used for historical purposes, for determining if a
526 maintainer of a project will allow the change, and for ultimately
527 pushing the change from your local Git repository into the project's
528 upstream repository.
529
530- *git status:* Reports any modified files that possibly need to be
531 staged and gives you a status of where you stand regarding local
532 commits as compared to the upstream repository.
533
534- *git checkout branch-name:* Changes your local working branch and
535 in this form assumes the local branch already exists. This command is
536 analogous to "cd".
537
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500538- *git checkout -b working-branch upstream-branch:* Creates and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500539 checks out a working branch on your local machine. The local branch
540 tracks the upstream branch. You can use your local branch to isolate
541 your work. It is a good idea to use local branches when adding
542 specific features or changes. Using isolated branches facilitates
543 easy removal of changes if they do not work out.
544
545- *git branch:* Displays the existing local branches associated
546 with your local repository. The branch that you have currently
547 checked out is noted with an asterisk character.
548
549- *git branch -D branch-name:* Deletes an existing local branch.
550 You need to be in a local branch other than the one you are deleting
551 in order to delete branch-name.
552
Patrick Williams45852732022-04-02 08:58:32 -0500553- *git pull \-\-rebase*: Retrieves information from an upstream Git
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500554 repository and places it in your local Git repository. You use this
555 command to make sure you are synchronized with the repository from
Andrew Geissler595f6302022-01-24 19:11:47 +0000556 which you are basing changes (e.g. the "&DISTRO_NAME_NO_CAP;"
Patrick Williams45852732022-04-02 08:58:32 -0500557 branch). The ``--rebase`` option ensures that any local commits you
Andrew Geissler595f6302022-01-24 19:11:47 +0000558 have in your branch are preserved at the top of your local branch.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500559
560- *git push repo-name local-branch:upstream-branch:* Sends
561 all your committed local changes to the upstream Git repository that
562 your local repository is tracking (e.g. a contribution repository).
563 The maintainer of the project draws from these repositories to merge
564 changes (commits) into the appropriate branch of project's upstream
565 repository.
566
567- *git merge:* Combines or adds changes from one local branch of
568 your repository with another branch. When you create a local Git
Andrew Geissler595f6302022-01-24 19:11:47 +0000569 repository, the default branch may be named "main". A typical
570 workflow is to create a temporary branch that is based off "main"
571 that you would use for isolated work. You would make your changes in
572 that isolated branch, stage and commit them locally, switch to the
573 "main" branch, and then use the ``git merge`` command to apply the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500574 changes from your isolated branch into the currently checked out
Andrew Geissler595f6302022-01-24 19:11:47 +0000575 branch (e.g. "main"). After the merge is complete and if you are
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500576 done with working in that isolated branch, you can safely delete the
577 isolated branch.
578
579- *git cherry-pick commits:* Choose and apply specific commits from
580 one branch into another branch. There are times when you might not be
581 able to merge all the changes in one branch with another but need to
582 pick out certain ones.
583
584- *gitk:* Provides a GUI view of the branches and changes in your
585 local Git repository. This command is a good way to graphically see
586 where things have diverged in your local repository.
587
588 .. note::
589
590 You need to install the
591 gitk
592 package on your development system to use this command.
593
594- *git log:* Reports a history of your commits to the repository.
595 This report lists all commits regardless of whether you have pushed
596 them upstream or not.
597
598- *git diff:* Displays line-by-line differences between a local
599 working file and the same file as understood by Git. This command is
600 useful to see what you have changed in any given file.
601
602Licensing
603=========
604
605Because open source projects are open to the public, they have different
606licensing structures in place. License evolution for both Open Source
607and Free Software has an interesting history. If you are interested in
608this history, you can find basic information here:
609
Patrick Williams7784c422022-11-17 07:29:11 -0600610- :wikipedia:`Open source license history <Open-source_license>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500611
Patrick Williams7784c422022-11-17 07:29:11 -0600612- :wikipedia:`Free software license history <Free_software_license>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500613
614In general, the Yocto Project is broadly licensed under the
615Massachusetts Institute of Technology (MIT) License. MIT licensing
616permits the reuse of software within proprietary software as long as the
Patrick Williams03907ee2022-05-01 06:28:52 -0500617license is distributed with that software. Patches to the Yocto Project
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500618follow the upstream licensing scheme. You can find information on the
Patrick Williams7784c422022-11-17 07:29:11 -0600619MIT license :wikipedia:`here <MIT_License>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500620
621When you build an image using the Yocto Project, the build process uses
622a known list of licenses to ensure compliance. You can find this list in
Patrick Williams2390b1b2022-11-03 13:47:49 -0500623the :term:`Source Directory` at ``meta/files/common-licenses``. Once the
624build completes, the list of all licenses found and used during that build
625are kept in the :term:`Build Directory` at ``tmp/deploy/licenses``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500626
627If a module requires a license that is not in the base list, the build
628process generates a warning during the build. These tools make it easier
629for a developer to be certain of the licenses with which their shipped
630products must comply. However, even with these tools it is still up to
631the developer to resolve potential licensing issues.
632
633The base list of licenses used by the build process is a combination of
634the Software Package Data Exchange (SPDX) list and the Open Source
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600635Initiative (OSI) projects. `SPDX Group <https://spdx.org>`__ is a working
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500636group of the Linux Foundation that maintains a specification for a
637standard format for communicating the components, licenses, and
638copyrights associated with a software package.
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600639`OSI <https://opensource.org>`__ is a corporation dedicated to the Open
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500640Source Definition and the effort for reviewing and approving licenses
641that conform to the Open Source Definition (OSD).
642
643You can find a list of the combined SPDX and OSI licenses that the Yocto
644Project uses in the ``meta/files/common-licenses`` directory in your
645:term:`Source Directory`.
646
647For information that can help you maintain compliance with various open
648source licensing during the lifecycle of a product created using the
649Yocto Project, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600650":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500651section in the Yocto Project Development Tasks Manual.