diff options
Diffstat (limited to 'poky/documentation/dev-manual/dev-manual-start.xml')
| -rw-r--r-- | poky/documentation/dev-manual/dev-manual-start.xml | 1086 |
1 files changed, 1086 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 0000000000..d8726b4857 --- /dev/null +++ b/poky/documentation/dev-manual/dev-manual-start.xml @@ -0,0 +1,1086 @@ +<!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; ] > + +<chapter id='dev-manual-start'> + +<title>Setting Up to Use the Yocto Project</title> + +<para> + This chapter provides procedures related to getting set up to use the + Yocto Project. + You can learn about creating a team environment that develops using the + Yocto Project, how to set up a build host, 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 scale it for a large + team of developers. + One of the strengths of the Yocto Project is that it is extremely + flexible. + Thus, you can adapt it to many different use cases and scenarios. + However, these characteristics can cause a struggle if you are trying + to create a working setup that scales across a large team. + </para> + + <para> + To help you understand how to set up this type of environment, + this section presents a procedure that gives you the information + to learn how to 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 work well. + Keep in mind, the procedure here is a starting point. + You can build off it and customize it to fit any + particular working environment and set of practices. + <orderedlist> + <listitem><para> + <emphasis>Determine Who is Going to be Developing:</emphasis> + You need to understand who is going to be doing anything + related to the Yocto Project and what their roles would be. + Making this determination is essential to completing the + steps two and three, 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 Development:</emphasis> + These types of developers do application level work + on top of an existing software stack. + </para></listitem> + <listitem><para> + <emphasis>Core System Development:</emphasis> + These types of developers work 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. + Not all environments need a Build Engineer. + </para></listitem> + <listitem><para> + <emphasis>Test Engineer:</emphasis> + This type of developer creates and manages automated + tests needed 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. + Any development, build, or test engineer should be using + a system that is running a supported Linux distribution. + 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. + </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> + and any software you are developing under the + control of an SCM system that is compatible + with the OpenEmbedded build system is advisable. + Of the SCMs BitBake supports, 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 backup, + 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 these 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 + that do 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> + When possible, use the Yocto Project + plug-in for the + <trademark class='trade'>Eclipse</trademark> IDE + and SDK development practices. + For more information, see the + "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>" + manual. + </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 are a + question for 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, these types of 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 Yocto Project build system itself 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 and 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 we use 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 sstate cache 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 itself 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 "<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 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='setting-up-the-development-host-to-use-the-yocto-project'> + <title>Preparing the Build Host</title> + + <para> + This section provides procedures to set up your development host to + use the Yocto Project. + You can use the Yocto Project on a native Linux development host or + you can use + <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>, + which leverages + <ulink url='https://www.docker.com/'>Docker Containers</ulink>, + to prepare any Linux, Mac, or Windows development host. + </para> + + <para> + Once your development 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, kernel development, and + development using the <trademark class='trade'>Eclipse</trademark> IDE: + <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> + <listitem><para> + <emphasis>Eclipse Development:</emphasis> + See the + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-eclipse-project'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></ulink>" + Chapter in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) 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 development 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, 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> + You 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, and Python. + <itemizedlist> + <listitem><para> + Git 1.8.3.1 or greater + </para></listitem> + <listitem><para> + tar 1.27 or greater + </para></listitem> + <listitem><para> + Python 3.4.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-and-python-versions'>Required Git, tar, and Python 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 machine 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-host-development-system'>Required Packages for the Host Development System</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://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>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 development host: + <orderedlist> + <listitem><para> + <emphasis>Go to the Docker Installation Site:</emphasis> + <ulink url='https://www.docker.com/what-docker'>Docker</ulink> + is a software container platform that you need to install + on the host development machine. + To start the installation process, see the + <ulink url='https://docs.docker.com/engine/installation/'>Docker Installation</ulink> + site. + </para></listitem> + <listitem><para> + <emphasis>Choose Your Docker Edition:</emphasis> + Docker comes in several editions. + For the Yocto Project, the stable community edition + (i.e. "Docker CE Stable") is adequate. + You can learn more about the Docker editions from the + site. + </para></listitem> + <listitem><para> + <emphasis>Go to the Install Site for Your Platform:</emphasis> + Click the link for the Docker edition associated with + your development host machine's native software. + For example, if your machine 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>Understand What You Need:</emphasis> + The install page has pre-requisites your machine must + meet. + Be sure you read through this page and make sure your + machine meets the requirements to run Docker. + If your machine does not meet the requirements, the page + has instructions to handle exceptions. + For example, to run Docker on Windows 10, you must have + the pro version of the operating system. + If you have the home version, you need to install the + <ulink url='https://docs.docker.com/toolbox/overview/#ready-to-get-started'>Docker Toolbox</ulink>. + </para> + + <para>Another example is that a Windows machine needs to + have Microsoft Hyper-V. + If you have a legacy version of the the Microsoft + operating system or for any other reason you do not have + Microsoft Hyper-V, you would have to enter the BIOS and + enable virtualization. + </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. + </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>. + 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 + development 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> + +<section id='locating-yocto-project-source-files'> + <title>Locating Yocto Project Source Files</title> + + <para> + This section contains procedures related to locating Yocto Project + files. + You establish and use these local files to work on projects. + <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 (i.e. + <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> + <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>eclipse-plugin</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. + <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. + </para></listitem> + <listitem><para> + <emphasis>Select a Yocto Project Release:</emphasis> + Use the menu next to "RELEASE" to display and choose + a Yocto Project release (e.g. sumo, rocko, pyro, and + so forth. + For a "map" of Yocto Project releases to version numbers, + see the + <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Releases</ulink> + wiki page. + </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, SDK installation + scripts, and experimental builds. + </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>Access the 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 Build:</emphasis> + Click on any build by date in which you are interested. + </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-branchs'> + <title>Cloning and Checking Out Branches</title> + + <para> + To use the Yocto Project, you need a release of the Yocto Project + locally installed on your development system. + The 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> + You create your Source Directory by using + <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> to clone a local + copy of the upstream <filename>poky</filename> repository. + <note><title>Tip</title> + The preferred method of getting the Yocto Project Source + Directory set up is to clone the repository. + </note> + Working from a copy of the upstream repository allows you + to contribute back into the Yocto Project or 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> + Be in the directory where you want to create your local + copy of poky. + </para></listitem> + <listitem><para> + <emphasis>Clone the Repository:</emphasis> + The following command clones the 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: 367178, done. + remote: Compressing objects: 100% (88161/88161), done. + remote: Total 367178 (delta 272761), reused 366942 (delta 272525) + Receiving objects: 100% (367178/367178), 133.26 MiB | 6.40 MiB/s, done. + Resolving deltas: 100% (272761/272761), 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 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. + </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/master-next + remotes/origin/master-next2 + remotes/origin/morty + remotes/origin/pinky + remotes/origin/purple + remotes/origin/pyro + remotes/origin/rocko + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Checkout the Branch:</emphasis> + Checkout 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.2 + yocto-2.2.1 + yocto-2.3 + yocto-2.3.1 + yocto-2.4 + yocto_1.5_M5.rc8 + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Checkout 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 +--> |