diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-start.rst')
-rw-r--r-- | documentation/dev-manual/dev-manual-start.rst | 940 |
1 files changed, 940 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-start.rst b/documentation/dev-manual/dev-manual-start.rst new file mode 100644 index 0000000000..d9c1e4de00 --- /dev/null +++ b/documentation/dev-manual/dev-manual-start.rst | |||
@@ -0,0 +1,940 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | *********************************** | ||
4 | Setting Up to Use the Yocto Project | ||
5 | *********************************** | ||
6 | |||
7 | This chapter provides guidance on how to prepare to use the Yocto | ||
8 | Project. You can learn about creating a team environment to develop | ||
9 | using the Yocto Project, how to set up a :ref:`build | ||
10 | host <dev-manual/dev-manual-start:preparing the build host>`, how to locate | ||
11 | Yocto Project source repositories, and how to create local Git | ||
12 | repositories. | ||
13 | |||
14 | .. _usingpoky-changes-collaborate: | ||
15 | |||
16 | Creating a Team Development Environment | ||
17 | ======================================= | ||
18 | |||
19 | It might not be immediately clear how you can use the Yocto Project in a | ||
20 | team development environment, or how to scale it for a large team of | ||
21 | developers. You can adapt the Yocto Project to many different use cases | ||
22 | and scenarios; however, this flexibility could cause difficulties if you | ||
23 | are trying to create a working setup that scales effectively. | ||
24 | |||
25 | To help you understand how to set up this type of environment, this | ||
26 | section presents a procedure that gives you information that can help | ||
27 | you get the results you want. The procedure is high-level and presents | ||
28 | some of the project's most successful experiences, practices, solutions, | ||
29 | and available technologies that have proved to work well in the past; | ||
30 | however, keep in mind, the procedure here is simply a starting point. | ||
31 | You can build off these steps and customize the procedure to fit any | ||
32 | particular working environment and set of practices. | ||
33 | |||
34 | 1. *Determine Who is Going to be Developing:* You first need to | ||
35 | understand who is going to be doing anything related to the Yocto | ||
36 | Project and determine their roles. Making this determination is | ||
37 | essential to completing subsequent steps, which are to get your | ||
38 | equipment together and set up your development environment's | ||
39 | hardware topology. | ||
40 | |||
41 | The following roles exist: | ||
42 | |||
43 | - *Application Developer:* This type of developer does application | ||
44 | level work on top of an existing software stack. | ||
45 | |||
46 | - *Core System Developer:* This type of developer works on the | ||
47 | contents of the operating system image itself. | ||
48 | |||
49 | - *Build Engineer:* This type of developer manages Autobuilders and | ||
50 | releases. Depending on the specifics of the environment, not all | ||
51 | situations might need a Build Engineer. | ||
52 | |||
53 | - *Test Engineer:* This type of developer creates and manages | ||
54 | automated tests that are used to ensure all application and core | ||
55 | system development meets desired quality standards. | ||
56 | |||
57 | 2. *Gather the Hardware:* Based on the size and make-up of the team, | ||
58 | get the hardware together. Ideally, any development, build, or test | ||
59 | engineer uses a system that runs a supported Linux distribution. | ||
60 | These systems, in general, should be high performance (e.g. dual, | ||
61 | six-core Xeons with 24 Gbytes of RAM and plenty of disk space). You | ||
62 | can help ensure efficiency by having any machines used for testing | ||
63 | or that run Autobuilders be as high performance as possible. | ||
64 | |||
65 | .. note:: | ||
66 | |||
67 | Given sufficient processing power, you might also consider | ||
68 | building Yocto Project development containers to be run under | ||
69 | Docker, which is described later. | ||
70 | |||
71 | 3. *Understand the Hardware Topology of the Environment:* Once you | ||
72 | understand the hardware involved and the make-up of the team, you | ||
73 | can understand the hardware topology of the development environment. | ||
74 | You can get a visual idea of the machines and their roles across the | ||
75 | development environment. | ||
76 | |||
77 | 4. *Use Git as Your Source Control Manager (SCM):* Keeping your | ||
78 | :term:`Metadata` (i.e. recipes, | ||
79 | configuration files, classes, and so forth) and any software you are | ||
80 | developing under the control of an SCM system that is compatible | ||
81 | with the OpenEmbedded build system is advisable. Of all of the SCMs | ||
82 | supported by BitBake, the Yocto Project team strongly recommends using | ||
83 | :ref:`overview-manual/overview-manual-development-environment:git`. | ||
84 | Git is a distributed system | ||
85 | that is easy to back up, allows you to work remotely, and then | ||
86 | connects back to the infrastructure. | ||
87 | |||
88 | .. note:: | ||
89 | |||
90 | For information about BitBake, see the | ||
91 | BitBake User Manual | ||
92 | . | ||
93 | |||
94 | It is relatively easy to set up Git services and create | ||
95 | infrastructure like | ||
96 | :yocto_git:`http://git.yoctoproject.org <>`, which is based on | ||
97 | server software called ``gitolite`` with ``cgit`` being used to | ||
98 | generate the web interface that lets you view the repositories. The | ||
99 | ``gitolite`` software identifies users using SSH keys and allows | ||
100 | branch-based access controls to repositories that you can control as | ||
101 | little or as much as necessary. | ||
102 | |||
103 | .. note:: | ||
104 | |||
105 | The setup of these services is beyond the scope of this manual. | ||
106 | However, sites such as the following exist that describe how to | ||
107 | perform setup: | ||
108 | |||
109 | - `Git documentation <http://git-scm.com/book/ch4-8.html>`__: | ||
110 | Describes how to install ``gitolite`` on the server. | ||
111 | |||
112 | - `Gitolite <http://gitolite.com>`__: Information for | ||
113 | ``gitolite``. | ||
114 | |||
115 | - `Interfaces, frontends, and | ||
116 | tools <https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools>`__: | ||
117 | Documentation on how to create interfaces and frontends for | ||
118 | Git. | ||
119 | |||
120 | 5. *Set up the Application Development Machines:* As mentioned earlier, | ||
121 | application developers are creating applications on top of existing | ||
122 | software stacks. Following are some best practices for setting up | ||
123 | machines used for application development: | ||
124 | |||
125 | - Use a pre-built toolchain that contains the software stack | ||
126 | itself. Then, develop the application code on top of the stack. | ||
127 | This method works well for small numbers of relatively isolated | ||
128 | applications. | ||
129 | |||
130 | - Keep your cross-development toolchains updated. You can do this | ||
131 | through provisioning either as new toolchain downloads or as | ||
132 | updates through a package update mechanism using ``opkg`` to | ||
133 | provide updates to an existing toolchain. The exact mechanics of | ||
134 | how and when to do this depend on local policy. | ||
135 | |||
136 | - Use multiple toolchains installed locally into different | ||
137 | locations to allow development across versions. | ||
138 | |||
139 | 6. *Set up the Core Development Machines:* As mentioned earlier, core | ||
140 | developers work on the contents of the operating system itself. | ||
141 | Following are some best practices for setting up machines used for | ||
142 | developing images: | ||
143 | |||
144 | - Have the :term:`OpenEmbedded Build System` available on | ||
145 | the developer workstations so developers can run their own builds | ||
146 | and directly rebuild the software stack. | ||
147 | |||
148 | - Keep the core system unchanged as much as possible and do your | ||
149 | work in layers on top of the core system. Doing so gives you a | ||
150 | greater level of portability when upgrading to new versions of | ||
151 | the core system or Board Support Packages (BSPs). | ||
152 | |||
153 | - Share layers amongst the developers of a particular project and | ||
154 | contain the policy configuration that defines the project. | ||
155 | |||
156 | 7. *Set up an Autobuilder:* Autobuilders are often the core of the | ||
157 | development environment. It is here that changes from individual | ||
158 | developers are brought together and centrally tested. Based on this | ||
159 | automated build and test environment, subsequent decisions about | ||
160 | releases can be made. Autobuilders also allow for "continuous | ||
161 | integration" style testing of software components and regression | ||
162 | identification and tracking. | ||
163 | |||
164 | See "`Yocto Project | ||
165 | Autobuilder <http://autobuilder.yoctoproject.org>`__" for more | ||
166 | information and links to buildbot. The Yocto Project team has found | ||
167 | this implementation works well in this role. A public example of | ||
168 | this is the Yocto Project Autobuilders, which the Yocto Project team | ||
169 | uses to test the overall health of the project. | ||
170 | |||
171 | The features of this system are: | ||
172 | |||
173 | - Highlights when commits break the build. | ||
174 | |||
175 | - Populates an :ref:`sstate | ||
176 | cache <overview-manual/overview-manual-concepts:shared state cache>` from which | ||
177 | developers can pull rather than requiring local builds. | ||
178 | |||
179 | - Allows commit hook triggers, which trigger builds when commits | ||
180 | are made. | ||
181 | |||
182 | - Allows triggering of automated image booting and testing under | ||
183 | the QuickEMUlator (QEMU). | ||
184 | |||
185 | - Supports incremental build testing and from-scratch builds. | ||
186 | |||
187 | - Shares output that allows developer testing and historical | ||
188 | regression investigation. | ||
189 | |||
190 | - Creates output that can be used for releases. | ||
191 | |||
192 | - Allows scheduling of builds so that resources can be used | ||
193 | efficiently. | ||
194 | |||
195 | 8. *Set up Test Machines:* Use a small number of shared, high | ||
196 | performance systems for testing purposes. Developers can use these | ||
197 | systems for wider, more extensive testing while they continue to | ||
198 | develop locally using their primary development system. | ||
199 | |||
200 | 9. *Document Policies and Change Flow:* The Yocto Project uses a | ||
201 | hierarchical structure and a pull model. Scripts exist to create and | ||
202 | send pull requests (i.e. ``create-pull-request`` and | ||
203 | ``send-pull-request``). This model is in line with other open source | ||
204 | projects where maintainers are responsible for specific areas of the | ||
205 | project and a single maintainer handles the final "top-of-tree" | ||
206 | merges. | ||
207 | |||
208 | .. note:: | ||
209 | |||
210 | You can also use a more collective push model. The | ||
211 | gitolite | ||
212 | software supports both the push and pull models quite easily. | ||
213 | |||
214 | As with any development environment, it is important to document the | ||
215 | policy used as well as any main project guidelines so they are | ||
216 | understood by everyone. It is also a good idea to have | ||
217 | well-structured commit messages, which are usually a part of a | ||
218 | project's guidelines. Good commit messages are essential when | ||
219 | looking back in time and trying to understand why changes were made. | ||
220 | |||
221 | If you discover that changes are needed to the core layer of the | ||
222 | project, it is worth sharing those with the community as soon as | ||
223 | possible. Chances are if you have discovered the need for changes, | ||
224 | someone else in the community needs them also. | ||
225 | |||
226 | 10. *Development Environment Summary:* Aside from the previous steps, | ||
227 | some best practices exist within the Yocto Project development | ||
228 | environment. Consider the following: | ||
229 | |||
230 | - Use :ref:`overview-manual/overview-manual-development-environment:git` as the source control | ||
231 | system. | ||
232 | |||
233 | - Maintain your Metadata in layers that make sense for your | ||
234 | situation. See the ":ref:`overview-manual/overview-manual-yp-intro:the yocto project layer model`" | ||
235 | section in the Yocto Project Overview and Concepts Manual and the | ||
236 | ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" | ||
237 | section for more information on layers. | ||
238 | |||
239 | - Separate the project's Metadata and code by using separate Git | ||
240 | repositories. See the ":ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`" | ||
241 | section in the Yocto Project Overview and Concepts Manual for | ||
242 | information on these repositories. See the "`Locating Yocto | ||
243 | Project Source Files <#locating-yocto-project-source-files>`__" | ||
244 | section for information on how to set up local Git repositories | ||
245 | for related upstream Yocto Project Git repositories. | ||
246 | |||
247 | - Set up the directory for the shared state cache | ||
248 | (:term:`SSTATE_DIR`) where | ||
249 | it makes sense. For example, set up the sstate cache on a system | ||
250 | used by developers in the same organization and share the same | ||
251 | source directories on their machines. | ||
252 | |||
253 | - Set up an Autobuilder and have it populate the sstate cache and | ||
254 | source directories. | ||
255 | |||
256 | - The Yocto Project community encourages you to send patches to the | ||
257 | project to fix bugs or add features. If you do submit patches, | ||
258 | follow the project commit guidelines for writing good commit | ||
259 | messages. See the | ||
260 | ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`" | ||
261 | section. | ||
262 | |||
263 | - Send changes to the core sooner than later as others are likely | ||
264 | to run into the same issues. For some guidance on mailing lists | ||
265 | to use, see the list in the | ||
266 | ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`" | ||
267 | section. For a description | ||
268 | of the available mailing lists, see the ":ref:`resources-mailinglist`" section in | ||
269 | the Yocto Project Reference Manual. | ||
270 | |||
271 | .. _dev-preparing-the-build-host: | ||
272 | |||
273 | Preparing the Build Host | ||
274 | ======================== | ||
275 | |||
276 | This section provides procedures to set up a system to be used as your | ||
277 | :term:`Build Host` for | ||
278 | development using the Yocto Project. Your build host can be a native | ||
279 | Linux machine (recommended), it can be a machine (Linux, Mac, or | ||
280 | Windows) that uses `CROPS <https://github.com/crops/poky-container>`__, | ||
281 | which leverages `Docker Containers <https://www.docker.com/>`__ or it | ||
282 | can be a Windows machine capable of running Windows Subsystem For Linux | ||
283 | v2 (WSL). | ||
284 | |||
285 | .. note:: | ||
286 | |||
287 | The Yocto Project is not compatible with | ||
288 | Windows Subsystem for Linux v1 | ||
289 | . It is compatible but not officially supported nor validated with | ||
290 | WSLv2. If you still decide to use WSL please upgrade to | ||
291 | WSLv2 | ||
292 | . | ||
293 | |||
294 | Once your build host is set up to use the Yocto Project, further steps | ||
295 | are necessary depending on what you want to accomplish. See the | ||
296 | following references for information on how to prepare for Board Support | ||
297 | Package (BSP) development and kernel development: | ||
298 | |||
299 | - *BSP Development:* See the ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`" | ||
300 | section in the Yocto Project Board Support Package (BSP) Developer's | ||
301 | Guide. | ||
302 | |||
303 | - *Kernel Development:* See the ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`" | ||
304 | section in the Yocto Project Linux Kernel Development Manual. | ||
305 | |||
306 | Setting Up a Native Linux Host | ||
307 | ------------------------------ | ||
308 | |||
309 | Follow these steps to prepare a native Linux machine as your Yocto | ||
310 | Project Build Host: | ||
311 | |||
312 | 1. *Use a Supported Linux Distribution:* You should have a reasonably | ||
313 | current Linux-based host system. You will have the best results with | ||
314 | a recent release of Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS | ||
315 | as these releases are frequently tested against the Yocto Project and | ||
316 | officially supported. For a list of the distributions under | ||
317 | validation and their status, see the ":ref:`Supported Linux | ||
318 | Distributions <detailed-supported-distros>`" | ||
319 | section in the Yocto Project Reference Manual and the wiki page at | ||
320 | :yocto_wiki:`Distribution Support </wiki/Distribution_Support>`. | ||
321 | |||
322 | 2. *Have Enough Free Memory:* Your system should have at least 50 Gbytes | ||
323 | of free disk space for building images. | ||
324 | |||
325 | 3. *Meet Minimal Version Requirements:* The OpenEmbedded build system | ||
326 | should be able to run on any modern distribution that has the | ||
327 | following versions for Git, tar, Python and gcc. | ||
328 | |||
329 | - Git 1.8.3.1 or greater | ||
330 | |||
331 | - tar 1.28 or greater | ||
332 | |||
333 | - Python 3.5.0 or greater. | ||
334 | |||
335 | - gcc 5.0 or greater. | ||
336 | |||
337 | If your build host does not meet any of these three listed version | ||
338 | requirements, you can take steps to prepare the system so that you | ||
339 | can still use the Yocto Project. See the | ||
340 | ":ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions`" | ||
341 | section in the Yocto Project Reference Manual for information. | ||
342 | |||
343 | 4. *Install Development Host Packages:* Required development host | ||
344 | packages vary depending on your build host and what you want to do | ||
345 | with the Yocto Project. Collectively, the number of required packages | ||
346 | is large if you want to be able to cover all cases. | ||
347 | |||
348 | For lists of required packages for all scenarios, see the | ||
349 | ":ref:`ref-manual/ref-system-requirements:required packages for the build host`" | ||
350 | section in the Yocto Project Reference Manual. | ||
351 | |||
352 | Once you have completed the previous steps, you are ready to continue | ||
353 | using a given development path on your native Linux machine. If you are | ||
354 | going to use BitBake, see the | ||
355 | ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" | ||
356 | section. If you are going | ||
357 | to use the Extensible SDK, see the ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto | ||
358 | Project Application Development and the Extensible Software Development | ||
359 | Kit (eSDK) manual. If you want to work on the kernel, see the :doc:`../kernel-dev/kernel-dev`. If you are going to use | ||
360 | Toaster, see the ":doc:`../toaster-manual/toaster-manual-setup-and-use`" | ||
361 | section in the Toaster User Manual. | ||
362 | |||
363 | .. _setting-up-to-use-crops: | ||
364 | |||
365 | Setting Up to Use CROss PlatformS (CROPS) | ||
366 | ----------------------------------------- | ||
367 | |||
368 | With `CROPS <https://github.com/crops/poky-container>`__, which | ||
369 | leverages `Docker Containers <https://www.docker.com/>`__, you can | ||
370 | create a Yocto Project development environment that is operating system | ||
371 | agnostic. You can set up a container in which you can develop using the | ||
372 | Yocto Project on a Windows, Mac, or Linux machine. | ||
373 | |||
374 | Follow these general steps to prepare a Windows, Mac, or Linux machine | ||
375 | as your Yocto Project build host: | ||
376 | |||
377 | 1. *Determine What Your Build Host Needs:* | ||
378 | `Docker <https://www.docker.com/what-docker>`__ is a software | ||
379 | container platform that you need to install on the build host. | ||
380 | Depending on your build host, you might have to install different | ||
381 | software to support Docker containers. Go to the Docker installation | ||
382 | page and read about the platform requirements in "`Supported | ||
383 | Platforms <https://docs.docker.com/engine/install/#supported-platforms>`__" | ||
384 | your build host needs to run containers. | ||
385 | |||
386 | 2. *Choose What To Install:* Depending on whether or not your build host | ||
387 | meets system requirements, you need to install "Docker CE Stable" or | ||
388 | the "Docker Toolbox". Most situations call for Docker CE. However, if | ||
389 | you have a build host that does not meet requirements (e.g. | ||
390 | Pre-Windows 10 or Windows 10 "Home" version), you must install Docker | ||
391 | Toolbox instead. | ||
392 | |||
393 | 3. *Go to the Install Site for Your Platform:* Click the link for the | ||
394 | Docker edition associated with your build host's native software. For | ||
395 | example, if your build host is running Microsoft Windows Version 10 | ||
396 | and you want the Docker CE Stable edition, click that link under | ||
397 | "Supported Platforms". | ||
398 | |||
399 | 4. *Install the Software:* Once you have understood all the | ||
400 | pre-requisites, you can download and install the appropriate | ||
401 | software. Follow the instructions for your specific machine and the | ||
402 | type of the software you need to install: | ||
403 | |||
404 | - Install `Docker CE for | ||
405 | Windows <https://docs.docker.com/docker-for-windows/install/#install-docker-desktop-on-windows>`__ | ||
406 | for Windows build hosts that meet requirements. | ||
407 | |||
408 | - Install `Docker CE for | ||
409 | MacOs <https://docs.docker.com/docker-for-mac/install/#install-and-run-docker-desktop-on-mac>`__ | ||
410 | for Mac build hosts that meet requirements. | ||
411 | |||
412 | - Install `Docker Toolbox for | ||
413 | Windows <https://docs.docker.com/toolbox/toolbox_install_windows/>`__ | ||
414 | for Windows build hosts that do not meet Docker requirements. | ||
415 | |||
416 | - Install `Docker Toolbox for | ||
417 | MacOS <https://docs.docker.com/toolbox/toolbox_install_mac/>`__ | ||
418 | for Mac build hosts that do not meet Docker requirements. | ||
419 | |||
420 | - Install `Docker CE for | ||
421 | CentOS <https://docs.docker.com/install/linux/docker-ce/centos/>`__ | ||
422 | for Linux build hosts running the CentOS distribution. | ||
423 | |||
424 | - Install `Docker CE for | ||
425 | Debian <https://docs.docker.com/install/linux/docker-ce/debian/>`__ | ||
426 | for Linux build hosts running the Debian distribution. | ||
427 | |||
428 | - Install `Docker CE for | ||
429 | Fedora <https://docs.docker.com/install/linux/docker-ce/fedora/>`__ | ||
430 | for Linux build hosts running the Fedora distribution. | ||
431 | |||
432 | - Install `Docker CE for | ||
433 | Ubuntu <https://docs.docker.com/install/linux/docker-ce/ubuntu/>`__ | ||
434 | for Linux build hosts running the Ubuntu distribution. | ||
435 | |||
436 | 5. *Optionally Orient Yourself With Docker:* If you are unfamiliar with | ||
437 | Docker and the container concept, you can learn more here - | ||
438 | https://docs.docker.com/get-started/. | ||
439 | |||
440 | 6. *Launch Docker or Docker Toolbox:* You should be able to launch | ||
441 | Docker or the Docker Toolbox and have a terminal shell on your | ||
442 | development host. | ||
443 | |||
444 | 7. *Set Up the Containers to Use the Yocto Project:* Go to | ||
445 | https://github.com/crops/docker-win-mac-docs/wiki and follow | ||
446 | the directions for your particular build host (i.e. Linux, Mac, or | ||
447 | Windows). | ||
448 | |||
449 | Once you complete the setup instructions for your machine, you have | ||
450 | the Poky, Extensible SDK, and Toaster containers available. You can | ||
451 | click those links from the page and learn more about using each of | ||
452 | those containers. | ||
453 | |||
454 | Once you have a container set up, everything is in place to develop just | ||
455 | as if you were running on a native Linux machine. If you are going to | ||
456 | use the Poky container, see the "`Cloning the ``poky`` | ||
457 | Repository <#cloning-the-poky-repository>`__" section. If you are going | ||
458 | to use the Extensible SDK container, see the | ||
459 | ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto | ||
460 | Project Application Development and the Extensible Software Development | ||
461 | Kit (eSDK) manual. If you are going to use the Toaster container, see | ||
462 | the ":doc:`../toaster-manual/toaster-manual-setup-and-use`" | ||
463 | section in the Toaster User Manual. | ||
464 | |||
465 | .. _setting-up-to-use-wsl: | ||
466 | |||
467 | Setting Up to Use Windows Subsystem For Linux (WSLv2) | ||
468 | ----------------------------------------------------- | ||
469 | |||
470 | With `Windows Subsystem for Linux | ||
471 | (WSLv2) <https://docs.microsoft.com/en-us/windows/wsl/wsl2-about>`__, | ||
472 | you can create a Yocto Project development environment that allows you | ||
473 | to build on Windows. You can set up a Linux distribution inside Windows | ||
474 | in which you can develop using the Yocto Project. | ||
475 | |||
476 | Follow these general steps to prepare a Windows machine using WSLv2 as | ||
477 | your Yocto Project build host: | ||
478 | |||
479 | 1. *Make sure your Windows 10 machine is capable of running WSLv2:* | ||
480 | WSLv2 is only available for Windows 10 builds > 18917. To check which | ||
481 | build version you are running, you may open a command prompt on | ||
482 | Windows and execute the command "ver". | ||
483 | :: | ||
484 | |||
485 | C:\Users\myuser> ver | ||
486 | |||
487 | Microsoft Windows [Version 10.0.19041.153] | ||
488 | |||
489 | If your build is capable of running | ||
490 | WSLv2 you may continue, for more information on this subject or | ||
491 | instructions on how to upgrade to WSLv2 visit `Windows 10 | ||
492 | WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/wsl2-install>`__ | ||
493 | |||
494 | 2. *Install the Linux distribution of your choice inside Windows 10:* | ||
495 | Once you know your version of Windows 10 supports WSLv2, you can | ||
496 | install the distribution of your choice from the Microsoft Store. | ||
497 | Open the Microsoft Store and search for Linux. While there are | ||
498 | several Linux distributions available, the assumption is that your | ||
499 | pick will be one of the distributions supported by the Yocto Project | ||
500 | as stated on the instructions for using a native Linux host. After | ||
501 | making your selection, simply click "Get" to download and install the | ||
502 | distribution. | ||
503 | |||
504 | 3. *Check your Linux distribution is using WSLv2:* Open a Windows | ||
505 | PowerShell and run: | ||
506 | :: | ||
507 | |||
508 | C:\WINDOWS\system32> wsl -l -v | ||
509 | NAME STATE VERSION | ||
510 | *Ubuntu Running 2 | ||
511 | |||
512 | Note the version column which says the WSL version | ||
513 | being used by your distribution, on compatible systems, this can be | ||
514 | changed back at any point in time. | ||
515 | |||
516 | 4. *Optionally Orient Yourself on WSL:* If you are unfamiliar with WSL, | ||
517 | you can learn more here - | ||
518 | https://docs.microsoft.com/en-us/windows/wsl/wsl2-about. | ||
519 | |||
520 | 5. *Launch your WSL Distibution:* From the Windows start menu simply | ||
521 | launch your WSL distribution just like any other application. | ||
522 | |||
523 | 6. *Optimize your WSLv2 storage often:* Due to the way storage is | ||
524 | handled on WSLv2, the storage space used by the undelying Linux | ||
525 | distribution is not reflected immedately, and since bitbake heavily | ||
526 | uses storage, after several builds, you may be unaware you are | ||
527 | running out of space. WSLv2 uses a VHDX file for storage, this issue | ||
528 | can be easily avoided by manually optimizing this file often, this | ||
529 | can be done in the following way: | ||
530 | |||
531 | 1. *Find the location of your VHDX file:* First you need to find the | ||
532 | distro app package directory, to achieve this open a Windows | ||
533 | Powershell as Administrator and run: | ||
534 | :: | ||
535 | |||
536 | C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName | ||
537 | PackageFamilyName | ||
538 | ----------------- | ||
539 | CanonicalGroupLimited.UbuntuonWindows_79abcdefgh | ||
540 | |||
541 | |||
542 | You should now | ||
543 | replace the PackageFamilyName and your user on the following path | ||
544 | to find your VHDX file: | ||
545 | :: | ||
546 | |||
547 | ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ | ||
548 | Mode LastWriteTime Length Name | ||
549 | -a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx | ||
550 | |||
551 | Your VHDX file path is: | ||
552 | ``C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx`` | ||
553 | |||
554 | 2. *Optimize your VHDX file:* Open a Windows Powershell as | ||
555 | Administrator to optimize your VHDX file, shutting down WSL first: | ||
556 | :: | ||
557 | |||
558 | C:\WINDOWS\system32> wsl --shutdown | ||
559 | C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full | ||
560 | |||
561 | A progress bar should be shown while optimizing the | ||
562 | VHDX file, and storage should now be reflected correctly on the | ||
563 | Windows Explorer. | ||
564 | |||
565 | .. note:: | ||
566 | |||
567 | The current implementation of WSLv2 does not have out-of-the-box | ||
568 | access to external devices such as those connected through a USB | ||
569 | port, but it automatically mounts your | ||
570 | C: | ||
571 | drive on | ||
572 | /mnt/c/ | ||
573 | (and others), which you can use to share deploy artifacts to be later | ||
574 | flashed on hardware through Windows, but your build directory should | ||
575 | not reside inside this mountpoint. | ||
576 | |||
577 | Once you have WSLv2 set up, everything is in place to develop just as if | ||
578 | you were running on a native Linux machine. If you are going to use the | ||
579 | Extensible SDK container, see the ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto | ||
580 | Project Application Development and the Extensible Software Development | ||
581 | Kit (eSDK) manual. If you are going to use the Toaster container, see | ||
582 | the ":doc:`../toaster-manual/toaster-manual-setup-and-use`" | ||
583 | section in the Toaster User Manual. | ||
584 | |||
585 | Locating Yocto Project Source Files | ||
586 | =================================== | ||
587 | |||
588 | This section shows you how to locate, fetch and configure the source | ||
589 | files you'll need to work with the Yocto Project. | ||
590 | |||
591 | .. note:: | ||
592 | |||
593 | - For concepts and introductory information about Git as it is used | ||
594 | in the Yocto Project, see the ":ref:`overview-manual/overview-manual-development-environment:git`" | ||
595 | section in the Yocto Project Overview and Concepts Manual. | ||
596 | |||
597 | - For concepts on Yocto Project source repositories, see the | ||
598 | ":ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`" | ||
599 | section in the Yocto Project Overview and Concepts Manual." | ||
600 | |||
601 | Accessing Source Repositories | ||
602 | ----------------------------- | ||
603 | |||
604 | Working from a copy of the upstream :ref:`dev-manual/dev-manual-start:accessing source repositories` is the | ||
605 | preferred method for obtaining and using a Yocto Project release. You | ||
606 | can view the Yocto Project Source Repositories at | ||
607 | :yocto_git:`/`. In particular, you can find the ``poky`` | ||
608 | repository at :yocto_git:`/cgit.cgi/poky`. | ||
609 | |||
610 | Use the following procedure to locate the latest upstream copy of the | ||
611 | ``poky`` Git repository: | ||
612 | |||
613 | 1. *Access Repositories:* Open a browser and go to | ||
614 | :yocto_git:`/` to access the GUI-based interface into the | ||
615 | Yocto Project source repositories. | ||
616 | |||
617 | 2. *Select the Repository:* Click on the repository in which you are | ||
618 | interested (e.g. ``poky``). | ||
619 | |||
620 | 3. *Find the URL Used to Clone the Repository:* At the bottom of the | ||
621 | page, note the URL used to clone that repository | ||
622 | (e.g. :yocto_git:`/cgit.cgi/poky`). | ||
623 | |||
624 | .. note:: | ||
625 | |||
626 | For information on cloning a repository, see the " | ||
627 | Cloning the | ||
628 | poky | ||
629 | Repository | ||
630 | " section. | ||
631 | |||
632 | Accessing Index of Releases | ||
633 | --------------------------- | ||
634 | |||
635 | Yocto Project maintains an Index of Releases area that contains related | ||
636 | files that contribute to the Yocto Project. Rather than Git | ||
637 | repositories, these files are tarballs that represent snapshots in time | ||
638 | of a given component. | ||
639 | |||
640 | .. note:: | ||
641 | |||
642 | The recommended method for accessing Yocto Project components is to | ||
643 | use Git to clone the upstream repository and work from within that | ||
644 | locally cloned repository. The procedure in this section exists | ||
645 | should you desire a tarball snapshot of any given component. | ||
646 | |||
647 | Follow these steps to locate and download a particular tarball: | ||
648 | |||
649 | 1. *Access the Index of Releases:* Open a browser and go to | ||
650 | :yocto_dl:`Index of Releases </releases>`. The | ||
651 | list represents released components (e.g. ``bitbake``, ``sato``, and | ||
652 | so on). | ||
653 | |||
654 | .. note:: | ||
655 | |||
656 | The | ||
657 | yocto | ||
658 | directory contains the full array of released Poky tarballs. The | ||
659 | poky | ||
660 | directory in the Index of Releases was historically used for very | ||
661 | early releases and exists now only for retroactive completeness. | ||
662 | |||
663 | 2. *Select a Component:* Click on any released component in which you | ||
664 | are interested (e.g. ``yocto``). | ||
665 | |||
666 | 3. *Find the Tarball:* Drill down to find the associated tarball. For | ||
667 | example, click on ``yocto-&DISTRO;`` to view files associated with the | ||
668 | Yocto Project &DISTRO; release (e.g. | ||
669 | ``&YOCTO_POKY;.tar.bz2``, which is the | ||
670 | released Poky tarball). | ||
671 | |||
672 | 4. *Download the Tarball:* Click the tarball to download and save a | ||
673 | snapshot of the given component. | ||
674 | |||
675 | Using the Downloads Page | ||
676 | ------------------------ | ||
677 | |||
678 | The :yocto_home:`Yocto Project Website <>` uses a "DOWNLOADS" page | ||
679 | from which you can locate and download tarballs of any Yocto Project | ||
680 | release. Rather than Git repositories, these files represent snapshot | ||
681 | tarballs similar to the tarballs located in the Index of Releases | ||
682 | described in the "`Accessing Index of | ||
683 | Releases <#accessing-index-of-releases>`__" section. | ||
684 | |||
685 | .. note:: | ||
686 | |||
687 | The recommended method for accessing Yocto Project components is to | ||
688 | use Git to clone a repository and work from within that local | ||
689 | repository. The procedure in this section exists should you desire a | ||
690 | tarball snapshot of any given component. | ||
691 | |||
692 | 1. *Go to the Yocto Project Website:* Open The | ||
693 | :yocto_home:`Yocto Project Website <>` in your browser. | ||
694 | |||
695 | 2. *Get to the Downloads Area:* Select the "DOWNLOADS" item from the | ||
696 | pull-down "SOFTWARE" tab menu near the top of the page. | ||
697 | |||
698 | 3. *Select a Yocto Project Release:* Use the menu next to "RELEASE" to | ||
699 | display and choose a recent or past supported Yocto Project release | ||
700 | (e.g. &DISTRO_NAME_NO_CAP;, &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth). | ||
701 | |||
702 | .. note:: | ||
703 | |||
704 | For a "map" of Yocto Project releases to version numbers, see the | ||
705 | Releases | ||
706 | wiki page. | ||
707 | |||
708 | You can use the "RELEASE ARCHIVE" link to reveal a menu of all Yocto | ||
709 | Project releases. | ||
710 | |||
711 | 4. *Download Tools or Board Support Packages (BSPs):* From the | ||
712 | "DOWNLOADS" page, you can download tools or BSPs as well. Just scroll | ||
713 | down the page and look for what you need. | ||
714 | |||
715 | Accessing Nightly Builds | ||
716 | ------------------------ | ||
717 | |||
718 | Yocto Project maintains an area for nightly builds that contains tarball | ||
719 | releases at https://autobuilder.yocto.io//pub/nightly/. These builds include Yocto | ||
720 | Project releases ("poky"), toolchains, and builds for supported | ||
721 | machines. | ||
722 | |||
723 | Should you ever want to access a nightly build of a particular Yocto | ||
724 | Project component, use the following procedure: | ||
725 | |||
726 | 1. *Locate the Index of Nightly Builds:* Open a browser and go to | ||
727 | https://autobuilder.yocto.io//pub/nightly/ to access the Nightly Builds. | ||
728 | |||
729 | 2. *Select a Date:* Click on the date in which you are interested. If | ||
730 | you want the latest builds, use "CURRENT". | ||
731 | |||
732 | 3. *Select a Build:* Choose the area in which you are interested. For | ||
733 | example, if you are looking for the most recent toolchains, select | ||
734 | the "toolchain" link. | ||
735 | |||
736 | 4. *Find the Tarball:* Drill down to find the associated tarball. | ||
737 | |||
738 | 5. *Download the Tarball:* Click the tarball to download and save a | ||
739 | snapshot of the given component. | ||
740 | |||
741 | Cloning and Checking Out Branches | ||
742 | ================================= | ||
743 | |||
744 | To use the Yocto Project for development, you need a release locally | ||
745 | installed on your development system. This locally installed set of | ||
746 | files is referred to as the :term:`Source Directory` | ||
747 | in the Yocto Project documentation. | ||
748 | |||
749 | The preferred method of creating your Source Directory is by using | ||
750 | :ref:`overview-manual/overview-manual-development-environment:git` to clone a local copy of the upstream | ||
751 | ``poky`` repository. Working from a cloned copy of the upstream | ||
752 | repository allows you to contribute back into the Yocto Project or to | ||
753 | simply work with the latest software on a development branch. Because | ||
754 | Git maintains and creates an upstream repository with a complete history | ||
755 | of changes and you are working with a local clone of that repository, | ||
756 | you have access to all the Yocto Project development branches and tag | ||
757 | names used in the upstream repository. | ||
758 | |||
759 | Cloning the ``poky`` Repository | ||
760 | ------------------------------- | ||
761 | |||
762 | Follow these steps to create a local version of the upstream | ||
763 | :term:`Poky` Git repository. | ||
764 | |||
765 | 1. *Set Your Directory:* Change your working directory to where you want | ||
766 | to create your local copy of ``poky``. | ||
767 | |||
768 | 2. *Clone the Repository:* The following example command clones the | ||
769 | ``poky`` repository and uses the default name "poky" for your local | ||
770 | repository: | ||
771 | :: | ||
772 | |||
773 | $ git clone git://git.yoctoproject.org/poky | ||
774 | Cloning into 'poky'... | ||
775 | remote: Counting objects: 432160, done. | ||
776 | remote: Compressing objects: 100% (102056/102056), done. | ||
777 | remote: Total 432160 (delta 323116), reused 432037 (delta 323000) | ||
778 | Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done. | ||
779 | Resolving deltas: 100% (323116/323116), done. | ||
780 | Checking connectivity... done. | ||
781 | |||
782 | Unless you | ||
783 | specify a specific development branch or tag name, Git clones the | ||
784 | "master" branch, which results in a snapshot of the latest | ||
785 | development changes for "master". For information on how to check out | ||
786 | a specific development branch or on how to check out a local branch | ||
787 | based on a tag name, see the "`Checking Out By Branch in | ||
788 | Poky <#checking-out-by-branch-in-poky>`__" and `Checking Out By Tag | ||
789 | in Poky <#checkout-out-by-tag-in-poky>`__" sections, respectively. | ||
790 | |||
791 | Once the local repository is created, you can change to that | ||
792 | directory and check its status. Here, the single "master" branch | ||
793 | exists on your system and by default, it is checked out: | ||
794 | :: | ||
795 | |||
796 | $ cd ~/poky | ||
797 | $ git status | ||
798 | On branch master | ||
799 | Your branch is up-to-date with 'origin/master'. | ||
800 | nothing to commit, working directory clean | ||
801 | $ git branch | ||
802 | * master | ||
803 | |||
804 | Your local repository of poky is identical to the | ||
805 | upstream poky repository at the time from which it was cloned. As you | ||
806 | work with the local branch, you can periodically use the | ||
807 | ``git pull --rebase`` command to be sure you are up-to-date | ||
808 | with the upstream branch. | ||
809 | |||
810 | Checking Out by Branch in Poky | ||
811 | ------------------------------ | ||
812 | |||
813 | When you clone the upstream poky repository, you have access to all its | ||
814 | development branches. Each development branch in a repository is unique | ||
815 | as it forks off the "master" branch. To see and use the files of a | ||
816 | particular development branch locally, you need to know the branch name | ||
817 | and then specifically check out that development branch. | ||
818 | |||
819 | .. note:: | ||
820 | |||
821 | Checking out an active development branch by branch name gives you a | ||
822 | snapshot of that particular branch at the time you check it out. | ||
823 | Further development on top of the branch that occurs after check it | ||
824 | out can occur. | ||
825 | |||
826 | 1. *Switch to the Poky Directory:* If you have a local poky Git | ||
827 | repository, switch to that directory. If you do not have the local | ||
828 | copy of poky, see the "`Cloning the ``poky`` | ||
829 | Repository <#cloning-the-poky-repository>`__" section. | ||
830 | |||
831 | 2. *Determine Existing Branch Names:* | ||
832 | :: | ||
833 | |||
834 | $ git branch -a | ||
835 | * master | ||
836 | remotes/origin/1.1_M1 | ||
837 | remotes/origin/1.1_M2 | ||
838 | remotes/origin/1.1_M3 | ||
839 | remotes/origin/1.1_M4 | ||
840 | remotes/origin/1.2_M1 | ||
841 | remotes/origin/1.2_M2 | ||
842 | remotes/origin/1.2_M3 | ||
843 | . . . | ||
844 | remotes/origin/thud | ||
845 | remotes/origin/thud-next | ||
846 | remotes/origin/warrior | ||
847 | remotes/origin/warrior-next | ||
848 | remotes/origin/zeus | ||
849 | remotes/origin/zeus-next | ||
850 | ... and so on ... | ||
851 | |||
852 | 3. *Check out the Branch:* Check out the development branch in which you | ||
853 | want to work. For example, to access the files for the Yocto Project | ||
854 | &DISTRO; Release (&DISTRO_NAME;), use the following command: | ||
855 | :: | ||
856 | |||
857 | $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; | ||
858 | Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin. | ||
859 | Switched to a new branch '&DISTRO_NAME;' | ||
860 | |||
861 | The previous command checks out the "&DISTRO_NAME;" development | ||
862 | branch and reports that the branch is tracking the upstream | ||
863 | "origin/&DISTRO_NAME;" branch. | ||
864 | |||
865 | The following command displays the branches that are now part of your | ||
866 | local poky repository. The asterisk character indicates the branch | ||
867 | that is currently checked out for work: | ||
868 | :: | ||
869 | |||
870 | $ git branch | ||
871 | master * | ||
872 | &DISTRO_NAME; | ||
873 | |||
874 | .. _checkout-out-by-tag-in-poky: | ||
875 | |||
876 | Checking Out by Tag in Poky | ||
877 | --------------------------- | ||
878 | |||
879 | Similar to branches, the upstream repository uses tags to mark specific | ||
880 | commits associated with significant points in a development branch (i.e. | ||
881 | a release point or stage of a release). You might want to set up a local | ||
882 | branch based on one of those points in the repository. The process is | ||
883 | similar to checking out by branch name except you use tag names. | ||
884 | |||
885 | .. note:: | ||
886 | |||
887 | Checking out a branch based on a tag gives you a stable set of files | ||
888 | not affected by development on the branch above the tag. | ||
889 | |||
890 | 1. *Switch to the Poky Directory:* If you have a local poky Git | ||
891 | repository, switch to that directory. If you do not have the local | ||
892 | copy of poky, see the "`Cloning the ``poky`` | ||
893 | Repository <#cloning-the-poky-repository>`__" section. | ||
894 | |||
895 | 2. *Fetch the Tag Names:* To checkout the branch based on a tag name, | ||
896 | you need to fetch the upstream tags into your local repository: | ||
897 | :: | ||
898 | |||
899 | $ git fetch --tags | ||
900 | $ | ||
901 | |||
902 | 3. *List the Tag Names:* You can list the tag names now: | ||
903 | :: | ||
904 | |||
905 | $ git tag | ||
906 | 1.1_M1.final | ||
907 | 1.1_M1.rc1 | ||
908 | 1.1_M1.rc2 | ||
909 | 1.1_M2.final | ||
910 | 1.1_M2.rc1 | ||
911 | . | ||
912 | . | ||
913 | . | ||
914 | yocto-2.5 | ||
915 | yocto-2.5.1 | ||
916 | yocto-2.5.2 | ||
917 | yocto-2.5.3 | ||
918 | yocto-2.6 | ||
919 | yocto-2.6.1 | ||
920 | yocto-2.6.2 | ||
921 | yocto-2.7 | ||
922 | yocto_1.5_M5.rc8 | ||
923 | |||
924 | |||
925 | 4. *Check out the Branch:* | ||
926 | :: | ||
927 | |||
928 | $ git checkout tags/yocto-&DISTRO; -b my_yocto_&DISTRO; | ||
929 | Switched to a new branch 'my_yocto_&DISTRO;' | ||
930 | $ git branch | ||
931 | master | ||
932 | * my_yocto_&DISTRO; | ||
933 | |||
934 | The previous command creates and | ||
935 | checks out a local branch named "my_yocto_&DISTRO;", which is based on | ||
936 | the commit in the upstream poky repository that has the same tag. In | ||
937 | this example, the files you have available locally as a result of the | ||
938 | ``checkout`` command are a snapshot of the "&DISTRO_NAME_NO_CAP;" | ||
939 | development branch at the point where Yocto Project &DISTRO; was | ||
940 | released. | ||