summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/Makefile3
-rw-r--r--documentation/dev-manual/dev-manual-start.xml134
-rwxr-xr-xdocumentation/ref-manual/figures/building-an-image.pngbin14891 -> 0 bytes
-rw-r--r--documentation/ref-manual/usingpoky.xml141
4 files changed, 120 insertions, 158 deletions
diff --git a/documentation/Makefile b/documentation/Makefile
index e9ec914df9..c08d912302 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -214,7 +214,7 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \
214 figures/wip.png 214 figures/wip.png
215 else 215 else
216TARFILES = mega-manual.html mega-style.css \ 216TARFILES = mega-manual.html mega-style.css \
217 figures/building-an-image.png figures/YP-flow-diagram.png \ 217 figures/YP-flow-diagram.png \
218 figures/using-a-pre-built-image.png \ 218 figures/using-a-pre-built-image.png \
219 figures/poky-title.png figures/buildhistory.png \ 219 figures/poky-title.png figures/buildhistory.png \
220 figures/buildhistory-web.png \ 220 figures/buildhistory-web.png \
@@ -282,7 +282,6 @@ XSLTOPTS = --xinclude
282ALLPREQ = html eclipse tarball 282ALLPREQ = html eclipse tarball
283TARFILES = ref-manual.html ref-style.css figures/poky-title.png \ 283TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
284 figures/buildhistory.png figures/buildhistory-web.png \ 284 figures/buildhistory.png figures/buildhistory-web.png \
285 figures/building-an-image.png \
286 figures/build-workspace-directory.png \ 285 figures/build-workspace-directory.png \
287 eclipse 286 eclipse
288MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse 287MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 4c6c441fe0..dc30659159 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -701,13 +701,16 @@
701 </section> 701 </section>
702</section> 702</section>
703 703
704<section id='performing-a-simple-build'> 704<section id='dev-building-an-image'>
705 <title>Performing a Simple Build</title> 705 <title>Building an Image</title>
706 706
707 <para> 707 <para>
708 In the development environment, you need to build an image whenever
709 you change hardware support, add or change system libraries, or add
710 or change services that have dependencies.
708 Several methods exist that allow you to build an image within the 711 Several methods exist that allow you to build an image within the
709 Yocto Project. 712 Yocto Project.
710 This procedure shows how to build an image using BitBake from a 713 This section shows you how to build an image using BitBake from a
711 Linux host. 714 Linux host.
712 <note><title>Notes</title> 715 <note><title>Notes</title>
713 <itemizedlist> 716 <itemizedlist>
@@ -715,7 +718,7 @@
715 For information on how to build an image using 718 For information on how to build an image using
716 <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>, 719 <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>,
717 see the 720 see the
718 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>. 721 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster Manual</ulink>.
719 </para></listitem> 722 </para></listitem>
720 <listitem><para> 723 <listitem><para>
721 For information on how to use 724 For information on how to use
@@ -724,6 +727,12 @@
724 section in the Yocto Project Application Development and 727 section in the Yocto Project Application Development and
725 the Extensible Software Development Kit (eSDK) manual. 728 the Extensible Software Development Kit (eSDK) manual.
726 </para></listitem> 729 </para></listitem>
730 <listitem><para>
731 For a practical example on how to build an image using the
732 OpenEmbedded build system, see the
733 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
734 section of the Yocto Project Quick Start.
735 </para></listitem>
727 </itemizedlist> 736 </itemizedlist>
728 </note> 737 </note>
729 </para> 738 </para>
@@ -736,9 +745,6 @@
736 For detailed information on the build process using BitBake, see the 745 For detailed information on the build process using BitBake, see the
737 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#images-dev-environment'>Images</ulink>" 746 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#images-dev-environment'>Images</ulink>"
738 section in the Yocto Project Overview Manual. 747 section in the Yocto Project Overview Manual.
739 You can also reference the
740 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
741 section in the Yocto Project Quick Start.
742 </para> 748 </para>
743 749
744 <para> 750 <para>
@@ -757,14 +763,30 @@
757 <emphasis>Initialize the Build Environment:</emphasis> 763 <emphasis>Initialize the Build Environment:</emphasis>
758 Initialize the build environment by sourcing the build 764 Initialize the build environment by sourcing the build
759 environment script (i.e. 765 environment script (i.e.
760 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>). 766 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>):
767 <literallayout class='monospaced'>
768 $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>]
769 </literallayout></para>
770
771 <para>When you use the initialization script, the
772 OpenEmbedded build system uses <filename>build</filename> as
773 the default Build Directory in your current work directory.
774 You can use a <replaceable>build_dir</replaceable> argument
775 with the script to specify a different build directory.
776 <note><title>Tip</title>
777 A common practice is to use a different Build Directory for
778 different targets.
779 For example, <filename>~/build/x86</filename> for a
780 <filename>qemux86</filename> target, and
781 <filename>~/build/arm</filename> for a
782 <filename>qemuarm</filename> target.
783 </note>
761 </para></listitem> 784 </para></listitem>
762 <listitem><para> 785 <listitem><para>
763 <emphasis>Make Sure Your <filename>local.conf</filename> 786 <emphasis>Make Sure Your <filename>local.conf</filename>
764 File is Correct:</emphasis> 787 File is Correct:</emphasis>
765 Ensure the <filename>conf/local.conf</filename> configuration 788 Ensure the <filename>conf/local.conf</filename> configuration
766 file, which is found in the 789 file, which is found in the Build Directory,
767 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
768 is set up how you want it. 790 is set up how you want it.
769 This file defines many aspects of the build environment 791 This file defines many aspects of the build environment
770 including the target machine architecture through the 792 including the target machine architecture through the
@@ -772,18 +794,100 @@
772 the packaging format used during the build 794 the packaging format used during the build
773 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>), 795 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>),
774 and a centralized tarball download directory through the 796 and a centralized tarball download directory through the
775 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable. 797 <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> variable.
776 </para></listitem> 798 </para></listitem>
777 <listitem><para> 799 <listitem><para>
778 <emphasis>Build the Image:</emphasis> 800 <emphasis>Build the Image:</emphasis>
779 Build the image using the <filename>bitbake</filename> command. 801 Build the image using the <filename>bitbake</filename> command:
780 For example, the following command builds the 802 <literallayout class='monospaced'>
803 $ bitbake <replaceable>target</replaceable>
804 </literallayout>
805 <note>
806 For information on BitBake, see the
807 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
808 </note>
809 The <replaceable>target</replaceable> is the name of the
810 recipe you want to build.
811 Common targets are the images in
812 <filename>meta/recipes-core/images</filename>,
813 <filename>meta/recipes-sato/images</filename>, etc. all found
814 in the
815 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
816 Or, the target can be the name of a recipe for a specific
817 piece of software such as BusyBox.
818 For more details about the images the OpenEmbedded build
819 system supports, see the
820 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
821 chapter in the Yocto Project Reference Manual.</para>
822
823 <para>As an example, the following command builds the
781 <filename>core-image-minimal</filename> image: 824 <filename>core-image-minimal</filename> image:
782 <literallayout class='monospaced'> 825 <literallayout class='monospaced'>
783 $ bitbake core-image-minimal 826 $ bitbake core-image-minimal
784 </literallayout> 827 </literallayout>
785 For information on BitBake, see the 828 Once an image has been built, it often needs to be installed.
786 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. 829 The images and kernels built by the OpenEmbedded build system
830 are placed in the Build Directory in
831 <filename class="directory">tmp/deploy/images</filename>.
832 For information on how to run pre-built images such as
833 <filename>qemux86</filename> and <filename>qemuarm</filename>,
834 see the
835 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
836 manual.
837 For information about how to install these images, see the
838 documentation for your particular board or machine.
839 <note><title>Build Notes</title>
840 <itemizedlist>
841 <listitem><para>
842 If you experience a build error due to resources
843 temporarily being unavailable and it appears you
844 should not be having this issue, it might be due
845 to the combination of a 4.3+ Linux kernel and
846 <filename>systemd</filename> version 228+
847 (i.e. see this
848 <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink>
849 for information).</para>
850
851 <para>To work around this issue, you can try either
852 of the following:
853 <itemizedlist>
854 <listitem><para>
855 Try the build again.
856 </para></listitem>
857 <listitem><para>
858 Modify the "DefaultTasksMax"
859 <filename>systemd</filename> parameter
860 by uncommenting it and setting it to
861 "infinity".
862 You can find this parameter in the
863 <filename>system.conf</filename> file
864 located in
865 <filename>/etc/systemd</filename>
866 on most systems.
867 </para></listitem>
868 </itemizedlist>
869 </para></listitem>
870 <listitem><para>
871 Building an image without GNU General Public
872 License Version 3 (GPLv3), or similarly licensed,
873 components is supported for only minimal and
874 base images.
875 See the
876 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
877 chapter in the Yocto Project Reference Manual
878 for more information.
879 </para></listitem>
880 <listitem><para>
881 When building an image using GPL components,
882 you need to maintain your original settings and
883 not switch back and forth applying different
884 versions of the GNU General Public License.
885 If you rebuild using different versions of GPL,
886 dependency errors might occur due to some components
887 not being rebuilt.
888 </para></listitem>
889 </itemizedlist>
890 </note>
787 </para></listitem> 891 </para></listitem>
788 </orderedlist> 892 </orderedlist>
789 </para> 893 </para>
diff --git a/documentation/ref-manual/figures/building-an-image.png b/documentation/ref-manual/figures/building-an-image.png
deleted file mode 100755
index 1fbea5ab00..0000000000
--- a/documentation/ref-manual/figures/building-an-image.png
+++ /dev/null
Binary files differ
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 73b5df88dd..bfca60a99b 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -11,147 +11,6 @@
11 documentation set provide more details on how to use the Yocto Project. 11 documentation set provide more details on how to use the Yocto Project.
12 </para> 12 </para>
13 13
14<section id='usingpoky-build'>
15 <title>Running a Build</title>
16
17 <para>
18 This section provides a summary of the build process and provides information
19 for less obvious aspects of the build process.
20 For general information on how to build an image using the OpenEmbedded build
21 system, see the
22 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
23 section of the Yocto Project Quick Start.
24 </para>
25
26 <section id='build-overview'>
27 <title>Build Overview</title>
28
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>
44 The first thing you need to do is set up the OpenEmbedded build
45 environment by sourcing the environment setup script
46 (i.e.
47 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
48 Here is an example:
49 <literallayout class='monospaced'>
50 $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>]
51 </literallayout>
52 </para>
53
54 <para>
55 The <replaceable>build_dir</replaceable> argument is optional and specifies the directory the
56 OpenEmbedded build system uses for the build -
57 the
58 <link linkend='build-directory'>Build Directory</link>.
59 If you do not specify a Build Directory, it defaults to a directory
60 named <filename>build</filename> in your current working directory.
61 A common practice is to use a different Build Directory for different targets.
62 For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
63 target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
64 </para>
65
66 <para>
67 Once the build environment is set up, you can build a target using:
68 <literallayout class='monospaced'>
69 $ bitbake <replaceable>target</replaceable>
70 </literallayout>
71 <note>
72 <para>
73 If you experience a build error due to resources
74 temporarily being unavailable and it appears you
75 should not be having this issue, it might be due
76 to the combination of a 4.3+ Linux kernel and
77 <filename>systemd</filename> version 228+
78 (i.e. see this
79 <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink>
80 for information).
81 </para>
82
83 <para>
84 To work around this issue, you can try either
85 of the following:
86 <itemizedlist>
87 <listitem><para>
88 Try the build again.
89 </para></listitem>
90 <listitem><para>
91 Modify the "DefaultTasksMax"
92 <filename>systemd</filename> parameter
93 by uncommenting it and setting it to
94 "infinity".
95 You can find this parameter in the
96 <filename>system.conf</filename> file
97 located in
98 <filename>/etc/systemd</filename>
99 on most systems.
100 </para></listitem>
101 </itemizedlist>
102 </para>
103 </note>
104 </para>
105
106 <para>
107 The <replaceable>target</replaceable> is the name of the recipe you want to build.
108 Common targets are the images in <filename>meta/recipes-core/images</filename>,
109 <filename>meta/recipes-sato/images</filename>, etc. all found in the
110 <link linkend='source-directory'>Source Directory</link>.
111 Or, the target can be the name of a recipe for a specific piece of software such as
112 BusyBox.
113 For more details about the images the OpenEmbedded build system supports, see the
114 "<link linkend="ref-images">Images</link>" chapter.
115 </para>
116
117 <note>
118 Building an image without GNU General Public License Version
119 3 (GPLv3), or similarly licensed, components is supported for
120 only minimal and base images.
121 See the "<link linkend='ref-images'>Images</link>" chapter for more information.
122 </note>
123 </section>
124
125 <section id='building-an-image-using-gpl-components'>
126 <title>Building an Image Using GPL Components</title>
127
128 <para>
129 When building an image using GPL components, you need to maintain your original
130 settings and not switch back and forth applying different versions of the GNU
131 General Public License.
132 If you rebuild using different versions of GPL, dependency errors might occur
133 due to some components not being rebuilt.
134 </para>
135 </section>
136</section>
137
138<section id='usingpoky-install'>
139 <title>Installing and Using the Result</title>
140
141 <para>
142 Once an image has been built, it often needs to be installed.
143 The images and kernels built by the OpenEmbedded build system are placed in the
144 <link linkend='build-directory'>Build Directory</link> in
145 <filename class="directory">tmp/deploy/images</filename>.
146 For information on how to run pre-built images such as <filename>qemux86</filename>
147 and <filename>qemuarm</filename>, see the
148 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
149 manual.
150 For information about how to install these images, see the documentation for your
151 particular board or machine.
152 </para>
153</section>
154
155<section id='usingpoky-debugging-tools-and-techniques'> 14<section id='usingpoky-debugging-tools-and-techniques'>
156 <title>Debugging Tools and Techniques</title> 15 <title>Debugging Tools and Techniques</title>
157 16