summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2015-05-21 11:12:19 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2015-07-28 18:02:32 +0100
commitab23dd967e5a59de3cffe48762b4956edba5d478 (patch)
treed170bb0b1418a309fb12419ccd310c2f1634abf7 /documentation
parentadd1f737b8baa5aa258d967cb29810dbd636ad1a (diff)
downloadpoky-ab23dd967e5a59de3cffe48762b4956edba5d478.tar.gz
yocto-project-qs and others: Rewrite of the QS
This was a complete re-write of the YP Quick Start in an attempt to streamline it, remove unecessary detail, and make it flow better with the examples. In doing so, many manuals were affected due to section headings being renamed, information being moved, etc. Here is a list of the changes by manual: Makefile - Removed two figures from TARFILE list for the yocto-project-qs. Added building-an-image.png to the ref-manual TARFILE list. Added using-a-pre-build-image.png to the adt-manual TARFILE list. Repositioned 'eclipse' in the adt-manual TARFILE list. adt-manual: Fixed a cross-reference so that it goes to the new 'Building Images' section that is within the YP QS. Added new section 'Example Using Pre-Build Binaries and QEMU' to hold the information that was formerly in YP QS. dev-manual: Removed a cross-reference into the YP QS that promised how to configure the most efficent build. Changed a cross-reference into the YP QS from 'The Packages' to 'The Build System Packages'. Changed a cross-reference into the YP QS from 'Building an Image' to 'Building Images'. Changed a text reference from the YP QS to the adt-manual. Moved the bit about getting YP files by using the YP website from the YP QS to the dev-manual. Changed a cross-reference into the YP QS from 'Using Pre-Built Binaries and QEMU' to 'Example Using Pre-built Binaries and QEMU', which was moved to the adt-manual. ref-manual: Changed a cross-reference into the YP QS from 'What You Need and How You Get It' to 'Setting Up to Use the Yocto Project'. Moved the note about if your system has oss4-dev in the packages area in the YP QS to the appropriate area in the ref-manual. Moved the introduction information regarding building an image along with the figure from YP QS to the ref-manual's section on building images. toaster-manual: Changed a cross-reference into the YP QS from 'What You Need and How You Get It' to 'Setting Up to Use the Yocto Project'. yocto-project-qs: Complete rewrite that changed many section headings and removed much detail, which was placed in other manuals. (From yocto-docs rev: da4ed8147b04963a700caa784bda709c57b4eb6e) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/Makefile6
-rw-r--r--documentation/adt-manual/adt-prepare.xml264
-rw-r--r--documentation/adt-manual/figures/using-a-pre-built-image.png (renamed from documentation/yocto-project-qs/figures/using-a-pre-built-image.png)bin12733 -> 12733 bytes
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml3
-rw-r--r--documentation/dev-manual/dev-manual-model.xml18
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml2
-rw-r--r--documentation/dev-manual/dev-manual-start.xml22
-rwxr-xr-xdocumentation/ref-manual/figures/building-an-image.png (renamed from documentation/yocto-project-qs/figures/building-an-image.png)bin14891 -> 14891 bytes
-rw-r--r--documentation/ref-manual/introduction.xml16
-rw-r--r--documentation/ref-manual/ref-bitbake.xml2
-rw-r--r--documentation/ref-manual/usingpoky.xml20
-rw-r--r--documentation/toaster-manual/toaster-manual-setup-and-use.xml8
-rw-r--r--documentation/toaster-manual/toaster-manual-start.xml2
-rw-r--r--documentation/yocto-project-qs/yocto-project-qs.xml1705
14 files changed, 965 insertions, 1103 deletions
diff --git a/documentation/Makefile b/documentation/Makefile
index 71420ac2bb..9197a40a78 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -147,7 +147,6 @@ ifeq ($(DOC),yocto-project-qs)
147XSLTOPTS = --xinclude 147XSLTOPTS = --xinclude
148ALLPREQ = html eclipse tarball 148ALLPREQ = html eclipse tarball
149TARFILES = yocto-project-qs.html qs-style.css figures/yocto-environment.png \ 149TARFILES = yocto-project-qs.html qs-style.css figures/yocto-environment.png \
150 figures/building-an-image.png figures/using-a-pre-built-image.png \
151 figures/yocto-project-transp.png \ 150 figures/yocto-project-transp.png \
152 eclipse 151 eclipse
153MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse 152MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
@@ -263,7 +262,7 @@ TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
263 figures/images.png figures/sdk.png figures/source-fetching.png \ 262 figures/images.png figures/sdk.png figures/source-fetching.png \
264 figures/patching.png figures/configuration-compile-autoreconf.png \ 263 figures/patching.png figures/configuration-compile-autoreconf.png \
265 figures/analysis-for-package-splitting.png figures/image-generation.png \ 264 figures/analysis-for-package-splitting.png figures/image-generation.png \
266 figures/sdk-generation.png 265 figures/sdk-generation.png figures/building-an-image.png
267MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse 266MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
268FIGURES = figures 267FIGURES = figures
269STYLESHEET = $(DOC)/*.css 268STYLESHEET = $(DOC)/*.css
@@ -274,7 +273,8 @@ ifeq ($(DOC),adt-manual)
274XSLTOPTS = --xinclude 273XSLTOPTS = --xinclude
275ALLPREQ = html eclipse tarball 274ALLPREQ = html eclipse tarball
276TARFILES = adt-manual.html adt-style.css figures/adt-title.png \ 275TARFILES = adt-manual.html adt-style.css figures/adt-title.png \
277 eclipse 276 figures/using-a-pre-built-image.png \
277 eclipse
278MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse 278MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
279FIGURES = figures 279FIGURES = figures
280STYLESHEET = $(DOC)/*.css 280STYLESHEET = $(DOC)/*.css
diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
index 814adbd615..01f569f805 100644
--- a/documentation/adt-manual/adt-prepare.xml
+++ b/documentation/adt-manual/adt-prepare.xml
@@ -465,9 +465,12 @@
465 <para> 465 <para>
466 To get the kernel and filesystem images, you either have to build them or download 466 To get the kernel and filesystem images, you either have to build them or download
467 pre-built versions. 467 pre-built versions.
468 You can find examples for both these situations in the 468 For an example of how to build these images, see the
469 "<ulink url='&YOCTO_DOCS_QS_URL;#test-run'>A Quick Test Run</ulink>" section of 469 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-buiding-images'>Buiding Images</ulink>"
470 the Yocto Project Quick Start. 470 section of the Yocto Project Quick Start.
471 For an example of downloading pre-build versions, see the
472 "<link linkend='using-pre-built'>Example Using Pre-Built Binaries and QEMU</link>"
473 section.
471 </para> 474 </para>
472 475
473 <para> 476 <para>
@@ -720,6 +723,261 @@
720 variable in the Yocto Project Reference Manual's variable glossary. 723 variable in the Yocto Project Reference Manual's variable glossary.
721 </para> 724 </para>
722</section> 725</section>
726
727 <section id='using-pre-built'>
728 <title>Example Using Pre-Built Binaries and QEMU</title>
729
730 <para>
731 If hardware, libraries and services are stable, you can get started by using a pre-built binary
732 of the filesystem image, kernel, and toolchain and run it using the QEMU emulator.
733 This scenario is useful for developing application software.
734 </para>
735
736 <mediaobject>
737 <imageobject>
738 <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/>
739 </imageobject>
740 <caption>
741 <para>Using a Pre-Built Image</para>
742 </caption>
743 </mediaobject>
744
745 <para>
746 For this scenario, you need to do several things:
747 </para>
748
749 <itemizedlist>
750 <listitem><para>Install the appropriate stand-alone toolchain tarball.</para></listitem>
751 <listitem><para>Download the pre-built image that will boot with QEMU.
752 You need to be sure to get the QEMU image that matches your target machine’s
753 architecture (e.g. x86, ARM, etc.).</para></listitem>
754 <listitem><para>Download the filesystem image for your target machine's architecture.
755 </para></listitem>
756 <listitem><para>Set up the environment to emulate the hardware and then start the QEMU emulator.
757 </para></listitem>
758 </itemizedlist>
759
760 <section id='installing-the-toolchain'>
761 <title>Installing the Toolchain</title>
762
763 <para>
764 You can download a tarball installer, which includes the
765 pre-built toolchain, the <filename>runqemu</filename>
766 script, and support files from the appropriate directory under
767 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
768 Toolchains are available for 32-bit and 64-bit x86 development
769 systems from the <filename>i686</filename> and
770 <filename>x86_64</filename> directories, respectively.
771 The toolchains the Yocto Project provides are based off the
772 <filename>core-image-sato</filename> image and contain
773 libraries appropriate for developing against that image.
774 Each type of development system supports five or more target
775 architectures.
776 </para>
777
778 <para>
779 The names of the tarball installer scripts are such that a
780 string representing the host system appears first in the
781 filename and then is immediately followed by a string
782 representing the target architecture.
783 </para>
784
785 <literallayout class='monospaced'>
786 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh
787
788 Where:
789 <replaceable>host_system</replaceable> is a string representing your development system:
790
791 i686 or x86_64.
792
793 <replaceable>image_type</replaceable> is a string representing the image you wish to
794 develop a Software Development Toolkit (SDK) for use against.
795 The Yocto Project builds toolchain installers using the
796 following BitBake command:
797
798 bitbake core-image-sato -c populate_sdk
799
800 <replaceable>arch</replaceable> is a string representing the tuned target architecture:
801
802 i586, x86_64, powerpc, mips, armv7a or armv5te
803
804 <replaceable>release_version</replaceable> is a string representing the release number of the
805 Yocto Project:
806
807 &DISTRO;, &DISTRO;+snapshot
808 </literallayout>
809
810 <para>
811 For example, the following toolchain installer is for a 64-bit
812 development host system and a i586-tuned target architecture
813 based off the SDK for <filename>core-image-sato</filename>:
814 <literallayout class='monospaced'>
815 poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
816 </literallayout>
817 </para>
818
819 <para>
820 Toolchains are self-contained and by default are installed into
821 <filename>/opt/poky</filename>.
822 However, when you run the toolchain installer, you can choose an
823 installation directory.
824 </para>
825
826 <para>
827 The following command shows how to run the installer given a toolchain tarball
828 for a 64-bit x86 development host system and a 32-bit x86 target architecture.
829 You must change the permissions on the toolchain
830 installer script so that it is executable.
831 </para>
832
833 <para>
834 The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>.
835 <note>
836 If you do not have write permissions for the directory into which you are installing
837 the toolchain, the toolchain installer notifies you and exits.
838 Be sure you have write permissions in the directory and run the installer again.
839 </note>
840 </para>
841
842 <para>
843 <literallayout class='monospaced'>
844 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
845 </literallayout>
846 </para>
847
848 <para>
849 For more information on how to install tarballs, see the
850 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and
851 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" sections in the Yocto Project Application Developer's Guide.
852 </para>
853 </section>
854
855 <section id='downloading-the-pre-built-linux-kernel'>
856 <title>Downloading the Pre-Built Linux Kernel</title>
857
858 <para>
859 You can download the pre-built Linux kernel suitable for running in the QEMU emulator from
860 <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.
861 Be sure to use the kernel that matches the architecture you want to simulate.
862 Download areas exist for the five supported machine architectures:
863 <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>,
864 <filename>qemux86</filename>, and <filename>qemux86-64</filename>.
865 </para>
866
867 <para>
868 Most kernel files have one of the following forms:
869 <literallayout class='monospaced'>
870 *zImage-qemu<replaceable>arch</replaceable>.bin
871 vmlinux-qemu<replaceable>arch</replaceable>.bin
872
873 Where:
874 <replaceable>arch</replaceable> is a string representing the target architecture:
875 x86, x86-64, ppc, mips, or arm.
876 </literallayout>
877 </para>
878
879 <para>
880 You can learn more about downloading a Yocto Project kernel in the
881 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>"
882 bulleted item in the Yocto Project Development Manual.
883 </para>
884 </section>
885
886 <section id='downloading-the-filesystem'>
887 <title>Downloading the Filesystem</title>
888
889 <para>
890 You can also download the filesystem image suitable for your target architecture from
891 <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.
892 Again, be sure to use the filesystem that matches the architecture you want
893 to simulate.
894 </para>
895
896 <para>
897 The filesystem image has two tarball forms: <filename>ext3</filename> and
898 <filename>tar</filename>.
899 You must use the <filename>ext3</filename> form when booting an image using the
900 QEMU emulator.
901 The <filename>tar</filename> form can be flattened out in your host development system
902 and used for build purposes with the Yocto Project.
903 <literallayout class='monospaced'>
904 core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.ext3
905 core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.tar.bz2
906
907 Where:
908 <replaceable>profile</replaceable> is the filesystem image's profile:
909 lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato,
910 sato-dev, or sato-sdk. For information on these types of image
911 profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
912 chapter in the Yocto Project Reference Manual.
913
914 <replaceable>arch</replaceable> is a string representing the target architecture:
915 x86, x86-64, ppc, mips, or arm.
916 </literallayout>
917 </para>
918 </section>
919
920 <section id='setting-up-the-environment-and-starting-the-qemu-emulator'>
921 <title>Setting Up the Environment and Starting the QEMU Emulator</title>
922
923 <para>
924 Before you start the QEMU emulator, you need to set up the emulation environment.
925 The following command form sets up the emulation environment.
926 <literallayout class='monospaced'>
927 $ source &YOCTO_ADTPATH_DIR;/environment-setup-<replaceable>arch</replaceable>-poky-linux-<replaceable>if</replaceable>
928
929 Where:
930 <replaceable>arch</replaceable> is a string representing the target architecture:
931 i586, x86_64, ppc603e, mips, or armv5te.
932
933 <replaceable>if</replaceable> is a string representing an embedded application binary interface.
934 Not all setup scripts include this string.
935 </literallayout>
936 </para>
937
938 <para>
939 Finally, this command form invokes the QEMU emulator
940 <literallayout class='monospaced'>
941 $ runqemu <replaceable>qemuarch</replaceable> <replaceable>kernel-image</replaceable> <replaceable>filesystem-image</replaceable>
942
943 Where:
944 <replaceable>qemuarch</replaceable> is a string representing the target architecture: qemux86, qemux86-64,
945 qemuppc, qemumips, or qemuarm.
946
947 <replaceable>kernel-image</replaceable> is the architecture-specific kernel image.
948
949 <replaceable>filesystem-image</replaceable> is the .ext3 filesystem image.
950
951 </literallayout>
952 </para>
953
954 <para>
955 Continuing with the example, the following two commands setup the emulation
956 environment and launch QEMU.
957 This example assumes the root filesystem (<filename>.ext3</filename> file) and
958 the pre-built kernel image file both reside in your home directory.
959 The kernel and filesystem are for a 32-bit target architecture.
960 <literallayout class='monospaced'>
961 $ cd $HOME
962 $ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux
963 $ runqemu qemux86 bzImage-qemux86.bin \
964 core-image-sato-qemux86.ext3
965 </literallayout>
966 </para>
967
968 <para>
969 The environment in which QEMU launches varies depending on the filesystem image and on the
970 target architecture.
971 For example, if you source the environment for the ARM target
972 architecture and then boot the minimal QEMU image, the emulator comes up in a new
973 shell in command-line mode.
974 However, if you boot the SDK image, QEMU comes up with a GUI.
975 <note>Booting the PPC image results in QEMU launching in the same shell in
976 command-line mode.</note>
977 </para>
978 </section>
979</section>
980
723</chapter> 981</chapter>
724<!-- 982<!--
725vim: expandtab tw=80 ts=4 983vim: expandtab tw=80 ts=4
diff --git a/documentation/yocto-project-qs/figures/using-a-pre-built-image.png b/documentation/adt-manual/figures/using-a-pre-built-image.png
index b03130d123..b03130d123 100644
--- a/documentation/yocto-project-qs/figures/using-a-pre-built-image.png
+++ b/documentation/adt-manual/figures/using-a-pre-built-image.png
Binary files differ
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index a929481633..e927a89bee 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -5021,9 +5021,6 @@
5021 Furthermore, the <link linkend='build-directory'>Build Directory</link> is 5021 Furthermore, the <link linkend='build-directory'>Build Directory</link> is
5022 <filename>build</filename> and is located in <filename>poky</filename> and 5022 <filename>build</filename> and is located in <filename>poky</filename> and
5023 the kernel is based on the Linux 3.4 kernel. 5023 the kernel is based on the Linux 3.4 kernel.
5024 For general information on how to configure the most efficient build, see the
5025 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
5026 in the Yocto Project Quick Start.
5027 </para> 5024 </para>
5028 5025
5029 <para> 5026 <para>
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 03eb5f1176..9c549d7464 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -124,7 +124,7 @@
124 development using the Yocto Project</emphasis>: See the 124 development using the Yocto Project</emphasis>: See the
125 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" 125 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>"
126 and the 126 and the
127 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both 127 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" sections both
128 in the Yocto Project Quick Start for requirements.</para></listitem> 128 in the Yocto Project Quick Start for requirements.</para></listitem>
129 <listitem><para><emphasis>Establish a local copy of the project files on your 129 <listitem><para><emphasis>Establish a local copy of the project files on your
130 system</emphasis>: You need this <link linkend='source-directory'>Source 130 system</emphasis>: You need this <link linkend='source-directory'>Source
@@ -223,7 +223,7 @@
223 "<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section 223 "<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section
224 for information on how to let the build system know about your new layer.</para> 224 for information on how to let the build system know about your new layer.</para>
225 <para>The entire process for building an image is overviewed in the section 225 <para>The entire process for building an image is overviewed in the section
226 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section 226 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" section
227 of the Yocto Project Quick Start. 227 of the Yocto Project Quick Start.
228 You might want to reference this information.</para></listitem> 228 You might want to reference this information.</para></listitem>
229 <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system 229 <listitem><para><emphasis>Build the image</emphasis>: The OpenEmbedded build system
@@ -451,7 +451,7 @@
451 <listitem><para><emphasis>Set up your host development system to support 451 <listitem><para><emphasis>Set up your host development system to support
452 development using the Yocto Project</emphasis>: See 452 development using the Yocto Project</emphasis>: See
453 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and 453 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and
454 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both 454 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" sections both
455 in the Yocto Project Quick Start for requirements.</para></listitem> 455 in the Yocto Project Quick Start for requirements.</para></listitem>
456 <listitem><para><emphasis>Establish a local copy of project files on your 456 <listitem><para><emphasis>Establish a local copy of project files on your
457 system</emphasis>: Having the <link linkend='source-directory'>Source 457 system</emphasis>: Having the <link linkend='source-directory'>Source
@@ -476,7 +476,7 @@
476 (<filename>local.conf</filename> and <filename>bblayers.conf</filename>) 476 (<filename>local.conf</filename> and <filename>bblayers.conf</filename>)
477 are configured appropriately.</para> 477 are configured appropriately.</para>
478 <para>The entire process for building an image is overviewed in the 478 <para>The entire process for building an image is overviewed in the
479 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 479 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
480 section of the Yocto Project Quick Start. 480 section of the Yocto Project Quick Start.
481 You might want to reference this information. 481 You might want to reference this information.
482 You can find more information on BitBake in the 482 You can find more information on BitBake in the
@@ -617,7 +617,7 @@
617 <para>For information on pre-built kernel image naming schemes for images 617 <para>For information on pre-built kernel image naming schemes for images
618 that can run on the QEMU emulator, see the 618 that can run on the QEMU emulator, see the
619 "<ulink url='&YOCTO_DOCS_QS_URL;#downloading-the-pre-built-linux-kernel'>Downloading the Pre-Built Linux Kernel</ulink>" 619 "<ulink url='&YOCTO_DOCS_QS_URL;#downloading-the-pre-built-linux-kernel'>Downloading the Pre-Built Linux Kernel</ulink>"
620 section in the Yocto Project Quick Start.</para></listitem> 620 section in the Yocto Project Application Developer's Guide.</para></listitem>
621 <listitem><para><emphasis>Install the ADT</emphasis>: 621 <listitem><para><emphasis>Install the ADT</emphasis>:
622 The ADT provides a target-specific cross-development toolchain, the root filesystem, 622 The ADT provides a target-specific cross-development toolchain, the root filesystem,
623 the QEMU emulator, and other tools that can help you develop your application. 623 the QEMU emulator, and other tools that can help you develop your application.
@@ -646,7 +646,7 @@
646 section in the Yocto Project Application Developer's Guide for information 646 section in the Yocto Project Application Developer's Guide for information
647 and the 647 and the
648 "<ulink url='&YOCTO_DOCS_QS_URL;#installing-the-toolchain'>Installing the Toolchain</ulink>" 648 "<ulink url='&YOCTO_DOCS_QS_URL;#installing-the-toolchain'>Installing the Toolchain</ulink>"
649 in the Yocto Project Quick Start for information on finding and installing 649 in the Yocto Project Application Developer's Guide for information on finding and installing
650 the correct toolchain based on your host development system and your target 650 the correct toolchain based on your host development system and your target
651 architecture. 651 architecture.
652 </para></listitem> 652 </para></listitem>
@@ -1163,7 +1163,7 @@
1163 If the architecture you need is not listed in 1163 If the architecture you need is not listed in
1164 the menu, you will need to build the image. 1164 the menu, you will need to build the image.
1165 See the 1165 See the
1166 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 1166 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
1167 section of the Yocto Project Quick Start for 1167 section of the Yocto Project Quick Start for
1168 more information.</para></listitem> 1168 more information.</para></listitem>
1169 </itemizedlist> 1169 </itemizedlist>
@@ -1740,7 +1740,7 @@
1740 For information on how to set up a local copy of the 1740 For information on how to set up a local copy of the
1741 <filename>poky</filename> repository and on how to 1741 <filename>poky</filename> repository and on how to
1742 build a Yocto Project image, see the 1742 build a Yocto Project image, see the
1743 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 1743 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
1744 section in the Yocto Project Quick Start. 1744 section in the Yocto Project Quick Start.
1745 </para></listitem> 1745 </para></listitem>
1746 <listitem><para> 1746 <listitem><para>
@@ -2375,7 +2375,7 @@
2375 <filename>bitbake -c cleanall <replaceable>package</replaceable></filename>). 2375 <filename>bitbake -c cleanall <replaceable>package</replaceable></filename>).
2376 Modifications will also disappear if you use the <filename>rm_work</filename> 2376 Modifications will also disappear if you use the <filename>rm_work</filename>
2377 feature as described in the 2377 feature as described in the
2378 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 2378 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
2379 section of the Yocto Project Quick Start. 2379 section of the Yocto Project Quick Start.
2380 </note></para></listitem> 2380 </note></para></listitem>
2381 <listitem><para><emphasis>Generate the Patch:</emphasis> 2381 <listitem><para><emphasis>Generate the Patch:</emphasis>
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 2c5fa683e0..70fa96975d 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -709,7 +709,7 @@
709 You "bake" something by running it through BitBake.</para> 709 You "bake" something by running it through BitBake.</para>
710 <para>It is worth noting that the term "package" can, in general, have subtle 710 <para>It is worth noting that the term "package" can, in general, have subtle
711 meanings. For example, the packages referred to in the 711 meanings. For example, the packages referred to in the
712 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section are 712 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" section are
713 compiled binaries that, when installed, add functionality to your Linux 713 compiled binaries that, when installed, add functionality to your Linux
714 distribution.</para> 714 distribution.</para>
715 <para>Another point worth noting is that historically within the Yocto Project, 715 <para>Another point worth noting is that historically within the Yocto Project,
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 36a3593c19..db989b7bfa 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -73,7 +73,7 @@
73 </para></listitem> 73 </para></listitem>
74 <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system 74 <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system
75 requires that certain packages exist on your development system (e.g. Python 2.7). 75 requires that certain packages exist on your development system (e.g. Python 2.7).
76 See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" 76 See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
77 section in the Yocto Project Quick Start and the 77 section in the Yocto Project Quick Start and the
78 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" 78 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
79 section in the Yocto Project Reference Manual for the exact 79 section in the Yocto Project Reference Manual for the exact
@@ -125,6 +125,20 @@
125 wiki page</ulink>, which describes how to create local 125 wiki page</ulink>, which describes how to create local
126 Git repositories for both 126 Git repositories for both
127 <filename>poky</filename> and <filename>meta-intel</filename>. 127 <filename>poky</filename> and <filename>meta-intel</filename>.
128 </para>
129 <para>
130 You can also get the Yocto Project Files by downloading
131 Yocto Project releases from the
132 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
133 From the website, you just click "Downloads" in the navigation
134 pane to the left to display all Yocto Project downloads.
135 Current and archived releases are available for download.
136 Nightly and developmental builds are also maintained at
137 <ulink url="&YOCTO_AB_NIGHTLY_URL;"></ulink>.
138 One final site you can visit for information on Yocto Project
139 releases is the
140 <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
141 wiki.
128 </para></listitem> 142 </para></listitem>
129 <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis> 143 <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
130 If you are going to be making modifications to a supported Yocto Project kernel, you 144 If you are going to be making modifications to a supported Yocto Project kernel, you
@@ -277,7 +291,7 @@
277 <para> 291 <para>
278 The build process creates an entire Linux distribution, including the toolchain, from source. 292 The build process creates an entire Linux distribution, including the toolchain, from source.
279 For more information on this topic, see the 293 For more information on this topic, see the
280 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 294 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
281 section in the Yocto Project Quick Start. 295 section in the Yocto Project Quick Start.
282 </para> 296 </para>
283 297
@@ -349,8 +363,8 @@
349 by sourcing an environment setup script. 363 by sourcing an environment setup script.
350 Finally, you start the QEMU emulator. 364 Finally, you start the QEMU emulator.
351 You can find details on all these steps in the 365 You can find details on all these steps in the
352 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" 366 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Example Using Pre-Built Binaries and QEMU</ulink>"
353 section of the Yocto Project Quick Start. 367 section of the Yocto Project Application Developer's Guide.
354 You can learn more about using QEMU with the Yocto Project in the 368 You can learn more about using QEMU with the Yocto Project in the
355 "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" 369 "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
356 section. 370 section.
diff --git a/documentation/yocto-project-qs/figures/building-an-image.png b/documentation/ref-manual/figures/building-an-image.png
index 1fbea5ab00..1fbea5ab00 100755
--- a/documentation/yocto-project-qs/figures/building-an-image.png
+++ b/documentation/ref-manual/figures/building-an-image.png
Binary files differ
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index cc3f6b075c..5250e26be7 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -110,7 +110,7 @@
110<title>System Requirements</title> 110<title>System Requirements</title>
111 <para> 111 <para>
112 For general Yocto Project system requirements, see the 112 For general Yocto Project system requirements, see the
113 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" section 113 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" section
114 in the Yocto Project Quick Start. 114 in the Yocto Project Quick Start.
115 The remainder of this section provides details on system requirements 115 The remainder of this section provides details on system requirements
116 not covered in the Yocto Project Quick Start. 116 not covered in the Yocto Project Quick Start.
@@ -212,6 +212,20 @@
212 <para> 212 <para>
213 The following list shows the required packages by function 213 The following list shows the required packages by function
214 given a supported Ubuntu or Debian Linux distribution: 214 given a supported Ubuntu or Debian Linux distribution:
215 <note>
216 If your build system has the
217 <filename>oss4-dev</filename> package installed, you
218 might experience QEMU build failures due to the package
219 installing its own custom
220 <filename>/usr/include/linux/soundcard.h</filename> on
221 the Debian system.
222 If you run into this situation, either of the following
223 solutions exist:
224 <literallayout class='monospaced'>
225 $ sudo apt-get build-dep qemu
226 $ sudo apt-get remove oss4-dev
227 </literallayout>
228 </note>
215 <itemizedlist> 229 <itemizedlist>
216 <listitem><para><emphasis>Essentials:</emphasis> 230 <listitem><para><emphasis>Essentials:</emphasis>
217 Packages needed to build an image on a headless 231 Packages needed to build an image on a headless
diff --git a/documentation/ref-manual/ref-bitbake.xml b/documentation/ref-manual/ref-bitbake.xml
index 30aff6431f..dc402dbffc 100644
--- a/documentation/ref-manual/ref-bitbake.xml
+++ b/documentation/ref-manual/ref-bitbake.xml
@@ -255,7 +255,7 @@
255 It is worth noting that you can greatly speed up the build time by properly setting 255 It is worth noting that you can greatly speed up the build time by properly setting
256 the <filename>BB_NUMBER_THREADS</filename> variable. 256 the <filename>BB_NUMBER_THREADS</filename> variable.
257 See the 257 See the
258 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 258 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
259 section in the Yocto Project Quick Start for more information. 259 section in the Yocto Project Quick Start for more information.
260 </para> 260 </para>
261 261
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index e2e05b2514..ca87962e24 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -19,7 +19,7 @@
19 for less obvious aspects of the build process. 19 for less obvious aspects of the build process.
20 For general information on how to build an image using the OpenEmbedded build 20 For general information on how to build an image using the OpenEmbedded build
21 system, see the 21 system, see the
22 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 22 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
23 section of the Yocto Project Quick Start. 23 section of the Yocto Project Quick Start.
24 </para> 24 </para>
25 25
@@ -27,6 +27,20 @@
27 <title>Build Overview</title> 27 <title>Build Overview</title>
28 28
29 <para> 29 <para>
30 In the development environment you will need to build an image whenever you change hardware
31 support, add or change system libraries, or add or change services that have dependencies.
32 </para>
33
34 <mediaobject>
35 <imageobject>
36 <imagedata fileref="figures/building-an-image.png" format="PNG" align='center' scalefit='1'/>
37 </imageobject>
38 <caption>
39 <para>Building an Image</para>
40 </caption>
41 </mediaobject>
42
43 <para>
30 The first thing you need to do is set up the OpenEmbedded build 44 The first thing you need to do is set up the OpenEmbedded build
31 environment by sourcing an environment setup script 45 environment by sourcing an environment setup script
32 (i.e. 46 (i.e.
@@ -99,8 +113,8 @@
99 <filename class="directory">tmp/deploy/images</filename>. 113 <filename class="directory">tmp/deploy/images</filename>.
100 For information on how to run pre-built images such as <filename>qemux86</filename> 114 For information on how to run pre-built images such as <filename>qemux86</filename>
101 and <filename>qemuarm</filename>, see the 115 and <filename>qemuarm</filename>, see the
102 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" 116 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Example Using Pre-Built Binaries and QEMU</ulink>"
103 section in the Yocto Project Quick Start. 117 section in the Yocto Project Application Developer's Guide.
104 For information about how to install these images, see the documentation for your 118 For information about how to install these images, see the documentation for your
105 particular board or machine. 119 particular board or machine.
106 </para> 120 </para>
diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
index a1546858d9..869d2490ef 100644
--- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -32,7 +32,7 @@
32 Get the requirements set up so that you can use the 32 Get the requirements set up so that you can use the
33 Yocto Project to build images. 33 Yocto Project to build images.
34 See the 34 See the
35 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" 35 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
36 section in the Yocto Project Quick Start for information. 36 section in the Yocto Project Quick Start for information.
37 </para></listitem> 37 </para></listitem>
38 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis> 38 <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis>
@@ -132,7 +132,7 @@
132 Get the requirements set up so that you can use the 132 Get the requirements set up so that you can use the
133 Yocto Project to build images. 133 Yocto Project to build images.
134 See the 134 See the
135 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" 135 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
136 section in the Yocto Project Quick Start for information. 136 section in the Yocto Project Quick Start for information.
137 </para></listitem> 137 </para></listitem>
138 <listitem><para><emphasis>Install and Set up the Database Server:</emphasis> 138 <listitem><para><emphasis>Install and Set up the Database Server:</emphasis>
@@ -394,7 +394,7 @@
394 Get the requirements set up so that you can use the 394 Get the requirements set up so that you can use the
395 Yocto Project to build images. 395 Yocto Project to build images.
396 See the 396 See the
397 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" 397 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
398 section in the Yocto Project Quick Start for information. 398 section in the Yocto Project Quick Start for information.
399 </para></listitem> 399 </para></listitem>
400 <listitem><para><emphasis>Start Toaster:</emphasis> 400 <listitem><para><emphasis>Start Toaster:</emphasis>
@@ -491,7 +491,7 @@
491 Get the requirements set up so that you can use the 491 Get the requirements set up so that you can use the
492 Yocto Project to build images. 492 Yocto Project to build images.
493 See the 493 See the
494 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" 494 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
495 section in the Yocto Project Quick Start for information. 495 section in the Yocto Project Quick Start for information.
496 </para></listitem> 496 </para></listitem>
497 <listitem><para><emphasis>Be Sure Management is Enabled:</emphasis> 497 <listitem><para><emphasis>Be Sure Management is Enabled:</emphasis>
diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml
index 2a77c90de7..fbdb5ecb90 100644
--- a/documentation/toaster-manual/toaster-manual-start.xml
+++ b/documentation/toaster-manual/toaster-manual-start.xml
@@ -18,7 +18,7 @@
18 You first need to be sure your build system is set up to run 18 You first need to be sure your build system is set up to run
19 the Yocto Project. 19 the Yocto Project.
20 See the 20 See the
21 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" 21 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
22 section in the Yocto Project Quick Start for information on how 22 section in the Yocto Project Quick Start for information on how
23 to set up your system for the Yocto Project. 23 to set up your system for the Yocto Project.
24 </para> 24 </para>
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index a8344be1ea..5da7314bd6 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -32,1013 +32,569 @@
32 </abstract> 32 </abstract>
33 </articleinfo> 33 </articleinfo>
34 34
35<section id='welcome'> 35 <section id='welcome'>
36 <title>Welcome!</title> 36 <title>Welcome!</title>
37 <para>
38 Welcome to the Yocto Project!
39 The Yocto Project is an open-source collaboration project focused on
40 embedded Linux developers.
41 Among other things, the Yocto Project uses a build system based on the
42 OpenEmbedded (OE) project, which uses the
43 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
44 tool, to construct complete Linux images.
45 The BitBake and OE components are combined together to form
46 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>,
47 a reference build system.
48 </para>
49
50 <para>
51 If you don't have a system that runs Linux and you want to give the Yocto Project a test run,
52 you might consider using the Yocto Project Build Appliance.
53 The Build Appliance allows you to build and boot a custom embedded Linux image with the Yocto
54 Project using a non-Linux development system.
55 See the <ulink url='https://www.yoctoproject.org/tools-resources/projects/build-appliance'>Yocto
56 Project Build Appliance</ulink> for more information.
57 </para>
58
59 <para>
60 On the other hand, if you know all about open-source development, Linux development environments,
61 Git source repositories and the like and you just want some quick information that lets you try out
62 the Yocto Project on your Linux system, skip right to the
63 "<link linkend='super-user'>Super User</link>" section at the end of this quick start.
64 </para>
65
66 <para>
67 For the rest of you, this short document will give you some basic information about the environment and
68 let you experience it in its simplest form.
69 After reading this document, you will have a basic understanding of what the Yocto Project is
70 and how to use some of its core components.
71 This document steps you through a simple example showing you how to build a small image
72 and run it using the Quick EMUlator (QEMU emulator).
73 </para>
74
75 <para>
76 For more detailed information on the Yocto Project, you should check out these resources:
77 <itemizedlist>
78 <listitem><para><emphasis>Website:</emphasis> The <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
79 provides the latest builds, breaking news, full development documentation, and a rich Yocto
80 Project Development Community into which you can tap.
81 </para></listitem>
82 <listitem><para><emphasis>FAQs:</emphasis> Lists commonly asked Yocto Project questions and answers.
83 You can find two FAQs: <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>Yocto Project FAQ</ulink> on
84 a wiki, and the
85 "<ulink url='&YOCTO_DOCS_REF_URL;#faq'>FAQ</ulink>" chapter in
86 the Yocto Project Reference Manual.
87 </para></listitem>
88 <listitem><para><emphasis>Developer Screencast:</emphasis> The
89 <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New Developer Screencast Tutorial</ulink>
90 provides a 30-minute video created for users unfamiliar with
91 the Yocto Project but familiar with Linux build systems.
92 While this screencast is somewhat dated, the introductory
93 and fundamental concepts are useful for the beginner.
94 </para></listitem>
95 </itemizedlist>
96 </para>
97</section>
98
99<section id='yp-intro'>
100 <title>Introducing the Yocto Project Development Environment</title>
101 <para>
102 The Yocto Project through the OpenEmbedded build system provides an
103 open source development environment targeting the ARM, MIPS, PowerPC
104 and x86 architectures for a variety of platforms including x86-64 and
105 emulated ones.
106 You can use components from the Yocto Project to design, develop,
107 build, debug, simulate, and test the complete software stack using
108 Linux, the X Window System, GTK+ frameworks, and Qt frameworks.
109 </para>
110
111 <mediaobject>
112 <imageobject>
113 <imagedata fileref="figures/yocto-environment.png"
114 format="PNG" align='center' scalefit='1' width="100%"/>
115 </imageobject>
116 <caption>
117 <para>The Yocto Project Development Environment</para>
118 </caption>
119 </mediaobject>
120
121 <para>
122 Here are some highlights for the Yocto Project:
123 </para>
124
125 <itemizedlist>
126 <listitem>
127 <para>Provides a recent Linux kernel along with a set of system commands and libraries suitable for the embedded environment.</para>
128 </listitem>
129 <listitem>
130 <para>Makes available system components such as X11, GTK+, Qt, Clutter, and SDL
131 (among others) so you can create a rich user experience on devices
132 that have display hardware.
133 For devices that do not have a display or where you wish to use alternative UI
134 frameworks, these components need not be installed.</para>
135 </listitem>
136 <listitem>
137 <para>Creates a focused and stable core compatible with the OpenEmbedded
138 project with which you can easily and reliably build and develop.</para>
139 </listitem>
140 <listitem>
141 <para>Fully supports a wide range of hardware and device emulation through the QEMU
142 Emulator.</para>
143 </listitem>
144 </itemizedlist>
145
146 <para>
147 The Yocto Project can generate images for many kinds of devices.
148 However, the standard example machines target QEMU full-system emulation for x86, x86-64, ARM, MIPS,
149 and PPC-based architectures as well as specific hardware such as the
150 <trademark class='registered'>Intel</trademark> Desktop Board DH55TC.
151 Because an image developed with the Yocto Project can boot inside a QEMU emulator, the
152 development environment works nicely as a test platform for developing embedded software.
153 </para>
154
155 <para>
156 Another important Yocto Project feature is the Sato reference User
157 Interface.
158 This optional UI that is based on GTK+ is intended for devices with
159 restricted screen sizes.
160 The UI sits neatly on top of a device using the
161 GTK+ stack and provides a well-defined user experience.
162 Implemented in its own layer, it makes it clear to developers how they
163 can implement their own user interface on top of a Linux image created
164 with the Yocto Project.
165 </para>
166</section>
167
168<section id='yp-resources'>
169 <title>What You Need and How You Get It</title>
170
171 <para>
172 You need these things to develop projects in the Yocto Project
173 environment:
174 </para>
175
176 <itemizedlist>
177 <listitem><para>
178 A host system with a minimum of 50 Gbytes of free disk space that
179 is running a supported Linux distribution (i.e. recent releases
180 of Fedora, openSUSE, CentOS, Debian, or Ubuntu).
181 If the host system supports multiple cores and threads, you can
182 configure the Yocto Project build system to significantly
183 decrease the time needed to build images.
184 </para></listitem>
185 <listitem><para>
186 Appropriate packages installed on the system you are using for
187 builds.
188 </para></listitem>
189 <listitem><para>
190 A release of the Yocto Project.
191 </para></listitem>
192 </itemizedlist>
193
194 <section id='the-linux-distro'>
195 <title>The Linux Distribution</title>
196
197 <para>
198 The Yocto Project team is continually verifying more and more Linux
199 distributions with each release.
200 In general, if you have the current release minus one of the following
201 distributions you should have no problems.
202 <itemizedlist>
203 <listitem><para>Ubuntu</para></listitem>
204 <listitem><para>Fedora</para></listitem>
205 <listitem><para>openSUSE</para></listitem>
206 <listitem><para>CentOS</para></listitem>
207 <listitem><para>Debian</para></listitem>
208 </itemizedlist>
209 For a more detailed list of distributions that support the Yocto Project,
210 see the
211 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
212 in the Yocto Project Reference Manual.
213 </para>
214 <para> 37 <para>
215 The OpenEmbedded build system should be able to run on any modern 38 Welcome to the Yocto Project!
216 distribution that has the following versions for Git, tar, and 39 The Yocto Project is an open-source collaboration project whose
217 Python. 40 focus is developers of embedded Linux systems.
218 <itemizedlist> 41 Among other things, the Yocto Project uses a build host based
219 <listitem><para>Git 1.7.8 or greater</para></listitem> 42 on the OpenEmbedded (OE) project, which uses the
220 <listitem><para>tar 1.24 or greater</para></listitem> 43 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
221 <listitem><para>Python 2.7.3 or greater excluding Python 44 tool, to construct complete Linux images.
222 3.x, which is not supported.</para></listitem> 45 The BitBake and OE components are combined together to form
223 </itemizedlist> 46 a reference build host, historically known as
224 Earlier releases of Python are known to not work and the 47 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>.
225 system does not support Python 3 at this time.
226 If your system does not meet any of these three listed
227 version requirements, you can
228 take steps to prepare the system so that you can still use the build
229 system.
230 See the
231 "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>"
232 section in the Yocto Project Reference Manual for information.
233 </para>
234 <para>
235 This document assumes you are running one of the previously noted
236 distributions on your Linux-based host systems.
237 </para>
238 <note>
239 <para>
240 If you attempt to use a distribution not in the above list,
241 you may or may not have success.
242 Yocto Project releases are tested against the stable Linux
243 distributions listed in the
244 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
245 section of the Yocto Project Reference Manual.
246 If you encounter problems, please go to
247 <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
248 and submit a bug.
249 We are interested in hearing about your experience.
250 </para>
251 </note>
252 </section>
253
254 <section id='packages'>
255 <title>The Packages</title>
256
257 <para>
258 Packages and package installation vary depending on your development system
259 and on your intent.
260 For example, if you want to build an image that can run
261 on QEMU in graphical mode (a minimal, basic build
262 requirement), then the number of packages is different than if you want to
263 build an image on a headless system or build out the Yocto Project
264 documentation set.
265 Collectively, the number of required packages is large
266 if you want to be able to cover all cases.
267 <note>In general, you need to have root access and then install the
268 required packages.
269 Thus, the commands in the following section may or may not work
270 depending on whether or not your Linux distribution has
271 <filename>sudo</filename> installed.</note>
272 </para>
273
274 <para>
275 The next few sections list, by supported Linux Distributions, the required
276 packages needed to build an image that runs on QEMU in graphical mode
277 (e.g. essential plus graphics support).
278 </para> 48 </para>
279 49
280 <para> 50 <para>
281 For lists of required packages for other scenarios, see the 51 If you do not have a system that runs Linux and you want to give
282 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" 52 the Yocto Project a test run, you might consider using the Yocto
283 section in the Yocto Project Reference Manual. 53 Project Build Appliance.
54 The Build Appliance allows you to build and boot a custom embedded
55 Linux image with the Yocto Project using a non-Linux development
56 system.
57 See the
58 <ulink url='https://www.yoctoproject.org/tools-resources/projects/build-appliance'>Yocto Project Build Appliance</ulink>
59 for more information.
284 </para> 60 </para>
285 61
286 <section id='ubuntu'>
287 <title>Ubuntu and Debian</title>
288
289 <para>
290 The essential and graphical support packages you need for a
291 supported Ubuntu or Debian distribution are shown in the
292 following command:
293 <literallayout class='monospaced'>
294 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm
295 </literallayout>
296 <note>
297 If your build system has the
298 <filename>oss4-dev</filename> package installed, you
299 might experience QEMU build failures due to the package
300 installing its own custom
301 <filename>/usr/include/linux/soundcard.h</filename> on
302 the Debian system.
303 If you run into this situation, either of the following
304 solutions exist:
305 <literallayout class='monospaced'>
306 $ sudo apt-get build-dep qemu
307 $ sudo apt-get remove oss4-dev
308 </literallayout>
309 </note>
310 </para>
311 </section>
312
313 <section id='fedora'>
314 <title>Fedora</title>
315
316 <para>
317 The essential and graphical packages you need for a supported
318 Fedora distribution are shown in the following command:
319 <literallayout class='monospaced'>
320 $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
321 </literallayout>
322 </para>
323 </section>
324
325 <section id='opensuse'>
326 <title>OpenSUSE</title>
327
328 <para>
329 The essential and graphical packages you need for a supported
330 OpenSUSE distribution are shown in the following command:
331 <literallayout class='monospaced'>
332 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; libSDL-devel xterm
333 </literallayout>
334 </para>
335 </section>
336
337 <section id='centos'>
338 <title>CentOS</title>
339
340 <para>
341 The essential and graphical packages you need for a supported
342 CentOS distribution are shown in the following command:
343 <literallayout class='monospaced'>
344 $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
345 </literallayout>
346 <note>Depending on the CentOS version you are using, other requirements
347 and dependencies might exist.
348 For details, you should look at the CentOS sections on the
349 <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink>
350 wiki page.</note>
351 </para>
352 </section>
353 </section>
354
355 <section id='releases'>
356 <title>Yocto Project Release</title>
357
358 <para> 62 <para>
359 It is recommended that you get the latest Yocto Project files 63 This quick start is written so that you can quickly get a host
360 by setting up (cloning in 64 build host set up to use the Yocto Project and then build some
361 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> terms) a local 65 Linux images.
362 copy of the 66 Rather than go into great detail about the Yocto Project and its
363 <filename>poky</filename> Git repository on your host development 67 many capabilities, this quick start provides the minimal
364 system. 68 information you need to try out the Yocto Project using a
365 Doing so allows you to contribute back to the Yocto Project project. 69 supported Linux build host.
366 For information on how to get set up using this method, see the 70 Reading and using the quick start should result in you having a
367 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-yp-release'>Yocto 71 basic understanding of what the Yocto Project is and how to use
368 Project Release</ulink>" item in the Yocto Project Development Manual. 72 some of its core components.
73 You will also have worked through steps to produce two images:
74 one suitable for emulation and one that can be used on actual
75 hardware.
76 The examples highlight the ease with which you can use the
77 Yocto Project to create images for multiple types of hardware.
369 </para> 78 </para>
370 79
371 <para> 80 <para>
372 You can also get the Yocto Project Files by downloading 81 For more detailed information on the Yocto Project, you can
373 Yocto Project releases from the 82 reference these resources:
374 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>. 83 <itemizedlist>
375 From the website, you just click "Downloads" in the navigation pane 84 <listitem><para><emphasis>Website:</emphasis>
376 to the left to display all Yocto Project downloads. 85 The
377 Current and archived releases are available for download. 86 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
378 Nightly and developmental builds are also maintained at 87 provides the latest builds, breaking news, full development
379 <ulink url="&YOCTO_AB_NIGHTLY_URL;"></ulink>. 88 documentation, and access to a rich Yocto Project
380 One final site you can visit for information on Yocto Project 89 Development Community into which you can tap.
381 releases is the 90 </para></listitem>
382 <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink> 91 <listitem><para><emphasis>FAQs:</emphasis>
383 wiki. 92 Lists commonly asked Yocto Project questions and answers.
384 However, for this document a released version of Yocto Project is used. 93 You can find two FAQs:
94 <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>Yocto Project FAQ</ulink>
95 on a wiki, and the
96 "<ulink url='&YOCTO_DOCS_REF_URL;#faq'>FAQ</ulink>"
97 chapter in the Yocto Project Reference Manual.
98 </para></listitem>
99 <listitem><para><emphasis>Developer Screencast:</emphasis>
100 The
101 <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New Developer Screencast Tutorial</ulink>
102 provides a 30-minute video created for users unfamiliar
103 with the Yocto Project but familiar with Linux build
104 hosts.
105 While this screencast is somewhat dated, the introductory
106 and fundamental concepts are useful for the beginner.
107 </para></listitem>
108 </itemizedlist>
385 </para> 109 </para>
386
387 </section> 110 </section>
388</section>
389 111
390<section id='test-run'> 112 <section id='yp-intro'>
391 <title>A Quick Test Run</title> 113 <title>Introducing the Yocto Project Development Environment</title>
392
393 <para>
394 Now that you have your system requirements in order, you can give
395 the Yocto Project a try.
396 This section presents some steps that let you do the following:
397 <itemizedlist>
398 <listitem><para>
399 Build an image and run it in the QEMU emulator.
400 </para></listitem>
401 <listitem><para>
402 Use a pre-built image and run it in the QEMU emulator.
403 </para></listitem>
404 </itemizedlist>
405 <note>
406 This section does not provide detail, but rather provides minimal,
407 working commands and examples designed to just get you started.
408 For more details, see the appropriate manuals in the
409 <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project manual set</ulink>.
410 </note>
411 </para>
412
413 <section id='building-image'>
414 <title>Building an Image</title>
415 114
416 <para> 115 <para>
417 In the development environment you will need to build an image whenever you change hardware 116 The Yocto Project through the OpenEmbedded build system provides an
418 support, add or change system libraries, or add or change services that have dependencies. 117 open source development environment targeting the ARM, MIPS,
118 PowerPC, and x86 architectures for a variety of platforms
119 including x86-64 and emulated ones.
120 You can use components from the Yocto Project to design, develop,
121 build, debug, simulate, and test the complete software stack using
122 Linux, the X Window System, GTK+ frameworks, and Qt frameworks.
419 </para> 123 </para>
420 124
421 <mediaobject> 125 <mediaobject>
422 <imageobject> 126 <imageobject>
423 <imagedata fileref="figures/building-an-image.png" format="PNG" align='center' scalefit='1'/> 127 <imagedata fileref="figures/yocto-environment.png"
128 format="PNG" align='center' scalefit='1' width="100%"/>
424 </imageobject> 129 </imageobject>
425 <caption> 130 <caption>
426 <para>Building an Image</para> 131 <para>The Yocto Project Development Environment</para>
427 </caption> 132 </caption>
428 </mediaobject> 133 </mediaobject>
429 134
430 <para>
431 Use the following commands to build your image.
432 The OpenEmbedded build process creates an entire Linux
433 distribution, including the toolchain, from source.
434 <note><title>Note about Network Proxies</title>
435 <para>
436 By default, the build process searches for source code
437 using a pre-determined order through a set of locations.
438 If you are working behind a firewall and your build system
439 is not set up for proxies, you could encounter problems
440 with the build process when fetching source code (e.g.
441 fetcher failures or Git failures).
442 </para>
443
444 <para>
445 If you do not know your proxy settings, consult your
446 local network infrastructure resources and get that
447 information.
448 A good starting point could also be to check your web
449 browser settings.
450 Finally, you can find more information on using the Yocto
451 Project behind a firewall in the Yocto Project Reference
452 Manual
453 <ulink url='&YOCTO_DOCS_REF_URL;#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</ulink>
454 and on the
455 "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
456 wiki page.
457 </para>
458 </note>
459 </para>
460
461 <para>
462 <literallayout class='monospaced'>
463 $ git clone &YOCTO_GIT_URL;/git/poky
464 $ cd poky
465 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
466 $ source &OE_INIT_FILE;
467 </literallayout>
468 </para>
469
470 <tip>
471 <para>
472 To help conserve disk space during builds, you can add the
473 following statement to your project's configuration file,
474 which for this example is
475 <filename>poky/build/conf/local.conf</filename>.
476 Adding this statement deletes the work directory used for
477 building a package once the package is built.
478 <literallayout class='monospaced'>
479 INHERIT += "rm_work"
480 </literallayout>
481 </para>
482 </tip>
483
484 <itemizedlist>
485 <listitem><para>In the previous example, the first command uses
486 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> to create
487 a local repository named <filename>poky</filename> that is a
488 clone of the upstream Yocto Project
489 <filename>poky</filename> repository.</para></listitem>
490 <listitem><para>The third command checks out the current
491 Yocto Project release into a local branch whose name matches
492 the release (i.e. <filename>&DISTRO_NAME;</filename>).
493 The local branch tracks the upstream branch of the same name.
494 Creating your own branch based on the released branch ensures
495 you are using the latest files for that release.
496 </para></listitem>
497 <listitem><para>
498 The final command runs the Yocto Project
499 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
500 environment setup script.
501 Running this script defines OpenEmbedded build environment
502 settings needed to complete the build.
503 The script also creates the
504 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
505 which is <filename>build</filename> in this case and is located
506 in the
507 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
508 After the script runs, your current working directory is set
509 to the Build Directory.
510 Later, when the build completes, the Build Directory contains
511 all the files created during the build.
512 <note>
513 For information on running a memory-resident
514 <ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>,
515 see the
516 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
517 setup script.
518 </note></para></listitem>
519 </itemizedlist>
520 <para>
521 Take some time to examine your <filename>local.conf</filename> file
522 in your project's configuration directory, which is found in the Build Directory.
523 The defaults in that file should work fine.
524 However, there are some variables of interest at which you might look.
525 </para>
526
527 <para>
528 By default, the target architecture for the build is <filename>qemux86</filename>,
529 which produces an image that can be used in the QEMU emulator and is targeted at an
530 <trademark class='registered'>Intel</trademark> 32-bit based architecture.
531 To change this default, edit the value of the
532 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
533 variable in the configuration file before launching the build.
534 </para>
535
536 <para>
537 Three other variables of interest are the
538 <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>,
539 <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>,
540 and
541 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink>
542 variables.
543 By default, the OpenEmbedded build system sets these variables
544 based on the number of processor cores your build host uses.
545 Thus, you typically do not need to uncomment these variables in
546 your <filename>local.conf</filename> file to gain optimal build
547 times.
548 </para>
549
550 <para> 135 <para>
551 Another consideration before you build is the package manager used when creating 136 Here are some highlights for the Yocto Project:
552 the image.
553 By default, the OpenEmbedded build system uses the RPM package manager.
554 You can control this configuration by using the
555 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink></filename> variable.
556 For additional package manager selection information, see the
557 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package*.bbclass</filename></ulink>"
558 section in the Yocto Project Reference Manual.
559 </para> 137 </para>
560 138
561 <para> 139 <itemizedlist>
562 Continue with the following command to build an OS image for the 140 <listitem><para>
563 target, which is <filename>core-image-sato</filename> in this 141 Provides a recent Linux kernel along with a set of system
564 example. 142 commands and libraries suitable for the embedded
565 For information on the <filename>-k</filename> option use the 143 environment.
566 <filename>bitbake --help</filename> command, see the 144 </para></listitem>
567 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>" 145 <listitem><para>
568 section in the Yocto Project Reference Manual, or see the 146 Makes available system components such as X11, GTK+, Qt,
569 "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>" 147 Clutter, and SDL (among others) so you can create a rich user
570 section in the BitBake User Manual. 148 experience on devices that have display hardware.
571 For information on other targets, see the 149 For devices that do not have a display or where you wish to
572 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" 150 use alternative UI frameworks, these components need not be
573 chapter in the Yocto Project Reference Manual. 151 installed.
574 <literallayout class='monospaced'> 152 </para></listitem>
575 $ bitbake -k core-image-sato 153 <listitem><para>
576 </literallayout> 154 Creates a focused and stable core compatible with the
577 <note> 155 OpenEmbedded project with which you can easily and reliably
578 BitBake requires Python 2.7. For more information on 156 build and develop.
579 this requirement, see the 157 </para></listitem>
580 "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python</ulink>" 158 <listitem><para>
581 section in the Yocto Project Reference Manual. 159 Fully supports a wide range of hardware and device emulation
582 </note> 160 through the Quick EMUlator (QEMU).
583 The final command runs the image using the QEMU emulator: 161 </para></listitem>
584 <literallayout class='monospaced'> 162 <listitem><para>
585 $ runqemu qemux86 163 Provides a layer mechanism that allows you to easily extend
586 </literallayout> 164 the system, make customizations, and keep them organized.
587 <note> 165 </para></listitem>
588 <para> 166 </itemizedlist>
589 Depending on the number of processors and cores, the amount
590 of RAM, the speed of your Internet connection and other
591 factors, the build process could take several hours the
592 first time you run it.
593 Subsequent builds run much faster since parts of the build
594 are cached.
595 </para>
596 </note>
597 If you want to learn more about running QEMU, see the
598 "<ulink url="&YOCTO_DOCS_DEV_URL;#dev-manual-qemu">Using the Quick EMUlator (QEMU)</ulink>"
599 chapter in the Yocto Project Development Manual.
600 </para>
601 167
602 <para> 168 <para>
603 For information on how to use a pre-built binary, continue reading 169 You can use the Yocto Project to generate images for many kinds
604 into the next section. 170 of devices.
605 Otherwise, you might be interested in reading the early chapters 171 As mentioned earlier, the Yocto Project supports creation of
606 of the 172 reference images that you can boot within and emulate using QEMU.
607 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>. 173 The standard example machines target QEMU full-system
174 emulation for 32-bit and 64-bit variants of x86, ARM, MIPS, and
175 PowerPC architectures.
176 Beyond emulation, you can use the layer mechanism to extend
177 support to just about any platform that Linux can run on and that
178 a toolchain can target.
608 </para> 179 </para>
609 </section>
610
611 <section id='using-pre-built'>
612 <title>Using Pre-Built Binaries and QEMU</title>
613 180
614 <para> 181 <para>
615 If hardware, libraries and services are stable, you can get started by using a pre-built binary 182 Another Yocto Project feature is the Sato reference User
616 of the filesystem image, kernel, and toolchain and run it using the QEMU emulator. 183 Interface.
617 This scenario is useful for developing application software. 184 This optional UI that is based on GTK+ is intended for devices with
185 restricted screen sizes and is included as part of the
186 OpenEmbedded Core layer so that developers can test parts of the
187 software stack.
618 </para> 188 </para>
189 </section>
619 190
620 <mediaobject> 191 <section id='yp-resources'>
621 <imageobject> 192 <title>Setting Up to Use the Yocto Project</title>
622 <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/>
623 </imageobject>
624 <caption>
625 <para>Using a Pre-Built Image</para>
626 </caption>
627 </mediaobject>
628 193
629 <para> 194 <para>
630 For this scenario, you need to do several things: 195 The following list shows what you need in order to use a
196 Linux-based build host to use the Yocto Project to build images:
631 </para> 197 </para>
632 198
633 <itemizedlist> 199 <itemizedlist>
634 <listitem><para>Install the appropriate stand-alone toolchain tarball.</para></listitem> 200 <listitem><para><emphasis>Build Host</emphasis>
635 <listitem><para>Download the pre-built image that will boot with QEMU. 201 A build host with a minimum of 50 Gbytes of free disk
636 You need to be sure to get the QEMU image that matches your target machine’s 202 space that is running a supported Linux distribution (i.e.
637 architecture (e.g. x86, ARM, etc.).</para></listitem> 203 recent releases of Fedora, openSUSE, CentOS, Debian, or
638 <listitem><para>Download the filesystem image for your target machine's architecture. 204 Ubuntu).
639 </para></listitem> 205 </para></listitem>
640 <listitem><para>Set up the environment to emulate the hardware and then start the QEMU emulator. 206 <listitem><para><emphasis>Build Host Packages</emphasis>
207 Appropriate packages installed on the build host.
208 </para></listitem>
209 <listitem><para><emphasis>The Yocto Project</emphasis>
210 A release of the Yocto Project.
641 </para></listitem> 211 </para></listitem>
642 </itemizedlist> 212 </itemizedlist>
643 213
644 <section id='installing-the-toolchain'> 214 <section id='the-linux-distro'>
645 <title>Installing the Toolchain</title> 215 <title>The Linux Distribution</title>
646 216
647 <para> 217 <para>
648 You can download a tarball installer, which includes the 218 The Yocto Project team verifies each release against recent
649 pre-built toolchain, the <filename>runqemu</filename> 219 versions of the most popular Linux distributions that
650 script, and support files from the appropriate directory under 220 provide stable releases.
651 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. 221 In general, if you have the current release minus one of the
652 Toolchains are available for 32-bit and 64-bit x86 development 222 following distributions, you should have no problems.
653 systems from the <filename>i686</filename> and 223 <itemizedlist>
654 <filename>x86_64</filename> directories, respectively. 224 <listitem><para>
655 The toolchains the Yocto Project provides are based off the 225 Ubuntu
656 <filename>core-image-sato</filename> image and contain 226 </para></listitem>
657 libraries appropriate for developing against that image. 227 <listitem><para>
658 Each type of development system supports five or more target 228 Fedora
659 architectures. 229 </para></listitem>
230 <listitem><para>
231 openSUSE
232 </para></listitem>
233 <listitem><para>
234 CentOS
235 </para></listitem>
236 <listitem><para>
237 Debian
238 </para></listitem>
239 </itemizedlist>
240 For a more detailed list of distributions that support the
241 Yocto Project, see the
242 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
243 section in the Yocto Project Reference Manual.
660 </para> 244 </para>
661 245
662 <para> 246 <para>
663 The names of the tarball installer scripts are such that a 247 The OpenEmbedded build system should be able to run on any
664 string representing the host system appears first in the 248 modern distribution that has the following versions for
665 filename and then is immediately followed by a string 249 Git, tar, and Python.
666 representing the target architecture. 250 <itemizedlist>
667 </para> 251 <listitem><para>
668 252 Git 1.7.8 or greater
669 <literallayout class='monospaced'> 253 </para></listitem>
670 poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh 254 <listitem><para>
671 255 tar 1.24 or greater
672 Where: 256 </para></listitem>
673 <replaceable>host_system</replaceable> is a string representing your development system: 257 <listitem><para>
674 258 Python 2.7.3 or greater excluding Python
675 i686 or x86_64. 259 3.x, which is not supported.
676 260 </para></listitem>
677 <replaceable>image_type</replaceable> is a string representing the image you wish to 261 </itemizedlist>
678 develop a Software Development Toolkit (SDK) for use against. 262 If your build host does not meet any of these three listed
679 The Yocto Project builds toolchain installers using the 263 version requirements, you can take steps to prepare the
680 following BitBake command: 264 system so that you can still use the Yocto Project.
681 265 See the
682 bitbake core-image-sato -c populate_sdk 266 "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>"
683 267 section in the Yocto Project Reference Manual for information.
684 <replaceable>arch</replaceable> is a string representing the tuned target architecture:
685
686 i586, x86_64, powerpc, mips, armv7a or armv5te
687
688 <replaceable>release_version</replaceable> is a string representing the release number of the
689 Yocto Project:
690
691 &DISTRO;, &DISTRO;+snapshot
692 </literallayout>
693
694 <para>
695 For example, the following toolchain installer is for a 64-bit
696 development host system and a i586-tuned target architecture
697 based off the SDK for <filename>core-image-sato</filename>:
698 <literallayout class='monospaced'>
699 poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
700 </literallayout>
701 </para> 268 </para>
269 </section>
702 270
703 <para> 271 <section id='packages'>
704 Toolchains are self-contained and by default are installed into 272 <title>The Build Host Packages</title>
705 <filename>/opt/poky</filename>.
706 However, when you run the toolchain installer, you can choose an
707 installation directory.
708 </para>
709 273
710 <para> 274 <para>
711 The following command shows how to run the installer given a toolchain tarball 275 Required build host packages vary depending on your
712 for a 64-bit x86 development host system and a 32-bit x86 target architecture. 276 build machine and what you want to do with the Yocto Project.
713 You must change the permissions on the toolchain 277 For example, if you want to build an image that can run
714 installer script so that it is executable. 278 on QEMU in graphical mode (a minimal, basic build
279 requirement), then the build host package requirements
280 are different than if you want to build an image on a headless
281 system or build out the Yocto Project documentation set.
715 </para> 282 </para>
716 283
717 <para> 284 <para>
718 The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>. 285 Collectively, the number of required packages is large
286 if you want to be able to cover all cases.
719 <note> 287 <note>
720 If you do not have write permissions for the directory into which you are installing 288 In general, you need to have root access and then install
721 the toolchain, the toolchain installer notifies you and exits. 289 the required packages.
722 Be sure you have write permissions in the directory and run the installer again. 290 Thus, the commands in the following section may or may
291 not work depending on whether or not your Linux
292 distribution has <filename>sudo</filename> installed.
723 </note> 293 </note>
724 </para> 294 </para>
725 295
726 <para> 296 <para>
727 <literallayout class='monospaced'> 297 The following list shows the required packages needed to build
728 $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh 298 an image that runs on QEMU in graphical mode (e.g. essential
729 </literallayout> 299 plus graphics support).
730 </para> 300 For lists of required packages for other scenarios, see the
731 301 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
732 <para> 302 section in the Yocto Project Reference Manual.
733 For more information on how to install tarballs, see the 303 <itemizedlist>
734 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and 304 <listitem><para><emphasis>Ubuntu and Debian</emphasis>
735 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" sections in the Yocto Project Application Developer's Guide. 305 <literallayout class='monospaced'>
736 </para> 306 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm
737 </section> 307 </literallayout>
738 308 </para></listitem>
739 <section id='downloading-the-pre-built-linux-kernel'> 309 <listitem><para><emphasis>Fedora</emphasis>
740 <title>Downloading the Pre-Built Linux Kernel</title> 310 <literallayout class='monospaced'>
741 311 $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
742 <para> 312 </literallayout>
743 You can download the pre-built Linux kernel suitable for running in the QEMU emulator from 313 </para></listitem>
744 <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>. 314 <listitem><para><emphasis>OpenSUSE</emphasis>
745 Be sure to use the kernel that matches the architecture you want to simulate. 315 <literallayout class='monospaced'>
746 Download areas exist for the five supported machine architectures: 316 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; libSDL-devel xterm
747 <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>, 317 </literallayout>
748 <filename>qemux86</filename>, and <filename>qemux86-64</filename>. 318 </para></listitem>
749 </para> 319 <listitem><para><emphasis>CentOS</emphasis>
750 320 <literallayout class='monospaced'>
751 <para> 321 $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
752 Most kernel files have one of the following forms: 322 </literallayout>
753 <literallayout class='monospaced'> 323 <note>
754 *zImage-qemu<replaceable>arch</replaceable>.bin 324 CentOS 6.x users need to ensure that the required
755 vmlinux-qemu<replaceable>arch</replaceable>.bin 325 versions of Git, tar and Python are available.
756 326 For details, See the
757 Where: 327 "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>"
758 <replaceable>arch</replaceable> is a string representing the target architecture: 328 section in the Yocto Project Reference Manual for
759 x86, x86-64, ppc, mips, or arm. 329 information.
760 </literallayout> 330 </note>
761 </para> 331 </para></listitem>
762 332 </itemizedlist>
763 <para>
764 You can learn more about downloading a Yocto Project kernel in the
765 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>"
766 bulleted item in the Yocto Project Development Manual.
767 </para>
768 </section>
769
770 <section id='downloading-the-filesystem'>
771 <title>Downloading the Filesystem</title>
772
773 <para>
774 You can also download the filesystem image suitable for your target architecture from
775 <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.
776 Again, be sure to use the filesystem that matches the architecture you want
777 to simulate.
778 </para>
779
780 <para>
781 The filesystem image has two tarball forms: <filename>ext3</filename> and
782 <filename>tar</filename>.
783 You must use the <filename>ext3</filename> form when booting an image using the
784 QEMU emulator.
785 The <filename>tar</filename> form can be flattened out in your host development system
786 and used for build purposes with the Yocto Project.
787 <literallayout class='monospaced'>
788 core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.ext3
789 core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.tar.bz2
790
791 Where:
792 <replaceable>profile</replaceable> is the filesystem image's profile:
793 lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato,
794 sato-dev, or sato-sdk. For information on these types of image
795 profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
796 chapter in the Yocto Project Reference Manual.
797
798 <replaceable>arch</replaceable> is a string representing the target architecture:
799 x86, x86-64, ppc, mips, or arm.
800 </literallayout>
801 </para> 333 </para>
802 </section> 334 </section>
803 335
804 <section id='setting-up-the-environment-and-starting-the-qemu-emulator'> 336 <section id='releases'>
805 <title>Setting Up the Environment and Starting the QEMU Emulator</title> 337 <title>Yocto Project Release</title>
806
807 <para>
808 Before you start the QEMU emulator, you need to set up the emulation environment.
809 The following command form sets up the emulation environment.
810 <literallayout class='monospaced'>
811 $ source &YOCTO_ADTPATH_DIR;/environment-setup-<replaceable>arch</replaceable>-poky-linux-<replaceable>if</replaceable>
812
813 Where:
814 <replaceable>arch</replaceable> is a string representing the target architecture:
815 i586, x86_64, ppc603e, mips, or armv5te.
816
817 <replaceable>if</replaceable> is a string representing an embedded application binary interface.
818 Not all setup scripts include this string.
819 </literallayout>
820 </para>
821 338
822 <para> 339 <para>
823 Finally, this command form invokes the QEMU emulator 340 The last requirement you need to meet before using the
824 <literallayout class='monospaced'> 341 Yocto Project is getting a Yocto Project release.
825 $ runqemu <replaceable>qemuarch</replaceable> <replaceable>kernel-image</replaceable> <replaceable>filesystem-image</replaceable> 342 It is recommended that you get the latest Yocto Project release
826 343 by setting up (cloning in
827 Where: 344 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> terms) a
828 <replaceable>qemuarch</replaceable> is a string representing the target architecture: qemux86, qemux86-64, 345 local copy of the <filename>poky</filename> Git repository on
829 qemuppc, qemumips, or qemuarm. 346 your build host and then checking out the latest release.
830 347 Doing so allows you to easily update to newer Yocto Project
831 <replaceable>kernel-image</replaceable> is the architecture-specific kernel image. 348 releases as well as contribute back to the Yocto Project.
832
833 <replaceable>filesystem-image</replaceable> is the .ext3 filesystem image.
834
835 </literallayout>
836 </para> 349 </para>
837 350
838 <para> 351 <para>
839 Continuing with the example, the following two commands setup the emulation 352 Here is an example from an Ubuntu build host that clones the
840 environment and launch QEMU. 353 <filename>poky</filename> repository and then checks out the
841 This example assumes the root filesystem (<filename>.ext3</filename> file) and 354 latest Yocto Project Release (i.e. &DISTRO;):
842 the pre-built kernel image file both reside in your home directory.
843 The kernel and filesystem are for a 32-bit target architecture.
844 <literallayout class='monospaced'> 355 <literallayout class='monospaced'>
845 $ cd $HOME 356 $ git clone git://git.yoctoproject.org/poky
846 $ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux 357 Cloning into 'poky'...
847 $ runqemu qemux86 bzImage-qemux86.bin \ 358 remote: Counting objects: 226790, done.
848 core-image-sato-qemux86.ext3 359 remote: Compressing objects: 100% (57465/57465), done.
360 remote: Total 226790 (delta 165212), reused 225887 (delta 164327)
361 Receiving objects: 100% (226790/226790), 100.98 MiB | 263 KiB/s, done.
362 Resolving deltas: 100% (165212/165212), done.
363 $ git checkout &DISTRO_NAME;
849 </literallayout> 364 </literallayout>
365 You can also get the Yocto Project Files by downloading
366 Yocto Project releases from the
367 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
850 </para> 368 </para>
851 369
852 <para> 370 <para>
853 The environment in which QEMU launches varies depending on the filesystem image and on the 371 For more information on getting set up with the Yocto Project
854 target architecture. 372 release, see the
855 For example, if you source the environment for the ARM target 373 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-yp-release'>Yocto Project Release</ulink>"
856 architecture and then boot the minimal QEMU image, the emulator comes up in a new 374 item in the Yocto Project Development Manual.
857 shell in command-line mode.
858 However, if you boot the SDK image, QEMU comes up with a GUI.
859 <note>Booting the PPC image results in QEMU launching in the same shell in
860 command-line mode.</note>
861 </para> 375 </para>
862 </section> 376 </section>
863 </section> 377 </section>
864 378
865 <para> 379 <section id='qs-building-images'>
866 For more detailed information on using the Yocto Project for 380 <title>Building Images</title>
867 image and application develop, the best place to continue reading is
868 in the
869 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>.
870 </para>
871</section>
872 381
873<section id='super-user'> 382 <para>
874 <title>Super User 383 Now that you have your system requirements in order, you can give
875</title> 384 the Yocto Project a try.
876 385 This section presents steps that let you do the following:
877 <para> 386 <itemizedlist>
878 This section provides minimal instruction for using the Yocto Project 387 <listitem><para>
879 to build an image for Beaglebone hardware and for building and 388 Build a <filename>qemux86</filename> reference image
880 booting an image for the third-party 389 and run it in the QEMU emulator.
881 <ulink url='http://www.minnowboard.org/meet-minnowboard-max/'>MinnowBoard MAX</ulink>. 390 </para></listitem>
882 <note> 391 <listitem><para>
883 The steps used in this section were performed on a 64-bit 392 Easily change configurations so that you can quickly
884 Ubuntu 14.10 system that has four cores. 393 create a second image, which would be for MinnowBoard
885 </note> 394 MAX-compatible boards.
886 </para> 395 </para></listitem>
887 396 </itemizedlist>
888 <section id='building-beaglebone-from-scratch'> 397 <note>
889 <title>Building Beaglebone from Scratch</title> 398 The steps in this section do not provide detail, but rather
399 provide minimal, working commands and examples designed to
400 just get you started.
401 For more details, see the appropriate manuals in the
402 <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project manual set</ulink>.
403 </note>
404 </para>
890 405
891 <para> 406 <para>
892 This section 407 Use the following commands to build your image.
893 <footnote> 408 The OpenEmbedded build system creates an entire Linux
409 distribution, including the toolchain, from source.
410 <note><title>Note about Network Proxies</title>
894 <para> 411 <para>
895 Kudos and thanks to Robert P. J. Day of 412 By default, the build process searches for source code
896 <ulink url='http://www.crashcourse.ca'>CrashCourse</ulink> 413 using a pre-determined order through a set of
897 for providing the basis for this "expert" section with 414 locations.
898 information from one of his 415 If you are working behind a firewall and your build
899 <ulink url='http://www.crashcourse.ca/wiki/index.php/Yocto_Project_Quick_Start'>wiki</ulink> 416 host is not set up for proxies, you could encounter
900 pages. 417 problems with the build process when fetching source
418 code (e.g. fetcher failures or Git failures).
901 </para> 419 </para>
902 </footnote>
903 gives you a minimal description of how to use the Yocto Project to
904 build images for Beaglebone hardware starting from scratch.
905 </para>
906 420
907 <section id='getting-yocto'> 421 <para>
908 <title>Getting the Yocto Project</title> 422 If you do not know your proxy settings, consult your
423 local network infrastructure resources and get that
424 information.
425 A good starting point could also be to check your web
426 browser settings.
427 Finally, you can find more information on using the
428 Yocto Project behind a firewall in the Yocto Project
429 Reference Manual
430 <ulink url='&YOCTO_DOCS_REF_URL;#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</ulink>
431 and on the
432 "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
433 wiki page.
434 </para>
435 </note>
436 </para>
909 437
910 <para> 438 <para>
911 Set up your 439 <orderedlist>
912 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> 440 <listitem><para><emphasis>Be Sure Your Build Host is Set Up:</emphasis>
913 by using Git to clone the <filename>poky</filename> 441 The steps to build an image in this section depend on
914 repository and then check out the release branch: 442 your build host being properly set up.
915 <literallayout class='monospaced'> 443 Be sure you have worked through the requirements
916 $ cd ~ 444 described in the
917 $ git clone git://git.yoctoproject.org/poky 445 "<link linkend='yp-resources'>Setting Up to Use the Yocto Project</link>"
918 $ cd poky 446 section.
447 </para></listitem>
448 <listitem><para><emphasis>Check Out Your Branch:</emphasis>
449 Be sure you are in the
450 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
451 (e.g. <filename>poky</filename>) and then check out
452 the branch associated with the latest Yocto Project
453 Release:
454 <literallayout class='monospaced'>
455 $ cd ~/poky
919 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; 456 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
920 </literallayout> 457 </literallayout>
921 </para> 458 Git's <filename>checkout</filename> command checks out
922 </section> 459 the current Yocto Project release into a local branch
923 460 whose name matches the release (i.e.
924 <section id='setting-up-your-host'> 461 <filename>&DISTRO_NAME;</filename>).
925 <title>Setting Up Your Host</title> 462 The local branch tracks the upstream branch of the
926 463 same name.
927 <para> 464 Creating your own branch based on the released
928 You need some packages for everything to work. 465 branch ensures you are using the latest files for
929 Rather than duplicate them here, look at the 466 that release.
930 "<link linkend='packages'>The Packages</link>" 467 </para></listitem>
931 section earlier in this quick start. 468 <listitem><para><emphasis>Initialize the Build Environment:</emphasis>
932 </para> 469 Run the
933 </section> 470 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
934 471 environment setup script to define the OpenEmbedded
935 <section id='initializing-the-build-environment'> 472 build environment on your build host.
936 <title>Initializing the Build Environment</title> 473 <literallayout class='monospaced'>
937 474 $ source &OE_INIT_FILE;
938 <para> 475 </literallayout>
939 From the root directory of your 476 Among other things, the script creates the
940 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, 477 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
941 initialize your environment and provide a meaningful 478 which is <filename>build</filename> in this case
942 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 479 and is located in the
943 name: 480 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
944 <literallayout class='monospaced'> 481 After the script runs, your current working directory
945 $ source &OE_INIT_FILE; mybuilds 482 is set to the Build Directory.
946 </literallayout> 483 Later, when the build completes, the Build Directory
947 At this point, the <filename>mybuilds</filename> directory has 484 contains all the files created during the build.
948 been created for you and it is now your current working directory. 485 <note>
949 If you do not provide your own directory name, 486 For information on running a memory-resident
950 it defaults to <filename>build</filename>, 487 <ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>,
951 which is inside the Source Directory. 488 see the
952 </para> 489 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
953 </section> 490 setup script.
954 491 </note>
955 <section id='configuring-the-local.conf-file'> 492 </para></listitem>
956 <title>Configuring the local.conf File</title> 493 <listitem><para><emphasis>Examine Your Local Configuration File:</emphasis>
957 494 When you set up the build environment, a local
958 <para> 495 configuration file named
959 Initializing the build environment creates a 496 <filename>local.conf</filename> becomes available in
960 <filename>conf/local.conf</filename> configuration file 497 a <filename>conf</filename> subdirectory of the
961 in the Build Directory. 498 Build Directory.
962 You need to manually edit this file to specify the machine you 499 Before using BitBake to start the build, you can
963 are building: 500 look at this file and be sure your general
964 <literallayout class='monospaced'> 501 configurations are how you want them:
965 MACHINE ?= "beaglebone" 502 <itemizedlist>
966 </literallayout> 503 <listitem><para>
967 </para> 504 To help conserve disk space during builds,
968 505 you can add the following statement to your
969 <para> 506 project's configuration file, which for this
970 A good deal that goes into a Yocto Project build is simply 507 example is
971 downloading all of the source tarballs. 508 <filename>poky/build/conf/local.conf</filename>.
972 Steps exist that can help you be more efficient with gathering 509 Adding this statement deletes the work
973 source files. 510 directory used for building a recipe once the
974 For example, you can set up local mirrors that hold your 511 recipe is built.
975 source tarballs or you can pre-fetch all your source without 512 <literallayout class='monospaced'>
976 initiating a build until later. 513 INHERIT += "rm_work"
977 For more information, see the 514 </literallayout>
978 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-source-files'>Working with Source Files</ulink>" 515 </para></listitem>
979 section in the Yocto Project Development Manual. 516 <listitem><para>
980 </para> 517 By default, the target machine for the build is
981 </section> 518 <filename>qemux86</filename>,
982 519 which produces an image that can be used in
983 <section id='building-the-image'> 520 the QEMU emulator and is targeted at an
984 <title>Building the Image</title> 521 <trademark class='registered'>Intel</trademark>
985 522 32-bit based architecture.
986 <para> 523 Further on in this example, this default is
987 At this point, you need to select an image to build for the 524 easily changed through the
988 Beaglebone hardware. 525 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
989 If this is your first build using the Yocto Project, you should 526 variable so that you can quickly
990 try the smallest and simplest image: 527 build an image for a different machine.
991 <literallayout class='monospaced'> 528 </para></listitem>
992 $ bitbake core-image-minimal 529 <listitem><para>
993 </literallayout> 530 Another consideration before you build is the
994 Now you just wait for the build to finish. 531 package manager used when creating the image.
995 </para> 532 The default <filename>local.conf</filename>
996 533 file selects the RPM package manager.
997 <para> 534 You can control this configuration by using the
998 You might encounter various warning messages during the 535 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink></filename>
999 build. 536 variable.</para>
1000 For example, if a source file fetch initially fails, 537 <para>Selection of the package manager is separate
1001 the OpenEmbedded build system notes that and attempts to 538 from whether package management is used at runtime
1002 find the files using mirrors. 539 in the target image.</para>
1003 Another example could be values requested for but not 540 <para>For additional package manager selection
1004 found in the final kernel <filename>.config</filename> 541 information, see the
1005 file. 542 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package*.bbclass</filename></ulink>"
1006 For information on configuration warnings, see the 543 section in the Yocto Project Reference Manual.
1007 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>" 544 </para></listitem>
1008 section in the Yocto Project Linux Kernel Development Manual. 545 </itemizedlist>
1009 </para> 546 </para></listitem>
1010 547 <listitem><para><emphasis>Start the Build:</emphasis>
1011 <para> 548 Continue with the following command to build an OS image
1012 By default, BitBake aborts when it encounters an error during 549 for the target, which is
1013 the build. 550 <filename>core-image-sato</filename> in this example:
1014 If you want to make sure the build continues even when BitBake 551 <note>
1015 encounters an error, use this variation: 552 Depending on the number of processors and cores, the
1016 <literallayout class='monospaced'> 553 amount of RAM, the speed of your Internet connection
1017 $ bitbake -k core-image-minimal 554 and other factors, the build process could take several
1018 </literallayout> 555 hours the first time you run it.
1019 </para> 556 Subsequent builds run much faster since parts of the
1020 557 build are cached.
1021 <para> 558 </note>
1022 Once you have your image, you can take steps to load and boot 559 <literallayout class='monospaced'>
1023 it on the target hardware. 560 $ bitbake core-image-sato
1024 </para> 561 </literallayout>
1025 562 For information on using the
1026 <para> 563 <filename>bitbake</filename> command, see the
1027 You can learn about BitBake in general by reading the 564 "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>"
1028 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. 565 section in the Yocto Project Reference Manual, or see the
1029 </para> 566 "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>"
1030 </section> 567 section in the BitBake User Manual.
1031 </section> 568 For information on other targets, see the
1032 569 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
1033 <section id='building-and-booting-minnowboard-max'> 570 chapter in the Yocto Project Reference Manual.
1034 <title>Building and Booting MinnowBoard MAX</title> 571 </para></listitem>
572 <listitem><para><emphasis>Simulate Your Image Using QEMU:</emphasis>
573 Once this particular image is built, you can start QEMU
574 and run the image:
575 <literallayout class='monospaced'>
576 $ runqemu qemux86
577 </literallayout>
578 If you want to learn more about running QEMU, see the
579 "<ulink url="&YOCTO_DOCS_DEV_URL;#dev-manual-qemu">Using the Quick EMUlator (QEMU)</ulink>"
580 chapter in the Yocto Project Development Manual.
581 </para></listitem>
582 <listitem><para><emphasis>Exit QEMU:</emphasis>
583 Exit QEMU by either clicking on the shutdown icon or by
584 opening a terminal, typing
585 <filename>poweroff</filename>, and then pressing "Enter".
586 </para></listitem>
587 </orderedlist>
588 </para>
1035 589
1036 <para> 590 <para>
1037 As of the Yocto Project 1.6 release, the MinnowBoard MAX is 591 The following steps show how easy it is to set up to build an
592 image for a new machine.
593 These steps build an image for the MinnowBoard MAX, which is
1038 supported by the Yocto Project and the 594 supported by the Yocto Project and the
1039 <filename>meta-intel</filename> 595 <filename>meta-intel</filename> <filename>intel-corei7-64</filename>
1040 <filename>intel-corei7-64</filename> and 596 and <filename>intel-core2-32</filename> Board Support Packages
1041 <filename>intel-core2-32</filename> Board Support Packages (BSPs). 597 (BSPs).
1042 <note> 598 <note>
1043 The MinnowBoard MAX ships with 64-bit firmware. 599 The MinnowBoard MAX ships with 64-bit firmware.
1044 If you want to use the board in 32-bit mode, you must 600 If you want to use the board in 32-bit mode, you must
@@ -1047,78 +603,46 @@
1047 </note> 603 </note>
1048 </para> 604 </para>
1049 605
1050 <section id='mm-getting-yocto-and-meta-intel'> 606 <para>
1051 <title>Getting the Yocto Project and <filename>meta-intel</filename></title> 607 <orderedlist>
1052 608 <listitem><para><emphasis>Create a Local Copy of the
1053 <para> 609 <filename>meta-intel</filename> Repository:</emphasis>
1054 Set up your 610 Building an image for the MinnowBoard MAX requires the
1055 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> 611 <filename>meta-intel</filename> layer.
1056 and the <filename>meta-intel</filename> layer 612 Use the <filename>git clone</filename> command to create
1057 by using Git to clone the <filename>poky</filename> 613 a local copy of the repository:
1058 and <filename>meta-intel</filename> repositories. 614 <literallayout class='monospaced'>
1059 These commands use the "&DISTRO_NAME;" branch: 615 $ git clone git://git.yoctoproject.org/meta-intel
1060 <literallayout class='monospaced'> 616 Cloning into 'meta-intel'...
1061 $ cd ~ 617 remote: Counting objects: 10824, done.
1062 $ mkdir source 618 remote: Compressing objects: 100% (3508/3508), done.
1063 $ cd source 619 remote: Total 10824 (delta 6219), reused 10580 (delta 5975)
1064 $ git clone -b &DISTRO_NAME; git://git.yoctoproject.org/poky 620 Receiving objects: 100% (10824/10824), 2.72 MiB | 482.00 KiB/s, done.
1065 $ cd poky 621 Resolving deltas: 100% (6219/6219), done.
1066 $ git clone -b &DISTRO_NAME; git://git.yoctoproject.org/meta-intel 622 Checking connectivity... done.
1067 </literallayout> 623 </literallayout>
1068 </para> 624 </para></listitem>
1069 </section> 625 <listitem><para><emphasis>Configure the Build:</emphasis>
1070 626 To configure the build, you edit the
1071 <section id='mm-setting-up-your-host'> 627 <filename>bblayers.conf</filename> and
1072 <title>Setting Up Your Host</title> 628 <filename>local.conf</filename> files, both of which are
1073 629 located in the <filename>build/conf</filename> directory.
1074 <para> 630 </para>
1075 You need some packages for everything to work.
1076 Rather than duplicate them here, look at the
1077 "<link linkend='packages'>The Packages</link>"
1078 section earlier in this quick start.
1079 </para>
1080 </section>
1081
1082 <section id='mm-initializing-the-build-environment'>
1083 <title>Initializing the Build Environment</title>
1084
1085 <para>
1086 From the root directory of your
1087 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
1088 initialize your environment by running the build environment
1089 initialization script:
1090 <literallayout class='monospaced'>
1091 $ source &OE_INIT_FILE;
1092 </literallayout>
1093 At this point, the <filename>build</filename> directory has
1094 been created for you and it is now your current working
1095 directory.
1096 </para>
1097 </section>
1098
1099 <section id='mm-configure-the-build'>
1100 <title>Configure the Build</title>
1101
1102 <para>
1103 To configure the build, you edit the
1104 <filename>bblayers.conf</filename> and
1105 <filename>local.conf</filename> files, both of which are
1106 located in the <filename>build/conf</filename> directory.
1107 </para>
1108 631
1109 <para> 632 <para>Here is a quick way to make the edits.
1110 Here is a quick way to make the edits. 633 The first command uses the
1111 The first command adds the <filename>meta-intel</filename> 634 <filename>bitbake-layers add-layer</filename> command
1112 branch, which contains the <filename>intel-core*</filename> 635 to add the <filename>meta-intel</filename>
1113 BSPs to the build. 636 layer, which contains the <filename>intel-core*</filename>
1114 The second command selects the BSP by setting the 637 BSPs to the build.
1115 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> 638 The second command selects the BSP by setting the
1116 variable. 639 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
1117 <literallayout class='monospaced'> 640 variable.
1118 $ echo 'BBLAYERS += "~/source/poky/meta-intel"' >> conf/bblayers.conf 641 <literallayout class='monospaced'>
642 $ bitbake-layers add-layer "$HOME/source/poky/meta-intel"
1119 $ echo 'MACHINE = "intel-corei7-64"' >> conf/local.conf 643 $ echo 'MACHINE = "intel-corei7-64"' >> conf/local.conf
1120 </literallayout> 644 </literallayout>
1121 <note><title>Notes</title> 645 <note><title>Notes</title>
1122 <para> 646 <para>
1123 If you want a 64-bit build, use the following: 647 If you want a 64-bit build, use the following:
1124 <literallayout class='monospaced'> 648 <literallayout class='monospaced'>
@@ -1132,98 +656,139 @@
1132 $ echo 'MACHINE = "intel-core2-32"' >> conf/local.conf 656 $ echo 'MACHINE = "intel-core2-32"' >> conf/local.conf
1133 </literallayout> 657 </literallayout>
1134 </para> 658 </para>
1135 </note> 659 </note>
1136 </para> 660 </para></listitem>
1137 </section> 661 <listitem><para><emphasis>Build a Minimal Image for MinnowBoard MAX:</emphasis>
1138 662 Use the following command to build the minimal image for
1139 <section id='mm-build-the-image'> 663 MinnowBoard MAX.
1140 <title>Build the Image</title> 664 Because configuration changes are minimal to set up for
1141 665 this second build, the OpenEmbedded build system can
1142 <para> 666 re-use files from previous builds as much as possible.
1143 Use this command to build the minimal image for 667 Re-using files means this second build will be much faster
1144 MinnowBoard MAX: 668 than an initial build.
1145 <literallayout class='monospaced'> 669 <literallayout class='monospaced'>
1146 $ bitbake core-image-minimal 670 $ bitbake core-image-minimal
1147 </literallayout> 671 </literallayout>
1148 Once the build completes, the resulting basic console image 672 Once the build completes, the resulting basic console image
1149 is located in the Build Directory here: 673 is located in the Build Directory here:
1150 <literallayout class='monospaced'> 674 <literallayout class='monospaced'>
1151 tmp/deploy/images/intel-corei7-64/core-image-minimal-intel-corei7-64.hddimg 675 tmp/deploy/images/intel-corei7-64/core-image-minimal-intel-corei7-64.hddimg
1152 </literallayout> 676 </literallayout>
1153 </para> 677 </para></listitem>
1154 </section> 678 <listitem><para><emphasis>Write the Image:</emphasis>
1155 679 You can write the image to a USB key, SATA drive, or SD
1156 <section id='mm-write-the-image'> 680 card by using the <filename>mkefidisk.sh</filename> script,
1157 <title>Write the Image</title> 681 which is included in the <filename>poky</filename>
1158 682 repository at
1159 <para> 683 <filename>scripts/contrib/mkefidisk.sh</filename>:
1160 You can write the image to a USB key, SATA drive, or SD card 684 <literallayout class='monospaced'>
1161 by using the <filename>mkefidisk.sh</filename> script,
1162 which is included in the <filename>poky</filename>
1163 repository at <filename>scripts/contrib/mkefidisk.sh</filename>:
1164 <literallayout class='monospaced'>
1165 $ sudo $HOME/source/poky/scripts/contrib/mkefidisk.sh <replaceable>HOST_DEVICE</replaceable> \ 685 $ sudo $HOME/source/poky/scripts/contrib/mkefidisk.sh <replaceable>HOST_DEVICE</replaceable> \
1166 tmp/deploy/images/intel-corei7-64/core-image-minimal-intel-corei7-64.hddimg <replaceable>TARGET_DEVICE</replaceable> 686 tmp/deploy/images/intel-corei7-64/core-image-minimal-intel-corei7-64.hddimg <replaceable>TARGET_DEVICE</replaceable>
1167 </literallayout> 687 </literallayout>
1168 In the previous command, <replaceable>HOST_DEVICE</replaceable> 688 In the previous command,
1169 is the device node on the build system (e.g. 689 <replaceable>HOST_DEVICE</replaceable> is the device node
1170 <filename>/dev/sdc</filename> or 690 on the build host (e.g. <filename>/dev/sdc</filename> or
1171 <filename>/dev/mmcblk0</filename>). 691 <filename>/dev/mmcblk0</filename>).
1172 <replaceable>TARGET_DEVICE</replaceable> is the name of the 692 <replaceable>TARGET_DEVICE</replaceable> is the name of the
1173 device as the MinnowBoard MAX sees it (e.g. 693 device as the MinnowBoard MAX sees it (e.g.
1174 <filename>/dev/sda</filename> or 694 <filename>/dev/sda</filename> or
1175 <filename>/dev/mmcblk0</filename>). 695 <filename>/dev/mmcblk0</filename>).
1176 </para> 696 </para></listitem>
1177 </section> 697 <listitem><para><emphasis>Boot the Hardware:</emphasis>
1178 698 With the boot device provisioned, you can insert the
1179 <section id='mm-boot-the-image'> 699 media into the MinnowBoard MAX and boot the hardware.
1180 <title>Boot the Image</title> 700 The board should automatically detect the media and boot to
1181 701 the bootloader and subsequently the operating system.
1182 <para> 702 </para>
1183 With the boot device provisioned, you can insert the media into
1184 the MinnowBoard MAX and boot the hardware.
1185 The board should automatically detect the media and boot to
1186 the bootloader and subsequently the operating system.
1187 </para>
1188 703
1189 <para> 704 <para>If the board does not boot automatically, you can
1190 If the board does not boot automatically, you can boot it 705 boot it manually from the EFI shell as follows:
1191 manually from the EFI shell as follows: 706 <literallayout class='monospaced'>
1192 <literallayout class='monospaced'>
1193 Shell> connect -r 707 Shell> connect -r
1194 Shell> map -r 708 Shell> map -r
1195 Shell> fs0: 709 Shell> fs0:
1196 Shell> bootx64 710 Shell> bootx64
1197 </literallayout>
1198 <note>
1199 For a 32-bit image use the following:
1200 <literallayout class='monospaced'>
1201 Shell> bootia32
1202 </literallayout> 711 </literallayout>
1203 </note> 712 <note>
1204 </para> 713 For a 32-bit image use the following:
1205 </section> 714 <literallayout class='monospaced'>
715 Shell> bootia32
716 </literallayout>
717 </note>
718 </para></listitem>
719 </orderedlist>
720 </para>
721 </section>
1206 722
1207 <section id='mm-next-steps'> 723 <section id='qs-next-steps'>
1208 <title>Next Steps</title> 724 <title>Next Steps</title>
1209 725
1210 <para> 726 <para>
1211 Now that you can build a basic image, you could experiment 727 If you completed all the steps in the previous section then
1212 by building some other example images: 728 congratulations to you!
1213 <literallayout class='monospaced'> 729 What now?
1214 $ bitbake core-image-sato 730 </para>
1215 $ bitbake core-image-sato-sdk
1216 </literallayout>
1217 Another possibility is to experiment creating your own image
1218 recipes that add packages to suit your needs.
1219 For information on how to create recipes, see the
1220 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe'>Writing a New Recipe</ulink>"
1221 section in the Yocto Project Development Manual.
1222 </para>
1223 </section>
1224 </section>
1225</section>
1226 731
732 <para>
733 Depending on what you primary interests are with the Yocto Project,
734 you could consider any of the following:
735 <itemizedlist>
736 <listitem><para><emphasis>Visit the Yocto Project Web Site:</emphasis>
737 The official
738 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink>
739 web site contains information on the entire project.
740 Visiting this site is a good way to familiarize yourself
741 with the overall project.
742 </para></listitem>
743 <listitem><para><emphasis>Explore Development Models:</emphasis>
744 You can see the
745 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-model'>Common Development Models</ulink>"
746 section in the Yocto Project Development Manual
747 to get an overview of the various ways by which
748 you can use the Yocto Project to develop projects.
749 </para></listitem>
750 <listitem><para><emphasis>Learn Some Open Source Basics:</emphasis>
751 If you are new to the open source environment, you might
752 read the
753 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-newbie'>The Yocto Project Open Source Development Environment</ulink>"
754 chapter of the Yocto Project Development Manual.
755 This chapter presents overview material for open source
756 development in the context of the Yocto Project.
757 </para></listitem>
758 <listitem><para><emphasis>Learn About Application Development:</emphasis>
759 If your primary interests lie in developing applications,
760 you can reference the
761 <ulink url='&YOCTO_DOCS_ADT_URL;#adt-manual-intro'>Yocto Project Application Developer's Guide</ulink>.
762 </para></listitem>
763 <listitem><para><emphasis>Learn About Board Support Packages (BSPs):</emphasis>
764 If you want to learn about BSPs, see the
765 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Yocto Project Board Support Packages (BSP) Developer's Guide</ulink>.
766 </para></listitem>
767 <listitem><para><emphasis>Learn About Using Eclipse With the Yocto Project:</emphasis>
768 If you are an Eclipse user, you can learn about using the
769 Yocto Project in that development environment by reading
770 the
771 "<ulink url='&YOCTO_DOCS_DEV_URL;#workflow-using-the-adt-and-eclipse'>Workflow Using the ADT and Eclipse™</ulink>"
772 section in the Yocto Project Development Manual.
773 </para></listitem>
774 <listitem><para><emphasis>Learn About Toaster:</emphasis>
775 Toaster is a web interface to the Yocto Project's
776 OpenEmbedded build system.
777 If you are interested in using this type of interface to
778 create images, see the
779 <ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-intro'>Toaster User Manual</ulink>.
780 </para></listitem>
781 <listitem><para><emphasis>Explore Yocto Project Common Tasks and Technical Details:</emphasis>
782 If you are interested in a mix of common tasks that have to
783 do with project develop using the Yocto Project, see the
784 "<ulink url='&YOCTO_DOCS_DEV_URL;#extendpoky'>Common Tasks</ulink>"
785 section of the Yocto Project Development Manual.
786 If you want more detail, see the
787 <ulink url='&YOCTO_DOCS_REF_URL;#ref-manual-intro'>Yocto Project Reference Manual</ulink>.
788 </para></listitem>
789 </itemizedlist>
790 </para>
791 </section>
1227</article> 792</article>
1228<!-- 793<!--
1229vim: expandtab tw=80 ts=4 794vim: expandtab tw=80 ts=4