summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-06-20 14:24:30 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-06-22 09:16:45 +0100
commitcf2169b351000b04f46270fcb3a9234ffa44b7c5 (patch)
treed8322f4a05cc7443153158adb86752a3d3a9af69 /documentation
parent1e90dd09ffacac3161016c5bf07eeb677749c798 (diff)
downloadpoky-cf2169b351000b04f46270fcb3a9234ffa44b7c5.tar.gz
dev-manual, ref-manual: Re-wrote the intros
Fixes [YOCTO #11630] I updated both the introductory sections of the ref-manual and the dev-manual. These need to work more tightly with the projected YP documentation set. (From yocto-docs rev: 6a28537d03fad8a53198edc7f9a6229f4e58e551) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-intro.xml123
-rw-r--r--documentation/ref-manual/introduction.xml173
2 files changed, 94 insertions, 202 deletions
diff --git a/documentation/dev-manual/dev-manual-intro.xml b/documentation/dev-manual/dev-manual-intro.xml
index 945c83e2c3..8c94009335 100644
--- a/documentation/dev-manual/dev-manual-intro.xml
+++ b/documentation/dev-manual/dev-manual-intro.xml
@@ -10,96 +10,67 @@
10 10
11 <para> 11 <para>
12 Welcome to the Yocto Project Development Manual! 12 Welcome to the Yocto Project Development Manual!
13 This manual provides information on how to use the Yocto Project to 13 This manual provides relevant procedures necessary for developing
14 develop embedded Linux images and user-space applications that 14 in the Yocto Project environment (i.e. developing embedded Linux
15 run on targeted devices. 15 images and user-space applications that run on targeted devices).
16 The manual provides an overview of image, kernel, and 16 The manual groups related procedures into higher-level sections.
17 user-space application development using the Yocto Project. 17 Procedures can consist of high-level steps or low-level steps
18 Because much of the information in this manual is general, it 18 depending on the topic.
19 contains many references to other sources where you can find more 19 You can find conceptual information related to a procedure by
20 detail. 20 following appropriate links to the Yocto Project Reference
21 For example, you can find detailed information on Git, repositories, 21 Manual.
22 and open source in general in many places on the Internet.
23 Another example specific to the Yocto Project is how to quickly
24 set up your host development system and build an image, which you
25 find in the
26 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
27 </para>
28
29 <para>
30 The Yocto Project Development Manual does, however, provide
31 guidance and examples on how to change the kernel source code,
32 reconfigure the kernel, and develop an application using
33 <filename>devtool</filename>.
34 </para> 22 </para>
35 23
36 <note>
37 By default, using the Yocto Project creates a Poky distribution.
38 However, you can create your own distribution by providing key
39 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>.
40 A good example is Angstrom, which has had a distribution
41 based on the Yocto Project since its inception.
42 Other examples include commercial distributions like
43 <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>,
44 <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>,
45 <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink>
46 and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>.
47 See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
48 section for more information.
49 </note>
50 </section>
51
52 <section id='what-this-manual-provides'>
53 <title>What This Manual Provides</title>
54
55 <para> 24 <para>
56 The following list describes what you can get from this manual: 25 The following list describes what you can get from this manual:
57 <itemizedlist> 26 <itemizedlist>
58 <listitem><para>Information that lets you get set 27 <listitem><para>
59 up to develop using the Yocto Project.</para></listitem> 28 <emphasis>Setup Procedures:</emphasis>
60 <listitem><para>Information to help developers who are new to 29 Procedures that show you how to set
61 the open source environment and to the distributed revision 30 up a Yocto Project Development environment and how
62 control system Git, which the Yocto Project uses. 31 to accomplish the change workflow through logging
32 defects and submitting changes.
63 </para></listitem> 33 </para></listitem>
64 <listitem><para>An understanding of common end-to-end 34 <listitem><para>
65 development models and tasks.</para></listitem> 35 <emphasis>Emulation Procedures:</emphasis>
66 <listitem><para>Information about common development tasks 36 Procedures that show you how to use the
67 generally used during image development for 37 Yocto Project integrated QuickEMUlator (QEMU), which lets
68 embedded devices. 38 you simulate running on hardware an image you have built
39 using the OpenEmbedded build system.
69 </para></listitem> 40 </para></listitem>
70 <listitem><para>Information on using the Yocto Project 41 <listitem><para>
71 integration of the QuickEMUlator (QEMU), which lets you 42 <emphasis>Common Procedures:</emphasis>
72 simulate running on hardware an image you have built using 43 Procedures related to "everyday" tasks you perform while
73 the OpenEmbedded build system. 44 developing images and applications using the Yocto
45 Project.
74 </para></listitem> 46 </para></listitem>
75 <listitem><para>Many references to other sources of related
76 information.</para></listitem>
77 </itemizedlist> 47 </itemizedlist>
78 </para> 48 </para>
79 </section>
80
81 <section id='what-this-manual-does-not-provide'>
82 <title>What this Manual Does Not Provide</title>
83 49
84 <para> 50 <para>
85 This manual will not give you the following: 51 This manual will not give you the following:
86 <itemizedlist> 52 <itemizedlist>
87 <listitem><para><emphasis>Step-by-step instructions when those instructions exist in other Yocto 53 <listitem><para>
88 Project documentation:</emphasis> 54 <emphasis>Redundant Step-by-step Instructions:</emphasis>
89 For example, the 55 For example, the
90 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink> 56 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>
91 manual contains detailed instructions on how to install an 57 contains detailed instructions on how to install an
92 SDK, which is used to develop applications for target 58 SDK, which is used to develop applications for target
93 hardware. 59 hardware.
94 </para></listitem> 60 </para></listitem>
95 <listitem><para><emphasis>Reference material:</emphasis> 61 <listitem><para>
62 <emphasis>Reference or Conceptual Material:</emphasis>
96 This type of material resides in an appropriate reference manual. 63 This type of material resides in an appropriate reference manual.
97 For example, system variables are documented in the 64 For example, system variables are documented in the
98 <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>. 65 <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.
99 </para></listitem> 66 </para></listitem>
100 <listitem><para><emphasis>Detailed public information that is not specific to the Yocto Project:</emphasis> 67 <listitem><para>
101 For example, exhaustive information on how to use Git is covered better through the 68 <emphasis>Detailed Public Information Not Specific to the
102 Internet than in this manual. 69 Yocto Project:</emphasis>
70 For example, exhaustive information on how to use the
71 Source Control Manager Git is better covered with Internet
72 searches and official Git Documentation than through the
73 Yocto Project documentation.
103 </para></listitem> 74 </para></listitem>
104 </itemizedlist> 75 </itemizedlist>
105 </para> 76 </para>
@@ -112,10 +83,22 @@
112 Because this manual presents information for many different 83 Because this manual presents information for many different
113 topics, supplemental information is recommended for full 84 topics, supplemental information is recommended for full
114 comprehension. 85 comprehension.
115 See the 86 For introductory information on the Yocto Project, see the
87 <ulink url='&YOCTO_HOME_URL;/ecosystem/yocto-project-backgrounders'>Yocto Project Backgrounders</ulink>
88 on the
89 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>.
90 You can find an introductory to using the Yocto Project by working
91 through the
92 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
93 </para>
94
95 <para>
96 For a comprehensive list of links and other documentation, see the
116 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>" 97 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"
117 section in the Yocto Project Reference Manual for helpful 98 section in the Yocto Project Reference Manual.
118 sources. 99 </para>
100
101 <para>
119 </para> 102 </para>
120 </section> 103 </section>
121</chapter> 104</chapter>
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index aab0eaa9e0..98b3ca828c 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -12,29 +12,25 @@
12 Welcome to the Yocto Project Reference Manual. 12 Welcome to the Yocto Project Reference Manual.
13 This manual provides reference information for the current release 13 This manual provides reference information for the current release
14 of the Yocto Project. 14 of the Yocto Project.
15 The Yocto Project is an open-source collaboration project focused 15 This manual is best used after you have an understanding
16 on embedded Linux developers. 16 of the basics of the Yocto Project.
17 Amongst other things, the Yocto Project uses the OpenEmbedded build 17 The manual is neither meant to be read as a starting point to the
18 system, which is based on the Poky project, to construct complete 18 Yocto Project nor read from start to finish.
19 Linux images. 19 Use this manual to find concepts, variable definitions, class
20 descriptions, and so forth as needed during the course of using
21 the Yocto Project.
20 </para> 22 </para>
21 23
22 <para> 24 <para>
23 This reference manual is best used after you have an understanding 25 For introductory information on the Yocto Project, see the
24 of the basics of the Yocto Project. 26 <ulink url='&YOCTO_HOME_URL;/ecosystem/yocto-project-backgrounders'>Yocto Project Backgrounders</ulink>
25 The manual is not meant to be read as a starting point to the 27 on the
26 Yocto Project. 28 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>.
27 Use this manual to find concepts, variable definitions, class
28 descriptions, and so forth.
29 The manual augments working with the Yocto Project during application
30 and kernel development.
31 </para> 29 </para>
32 30
33 <para> 31 <para>
34 The Yocto Project Reference Manual does not provide "how-to", 32 You can find an introductory to using the Yocto Project by working
35 task-oriented information. 33 through the
36 You can find complete introductory and getting started information
37 on the Yocto Project by reading the
38 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. 34 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
39 You can find "how-to" information in the 35 You can find "how-to" information in the
40 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>. 36 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>.
@@ -47,124 +43,37 @@
47 </para> 43 </para>
48</section> 44</section>
49 45
50<!-- 46<section id='ref-yp-intro'>
51<section id='intro-manualoverview'> 47 <title>Yocto Project Introduction</title>
52 <title>Documentation Overview</title> 48
53 <para> 49 <para>
54 This reference manual consists of the following: 50 The Yocto Project is an open-source collaboration project whose
55 <itemizedlist> 51 focus is for developers of embedded Linux systems.
56 <listitem><para> 52 Among other things, the Yocto Project uses a build host based
57 <emphasis> 53 on the OpenEmbedded (OE) project, which uses the
58 <link linkend='usingpoky'>Using the Yocto Project</link>: 54 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
59 </emphasis> 55 tool, to construct complete Linux images.
60 Provides an overview of the components that make up the Yocto 56 The BitBake and OE components are combined together to form
61 Project followed by information about debugging images created 57 a reference build host, historically known as
62 in the Yocto Project. 58 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>
63 </para></listitem> 59 (<emphasis>Pah</emphasis>-kee).
64 <listitem><para> 60 </para>
65 <emphasis> 61
66 <link linkend='closer-look'>A Closer Look at the Yocto Project Development Environment</link>: 62 <para>
67 </emphasis> 63 By default, using the Yocto Project creates a Poky distribution.
68 Provides a more detailed look at the Yocto Project development 64 However, you can create your own distribution by providing key
69 environment within the context of development. 65 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>.
70 </para></listitem> 66 A good example is Angstrom, which has had a distribution
71 <listitem><para> 67 based on the Yocto Project since its inception.
72 <emphasis> 68 Other examples include commercial distributions like
73 <link linkend='technical-details'>Technical Details</link>: 69 <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>,
74 </emphasis> 70 <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>,
75 Describes fundamental Yocto Project components as well as an 71 <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink>
76 explanation behind how the Yocto Project uses shared state 72 and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>.
77 (sstate) cache to speed build time. 73 See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-distribution'>Creating Your Own Distribution</ulink>"
78 </para></listitem> 74 section in the Yocto Project Development Manual for more information.
79 <listitem><para>
80 <emphasis>
81 <link linkend='migration'>Migrating to a Newer Yocto Project Release</link>:
82 </emphasis>
83 Describes release-specific information that helps you move from
84 one Yocto Project Release to another.
85 </para></listitem>
86 <listitem><para>
87 <emphasis>
88 <link linkend='ref-structure'>Directory Structure</link>:
89 </emphasis> Describes the
90 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
91 created either by unpacking a released Yocto Project tarball on
92 your host development system, or by cloning the upstream
93 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>
94 Git repository.
95 </para></listitem>
96 <listitem><para>
97 <emphasis>
98 <link linkend='ref-classes'>Classes</link>:
99 </emphasis>
100 Describes the classes used in the Yocto Project.
101 </para></listitem>
102 <listitem><para>
103 <emphasis>
104 <link linkend='ref-tasks'>Tasks</link>:
105 </emphasis>
106 Describes the tasks defined by the OpenEmbedded build system.
107 </para></listitem>
108 <listitem><para>
109 <emphasis>
110 <link linkend='ref-devtool-reference'><filename>devtool</filename> Quick Reference</link>:
111 </emphasis>
112 Provides a quick reference for the <filename>devtool</filename>
113 command.
114 </para></listitem>
115 <listitem><para>
116 <emphasis>
117 <link linkend='ref-qa-checks'>QA Error and Warning Messages</link>:
118 </emphasis>
119 Lists and describes QA warning and error messages.
120 </para></listitem>
121 <listitem><para>
122 <emphasis>
123 <link linkend='ref-images'>Images</link>:
124 </emphasis>
125 Describes the standard images that the Yocto Project supports.
126 </para></listitem>
127 <listitem><para>
128 <emphasis>
129 <link linkend='ref-features'>Features</link>:
130 </emphasis>
131 Describes mechanisms for creating distribution, machine, and
132 image features during the build process using the OpenEmbedded
133 build system.
134 </para></listitem>
135 <listitem><para>
136 <emphasis>
137 <link linkend='ref-variables-glos'>Variables Glossary</link>:
138 </emphasis>
139 Presents most variables used by the OpenEmbedded build system,
140 which uses BitBake.
141 Entries describe the function of the variable and how to
142 apply them.
143 </para></listitem>
144 <listitem><para>
145 <emphasis>
146 <link linkend='ref-varlocality'>Variable Context</link>:
147 </emphasis>
148 Provides variable locality or context.
149 </para></listitem>
150 <listitem><para>
151 <emphasis>
152 <link linkend='faq'>FAQ</link>:
153 </emphasis>
154 Provides answers for commonly asked questions in the Yocto
155 Project development environment.
156 </para></listitem>
157 <listitem><para>
158 <emphasis>
159 <link linkend='resources'>Contributions and Additional Information</link>:
160 </emphasis>
161 Provides an overview of methods by which you can
162 contribute to and participate in the Yocto Project.
163 </para></listitem>
164 </itemizedlist>
165 </para> 75 </para>
166</section> 76</section>
167-->
168 77
169<section id='intro-requirements'> 78<section id='intro-requirements'>
170<title>System Requirements</title> 79<title>System Requirements</title>