diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml')
| -rw-r--r-- | import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml | 1167 |
1 files changed, 694 insertions, 473 deletions
diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml index b8527f670a..195b22d0b1 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml @@ -7,523 +7,744 @@ <title>Getting Started with the Yocto Project</title> <para> - This chapter introduces the Yocto Project and gives you an idea of what you need to get started. - You can find enough information to set up your development host and build or use images for - hardware supported by the Yocto Project by reading the + This chapter provides procedures related to getting set up to use the + Yocto Project. + For a more front-to-end process that takes you from minimally preparing + a build host through building an image, see the <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. </para> -<para> - The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides - some higher-level concepts you might want to consider. -</para> - -<section id='introducing-the-yocto-project'> - <title>Introducing the Yocto Project</title> +<section id='setting-up-the-development-host-to-use-the-yocto-project'> + <title>Setting Up the Development Host to Use the Yocto Project</title> <para> - The Yocto Project is an open-source collaboration project focused on embedded Linux development. - The project currently provides a build system that is - referred to as the - <link linkend='build-system-term'>OpenEmbedded build system</link> - in the Yocto Project documentation. - The Yocto Project provides various ancillary tools for the embedded developer - and also features the Sato reference User Interface, which is optimized for - stylus-driven, low-resolution screens. + 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> - You can use the OpenEmbedded build system, which uses - <link linkend='bitbake-term'>BitBake</link>, to develop complete Linux - images and associated user-space applications for architectures based - on ARM, MIPS, PowerPC, x86 and x86-64. - <note> - By default, using the Yocto Project creates a Poky distribution. - However, you can create your own distribution by providing key - <link linkend='metadata'>Metadata</link>. - See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>" - section for more information. - </note> - While the Yocto Project does not provide a strict testing framework, - it does provide or generate for you artifacts that let you perform target-level and - emulated testing and debugging. - Additionally, if you are an <trademark class='trade'>Eclipse</trademark> - IDE user, you can install an Eclipse Yocto Plug-in to allow you to - develop within that familiar environment. + 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 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 Dockers:</emphasis> + If you are unfamiliar with Dockers 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='getting-setup'> - <title>Getting Set Up</title> +<section id='working-with-yocto-project-source-files'> + <title>Working With Yocto Project Source Files</title> <para> - Here is what you need to use the Yocto Project: - <itemizedlist> - <listitem><para><emphasis>Host System:</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> - <para> - You should also have about 50 Gbytes of free disk space for building images. - </para></listitem> - <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system - requires that certain packages exist on your development system (e.g. Python 2.7). - See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" - section in the Yocto Project Quick Start and 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 for the exact - package requirements and the installation commands to install - them for the supported distributions. - </para></listitem> - <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis> - You need a release of the Yocto Project locally installed on - your development system. - The documentation refers to this set of locally installed files - as the <link linkend='source-directory'>Source Directory</link>. - You create your Source Directory by using - <link linkend='git'>Git</link> to clone a local copy - of the upstream <filename>poky</filename> repository, - or by downloading and unpacking a tarball of an official - Yocto Project release. - The preferred method is to create a clone of the repository. - </para> - <para>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> - <note>You can view the Yocto Project Source Repositories at - <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> - </note> - <para>The following transcript shows how to clone the - <filename>poky</filename> Git repository into the current - working directory. - The command creates the local repository in a directory - named <filename>poky</filename>. - For information on Git used within the Yocto Project, see - the "<link linkend='git'>Git</link>" section. - <literallayout class='monospaced'> + This section contains procedures related to locating and securing + 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_REF_URL;#git'>Git</ulink>" + section in the Yocto Project Reference Manual. + </para></listitem> + <listitem><para> + For concepts on Yocto Project source repositories, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>" + section in the Yocto Project Reference Manual." + </para></listitem> + </itemizedlist> + </note> + </para> + + <section id='accessing-source-repositories'> + <title>Accessing Source Repositories</title> + + <para> + Yocto Project maintains upstream Git + <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink> + that you can examine and access using a browser-based UI: + <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 a Repository:</emphasis> + Click on any 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_REF_URL;#git-commands-clone'>clone</ulink> + that repository (e.g. + <filename>&YOCTO_GIT_URL;/poky</filename>). + </para></listitem> + <listitem><para> + <emphasis>Examine Change History of the Repository:</emphasis> + At the top of the page, click on any branch in which you + might be interested (e.g. + <filename>&DISTRO_NAME_NO_CAP;</filename>). + You can then view the commit log or tree view for that + development branch. + </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 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>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 for retroactive + completeness only. + </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 a tarball to download and save a snapshot of a + 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" area 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> + Click the "Downloads" tab. + </para></listitem> + <listitem><para> + <emphasis>Select the Type of Files:</emphasis> + Click the type of files you want (i.e "Build System", + "Tools", or "Board Support Packages (BSPs)". + </para></listitem> + <listitem><para> + <emphasis>Locate and Download the Tarball:</emphasis> + From the list of releases, locate the appropriate + download link and download the files. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='cloning-the-poky-repository'> + <title>Cloning the <filename>poky</filename> Repository</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_REF_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> + + <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: 226790, done. - remote: Compressing objects: 100% (57465/57465), done. - remote: Total 226790 (delta 165212), reused 225887 (delta 164327) - Receiving objects: 100% (226790/226790), 100.98 MiB | 263 KiB/s, done. - Resolving deltas: 100% (165212/165212), done. - </literallayout></para> - <para>For another example of how to set up your own local Git - repositories, see this - <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'> - wiki page</ulink>, which describes how to create local - Git repositories for both - <filename>poky</filename> and <filename>meta-intel</filename>. - </para> - <para> - You can also get the Yocto Project Files by downloading - Yocto Project releases from the - <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>. - From the website, you just click "Downloads" in the navigation - pane to the left to display all Yocto Project downloads. - Current and archived releases are available for download. - Nightly and developmental builds are also maintained at - <ulink url="&YOCTO_AB_NIGHTLY_URL;"></ulink>. - One final site you can visit for information on Yocto Project - releases is the - <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink> - wiki. - </para></listitem> - <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis> - If you are going to be making modifications to a supported Yocto Project kernel, you - need to establish local copies of the source. - You can find Git repositories of supported Yocto Project kernels organized under - "Yocto Linux Kernel" in the Yocto Project Source Repositories at - <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> - <para>This setup can involve creating a bare clone of the Yocto Project kernel and then - copying that cloned repository. - You can create the bare clone and the copy of the bare clone anywhere you like. - For simplicity, it is recommended that you create these structures outside of the - Source Directory, which is usually named <filename>poky</filename>.</para> - <para>As an example, the following transcript shows how to create the bare clone - of the <filename>linux-yocto-3.19</filename> kernel and then create a copy of - that clone. - <note>When you have a local Yocto Project kernel Git repository, you can - reference that repository rather than the upstream Git repository as - part of the <filename>clone</filename> command. - Doing so can speed up the process.</note></para> - <para>In the following example, the bare clone is named - <filename>linux-yocto-3.19.git</filename>, while the - copy is named <filename>my-linux-yocto-3.19-work</filename>: - <literallayout class='monospaced'> - $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.19 linux-yocto-3.19.git - Cloning into bare repository 'linux-yocto-3.19.git'... - remote: Counting objects: 3983256, done. - remote: Compressing objects: 100% (605006/605006), done. - remote: Total 3983256 (delta 3352832), reused 3974503 (delta 3344079) - Receiving objects: 100% (3983256/3983256), 843.66 MiB | 1.07 MiB/s, done. - Resolving deltas: 100% (3352832/3352832), done. + 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></para> - <para>Now create a clone of the bare clone just created: - <literallayout class='monospaced'> - $ git clone linux-yocto-3.19.git my-linux-yocto-3.19-work - Cloning into 'my-linux-yocto-3.19-work'... - done. - Checking out files: 100% (48440/48440), done. - </literallayout></para></listitem> - <listitem id='meta-yocto-kernel-extras-repo'><para><emphasis> - The <filename>meta-yocto-kernel-extras</filename> Git Repository</emphasis>: - The <filename>meta-yocto-kernel-extras</filename> Git repository contains Metadata needed - only if you are modifying and building the kernel image. - In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>) - files that you - edit to point to your locally modified kernel source files and to build the kernel - image. - Pointing to these local files is much more efficient than requiring a download of the - kernel's source files from upstream each time you make changes to the kernel.</para> - <para>You can find the <filename>meta-yocto-kernel-extras</filename> Git Repository in the - "Yocto Metadata Layers" area of the Yocto Project Source Repositories at - <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. - It is good practice to create this Git repository inside the Source Directory.</para> - <para>Following is an example that creates the <filename>meta-yocto-kernel-extras</filename> Git - repository inside the Source Directory, which is named <filename>poky</filename> - in this case: - <literallayout class='monospaced'> - $ cd ~/poky - $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras - Cloning into 'meta-yocto-kernel-extras'... - remote: Counting objects: 727, done. - remote: Compressing objects: 100% (452/452), done. - remote: Total 727 (delta 260), reused 719 (delta 252) - Receiving objects: 100% (727/727), 536.36 KiB | 240 KiB/s, done. - Resolving deltas: 100% (260/260), done. - </literallayout></para></listitem> - <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board Support Packages (BSPs):</emphasis> - The Yocto Project supports many BSPs, which are maintained in - their own layers or in layers designed to contain several - BSPs. - To get an idea of machine support through BSP layers, you can - look at the - <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink> - for the release.</para> - - <para>The Yocto Project uses the following BSP layer naming - scheme: - <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable> - </literallayout> - where <replaceable>bsp_name</replaceable> is the recognized - BSP name. - Here is an example: - <literallayout class='monospaced'> - meta-raspberrypi - </literallayout> - See the - "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" - section in the Yocto Project Board Support Package (BSP) - Developer's Guide for more information on BSP Layers.</para> - - <para>A useful Git repository released with the Yocto - Project is <filename>meta-intel</filename>, which is a - parent layer that contains many supported - <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>. - You can locate the <filename>meta-intel</filename> Git - repository in the "Yocto Metadata Layers" area of the Yocto - Project Source Repositories at - <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> - - <para>Using - <link linkend='git'>Git</link> to create a local clone of the - upstream repository can be helpful if you are working with - BSPs. - Typically, you set up the <filename>meta-intel</filename> - Git repository inside the Source Directory. - For example, the following transcript shows the steps to clone - <filename>meta-intel</filename>. - <note> - Be sure to work in the <filename>meta-intel</filename> - branch that matches your - <link linkend='source-directory'>Source Directory</link> - (i.e. <filename>poky</filename>) branch. - For example, if you have checked out the "master" branch - of <filename>poky</filename> and you are going to use - <filename>meta-intel</filename>, be sure to checkout the - "master" branch of <filename>meta-intel</filename>. - </note> - <literallayout class='monospaced'> + </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>", + 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 clone git://git.yoctoproject.org/meta-intel.git - Cloning into 'meta-intel'... - remote: Counting objects: 11917, done. - remote: Compressing objects: 100% (3842/3842), done. - remote: Total 11917 (delta 6840), reused 11699 (delta 6622) - Receiving objects: 100% (11917/11917), 2.92 MiB | 2.88 MiB/s, done. - Resolving deltas: 100% (6840/6840), done. - Checking connectivity... done. - </literallayout></para> + $ 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> - <para>The same - <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>wiki page</ulink> - referenced earlier covers how to set up the - <filename>meta-intel</filename> Git repository. - </para></listitem> - <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing - applications using the Eclipse Integrated Development Environment (IDE), - you will need this plug-in. - See the - "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-appendix-latest-yp-eclipse-plug-in'>Using Eclipse</ulink>" - section in the Yocto Project Software Development Kit (SDK) - Developer's Guide for more information.</para></listitem> - </itemizedlist> - </para> + <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; -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> -<section id='building-images'> - <title>Building Images</title> +<section id='performing-a-simple-build'> + <title>Performing a Simple Build</title> + + <para> + Several methods exist that allow you to build an image within the + Yocto Project. + This procedure shows how to build an image using BitBake from a + Linux host. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + For information on how to build an image using + <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>, + see the + <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>. + </para></listitem> + <listitem><para> + For information on how to use + <filename>devtool</filename> to build images, see the + "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow</ulink>" + section in the Yocto Project Application Development and + the Extensible Software Development Kit (eSDK) manual. + </para></listitem> + </itemizedlist> + </note> + </para> <para> - The build process creates an entire Linux distribution, including the toolchain, from source. - For more information on this topic, see the + The build process creates an entire Linux distribution from source + and places it in your + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink> + under <filename>tmp/deploy/images</filename>. + For detailed information on the build process using BitBake, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#images-dev-environment'>Images</ulink>" + section in the Yocto Project Reference Manual. + You can also reference the "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" section in the Yocto Project Quick Start. </para> <para> - The build process is as follows: + The following figure and list overviews the build process: + <imagedata fileref="figures/bitbake-build-flow.png" width="7in" depth="4in" align="center" scalefit="1" /> <orderedlist> - <listitem><para>Make sure you have set up the Source Directory described in the - previous section.</para></listitem> - <listitem><para>Initialize the build environment by sourcing a build + <listitem><para> + <emphasis>Set up Your Host Development System to Support + Development Using the Yocto Project</emphasis>: + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" + section in the Yocto Project Quick Start for options on how + to get a build host ready to use the Yocto Project. + </para></listitem> + <listitem><para> + <emphasis>Initialize the Build Environment:</emphasis> + Initialize the build environment by sourcing the build environment script (i.e. - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>). </para></listitem> - <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file, - which is found in the - <link linkend='build-directory'>Build Directory</link>, + <listitem><para> + <emphasis>Make Sure Your <filename>local.conf</filename> + File is Correct:</emphasis> + Ensure the <filename>conf/local.conf</filename> configuration + file, which is found in the + <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, is set up how you want it. - This file defines many aspects of the build environment including - the target machine architecture through the + This file defines many aspects of the build environment + including the target machine architecture through the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable, the packaging format used during the build (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>), and a centralized tarball download directory through the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem> - <listitem><para> - Build the image using the <filename>bitbake</filename> command. - If you want information on BitBake, see the - <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. - </para></listitem> - <listitem><para>Run the image either on the actual hardware or using the QEMU - emulator.</para></listitem> - </orderedlist> - </para> -</section> - -<section id='flashing-images-using-bmaptool'> - <title>Flashing Images Using <filename>bmaptool</filename></title> - - <para> - An easy way to flash an image to a bootable device is to use - <filename>bmaptool</filename>, which is integrated into the - OpenEmbedded build system. - </para> - - <para> - Following, is an example that shows how to flash a Wic image. - <note> - You can use <filename>bmaptool</filename> to flash any - type of image. - </note> - Use these steps to flash an image using - <filename>bmaptool</filename>: - <note> - Unless you are able to install the - <filename>bmap-tools</filename> package as mentioned in the note - in the second bullet of step 3 further down, you will need to build - <filename>bmaptool</filename> before using it. - Build the tool using the following command: - <literallayout class='monospaced'> - $ bitbake bmap-tools-native - </literallayout> - </note> - <orderedlist> - <listitem><para> - Add the following to your <filename>local.conf</filename> - file: - <literallayout class='monospaced'> - IMAGE_FSTYPES += "wic wic.bmap" - </literallayout> + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable. </para></listitem> <listitem><para> - Either have your image ready (pre-built) or take the step - build the image: + <emphasis>Build the Image:</emphasis> + Build the image using the <filename>bitbake</filename> command. + For example, the following command builds the + <filename>core-image-minimal</filename> image: <literallayout class='monospaced'> - $ bitbake <replaceable>image</replaceable> + $ bitbake core-image-minimal </literallayout> - </para></listitem> - <listitem><para> - Flash the image to the media by using - <filename>bmaptool</filename> depending on your particular - setup: - <itemizedlist> - <listitem><para> - If you have write access to the media, - use this command form: - <literallayout class='monospaced'> - $ oe-run-native bmaptool copy ./tmp/deploy/images/qemux86-64/core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable> - </literallayout> - </para></listitem> - <listitem><para> - If you do not have write access to - the media, use the following - commands: - <literallayout class='monospaced'> - $ sudo bash - $ PATH=tmp/sysroots/x86_64-linux/usr/bin/ bmaptool copy ./tmp/deploy/images/qemux86-64/core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable> - </literallayout> - <note> - If you are using Ubuntu or Debian distributions, - you can install the - <filename>bmap-tools</filename> package using the - following command and then use the tool - without specifying - <filename>PATH</filename> even from the - root account: - <literallayout class='monospaced'> - $ sudo apt-get install bmap-tools - </literallayout> - </note> - </para></listitem> - </itemizedlist> + For information on BitBake, see the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. </para></listitem> </orderedlist> </para> - - <para> - For help on the <filename>bmaptool</filename> command, use either of - the following commands: - <literallayout class='monospaced'> - $ bmaptool --help - $ oe-run-native bmaptool --help - </literallayout> - </para> </section> -<section id='using-pre-built-binaries-and-qemu'> - <title>Using Pre-Built Binaries and QEMU</title> - - <para> - Another option you have to get started is to use pre-built binaries. - The Yocto Project provides many types of binaries with each release. - See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" - chapter in the Yocto Project Reference Manual - for descriptions of the types of binaries that ship with a Yocto Project - release. - </para> - - <para> - Using a pre-built binary is ideal for developing software - applications to run on your target hardware. - To do this, you need to be able to access the appropriate - cross-toolchain tarball for the architecture on which you are - developing. - If you are using an SDK type image, the image ships with the complete - toolchain native to the architecture (i.e. a toolchain designed to - run on the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>). - If you are not using an SDK type image, you need to separately download - and install the stand-alone Yocto Project cross-toolchain tarball. - See the - "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-appendix-obtain'>Obtaining the SDK</ulink>" - appendix in the Yocto Project Software Development Kit (SDK) - Developer's Guide for more information on locating and installing - cross-toolchains. - </para> - - <para> - Regardless of the type of image you are using, you need to download the pre-built kernel - that you will boot in the QEMU emulator and then download and extract the target root - filesystem for your target machine’s architecture. - You can get architecture-specific binaries and file systems from - <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>. - You can get installation scripts for stand-alone toolchains from - <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>. - Once you have all your files, you set up the environment to emulate the hardware - by sourcing an environment setup script. - Finally, you start the QEMU emulator. - You can find details on all these steps in the - <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. - You can learn more about using QEMU with the Yocto Project in the - "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" - section. - </para> - - <para> - Using QEMU to emulate your hardware can result in speed issues - depending on the target and host architecture mix. - For example, using the <filename>qemux86</filename> image in the emulator - on an Intel-based 32-bit (x86) host machine is fast because the target and - host architectures match. - On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based - host can be slower. - But, you still achieve faithful emulation of ARM-specific issues. - </para> - - <para> - To speed things up, the QEMU images support using <filename>distcc</filename> - to call a cross-compiler outside the emulated system. - If you used <filename>runqemu</filename> to start QEMU, and the - <filename>distccd</filename> application is present on the host system, any - BitBake cross-compiling toolchain available from the build system is automatically - used from within QEMU simply by calling <filename>distcc</filename>. - You can accomplish this by defining the cross-compiler variable - (e.g. <filename>export CC="distcc"</filename>). - Alternatively, if you are using a suitable SDK image or the appropriate - stand-alone toolchain is present, - the toolchain is also automatically used. - </para> - - <note> - Several mechanisms exist that let you connect to the system running on the - QEMU emulator: - <itemizedlist> - <listitem><para>QEMU provides a framebuffer interface that makes standard - consoles available.</para></listitem> - <listitem><para>Generally, headless embedded devices have a serial port. - If so, you can configure the operating system of the running image - to use that port to run a console. - The connection uses standard IP networking.</para></listitem> - <listitem><para> - SSH servers exist in some QEMU images. - The <filename>core-image-sato</filename> QEMU image has a - Dropbear secure shell (SSH) server that runs with the root - password disabled. - The <filename>core-image-full-cmdline</filename> and - <filename>core-image-lsb</filename> QEMU images - have OpenSSH instead of Dropbear. - Including these SSH servers allow you to use standard - <filename>ssh</filename> and <filename>scp</filename> commands. - The <filename>core-image-minimal</filename> QEMU image, - however, contains no SSH server. - </para></listitem> - <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session - using a local copy of the root filesystem on the host. - In order to make this connection, you must extract a root filesystem tarball by using the - <filename>runqemu-extract-sdk</filename> command. - After running the command, you must then point the <filename>runqemu</filename> - script to the extracted directory instead of a root filesystem image file.</para></listitem> - </itemizedlist> - </note> -</section> +--> </chapter> <!-- vim: expandtab tw=80 ts=4 |