summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorRichard Purdie <rpurdie@linux.intel.com>2010-10-15 15:14:06 +0100
committerRichard Purdie <rpurdie@linux.intel.com>2010-10-27 07:50:33 +0100
commit4999f788740b5cb2c4490c86e44ab5eac7b3dfe0 (patch)
treefd578c3315dcc30a0389ef55b3261491bbeb45e0 /documentation
parent00e061b56455e8bc6ab937a8114386f921f53fa5 (diff)
downloadpoky-4999f788740b5cb2c4490c86e44ab5eac7b3dfe0.tar.gz
documentation/pokt-ref-manual: Update with Yocto branding
Signed-off-by: Richard Purdie <rpurdie@linux.intel.com>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/poky-ref-manual/Makefile2
-rw-r--r--documentation/poky-ref-manual/development.xml410
-rwxr-xr-xdocumentation/poky-ref-manual/figures/cropped-yocto-project-bw.pngbin0 -> 5453 bytes
-rwxr-xr-xdocumentation/poky-ref-manual/figures/yocto-project-transp.pngbin0 -> 8626 bytes
-rw-r--r--documentation/poky-ref-manual/introduction.xml258
-rw-r--r--documentation/poky-ref-manual/poky-ref-manual.xml13
-rw-r--r--documentation/poky-ref-manual/style.css9
-rwxr-xr-xdocumentation/poky-ref-manual/white-on-black-yp.pngbin0 -> 9584 bytes
-rw-r--r--documentation/template/yocto-project-qs.pngbin0 -> 17829 bytes
9 files changed, 281 insertions, 411 deletions
diff --git a/documentation/poky-ref-manual/Makefile b/documentation/poky-ref-manual/Makefile
index 22913e1554..dfd44efd30 100644
--- a/documentation/poky-ref-manual/Makefile
+++ b/documentation/poky-ref-manual/Makefile
@@ -23,7 +23,7 @@ html:
23 xsltproc $(XSLTOPTS) -o bsp-guide.html $(XSL_XHTML_URI) bsp-guide.xml 23 xsltproc $(XSLTOPTS) -o bsp-guide.html $(XSL_XHTML_URI) bsp-guide.xml
24 24
25tarball: html 25tarball: html
26 tar -cvzf poky-ref-manual.tgz poky-ref-manual.html style.css screenshots/ss-sato.png poky-beaver.png poky-ref-manual.png 26 tar -cvzf poky-ref-manual.tgz poky-ref-manual.html style.css figures/yocto-project-transp.png
27 27
28validate: 28validate:
29 xmllint --postvalid --xinclude --noout poky-ref-manual.xml 29 xmllint --postvalid --xinclude --noout poky-ref-manual.xml
diff --git a/documentation/poky-ref-manual/development.xml b/documentation/poky-ref-manual/development.xml
index 921943c155..60fb984e44 100644
--- a/documentation/poky-ref-manual/development.xml
+++ b/documentation/poky-ref-manual/development.xml
@@ -41,181 +41,253 @@
41 </para> 41 </para>
42 </section> 42 </section>
43 43
44 <section id="platdev-appdev-external-anjuta"> 44 <section id="using-the-eclipse-and-anjuta-plug-ins">
45 <title>Developing externally using the Anjuta plugin</title> 45 <title>Using the Eclipse and Anjuta Plug-ins</title>
46
47 <para>
48 An Anjuta IDE plugin exists to make developing software within the Poky framework
49 easier for the application developer. It presents a graphical IDE from which the
50 developer can cross compile an application then deploy and execute the output in a QEMU
51 emulation session. It also supports cross debugging and profiling.
52 </para>
53<!-- DISBALED, TOO BIG!
54 <screenshot>
55 <mediaobject>
56 <imageobject>
57 <imagedata fileref="screenshots/ss-anjuta-poky-1.png" format="PNG"/>
58 </imageobject>
59 <caption>
60 <para>The Anjuta Poky SDK plugin showing an active QEMU session running Sato</para>
61 </caption>
62 </mediaobject>
63 </screenshot>
64-->
65 <para>
66 To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta it's development
67 headers and the Anjuta plugin. The Poky Anjuta plugin is available to download as a tarball at the
68 <ulink url='http://labs.o-hand.com/anjuta-poky-sdk-plugin/'>OpenedHand labs</ulink> page or
69 directly from the Poky Git repository located at git://git.pokylinux.org/anjuta-poky; a web interface
70 to the repository can be accessed at <ulink url='http://git.pokylinux.org/?p=anjuta-poky.git;a=summary'/>.
71 </para>
72 <para> 46 <para>
73 See the README file contained in the project for more information on dependencies and building 47 Yocto Project supports both Anjuta and Eclipse IDE plug-ins to make developing software
74 the plugin. If you want to disable remote gdb debugging, please pass --diable-gdb-integration 48 easier for the application developer. The plug-ins provide capability
75 switch when doing configure. 49 extensions to the graphical IDE allowing for cross compilation,
50 deployment and execution of the output in a QEMU emulation session.
51 Support of these plug-ins also supports cross debugging and
52 profiling. Additionally, the Eclipse plug-in provides a suite of tools
53 that allows the developer to perform remote profiling, tracing, collection of
54 power data, collection of latency data and collection of performance data.
76 </para> 55 </para>
77 56
78 <section id="platdev-appdev-external-anjuta-setup"> 57 <section id="the-eclipse-plug-in">
79 <title>Setting up the Anjuta plugin</title> 58 <title>The Eclipse Plug-in</title>
80 59 <para>
81 <para>Extract the tarball for the toolchain into / as root. The 60 To use the Eclipse plug-in, a toolchain and SDK built by Poky is required along with
82 toolchain will be installed into 61 the Eclipse Framework (Helios 3.6).
83 <filename class="directory">/opt/poky</filename>.</para> 62 To install the plug-in you need to be in the Eclipse IDE and select
84 63 the following menu:
85 <para>To use the plugin, first open or create an existing 64 <literallayout class='monospaced'>
86 project. If creating a new project the "C GTK+" project type 65 Help -> Install New Software
87 will allow itself to be cross-compiled. However you should be 66 </literallayout>
88 aware that this uses glade for the UI.</para> 67 Specify the target URL as http://yocto./download (real link needed).
89 68 </para>
90 <para>To activate the plugin go to 69 <para>
91 <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>, 70 If you want to download the source code for the plug-in you can find it in the Poky
92 then choose <guilabel>General</guilabel> from the left hand side. Choose the 71 git repository, which has a web interface, and is located at
93 Installed plugins tab, scroll down to <guilabel>Poky 72 <ulink url="http://git.pokylinux.org/cgit.cgi/eclipse-poky"></ulink>.
94 SDK</guilabel> and check the 73 </para>
95 box. The plugin is now activated but first it must be 74
96 configured.</para> 75 <section id="installing-and-setting-up-the-eclipse-ide">
97 </section> 76 <title>Installing and Setting up the Eclipse IDE</title>
98 77 <para>
99 <section id="platdev-appdev-external-anjuta-configuration"> 78 If you don't have the Eclipse IDE (Helios 3.6) on your system you need to
100 <title>Configuring the Anjuta plugin</title> 79 download and install it from <ulink url="http://www.eclipse.org/downloads"></ulink>.
101 80 Choose the Eclipse Classic, which contains the Eclipse Platform, Java Development
102 <para>The configuration options for the SDK can be found by choosing 81 Tools (JDT), and the Plug-in Development Environment.
103 the <guilabel>Poky SDK</guilabel> icon from the left hand side. The following options 82 </para>
104 need to be set:</para> 83 <para>
105 84 NOTE: Due to the Java Virtual Machine's garbage collection (GC) process the
106 <itemizedlist> 85 permanent generation space (PermGen) is not cleaned up. This space is used
107 86 to store meta-data descriptions of classes. The default value is set too small
108 <listitem><para><guilabel>SDK root</guilabel>: If we use external toolchain, we need to set SDK root. 87 and it could trigger an out of memory error like the following:
109 this is the root directory of the SDK's sysroot. For an i586 SDK this will be <filename 88 <literallayout class='monospaced'>
110 class="directory">/opt/poky/</filename>. 89 Java.lang.OutOfMemoryError: PermGen space
111 This directory will contain directories named like "bin", 90 </literallayout>
112 "include", "var", etc. under your selected target architecture subdirectory<filename class="directory"> 91 This error causes the applications to hang.
113 /opt/poky/sysroot/i586-poky-linux/</filename>. Needed cross compile tools are under 92 </para>
114 <filename class ="directory">/opt/poky/sysroot/i586-pokysdk-linux/</filename> 93 <para>
115 </para></listitem> 94 To fix this issue you can use the <command>-vmargs</command>
116 95 option when you start Eclipse to increase the size of the permenant generation space:
117 <listitem><para><guilabel>Poky root</guilabel>: If we have local poky build tree, we need to set the Poky root. 96 <literallayout class='monospaced'>
118 this is the root directory of the poky build tree, if you build your i586 target architecture 97 Eclipse -vmargs -XX:PermSize=256M
119 under the subdirectory of build_x86 within your poky tree, the Poky root directory should be 98 </literallayout>
120 <filename class="directory">${Poky_tree}/build_x86/</filename>. 99 </para>
121 </para></listitem> 100 <para>
122 101 The Eclipse plug-in depends several Eclipse projects plug-ins:
123 <listitem><para><guilabel>Target Architecture</guilabel>: this is the cross compile 102 Eclipse C/C++ Development Tools (CDT), Autotools support for CDT (Incubation) and Target
124 triplet, e.g. "i586-poky-linux". This target triplet is the prefix extracted from 103 Management (RSE).
125 the set up script file name. For examle, "i586-poky-linux" is extracted from set up script file 104 </para>
126 <filename>/opt/poky/environment-setup-i586-poky-linux</filename> 105 <para>
127 </para></listitem> 106 After installing Eclipse and bringing up the IDE for the first
128 107 time you need to be sure the following four sites are available by adding them.
129 <listitem><para><guilabel>Kernel</guilabel>: use the file chooser to select the kernel 108 </para>
130 to use with QEMU</para></listitem> 109 <itemizedlist>
131 110 <listitem>CDT - http://download.eclipse.org/tools/cdt/releases/helios</listitem>
132 <listitem><para><guilabel>Root filesystem</guilabel>: use the file chooser to select 111 <listitem>Helios - http://download.eclipse.org/releases/helios</listitem>
133 the root filesystem directory, this is the directory where you use "poky-extract-sdk" command to 112 <listitem>Target Management
134 extract the poky-image-sdk tarball.</para></listitem> 113 3.2 Updates - http://download.eclipse.org/dsdp/tm/updates/3.2</listitem>
135 </itemizedlist> 114 <listitem>The Eclipse Project Updates -
136<!-- DISBALED, TOO BIG! 115 http://download.eclipse.org/eclipse/updates/3.6</listitem>
137 <screenshot> 116 </itemizedlist>
138 <mediaobject> 117 <para>
139 <imageobject> 118 Once these sites are available do the following:
140 <imagedata fileref="screenshots/ss-anjuta-poky-2.png" format="PNG"/> 119 <itemizedlist>
141 </imageobject> 120 <listitem>Use the "Work with:" drop down list and
142 <caption> 121 select "All Available Sites--"</listitem>
143 <para>Anjuta Preferences Dialog</para> 122 <listitem><emphasis>For CDT and Autotools support:</emphasis> Expand the
144 </caption> 123 "Programming Languages" list and select "Autotools support for CDT
145 </mediaobject> 124 (Incubation)" and "C/C++ Development Tools". Click "Next" and complete
146 </screenshot> 125 the update.</listitem>
147--> 126 <listitem><emphasis>For RSE support:</emphasis> Select "TM and
127 RSE Main Features". Click "Next" and complete the update.</listitem>
128 </itemizedlist>
129 </para>
130 </section>
148 131
132 <section id="installing-the-yocto-plug-in">
133 <title>Installing the Yocto Plug-in</title>
134 <para>
135 Once you have the Eclipse IDE installed and configure you need to install the
136 Yocto plug-in. You do this similar to installing the Eclipse plug-ins in the
137 previous section.
138 </para>
139 <para>
140 Do the following to install the Yocto plug-in into the Eclipse IDE:
141 <itemizedlist>
142 <listitem>Select the "Help -> Install New Software" item.</listitem>
143 <listitem>In the "Work with:" area click "Add..." and enter the URL for
144 the Yocto plug-in (we need to supply this URL).</listitem>
145 <listitem>Finish out the installation of the update similar to any other
146 Eclipse plug-in.</listitem>
147 </itemizedlist>
148 </para>
149 </section>
150
151 <section id="configuring-yocto-eclipse-plug-in">
152 <title>Configuring Yocto Eclipse plug-in</title>
153 <para>
154 To configure the Yocto Eclipse plug-in you need to select the mode and then the
155 architecture with which you will be working. Start by selecting "Preferences"
156 from the "Window" menu and then selecting "Yocto SDK".
157 </para>
158 <para>
159 If you normally will use an installed Yocto
160 SDK (under /opt/poky) select “SDK Root Mode”. Otherwise, if your crosstool chain
161 and sysroot are within your poky tree, select “Poky Tree Mode”.
162 If you are in SDK Root Mode you will need to provide your poky tree path, for
163 example, $&lt;Poky_tree&gt;/build/.
164 </para>
165 <para>
166 Now you need to select the architecture.
167 Use the drop down list and select the architecture that you’ll be primarily
168 working against.
169 For target option, select your typical target QEMU vs External HW. If you
170 choose QEMU, you’ll need to specify your QEMU kernel file with full path and the
171 rootfs mount point. Yocto QEMU boots off user mode NFS, Please refer to QEMU
172 section for how to set it up. (Section TBD)
173 </para>
174 <para>
175 Save all your settings and they become your defaults for every new Yocto project
176 created using the Eclipse IDE.
177 </para>
178 </section>
179
180 <section id="using-the-yocto-eclipse-plug-in">
181 <title>Using the Yocto Eclipse Plug-in</title>
182 <para>
183 As an example, this section shows you how to cross-compile a Yocto C autotools
184 based project, deploy it into QEMU, and then run the debugger against it.
185 You need to configure the project, trigger <command> autogen.sh</command>, build
186 the image, start QEMU, and then debug.
187 </para>
188 <orderedlist>
189 <listitem>Creating a Yocto Autotools Based Project Using a Template:
190 Get to the Wizard selection by selecting the File -> New -> Project
191 menu. Expand "C/C++" and select "C Project". Click "Next" and select a template
192 to start with, for example "Hello World ANSI C Project". Complete the steps
193 to create a new Yocto autotools based project using this template.</listitem>
194 <listitem>Specify Specific Toolchain Configurations: By default the project
195 uses the Yocto preferences settings as defined using the procedure in
196 <link linkend="configuring-yocto-eclipse-plug-in"> the previous section</link>.
197 If there are any specific setup requirements for the newly created project
198 you need to reconfigure the Yocto plug-in through the menu selection
199 Project -> Invoke Yocto Tools -> Reconfigure Yocto. Use this dialogue
200 to specify specific toolchain and QEMU setups for the project.</listitem>
201 <listitem>Building the Project: Trigger <command>autogen.sh</command> through
202 Project -> Reconfigure Project. Then build the project using
203 Project -> Build.</listitem>
204 <listitem>Starting QEMU: Use the Run -> External Tools menu and see if there is
205 a QEMU instance for the desired target. If there is click on the instance
206 to start QEMU. If your target is not there then click "External Tools
207 Configuration". You should find an instance of QEMU for your architecture
208 under the entry under "Program". After the boot completes you are ready to
209 deploy the image into QEMU.</listitem>
210 <listitem>Debugging: To bring up your remote debugging configuration in the
211 right-hand window highlight your project in “Project Explorer”, select
212 the Run -> Debug Configurations menu item and expand “C/C++ Remote Application”.
213 Next, select projectname_ gdb_target-poky-linux.
214 You need to be sure that there is an
215 entry for the remote target you want to deploy and cross debug with. If there
216 is no entry then click "New..." to bring up the wizard. Using the wizard
217 select TCF and enter the IP address of you remote target in the
218 “Host name:” field. Back in the remote debug configure window,
219 you need to specify the absolute path for the program on the remote target
220 in the “Remote Absolute File Path for C/C++ Application” field. By default,
221 the program deploys into the remote target. If you don't want this then check
222 “Skip download to target path”. Finally, click "Debug” to start the remote
223 debugging session.</listitem>
224 </orderedlist>
225 </section>
226
227 <section id="using-yocto-eclipse-plug-in-remote-tools-suite">
228 <title>Using Yocto Eclipse plug-in Remote Tools Suite</title>
229 <para>
230 Remote tools let you do things like perform system profiling, kernel tracing,
231 examine power consumption, and so forth. To see and access the remote tools use the
232 Window -> YoctoTools menu.
233 </para>
234 <para>
235 Once you pick a tool you need to configure it for the remote target. Every tool
236 needs to have the connection configured. You have to select an existing TCF-based
237 RSE connection to the remote target. If one does not exist you need to create one
238 by clicking "New"
239 </para>
240 <para>
241 Here are some specifics about the remote tools:
242 <itemizedlist>
243 <listitem>Oprofile: Selecting this tool causes the oprofile-server on the remote
244 target to launch on the local host machine. To use the oprofile the oprofile-viewer
245 must be installed on the local host machine and the oprofile-server must be
246 installed on the remote target.</listitem>
247 <listitem>lttng: Selecting this tool runs ustrace on the remote target, transfers
248 the output data back to the local host machine and uses lttv-gui to graphically
249 display the output. To use this tool the lttv-gui must be installed on the
250 local host machine. See <ulink url="http://lttng.org/files/ust/manual/ust.html">
251 </ulink> for information on how to use <command>lttng</command> to trace an
252 application.
253 <para>
254 For "Application" you must supply the absolute path name to the application to
255 be traced by user mode lttng. For example, typing <command>/path/to/foo"
256 </command> triggers <command>usttrace /path/to/foo</command> on the
257 remote target to trace the program <command>/path/to/foo</command>.
258 </para>
259 <para>
260 "Argument" is passed to "usttrace" running on the remote target.
261 </para>
262 </listitem>
263 <listitem>powertop: Selecting this tool runs <command>powertop</command> on the
264 remote target machine and displays the result in a new view called "powertop".
265 <para>
266 "Time to gather data(sec):" is the time passed in seconds before data is
267 gathered from the remote target for analysis.
268 </para>
269 <para>
270 "show pids in wakeups list:" corresponds to the <command>-p</command>
271 argument passed to <command>powertop</command>
272 </para>
273 </listitem>
274 <listitem>latencytop and perf: The <command>latencytop</command> identifies
275 system latency, while <command>perf</command> monitors the system's performance
276 counter registers. Selecting either of these tools causes an RSE
277 terminal view to appear in which you can run the tools. Both tools refresh the
278 entire screen to display results while they run.</listitem>
279 </itemizedlist>
280 </para>
281 </section>
149 </section> 282 </section>
150 283
151 <section id="platdev-appdev-external-anjuta-usage"> 284 <section id="external-development-using-the-anjuta-plug-in">
152 <title>Using the Anjuta plugin</title> 285 <title>External Development Using the Anjuta Plug-in</title>
153 286 <para>
154 <para>As an example, cross-compiling a project, deploying it into 287 (Note: We will stop Anjuta plug-in support after Yocto project 0.9 release. Its source
155 QEMU and running a debugger against it and then doing a system 288 code can be downloaded from git respository listed below, and free for the community to
156 wide profile.</para> 289 continue supporting it moving forward.)
157 290 </para>
158 <para>Choose <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
159 Configure</guimenuitem></menuchoice> or
160 <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
161 Autogenerate</guimenuitem></menuchoice> to run "configure"
162 (or to run "autogen") for the project. This passes command line
163 arguments to instruct it to cross-compile.</para>
164
165 <para>Next do
166 <menuchoice><guimenu>Build</guimenu><guimenuitem>Build
167 Project</guimenuitem></menuchoice> to build and compile the
168 project. If you have previously built the project in the same
169 tree without using the cross-compiler you may find that your
170 project fails to link. Simply do
171 <menuchoice><guimenu>Build</guimenu><guimenuitem>Clean
172 Project</guimenuitem></menuchoice> to remove the old
173 binaries. You may then try building again.</para>
174
175 <para>Next start QEMU by using
176 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Start
177 QEMU</guimenuitem></menuchoice>, this will start QEMU and
178 will show any error messages in the message view. Once Poky has
179 fully booted within QEMU you may now deploy into it.</para>
180
181 <para>Once built and QEMU is running, choose
182 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Deploy</guimenuitem></menuchoice>,
183 this will install the package into a temporary directory and
184 then copy using rsync over SSH into the target. Progress and
185 messages will be shown in the message view.</para>
186
187 <para>To debug a program installed into onto the target choose
188 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Debug
189 remote</guimenuitem></menuchoice>. This prompts for the
190 local binary to debug and also the command line to run on the
191 target. The command line to run should include the full path to
192 the to binary installed in the target. This will start a
193 gdbserver over SSH on the target and also an instance of a
194 cross-gdb in a local terminal. This will be preloaded to connect
195 to the server and use the <guilabel>SDK root</guilabel> to find
196 symbols. This gdb will connect to the target and load in
197 various libraries and the target program. You should setup any
198 breakpoints or watchpoints now since you might not be able to
199 interrupt the execution later. You may stop
200 the debugger on the target using
201 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Stop
202 debugger</guimenuitem></menuchoice>.</para>
203
204 <para>It is also possible to execute a command in the target over
205 SSH, the appropriate environment will be be set for the
206 execution. Choose
207 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Run
208 remote</guimenuitem></menuchoice> to do this. This will open
209 a terminal with the SSH command inside.</para>
210
211 <para>To do a system wide profile against the system running in
212 QEMU choose
213 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Profile
214 remote</guimenuitem></menuchoice>. This will start up
215 OProfileUI with the appropriate parameters to connect to the
216 server running inside QEMU and will also supply the path to the
217 debug information necessary to get a useful profile.</para>
218
219 </section> 291 </section>
220 </section> 292 </section>
221 293
diff --git a/documentation/poky-ref-manual/figures/cropped-yocto-project-bw.png b/documentation/poky-ref-manual/figures/cropped-yocto-project-bw.png
new file mode 100755
index 0000000000..561333b146
--- /dev/null
+++ b/documentation/poky-ref-manual/figures/cropped-yocto-project-bw.png
Binary files differ
diff --git a/documentation/poky-ref-manual/figures/yocto-project-transp.png b/documentation/poky-ref-manual/figures/yocto-project-transp.png
new file mode 100755
index 0000000000..31d2b147fd
--- /dev/null
+++ b/documentation/poky-ref-manual/figures/yocto-project-transp.png
Binary files differ
diff --git a/documentation/poky-ref-manual/introduction.xml b/documentation/poky-ref-manual/introduction.xml
index 2683d01f22..301086a824 100644
--- a/documentation/poky-ref-manual/introduction.xml
+++ b/documentation/poky-ref-manual/introduction.xml
@@ -4,43 +4,39 @@
4<chapter id='intro'> 4<chapter id='intro'>
5<title>Introduction</title> 5<title>Introduction</title>
6 6
7<section id='intro-what-is'> 7<section id='intro-welcome'>
8 <title>What is Poky?</title> 8 <title>Welcome to Poky!</title>
9 9
10 <para> 10 <para>
11 Poky is the the build tool in Yocto Project.
12 It is at the heart of Yocto Project.
13 You use Poky within Yocto Project to build the images (kernel software) for targeted hardware.
14 </para>
11 15
12 Poky is an open source platform build tool. It is a complete 16 <para>
13 software development environment for the creation of Linux 17 Before jumping into Poky you should have an understanding of Yokto Project.
14 devices. It aids the design, development, building, debugging, 18 Be sure you are familiar with the information in the Yocto Project Quick Start.
15 simulation and testing of complete modern software stacks 19 You can find this documentation on the public <ulink rul='http://yoctoproject.org/'>Yocto Project Website</ulink>.
16 using Linux, the X Window System and GNOME Mobile
17 based application frameworks. It is based on <ulink
18 url='http://openembedded.org/'>OpenEmbedded</ulink> but has
19 been customised with a particular focus.
20
21 </para> 20 </para>
21</section>
22 22
23 <para> Poky was setup to:</para> 23<section>
24 <title>What is Poky?</title>
24 25
25 <itemizedlist> 26 <para>
26 <listitem> 27 Poky provides an open source Linux, X11, Matchbox, GTK+, Pimlico, Clutter, and other <ulink url='http://gnome.org/mobile'>GNOME Mobile</ulink> technologies based full platform build tool within Yocto Project.
27 <para>Provide an open source Linux, X11, Matchbox, GTK+, Pimlico, Clutter, and other <ulink url='http://gnome.org/mobile'>GNOME Mobile</ulink> technologies based full platform build and development tool.</para> 28 It creates a focused, stable, subset of OpenEmbedded that can be easily and reliably built and developed upon.
28 </listitem> 29 Poky fully supports a wide range of x86 ARM, MIPS and PowerPC hardware and device virtulisation.
29 <listitem> 30 </para>
30 <para>Create a focused, stable, subset of OpenEmbedded that can be easily and reliably built and developed upon.</para>
31 </listitem>
32 <listitem>
33 <para>Fully support a wide range of x86, ARM, MIPS, PowerPC hardware and device virtulisation</para>
34 </listitem>
35 </itemizedlist>
36 31
37 <para> 32 <para>
38 Poky is primarily a platform builder which generates filesystem images 33 Poky is primarily a platform builder which generates filesystem images
39 based on open source software such as the Kdrive X server, the Matchbox 34 based on open source software such as the Kdrive X server, the Matchbox
40 window manager, the GTK+ toolkit and the D-Bus message bus system. Images 35 window manager, the GTK+ toolkit and the D-Bus message bus system. Images
41 for many kinds of devices can be generated, however the standard example 36 for many kinds of devices can be generated, however the standard example
42 machines target QEMU full system emulation(x86, ARM, MIPS and PowerPC) and the ARM based 37 machines target QEMU full system emulation(x86, ARM, MIPS and PowerPC) and
43 Sharp Zaurus series of devices. Poky's ability to boot inside a QEMU 38 real reference boards for each of these architectures.
39 Poky's ability to boot inside a QEMU
44 emulator makes it particularly suitable as a test platform for development 40 emulator makes it particularly suitable as a test platform for development
45 of embedded software. 41 of embedded software.
46 </para> 42 </para>
@@ -76,222 +72,32 @@
76 72
77<section id='intro-manualoverview'> 73<section id='intro-manualoverview'>
78 <title>Documentation Overview</title> 74 <title>Documentation Overview</title>
79
80 <para> 75 <para>
81 The handbook is split into sections covering different aspects of Poky. 76 The Poky User Guide is split into sections covering different aspects of Poky.
82 The <link linkend='usingpoky'>'Using Poky' section</link> gives an overview 77 The <link linkend='usingpoky'>'Using Poky' section</link> gives an overview of the components that make up Poky followed by information about using Poky and debugging images created in Yocto Project.
83 of the components that make up Poky followed by information about using and 78 The <link linkend='extendpoky'>'Extending Poky' section</link> gives information about how to extend and customise Poky along with advice on how to manage these changes.
84 debugging the Poky build system. The <link linkend='extendpoky'>'Extending Poky' section</link> 79 The <link linkend='platdev'>'Platform Development with Poky' section</link> gives information about interaction between Poky and target hardware for common platform development tasks such as software development, debugging and profiling.
85 gives information about how to extend and customise Poky along with advice 80 The rest of the manual consists of several reference sections each giving details on a specific section of Poky functionality.
86 on how to manage these changes.
87 The <link linkend='bsp'>'Board Support Packages (BSP) - Developers Guide' section</link>
88 gives information about how to develop BSP such as the common layout, the
89 software hardware configuration options etc.
90 The <link linkend='platdev'>'Platform Development with Poky'
91 section</link> gives information about interaction between Poky and target
92 hardware for common platform development tasks such as software development,
93 debugging and profiling. The rest of the manual
94 consists of several reference sections each giving details on a specific
95 section of Poky functionality.
96 </para> 81 </para>
97 82
98 <para> 83 <para>
99 This manual applies to Poky Release 3.3 (Green). 84 This manual applies to Poky Release 3.3 (Green).
100 </para> 85 </para>
101
102</section> 86</section>
103 87
104 88
105<section id='intro-requirements'> 89<section id='intro-requirements'>
106 <title>System Requirements</title> 90 <title>System Requirements</title>
107
108 <para> 91 <para>
109 We recommend Debian-based distributions, in particular a recent Ubuntu 92 We recommend Debian-based distributions, in particular a recent Ubuntu
110 release (10.04 or newer), as the host system for Poky. Nothing in Poky is 93 release (10.04 or newer), as the host system for Poky. Nothing in Poky is
111 distribution specific and 94 distribution specific and other distributions will most likely work as long
112 other distributions will most likely work as long as the appropriate 95 as the appropriate prerequisites are installed - we know of Poky being used
113 prerequisites are installed - we know of Poky being used successfully on Redhat, 96 successfully on Redhat, SUSE, Gentoo and Slackware host systems.
114 SUSE, Gentoo and Slackware host systems. 97 For information on what you need to develop images using Yocto Project and Poky
98 you should see the Yocto Project Quick Start on the public
99 <ulink rul='http://yoctoproject.org/'>Yocto Project Website</ulink>.
115 </para> 100 </para>
116
117 <para>On a Debian-based system, you need the following packages installed:</para>
118
119 <itemizedlist>
120 <listitem>
121 <para>build-essential</para>
122 </listitem>
123 <listitem>
124 <para>python (version 2.6 or later)</para>
125 </listitem>
126 <listitem>
127 <para>diffstat</para>
128 </listitem>
129 <listitem>
130 <para>texinfo</para>
131 </listitem>
132 <listitem>
133 <para>texi2html</para>
134 </listitem>
135 <listitem>
136 <para>cvs</para>
137 </listitem>
138 <listitem>
139 <para>subversion</para>
140 </listitem>
141 <listitem>
142 <para>wget</para>
143 </listitem>
144 <listitem>
145 <para>gawk</para>
146 </listitem>
147 <listitem>
148 <para>help2man</para>
149 </listitem>
150 <listitem>
151 <para>chrpath</para>
152 </listitem>
153 <listitem>
154 <para>mercurial</para>
155 </listitem>
156 </itemizedlist>
157 <para>Furthermore if you wish to run an emulated Poky image using <ulink url='http://qemu.org'>QEMU</ulink> (as in the quickstart below) you will need the following packages installed:</para>
158 <itemizedlist>
159 <listitem>
160 <para>libgl1-mesa-dev</para>
161 </listitem>
162 <listitem>
163 <para>libglu1-mesa-dev</para>
164 </listitem>
165 <listitem>
166 <para>libsdl1.2-dev</para>
167 </listitem>
168 <listitem>
169 <para>bochsbios (only to run qemux86 images)</para>
170 </listitem>
171 </itemizedlist>
172
173 <para>
174 Debian users can add debian.o-hand.com to their APT sources (See
175 <ulink url='http://debian.o-hand.com'/>
176 for instructions on doing this) and then run <command>
177 "apt-get install qemu poky-depends poky-scripts"</command> which will
178 automatically install all these dependencies. Virtualisation images with
179 Poky and all dependencies can also easily be built if required.
180 </para>
181
182 <para>
183 Poky can use a system provided QEMU or build its own depending on how it's
184 configured. See the options in <filename>local.conf</filename> for more details.
185 </para>
186</section>
187
188<section id='intro-quickstart'>
189 <title>Quick Start</title>
190
191 <section id='intro-quickstart-build'>
192 <title>Building and Running an Image</title>
193
194 <para>
195 If you want to try Poky, you can do so in a few commands. The example below
196 checks out the Poky source code, sets up a build environment, builds an
197 image and then runs that image under the QEMU emulator in x86 system emulation mode:
198 </para>
199
200 <para>
201 <literallayout class='monospaced'>
202$ wget http://pokylinux.org/releases/poky-green-3.3.tar.bz2
203$ tar xjvf poky-green-3.3.tar.bz2
204$ cd green-3.3/
205$ source poky-init-build-env
206$ bitbake poky-image-sato
207$ bitbake qemu-native
208$ runqemu qemux86
209</literallayout>
210 </para>
211
212 <note>
213 <para>
214 This process will need Internet access, about 20 GB of disk space
215 available, and you should expect the build to take about 4 - 5 hours since
216 it is building an entire Linux system from source including the toolchain!
217 </para>
218 </note>
219
220 <para>
221 To build for other machines see the <glossterm><link
222 linkend='var-MACHINE'>MACHINE</link></glossterm> variable in build/conf/local.conf.
223 This file contains other useful configuration information and the default version
224 has examples of common setup needs and is worth
225 reading. To take advantage of multiple processor cores to speed up builds for example, set the
226 <glossterm><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm>
227 and <glossterm><link linkend='var-PARALLEL_MAKE'>PARALLEL_MAKE</link></glossterm> variables.
228
229 The images/kernels built by Poky are placed in the <filename class="directory">tmp/deploy/images</filename>
230 directory.
231 </para>
232
233 <para>
234 You could also run <command>"poky-qemu zImage-qemuarm.bin poky-image-sato-qemuarm.ext2"
235 </command> within the images directory if you have the poky-scripts Debian package
236 installed from debian.o-hand.com. This allows the QEMU images to be used standalone
237 outside the Poky build environment.
238 </para>
239 <para>
240 To setup networking within QEMU see the <link linkend='usingpoky-install-qemu-networking'>
241 QEMU/USB networking with IP masquerading</link> section.
242 </para>
243
244 </section>
245 <section id='intro-quickstart-qemu'>
246 <title>Downloading and Using Prebuilt Images</title>
247
248 <para>
249 Prebuilt images from Poky are also available if you just want to run the system
250 under QEMU. To use these you need to:
251 </para>
252
253 <itemizedlist>
254 <listitem>
255 <para>
256 Add debian.o-hand.com to your APT sources (See
257 <ulink url='http://debian.o-hand.com'/> for instructions on doing this)
258 </para>
259 </listitem>
260 <listitem>
261 <para>Install patched QEMU and poky-scripts:</para>
262 <para>
263 <literallayout class='monospaced'>
264$ apt-get install qemu poky-scripts
265</literallayout>
266 </para>
267 </listitem>
268
269 <listitem>
270 <para>
271 Download a Poky QEMU release kernel (*zImage*qemu*.bin) and compressed
272 filesystem image (poky-image-*-qemu*.ext2.bz2) which
273 you'll need to decompress with 'bzip2 -d'. These are available from the
274 <ulink url='http://pokylinux.org/releases/green-3.3/'>last release</ulink>
275 or from the <ulink url='http://autobuilder.pokylinux.org/'>autobuilder</ulink>.
276 </para>
277 </listitem>
278 <listitem>
279 <para>Start the image:</para>
280 <para>
281 <literallayout class='monospaced'>
282$ poky-qemu &lt;kernel&gt; &lt;image&gt;
283</literallayout>
284 </para>
285 </listitem>
286 </itemizedlist>
287
288 <note><para>
289 A patched version of QEMU is required at present. A suitable version is available from
290 <ulink url='http://debian.o-hand.com'/>, it can be built
291 by poky (bitbake qemu-native) or can be downloaded/built as part of the toolchain/SDK tarballs.
292 </para></note>
293
294 </section>
295</section> 101</section>
296 102
297<section id='intro-getit'> 103<section id='intro-getit'>
diff --git a/documentation/poky-ref-manual/poky-ref-manual.xml b/documentation/poky-ref-manual/poky-ref-manual.xml
index 952b5d602f..a6f095c9ca 100644
--- a/documentation/poky-ref-manual/poky-ref-manual.xml
+++ b/documentation/poky-ref-manual/poky-ref-manual.xml
@@ -6,17 +6,10 @@
6 xmlns="http://docbook.org/ns/docbook" 6 xmlns="http://docbook.org/ns/docbook"
7 > 7 >
8 <bookinfo> 8 <bookinfo>
9
10 <mediaobject>
11 <imageobject>
12 <imagedata fileref='poky-ref-manual.png'
13 format='SVG'
14 align='center' scalefit='1' width='100%'/>
15 </imageobject>
16 </mediaobject>
17
18 <title>Poky Reference Manual</title> 9 <title>Poky Reference Manual</title>
19 <subtitle>A Guide and Reference to Poky</subtitle> 10 <subtitle>A Guide and Reference to Poky
11 <imagedata fileref="figures/yocto-project-transp.png"
12 width="6in" depth="2in" align="center" scale="50" /></subtitle>
20 13
21 <authorgroup> 14 <authorgroup>
22 <author> 15 <author>
diff --git a/documentation/poky-ref-manual/style.css b/documentation/poky-ref-manual/style.css
index b5019bbee6..cb2db8b273 100644
--- a/documentation/poky-ref-manual/style.css
+++ b/documentation/poky-ref-manual/style.css
@@ -118,14 +118,13 @@ h6 {
118 background-color: transparent; 118 background-color: transparent;
119 background-repeat: no-repeat; 119 background-repeat: no-repeat;
120 padding-top: 256px; 120 padding-top: 256px;
121 background-image: url("poky-beaver.png"); 121 background-image: url("white-on-black-50.png");
122 background-position: right top; 122 background-position: top;
123 float: right;
124 margin-top: -256px; 123 margin-top: -256px;
125 padding-right: 50px; 124 padding-right: 50px;
126 margin-left: 50px; 125 margin-left: 50px;
127 text-align: right; 126 text-align: center;
128 width: 200px; 127 width: 600px;
129} 128}
130 129
131h3.author { 130h3.author {
diff --git a/documentation/poky-ref-manual/white-on-black-yp.png b/documentation/poky-ref-manual/white-on-black-yp.png
new file mode 100755
index 0000000000..81f801d0e7
--- /dev/null
+++ b/documentation/poky-ref-manual/white-on-black-yp.png
Binary files differ
diff --git a/documentation/template/yocto-project-qs.png b/documentation/template/yocto-project-qs.png
new file mode 100644
index 0000000000..333442e0d6
--- /dev/null
+++ b/documentation/template/yocto-project-qs.png
Binary files differ
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-04 06:00:13 +0000