| <!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 |
| <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. |
| 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, this flexibility could cause difficulties 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 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. |
| Keep in mind, the procedure here is 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 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 |
| 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 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. |
| Not all environments 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. |
| </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 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 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> |
| 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 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) or it can |
| be a machine (Linux, Mac, or Windows) that uses |
| <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>, |
| which leverages |
| <ulink url='https://www.docker.com/'>Docker Containers</ulink>. |
| <note> |
| You cannot use a build host that is using the |
| <ulink url='https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux'>Windows Subsystem for Linux</ulink> |
| (WSL). |
| The Yocto Project is not compatible with WSL. |
| </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, 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 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, 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, 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 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/crops/blob/master/README.md'>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> |
| |
| <section id='locating-yocto-project-source-files'> |
| <title>Locating Yocto Project Source Files</title> |
| |
| <para> |
| This section shows you how to locate and access the |
| source files that ship with the Yocto Project. |
| 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 (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>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 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, Yocto Project plugins for Eclipse, 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: 416542, done. |
| remote: Compressing objects: 100% (98611/98611), done. |
| remote: Total 416542 (delta 311104), reused 416377 (delta 310939) |
| Receiving objects: 100% (416542/416542), 150.39 MiB | 15.77 MiB/s, done. |
| Resolving deltas: 100% (311104/311104), 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/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 |
| --> |