summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-09-19 10:16:24 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-09-25 17:59:58 +0100
commitfea08c71f0f7ca1034f243e9be5320aee3833b54 (patch)
treefbee287ab5f04db80f1f5582f8f8f1b18627b6a6 /documentation/dev-manual
parent90ed20051c4e6381ab0a138a4bb54436b82960d7 (diff)
downloadpoky-fea08c71f0f7ca1034f243e9be5320aee3833b54.tar.gz
documentation/dev-manual/dev-manual-start.xml: formats and re-wordings.
Applied consistent section referencing formats. Also cleaned up some terminolgy for the YP Git repo. (From yocto-docs rev: fa3cbb835b61158357d3f6fb9ebe017b9ba405cf) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-start.xml121
1 files changed, 60 insertions, 61 deletions
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 80192a5322..fd0967c939 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -7,16 +7,15 @@
7 7
8<para> 8<para>
9 This chapter introduces the Yocto Project and gives you an idea of what you need to get started. 9 This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
10 You can find enough information to set your development host up and build or use images for 10 You can find enough information to set up your development host and build or use images for
11 hardware supported by the Yocto Project by reading the 11 hardware supported by the Yocto Project by reading
12 <ulink url='http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html'> 12 <ulink url='http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html'>
13 Yocto Project Quick Start</ulink> located on the <ulink url='http://www.yoctoproject.org'> 13 The Yocto Project Quick Start</ulink>.
14 Yocto Project website</ulink>.
15</para> 14</para>
16 15
17<para> 16<para>
18 The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides 17 The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
19 some higher level concepts you might want to consider. 18 some higher-level concepts you might want to consider.
20</para> 19</para>
21 20
22<section id='introducing-the-yocto-project'> 21<section id='introducing-the-yocto-project'>
@@ -24,8 +23,8 @@
24 23
25 <para> 24 <para>
26 The Yocto Project is an open-source collaboration project focused on embedded Linux development. 25 The Yocto Project is an open-source collaboration project focused on embedded Linux development.
27 The project currently provides a build system and various ancillary tools suitable for the 26 The project currently provides a build system, which is sometimes referred to as "Poky",
28 embedded developer. 27 and provides various ancillary tools suitable for the embedded developer.
29 The Yocto Project also features the Sato reference User Interface, which is optimized for 28 The Yocto Project also features the Sato reference User Interface, which is optimized for
30 stylus driven, low-resolution screens. 29 stylus driven, low-resolution screens.
31 </para> 30 </para>
@@ -37,7 +36,7 @@
37 While the Yocto Project does not provide a strict testing framework, 36 While the Yocto Project does not provide a strict testing framework,
38 it does provide or generate for you artifacts that let you perform target-level and 37 it does provide or generate for you artifacts that let you perform target-level and
39 emulated testing and debugging. 38 emulated testing and debugging.
40 And, if you are an Eclipse user, you can install an Eclipse Yocto Plug-in to allow you to 39 And, if you are an Eclipse IDE user, you can install an Eclipse Yocto Plug-in to allow you to
41 develop within that familiar environment. 40 develop within that familiar environment.
42 </para> 41 </para>
43</section> 42</section>
@@ -51,50 +50,50 @@
51 <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current 50 <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current
52 Linux-based host system. 51 Linux-based host system.
53 You will have the best results with a recent release of Fedora, 52 You will have the best results with a recent release of Fedora,
54 OpenSUSE, or Ubuntu as these releases are frequently tested and officially supported 53 OpenSUSE, or Ubuntu as these releases are frequently tested against the Yocto Project
55 host systems. 54 and officially supported.
56 You should also have about 100 gigabytes of free disk space for building images. 55 You should also have about 100 gigabytes of free disk space for building images.
57 </para></listitem> 56 </para></listitem>
58 <listitem><para><emphasis>Packages:</emphasis> The Yocto Project requires certain packages 57 <listitem><para><emphasis>Packages:</emphasis> The Yocto Project requires certain packages
59 exist on your development system (e.g. Python 2.6 or 2.7). 58 exist on your development system (e.g. Python 2.6 or 2.7).
60 See <ulink url='http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html#packages'> 59 See "<ulink url='http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html#packages'>The Packages</ulink>"
61 The Packages</ulink> section in the Yocto Project Quick start for the exact package 60 section in the Yocto Project Quick start for the exact package
62 requirements and the installation commands for the supported distributions.</para></listitem> 61 requirements and the installation commands to install them
62 for the supported distributions.</para></listitem>
63 <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis> 63 <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
64 You need a release of the Yocto Project. 64 You need a release of the Yocto Project.
65 You can get set up with local Yocto Project files one of two ways depending on whether you 65 You can get set up with local Yocto Project files one of two ways depending on whether you
66 are going to be contributing back into the Yocto Project source repository or not. 66 are going to be contributing back into the Yocto Project source repository or not.
67 <note> 67 <note>
68 Regardless of the method you use, this manual will refer to the resulting 68 Regardless of the method you use, this manual refers to the resulting
69 hierarchical set of files as "the local Yocto Project files." 69 hierarchical set of files as "the Yocto Project files" or "the Yocto Project file
70 structure."
70 </note> 71 </note>
71 <itemizedlist> 72 <itemizedlist>
72 <listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute 73 <listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute
73 back into the Yocto Project you can simply download the Yocto Project release you want 74 back into the Yocto Project, you can simply download the Yocto Project release you want
74 from the website’s <ulink url='http://yoctoproject.org/download'>download page</ulink>. 75 from the website’s <ulink url='http://yoctoproject.org/download'>download page</ulink>.
75 Once you have the tarball, just extract it into a directory of your choice.</para> 76 Once you have the tarball, just extract it into a directory of your choice.</para>
76
77 <para>For example, the following command extracts the Yocto Project 1.1 release tarball 77 <para>For example, the following command extracts the Yocto Project 1.1 release tarball
78 into the current working directory and sets up a file structure whose top-level 78 into the current working directory and sets up the Yocto Project file structure
79 directory is named <filename>poky-1.1</filename>: 79 with a top-level directory named <filename>poky-1.1</filename>:
80 <literallayout class='monospaced'> 80 <literallayout class='monospaced'>
81 $ tar xfj poky-1.1.tar.bz2 81 $ tar xfj poky-1.1.tar.bz2
82 </literallayout></para> 82 </literallayout></para>
83 <para>This method does not produce a <filename>poky</filename> Git repository. 83 <para>This method does not produce a Git repository.
84 You end up simply with a local snapshot of Yocto Project files that are based on the 84 Instead, you simply end up with a local snapshot of the
85 particular release in the tarball.</para></listitem> 85 Yocto Project files that are based on the particular release in the
86 tarball.</para></listitem>
86 <listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing 87 <listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing
87 back into the Yocto Project you should use Git commands to set up a local 88 back into the Yocto Project, you should use Git commands to set up a local
88 <filename>poky</filename> Git repository of the Yocto Project. 89 Git repository of the Yocto Project files.
89 Doing so creates a Git repository with a complete history of changes and allows 90 Doing so creates a Git repository with a complete history of changes and allows
90 you to easily submit your changes upstream to the project.</para> 91 you to easily submit your changes upstream to the project.</para>
91 92 <para>The following transcript shows how to clone the Yocto Project files'
92 <para>The following transcript shows how to clone the <filename>poky</filename>
93 Git repository into the current working directory. 93 Git repository into the current working directory.
94 The command creates the repository in a directory named <filename>poky</filename>. 94 The command creates the repository in a directory named <filename>poky</filename>.
95 For information on the Yocto Project and Git, see 95 For information on the Yocto Project and Git, see the
96 <xref linkend='git'>Git</xref> in 96 "<link linkend='git'>Git</link>" section.
97 <xref linkend='dev-manual-newbie'>Working with Open Source Code</xref>.
98 <literallayout class='monospaced'> 97 <literallayout class='monospaced'>
99 $ git clone git://git.yoctoproject.org/poky 98 $ git clone git://git.yoctoproject.org/poky
100 Initialized empty Git repository in /home/scottrif/poky/.git/ 99 Initialized empty Git repository in /home/scottrif/poky/.git/
@@ -104,28 +103,28 @@
104 Receiving objects: 100% (107624/107624), 69.74 MiB | 483 KiB/s, done. 103 Receiving objects: 100% (107624/107624), 69.74 MiB | 483 KiB/s, done.
105 Resolving deltas: 100% (73393/73393), done. 104 Resolving deltas: 100% (73393/73393), done.
106 </literallayout></para> 105 </literallayout></para>
107 106 <para>For another example of how to set up your own local Git repositories, see this
108 <para>For another example of how to set up your own local Git repositories see this
109 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'> 107 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
110 wiki page</ulink>, which describes how to create both <filename>poky</filename> 108 wiki page</ulink>, which describes how to create both <filename>poky</filename>
111 and <filename>meta-intel</filename> Git repositories.</para></listitem> 109 and <filename>meta-intel</filename> Git repositories.</para></listitem>
112 </itemizedlist></para></listitem> 110 </itemizedlist></para></listitem>
113 <listitem id='local-kernel-files'><para><emphasis>Linux Yocto Kernel:</emphasis> 111 <listitem id='local-kernel-files'><para><emphasis>Linux Yocto Kernel:</emphasis>
114 If you are going to be making modifications to a supported Linux Yocto kernel you 112 If you are going to be making modifications to a supported Linux Yocto kernel, you
115 need to get set up so that you can edit local copies of the source. 113 need to establish local copies of the source.
116 This setup involves creating a bare clone of the Linux Yocto kernel and then cloning 114 This setup involves creating a bare clone of the Linux Yocto kernel and then cloning
117 that repository. 115 that repository.
118 You can create the bare clone and the copy of the bare clone anywhere you like. 116 You can create the bare clone and the copy of the bare clone anywhere you like.
119 For simplicity, it is recommended that you create these structures outside of the 117 For simplicity, it is recommended that you create these structures outside of the
120 Yocto Project files Git repository.</para> 118 Yocto Project files' Git repository.</para>
121 <para>As an example, the following transcript shows how to create the bare clone 119 <para>As an example, the following transcript shows how to create the bare clone
122 of the <filename>linux-yocto-3.0</filename> kernel and then create a copy of 120 of the <filename>linux-yocto-3.0</filename> kernel and then create a copy of
123 that clone. 121 that clone.
124 <note>If you currently have a local Linux Yocto kernel Git repository, you can 122 <note>When you have a local Linux Yocto kernel Git repository, you can
125 reference this local repository rather than the upstream Git repository as 123 reference that repository rather than the upstream Git repository as
126 part of the <filename>clone</filename> command. 124 part of the <filename>clone</filename> command.
127 Doing so can speed up the process.</note> 125 Doing so can speed up the process.</note>
128 The bare clone is named <filename>linux-yocto-3.0.git</filename>, while the 126 In the following example, the bare clone is named
127 <filename>linux-yocto-3.0.git</filename>, while the
129 copy is named <filename>linux-yocto-3.0</filename>: 128 copy is named <filename>linux-yocto-3.0</filename>:
130 <literallayout class='monospaced'> 129 <literallayout class='monospaced'>
131 $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.0 linux-yocto-3.0.git 130 $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.0 linux-yocto-3.0.git
@@ -147,7 +146,7 @@
147 The <filename>poky-extras</filename> Git repository contains metadata needed to 146 The <filename>poky-extras</filename> Git repository contains metadata needed to
148 build the kernel image. 147 build the kernel image.
149 In particular, it contains the kernel <filename>.bbappend</filename> files that you 148 In particular, it contains the kernel <filename>.bbappend</filename> files that you
150 edit to point to your locally modified kernel source files and to build kernel 149 edit to point to your locally modified kernel source files and to build the kernel
151 image. 150 image.
152 Pointing to these local files is much more efficient than requiring a download of the 151 Pointing to these local files is much more efficient than requiring a download of the
153 source files from upstream each time you make changes to the kernel.</para> 152 source files from upstream each time you make changes to the kernel.</para>
@@ -166,8 +165,8 @@
166 Receiving objects: 100% (531/531), 517.86 KiB, done. 165 Receiving objects: 100% (531/531), 517.86 KiB, done.
167 Resolving deltas: 100% (138/138), done. 166 Resolving deltas: 100% (138/138), done.
168 </literallayout></para></listitem> 167 </literallayout></para></listitem>
169 <listitem><para><emphasis>Supported Board Support Packages (BSPs):</emphasis> The same considerations 168 <listitem><para><emphasis>Supported Board Support Packages (BSPs):</emphasis>
170 exist for BSPs. 169 Similar considerations exist for BSPs.
171 You can get set up for BSP development one of two ways: tarball extraction or 170 You can get set up for BSP development one of two ways: tarball extraction or
172 with a local Git repository. 171 with a local Git repository.
173 Regardless of the method you use, the Yocto Project uses the following BSP layer 172 Regardless of the method you use, the Yocto Project uses the following BSP layer
@@ -185,16 +184,16 @@
185 <itemizedlist> 184 <itemizedlist>
186 <listitem><para><emphasis>Tarball Extraction:</emphasis> You can download any released 185 <listitem><para><emphasis>Tarball Extraction:</emphasis> You can download any released
187 BSP tarball from the same 186 BSP tarball from the same
188 <ulink url='http://yoctoproject.org/download'>download site</ulink>. 187 <ulink url='http://yoctoproject.org/download'>download site</ulink> used
189 Once you have the tarball just extract it into a directory of your choice. 188 to get the Yocto Project release.
189 Once you have the tarball, just extract it into a directory of your choice.
190 Again, this method just produces a snapshot of the BSP layer in the form 190 Again, this method just produces a snapshot of the BSP layer in the form
191 of a hierarchical directory structure.</para></listitem> 191 of a hierarchical directory structure.</para></listitem>
192 <listitem><para><emphasis>Git Repository Method:</emphasis> If you are working 192 <listitem><para><emphasis>Git Repository Method:</emphasis> If you are working
193 with a <filename>poky</filename> Git repository you should also set up a 193 with a Yocto Project files Git repository, you should also set up a
194 <filename>meta-intel</filename> Git repository. 194 <filename>meta-intel</filename> Git repository.
195 Typically, you set up the <filename>meta-intel</filename> Git repository inside 195 Typically, you set up the <filename>meta-intel</filename> Git repository inside
196 the <filename>poky</filename> Git repository.</para> 196 the Yocto Project files Git repository.</para>
197
198 <para>For example, the following transcript shows the steps to clone the 197 <para>For example, the following transcript shows the steps to clone the
199 <filename>meta-intel</filename> 198 <filename>meta-intel</filename>
200 Git repository inside the <filename>poky</filename> Git repository. 199 Git repository inside the <filename>poky</filename> Git repository.
@@ -208,18 +207,17 @@
208 Receiving objects: 100% (1325/1325), 1.56 MiB | 330 KiB/s, done. 207 Receiving objects: 100% (1325/1325), 1.56 MiB | 330 KiB/s, done.
209 Resolving deltas: 100% (546/546), done. 208 Resolving deltas: 100% (546/546), done.
210 </literallayout></para> 209 </literallayout></para>
211
212 <para>The same 210 <para>The same
213 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'> 211 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
214 wiki page</ulink> referenced earlier covers how to 212 wiki page</ulink> referenced earlier covers how to
215 set up the <filename>meta-intel</filename> Git repository.</para></listitem> 213 set up the <filename>meta-intel</filename> Git repository.</para></listitem>
216 </itemizedlist></para></listitem> 214 </itemizedlist></para></listitem>
217 <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing 215 <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing
218 applications using the 216 applications using the Eclipse Integrated Development Environment (IDE),
219 Eclipse Integrated Development Environment (IDE) you will need this plug-in. 217 you will need this plug-in.
220 See the 218 See the
221 <ulink url='http://www.yoctoproject.org/docs/adt-manual/adt-manual.html#setting-up-the-eclipse-ide'> 219 "<ulink url='http://www.yoctoproject.org/docs/adt-manual/adt-manual.html#setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</ulink>"
222 Setting up the Eclipse IDE</ulink> section in the Yocto Application Development Toolkit (ADT) 220 section in the Yocto Application Development Toolkit (ADT)
223 User’s Guide for more information.</para></listitem> 221 User’s Guide for more information.</para></listitem>
224 </itemizedlist> 222 </itemizedlist>
225 </para> 223 </para>
@@ -231,8 +229,8 @@
231 <para> 229 <para>
232 The build process creates an entire Linux distribution, including the toolchain, from source. 230 The build process creates an entire Linux distribution, including the toolchain, from source.
233 For more information on this topic, see the 231 For more information on this topic, see the
234 <ulink url='http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html#building-image'> 232 "<ulink url='http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html#building-image'>Building an Image</ulink>"
235 Building an Image</ulink> section in the Yocto Project Quick Start. 233 section in the Yocto Project Quick Start.
236 </para> 234 </para>
237 235
238 <para> 236 <para>
@@ -244,7 +242,7 @@
244 script.</para></listitem> 242 script.</para></listitem>
245 <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file is set 243 <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file is set
246 up how you want it. 244 up how you want it.
247 This file defines the target machine architecture and and other build options.</para></listitem> 245 This file defines the target machine architecture and other build options.</para></listitem>
248 <listitem><para>Build the image using the BitBake command. 246 <listitem><para>Build the image using the BitBake command.
249 If you want information on Bitbake, see the user manual at 247 If you want information on Bitbake, see the user manual at
250 <ulink url='http://docs.openembedded.org/bitbake/html'></ulink>.</para></listitem> 248 <ulink url='http://docs.openembedded.org/bitbake/html'></ulink>.</para></listitem>
@@ -260,16 +258,17 @@
260 <para> 258 <para>
261 Another option you have to get started is to use pre-built binaries. 259 Another option you have to get started is to use pre-built binaries.
262 This scenario is ideal for developing software applications to run on your target hardware. 260 This scenario is ideal for developing software applications to run on your target hardware.
263 To do this you need to install the stand-alone Yocto toolchain tarball and then download the 261 To do this, you need to install the stand-alone Yocto Project cross-toolchain tarball and
264 pre-built kernel that you will boot using the QEMU emulator. 262 then download the pre-built kernel that you will boot in the QEMU emulator.
265 Next, you must download the filesystem for your target machine’s architecture. 263 Next, you must download and extract the target root filesystem for your target
266 Finally, you set up the environment to emulate the hardware then start the emulator. 264 machine’s architecture.
265 Finally, you set up the environment to emulate the hardware and then start the QEMU emulator.
267 </para> 266 </para>
268 267
269 <para> 268 <para>
270 You can find details on all these steps in the 269 You can find details on all these steps in the
271 <ulink url='http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html#using-pre-built'> 270 "<ulink url='http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
272 Using Pre-Built Binaries and QEMU</ulink> section in the Yocto Project Quick Start. 271 section of the Yocto Project Quick Start.
273 </para> 272 </para>
274</section> 273</section>
275</chapter> 274</chapter>