diff options
Diffstat (limited to 'documentation/dev-manual/start.rst')
-rw-r--r-- | documentation/dev-manual/start.rst | 434 |
1 files changed, 187 insertions, 247 deletions
diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst index 03061a79f3..386e5f5d29 100644 --- a/documentation/dev-manual/start.rst +++ b/documentation/dev-manual/start.rst | |||
@@ -29,14 +29,14 @@ however, keep in mind, the procedure here is simply a starting point. | |||
29 | You can build off these steps and customize the procedure to fit any | 29 | You can build off these steps and customize the procedure to fit any |
30 | particular working environment and set of practices. | 30 | particular working environment and set of practices. |
31 | 31 | ||
32 | 1. *Determine Who is Going to be Developing:* You first need to | 32 | #. *Determine Who is Going to be Developing:* You first need to |
33 | understand who is going to be doing anything related to the Yocto | 33 | understand who is going to be doing anything related to the Yocto |
34 | Project and determine their roles. Making this determination is | 34 | Project and determine their roles. Making this determination is |
35 | essential to completing subsequent steps, which are to get your | 35 | essential to completing subsequent steps, which are to get your |
36 | equipment together and set up your development environment's | 36 | equipment together and set up your development environment's |
37 | hardware topology. | 37 | hardware topology. |
38 | 38 | ||
39 | The following roles exist: | 39 | Possible roles are: |
40 | 40 | ||
41 | - *Application Developer:* This type of developer does application | 41 | - *Application Developer:* This type of developer does application |
42 | level work on top of an existing software stack. | 42 | level work on top of an existing software stack. |
@@ -52,7 +52,7 @@ particular working environment and set of practices. | |||
52 | automated tests that are used to ensure all application and core | 52 | automated tests that are used to ensure all application and core |
53 | system development meets desired quality standards. | 53 | system development meets desired quality standards. |
54 | 54 | ||
55 | 2. *Gather the Hardware:* Based on the size and make-up of the team, | 55 | #. *Gather the Hardware:* Based on the size and make-up of the team, |
56 | get the hardware together. Ideally, any development, build, or test | 56 | get the hardware together. Ideally, any development, build, or test |
57 | engineer uses a system that runs a supported Linux distribution. | 57 | engineer uses a system that runs a supported Linux distribution. |
58 | These systems, in general, should be high performance (e.g. dual, | 58 | These systems, in general, should be high performance (e.g. dual, |
@@ -66,13 +66,13 @@ particular working environment and set of practices. | |||
66 | building Yocto Project development containers to be run under | 66 | building Yocto Project development containers to be run under |
67 | Docker, which is described later. | 67 | Docker, which is described later. |
68 | 68 | ||
69 | 3. *Understand the Hardware Topology of the Environment:* Once you | 69 | #. *Understand the Hardware Topology of the Environment:* Once you |
70 | understand the hardware involved and the make-up of the team, you | 70 | understand the hardware involved and the make-up of the team, you |
71 | can understand the hardware topology of the development environment. | 71 | can understand the hardware topology of the development environment. |
72 | You can get a visual idea of the machines and their roles across the | 72 | You can get a visual idea of the machines and their roles across the |
73 | development environment. | 73 | development environment. |
74 | 74 | ||
75 | 4. *Use Git as Your Source Control Manager (SCM):* Keeping your | 75 | #. *Use Git as Your Source Control Manager (SCM):* Keeping your |
76 | :term:`Metadata` (i.e. recipes, | 76 | :term:`Metadata` (i.e. recipes, |
77 | configuration files, classes, and so forth) and any software you are | 77 | configuration files, classes, and so forth) and any software you are |
78 | developing under the control of an SCM system that is compatible | 78 | developing under the control of an SCM system that is compatible |
@@ -88,31 +88,18 @@ particular working environment and set of practices. | |||
88 | For information about BitBake, see the | 88 | For information about BitBake, see the |
89 | :doc:`bitbake:index`. | 89 | :doc:`bitbake:index`. |
90 | 90 | ||
91 | It is relatively easy to set up Git services and create | 91 | It is relatively easy to set up Git services and create infrastructure like |
92 | infrastructure like :yocto_git:`/`, which is based on | 92 | :yocto_git:`/`, which is based on server software called |
93 | server software called ``gitolite`` with ``cgit`` being used to | 93 | `Gitolite <https://gitolite.com>`__ |
94 | generate the web interface that lets you view the repositories. The | 94 | with `cgit <https://git.zx2c4.com/cgit/about/>`__ being used to |
95 | ``gitolite`` software identifies users using SSH keys and allows | 95 | generate the web interface that lets you view the repositories. |
96 | ``gitolite`` identifies users using SSH keys and allows | ||
96 | branch-based access controls to repositories that you can control as | 97 | branch-based access controls to repositories that you can control as |
97 | little or as much as necessary. | 98 | little or as much as necessary. |
98 | 99 | ||
99 | .. note:: | 100 | #. *Set up the Application Development Machines:* As mentioned earlier, |
100 | |||
101 | The setup of these services is beyond the scope of this manual. | ||
102 | However, sites such as the following exist that describe how to | ||
103 | perform setup: | ||
104 | |||
105 | - `Gitolite <https://gitolite.com>`__: Information for | ||
106 | ``gitolite``. | ||
107 | |||
108 | - `Interfaces, frontends, and | ||
109 | tools <https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools>`__: | ||
110 | Documentation on how to create interfaces and frontends for | ||
111 | Git. | ||
112 | |||
113 | 5. *Set up the Application Development Machines:* As mentioned earlier, | ||
114 | application developers are creating applications on top of existing | 101 | application developers are creating applications on top of existing |
115 | software stacks. Following are some best practices for setting up | 102 | software stacks. Here are some best practices for setting up |
116 | machines used for application development: | 103 | machines used for application development: |
117 | 104 | ||
118 | - Use a pre-built toolchain that contains the software stack | 105 | - Use a pre-built toolchain that contains the software stack |
@@ -129,9 +116,9 @@ particular working environment and set of practices. | |||
129 | - Use multiple toolchains installed locally into different | 116 | - Use multiple toolchains installed locally into different |
130 | locations to allow development across versions. | 117 | locations to allow development across versions. |
131 | 118 | ||
132 | 6. *Set up the Core Development Machines:* As mentioned earlier, core | 119 | #. *Set up the Core Development Machines:* As mentioned earlier, core |
133 | developers work on the contents of the operating system itself. | 120 | developers work on the contents of the operating system itself. |
134 | Following are some best practices for setting up machines used for | 121 | Here are some best practices for setting up machines used for |
135 | developing images: | 122 | developing images: |
136 | 123 | ||
137 | - Have the :term:`OpenEmbedded Build System` available on | 124 | - Have the :term:`OpenEmbedded Build System` available on |
@@ -146,7 +133,7 @@ particular working environment and set of practices. | |||
146 | - Share layers amongst the developers of a particular project and | 133 | - Share layers amongst the developers of a particular project and |
147 | contain the policy configuration that defines the project. | 134 | contain the policy configuration that defines the project. |
148 | 135 | ||
149 | 7. *Set up an Autobuilder:* Autobuilders are often the core of the | 136 | #. *Set up an Autobuilder:* Autobuilders are often the core of the |
150 | development environment. It is here that changes from individual | 137 | development environment. It is here that changes from individual |
151 | developers are brought together and centrally tested. Based on this | 138 | developers are brought together and centrally tested. Based on this |
152 | automated build and test environment, subsequent decisions about | 139 | automated build and test environment, subsequent decisions about |
@@ -184,13 +171,13 @@ particular working environment and set of practices. | |||
184 | - Allows scheduling of builds so that resources can be used | 171 | - Allows scheduling of builds so that resources can be used |
185 | efficiently. | 172 | efficiently. |
186 | 173 | ||
187 | 8. *Set up Test Machines:* Use a small number of shared, high | 174 | #. *Set up Test Machines:* Use a small number of shared, high |
188 | performance systems for testing purposes. Developers can use these | 175 | performance systems for testing purposes. Developers can use these |
189 | systems for wider, more extensive testing while they continue to | 176 | systems for wider, more extensive testing while they continue to |
190 | develop locally using their primary development system. | 177 | develop locally using their primary development system. |
191 | 178 | ||
192 | 9. *Document Policies and Change Flow:* The Yocto Project uses a | 179 | #. *Document Policies and Change Flow:* The Yocto Project uses a |
193 | hierarchical structure and a pull model. Scripts exist to create and | 180 | hierarchical structure and a pull model. There are scripts to create and |
194 | send pull requests (i.e. ``create-pull-request`` and | 181 | send pull requests (i.e. ``create-pull-request`` and |
195 | ``send-pull-request``). This model is in line with other open source | 182 | ``send-pull-request``). This model is in line with other open source |
196 | projects where maintainers are responsible for specific areas of the | 183 | projects where maintainers are responsible for specific areas of the |
@@ -214,9 +201,9 @@ particular working environment and set of practices. | |||
214 | possible. Chances are if you have discovered the need for changes, | 201 | possible. Chances are if you have discovered the need for changes, |
215 | someone else in the community needs them also. | 202 | someone else in the community needs them also. |
216 | 203 | ||
217 | 10. *Development Environment Summary:* Aside from the previous steps, | 204 | #. *Development Environment Summary:* Aside from the previous steps, |
218 | some best practices exist within the Yocto Project development | 205 | here are best practices within the Yocto Project development |
219 | environment. Consider the following: | 206 | environment: |
220 | 207 | ||
221 | - Use :ref:`overview-manual/development-environment:git` as the source control | 208 | - Use :ref:`overview-manual/development-environment:git` as the source control |
222 | system. | 209 | system. |
@@ -224,14 +211,14 @@ particular working environment and set of practices. | |||
224 | - Maintain your Metadata in layers that make sense for your | 211 | - Maintain your Metadata in layers that make sense for your |
225 | situation. See the ":ref:`overview-manual/yp-intro:the yocto project layer model`" | 212 | situation. See the ":ref:`overview-manual/yp-intro:the yocto project layer model`" |
226 | section in the Yocto Project Overview and Concepts Manual and the | 213 | section in the Yocto Project Overview and Concepts Manual and the |
227 | ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 214 | ":ref:`dev-manual/layers:understanding and creating layers`" |
228 | section for more information on layers. | 215 | section for more information on layers. |
229 | 216 | ||
230 | - Separate the project's Metadata and code by using separate Git | 217 | - Separate the project's Metadata and code by using separate Git |
231 | repositories. See the ":ref:`overview-manual/development-environment:yocto project source repositories`" | 218 | repositories. See the ":ref:`overview-manual/development-environment:yocto project source repositories`" |
232 | section in the Yocto Project Overview and Concepts Manual for | 219 | section in the Yocto Project Overview and Concepts Manual for |
233 | information on these repositories. See the "`Locating Yocto | 220 | information on these repositories. See the |
234 | Project Source Files <#locating-yocto-project-source-files>`__" | 221 | ":ref:`dev-manual/start:locating yocto project source files`" |
235 | section for information on how to set up local Git repositories | 222 | section for information on how to set up local Git repositories |
236 | for related upstream Yocto Project Git repositories. | 223 | for related upstream Yocto Project Git repositories. |
237 | 224 | ||
@@ -247,14 +234,13 @@ particular working environment and set of practices. | |||
247 | - The Yocto Project community encourages you to send patches to the | 234 | - The Yocto Project community encourages you to send patches to the |
248 | project to fix bugs or add features. If you do submit patches, | 235 | project to fix bugs or add features. If you do submit patches, |
249 | follow the project commit guidelines for writing good commit | 236 | follow the project commit guidelines for writing good commit |
250 | messages. See the | 237 | messages. See the ":doc:`../contributor-guide/submit-changes`" |
251 | ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" | 238 | section in the Yocto Project and OpenEmbedded Contributor Guide. |
252 | section. | ||
253 | 239 | ||
254 | - Send changes to the core sooner than later as others are likely | 240 | - Send changes to the core sooner than later as others are likely |
255 | to run into the same issues. For some guidance on mailing lists | 241 | to run into the same issues. For some guidance on mailing lists |
256 | to use, see the list in the | 242 | to use, see the lists in the |
257 | ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" | 243 | ":ref:`contributor-guide/submit-changes:finding a suitable mailing list`" |
258 | section. For a description | 244 | section. For a description |
259 | of the available mailing lists, see the ":ref:`resources-mailinglist`" section in | 245 | of the available mailing lists, see the ":ref:`resources-mailinglist`" section in |
260 | the Yocto Project Reference Manual. | 246 | the Yocto Project Reference Manual. |
@@ -268,16 +254,16 @@ development using the Yocto Project. Your build host can be a native | |||
268 | Linux machine (recommended), it can be a machine (Linux, Mac, or | 254 | Linux machine (recommended), it can be a machine (Linux, Mac, or |
269 | Windows) that uses `CROPS <https://github.com/crops/poky-container>`__, | 255 | Windows) that uses `CROPS <https://github.com/crops/poky-container>`__, |
270 | which leverages `Docker Containers <https://www.docker.com/>`__ or it | 256 | which leverages `Docker Containers <https://www.docker.com/>`__ or it |
271 | can be a Windows machine capable of running Windows Subsystem For Linux | 257 | can be a Windows machine capable of running version 2 of Windows Subsystem |
272 | v2 (WSL). | 258 | For Linux (WSL 2). |
273 | 259 | ||
274 | .. note:: | 260 | .. note:: |
275 | 261 | ||
276 | The Yocto Project is not compatible with | 262 | The Yocto Project is not compatible with version 1 of |
277 | `Windows Subsystem for Linux v1 <https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux>`__. | 263 | :wikipedia:`Windows Subsystem for Linux <Windows_Subsystem_for_Linux>`. |
278 | It is compatible but not officially supported nor validated with | 264 | It is compatible but neither officially supported nor validated with |
279 | WSLv2. If you still decide to use WSL please upgrade to | 265 | WSL 2. If you still decide to use WSL please upgrade to |
280 | `WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__. | 266 | `WSL 2 <https://learn.microsoft.com/en-us/windows/wsl/install>`__. |
281 | 267 | ||
282 | Once your build host is set up to use the Yocto Project, further steps | 268 | Once your build host is set up to use the Yocto Project, further steps |
283 | are necessary depending on what you want to accomplish. See the | 269 | are necessary depending on what you want to accomplish. See the |
@@ -297,38 +283,40 @@ Setting Up a Native Linux Host | |||
297 | Follow these steps to prepare a native Linux machine as your Yocto | 283 | Follow these steps to prepare a native Linux machine as your Yocto |
298 | Project Build Host: | 284 | Project Build Host: |
299 | 285 | ||
300 | 1. *Use a Supported Linux Distribution:* You should have a reasonably | 286 | #. *Use a Supported Linux Distribution:* You should have a reasonably |
301 | current Linux-based host system. You will have the best results with | 287 | current Linux-based host system. You will have the best results with |
302 | a recent release of Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS | 288 | a recent release of Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS |
303 | as these releases are frequently tested against the Yocto Project and | 289 | as these releases are frequently tested against the Yocto Project and |
304 | officially supported. For a list of the distributions under | 290 | officially supported. For a list of the distributions under |
305 | validation and their status, see the ":ref:`Supported Linux | 291 | validation and their status, see the ":ref:`Supported Linux |
306 | Distributions <detailed-supported-distros>`" | 292 | Distributions <system-requirements-supported-distros>`" |
307 | section in the Yocto Project Reference Manual and the wiki page at | 293 | section in the Yocto Project Reference Manual and the wiki page at |
308 | :yocto_wiki:`Distribution Support </Distribution_Support>`. | 294 | :yocto_wiki:`Distribution Support </Distribution_Support>`. |
309 | 295 | ||
310 | 2. *Have Enough Free Memory:* Your system should have at least 50 Gbytes | 296 | #. *Have Enough Free Memory:* Your system should have at least 50 Gbytes |
311 | of free disk space for building images. | 297 | of free disk space for building images. |
312 | 298 | ||
313 | 3. *Meet Minimal Version Requirements:* The OpenEmbedded build system | 299 | #. *Meet Minimal Version Requirements:* The OpenEmbedded build system |
314 | should be able to run on any modern distribution that has the | 300 | should be able to run on any modern distribution that has the |
315 | following versions for Git, tar, Python and gcc. | 301 | following versions for Git, tar, Python, gcc and make. |
302 | |||
303 | - Git &MIN_GIT_VERSION; or greater | ||
316 | 304 | ||
317 | - Git 1.8.3.1 or greater | 305 | - tar &MIN_TAR_VERSION; or greater |
318 | 306 | ||
319 | - tar 1.28 or greater | 307 | - Python &MIN_PYTHON_VERSION; or greater. |
320 | 308 | ||
321 | - Python 3.5.0 or greater. | 309 | - gcc &MIN_GCC_VERSION; or greater. |
322 | 310 | ||
323 | - gcc 5.0 or greater. | 311 | - GNU make &MIN_MAKE_VERSION; or greater |
324 | 312 | ||
325 | If your build host does not meet any of these three listed version | 313 | If your build host does not meet any of these listed version |
326 | requirements, you can take steps to prepare the system so that you | 314 | requirements, you can take steps to prepare the system so that you |
327 | can still use the Yocto Project. See the | 315 | can still use the Yocto Project. See the |
328 | ":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`" | 316 | ":ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`" |
329 | section in the Yocto Project Reference Manual for information. | 317 | section in the Yocto Project Reference Manual for information. |
330 | 318 | ||
331 | 4. *Install Development Host Packages:* Required development host | 319 | #. *Install Development Host Packages:* Required development host |
332 | packages vary depending on your build host and what you want to do | 320 | packages vary depending on your build host and what you want to do |
333 | with the Yocto Project. Collectively, the number of required packages | 321 | with the Yocto Project. Collectively, the number of required packages |
334 | is large if you want to be able to cover all cases. | 322 | is large if you want to be able to cover all cases. |
@@ -346,7 +334,10 @@ to use the Extensible SDK, see the ":doc:`/sdk-manual/extensible`" Chapter in th | |||
346 | Project Application Development and the Extensible Software Development | 334 | Project Application Development and the Extensible Software Development |
347 | Kit (eSDK) manual. If you want to work on the kernel, see the :doc:`/kernel-dev/index`. If you are going to use | 335 | Kit (eSDK) manual. If you want to work on the kernel, see the :doc:`/kernel-dev/index`. If you are going to use |
348 | Toaster, see the ":doc:`/toaster-manual/setup-and-use`" | 336 | Toaster, see the ":doc:`/toaster-manual/setup-and-use`" |
349 | section in the Toaster User Manual. | 337 | section in the Toaster User Manual. If you are a VSCode user, you can configure |
338 | the `Yocto Project BitBake | ||
339 | <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__ | ||
340 | extension accordingly. | ||
350 | 341 | ||
351 | Setting Up to Use CROss PlatformS (CROPS) | 342 | Setting Up to Use CROss PlatformS (CROPS) |
352 | ----------------------------------------- | 343 | ----------------------------------------- |
@@ -360,7 +351,7 @@ Yocto Project on a Windows, Mac, or Linux machine. | |||
360 | Follow these general steps to prepare a Windows, Mac, or Linux machine | 351 | Follow these general steps to prepare a Windows, Mac, or Linux machine |
361 | as your Yocto Project build host: | 352 | as your Yocto Project build host: |
362 | 353 | ||
363 | 1. *Determine What Your Build Host Needs:* | 354 | #. *Determine What Your Build Host Needs:* |
364 | `Docker <https://www.docker.com/what-docker>`__ is a software | 355 | `Docker <https://www.docker.com/what-docker>`__ is a software |
365 | container platform that you need to install on the build host. | 356 | container platform that you need to install on the build host. |
366 | Depending on your build host, you might have to install different | 357 | Depending on your build host, you might have to install different |
@@ -369,65 +360,57 @@ as your Yocto Project build host: | |||
369 | Platforms <https://docs.docker.com/engine/install/#supported-platforms>`__" | 360 | Platforms <https://docs.docker.com/engine/install/#supported-platforms>`__" |
370 | your build host needs to run containers. | 361 | your build host needs to run containers. |
371 | 362 | ||
372 | 2. *Choose What To Install:* Depending on whether or not your build host | 363 | #. *Choose What To Install:* Depending on whether or not your build host |
373 | meets system requirements, you need to install "Docker CE Stable" or | 364 | meets system requirements, you need to install "Docker CE Stable" or |
374 | the "Docker Toolbox". Most situations call for Docker CE. However, if | 365 | the "Docker Toolbox". Most situations call for Docker CE. However, if |
375 | you have a build host that does not meet requirements (e.g. | 366 | you have a build host that does not meet requirements (e.g. |
376 | Pre-Windows 10 or Windows 10 "Home" version), you must install Docker | 367 | Pre-Windows 10 or Windows 10 "Home" version), you must install Docker |
377 | Toolbox instead. | 368 | Toolbox instead. |
378 | 369 | ||
379 | 3. *Go to the Install Site for Your Platform:* Click the link for the | 370 | #. *Go to the Install Site for Your Platform:* Click the link for the |
380 | Docker edition associated with your build host's native software. For | 371 | Docker edition associated with your build host's native software. For |
381 | example, if your build host is running Microsoft Windows Version 10 | 372 | example, if your build host is running Microsoft Windows Version 10 |
382 | and you want the Docker CE Stable edition, click that link under | 373 | and you want the Docker CE Stable edition, click that link under |
383 | "Supported Platforms". | 374 | "Supported Platforms". |
384 | 375 | ||
385 | 4. *Install the Software:* Once you have understood all the | 376 | #. *Install the Software:* Once you have understood all the |
386 | pre-requisites, you can download and install the appropriate | 377 | pre-requisites, you can download and install the appropriate |
387 | software. Follow the instructions for your specific machine and the | 378 | software. Follow the instructions for your specific machine and the |
388 | type of the software you need to install: | 379 | type of the software you need to install: |
389 | 380 | ||
390 | - Install `Docker CE for | 381 | - Install `Docker Desktop on |
391 | Windows <https://docs.docker.com/docker-for-windows/install/#install-docker-desktop-on-windows>`__ | 382 | Windows <https://docs.docker.com/docker-for-windows/install/#install-docker-desktop-on-windows>`__ |
392 | for Windows build hosts that meet requirements. | 383 | for Windows build hosts that meet requirements. |
393 | 384 | ||
394 | - Install `Docker CE for | 385 | - Install `Docker Desktop on |
395 | MacOs <https://docs.docker.com/docker-for-mac/install/#install-and-run-docker-desktop-on-mac>`__ | 386 | MacOs <https://docs.docker.com/docker-for-mac/install/#install-and-run-docker-desktop-on-mac>`__ |
396 | for Mac build hosts that meet requirements. | 387 | for Mac build hosts that meet requirements. |
397 | 388 | ||
398 | - Install `Docker Toolbox for | 389 | - Install `Docker Engine on |
399 | Windows <https://docs.docker.com/toolbox/toolbox_install_windows/>`__ | 390 | CentOS <https://docs.docker.com/engine/install/centos/>`__ |
400 | for Windows build hosts that do not meet Docker requirements. | ||
401 | |||
402 | - Install `Docker Toolbox for | ||
403 | MacOS <https://docs.docker.com/toolbox/toolbox_install_mac/>`__ | ||
404 | for Mac build hosts that do not meet Docker requirements. | ||
405 | |||
406 | - Install `Docker CE for | ||
407 | CentOS <https://docs.docker.com/install/linux/docker-ce/centos/>`__ | ||
408 | for Linux build hosts running the CentOS distribution. | 391 | for Linux build hosts running the CentOS distribution. |
409 | 392 | ||
410 | - Install `Docker CE for | 393 | - Install `Docker Engine on |
411 | Debian <https://docs.docker.com/install/linux/docker-ce/debian/>`__ | 394 | Debian <https://docs.docker.com/engine/install/debian/>`__ |
412 | for Linux build hosts running the Debian distribution. | 395 | for Linux build hosts running the Debian distribution. |
413 | 396 | ||
414 | - Install `Docker CE for | 397 | - Install `Docker Engine for |
415 | Fedora <https://docs.docker.com/install/linux/docker-ce/fedora/>`__ | 398 | Fedora <https://docs.docker.com/engine/install/fedora/>`__ |
416 | for Linux build hosts running the Fedora distribution. | 399 | for Linux build hosts running the Fedora distribution. |
417 | 400 | ||
418 | - Install `Docker CE for | 401 | - Install `Docker Engine for |
419 | Ubuntu <https://docs.docker.com/install/linux/docker-ce/ubuntu/>`__ | 402 | Ubuntu <https://docs.docker.com/engine/install/ubuntu/>`__ |
420 | for Linux build hosts running the Ubuntu distribution. | 403 | for Linux build hosts running the Ubuntu distribution. |
421 | 404 | ||
422 | 5. *Optionally Orient Yourself With Docker:* If you are unfamiliar with | 405 | #. *Optionally Orient Yourself With Docker:* If you are unfamiliar with |
423 | Docker and the container concept, you can learn more here - | 406 | Docker and the container concept, you can learn more here - |
424 | https://docs.docker.com/get-started/. | 407 | https://docs.docker.com/get-started/. |
425 | 408 | ||
426 | 6. *Launch Docker or Docker Toolbox:* You should be able to launch | 409 | #. *Launch Docker or Docker Toolbox:* You should be able to launch |
427 | Docker or the Docker Toolbox and have a terminal shell on your | 410 | Docker or the Docker Toolbox and have a terminal shell on your |
428 | development host. | 411 | development host. |
429 | 412 | ||
430 | 7. *Set Up the Containers to Use the Yocto Project:* Go to | 413 | #. *Set Up the Containers to Use the Yocto Project:* Go to |
431 | https://github.com/crops/docker-win-mac-docs/wiki and follow | 414 | https://github.com/crops/docker-win-mac-docs/wiki and follow |
432 | the directions for your particular build host (i.e. Linux, Mac, or | 415 | the directions for your particular build host (i.e. Linux, Mac, or |
433 | Windows). | 416 | Windows). |
@@ -446,37 +429,41 @@ section. If you are going to use the Extensible SDK container, see the | |||
446 | Project Application Development and the Extensible Software Development | 429 | Project Application Development and the Extensible Software Development |
447 | Kit (eSDK) manual. If you are going to use the Toaster container, see | 430 | Kit (eSDK) manual. If you are going to use the Toaster container, see |
448 | the ":doc:`/toaster-manual/setup-and-use`" | 431 | the ":doc:`/toaster-manual/setup-and-use`" |
449 | section in the Toaster User Manual. | 432 | section in the Toaster User Manual. If you are a VSCode user, you can configure |
433 | the `Yocto Project BitBake | ||
434 | <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__ | ||
435 | extension accordingly. | ||
450 | 436 | ||
451 | Setting Up to Use Windows Subsystem For Linux (WSLv2) | 437 | Setting Up to Use Windows Subsystem For Linux (WSL 2) |
452 | ----------------------------------------------------- | 438 | ----------------------------------------------------- |
453 | 439 | ||
454 | With `Windows Subsystem for Linux | 440 | With `Windows Subsystem for Linux (WSL 2) |
455 | (WSLv2) <https://docs.microsoft.com/en-us/windows/wsl/wsl2-about>`__, | 441 | <https://learn.microsoft.com/en-us/windows/wsl/>`__, |
456 | you can create a Yocto Project development environment that allows you | 442 | you can create a Yocto Project development environment that allows you |
457 | to build on Windows. You can set up a Linux distribution inside Windows | 443 | to build on Windows. You can set up a Linux distribution inside Windows |
458 | in which you can develop using the Yocto Project. | 444 | in which you can develop using the Yocto Project. |
459 | 445 | ||
460 | Follow these general steps to prepare a Windows machine using WSLv2 as | 446 | Follow these general steps to prepare a Windows machine using WSL 2 as |
461 | your Yocto Project build host: | 447 | your Yocto Project build host: |
462 | 448 | ||
463 | 1. *Make sure your Windows 10 machine is capable of running WSLv2:* | 449 | #. *Make sure your Windows machine is capable of running WSL 2:* |
464 | WSLv2 is only available for Windows 10 builds > 18917. To check which | 450 | |
465 | build version you are running, you may open a command prompt on | 451 | While all Windows 11 and Windows Server 2022 builds support WSL 2, |
466 | Windows and execute the command "ver". | 452 | the first versions of Windows 10 and Windows Server 2019 didn't. |
467 | :: | 453 | Check the minimum build numbers for `Windows 10 |
454 | <https://learn.microsoft.com/en-us/windows/wsl/install-manual#step-2---check-requirements-for-running-wsl-2>`__ | ||
455 | and for `Windows Server 2019 | ||
456 | <https://learn.microsoft.com/en-us/windows/wsl/install-on-server>`__. | ||
457 | |||
458 | To check which build version you are running, you may open a command | ||
459 | prompt on Windows and execute the command "ver":: | ||
468 | 460 | ||
469 | C:\Users\myuser> ver | 461 | C:\Users\myuser> ver |
470 | 462 | ||
471 | Microsoft Windows [Version 10.0.19041.153] | 463 | Microsoft Windows [Version 10.0.19041.153] |
472 | 464 | ||
473 | If your build is capable of running | 465 | #. *Install the Linux distribution of your choice inside WSL 2:* |
474 | WSLv2 you may continue, for more information on this subject or | 466 | Once you know your version of Windows supports WSL 2, you can |
475 | instructions on how to upgrade to WSLv2 visit `Windows 10 | ||
476 | WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/wsl2-install>`__ | ||
477 | |||
478 | 2. *Install the Linux distribution of your choice inside Windows 10:* | ||
479 | Once you know your version of Windows 10 supports WSLv2, you can | ||
480 | install the distribution of your choice from the Microsoft Store. | 467 | install the distribution of your choice from the Microsoft Store. |
481 | Open the Microsoft Store and search for Linux. While there are | 468 | Open the Microsoft Store and search for Linux. While there are |
482 | several Linux distributions available, the assumption is that your | 469 | several Linux distributions available, the assumption is that your |
@@ -485,37 +472,33 @@ your Yocto Project build host: | |||
485 | making your selection, simply click "Get" to download and install the | 472 | making your selection, simply click "Get" to download and install the |
486 | distribution. | 473 | distribution. |
487 | 474 | ||
488 | 3. *Check your Linux distribution is using WSLv2:* Open a Windows | 475 | #. *Check which Linux distribution WSL 2 is using:* Open a Windows |
489 | PowerShell and run: | 476 | PowerShell and run:: |
490 | :: | ||
491 | 477 | ||
492 | C:\WINDOWS\system32> wsl -l -v | 478 | C:\WINDOWS\system32> wsl -l -v |
493 | NAME STATE VERSION | 479 | NAME STATE VERSION |
494 | *Ubuntu Running 2 | 480 | *Ubuntu Running 2 |
495 | 481 | ||
496 | Note the version column which says the WSL version | 482 | Note that WSL 2 supports running as many different Linux distributions |
497 | being used by your distribution, on compatible systems, this can be | 483 | as you want to install. |
498 | changed back at any point in time. | ||
499 | 484 | ||
500 | 4. *Optionally Orient Yourself on WSL:* If you are unfamiliar with WSL, | 485 | #. *Optionally Get Familiar with WSL:* You can learn more on |
501 | you can learn more here - | ||
502 | https://docs.microsoft.com/en-us/windows/wsl/wsl2-about. | 486 | https://docs.microsoft.com/en-us/windows/wsl/wsl2-about. |
503 | 487 | ||
504 | 5. *Launch your WSL Distibution:* From the Windows start menu simply | 488 | #. *Launch your WSL Distibution:* From the Windows start menu simply |
505 | launch your WSL distribution just like any other application. | 489 | launch your WSL distribution just like any other application. |
506 | 490 | ||
507 | 6. *Optimize your WSLv2 storage often:* Due to the way storage is | 491 | #. *Optimize your WSL 2 storage often:* Due to the way storage is |
508 | handled on WSLv2, the storage space used by the undelying Linux | 492 | handled on WSL 2, the storage space used by the underlying Linux |
509 | distribution is not reflected immedately, and since bitbake heavily | 493 | distribution is not reflected immediately, and since BitBake heavily |
510 | uses storage, after several builds, you may be unaware you are | 494 | uses storage, after several builds, you may be unaware you are |
511 | running out of space. WSLv2 uses a VHDX file for storage, this issue | 495 | running out of space. As WSL 2 uses a VHDX file for storage, this issue |
512 | can be easily avoided by manually optimizing this file often, this | 496 | can be easily avoided by regularly optimizing this file in a manual way: |
513 | can be done in the following way: | ||
514 | 497 | ||
515 | 1. *Find the location of your VHDX file:* First you need to find the | 498 | 1. *Find the location of your VHDX file:* |
516 | distro app package directory, to achieve this open a Windows | 499 | |
517 | Powershell as Administrator and run: | 500 | First you need to find the distro app package directory, to achieve this |
518 | :: | 501 | open a Windows Powershell as Administrator and run:: |
519 | 502 | ||
520 | C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName | 503 | C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName |
521 | PackageFamilyName | 504 | PackageFamilyName |
@@ -525,43 +508,62 @@ your Yocto Project build host: | |||
525 | 508 | ||
526 | You should now | 509 | You should now |
527 | replace the PackageFamilyName and your user on the following path | 510 | replace the PackageFamilyName and your user on the following path |
528 | to find your VHDX file: | 511 | to find your VHDX file:: |
529 | :: | ||
530 | 512 | ||
531 | ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ | 513 | ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ |
532 | Mode LastWriteTime Length Name | 514 | Mode LastWriteTime Length Name |
533 | -a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx | 515 | -a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx |
534 | 516 | ||
535 | Your VHDX file path is: | 517 | Your VHDX file path is: |
536 | ``C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx`` | 518 | ``C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx`` |
537 | 519 | ||
538 | 2. *Optimize your VHDX file:* Open a Windows Powershell as | 520 | 2a. *Optimize your VHDX file using Windows Powershell:* |
539 | Administrator to optimize your VHDX file, shutting down WSL first: | 521 | |
540 | :: | 522 | To use the ``optimize-vhd`` cmdlet below, first install the Hyper-V |
523 | option on Windows. Then, open a Windows Powershell as Administrator to | ||
524 | optimize your VHDX file, shutting down WSL first:: | ||
541 | 525 | ||
542 | C:\WINDOWS\system32> wsl --shutdown | 526 | C:\WINDOWS\system32> wsl --shutdown |
543 | C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full | 527 | C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full |
544 | 528 | ||
545 | A progress bar should be shown while optimizing the | 529 | A progress bar should be shown while optimizing the |
546 | VHDX file, and storage should now be reflected correctly on the | 530 | VHDX file, and storage should now be reflected correctly on the |
547 | Windows Explorer. | 531 | Windows Explorer. |
532 | |||
533 | 2b. *Optimize your VHDX file using DiskPart:* | ||
534 | |||
535 | The ``optimize-vhd`` cmdlet noted in step 2a above is provided by | ||
536 | Hyper-V. Not all SKUs of Windows can install Hyper-V. As an alternative, | ||
537 | use the DiskPart tool. To start, open a Windows command prompt as | ||
538 | Administrator to optimize your VHDX file, shutting down WSL first:: | ||
539 | |||
540 | C:\WINDOWS\system32> wsl --shutdown | ||
541 | C:\WINDOWS\system32> diskpart | ||
542 | |||
543 | DISKPART> select vdisk file="<path_to_VHDX_file>" | ||
544 | DISKPART> attach vdisk readonly | ||
545 | DISKPART> compact vdisk | ||
546 | DISKPART> exit | ||
548 | 547 | ||
549 | .. note:: | 548 | .. note:: |
550 | 549 | ||
551 | The current implementation of WSLv2 does not have out-of-the-box | 550 | The current implementation of WSL 2 does not have out-of-the-box |
552 | access to external devices such as those connected through a USB | 551 | access to external devices such as those connected through a USB |
553 | port, but it automatically mounts your ``C:`` drive on ``/mnt/c/`` | 552 | port, but it automatically mounts your ``C:`` drive on ``/mnt/c/`` |
554 | (and others), which you can use to share deploy artifacts to be later | 553 | (and others), which you can use to share deploy artifacts to be later |
555 | flashed on hardware through Windows, but your build directory should | 554 | flashed on hardware through Windows, but your :term:`Build Directory` |
556 | not reside inside this mountpoint. | 555 | should not reside inside this mountpoint. |
557 | 556 | ||
558 | Once you have WSLv2 set up, everything is in place to develop just as if | 557 | Once you have WSL 2 set up, everything is in place to develop just as if |
559 | you were running on a native Linux machine. If you are going to use the | 558 | you were running on a native Linux machine. If you are going to use the |
560 | Extensible SDK container, see the ":doc:`/sdk-manual/extensible`" Chapter in the Yocto | 559 | Extensible SDK container, see the ":doc:`/sdk-manual/extensible`" Chapter in the Yocto |
561 | Project Application Development and the Extensible Software Development | 560 | Project Application Development and the Extensible Software Development |
562 | Kit (eSDK) manual. If you are going to use the Toaster container, see | 561 | Kit (eSDK) manual. If you are going to use the Toaster container, see |
563 | the ":doc:`/toaster-manual/setup-and-use`" | 562 | the ":doc:`/toaster-manual/setup-and-use`" |
564 | section in the Toaster User Manual. | 563 | section in the Toaster User Manual. If you are a VSCode user, you can configure |
564 | the `Yocto Project BitBake | ||
565 | <https://marketplace.visualstudio.com/items?itemName=yocto-project.yocto-bitbake>`__ | ||
566 | extension accordingly. | ||
565 | 567 | ||
566 | Locating Yocto Project Source Files | 568 | Locating Yocto Project Source Files |
567 | =================================== | 569 | =================================== |
@@ -591,14 +593,14 @@ repository at :yocto_git:`/poky`. | |||
591 | Use the following procedure to locate the latest upstream copy of the | 593 | Use the following procedure to locate the latest upstream copy of the |
592 | ``poky`` Git repository: | 594 | ``poky`` Git repository: |
593 | 595 | ||
594 | 1. *Access Repositories:* Open a browser and go to | 596 | #. *Access Repositories:* Open a browser and go to |
595 | :yocto_git:`/` to access the GUI-based interface into the | 597 | :yocto_git:`/` to access the GUI-based interface into the |
596 | Yocto Project source repositories. | 598 | Yocto Project source repositories. |
597 | 599 | ||
598 | 2. *Select the Repository:* Click on the repository in which you are | 600 | #. *Select the Repository:* Click on the repository in which you are |
599 | interested (e.g. ``poky``). | 601 | interested (e.g. ``poky``). |
600 | 602 | ||
601 | 3. *Find the URL Used to Clone the Repository:* At the bottom of the | 603 | #. *Find the URL Used to Clone the Repository:* At the bottom of the |
602 | page, note the URL used to clone that repository | 604 | page, note the URL used to clone that repository |
603 | (e.g. :yocto_git:`/poky`). | 605 | (e.g. :yocto_git:`/poky`). |
604 | 606 | ||
@@ -607,73 +609,43 @@ Use the following procedure to locate the latest upstream copy of the | |||
607 | For information on cloning a repository, see the | 609 | For information on cloning a repository, see the |
608 | ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" section. | 610 | ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" section. |
609 | 611 | ||
610 | Accessing Index of Releases | 612 | Accessing Source Archives |
611 | --------------------------- | 613 | ------------------------- |
614 | |||
615 | The Yocto Project also provides source archives of its releases, which | ||
616 | are available on :yocto_dl:`/releases/yocto/`. Then, choose the subdirectory | ||
617 | containing the release you wish to use, for example | ||
618 | :yocto_dl:`yocto-&DISTRO; </releases/yocto/yocto-&DISTRO;/>`. | ||
612 | 619 | ||
613 | Yocto Project maintains an Index of Releases area that contains related | 620 | You will find there source archives of individual components (if you wish |
614 | files that contribute to the Yocto Project. Rather than Git | 621 | to use them individually), and of the corresponding Poky release bundling |
615 | repositories, these files are tarballs that represent snapshots in time | 622 | a selection of these components. |
616 | of a given component. | ||
617 | 623 | ||
618 | .. note:: | 624 | .. note:: |
619 | 625 | ||
620 | The recommended method for accessing Yocto Project components is to | 626 | The recommended method for accessing Yocto Project components is to |
621 | use Git to clone the upstream repository and work from within that | 627 | use Git to clone the upstream repository and work from within that |
622 | locally cloned repository. The procedure in this section exists | 628 | locally cloned repository. |
623 | should you desire a tarball snapshot of any given component. | ||
624 | |||
625 | Follow these steps to locate and download a particular tarball: | ||
626 | |||
627 | 1. *Access the Index of Releases:* Open a browser and go to | ||
628 | :yocto_dl:`Index of Releases </releases>`. The | ||
629 | list represents released components (e.g. ``bitbake``, ``sato``, and | ||
630 | so on). | ||
631 | |||
632 | .. note:: | ||
633 | |||
634 | The ``yocto`` directory contains the full array of released Poky | ||
635 | tarballs. The ``poky`` directory in the Index of Releases was | ||
636 | historically used for very early releases and exists now only for | ||
637 | retroactive completeness. | ||
638 | |||
639 | 2. *Select a Component:* Click on any released component in which you | ||
640 | are interested (e.g. ``yocto``). | ||
641 | |||
642 | 3. *Find the Tarball:* Drill down to find the associated tarball. For | ||
643 | example, click on ``yocto-&DISTRO;`` to view files associated with the | ||
644 | Yocto Project &DISTRO; release (e.g. | ||
645 | ``&YOCTO_POKY;.tar.bz2``, which is the | ||
646 | released Poky tarball). | ||
647 | |||
648 | 4. *Download the Tarball:* Click the tarball to download and save a | ||
649 | snapshot of the given component. | ||
650 | 629 | ||
651 | Using the Downloads Page | 630 | Using the Downloads Page |
652 | ------------------------ | 631 | ------------------------ |
653 | 632 | ||
654 | The :yocto_home:`Yocto Project Website <>` uses a "DOWNLOADS" page | 633 | The :yocto_home:`Yocto Project Website <>` uses a "RELEASES" page |
655 | from which you can locate and download tarballs of any Yocto Project | 634 | from which you can locate and download tarballs of any Yocto Project |
656 | release. Rather than Git repositories, these files represent snapshot | 635 | release. Rather than Git repositories, these files represent snapshot |
657 | tarballs similar to the tarballs located in the Index of Releases | 636 | tarballs similar to the tarballs located in the Index of Releases |
658 | described in the "`Accessing Index of | 637 | described in the ":ref:`dev-manual/start:accessing source archives`" section. |
659 | Releases <#accessing-index-of-releases>`__" section. | ||
660 | |||
661 | .. note:: | ||
662 | |||
663 | The recommended method for accessing Yocto Project components is to | ||
664 | use Git to clone a repository and work from within that local | ||
665 | repository. The procedure in this section exists should you desire a | ||
666 | tarball snapshot of any given component. | ||
667 | 638 | ||
668 | 1. *Go to the Yocto Project Website:* Open The | 639 | #. *Go to the Yocto Project Website:* Open The |
669 | :yocto_home:`Yocto Project Website <>` in your browser. | 640 | :yocto_home:`Yocto Project Website <>` in your browser. |
670 | 641 | ||
671 | 2. *Get to the Downloads Area:* Select the "DOWNLOADS" item from the | 642 | #. *Get to the Downloads Area:* Select the "RELEASES" item from the |
672 | pull-down "SOFTWARE" tab menu near the top of the page. | 643 | pull-down "DEVELOPMENT" tab menu near the top of the page. |
673 | 644 | ||
674 | 3. *Select a Yocto Project Release:* Use the menu next to "RELEASE" to | 645 | #. *Select a Yocto Project Release:* On the top of the "RELEASE" page currently |
675 | display and choose a recent or past supported Yocto Project release | 646 | supported releases are displayed, further down past supported Yocto Project |
676 | (e.g. &DISTRO_NAME_NO_CAP;, &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth). | 647 | releases are visible. The "Download" links in the rows of the table there |
648 | will lead to the download tarballs for the release. | ||
677 | 649 | ||
678 | .. note:: | 650 | .. note:: |
679 | 651 | ||
@@ -683,35 +655,9 @@ Releases <#accessing-index-of-releases>`__" section. | |||
683 | You can use the "RELEASE ARCHIVE" link to reveal a menu of all Yocto | 655 | You can use the "RELEASE ARCHIVE" link to reveal a menu of all Yocto |
684 | Project releases. | 656 | Project releases. |
685 | 657 | ||
686 | 4. *Download Tools or Board Support Packages (BSPs):* From the | 658 | #. *Download Tools or Board Support Packages (BSPs):* Next to the tarballs you |
687 | "DOWNLOADS" page, you can download tools or BSPs as well. Just scroll | 659 | will find download tools or BSPs as well. Just select a Yocto Project |
688 | down the page and look for what you need. | 660 | release and look for what you need. |
689 | |||
690 | Accessing Nightly Builds | ||
691 | ------------------------ | ||
692 | |||
693 | Yocto Project maintains an area for nightly builds that contains tarball | ||
694 | releases at https://autobuilder.yocto.io//pub/nightly/. These builds include Yocto | ||
695 | Project releases ("poky"), toolchains, and builds for supported | ||
696 | machines. | ||
697 | |||
698 | Should you ever want to access a nightly build of a particular Yocto | ||
699 | Project component, use the following procedure: | ||
700 | |||
701 | 1. *Locate the Index of Nightly Builds:* Open a browser and go to | ||
702 | https://autobuilder.yocto.io//pub/nightly/ to access the Nightly Builds. | ||
703 | |||
704 | 2. *Select a Date:* Click on the date in which you are interested. If | ||
705 | you want the latest builds, use "CURRENT". | ||
706 | |||
707 | 3. *Select a Build:* Choose the area in which you are interested. For | ||
708 | example, if you are looking for the most recent toolchains, select | ||
709 | the "toolchain" link. | ||
710 | |||
711 | 4. *Find the Tarball:* Drill down to find the associated tarball. | ||
712 | |||
713 | 5. *Download the Tarball:* Click the tarball to download and save a | ||
714 | snapshot of the given component. | ||
715 | 661 | ||
716 | Cloning and Checking Out Branches | 662 | Cloning and Checking Out Branches |
717 | ================================= | 663 | ================================= |
@@ -737,13 +683,12 @@ Cloning the ``poky`` Repository | |||
737 | Follow these steps to create a local version of the upstream | 683 | Follow these steps to create a local version of the upstream |
738 | :term:`Poky` Git repository. | 684 | :term:`Poky` Git repository. |
739 | 685 | ||
740 | 1. *Set Your Directory:* Change your working directory to where you want | 686 | #. *Set Your Directory:* Change your working directory to where you want |
741 | to create your local copy of ``poky``. | 687 | to create your local copy of ``poky``. |
742 | 688 | ||
743 | 2. *Clone the Repository:* The following example command clones the | 689 | #. *Clone the Repository:* The following example command clones the |
744 | ``poky`` repository and uses the default name "poky" for your local | 690 | ``poky`` repository and uses the default name "poky" for your local |
745 | repository: | 691 | repository:: |
746 | :: | ||
747 | 692 | ||
748 | $ git clone git://git.yoctoproject.org/poky | 693 | $ git clone git://git.yoctoproject.org/poky |
749 | Cloning into 'poky'... | 694 | Cloning into 'poky'... |
@@ -759,16 +704,15 @@ Follow these steps to create a local version of the upstream | |||
759 | "master" branch, which results in a snapshot of the latest | 704 | "master" branch, which results in a snapshot of the latest |
760 | development changes for "master". For information on how to check out | 705 | development changes for "master". For information on how to check out |
761 | a specific development branch or on how to check out a local branch | 706 | a specific development branch or on how to check out a local branch |
762 | based on a tag name, see the "`Checking Out By Branch in | 707 | based on a tag name, see the |
763 | Poky <#checking-out-by-branch-in-poky>`__" and `Checking Out By Tag | 708 | ":ref:`dev-manual/start:checking out by branch in poky`" and |
764 | in Poky <#checkout-out-by-tag-in-poky>`__" sections, respectively. | 709 | ":ref:`dev-manual/start:checking out by tag in poky`" sections, respectively. |
765 | 710 | ||
766 | Once the local repository is created, you can change to that | 711 | Once the local repository is created, you can change to that |
767 | directory and check its status. Here, the single "master" branch | 712 | directory and check its status. The ``master`` branch is checked out |
768 | exists on your system and by default, it is checked out: | 713 | by default:: |
769 | :: | ||
770 | 714 | ||
771 | $ cd ~/poky | 715 | $ cd poky |
772 | $ git status | 716 | $ git status |
773 | On branch master | 717 | On branch master |
774 | Your branch is up-to-date with 'origin/master'. | 718 | Your branch is up-to-date with 'origin/master'. |
@@ -798,13 +742,13 @@ and then specifically check out that development branch. | |||
798 | Further development on top of the branch that occurs after check it | 742 | Further development on top of the branch that occurs after check it |
799 | out can occur. | 743 | out can occur. |
800 | 744 | ||
801 | 1. *Switch to the Poky Directory:* If you have a local poky Git | 745 | #. *Switch to the Poky Directory:* If you have a local poky Git |
802 | repository, switch to that directory. If you do not have the local | 746 | repository, switch to that directory. If you do not have the local |
803 | copy of poky, see the | 747 | copy of poky, see the |
804 | ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" | 748 | ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" |
805 | section. | 749 | section. |
806 | 750 | ||
807 | 2. *Determine Existing Branch Names:* | 751 | #. *Determine Existing Branch Names:* |
808 | :: | 752 | :: |
809 | 753 | ||
810 | $ git branch -a | 754 | $ git branch -a |
@@ -825,10 +769,9 @@ and then specifically check out that development branch. | |||
825 | remotes/origin/zeus-next | 769 | remotes/origin/zeus-next |
826 | ... and so on ... | 770 | ... and so on ... |
827 | 771 | ||
828 | 3. *Check out the Branch:* Check out the development branch in which you | 772 | #. *Check out the Branch:* Check out the development branch in which you |
829 | want to work. For example, to access the files for the Yocto Project | 773 | want to work. For example, to access the files for the Yocto Project |
830 | &DISTRO; Release (&DISTRO_NAME;), use the following command: | 774 | &DISTRO; Release (&DISTRO_NAME;), use the following command:: |
831 | :: | ||
832 | 775 | ||
833 | $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; | 776 | $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; |
834 | Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin. | 777 | Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin. |
@@ -840,8 +783,7 @@ and then specifically check out that development branch. | |||
840 | 783 | ||
841 | The following command displays the branches that are now part of your | 784 | The following command displays the branches that are now part of your |
842 | local poky repository. The asterisk character indicates the branch | 785 | local poky repository. The asterisk character indicates the branch |
843 | that is currently checked out for work: | 786 | that is currently checked out for work:: |
844 | :: | ||
845 | 787 | ||
846 | $ git branch | 788 | $ git branch |
847 | master | 789 | master |
@@ -861,21 +803,19 @@ similar to checking out by branch name except you use tag names. | |||
861 | Checking out a branch based on a tag gives you a stable set of files | 803 | Checking out a branch based on a tag gives you a stable set of files |
862 | not affected by development on the branch above the tag. | 804 | not affected by development on the branch above the tag. |
863 | 805 | ||
864 | 1. *Switch to the Poky Directory:* If you have a local poky Git | 806 | #. *Switch to the Poky Directory:* If you have a local poky Git |
865 | repository, switch to that directory. If you do not have the local | 807 | repository, switch to that directory. If you do not have the local |
866 | copy of poky, see the | 808 | copy of poky, see the |
867 | ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" | 809 | ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" |
868 | section. | 810 | section. |
869 | 811 | ||
870 | 2. *Fetch the Tag Names:* To checkout the branch based on a tag name, | 812 | #. *Fetch the Tag Names:* To checkout the branch based on a tag name, |
871 | you need to fetch the upstream tags into your local repository: | 813 | you need to fetch the upstream tags into your local repository:: |
872 | :: | ||
873 | 814 | ||
874 | $ git fetch --tags | 815 | $ git fetch --tags |
875 | $ | 816 | $ |
876 | 817 | ||
877 | 3. *List the Tag Names:* You can list the tag names now: | 818 | #. *List the Tag Names:* You can list the tag names now:: |
878 | :: | ||
879 | 819 | ||
880 | $ git tag | 820 | $ git tag |
881 | 1.1_M1.final | 821 | 1.1_M1.final |
@@ -897,7 +837,7 @@ similar to checking out by branch name except you use tag names. | |||
897 | yocto_1.5_M5.rc8 | 837 | yocto_1.5_M5.rc8 |
898 | 838 | ||
899 | 839 | ||
900 | 4. *Check out the Branch:* | 840 | #. *Check out the Branch:* |
901 | :: | 841 | :: |
902 | 842 | ||
903 | $ git checkout tags/yocto-&DISTRO; -b my_yocto_&DISTRO; | 843 | $ git checkout tags/yocto-&DISTRO; -b my_yocto_&DISTRO; |