diff options
Diffstat (limited to 'documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml')
| -rw-r--r-- | documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml | 577 |
1 files changed, 0 insertions, 577 deletions
diff --git a/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml b/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml deleted file mode 100644 index 198c7b9689..0000000000 --- a/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml +++ /dev/null @@ -1,577 +0,0 @@ -<!DOCTYPE article 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; ] > -<!--SPDX-License-Identifier: CC-BY-2.0-UK--> - -<article id='brief-yocto-project-qs-intro'> - <articleinfo> - <title>Yocto Project Quick Build</title> - - <copyright> - <year>©RIGHT_YEAR;</year> - <holder>Linux Foundation</holder> - </copyright> - - <legalnotice> - <para> - Permission is granted to copy, distribute and/or modify this document under - the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. - </para> - </legalnotice> - - - <abstract> - <imagedata fileref="figures/yocto-project-transp.png" - width="6in" depth="1in" - align="right" scale="25" /> - </abstract> - </articleinfo> - - <section id='brief-welcome'> - <title>Welcome!</title> - - <para> - Welcome! - This short document steps you through the process for a typical - image build using the Yocto Project. - The document also introduces how to configure a build for specific - hardware. - You will use Yocto Project to build a reference embedded OS - called Poky. - <note><title>Notes</title> - <itemizedlist> - <listitem><para> - The examples in this paper assume you are using a - native Linux system running a recent Ubuntu Linux - distribution. - If the machine you want to use Yocto Project on to - build an image - (<ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>) - is not a native Linux system, you can - still perform these steps by using CROss PlatformS - (CROPS) and setting up a Poky container. - See the - <ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>" - section in the Yocto Project Development Tasks Manual for more - information. - </para></listitem> - <listitem><para> - You may use Windows Subsystem For Linux v2 to set up a build - host using Windows 10. - <note> - The Yocto Project is not compatible with WSLv1, it is - compatible but not officially supported nor validated - with WSLv2, if you still decide to use WSL please upgrade - to WSLv2. - </note> - See the - <ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-wsl'>Setting Up to Use Windows Subsystem For Linux</ulink>" - section in the Yocto Project Development Tasks Manual for more - information. - </para></listitem> - </itemizedlist> - </note> - </para> - - <para> - If you want more conceptual or background information on the - Yocto Project, see the - <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>. - </para> - </section> - - <section id='brief-compatible-distro'> - <title>Compatible Linux Distribution</title> - - <para> - Make sure your - <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink> - meets the following requirements: - <itemizedlist> - <listitem><para> - 50 Gbytes of free disk space - </para></listitem> - <listitem><para> - Runs a supported Linux distribution (i.e. recent releases of - Fedora, openSUSE, CentOS, Debian, or Ubuntu). For a list of - Linux distributions that support the Yocto Project, see the - "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" - section in the Yocto Project Reference Manual. - For detailed information on preparing your build host, see - the - "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>" - section in the Yocto Project Development Tasks Manual. - </para></listitem> - <listitem><para> - <itemizedlist> - <listitem><para> - Git 1.8.3.1 or greater - </para></listitem> - <listitem><para> - tar 1.28 or greater - </para></listitem> - <listitem><para> - Python 3.5.0 or greater. - </para></listitem> - <listitem><para> - gcc 5.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-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</ulink>" - section in the Yocto Project Reference Manual for information. - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='brief-build-system-packages'> - <title>Build Host Packages</title> - - <para> - You must install essential host packages on your - build host. - The following command installs the host packages based on an - Ubuntu distribution: - <note> - For host package requirements on all supported Linux - distributions, 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. - </note> - <literallayout class='monospaced'> - $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; - </literallayout> - </para> - </section> - - <section id='brief-use-git-to-clone-poky'> - <title>Use Git to Clone Poky</title> - - <para> - Once you complete the setup instructions for your machine, - you need to get a copy of the Poky repository on your build - host. - Use the following commands to clone the Poky - 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> - Move to the <filename>poky</filename> directory and take a look - at the tags: - <literallayout class='monospaced'> - $ cd poky - $ git fetch --tags - $ 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.6 - yocto-2.6.1 - yocto-2.6.2 - yocto-2.7 - yocto_1.5_M5.rc8 - </literallayout> - For this example, check out the branch based on the - &DISTRO_REL_TAG; release: - <literallayout class='monospaced'> - $ git checkout tags/&DISTRO_REL_TAG; -b my-&DISTRO_REL_TAG; - Switched to a new branch 'my-&DISTRO_REL_TAG;' - </literallayout> - The previous Git checkout command creates a local branch - named my-&DISTRO_REL_TAG;. The files available to you in that - branch exactly match the repository's files in the - "&DISTRO_NAME_NO_CAP;" development branch at the time of the - Yocto Project &DISTRO_REL_TAG; release. - </para> - - <para> - For more options and information about accessing Yocto - Project related repositories, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>" - section in the Yocto Project Development Tasks Manual. - </para> - </section> - - <section id='brief-building-your-image'> - <title>Building Your Image</title> - - <para> - Use the following steps to build your image. - The build process creates an entire Linux distribution, including - the toolchain, from source. - <note> - <itemizedlist> - <listitem><para> - If you are working behind a firewall and your build - host is not set up for proxies, you could encounter - problems with the build process when fetching source - code (e.g. fetcher failures or Git failures). - </para></listitem> - <listitem><para> - If you do not know your proxy settings, consult your - local network infrastructure resources and get that - information. - A good starting point could also be to check your - web browser settings. - Finally, you can find more information on the - "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>" - page of the Yocto Project Wiki. - </para></listitem> - </itemizedlist> - </note> - </para> - - <para> - <orderedlist> - <listitem><para> - <emphasis>Initialize the Build Environment:</emphasis> - From within the <filename>poky</filename> directory, run the - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - environment setup script to define Yocto Project's - build environment on your build host. - <literallayout class='monospaced'> - $ cd ~/poky - $ source &OE_INIT_FILE; - You had no conf/local.conf file. This configuration file has therefore been - created for you with some default values. You may wish to edit it to, for - example, select a different MACHINE (target hardware). See conf/local.conf - for more information as common configuration options are commented. - - You had no conf/bblayers.conf file. This configuration file has therefore been - created for you with some default values. To add additional metadata layers - into your configuration please add entries to conf/bblayers.conf. - - The Yocto Project has extensive documentation about OE including a reference - manual which can be found at: - http://yoctoproject.org/documentation - - For more information about OpenEmbedded see their website: - http://www.openembedded.org/ - - - ### Shell environment set up for builds. ### - - You can now run 'bitbake <target>' - - Common targets are: - core-image-minimal - core-image-sato - meta-toolchain - meta-ide-support - - You can also run generated qemu images with a command like 'runqemu qemux86-64' - </literallayout> - Among other things, the script creates the - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, - which is <filename>build</filename> in this case - and is located in the - <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. - After the script runs, your current working directory - is set to the Build Directory. - Later, when the build completes, the Build Directory - contains all the files created during the build. - </para></listitem> - <listitem><para id='conf-file-step'> - <emphasis>Examine Your Local Configuration File:</emphasis> - When you set up the build environment, a local - configuration file named - <filename>local.conf</filename> becomes available in - a <filename>conf</filename> subdirectory of the - Build Directory. - For this example, the defaults are set to build - for a <filename>qemux86</filename> target, which is - suitable for emulation. - The package manager used is set to the RPM package - manager. - <tip> - You can significantly speed up your build and guard - against fetcher failures by using mirrors. - To use mirrors, add these lines to your - <filename>local.conf</filename> file in the Build - directory: - <literallayout class='monospaced'> - SSTATE_MIRRORS = "\ - file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \ - file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \ - file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \ - " - </literallayout> - The previous examples showed how to add sstate - paths for Yocto Project &YOCTO_DOC_VERSION_MINUS_ONE;, - &YOCTO_DOC_VERSION;, and a development area. - For a complete index of sstate locations, see - <ulink url='http://sstate.yoctoproject.org/'></ulink>. - </tip> - </para></listitem> - <listitem><para> - <emphasis>Start the Build:</emphasis> - Continue with the following command to build an OS image - for the target, which is - <filename>core-image-sato</filename> in this example: - <literallayout class='monospaced'> - $ bitbake core-image-sato - </literallayout> - For information on using the - <filename>bitbake</filename> command, see the - "<ulink url='&YOCTO_DOCS_OM_URL;#usingpoky-components-bitbake'>BitBake</ulink>" - section in the Yocto Project Overview and Concepts Manual, - or see the - "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>" - section in the BitBake User Manual. - </para></listitem> - <listitem><para> - <emphasis>Simulate Your Image Using QEMU:</emphasis> - Once this particular image is built, you can start - QEMU, which is a Quick EMUlator that ships with - the Yocto Project: - <literallayout class='monospaced'> - $ runqemu qemux86-64 - </literallayout> - If you want to learn more about running QEMU, see the - "<ulink url="&YOCTO_DOCS_DEV_URL;#dev-manual-qemu">Using the Quick EMUlator (QEMU)</ulink>" - chapter in the Yocto Project Development Tasks Manual. - </para></listitem> - <listitem><para> - <emphasis>Exit QEMU:</emphasis> - Exit QEMU by either clicking on the shutdown icon or by - typing <filename>Ctrl-C</filename> in the QEMU - transcript window from which you evoked QEMU. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='customizing-your-build-for-specific-hardware'> - <title>Customizing Your Build for Specific Hardware</title> - - <para> - So far, all you have done is quickly built an image suitable - for emulation only. - This section shows you how to customize your build for specific - hardware by adding a hardware layer into the Yocto Project - development environment. - </para> - - <para> - In general, layers are repositories that contain related sets of - instructions and configurations that tell the Yocto Project what - to do. - Isolating related metadata into functionally specific layers - facilitates modular development and makes it easier to reuse the - layer metadata. - <note> - By convention, layer names start with the string "meta-". - </note> - </para> - - <para> - Follow these steps to add a hardware layer: - <orderedlist> - <listitem><para> - <emphasis>Find a Layer:</emphasis> - Lots of hardware layers exist. - The Yocto Project - <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> - has many hardware layers. - This example adds the - <ulink url='https://github.com/kraj/meta-altera'>meta-altera</ulink> - hardware layer. - </para></listitem> - <listitem><para> - <emphasis>Clone the Layer</emphasis> - Use Git to make a local copy of the layer on your machine. - You can put the copy in the top level of the copy of the - Poky repository created earlier: - <literallayout class='monospaced'> - $ cd ~/poky - $ git clone https://github.com/kraj/meta-altera.git - Cloning into 'meta-altera'... - remote: Counting objects: 25170, done. - remote: Compressing objects: 100% (350/350), done. - remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219 - Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done. - Resolving deltas: 100% (13385/13385), done. - Checking connectivity... done. - </literallayout> - The hardware layer now exists with other layers inside - the Poky reference repository on your build host as - <filename>meta-altera</filename> and contains all the - metadata needed to support hardware from Altera, which - is owned by Intel. - </para></listitem> - <listitem><para> - <emphasis>Change the Configuration to Build for a Specific Machine:</emphasis> - The - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - variable in the <filename>local.conf</filename> file - specifies the machine for the build. - For this example, set the <filename>MACHINE</filename> - variable to "cyclone5". - These configurations are used: - <ulink url='https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf'></ulink>. - <note> - See the - "<link linkend='conf-file-step'>Examine Your Local Configuration File</link>" - step earlier for more information on configuring the - build. - </note> - </para></listitem> - <listitem><para> - <emphasis>Add Your Layer to the Layer Configuration File:</emphasis> - Before you can use a layer during a build, you must add it - to your <filename>bblayers.conf</filename> file, which - is found in the - <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink> - <filename>conf</filename> directory.</para> - - <para>Use the <filename>bitbake-layers add-layer</filename> - command to add the layer to the configuration file: - <literallayout class='monospaced'> - $ cd ~/poky/build - $ bitbake-layers add-layer ../meta-altera - NOTE: Starting bitbake server... - Parsing recipes: 100% |##################################################################| Time: 0:00:32 - Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets, 123 skipped, 0 masked, 0 errors. - </literallayout> - You can find more information on adding layers in the - "<ulink url='&YOCTO_DOCS_DEV_URL;#adding-a-layer-using-the-bitbake-layers-script'>Adding a Layer Using the <filename>bitbake-layers</filename> Script</ulink>" - section. - </para></listitem> - </orderedlist> - Completing these steps has added the - <filename>meta-altera</filename> layer to your Yocto Project - development environment and configured it to build for the - "cyclone5" machine. - <note> - The previous steps are for demonstration purposes only. - If you were to attempt to build an image for the - "cyclone5" build, you should read the Altera - <filename>README</filename>. - </note> - </para> - </section> - - <section id='creating-your-own-general-layer'> - <title>Creating Your Own General Layer</title> - - <para> - Maybe you have an application or specific set of behaviors you - need to isolate. - You can create your own general layer using the - <filename>bitbake-layers create-layer</filename> command. - The tool automates layer creation by setting up a - subdirectory with a <filename>layer.conf</filename> - configuration file, a <filename>recipes-example</filename> - subdirectory that contains an <filename>example.bb</filename> - recipe, a licensing file, and a <filename>README</filename>. - </para> - - <para> - The following commands run the tool to create a layer named - <filename>meta-mylayer</filename> in the - <filename>poky</filename> directory: - <literallayout class='monospaced'> - $ cd ~/poky - $ bitbake-layers create-layer meta-mylayer - NOTE: Starting bitbake server... - Add your new layer with 'bitbake-layers add-layer meta-mylayer' - </literallayout> - For more information on layers and how to create them, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>" - section in the Yocto Project Development Tasks Manual. - </para> - </section> - - <section id='brief-where-to-go-next'> - <title>Where To Go Next</title> - - <para> - Now that you have experienced using the Yocto Project, you might - be asking yourself "What now?" - The Yocto Project has many sources of information including - the website, wiki pages, and user manuals: - <itemizedlist> - <listitem><para> - <emphasis>Website:</emphasis> - The - <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> - provides background information, the latest builds, - breaking news, full development documentation, and - access to a rich Yocto Project Development Community - into which you can tap. - </para></listitem> - <listitem><para> - <emphasis>Developer Screencast:</emphasis> - The - <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New Developer Screencast Tutorial</ulink> - provides a 30-minute video created for users unfamiliar - with the Yocto Project but familiar with Linux build - hosts. - While this screencast is somewhat dated, the - introductory and fundamental concepts are useful for - the beginner. - </para></listitem> - <listitem><para> - <emphasis>Yocto Project Overview and Concepts Manual:</emphasis> - The - <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink> - is a great place to start to learn about the - Yocto Project. - This manual introduces you to the Yocto Project and its - development environment. - The manual also provides conceptual information for - various aspects of the Yocto Project. - </para></listitem> - <listitem><para> - <emphasis>Yocto Project Wiki:</emphasis> - The - <ulink url='&YOCTO_WIKI_URL;'>Yocto Project Wiki</ulink> - provides additional information on where to go next - when ramping up with the Yocto Project, release - information, project planning, and QA information. - </para></listitem> - <listitem><para> - <emphasis>Yocto Project Mailing Lists:</emphasis> - Related mailing lists provide a forum for discussion, - patch submission and announcements. - Several mailing lists exist and are grouped according - to areas of concern. - See the - "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" - section in the Yocto Project Reference Manual for a - complete list of Yocto Project mailing lists. - </para></listitem> - <listitem><para> - <emphasis>Comprehensive List of Links and Other Documentation:</emphasis> - The - "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>" - section in the Yocto Project Reference Manual provides a - comprehensive list of all related links and other - user documentation. - </para></listitem> - </itemizedlist> - </para> - </section> -</article> -<!-- -vim: expandtab tw=80 ts=4 ---> |