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