diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2015-05-21 11:12:19 -0600 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2015-07-28 18:02:32 +0100 |
commit | ab23dd967e5a59de3cffe48762b4956edba5d478 (patch) | |
tree | d170bb0b1418a309fb12419ccd310c2f1634abf7 /documentation | |
parent | add1f737b8baa5aa258d967cb29810dbd636ad1a (diff) | |
download | poky-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')
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) | |||
147 | XSLTOPTS = --xinclude | 147 | XSLTOPTS = --xinclude |
148 | ALLPREQ = html eclipse tarball | 148 | ALLPREQ = html eclipse tarball |
149 | TARFILES = yocto-project-qs.html qs-style.css figures/yocto-environment.png \ | 149 | TARFILES = 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 |
153 | MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse | 152 | MANUALS = $(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 |
267 | MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse | 266 | MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse |
268 | FIGURES = figures | 267 | FIGURES = figures |
269 | STYLESHEET = $(DOC)/*.css | 268 | STYLESHEET = $(DOC)/*.css |
@@ -274,7 +273,8 @@ ifeq ($(DOC),adt-manual) | |||
274 | XSLTOPTS = --xinclude | 273 | XSLTOPTS = --xinclude |
275 | ALLPREQ = html eclipse tarball | 274 | ALLPREQ = html eclipse tarball |
276 | TARFILES = adt-manual.html adt-style.css figures/adt-title.png \ | 275 | TARFILES = adt-manual.html adt-style.css figures/adt-title.png \ |
277 | eclipse | 276 | figures/using-a-pre-built-image.png \ |
277 | eclipse | ||
278 | MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse | 278 | MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse |
279 | FIGURES = figures | 279 | FIGURES = figures |
280 | STYLESHEET = $(DOC)/*.css | 280 | STYLESHEET = $(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 | <!-- |
725 | vim: expandtab tw=80 ts=4 | 983 | vim: 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 | <!-- |
1229 | vim: expandtab tw=80 ts=4 | 794 | vim: expandtab tw=80 ts=4 |