summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-03-16 17:05:26 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-03-23 14:24:49 +0000
commitcb4b0aa3289e873f020d2758deb4982e7b40f7ad (patch)
treee43ea60194069da260e7887af014fdd96cb0affc
parent3b95307126a92f2ac8b940fa876ec5f170332ffd (diff)
downloadpoky-cb4b0aa3289e873f020d2758deb4982e7b40f7ad.tar.gz
documentation/yocto-project-qs/yocto-project-qs.xml: new expert section
Added a new "expert" section at the end of the QS. I reference the section right up front. This new section is an attempt to divert the expert user away from most of the QS. The information was formed from Robert P. J. Day's wiki at his crashcourse.com site. Reported-by: Robert P. J. Day <rpjday@crashcourse.ca> (From yocto-docs rev: b2981e9fcdd083e15194f520a4160938b02b1275) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/yocto-project-qs/yocto-project-qs.xml154
1 files changed, 154 insertions, 0 deletions
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index e7b83b2f64..785707fe5d 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -19,6 +19,15 @@
19 Amongst other things, the Yocto Project uses the Poky build system to 19 Amongst other things, the Yocto Project uses the Poky build system to
20 construct complete Linux images. 20 construct complete Linux images.
21 </para> 21 </para>
22
23 <para>
24 If you know all about open-source development, Linux development environments, Git source
25 repositories and the like and you just want some quick information that lets you try out
26 the Yocto Project, skip right to the "<link linkend='super-user'>Super User</link>" section at
27 the end of this quick start.
28 Otherwise, keep reading...
29 </para>
30
22 <para> 31 <para>
23 This short document will give you some basic information about the environment and 32 This short document will give you some basic information about the environment and
24 let you experience it in its simplest form. 33 let you experience it in its simplest form.
@@ -27,6 +36,7 @@
27 This document steps you through a simple example showing you how to build a small image 36 This document steps you through a simple example showing you how to build a small image
28 and run it using the QEMU emulator. 37 and run it using the QEMU emulator.
29 </para> 38 </para>
39
30 <para> 40 <para>
31 For more detailed information on the Yocto Project, you should check out these resources: 41 For more detailed information on the Yocto Project, you should check out these resources:
32 <itemizedlist> 42 <itemizedlist>
@@ -670,6 +680,150 @@
670 </section> 680 </section>
671</section> 681</section>
672 682
683<section id='super-user'>
684 <title>Super User
685</title>
686
687 <para>
688 This section
689 <footnote>
690 <para>
691 Kudos and thanks to Robert P. J. Day of
692 <ulink url='http://www.crashcourse.ca'>CrashCourse</ulink> for providing the basis
693 for this "expert" section with information from one of his
694 <ulink url='http://www.crashcourse.ca/wiki/index.php/Yocto_Project_Quick_Start'>wiki</ulink>
695 pages.
696 </para>
697 </footnote>
698 gives you a very fast description of how to use the Yocto Project to build images
699 for a BeagleBoard xM starting from scratch.
700 The steps were performed on a 64-bit Ubuntu 10.04 system.
701 </para>
702
703 <section id='getting-yocto'>
704 <title>Getting the Yocto Project</title>
705
706 <para>
707 Get the <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-files'>Yocto Project Files</ulink>
708 one of two ways:
709 <itemizedlist>
710 <listitem><para><emphasis>Tarball:</emphasis>
711 Use if you want the latest stable release:
712 <literallayout class='monospaced'>
713 $ wget &YOCTO_RELEASE_DL_URL;.&YOCTO_POKY_TARBALL;
714 $ tar xvjf &YOCTO_POKY_TARBALL;
715 </literallayout></para></listitem>
716 <listitem><para><emphasis>Git Repository:</emphasis>
717 Use if you want to work with cutting edge development content:
718 <literallayout class='monospaced'>
719 $ git clone &YOCTO_GIT_URL;.poky.git
720 </literallayout></para></listitem>
721 </itemizedlist>
722 The remainder of the section assumes the Git repository method.
723 </para>
724 </section>
725
726 <section id='setting-up-your-host'>
727 <title>Setting Up Your Host</title>
728
729 <para>
730 You need some packages for everything to work.
731 Rather than duplicate them here, look at the "<link linkend='packages'>The Packages</link>"
732 section earlier in this quick start.
733 </para>
734 </section>
735
736 <section id='initializing-the-build-environment'>
737 <title>Initializing the Build Environment</title>
738
739 <para>
740 From the parent directory of the Yocto Project Files, initialize your environment
741 and provide a meaningful
742 <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-build-directory'>Yocto Project Build Directory</ulink>
743 name:
744 <literallayout class='monospaced'>
745 $ source git/oe-init-build-env mybuilds
746 </literallayout>
747 At this point, the <filename>mybuilds</filename> directory has been created for you
748 and it is now your current working directory.
749 If you don't provide your own directory name it defaults to <filename>build</filename>.
750 </para>
751 </section>
752
753 <section id='configuring-the-local.conf-file'>
754 <title>Configuring the local.conf File</title>
755
756 <para>
757 Initializing the build environment creates a <filename>local.conf</filename> configuration file
758 in the build directory.
759 You need to manually edit this file to specify the machine you are building and to optimize
760 your build time.
761 Here are the minimal changes to make:
762 <literallayout class='monospaced'>
763 BB_NUMBER_THREADS = "8"
764 PARALLEL_MAKE = "-j 8"
765 MACHINE ?= "beagleboard"
766 </literallayout>
767 Briefly, set <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>
768 and <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> to
769 twice your host processor's number of cores.
770 </para>
771
772 <para>
773 A good deal that goes into a Yocto Project build is simply downloading all of the source
774 tarballs.
775 Maybe you have been working with another build system (OpenEmbedded, Angstrom, etc) for which
776 you've built up a sizable directory of source tarballs.
777 Or perhaps someone else has such a directory for which you have read access.
778 If so, you can save time by adding the <filename>PREMIRRORS</filename>
779 statement to your configuration file so that local directories are first checked for existing
780 tarballs before running out to the net:
781 <literallayout class='monospaced'>
782 PREMIRRORS_prepend = "\
783 git://.*/.* file:///home/you/dl/ \n \
784 svn://.*/.* file:///home/you/dl/ \n \
785 cvs://.*/.* file:///home/you/dl/ \n \
786 ftp://.*/.* file:///home/you/dl/ \n \
787 http://.*/.* file:///home/you/dl/ \n \
788 https://.*/.* file:///home/you/dl/ \n"
789 </literallayout>
790 </para>
791 </section>
792
793 <section id='building-the-image'>
794 <title>Building the Image</title>
795
796 <para>
797 At this point, you need to select an image to build for the BeagleBoard xM.
798 If this is your first build using the Yocto Project, you should try the smallest and simplest
799 image:
800 <literallayout class='monospaced'>
801 $ bitbake core-image-minimal
802 </literallayout>
803 Now you just wait for the build to finish.
804 </para>
805
806 <para>
807 Here are some variations on the build process that could be helpful:
808 <itemizedlist>
809 <listitem><para>Fetch all the necessary sources without starting the build:
810 <literallayout class='monospaced'>
811 $ bitbake -c fetchall core-image-minimal
812 </literallayout>
813 This variation guarantees that you have all the sources for that BitBake target
814 should you to disconnect from the net and want to do the build later offline.
815 </para></listitem>
816 <listitem><para>Specify to continue the build even if BitBake encounters an error.
817 By default, BitBake aborts the build when it encounters an error.
818 This command keeps a faulty build going:
819 <literallayout class='monospaced'>
820 $ bitbake -k core-image-minimal
821 </literallayout></para></listitem>
822 </itemizedlist>
823 </para>
824 </section>
825</section>
826
673</article> 827</article>
674<!-- 828<!--
675vim: expandtab tw=80 ts=4 829vim: expandtab tw=80 ts=4