| <!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 |
| --> |