summaryrefslogtreecommitdiffstats
path: root/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-02-26 13:20:27 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-03-03 08:35:25 +0000
commit92ee38410f9ef0737a425b082783e818c6f6cc5b (patch)
tree48b0194bc47383f4ec0cab8849489bafe1be125d /documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml
parentefc08b7b6f8d5d0d45c2f9ccfaaff897aeed76ce (diff)
downloadpoky-92ee38410f9ef0737a425b082783e818c6f6cc5b.tar.gz
brief-yoctoprojectqs, Makefile: New "First Build" article.
I have created an brief article in the form of current YP docs that is a pared down version of the Quick Start (pre 2.5 release). The article fills a gap for a short (2-page), process-oriented article that steps the user through an initial build using YP. I had to make changes to the Makefile to support building the new article. (From yocto-docs rev: 47aace60cea4a892ae1efabb050b240c6abdaec9) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml')
-rw-r--r--documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml337
1 files changed, 337 insertions, 0 deletions
diff --git a/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml b/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml
new file mode 100644
index 0000000000..da497cc100
--- /dev/null
+++ b/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml
@@ -0,0 +1,337 @@
1<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<article id='brief-yocto-project-qs-intro'>
6 <articleinfo>
7 <title>My First Yocto Project Build</title>
8
9 <copyright>
10 <year>&COPYRIGHT_YEAR;</year>
11 <holder>Linux Foundation</holder>
12 </copyright>
13
14 <legalnotice>
15 <para>
16 Permission is granted to copy, distribute and/or modify this document under
17 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
18 </para>
19 <note><title>Manual Notes</title>
20 <itemizedlist>
21 <listitem><para>
22 For the latest version of this document associated with
23 this Yocto Project release
24 (version &YOCTO_DOC_VERSION;), see the "My First
25 Yocto Project Build" from the
26 <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
27 </para></listitem>
28 <listitem><para>
29 This version of the manual is version
30 &YOCTO_DOC_VERSION;.
31 For later releases of the Yocto Project (if they exist),
32 go to the
33 <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
34 and use the drop-down "Active Releases" button
35 and choose the Yocto Project version for which you want
36 the manual.
37 </para></listitem>
38 </itemizedlist>
39 </note>
40 </legalnotice>
41
42
43 <abstract>
44 <imagedata fileref="figures/yocto-project-transp.png"
45 width="6in" depth="1in"
46 align="right" scale="25" />
47 </abstract>
48 </articleinfo>
49
50 <section id='brief-welcome'>
51 <title>Welcome!</title>
52
53 <para>
54 Welcome!
55 This short document steps you through the process for a typical
56 image build using the Yocto Project.
57 The build uses Poky, which is the reference embedded OS that is
58 completely specified.
59 <note>
60 The examples in this paper assume you are using a native Linux
61 system running a recent Ubuntu Linux distribution.
62 If the machine you want to use
63 Yocto Project on to build an image is not a native Linux
64 system, you can still perform these steps by using CROss
65 PlatformS (CROPS) and setting up a Poky container.
66 See the
67 <ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
68 section in the Yocto Project Development Tasks Manual for more
69 information.
70 </note>
71 </para>
72
73 <para>
74 If you want more conceptual or background information on the
75 Yocto Project, see the
76 <ulink url='&YOCTO_DOCS_GS_URL;'>Getting Started With Yocto Project Manual</ulink>.
77 </para>
78 </section>
79
80 <section id='brief-compatible-distro'>
81 <title>Compatible Linux Distribution</title>
82
83 <para>
84 Make sure your build system meets the following requirements:
85 <itemizedlist>
86 <listitem><para>
87 50 Gbytes of free disk space
88 </para></listitem>
89 <listitem><para>
90 Runs a supported Linux distribution (i.e. recent releases of
91 Fedora, openSUSE, CentOS, Debian, or Ubuntu). For a list of
92 Linux distributions that support the Yocto Project, see the
93 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
94 section in the Yocto Project Reference Manual.
95 </para></listitem>
96 <listitem><para>
97 <itemizedlist>
98 <listitem><para>
99 Git 1.8.3.1 or greater
100 </para></listitem>
101 <listitem><para>
102 tar 1.27 or greater
103 </para></listitem>
104 <listitem><para>
105 Python 3.4.0 or greater.
106 </para></listitem>
107 </itemizedlist>
108 If your build host does not meet any of these three listed
109 version requirements, you can take steps to prepare the
110 system so that you can still use the Yocto Project.
111 See the
112 "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>"
113 section in the Yocto Project Reference Manual for information.
114 </para></listitem>
115 </itemizedlist>
116 </para>
117 </section>
118
119 <section id='brief-build-system-packages'>
120 <title>Build System Packages</title>
121
122 <para>
123 You must install essential host packages on your
124 development host.
125 The following command installs the host packages based on an
126 Ubuntu distribution:
127 <note>
128 For host package requirements on all supported Linux
129 distributions, see the
130 "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
131 section in the Yocto Project Reference Manual.
132 </note>
133 <literallayout class='monospaced'>
134 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm
135 </literallayout>
136 </para>
137 </section>
138
139 <section id='brief-use-git-to-clone-poky'>
140 <title>Use Git to Clone Poky</title>
141
142 <para>
143 Once you complete the setup instructions for your machine,
144 you need to get a copy of the Poky repository on your build
145 system.
146 Use the following commands to clone the Poky
147 repository and then checkout the &DISTRO_REL_TAG; release:
148 <literallayout class='monospaced'>
149 $ git clone git://git.yoctoproject.org/poky
150 Cloning into 'poky'...
151 remote: Counting objects: 361782, done.
152 remote: Compressing objects: 100% (87100/87100), done.
153 remote: Total 361782 (delta 268619), reused 361439 (delta 268277)
154 Receiving objects: 100% (361782/361782), 131.94 MiB | 6.88 MiB/s, done.
155 Resolving deltas: 100% (268619/268619), done.
156 Checking connectivity... done.
157 $ git checkout tags/yocto-2.5 -b my-yocto-2.5
158 </literallayout>
159 The previous Git checkout command creates a local branch
160 named my-&DISTRO_REL_TAG;. The files available to you in that
161 branch exactly match the repository's files in the
162 "&DISTRO_NAME_NO_CAP;" development branch at the time of the
163 Yocto Project &DISTRO; release.
164 </para>
165
166 <para>
167 For more options and information about accessing Yocto
168 Project related repositories, see the
169 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
170 section in the Yocto Project Development Tasks Manual.
171 </para>
172 </section>
173
174 <section id='brief-building-your-image'>
175 <title>Building Your Image</title>
176
177 <para>
178 Use the following steps to build your image.
179 The OpenEmbedded build system creates an entire Linux
180 distribution, including the toolchain, from source.
181 <note>
182 <itemizedlist>
183 <listitem><para>
184 If you are working behind a firewall and your build
185 host is not set up for proxies, you could encounter
186 problems with the build process when fetching source
187 code (e.g. fetcher failures or Git failures).
188 </para></listitem>
189 <listitem><para>
190 If you do not know your proxy settings, consult your
191 local network infrastructure resources and get that
192 information.
193 A good starting point could also be to check your
194 web browser settings.
195 Finally, you can find more information on the
196 "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
197 wiki page.
198 </para></listitem>
199 </itemizedlist>
200 </note>
201 </para>
202
203 <para>
204 <orderedlist>
205 <listitem><para>
206 <emphasis>Initialize the Build Environment:</emphasis>
207 Run the
208 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
209 environment setup script to define the OpenEmbedded
210 build environment on your build host.
211 <literallayout class='monospaced'>
212 $ source &OE_INIT_FILE;
213 </literallayout>
214 Among other things, the script creates the
215 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
216 which is <filename>build</filename> in this case
217 and is located in the
218 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
219 After the script runs, your current working directory
220 is set to the Build Directory.
221 Later, when the build completes, the Build Directory
222 contains all the files created during the build.
223 </para></listitem>
224 <listitem><para>
225 <emphasis>Examine Your Local Configuration File:</emphasis>
226 When you set up the build environment, a local
227 configuration file named
228 <filename>local.conf</filename> becomes available in
229 a <filename>conf</filename> subdirectory of the
230 Build Directory.
231 For this quick start, the defaults are set to build
232 for a <filename>qemux86</filename> target, which is
233 suitable for emulation.
234 The package manager used is set to the RPM package
235 manager.
236 </para></listitem>
237 <listitem><para>
238 <emphasis>Start the Build:</emphasis>
239 Continue with the following command to build an OS image
240 for the target, which is
241 <filename>core-image-sato</filename> in this example:
242 <literallayout class='monospaced'>
243 $ bitbake core-image-sato
244 </literallayout>
245 For information on using the
246 <filename>bitbake</filename> command, see the
247 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#usingpoky-components-bitbake'>BitBake</ulink>"
248 section in the Yocto Project Overview Manual, or
249 see the
250 "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>"
251 section in the BitBake User Manual.
252 </para></listitem>
253 <listitem><para>
254 <emphasis>Simulate Your Image Using QEMU:</emphasis>
255 Once this particular image is built, you can start
256 QEMU, which is a Quick EMUlator that ships with
257 the Yocto Project:
258 <literallayout class='monospaced'>
259 $ runqemu qemux86
260 </literallayout>
261 If you want to learn more about running QEMU, see the
262 "<ulink url="&YOCTO_DOCS_DEV_URL;#dev-manual-qemu">Using the Quick EMUlator (QEMU)</ulink>"
263 chapter in the Yocto Project Development Tasks Manual.
264 </para></listitem>
265 <listitem><para>
266 <emphasis>Exit QEMU:</emphasis>
267 Exit QEMU by either clicking on the shutdown icon or by
268 typing <filename>Ctrl-C</filename> in the QEMU
269 transcript window from which you evoked QEMU.
270 </para></listitem>
271 </orderedlist>
272 </para>
273 </section>
274
275 <section id='brief-where-to-go-next'>
276 <title>Where To Go Next</title>
277
278 <para>
279 Now that you have experienced using the Yocto Project, you might
280 be asking yourself "What now?"
281 The Yocto Project has many sources of information including
282 the website, wiki pages, and user manuals:
283 <itemizedlist>
284 <listitem><para>
285 <emphasis>Website:</emphasis>
286 The
287 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
288 provides background information, the latest builds,
289 breaking news, full development documentation, and
290 access to a rich Yocto Project Development Community
291 into which you can tap.
292 </para></listitem>
293 <listitem><para>
294 <emphasis>Developer Screencast:</emphasis>
295 The
296 <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New Developer Screencast Tutorial</ulink>
297 provides a 30-minute video created for users unfamiliar
298 with the Yocto Project but familiar with Linux build
299 hosts.
300 While this screencast is somewhat dated, the
301 introductory and fundamental concepts are useful for
302 the beginner.
303 </para></listitem>
304 <listitem><para>
305 <emphasis>Yocto Project Wiki:</emphasis>
306 The
307 <ulink url='&YOCTO_WIKI_URL;'>Yocto Project Wiki</ulink>
308 provides additional information on where to go next
309 when ramping up with the Yocto Project, release
310 information, project planning, and QA information.
311 </para></listitem>
312 <listitem><para>
313 <emphasis>Yocto Project Mailing Lists:</emphasis>
314 Related mailing lists provide a forum for discussion,
315 patch submission and announcements.
316 Several mailing lists exist and are grouped according
317 to areas of concern.
318 See the
319 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
320 section in the Yocto Project Reference Manual for a
321 complete list of Yocto Project mailing lists.
322 </para></listitem>
323 <listitem><para>
324 <emphasis>Comprehensive List of Links and Other Documentation:</emphasis>
325 The
326 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"
327 section in the Yocto Project Reference Manual provides a
328 comprehensive list of all related links and other
329 user documentation.
330 </para></listitem>
331 </itemizedlist>
332 </para>
333 </section>
334</article>
335<!--
336vim: expandtab tw=80 ts=4
337-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-09 21:54:07 +0000