diff options
Diffstat (limited to 'poky/documentation/dev-manual/dev-manual-start.xml')
-rw-r--r-- | poky/documentation/dev-manual/dev-manual-start.xml | 1288 |
1 files changed, 1288 insertions, 0 deletions
diff --git a/poky/documentation/dev-manual/dev-manual-start.xml b/poky/documentation/dev-manual/dev-manual-start.xml new file mode 100644 index 000000000..9ff9ac4c8 --- /dev/null +++ b/poky/documentation/dev-manual/dev-manual-start.xml @@ -0,0 +1,1288 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > +<!--SPDX-License-Identifier: CC-BY-2.0-UK--> + +<chapter id='dev-manual-start'> + +<title>Setting Up to Use the Yocto Project</title> + +<para> + This chapter provides guidance on how to prepare to use the + Yocto Project. + You can learn about creating a team environment that develops using the + Yocto Project, how to set up a + <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>, + how to locate Yocto Project source repositories, and how to create local + Git repositories. +</para> + +<section id="usingpoky-changes-collaborate"> + <title>Creating a Team Development Environment</title> + + <para> + It might not be immediately clear how you can use the Yocto + Project in a team development environment, or how to scale it for a + large team of developers. + You can adapt the Yocto Project to many different use cases and + scenarios; + however, this flexibility could cause difficulties if you are trying + to create a working setup that scales effectively. + </para> + + <para> + To help you understand how to set up this type of environment, + this section presents a procedure that gives you information + that can help you get the results you want. + The procedure is high-level and presents some of the project's most + successful experiences, practices, solutions, and available + technologies that have proved to work well in the past; + however, keep in mind, the procedure here is simply a starting point. + You can build off these steps and customize the procedure to fit any + particular working environment and set of practices. + <orderedlist> + <listitem><para> + <emphasis>Determine Who is Going to be Developing:</emphasis> + You first need to understand who is going to be doing anything + related to the Yocto Project and determine their roles. + Making this determination is essential to completing + subsequent steps, which are to get your equipment together + and set up your development environment's hardware topology. + </para> + + <para>The following roles exist: + <itemizedlist> + <listitem><para> + <emphasis>Application Developer:</emphasis> + This type of developer does application level work + on top of an existing software stack. + </para></listitem> + <listitem><para> + <emphasis>Core System Developer:</emphasis> + This type of developer works on the contents of the + operating system image itself. + </para></listitem> + <listitem><para> + <emphasis>Build Engineer:</emphasis> + This type of developer manages Autobuilders and + releases. Depending on the specifics of the environment, + not all situations might need a Build Engineer. + </para></listitem> + <listitem><para> + <emphasis>Test Engineer:</emphasis> + This type of developer creates and manages automated + tests that are used to ensure all application and + core system development meets desired quality + standards. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Gather the Hardware:</emphasis> + Based on the size and make-up of the team, get the hardware + together. + Ideally, any development, build, or test engineer uses + a system that runs a supported Linux distribution. + These systems, in general, should be high performance + (e.g. dual, six-core Xeons with 24 Gbytes of RAM and plenty + of disk space). + You can help ensure efficiency by having any machines used + for testing or that run Autobuilders be as high performance + as possible. + <note> + Given sufficient processing power, you might also consider + building Yocto Project development containers to be run + under Docker, which is described later. + </note> + </para></listitem> + <listitem><para> + <emphasis>Understand the Hardware Topology of the Environment:</emphasis> + Once you understand the hardware involved and the make-up + of the team, you can understand the hardware topology of the + development environment. + You can get a visual idea of the machines and their roles + across the development environment. + +<!-- + The following figure shows a moderately sized Yocto Project + development environment. + + <para role="writernotes"> + Need figure.</para> +--> + + </para></listitem> + <listitem><para> + <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis> + Keeping your + <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> + (i.e. recipes, configuration files, classes, and so forth) + and any software you are developing under the control of an SCM + system that is compatible with the OpenEmbedded build system + is advisable. + Of all of the SCMs supported by BitBake, the Yocto Project team strongly + recommends using + <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>. + Git is a distributed system that is easy to back up, + allows you to work remotely, and then connects back to the + infrastructure. + <note> + For information about BitBake, see the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. + </note></para> + + <para>It is relatively easy to set up Git services and create + infrastructure like + <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>, + which is based on server software called + <filename>gitolite</filename> with <filename>cgit</filename> + being used to generate the web interface that lets you view the + repositories. + The <filename>gitolite</filename> software identifies users + using SSH keys and allows branch-based access controls to + repositories that you can control as little or as much as + necessary. + <note> + The setup of these services is beyond the scope of this + manual. + However, sites such as the following exist that describe + how to perform setup: + <itemizedlist> + <listitem><para> + <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>: + Describes how to install + <filename>gitolite</filename> on the server. + </para></listitem> + <listitem><para> + <ulink url='http://gitolite.com'>Gitolite</ulink>: + Information for <filename>gitolite</filename>. + </para></listitem> + <listitem><para> + <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>: + Documentation on how to create interfaces and + frontends for Git. + </para></listitem> + </itemizedlist> + </note> + </para></listitem> + <listitem><para> + <emphasis>Set up the Application Development Machines:</emphasis> + As mentioned earlier, application developers are creating + applications on top of existing software stacks. + Following are some best practices for setting up machines + used for application development: + <itemizedlist> + <listitem><para> + Use a pre-built toolchain that contains the software + stack itself. + Then, develop the application code on top of the + stack. + This method works well for small numbers of relatively + isolated applications. + </para></listitem> + <listitem><para> + Keep your cross-development toolchains updated. + You can do this through provisioning either as new + toolchain downloads or as updates through a package + update mechanism using <filename>opkg</filename> + to provide updates to an existing toolchain. + The exact mechanics of how and when to do this depend + on local policy. + </para></listitem> + <listitem><para> + Use multiple toolchains installed locally into + different locations to allow development across + versions. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Set up the Core Development Machines:</emphasis> + As mentioned earlier, core developers work on the contents of + the operating system itself. + Following are some best practices for setting up machines + used for developing images: + <itemizedlist> + <listitem><para> + Have the + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink> + available on the developer workstations so developers + can run their own builds and directly rebuild the + software stack. + </para></listitem> + <listitem><para> + Keep the core system unchanged as much as + possible and do your work in layers on top of the + core system. + Doing so gives you a greater level of portability when + upgrading to new versions of the core system or Board + Support Packages (BSPs). + </para></listitem> + <listitem><para> + Share layers amongst the developers of a + particular project and contain the policy configuration + that defines the project. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Set up an Autobuilder:</emphasis> + Autobuilders are often the core of the development + environment. + It is here that changes from individual developers are brought + together and centrally tested. + Based on this automated build and test environment, subsequent + decisions about releases can be made. + Autobuilders also allow for "continuous integration" style + testing of software components and regression identification + and tracking.</para> + + <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>" + for more information and links to buildbot. + The Yocto Project team has found this implementation + works well in this role. + A public example of this is the Yocto Project + Autobuilders, which the Yocto Project team uses to test the + overall health of the project.</para> + + <para>The features of this system are: + <itemizedlist> + <listitem><para> + Highlights when commits break the build. + </para></listitem> + <listitem><para> + Populates an + <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate cache</ulink> + from which developers can pull rather than requiring + local builds. + </para></listitem> + <listitem><para> + Allows commit hook triggers, which trigger builds when + commits are made. + </para></listitem> + <listitem><para> + Allows triggering of automated image booting + and testing under the QuickEMUlator (QEMU). + </para></listitem> + <listitem><para> + Supports incremental build testing and + from-scratch builds. + </para></listitem> + <listitem><para> + Shares output that allows developer + testing and historical regression investigation. + </para></listitem> + <listitem><para> + Creates output that can be used for releases. + </para></listitem> + <listitem><para> + Allows scheduling of builds so that resources + can be used efficiently. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Set up Test Machines:</emphasis> + Use a small number of shared, high performance systems + for testing purposes. + Developers can use these systems for wider, more + extensive testing while they continue to develop + locally using their primary development system. + </para></listitem> + <listitem><para> + <emphasis>Document Policies and Change Flow:</emphasis> + The Yocto Project uses a hierarchical structure and a + pull model. + Scripts exist to create and send pull requests + (i.e. <filename>create-pull-request</filename> and + <filename>send-pull-request</filename>). + This model is in line with other open source projects where + maintainers are responsible for specific areas of the project + and a single maintainer handles the final "top-of-tree" merges. + <note> + You can also use a more collective push model. + The <filename>gitolite</filename> software supports both the + push and pull models quite easily. + </note></para> + + <para>As with any development environment, it is important + to document the policy used as well as any main project + guidelines so they are understood by everyone. + It is also a good idea to have well-structured + commit messages, which are usually a part of a project's + guidelines. + Good commit messages are essential when looking back in time and + trying to understand why changes were made.</para> + + <para>If you discover that changes are needed to the core + layer of the project, it is worth sharing those with the + community as soon as possible. + Chances are if you have discovered the need for changes, + someone else in the community needs them also. + </para></listitem> + <listitem><para> + <emphasis>Development Environment Summary:</emphasis> + Aside from the previous steps, some best practices exist + within the Yocto Project development environment. + Consider the following: + <itemizedlist> + <listitem><para> + Use + <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> + as the source control system. + </para></listitem> + <listitem><para> + Maintain your Metadata in layers that make sense + for your situation. + See the + "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>" + section in the Yocto Project Overview and Concepts + Manual and the + "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" + section for more information on layers. + </para></listitem> + <listitem><para> + Separate the project's Metadata and code by using + separate Git repositories. + See the + "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>" + section in the Yocto Project Overview and Concepts + Manual for information on these repositories. + See the + "<link linkend='locating-yocto-project-source-files'>Locating Yocto Project Source Files</link>" + section for information on how to set up local Git + repositories for related upstream Yocto Project + Git repositories. + </para></listitem> + <listitem><para> + Set up the directory for the shared state cache + (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>) + where it makes sense. + For example, set up the sstate cache on a system used + by developers in the same organization and share the + same source directories on their machines. + </para></listitem> + <listitem><para> + Set up an Autobuilder and have it populate the + sstate cache and source directories. + </para></listitem> + <listitem><para> + The Yocto Project community encourages you + to send patches to the project to fix bugs or add + features. + If you do submit patches, follow the project commit + guidelines for writing good commit messages. + See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>" + section. + </para></listitem> + <listitem><para> + Send changes to the core sooner than later + as others are likely to run into the same issues. + For some guidance on mailing lists to use, see the list + in the + "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>" + section. + For a description of the available mailing lists, see + the + "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" + section in the Yocto Project Reference Manual. + </para></listitem> + </itemizedlist> + </para></listitem> + </orderedlist> + </para> +</section> + +<section id='dev-preparing-the-build-host'> + <title>Preparing the Build Host</title> + + <para> + This section provides procedures to set up a system to be used as your + <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink> + for development using the Yocto Project. + Your build host can be a native Linux machine (recommended), it can + be a machine (Linux, Mac, or Windows) that uses + <ulink url='https://github.com/crops/poky-container'>CROPS</ulink>, + which leverages + <ulink url='https://www.docker.com/'>Docker Containers</ulink> or it can + be a Windows machine capable of running Windows Subsystem For Linux v2 (WSL). + <note> + The Yocto Project is not compatible with + <ulink url='https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux'>Windows Subsystem for Linux v1</ulink>. + It is compatible but not officially supported nor validated with WSLv2. + If you still decide to use WSL please upgrade to + <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-install'>WSLv2</ulink>. + </note> + </para> + + <para> + Once your build host is set up to use the Yocto Project, + further steps are necessary depending on what you want to + accomplish. + See the following references for information on how to prepare for + Board Support Package (BSP) development and kernel development: + <itemizedlist> + <listitem><para> + <emphasis>BSP Development:</emphasis> + See the + "<ulink url='&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work With BSP Layers</ulink>" + section in the Yocto Project Board Support Package (BSP) + Developer's Guide. + </para></listitem> + <listitem><para> + <emphasis>Kernel Development:</emphasis> + See the + "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</ulink>" + section in the Yocto Project Linux Kernel Development Manual. + </para></listitem> + </itemizedlist> + </para> + + <section id='setting-up-a-native-linux-host'> + <title>Setting Up a Native Linux Host</title> + + <para> + Follow these steps to prepare a native Linux machine as your + Yocto Project Build Host: + <orderedlist> + <listitem><para> + <emphasis>Use a Supported Linux Distribution:</emphasis> + You should have a reasonably current Linux-based host + system. + You will have the best results with a recent release of + Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS as these + releases are frequently tested against the Yocto Project + and officially supported. + For a list of the distributions under validation and their + status, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section + in the Yocto Project Reference Manual and the wiki page at + <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>. + </para></listitem> + <listitem><para> + <emphasis>Have Enough Free Memory:</emphasis> + Your system should have at least 50 Gbytes of free disk + space for building images. + </para></listitem> + <listitem><para> + <emphasis>Meet Minimal Version Requirements:</emphasis> + The OpenEmbedded build system should be able to run on any + modern distribution that has the following versions for + Git, tar, Python and gcc. + <itemizedlist> + <listitem><para> + Git 1.8.3.1 or greater + </para></listitem> + <listitem><para> + tar 1.28 or greater + </para></listitem> + <listitem><para> + Python 3.5.0 or greater. + </para></listitem> + <listitem><para> + gcc 5.0 or greater. + </para></listitem> + </itemizedlist> + If your build host does not meet any of these three listed + version requirements, you can take steps to prepare the + system so that you can still use the Yocto Project. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</ulink>" + section in the Yocto Project Reference Manual for + information. + </para></listitem> + <listitem><para> + <emphasis>Install Development Host Packages:</emphasis> + Required development host packages vary depending on your + build host and what you want to do with the Yocto + Project. + Collectively, the number of required packages is large + if you want to be able to cover all cases.</para> + + <para>For lists of required packages for all scenarios, + see the + "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host'>Required Packages for the Build Host</ulink>" + section in the Yocto Project Reference Manual. + </para></listitem> + </orderedlist> + Once you have completed the previous steps, you are ready to + continue using a given development path on your native Linux + machine. + If you are going to use BitBake, see the + "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>" + section. + If you are going to use the Extensible SDK, see the + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>" + Chapter in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + If you want to work on the kernel, see the + <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. + If you are going to use Toaster, see the + "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>" + section in the Toaster User Manual. + </para> + </section> + + <section id='setting-up-to-use-crops'> + <title>Setting Up to Use CROss PlatformS (CROPS)</title> + + <para> + With + <ulink url='https://github.com/crops/poky-container'>CROPS</ulink>, + which leverages + <ulink url='https://www.docker.com/'>Docker Containers</ulink>, + you can create a Yocto Project development environment that + is operating system agnostic. + You can set up a container in which you can develop using the + Yocto Project on a Windows, Mac, or Linux machine. + </para> + + <para> + Follow these general steps to prepare a Windows, Mac, or Linux + machine as your Yocto Project build host: + <orderedlist> + <listitem><para> + <emphasis>Determine What Your Build Host Needs:</emphasis> + <ulink url='https://www.docker.com/what-docker'>Docker</ulink> + is a software container platform that you need to install + on the build host. + Depending on your build host, you might have to install + different software to support Docker containers. + Go to the Docker installation page and read about the + platform requirements in + "<ulink url='https://docs.docker.com/install/#supported-platforms'>Supported Platforms</ulink>" + your build host needs to run containers. + </para></listitem> + <listitem><para> + <emphasis>Choose What To Install:</emphasis> + Depending on whether or not your build host meets system + requirements, you need to install "Docker CE Stable" or + the "Docker Toolbox". + Most situations call for Docker CE. + However, if you have a build host that does not meet + requirements (e.g. Pre-Windows 10 or Windows 10 "Home" + version), you must install Docker Toolbox instead. + </para></listitem> + <listitem><para> + <emphasis>Go to the Install Site for Your Platform:</emphasis> + Click the link for the Docker edition associated with + your build host's native software. + For example, if your build host is running Microsoft + Windows Version 10 and you want the Docker CE Stable + edition, click that link under "Supported Platforms". + </para></listitem> + <listitem><para> + <emphasis>Install the Software:</emphasis> + Once you have understood all the pre-requisites, you can + download and install the appropriate software. + Follow the instructions for your specific machine and + the type of the software you need to install: + <itemizedlist> + <listitem><para> + Install + <ulink url='https://docs.docker.com/docker-for-windows/install/#install-docker-for-windows-desktop-app'>Docker CE for Windows</ulink> + for Windows build hosts that meet requirements. + </para></listitem> + <listitem><para> + Install + <ulink url='https://docs.docker.com/docker-for-mac/install/#install-and-run-docker-for-mac'>Docker CE for Macs</ulink> + for Mac build hosts that meet requirements. + </para></listitem> + <listitem><para> + Install + <ulink url='https://docs.docker.com/toolbox/toolbox_install_windows/'>Docker Toolbox for Windows</ulink> + for Windows build hosts that do not meet Docker + requirements. + </para></listitem> + <listitem><para> + Install + <ulink url='https://docs.docker.com/toolbox/toolbox_install_mac/'>Docker Toolbox for MacOS</ulink> + for Mac build hosts that do not meet Docker + requirements. + </para></listitem> + <listitem><para> + Install + <ulink url='https://docs.docker.com/install/linux/docker-ce/centos/'>Docker CE for CentOS</ulink> + for Linux build hosts running the CentOS + distribution. + </para></listitem> + <listitem><para> + Install + <ulink url='https://docs.docker.com/install/linux/docker-ce/debian/'>Docker CE for Debian</ulink> + for Linux build hosts running the Debian + distribution. + </para></listitem> + <listitem><para> + Install + <ulink url='https://docs.docker.com/install/linux/docker-ce/fedora/'>Docker CE for Fedora</ulink> + for Linux build hosts running the Fedora + distribution. + </para></listitem> + <listitem><para> + Install + <ulink url='https://docs.docker.com/install/linux/docker-ce/ubuntu/'>Docker CE for Ubuntu</ulink> + for Linux build hosts running the Ubuntu + distribution. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Optionally Orient Yourself With Docker:</emphasis> + If you are unfamiliar with Docker and the container + concept, you can learn more here - + <ulink url='https://docs.docker.com/get-started/'></ulink>. + </para></listitem> + <listitem><para> + <emphasis>Launch Docker or Docker Toolbox:</emphasis> + You should be able to launch Docker or the Docker Toolbox + and have a terminal shell on your development host. + </para></listitem> + <listitem><para> + <emphasis>Set Up the Containers to Use the Yocto Project:</emphasis> + Go to + <ulink url='https://github.com/crops/docker-win-mac-docs/wiki'></ulink> + and follow the directions for your particular + build host (i.e. Linux, Mac, or Windows).</para> + + <para>Once you complete the setup instructions for your + machine, you have the Poky, Extensible SDK, and Toaster + containers available. + You can click those links from the page and learn more + about using each of those containers. + </para></listitem> + </orderedlist> + Once you have a container set up, everything is in place to + develop just as if you were running on a native Linux machine. + If you are going to use the Poky container, see the + "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>" + section. + If you are going to use the Extensible SDK container, see the + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>" + Chapter in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + If you are going to use the Toaster container, see the + "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>" + section in the Toaster User Manual. + </para> + </section> + + <section id='setting-up-to-use-wsl'> + <title>Setting Up to Use Windows Subsystem For Linux (WSLv2)</title> + + <para> + With <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-about'> + Windows Subsystem for Linux (WSLv2)</ulink>, you can create a + Yocto Project development environment that allows you to build + on Windows. You can set up a Linux distribution inside Windows + in which you can develop using the Yocto Project. + </para> + + <para> + Follow these general steps to prepare a Windows machine using WSLv2 + as your Yocto Project build host: + <orderedlist> + <listitem><para> + <emphasis>Make sure your Windows 10 machine is capable of running WSLv2:</emphasis> + + WSLv2 is only available for Windows 10 builds > 18917. To + check which build version you are running, you may open a + command prompt on Windows and execute the command "ver". + <literallayout class='monospaced'> + C:\Users\myuser> ver + + Microsoft Windows [Version 10.0.19041.153] + </literallayout> + If your build is capable of running WSLv2 you may continue, + for more information on this subject or instructions on how + to upgrade to WSLv2 visit <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-install'>Windows 10 WSLv2</ulink> + </para></listitem> + <listitem><para> + <emphasis>Install the Linux distribution of your choice inside Windows 10:</emphasis> + Once you know your version of Windows 10 supports WSLv2, + you can install the distribution of your choice from the + Microsoft Store. + Open the Microsoft Store and search for Linux. While there + are several Linux distributions available, the assumption + is that your pick will be one of the distributions supported + by the Yocto Project as stated on the instructions for + using a native Linux host. + After making your selection, simply click "Get" to download + and install the distribution. + </para></listitem> + <listitem><para> + <emphasis>Check your Linux distribution is using WSLv2:</emphasis> + Open a Windows PowerShell and run: + <literallayout class='monospaced'> + C:\WINDOWS\system32> wsl -l -v + NAME STATE VERSION + *Ubuntu Running 2 + </literallayout> + Note the version column which says the WSL version being used by + your distribution, on compatible systems, this can be changed back + at any point in time. + </para></listitem> + <listitem><para> + <emphasis>Optionally Orient Yourself on WSL:</emphasis> + If you are unfamiliar with WSL, you can learn more here - + <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-about'></ulink>. + </para></listitem> + <listitem><para> + <emphasis>Launch your WSL Distibution:</emphasis> + From the Windows start menu simply launch your WSL distribution + just like any other application. + </para></listitem> + <listitem><para> + <emphasis>Optimize your WSLv2 storage often:</emphasis> + Due to the way storage is handled on WSLv2, the storage + space used by the undelying Linux distribution is not + reflected immedately, and since bitbake heavily uses + storage, after several builds, you may be unaware you + are running out of space. WSLv2 uses a VHDX file for + storage, this issue can be easily avoided by manually + optimizing this file often, this can be done in the + following way: + <orderedlist> + <listitem><para> + <emphasis>Find the location of your VHDX file:</emphasis> + First you need to find the distro app package directory, + to achieve this open a Windows Powershell as Administrator + and run: + <literallayout class='monospaced'> + C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName + PackageFamilyName + ----------------- + CanonicalGroupLimited.UbuntuonWindows_79abcdefgh + </literallayout> + You should now replace the <replaceable>PackageFamilyName</replaceable> + and your <replaceable>user</replaceable> on the following + path to find your VHDX file: <filename>C:\Users\user\AppData\Local\Packages\PackageFamilyName\LocalState\</filename> + For example: + <literallayout class='monospaced'> + ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ + Mode LastWriteTime Length Name + -a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx + </literallayout> + Your VHDX file path is: <filename>C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx</filename> + </para></listitem> + <listitem><para><emphasis>Optimize your VHDX file:</emphasis> + Open a Windows Powershell as Administrator to optimize + your VHDX file, shutting down WSL first: + <literallayout class='monospaced'> + C:\WINDOWS\system32> wsl --shutdown + C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full + </literallayout> + A progress bar should be shown while optimizing the VHDX file, + and storage should now be reflected correctly on the Windows + Explorer. + </para></listitem> + </orderedlist> + </para></listitem> + </orderedlist> + <note> + The current implementation of WSLv2 does not have out-of-the-box + access to external devices such as those connected through a + USB port, but it automatically mounts your <filename>C:</filename> + drive on <filename>/mnt/c/</filename> (and others), which + you can use to share deploy artifacts to be later flashed on + hardware through Windows, but your build directory should not + reside inside this mountpoint. + </note> + Once you have WSLv2 set up, everything is in place to + develop just as if you were running on a native Linux machine. + If you are going to use the Extensible SDK container, see the + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>" + Chapter in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + If you are going to use the Toaster container, see the + "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>" + section in the Toaster User Manual. + </para> + </section> +</section> + +<section id='locating-yocto-project-source-files'> + <title>Locating Yocto Project Source Files</title> + + <para> + This section shows you how to locate, fetch and configure the source + files you'll need to work with the Yocto Project. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + For concepts and introductory information about Git as it + is used in the Yocto Project, see the + "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>" + section in the Yocto Project Overview and Concepts Manual. + </para></listitem> + <listitem><para> + For concepts on Yocto Project source repositories, see the + "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>" + section in the Yocto Project Overview and Concepts Manual." + </para></listitem> + </itemizedlist> + </note> + </para> + + <section id='accessing-source-repositories'> + <title>Accessing Source Repositories</title> + + <para> + Working from a copy of the upstream Yocto Project + <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink> + is the preferred method for obtaining and using a Yocto Project + release. + You can view the Yocto Project Source Repositories at + <ulink url='&YOCTO_GIT_URL;'></ulink>. + In particular, you can find the + <filename>poky</filename> repository at + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/'></ulink>. + </para> + + <para> + Use the following procedure to locate the latest upstream copy of + the <filename>poky</filename> Git repository: + <orderedlist> + <listitem><para> + <emphasis>Access Repositories:</emphasis> + Open a browser and go to + <ulink url='&YOCTO_GIT_URL;'></ulink> to access the + GUI-based interface into the Yocto Project source + repositories. + </para></listitem> + <listitem><para> + <emphasis>Select the Repository:</emphasis> + Click on the repository in which you are interested (e.g. + <filename>poky</filename>). + </para></listitem> + <listitem><para> + <emphasis>Find the URL Used to Clone the Repository:</emphasis> + At the bottom of the page, note the URL used to + <ulink url='&YOCTO_DOCS_OM_URL;#git-commands-clone'>clone</ulink> + that repository (e.g. + <filename>&YOCTO_GIT_URL;/poky</filename>). + <note> + For information on cloning a repository, see the + "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>" + section. + </note> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='accessing-index-of-releases'> + <title>Accessing Index of Releases</title> + + <para> + Yocto Project maintains an Index of Releases area that contains + related files that contribute to the Yocto Project. + Rather than Git repositories, these files are tarballs that + represent snapshots in time of a given component. + <note><title>Tip</title> + The recommended method for accessing Yocto Project + components is to use Git to clone the upstream repository and + work from within that locally cloned repository. + The procedure in this section exists should you desire a + tarball snapshot of any given component. + </note> + Follow these steps to locate and download a particular tarball: + <orderedlist> + <listitem><para> + <emphasis>Access the Index of Releases:</emphasis> + Open a browser and go to + <ulink url='&YOCTO_DL_URL;/releases'></ulink> to access the + Index of Releases. + The list represents released components (e.g. + <filename>bitbake</filename>, + <filename>sato</filename>, and so on). + <note> + The <filename>yocto</filename> directory contains the + full array of released Poky tarballs. + The <filename>poky</filename> directory in the + Index of Releases was historically used for very + early releases and exists now only for retroactive + completeness. + </note> + </para></listitem> + <listitem><para> + <emphasis>Select a Component:</emphasis> + Click on any released component in which you are interested + (e.g. <filename>yocto</filename>). + </para></listitem> + <listitem><para> + <emphasis>Find the Tarball:</emphasis> + Drill down to find the associated tarball. + For example, click on <filename>yocto-&DISTRO;</filename> to + view files associated with the Yocto Project &DISTRO; + release (e.g. <filename>poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;.tar.bz2</filename>, + which is the released Poky tarball). + </para></listitem> + <listitem><para> + <emphasis>Download the Tarball:</emphasis> + Click the tarball to download and save a snapshot of the + given component. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='using-the-downloads-page'> + <title>Using the Downloads Page</title> + + <para> + The + <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> + uses a "DOWNLOADS" page from which you can locate and download + tarballs of any Yocto Project release. + Rather than Git repositories, these files represent snapshot + tarballs similar to the tarballs located in the Index of Releases + described in the + "<link linkend='accessing-index-of-releases'>Accessing Index of Releases</link>" + section. + <note><title>Tip</title> + The recommended method for accessing Yocto Project + components is to use Git to clone a repository and work from + within that local repository. + The procedure in this section exists should you desire a + tarball snapshot of any given component. + </note> + <orderedlist> + <listitem><para> + <emphasis>Go to the Yocto Project Website:</emphasis> + Open The + <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> + in your browser. + </para></listitem> + <listitem><para> + <emphasis>Get to the Downloads Area:</emphasis> + Select the "DOWNLOADS" item from the pull-down + "SOFTWARE" tab menu near the top of the page. + </para></listitem> + <listitem><para> + <emphasis>Select a Yocto Project Release:</emphasis> + Use the menu next to "RELEASE" to display and choose + a recent or past supported Yocto Project release + (e.g. &DISTRO_NAME_NO_CAP;, + &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth). + <note><title>Tip</title> + For a "map" of Yocto Project releases to version + numbers, see the + <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Releases</ulink> + wiki page. + </note> + You can use the "RELEASE ARCHIVE" link to reveal a menu of + all Yocto Project releases. + </para></listitem> + <listitem><para> + <emphasis>Download Tools or Board Support Packages (BSPs):</emphasis> + From the "DOWNLOADS" page, you can download tools or + BSPs as well. + Just scroll down the page and look for what you need. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='accessing-nightly-builds'> + <title>Accessing Nightly Builds</title> + + <para> + Yocto Project maintains an area for nightly builds that contains + tarball releases at <ulink url='&YOCTO_AB_NIGHTLY_URL;'/>. + These builds include Yocto Project releases ("poky"), + toolchains, and builds for supported machines. + </para> + + <para> + Should you ever want to access a nightly build of a particular + Yocto Project component, use the following procedure: + <orderedlist> + <listitem><para> + <emphasis>Locate the Index of Nightly Builds:</emphasis> + Open a browser and go to + <ulink url='&YOCTO_AB_NIGHTLY_URL;'/> to access the + Nightly Builds. + </para></listitem> + <listitem><para> + <emphasis>Select a Date:</emphasis> + Click on the date in which you are interested. + If you want the latest builds, use "CURRENT". + </para></listitem> + <listitem><para> + <emphasis>Select a Build:</emphasis> + Choose the area in which you are interested. + For example, if you are looking for the most recent + toolchains, select the "toolchain" link. + </para></listitem> + <listitem><para> + <emphasis>Find the Tarball:</emphasis> + Drill down to find the associated tarball. + </para></listitem> + <listitem><para> + <emphasis>Download the Tarball:</emphasis> + Click the tarball to download and save a snapshot of the + given component. + </para></listitem> + </orderedlist> + </para> + </section> +</section> + +<section id='cloning-and-checking-out-branches'> + <title>Cloning and Checking Out Branches</title> + + <para> + To use the Yocto Project for development, you need a release locally + installed on your development system. + This locally installed set of files is referred to as the + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + in the Yocto Project documentation. + </para> + + <para> + The preferred method of creating your Source Directory is by using + <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> to clone a local + copy of the upstream <filename>poky</filename> repository. + Working from a cloned copy of the upstream repository allows you + to contribute back into the Yocto Project or to simply work with + the latest software on a development branch. + Because Git maintains and creates an upstream repository with + a complete history of changes and you are working with a local + clone of that repository, you have access to all the Yocto + Project development branches and tag names used in the upstream + repository. + </para> + + <section id='cloning-the-poky-repository'> + <title>Cloning the <filename>poky</filename> Repository</title> + + <para> + Follow these steps to create a local version of the + upstream + <ulink url='&YOCTO_DOCS_REF_URL;#poky'><filename>poky</filename></ulink> + Git repository. + <orderedlist> + <listitem><para> + <emphasis>Set Your Directory:</emphasis> + Change your working directory to where you want to + create your local copy of + <filename>poky</filename>. + </para></listitem> + <listitem><para> + <emphasis>Clone the Repository:</emphasis> + The following example command clones the + <filename>poky</filename> repository and uses + the default name "poky" for your local repository: + <literallayout class='monospaced'> + $ git clone git://git.yoctoproject.org/poky + Cloning into 'poky'... + remote: Counting objects: 432160, done. + remote: Compressing objects: 100% (102056/102056), done. + remote: Total 432160 (delta 323116), reused 432037 (delta 323000) + Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done. + Resolving deltas: 100% (323116/323116), done. + Checking connectivity... done. + </literallayout> + Unless you specify a specific development branch or + tag name, Git clones the "master" branch, which results + in a snapshot of the latest development changes for + "master". + For information on how to check out a specific + development branch or on how to check out a local + branch based on a tag name, see the + "<link linkend='checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</link>" + and + <link linkend='checkout-out-by-tag-in-poky'>Checking Out By Tag in Poky</link>" + sections, respectively.</para> + + <para>Once the local repository is created, you can + change to that directory and check its status. + Here, the single "master" branch exists on your system + and by default, it is checked out: + <literallayout class='monospaced'> + $ cd ~/poky + $ git status + On branch master + Your branch is up-to-date with 'origin/master'. + nothing to commit, working directory clean + $ git branch + * master + </literallayout> + Your local repository of poky is identical to the + upstream poky repository at the time from which it was + cloned. + As you work with the local branch, you can periodically + use the <filename>git pull ‐‐rebase</filename> + command to be sure you are up-to-date with the upstream + branch. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='checking-out-by-branch-in-poky'> + <title>Checking Out by Branch in Poky</title> + + <para> + When you clone the upstream poky repository, you have access to + all its development branches. + Each development branch in a repository is unique as it forks + off the "master" branch. + To see and use the files of a particular development branch + locally, you need to know the branch name and then specifically + check out that development branch. + <note> + Checking out an active development branch by branch name + gives you a snapshot of that particular branch at the time + you check it out. + Further development on top of the branch that occurs after + check it out can occur. + </note> + <orderedlist> + <listitem><para> + <emphasis>Switch to the Poky Directory:</emphasis> + If you have a local poky Git repository, switch to that + directory. + If you do not have the local copy of poky, see the + "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>" + section. + </para></listitem> + <listitem><para> + <emphasis>Determine Existing Branch Names:</emphasis> + <literallayout class='monospaced'> + $ git branch -a + * master + remotes/origin/1.1_M1 + remotes/origin/1.1_M2 + remotes/origin/1.1_M3 + remotes/origin/1.1_M4 + remotes/origin/1.2_M1 + remotes/origin/1.2_M2 + remotes/origin/1.2_M3 + . + . + . + remotes/origin/thud + remotes/origin/thud-next + remotes/origin/warrior + remotes/origin/warrior-next + remotes/origin/zeus + remotes/origin/zeus-next + ... and so on ... + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Check out the Branch:</emphasis> + Check out the development branch in which you want to work. + For example, to access the files for the Yocto Project + &DISTRO; Release (&DISTRO_NAME;), use the following command: + <literallayout class='monospaced'> + $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; + Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin. + Switched to a new branch '&DISTRO_NAME_NO_CAP;' + </literallayout> + The previous command checks out the "&DISTRO_NAME_NO_CAP;" + development branch and reports that the branch is tracking + the upstream "origin/&DISTRO_NAME_NO_CAP;" branch.</para> + + <para>The following command displays the branches + that are now part of your local poky repository. + The asterisk character indicates the branch that is + currently checked out for work: + <literallayout class='monospaced'> + $ git branch + master + * &DISTRO_NAME_NO_CAP; + </literallayout> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='checkout-out-by-tag-in-poky'> + <title>Checking Out by Tag in Poky</title> + + <para> + Similar to branches, the upstream repository uses tags + to mark specific commits associated with significant points in + a development branch (i.e. a release point or stage of a + release). + You might want to set up a local branch based on one of those + points in the repository. + The process is similar to checking out by branch name except you + use tag names. + <note> + Checking out a branch based on a tag gives you a + stable set of files not affected by development on the + branch above the tag. + </note> + <orderedlist> + <listitem><para> + <emphasis>Switch to the Poky Directory:</emphasis> + If you have a local poky Git repository, switch to that + directory. + If you do not have the local copy of poky, see the + "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>" + section. + </para></listitem> + <listitem><para> + <emphasis>Fetch the Tag Names:</emphasis> + To checkout the branch based on a tag name, you need to + fetch the upstream tags into your local repository: + <literallayout class='monospaced'> + $ git fetch --tags + $ + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>List the Tag Names:</emphasis> + You can list the tag names now: + <literallayout class='monospaced'> + $ git tag + 1.1_M1.final + 1.1_M1.rc1 + 1.1_M1.rc2 + 1.1_M2.final + 1.1_M2.rc1 + . + . + . + yocto-2.5 + yocto-2.5.1 + yocto-2.5.2 + yocto-2.5.3 + yocto-2.6 + yocto-2.6.1 + yocto-2.6.2 + yocto-2.7 + yocto_1.5_M5.rc8 + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Check out the Branch:</emphasis> + <literallayout class='monospaced'> + $ git checkout tags/&DISTRO_REL_TAG; -b my_yocto_&DISTRO; + Switched to a new branch 'my_yocto_&DISTRO;' + $ git branch + master + * my_yocto_&DISTRO; + </literallayout> + The previous command creates and checks out a local + branch named "my_yocto_&DISTRO;", which is based on + the commit in the upstream poky repository that has + the same tag. + In this example, the files you have available locally + as a result of the <filename>checkout</filename> + command are a snapshot of the + "&DISTRO_NAME_NO_CAP;" development branch at the point + where Yocto Project &DISTRO; was released. + </para></listitem> + </orderedlist> + </para> + </section> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> |