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