diff options
Diffstat (limited to 'documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml')
-rw-r--r-- | documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml | 337 |
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>©RIGHT_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 & 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 | <!-- | ||
336 | vim: expandtab tw=80 ts=4 | ||
337 | --> | ||