diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-start.xml')
| -rw-r--r-- | documentation/dev-manual/dev-manual-start.xml | 1147 |
1 files changed, 0 insertions, 1147 deletions
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml deleted file mode 100644 index 59ffa49bb6..0000000000 --- a/documentation/dev-manual/dev-manual-start.xml +++ /dev/null @@ -1,1147 +0,0 @@ -<!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. - You can adapt the Yocto Project to many different use cases and - scenarios. - However, this flexibility could cause difficulties if you are trying - to create a working setup that scales 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 determine their roles. - 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> - 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 and kernel development: - <itemizedlist> - <listitem><para> - <emphasis>BSP Development:</emphasis> - See the - "<ulink url='&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work With BSP Layers</ulink>" - section in the Yocto Project Board Support Package (BSP) - Developer's Guide. - </para></listitem> - <listitem><para> - <emphasis>Kernel Development:</emphasis> - See the - "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</ulink>" - section in the Yocto Project Linux Kernel Development Manual. - </para></listitem> - </itemizedlist> - </para> - - <section id='setting-up-a-native-linux-host'> - <title>Setting Up a Native Linux Host</title> - - <para> - Follow these steps to prepare a native Linux machine as your - Yocto Project Build Host: - <orderedlist> - <listitem><para> - <emphasis>Use a Supported Linux Distribution:</emphasis> - You should have a reasonably current Linux-based host - system. - You will have the best results with a recent release of - Fedora, openSUSE, Debian, Ubuntu, 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>bitbake</filename>, - <filename>sato</filename>, and so on). - <note> - The <filename>yocto</filename> directory contains the - full array of released Poky tarballs. - The <filename>poky</filename> directory in the - Index of Releases was historically used for very - early releases and exists now only for retroactive - completeness. - </note> - </para></listitem> - <listitem><para> - <emphasis>Select a Component:</emphasis> - Click on any released component in which you are interested - (e.g. <filename>yocto</filename>). - </para></listitem> - <listitem><para> - <emphasis>Find the Tarball:</emphasis> - Drill down to find the associated tarball. - For example, click on <filename>yocto-&DISTRO;</filename> to - view files associated with the Yocto Project &DISTRO; - release (e.g. <filename>poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;.tar.bz2</filename>, - which is the released Poky tarball). - </para></listitem> - <listitem><para> - <emphasis>Download the Tarball:</emphasis> - Click the tarball to download and save a snapshot of the - given component. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='using-the-downloads-page'> - <title>Using the Downloads Page</title> - - <para> - The - <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> - uses a "DOWNLOADS" page from which you can locate and download - tarballs of any Yocto Project release. - Rather than Git repositories, these files represent snapshot - tarballs similar to the tarballs located in the Index of Releases - described in the - "<link linkend='accessing-index-of-releases'>Accessing Index of Releases</link>" - section. - <note><title>Tip</title> - The recommended method for accessing Yocto Project - components is to use Git to clone a repository and work from - within that local repository. - The procedure in this section exists should you desire a - tarball snapshot of any given component. - </note> - <orderedlist> - <listitem><para> - <emphasis>Go to the Yocto Project Website:</emphasis> - Open The - <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> - in your browser. - </para></listitem> - <listitem><para> - <emphasis>Get to the Downloads Area:</emphasis> - Select the "DOWNLOADS" item from the pull-down - "SOFTWARE" tab menu near the top of the page. - </para></listitem> - <listitem><para> - <emphasis>Select a Yocto Project Release:</emphasis> - Use the menu next to "RELEASE" to display and choose - a recent or past supported Yocto Project release - (e.g. &DISTRO_NAME_NO_CAP;, - &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth). - <note><title>Tip</title> - For a "map" of Yocto Project releases to version - numbers, see the - <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Releases</ulink> - wiki page. - </note> - You can use the "RELEASE ARCHIVE" link to reveal a menu of - all Yocto Project releases. - </para></listitem> - <listitem><para> - <emphasis>Download Tools or Board Support Packages (BSPs):</emphasis> - From the "DOWNLOADS" page, you can download tools or - BSPs as well. - Just scroll down the page and look for what you need. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='accessing-nightly-builds'> - <title>Accessing Nightly Builds</title> - - <para> - Yocto Project maintains an area for nightly builds that contains - tarball releases at <ulink url='&YOCTO_AB_NIGHTLY_URL;'/>. - These builds include Yocto Project releases ("poky"), - toolchains, and builds for supported machines. - </para> - - <para> - Should you ever want to access a nightly build of a particular - Yocto Project component, use the following procedure: - <orderedlist> - <listitem><para> - <emphasis>Locate the Index of Nightly Builds:</emphasis> - Open a browser and go to - <ulink url='&YOCTO_AB_NIGHTLY_URL;'/> to access the - Nightly Builds. - </para></listitem> - <listitem><para> - <emphasis>Select a Date:</emphasis> - Click on the date in which you are interested. - If you want the latest builds, use "CURRENT". - </para></listitem> - <listitem><para> - <emphasis>Select a Build:</emphasis> - Choose the area in which you are interested. - For example, if you are looking for the most recent - toolchains, select the "toolchain" link. - </para></listitem> - <listitem><para> - <emphasis>Find the Tarball:</emphasis> - Drill down to find the associated tarball. - </para></listitem> - <listitem><para> - <emphasis>Download the Tarball:</emphasis> - Click the tarball to download and save a snapshot of the - given component. - </para></listitem> - </orderedlist> - </para> - </section> -</section> - -<section id='cloning-and-checking-out-branches'> - <title>Cloning and Checking Out Branches</title> - - <para> - To use the Yocto Project for development, you need a release locally - installed on your development system. - This locally installed set of files is referred to as the - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> - in the Yocto Project documentation. - </para> - - <para> - The preferred method of creating your Source Directory is by using - <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> to clone a local - copy of the upstream <filename>poky</filename> repository. - Working from a cloned copy of the upstream repository allows you - to contribute back into the Yocto Project or to simply work with - the latest software on a development branch. - Because Git maintains and creates an upstream repository with - a complete history of changes and you are working with a local - clone of that repository, you have access to all the Yocto - Project development branches and tag names used in the upstream - repository. - </para> - - <section id='cloning-the-poky-repository'> - <title>Cloning the <filename>poky</filename> Repository</title> - - <para> - Follow these steps to create a local version of the - upstream - <ulink url='&YOCTO_DOCS_REF_URL;#poky'><filename>poky</filename></ulink> - Git repository. - <orderedlist> - <listitem><para> - <emphasis>Set Your Directory:</emphasis> - Change your working directory to where you want to - create your local copy of - <filename>poky</filename>. - </para></listitem> - <listitem><para> - <emphasis>Clone the Repository:</emphasis> - The following example command clones the - <filename>poky</filename> repository and uses - the default name "poky" for your local repository: - <literallayout class='monospaced'> - $ git clone git://git.yoctoproject.org/poky - Cloning into 'poky'... - remote: Counting objects: 432160, done. - remote: Compressing objects: 100% (102056/102056), done. - remote: Total 432160 (delta 323116), reused 432037 (delta 323000) - Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done. - Resolving deltas: 100% (323116/323116), done. - Checking connectivity... done. - </literallayout> - Unless you specify a specific development branch or - tag name, Git clones the "master" branch, which results - in a snapshot of the latest development changes for - "master". - For information on how to check out a specific - development branch or on how to check out a local - branch based on a tag name, see the - "<link linkend='checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</link>" - and - <link linkend='checkout-out-by-tag-in-poky'>Checking Out By Tag in Poky</link>" - sections, respectively.</para> - - <para>Once the local repository is created, you can - change to that directory and check its status. - Here, the single "master" branch exists on your system - and by default, it is checked out: - <literallayout class='monospaced'> - $ cd ~/poky - $ git status - On branch master - Your branch is up-to-date with 'origin/master'. - nothing to commit, working directory clean - $ git branch - * master - </literallayout> - Your local repository of poky is identical to the - upstream poky repository at the time from which it was - cloned. - As you work with the local branch, you can periodically - use the <filename>git pull ‐‐rebase</filename> - command to be sure you are up-to-date with the upstream - branch. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='checking-out-by-branch-in-poky'> - <title>Checking Out by Branch in Poky</title> - - <para> - When you clone the upstream poky repository, you have access to - all its development branches. - Each development branch in a repository is unique as it forks - off the "master" branch. - To see and use the files of a particular development branch - locally, you need to know the branch name and then specifically - check out that development branch. - <note> - Checking out an active development branch by branch name - gives you a snapshot of that particular branch at the time - you check it out. - Further development on top of the branch that occurs after - check it out can occur. - </note> - <orderedlist> - <listitem><para> - <emphasis>Switch to the Poky Directory:</emphasis> - If you have a local poky Git repository, switch to that - directory. - If you do not have the local copy of poky, see the - "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>" - section. - </para></listitem> - <listitem><para> - <emphasis>Determine Existing Branch Names:</emphasis> - <literallayout class='monospaced'> - $ git branch -a - * master - remotes/origin/1.1_M1 - remotes/origin/1.1_M2 - remotes/origin/1.1_M3 - remotes/origin/1.1_M4 - remotes/origin/1.2_M1 - remotes/origin/1.2_M2 - remotes/origin/1.2_M3 - . - . - . - remotes/origin/pyro - remotes/origin/pyro-next - remotes/origin/rocko - remotes/origin/rocko-next - remotes/origin/sumo - remotes/origin/sumo-next - remotes/origin/thud - remotes/origin/thud-next - remotes/origin/warrior - </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.5 - yocto-2.5.1 - yocto-2.5.2 - yocto-2.5.3 - yocto-2.6 - yocto-2.6.1 - yocto-2.6.2 - yocto-2.7 - yocto_1.5_M5.rc8 - </literallayout> - </para></listitem> - <listitem><para> - <emphasis>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 ---> |