diff options
Diffstat (limited to 'documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml')
-rw-r--r-- | documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml | 216 |
1 files changed, 175 insertions, 41 deletions
diff --git a/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml b/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml index 356bd521fd1..42dbf9c5636 100644 --- a/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml +++ b/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml @@ -4,7 +4,7 @@ <article id='brief-yocto-project-qs-intro'> <articleinfo> - <title>My First Yocto Project Build</title> + <title>Yocto Project Quick Build</title> <copyright> <year>©RIGHT_YEAR;</year> @@ -16,28 +16,6 @@ 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> -<!-- - <note><title>Manual Notes</title> - <itemizedlist> - <listitem><para> - For the latest version of this document associated with - this Yocto Project release - (version &YOCTO_DOC_VERSION;), see the "My First - Yocto Project Build" from the - <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. - </para></listitem> - <listitem><para> - This paper is written for the &YOCTO_DOC_VERSION;. - For later releases of the Yocto Project (if they exist), - go to the - <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> - and use the drop-down "Active Releases" button - and choose the Yocto Project version for which you want - the manual. - </para></listitem> - </itemizedlist> - </note> ---> </legalnotice> @@ -55,6 +33,8 @@ 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> @@ -74,7 +54,7 @@ <para> If you want more conceptual or background information on the Yocto Project, see the - <ulink url='&YOCTO_DOCS_GS_URL;'>Getting Started With Yocto Project Manual</ulink>. + <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>. </para> </section> @@ -82,7 +62,9 @@ <title>Compatible Linux Distribution</title> <para> - Make sure your build system meets the following requirements: + 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 @@ -118,17 +100,17 @@ </section> <section id='brief-build-system-packages'> - <title>Build System Packages</title> + <title>Build Host Packages</title> <para> You must install essential host packages on your - development host. + 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-host-development-system'>Required Packages for the Host Development System</ulink>" + "<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'> @@ -143,7 +125,7 @@ <para> Once you complete the setup instructions for your machine, you need to get a copy of the Poky repository on your build - system. + host. Use the following commands to clone the Poky repository and then checkout the &DISTRO_REL_TAG; release: <literallayout class='monospaced'> @@ -167,7 +149,7 @@ <para> For more options and information about accessing Yocto Project related repositories, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>" + "<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> @@ -177,8 +159,8 @@ <para> Use the following steps to build your image. - The OpenEmbedded build system creates an entire Linux - distribution, including the toolchain, from source. + The build process creates an entire Linux distribution, including + the toolchain, from source. <note> <itemizedlist> <listitem><para> @@ -207,7 +189,7 @@ <emphasis>Initialize the Build Environment:</emphasis> Run the <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - environment setup script to define the OpenEmbedded + environment setup script to define Yocto Project's build environment on your build host. <literallayout class='monospaced'> $ source &OE_INIT_FILE; @@ -222,7 +204,7 @@ Later, when the build completes, the Build Directory contains all the files created during the build. </para></listitem> - <listitem><para> + <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 @@ -243,13 +225,13 @@ <literallayout class='monospaced'> SSTATE_MIRRORS = "\ file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \ - file://.* http://sstate.yoctoproject.org/2.3/PATH;downloadfilename=PATH \n \ - file://.* http://sstate.yoctoproject.org/2.4/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 2.3, 2.4, and a development - area. + 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> @@ -264,9 +246,9 @@ </literallayout> For information on using the <filename>bitbake</filename> command, see the - "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#usingpoky-components-bitbake'>BitBake</ulink>" - section in the Yocto Project Overview Manual, or - 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> @@ -292,6 +274,147 @@ </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> @@ -322,6 +445,17 @@ 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> |