summaryrefslogtreecommitdiffstats
path: root/handbook/poky-handbook.html
blob: abc32354dd20d71986a07b072bbdd4617f382794 (plain) 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Poky Handbook</title><link rel="stylesheet" href="style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="poky-handbook"></a>Poky Handbook</h1></div><div><h2 class="subtitle">Hitchhiker's Guide to Poky</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Richard</span> <span class="surname">Purdie</span></h3><div class="affiliation"><span class="orgname">OpenedHand Ltd<br></span></div><code class="email">&lt;<a href="mailto:richard@openedhand.com">richard@openedhand.com</a>&gt;</code></div><div class="author"><h3 class="author"><span class="firstname">Tomas</span> <span class="surname">Frydrych</span></h3><div class="affiliation"><span class="orgname">OpenedHand Ltd<br></span></div><code class="email">&lt;<a href="mailto:tf@openedhand.com">tf@openedhand.com</a>&gt;</code></div><div class="author"><h3 class="author"><span class="firstname">Marcin</span> <span class="surname">Juszkiewicz</span></h3><div class="affiliation"><span class="orgname">OpenedHand Ltd<br></span></div><code class="email">&lt;<a href="mailto:hrw@openedhand.com">hrw@openedhand.com</a>&gt;</code></div><div class="author"><h3 class="author"><span class="firstname">Dodji</span> <span class="surname">Seketeli</span></h3><div class="affiliation"><span class="orgname">OpenedHand Ltd<br></span></div><code class="email">&lt;<a href="mailto:dodji@openedhand.com">dodji@openedhand.com</a>&gt;</code></div></div></div><div><p class="copyright">Copyright � 2007 OpenedHand Limited</p></div><div><div class="legalnotice"><a name="id1081631"></a><p>
        Permission is granted to copy, distribute and/or modify this document under 
        the terms of the <a href="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/" target="_top">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England &amp; Wales</a> as published by Creative Commons.
      </p></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision 3.1</td><td align="left">15 Feburary 2008</td></tr><tr><td align="left" colspan="2">Poky 3.1 (Pinky) Documentation Release</td></tr></table></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#intro">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-what-is">1. What is Poky?</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">3. System Requirements</a></span></dt><dt><span class="section"><a href="#intro-quickstart">4. Quick Start</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-quickstart-build">4.1. Building and Running an Image</a></span></dt><dt><span class="section"><a href="#intro-quickstart-qemu">4.2. Downloading and Using Prebuilt Images</a></span></dt></dl></dd><dt><span class="section"><a href="#intro-getit">5. Obtaining Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-getit-releases">5.1. Releases</a></span></dt><dt><span class="section"><a href="#intro-getit-nightly">5.2. Nightly Builds</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">5.3. Development Checkouts</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#usingpoky">2. Using Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components">1. Poky Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">1.1. Bitbake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-build">2. Running a Build</a></span></dt><dt><span class="section"><a href="#usingpoky-install">3. Installing and Using the Result</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-install-usbnetworking">3.1. USB Networking</a></span></dt><dt><span class="section"><a href="#usingpoky-install-qemu-networking">3.2. QEMU/USB networking with IP masquerading</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-debugging">4. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">4.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">4.2. Running specific tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">4.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">4.4. General Bitbake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">4.5. Building with no dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">4.6. Variables</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">4.7. Other Tips</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#extendpoky">3. Extending Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg">1. Adding a Package</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg-singlec">1.1. Single .c File Package (Hello World!)</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-autotools">1.2. Autotooled Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-makefile">1.3. Makefile-Based Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-files">1.4. Controlling packages content</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-postinstalls">1.5. Post Install Scripts</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-extend-customimage">2. Customising Images</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-customimage-custombb">2.1. Customising Images through a custom image .bb files</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-customtasks">2.2. Customising Images through custom tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-imagefeatures">2.3. Customising Images through custom IMAGE_FEATURES</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-localconf">2.4. Customising Images through local.conf</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-newmachine">3. Porting Poky to a new machine</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-newmachine-conffile">3.1. Adding the machine configuration file</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-kernel">3.2. Adding a kernel for the machine</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-formfactor">3.3. Adding a formfactor configuration file</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-changes">4. Making and Maintaining Changes</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-changes-collections">4.1. Bitbake Collections</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-commits">4.2. Committing Changes</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-prbump">4.3. Package Revision Incrementing</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-modifing-packages">5. Modifying Package Source Code</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-modifying-packages-quilt">5.1. Modifying Package Source Code with quilt</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#platdev">4. Platform Development with Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-appdev">1. Software development</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-appdev-external-anjuta">1.1. Developing externally using the Anjuta Plugin</a></span></dt><dt><span class="section"><a href="#platdev-appdev-external-sdk">1.2. Developing externally using the Poky SDK</a></span></dt><dt><span class="section"><a href="#platdev-appdev-qemu">1.3. Developing externally in QEMU</a></span></dt><dt><span class="section"><a href="#platdev-appdev-chroot">1.4. Developing externally in a chroot</a></span></dt><dt><span class="section"><a href="#platdev-appdev-insitu">1.5. Developing in Poky directly</a></span></dt><dt><span class="section"><a href="#platdev-appdev-devshell">1.6. Developing with 'devshell'</a></span></dt><dt><span class="section"><a href="#platdev-appdev-srcrev">1.7. Developing within Poky with an external SCM based package</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-gdb-remotedebug">2. Debugging with GDB Remotely</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdbserver">2.1. Launching GDBSERVER on the target</a></span></dt><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdb">2.2. Launching GDB on the host computer</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-oprofile">3. Profiling with OProfile</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-oprofile-target">3.1. Profiling on the target</a></span></dt><dt><span class="section"><a href="#platdev-oprofile-oprofileui">3.2. Using OProfileUI</a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="#ref-structure">1. Reference: Directory Structure</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core">1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">1.3. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-extras">1.4. <code class="filename">meta-extras/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">1.5. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-sources">1.6. <code class="filename">sources/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">1.7. <code class="filename">poky-init-build-env</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">2. <code class="filename">build/</code> - The Build Directory</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-conf-local.conf">2.1. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">2.2. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">2.3. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cross">2.4. <code class="filename">build/tmp/cross/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">2.5. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">2.6. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">2.7. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">2.8. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-rootfs">2.9. <code class="filename">build/tmp/rootfs/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-staging">2.10. <code class="filename">build/tmp/staging/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">2.11. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">2.12. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">3. <code class="filename">meta/</code> - The Metadata</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-packages">3.5. <code class="filename">meta/packages/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">3.6. <code class="filename">meta/site/</code></a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="#ref-bitbake">2. Reference: Bitbake</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-bitbake-parsing">1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">6. Commandline</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">7. Fetchers</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ref-classes">3. Reference: Classes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-classes-base">1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">12. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">13. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">14. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">15. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">16. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">17. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">18. Other Classes</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ref-images">4. Reference: Images</a></span></dt><dt><span class="appendix"><a href="#ref-features">5. Reference: Features</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-features-distro">1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">3. Reference: Images</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ref-variables-glos">6. Reference: Variables Glossary</a></span></dt><dd><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ref-varlocality">7. Reference: Variable Locality (Distro, Machine, Recipe etc.)</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">1. Distro Configuration</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">2. Machine Configuration</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">3. Local Configuration (local.conf)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-required">4. Recipe Variables - Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">5. Recipe Variables - Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">6. Recipe Variables - Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">7. Recipe Variables - Extra Build Information</a></span></dt></dl></dd><dt><span class="appendix"><a href="#faq">8. FAQ</a></span></dt><dt><span class="appendix"><a href="#resources">9. Contributing to Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#resources-intro">1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">2. Bugtracker</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">3. Mailing list</a></span></dt><dt><span class="section"><a href="#resources-irc">4. IRC</a></span></dt><dt><span class="section"><a href="#resources-links">5. Links</a></span></dt></dl></dd><dt><span class="appendix"><a href="#contact">10. OpenedHand Contact Information</a></span></dt><dt><span class="index"><a href="#index">Index</a></span></dt></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="intro"></a>Chapter�1.�Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#intro-what-is">1. What is Poky?</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">3. System Requirements</a></span></dt><dt><span class="section"><a href="#intro-quickstart">4. Quick Start</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-quickstart-build">4.1. Building and Running an Image</a></span></dt><dt><span class="section"><a href="#intro-quickstart-qemu">4.2. Downloading and Using Prebuilt Images</a></span></dt></dl></dd><dt><span class="section"><a href="#intro-getit">5. Obtaining Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-getit-releases">5.1. Releases</a></span></dt><dt><span class="section"><a href="#intro-getit-nightly">5.2. Nightly Builds</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">5.3. Development Checkouts</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-what-is"></a>1.�What is Poky?</h2></div></div></div><p>
        Poky is an open source platform build tool. It is a complete software
        development environment for the creation of Linux devices. It aids the
        design, development, building, debugging, simulation and testing of
        complete modern software stacks using Linux, the X Window System and
        GNOME Mobile based application frameworks. It is based on 
        <a href="http://openembedded.org/" target="_top">OpenEmbedded</a>
        but has been customised with a particular focus.
    </p><p> Poky was setup to:</p><div class="itemizedlist"><ul type="disc"><li><p>Provide an open source Linux, X11, Matchbox, GTK+, <a href="http://gnome.org/mobile" target="_top">GNOME Mobile</a> platform.</p></li><li><p>Create a focused, stable, subset of OpenEmbedded that can be easily and reliably built and developed upon.</p></li><li><p>Fully support a wide range of x86 and ARM hardware</p></li></ul></div><p><a href="http://www.o-hand.com" target="_top">OpenedHand</a> is the principle developer and maintainer of Poky and uses it to:</p><div class="itemizedlist"><ul type="disc"><li><p>Provide <a href="http://www.o-hand.com" target="_top">OpenedHand</a> with stable R&amp;D platform we can build and develop upon.</p></li><li><p>
                Demonstrate the skills available within <a href="http://www.o-hand.com" target="_top">
                OpenedHand</a> and provide a showcase for our software products
                (such as the <a href="http://www.matchbox-project.org/" target="_top">Matchbox</a> and
                <a href="http://www.pimlico-project.org/" target="_top">Pimlico</a> software packages and
                Sato, the default user interface in Poky).
            </p></li><li><p>Provide a base we can supply to our clients for building and developing their customised platforms.</p></li></ul></div><p>
        Poky is primarily a platform builder which generates filesystem images
        based on open source software such as the Kdrive X server, the Matchbox
        window manager, the GTK+ toolkit and the D-Bus message bus system. Images
        for many kinds of devices can be generated, however the standard example
        machines target QEMU system emulation (both x86 and ARM) and the ARM based
        Sharp Zaurus series of devices. Poky's ability to boot inside a QEMU
        emulator makes it particularly suitable as a test platform for development
        of embedded software.
    </p><p>
        An important component integrated within Poky is Sato, a GNOME Mobile 
        based user interface environment.
        It is designed to work well with screens at very high DPI and restricted
        size, such as those often found on smartphones and PDAs. It is coded with
        focus on efficiency and speed so that it works smoothly on hand-held and
        other embedded hardware. It will sit neatly on top of any device
        using the GNOME Mobile stack, providing a well defined user experience.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-manualoverview"></a>2.�Documentation Overview</h2></div></div></div><p>
        The handbook is split into sections covering different aspects of Poky. 
        The <a href="#usingpoky" title="Chapter�2.�Using Poky">'Using Poky' section</a> gives an overview 
        of the components that make up Poky followed by information about using and
        debugging the Poky build system. The <a href="#extendpoky" title="Chapter�3.�Extending Poky">'Extending Poky' section</a> 
        gives information about how to extend and customise Poky along with advice 
        on how to manage these changes. The <a href="#platdev" title="Chapter�4.�Platform Development with Poky">'Platform Development with Poky' 
        section</a> gives information about interaction between Poky and target
        hardware for common platform development tasks such as software development, 
        debugging and profiling. The rest of the manual
        consists of several reference sections each giving details on a specific
        section of Poky functionality.
    </p><p>
        This manual applies to Poky Release 3.1 (Pinky).
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-requirements"></a>3.�System Requirements</h2></div></div></div><p>
        We recommend Debian-based distributions, in particular a recent Ubuntu 
        release (7.04 or newer), as the host system for Poky. Nothing in Poky is
        distribution specific and
        other distributions will most likely work as long as the appropriate
        prerequisites are installed - we know of Poky being used successfully on Redhat,
        SUSE, Gentoo and Slackware host systems.
    </p><p>On a Debian-based system, you need the following packages installed:</p><div class="itemizedlist"><ul type="disc"><li><p>build-essential</p></li><li><p>python</p></li><li><p>diffstat</p></li><li><p>texinfo</p></li><li><p>texi2html</p></li><li><p>cvs</p></li><li><p>subversion</p></li><li><p>wget</p></li><li><p>gawk</p></li><li><p>help2man</p></li><li><p>bochsbios (only to run qemux86 images)</p></li></ul></div><p>
        Debian users can add debian.o-hand.com to their APT sources (See
        <a href="http://debian.o-hand.com" target="_top">http://debian.o-hand.com</a>
        for instructions on doing this) and then run <span><strong class="command">
        "apt-get install qemu poky-depends poky-scripts"</strong></span> which will
        automatically install all these dependencies. OpenedHand can also provide
        VMware images with Poky and all dependencies pre-installed if required.
    </p><p>
        Poky can use a system provided QEMU or build its own depending on how it's
        configured. See the options in <code class="filename">local.conf</code> for more details.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-quickstart"></a>4.�Quick Start</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-quickstart-build"></a>4.1.�Building and Running an Image</h3></div></div></div><p>
            If you want to try Poky, you can do so in a few commands. The example below
            checks out the Poky source code, sets up a build environment, builds an
            image and then runs that image under the QEMU emulator in ARM system emulation mode:
        </p><p>
            </p><pre class="literallayout">
$ wget http://pokylinux.org/releases/pinky-3.1.tar.gz
$ tar zxvf pinky-3.1.tar.gz
$ cd pinky-3.1/
$ source poky-init-build-env
$ bitbake poky-image-sato
$ runqemu qemuarm
</pre><p>
        </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
            This process will need Internet access, about 3 GB of disk space
            available, and you should expect the build to take about 4 - 5 hours since
            it is building an entire Linux system from source including the toolchain!
        </p></div><p>
            To build for other machines see the <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a></em> variable in build/conf/local.conf
            which also contains other configuration information. The images/kernels built
            by Poky are placed in the <code class="filename">tmp/deploy/images</code>
            directory.
        </p><p>
            You could also run <span><strong class="command">"poky-qemu zImage-qemuarm.bin poky-image-sato-qemuarm.ext2"
            </strong></span> within the images directory if you have the poky-scripts Debian package
            installed from debian.o-hand.com. This allows the QEMU images to be used standalone
            outside the Poky build environment.
        </p><p>
            To setup networking within QEMU see the <a href="#usingpoky-install-qemu-networking" title="3.2.�QEMU/USB networking with IP masquerading">
            QEMU/USB networking with IP masquerading</a> section.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-quickstart-qemu"></a>4.2.�Downloading and Using Prebuilt Images</h3></div></div></div><p>
            Prebuilt images from Poky are also available if you just want to run the system
            under QEMU. To use these you need to:
        </p><div class="itemizedlist"><ul type="disc"><li><p>
                     Add debian.o-hand.com to your APT sources (See
                    <a href="http://debian.o-hand.com" target="_top">http://debian.o-hand.com</a> for instructions on doing this)
                </p></li><li><p>Install patched QEMU and poky-scripts:</p><p>
                    </p><pre class="literallayout">
$ apt-get install qemu poky-scripts
</pre><p>
                </p></li><li><p>
                    Download a Poky QEMU release kernel (*zImage*qemu*.bin) and compressed
                    filesystem image (poky-image-*-qemu*.ext2.bz2) which
                    you'll need to decompress with 'bzip2 -d'. These are available from the
                    <a href="http://pokylinux.org/releases/blinky-3.0/" target="_top">last release</a>
                    or from the <a href="http://pokylinux.org/autobuild/poky/" target="_top">autobuilder</a>.
                </p></li><li><p>Start the image:</p><p>
                    </p><pre class="literallayout">
$ poky-qemu &lt;kernel&gt; &lt;image&gt;
</pre><p>
                </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
            A patched version of QEMU is required at present. A suitable version is available from 
            <a href="http://debian.o-hand.com" target="_top">http://debian.o-hand.com</a>, it can be built 
            by poky (bitbake qemu-native) or can be downloaded/built as part of the toolchain/SDK tarballs.
        </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-getit"></a>5.�Obtaining Poky</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-getit-releases"></a>5.1.�Releases</h3></div></div></div><p>Periodically, we make releases of Poky and these are available
            at <a href="http://pokylinux.org/releases/" target="_top">http://pokylinux.org/releases/</a>.
            These are more stable and tested than the nightly development images.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-getit-nightly"></a>5.2.�Nightly Builds</h3></div></div></div><p>
            We make nightly builds of Poky for testing purposes and to make the
            latest developments available. The output from these builds is available
            at <a href="http://pokylinux.org/autobuild/" target="_top">http://pokylinux.org/autobuild/</a>
            where the numbers represent the svn revision the builds were made from.
        </p><p>
            Automated builds are available for "standard" Poky and for Poky SDKs and toolchains as well 
            as any testing versions we might have such as poky-bleeding. The toolchains can
            be used either as external standalone toolchains or can be combined with Poky as a
            prebuilt toolchain to reduce build time. Using the external toolchains is simply a
            case of untarring the tarball into the root of your system (it only creates files in
            <code class="filename">/usr/local/poky</code>) and then enabling the option 
            in <code class="filename">local.conf</code>.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-getit-dev"></a>5.3.�Development Checkouts</h3></div></div></div><p>
            Poky is available from our SVN repository located at
            http://svn.o-hand.com/repos/poky/trunk; a web interface to the repository
            can be accessed at <a href="http://svn.o-hand.com/view/poky/" target="_top">http://svn.o-hand.com/view/poky/</a>.
        </p><p>
           'trunk' is where the deveopment work takes place and you should use this if you're
           after to work with the latest cutting edge developments. It is possible trunk
           can suffer temporary periods of instability while new features are developed and
           if this is undesireable we recommend using one of the release branches.
        </p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="usingpoky"></a>Chapter�2.�Using Poky</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#usingpoky-components">1. Poky Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">1.1. Bitbake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-build">2. Running a Build</a></span></dt><dt><span class="section"><a href="#usingpoky-install">3. Installing and Using the Result</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-install-usbnetworking">3.1. USB Networking</a></span></dt><dt><span class="section"><a href="#usingpoky-install-qemu-networking">3.2. QEMU/USB networking with IP masquerading</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-debugging">4. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">4.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">4.2. Running specific tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">4.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">4.4. General Bitbake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">4.5. Building with no dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">4.6. Variables</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">4.7. Other Tips</a></span></dt></dl></dd></dl></div><p>
        This section gives an overview of the components that make up Poky 
        following by information about running poky builds and dealing with any
        problems that may arise.
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-components"></a>1.�Poky Overview</h2></div></div></div><p>
        At the core of Poky is the bitbake task executor together with various types of
        configuration files. This section gives an overview of bitbake and the
        configuration files, in particular what they are used for, and how they
        interact.
    </p><p>  
        Bitbake handles the parsing and execution of the data
        files. The data itself is of various types; recipes which give
        details about particular pieces of software, class data which is an
        abstraction of common build information (e.g. how to build a Linux kernel)
        and configuration data for machines, policy decisions, etc., which acts as
        a glue and binds everything together. Bitbake knows how to combine multiple
        data sources together, each data source being referred to as a <a href="#usingpoky-changes-collections" title="4.1.�Bitbake Collections">'collection'</a>.
    </p><p>
        The <a href="#ref-structure" title="Appendix�1.�Reference: Directory Structure">directory structure walkthrough</a>
        section gives details on the meaning of specific directories but some
        brief details on the core components follows:
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-components-bitbake"></a>1.1.�Bitbake</h3></div></div></div><p>
            Bitbake is the tool at the heart of Poky and is responsible
            for parsing the metadata, generating a list of tasks from it
            and then executing them. To see a list of the options it
            supports look at <span><strong class="command">bitbake --help</strong></span>.
        </p><p>
            The most common usage is <span><strong class="command">bitbake packagename</strong></span> where
            packagename is the name of the package you wish to build
            (from now on called the target). This often equates to the first part of a .bb
            filename, so to run the <code class="filename">matchbox-desktop_1.2.3.bb</code> file, you
            might type <span><strong class="command">bitbake matchbox-desktop</strong></span>.
            Several different versions of matchbox-desktop might exist and
            bitbake will choose the one selected by the distribution configuration
            (more details about how bitbake chooses between different versions
            and providers is available in the <a href="#ref-bitbake-providers" title="2.�Preferences and Providers">
            'Preferences and Providers' section</a>). Bitbake will also try to execute any
            dependent tasks first so before building matchbox-desktop it
            would build a cross compiler and glibc if not already built.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-components-metadata"></a>1.2.�Metadata (Recipes)</h3></div></div></div><p>
            The .bb files are usually referred to as 'recipes'. In general, a
            recipe contains information about a single piece of software such
            as where to download the source, any patches that are needed,
            any special configuration options, how to compile the source files
            and how to package the compiled output.
        </p><p>
            'package' can also used to describe recipes but since the same
            word is used for the packaged output from Poky (i.e. .ipk or .deb
            files), this document will avoid it.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-components-classes"></a>1.3.�Classes</h3></div></div></div><p>
            Class (.bbclass) files contain information which is useful to share
            between metadata files. An example is the autotools class which contains
            the common settings that any application using autotools would use. The
            <a href="#ref-classes" title="Appendix�3.�Reference: Classes">classes reference section</a> gives details
            on common classes and how to use them.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-components-configuration"></a>1.4.�Configuration</h3></div></div></div><p>
            The configuration (.conf) files define various configuration variables
            which govern what Poky does. These are split into several areas, such
            as machine configuration options, distribution configuration options,
            compiler tuning options, general common configuration and user
            configuration (local.conf).
        </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-build"></a>2.�Running a Build</h2></div></div></div><p>
        First the Poky build environment needs to be setup using the following command:
    </p><p>
        </p><pre class="literallayout">
$ source poky-init-build-env
</pre><p>
    </p><p>
        Once the Poky build environment is setup, a target can now be built using:
    </p><p>
        </p><pre class="literallayout">
$ bitbake &lt;target&gt;
</pre><p>
    </p><p>
        The target is the name of the recipe you want to build. Common targets are the
        images (in <code class="filename">meta/packages/images/</code>)
        or the name of a recipe for a specific piece of software like 
        <span class="application">busybox</span>. More details about the standard images 
        are available in the <a href="#ref-images" title="Appendix�4.�Reference: Images">image reference section</a>.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-install"></a>3.�Installing and Using the Result</h2></div></div></div><p>
        Once an image has been built it often needs to be installed. The images/kernels built
        by Poky are placed in the <code class="filename">tmp/deploy/images</code>
        directory. Running qemux86 and qemuarm images is covered in the <a href="#intro-quickstart-qemu" title="4.2.�Downloading and Using Prebuilt Images">Running an Image</a> section. See your 
        board/machine documentation for information about how to install these images.
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-install-usbnetworking"></a>3.1.�USB Networking</h3></div></div></div><p>
            Devices commonly have USB connectivity. To connect to the usbnet interface, on 
            the host machine run:
        </p><p>
            </p><pre class="programlisting">
modprobe usbnet
ifconfig usb0 192.168.0.200
route add 192.168.0.202 usb0 
</pre><p>
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-install-qemu-networking"></a>3.2.�QEMU/USB networking with IP masquerading</h3></div></div></div><p>
            On Ubuntu, Debian or similar distributions you can have the network automatically 
            configured. You can also enable masquerading between the QEMU system and the rest 
            of your network. To do this you need to edit <code class="filename">/etc/network/interfaces</code> to include:
        </p><pre class="programlisting">
allow-hotplug tap0
iface tap0 inet static
        address 192.168.7.200
        netmask 255.255.255.0
        network 192.168.7.0
        post-up iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.7.0/24
        post-up echo 1 &gt; /proc/sys/net/ipv4/ip_forward
        post-up iptables -P FORWARD ACCEPT
</pre><p>
        </p><p>
            This ensures the tap0 interface will be up everytime you run QEMU
            and it will have network/internet access.
        </p><p>
            Under emulation there are two steps to configure for internet access
            via tap0. The first step is to configure routing:
        </p><pre class="programlisting">
route add default gw 192.168.7.200 tap0
</pre><p>
        </p><p>
            The second is to configure name resolution which is configured in the 
            <code class="filename">/etc/resolv.conf</code> file. The simplest solution is 
            to copy it's content from the host machine.
        </p><p>
            USB connections to devices can be setup and automated in a similar way.
            First add the following to
            <code class="filename">/etc/network/interfaces</code>:
        </p><pre class="programlisting">
allow-hotplug usb0
iface usb0 inet static
        address 192.168.0.200
        netmask 255.255.255.0
        network 192.168.0.0
        post-up iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.0.0/24
        post-up echo 1 &gt; /proc/sys/net/ipv4/ip_forward
        post-up iptables -P FORWARD ACCEPT
</pre><p>
        </p><p>
            and then to configure routing on the device you would use:
        </p><pre class="programlisting">
route add default gw 192.168.0.202 usb0
</pre><p>
        </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-debugging"></a>4.�Debugging Build Failures</h2></div></div></div><p>
        The exact method for debugging Poky depends on the nature of the 
        bug(s) and which part of the system they might be from. Standard 
        debugging practises such as comparing to the last 
        known working version and examining the changes, reapplying the 
        changes in steps to identify the one causing the problem etc. are
        valid for Poky just like any other system. Its impossible to detail
        every possible potential failure here but there are some general
        tips to aid debugging:
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-taskfailures"></a>4.1.�Task Failures</h3></div></div></div><p>The log file for shell tasks is available in <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>. 
            For the compile task of busybox 1.01 on the ARM spitz machine, this 
            might be <code class="filename">tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</code> 
            for example. To see what bitbake ran to generate that log, look at the <code class="filename">run.do_taskname.pid </code>
            file in the same directory.
        </p><p>The output from python tasks is sent directly to the console at present.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-taskrunning"></a>4.2.�Running specific tasks</h3></div></div></div><p> Any given package consists of a set of tasks, in most
            cases the series is fetch, unpack, patch, configure,
            compile, install, package, package_write and build. The
            default task is "build" and any tasks this depends on are
            built first hence the standard bitbake behaviour. There are
            some tasks such as devshell which are not part of the
            default build chain.  If you wish to run such a task you can
            use the "-c" option to bitbake e.g. <span><strong class="command">bitbake
            matchbox-desktop -c devshell</strong></span>.
        </p><p>
            If you wish to rerun a task you can use the force option
            "-f". A typical usage session might look like: </p><p>
            </p><pre class="literallayout">
% bitbake matchbox-desktop
[change some source in the WORKDIR for example]
% bitbake matchbox-desktop -c compile -f
% bitbake matchbox-desktop</pre><p>
        </p><p>
            which would build matchbox-desktop, then recompile it. The
            final command reruns all tasks after the compile (basically
            the packaging tasks) since bitbake will notice the the
            compile has been rerun and hence the other tasks also need
            to run again.
        </p><p>
            You can view a list of tasks in a given package by running
            the listtasks task e.g. <span><strong class="command">bitbake matchbox-desktop -c
            listtasks</strong></span>.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-dependencies"></a>4.3.�Dependency Graphs</h3></div></div></div><p>
            Sometimes it can be hard to see why bitbake wants to build
            some other packages before a given package you've specified.
            <span><strong class="command">bitbake -g targetname</strong></span> will create
            <code class="filename">depends.dot</code> and
            <code class="filename">task-depends.dot</code> files in the current 
            directory. They show
            which packages and tasks depend on which other packages and
            tasks and are useful for debugging purposes.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-bitbake"></a>4.4.�General Bitbake Problems</h3></div></div></div><p>
            Debug output from bitbake can be seen with the "-D" option.
            The debug output gives more information about what bitbake
            is doing and/or why. Each -D option increases the logging
            level, the most common usage being "-DDD".
        </p><p>
            The output from <span><strong class="command">bitbake -DDD -v targetname</strong></span> can reveal why
            a certain version of a package might be chosen, why bitbake
            picked a certain provider or help in other situations where
            bitbake does something you're not expecting.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-buildfile"></a>4.5.�Building with no dependencies</h3></div></div></div><p>
            If you really want to build a specific .bb file, you can use
            the form <span><strong class="command">bitbake -b somepath/somefile.bb</strong></span>. Note that this
            will not check the dependencies so this option should only
            be used when you know its dependencies already exist. You
            can specify fragments of the filename and bitbake will see
            if it can find a unique match.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-variables"></a>4.6.�Variables</h3></div></div></div><p>
            The "-e" option will dump the resulting environment for
            either the configuration (no package specified) or for a
            specific package when specified with the "-b" option.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-others"></a>4.7.�Other Tips</h3></div></div></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>When adding new packages it is worth keeping an eye open for bad 
            things creeping into compiler commandlines such as references to local 
            system files (<code class="filename">/usr/lib/</code> or <code class="filename">/usr/include/</code> etc.).
        </p></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
            If you want to remove the psplash boot splashscreen, add "psplash=false"
            to  the kernel commandline and psplash won't load allowing you to see 
            the console. It's also possible to switch out of the splashscreen by 
            switching virtual console (Fn+Left or Fn+Right on a Zaurus).
        </p></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="extendpoky"></a>Chapter�3.�Extending Poky</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg">1. Adding a Package</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg-singlec">1.1. Single .c File Package (Hello World!)</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-autotools">1.2. Autotooled Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-makefile">1.3. Makefile-Based Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-files">1.4. Controlling packages content</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-postinstalls">1.5. Post Install Scripts</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-extend-customimage">2. Customising Images</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-customimage-custombb">2.1. Customising Images through a custom image .bb files</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-customtasks">2.2. Customising Images through custom tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-imagefeatures">2.3. Customising Images through custom IMAGE_FEATURES</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-localconf">2.4. Customising Images through local.conf</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-newmachine">3. Porting Poky to a new machine</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-newmachine-conffile">3.1. Adding the machine configuration file</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-kernel">3.2. Adding a kernel for the machine</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-formfactor">3.3. Adding a formfactor configuration file</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-changes">4. Making and Maintaining Changes</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-changes-collections">4.1. Bitbake Collections</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-commits">4.2. Committing Changes</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-prbump">4.3. Package Revision Incrementing</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-modifing-packages">5. Modifying Package Source Code</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-modifying-packages-quilt">5.1. Modifying Package Source Code with quilt</a></span></dt></dl></dd></dl></div><p>
        This section gives information about how to extend the functionality
        already present in Poky, documenting standard tasks such as adding new
        software packages, extending or customising images or porting poky to
        new hardware (adding a new machine). It also contains advice about how
        to manage the process of making changes to Poky to achieve best results.
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-extend-addpkg"></a>1.�Adding a Package</h2></div></div></div><p>
            To add package into Poky you need to write a recipe for it. 
            Writing a recipe means creating a .bb file which sets various
            variables. The variables
            useful for recipes are detailed in the <a href="#ref-varlocality-recipe-required" title="4.�Recipe Variables - Required">
                recipe reference</a> section along with more detailed information 
            about issues such as recipe naming.
        </p><p>
            The simplest way to add a new package is to base it on a similar
            pre-existing recipe. There are some examples below of how to add 
            standard types of packages:
        </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-singlec"></a>1.1.�Single .c File Package (Hello World!)</h3></div></div></div><p>
                To build an application from a single file stored locally requires a
                recipe which has the file listed in the <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em> variable. In addition 
                the <code class="function">do_compile</code> and <code class="function">do_install</code> 
                tasks need to be manually written. The <em class="glossterm"><a href="#var-S" title="S">
                S</a></em> variable defines the directory containing the source 
                code which in this case is set equal to <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">
                WORKDIR</a></em>, the directory BitBake uses for the build.
            </p><pre class="programlisting">
DESCRIPTION = "Simple helloworld application"
SECTION = "examples"
LICENSE = "MIT"

SRC_URI = "file://helloworld.c"

S = "${WORKDIR}"

do_compile() {
	${CC} helloworld.c -o helloworld
}

do_install() {
	install -d ${D}${bindir}
	install -m 0755 helloworld ${D}${bindir}
}
            </pre><p>
                As a result of the build process "helloworld" and "helloworld-dbg"
                packages will be built.
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-autotools"></a>1.2.�Autotooled Package</h3></div></div></div><p>
                Applications which use autotools (autoconf, automake)
                require a recipe which has a source archive listed in 
                <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em> and 
                <span><strong class="command">inherit autotools</strong></span> to instruct BitBake to use the
                <code class="filename">autotools.bbclass</code> which has 
                definitions of all the steps
                needed to build an autotooled application.
                The result of the build will be automatically packaged and if
                the application uses NLS to localise then packages with
                locale information will be generated (one package per
                language).
            </p><pre class="programlisting">
DESCRIPTION = "GNU Helloworld application"
SECTION = "examples"
LICENSE = "GPLv2"

SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2"

inherit autotools
            </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-makefile"></a>1.3.�Makefile-Based Package</h3></div></div></div><p>
                Applications which use GNU make require a recipe which has
                the source archive listed in <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em>. 
                Adding a <code class="function">do_compile</code> step
                is not needed as by default BitBake will start the "make"
                command to compile the application. If there is a need for
                additional options to make then they should be stored in the
                <em class="glossterm"><a href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></em> variable - BitBake 
                will pass them into the GNU
                make invocation. A <code class="function">do_install</code> task is required
                - otherwise BitBake will run an empty <code class="function">do_install</code> 
                task by default. 
            </p><p>
                Some applications may require extra parameters to be passed to
                the compiler, for example an additional header path. This can
                be done buy adding to the <em class="glossterm"><a href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></em> variable, as in the example below.
            </p><pre class="programlisting">
DESCRIPTION = "Tools for managing memory technology devices."
SECTION = "base"
DEPENDS = "zlib"
HOMEPAGE = "http://www.linux-mtd.infradead.org/"
LICENSE = "GPLv2"

SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz"

CFLAGS_prepend = "-I ${S}/include "

do_install() {
	oe_runmake install DESTDIR=${D}
}
            </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-files"></a>1.4.�Controlling packages content</h3></div></div></div><p>                        
                The variables <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></em> and 
                <em class="glossterm"><a href="#var-FILES" title="FILES">FILES</a></em> are used to split an
                application into multiple packages.
            </p><p>
                Below the "libXpm" recipe is used as an example. By
                default the "libXpm" recipe generates one package 
                which contains the library
                and also a few binaries. The recipe can be adapted to 
                split the binaries into separate packages.
            </p><pre class="programlisting">
require xorg-lib-common.inc

DESCRIPTION = "X11 Pixmap library"
LICENSE = "X-BSD"
DEPENDS += "libxext"
PE = "1"

XORG_PN = "libXpm"

PACKAGES =+ "sxpm cxpm"
FILES_cxpm = "${bindir}/cxpm"
FILES_sxpm = "${bindir}/sxpm"
            </pre><p>
                In this example we want to ship the "sxpm" and "cxpm" binaries 
                in separate packages. Since "bindir" would be packaged into the 
                main <em class="glossterm"><a href="#var-PN" title="PN">PN</a></em> 
                package as standard we prepend the <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></em> variable so
                additional package names are added to the start of list. The 
                extra <em class="glossterm"><a href="#var-PN" title="PN">FILES</a></em>_*
                variables then contain information to specify which files and
                directories goes into which package. 
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-postinstalls"></a>1.5.�Post Install Scripts</h3></div></div></div><p>
                To add a post-installation script to a package, add
                a <code class="function">pkg_postinst_PACKAGENAME()</code> 
                function to the .bb file
                where PACKAGENAME is the name of the package to attach
                the postinst script to. A post-installation function has the following structure:
            </p><pre class="programlisting">
pkg_postinst_PACKAGENAME () {
#!/bin/sh -e
# Commands to carry out
}
            </pre><p>
                The script defined in the post installation function
                gets called when the rootfs is made. If the script succeeds,
                the package is marked as installed. If the script fails,
                the package is marked as unpacked and the script will be
                executed again on the first boot of the image.
            </p><p>
                Sometimes it is necessary that the execution of a post-installation
                script is delayed until the first boot, because the script 
                needs to be executed the device itself.  To delay script execution
                until boot time, the post-installation function should have the
                following structure:
            </p><pre class="programlisting">
pkg_postinst_PACKAGENAME () {
#!/bin/sh -e
if [ x"$D" = "x" ]; then
# Actions to carry out on the device go here
else
exit 1
fi
}
            </pre><p>
                The structure above delays execution until first boot 
                because the <em class="glossterm"><a href="#var-D" title="D">D</a></em> variable points
                to the 'image'
                directory when the rootfs is being made at build time but
                is unset when executed on the first boot. 
            </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-extend-customimage"></a>2.�Customising Images</h2></div></div></div><p>
        Poky images can be customised to satisfy 
        particular requirements. Several methods are detailed below 
        along with guidelines of when to use them.
        </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-customimage-custombb"></a>2.1.�Customising Images through a custom image .bb files</h3></div></div></div><p>
                One way to get additional software into an image is by creating a
                custom image. The recipe will contain two lines:
            </p><pre class="programlisting">
IMAGE_INSTALL = "task-poky-x11-base package1 package2"

inherit poky-image
            </pre><p>
                By creating a custom image, a developer has total control
                over the contents of the image. It is important use 
                the correct names of packages in the <em class="glossterm"><a href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></em> variable. 
                The names must be in 
                the OpenEmbedded notation instead of Debian notation, for example
                "glibc-dev" instead of "libc6-dev" etc.
            </p><p>
                The other method of creating a new image is by modifying
                an existing image. For example if a developer wants to add
                "strace" into "poky-image-sato" the following recipe can
                be used:
            </p><pre class="programlisting">
require poky-image-sato.bb

IMAGE_INSTALL += "strace"
            </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-customimage-customtasks"></a>2.2.�Customising Images through custom tasks</h3></div></div></div><p>
                For for complex custom images, the best approach is to create a custom 
                task package which is them used to build the image (or images). A good
                example of a tasks package is <code class="filename">meta/packages/tasks/task-poky.bb
                </code>. The <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></em> 
                variable lists the task packages to build (along with the complimentary
                -dbg and -dev packages). For each package added,
                <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">RDEPENDS</a></em> and
                <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">RRECOMMENDS</a></em> 
                entries can then be added each containing a list of packages the parent 
                task package should contain. An example would be:
            </p><p>
            </p><pre class="programlisting">
DESCRIPTION = "My Custom Tasks"

PACKAGES = "\
    task-custom-apps \
    task-custom-apps-dbg \
    task-custom-apps-dev \
    task-custom-tools \
    task-custom-tools-dbg \
    task-custom-tools-dev \
    "

RDEPENDS_task-custom-apps = "\
    dropbear \
    portmap \
    psplash"

RDEPENDS_task-custom-tools = "\
    oprofile \
    oprofileui-server \
    lttng-control \
    lttng-viewer"

RRECOMMENDS_task-custom-tools = "\
    kernel-module-oprofile"
</pre><p>
            </p><p>
                In this example, two tasks packages are created, task-custom-apps and 
                task-custom-tools with the dependencies and recommended package dependencies 
                listed. To build an image using these task packages, you would then add 
                "task-custom-apps" and/or "task-custom-tools" to <em class="glossterm"><a href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></em> or other forms 
                of image dependencies as described in other areas of this section.
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-customimage-imagefeatures"></a>2.3.�Customising Images through custom <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em></h3></div></div></div><p>
                Ultimately users may want to add extra image "features" as used by Poky with the 
                <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em>
                variable. To create these, the best reference is <code class="filename">meta/classes/poky-image.bbclass</code>
                which illustrates how poky achieves this. In summary, the file looks at the contents of the 
                <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em>
                variable and based on this generates the <em class="glossterm"><a href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">
                IMAGE_INSTALL</a></em> variable automatically. Extra features can be added by 
                extending the class or creating a custom class for use with specialised image .bb files.
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-customimage-localconf"></a>2.4.�Customising Images through local.conf</h3></div></div></div><p>
                It is possible to customise image contents by abusing
                variables used by distribution maintainers in local.conf.
                This method only allows the addition of packages and 
                is not recommended.
            </p><p>
                To add an "strace" package into the image the following is 
                added to local.conf:
            </p><pre class="programlisting">
DISTRO_EXTRA_RDEPENDS += "strace"
            </pre><p>
                However, since the <em class="glossterm"><a href="#var-DISTRO_EXTRA_RDEPENDS" title="DISTRO_EXTRA_RDEPENDS">
                DISTRO_EXTRA_RDEPENDS</a></em> variable is for
                distribution maintainers this method does not make
                adding packages as simple as a custom .bb file. Using
                this method, a few packages will need to be recreated
                and the the image built.
            </p><pre class="programlisting">
bitbake -cclean task-boot task-base task-poky
bitbake poky-image-sato
            </pre><p>
                Cleaning task-* packages is required because they use the
                <em class="glossterm"><a href="#var-DISTRO_EXTRA_RDEPENDS" title="DISTRO_EXTRA_RDEPENDS">
                DISTRO_EXTRA_RDEPENDS</a></em> variable. There is no need to
                build them by hand as Poky images depend on the packages they contain so
                dependencies will be built automatically. For this reason we don't use the
                "rebuild" task in this case since "rebuild" does not care about
                dependencies - it only rebuilds the specified package.
            </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="platdev-newmachine"></a>3.�Porting Poky to a new machine</h2></div></div></div><p>
        Adding a new machine to Poky is a straightforward process and
        this section gives an idea of the changes that are needed. This guide is
        meant to cover adding machines similar to those Poky already supports. 
        Adding a totally new architecture might require gcc/glibc changes as 
        well as updates to the site information and, whilst well within Poky's 
        capabilities, is outside the scope of this section.
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-newmachine-conffile"></a>3.1.�Adding the machine configuration file</h3></div></div></div><p>
            A .conf file needs to be added to conf/machine/ with details of the
            device being added. The name of the file determines the name Poky will
            use to reference this machine.
        </p><p>
            The most important variables to set in this file are <em class="glossterm">
            <a href="#var-TARGET_ARCH" title="TARGET_ARCH">TARGET_ARCH</a></em> 
            (e.g. "arm"), <em class="glossterm"><a href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">
            PREFERRED_PROVIDER</a></em>_virtual/kernel (see below) and 
            <em class="glossterm"><a href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES
            </a></em> (e.g. "kernel26 apm screen wifi"). Other variables
            like <em class="glossterm"><a href="#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE
            </a></em> (e.g. "115200 ttyS0"), <em class="glossterm"> 
            <a href="#var-KERNEL_IMAGETYPE" title="KERNEL_IMAGETYPE">KERNEL_IMAGETYPE</a>
            </em> (e.g. "zImage") and <em class="glossterm"><a href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">
            IMAGE_FSTYPES</a></em> (e.g. "tar.gz jffs2") might also be 
            needed. Full details on what these variables do and the meaning of
            their contents is available through the links.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-newmachine-kernel"></a>3.2.�Adding a kernel for the machine</h3></div></div></div><p>
             Poky needs to be able to build a kernel for the machine. You need 
             to either create a new kernel recipe for this machine or extend an 
             existing recipe. There are plenty of kernel examples in the 
             packages/linux directory which can be used as references.
        </p><p>
             If creating a new recipe  the "normal" recipe writing rules apply 
             for setting up a <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI
             </a></em> including any patches and setting <em class="glossterm">
             <a href="#var-S" title="S">S</a></em> to point at the source 
             code. You will need to create a configure task which configures the 
             unpacked kernel with a defconfig be that through a "make defconfig" 
             command or more usually though copying in a suitable defconfig and 
             running "make oldconfig". By making use of "inherit kernel" and also 
             maybe some of the linux-*.inc files, most other functionality is 
             centralised and the the defaults of the class normally work well.
        </p><p>
            If extending an existing kernel it is usually a case of adding a 
            suitable defconfig file in a location similar to that used by other 
            machine's defconfig files in a given kernel, possibly listing it in
            the SRC_URI and adding the machine to the expression in <em class="glossterm">
            <a href="#var-COMPATIBLE_MACHINES" title="COMPATIBLE_MACHINES">COMPATIBLE_MACHINES</a>
            </em>.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-newmachine-formfactor"></a>3.3.�Adding a formfactor configuration file</h3></div></div></div><p>
            A formfactor configuration file provides information about the 
            target hardware on which Poky is running, and that Poky cannot 
            obtain from other sources such as the kernel.  Some examples of 
            information contained in a formfactor configuration file include 
            framebuffer orientation, whether or not the system has a keyboard, 
            the positioning of the keyboard in relation to the screen, and 
            screen resolution.
        </p><p>
            Sane defaults should be used in most cases, but if customisation is 
            necessary you need to create a <code class="filename">machconfig</code> file 
            under <code class="filename">meta/packages/formfactor/files/MACHINENAME/</code>
            where <code class="literal">MACHINENAME</code> is the name for which this infomation
            applies. For information about the settings available and the defaults, please see 
            <code class="filename">meta/packages/formfactor/files/config</code>.
        </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-changes"></a>4.�Making and Maintaining Changes</h2></div></div></div><p>
            We recognise that people will want to extend/configure/optimise Poky for
            their specific uses, especially due to the extreme configurability and 
            flexibility Poky offers. To ensure ease of keeping pace with future 
            changes in Poky we recommend making changes to Poky in a controlled way.
        </p><p>
            Poky supports the idea of <a href="#usingpoky-changes-collections" title="4.1.�Bitbake Collections">"collections"</a> which when used
            properly can massively ease future upgrades and allow segregation
            between the Poky core and a given developer's changes. Some other advice on 
            managing changes to Poky is also given in the following section.
        </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-changes-collections"></a>4.1.�Bitbake Collections</h3></div></div></div><p>
                Often, people want to extend Poky either through adding packages
                or overriding files contained within Poky to add their own
                functionality. Bitbake has a powerful mechanism called
                collections which provide a way to handle this which is fully
                supported and actively encouraged within Poky.
            </p><p>
                In the standard tree, meta-extras is an example of how you can
                do this. As standard the data in meta-extras is not used on a
                Poky build but local.conf.sample shows how to enable it:
            </p><p>
                </p><pre class="literallayout">
BBFILES := "${OEROOT}/meta/packages/*/*.bb ${OEROOT}/meta-extras/packages/*/*.bb"
BBFILE_COLLECTIONS = "normal extras"
BBFILE_PATTERN_normal = "^${OEROOT}/meta/"
BBFILE_PATTERN_extras = "^${OEROOT}/meta-extras/"
BBFILE_PRIORITY_normal = "5"
BBFILE_PRIORITY_extras = "5"</pre><p>
            </p><p>
                As can be seen, the extra recipes are added to BBFILES. The
                BBFILE_COLLECTIONS variable is then set to contain a list of
                collection names. The BBFILE_PATTERN variables are regular
                expressions used to match files from BBFILES into a particular
                collection in this case by using the base pathname. 
                The BBFILE_PRIORITY variable then assigns the different
                priorities to the files in different collections. This is useful
                in situations where the same package might appear in both
                repositories and allows you to choose which collection should
                'win'.
            </p><p>
                This works well for recipes. For bbclasses and configuration
                files, you can use the BBPATH environment variable. In this
                case, the first file with the matching name found in BBPATH is
                the one that is used, just like the PATH variable for binaries.
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-changes-commits"></a>4.2.�Committing Changes</h3></div></div></div><p>
                Modifications to Poky are often managed under some kind of source
                revision control system. The policy for committing to such systems
                is important as some simple policy can significantly improve 
                usability. The tips below are based on the policy that OpenedHand 
                uses for commits to Poky.
            </p><p>
                It helps to use a consistent style for commit messages when committing 
                changes. We've found a style where the first line of a commit message 
                summarises the change and starts with the name of any package affected
                work well. Not all changes are to specific packages so the prefix could 
                also be a machine name or class name instead. If a change needs a longer 
                description this should follow the summary.
            </p><p>
                Any commit should be self contained in that it should leave the 
                metadata in a consistent state, buildable before and after the 
                commit. This helps ensure the autobuilder test results are valid 
                but is good practice regardless.
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-changes-prbump"></a>4.3.�Package Revision Incrementing</h3></div></div></div><p>
                If a committed change will result in changing the package output
                then the value of the <em class="glossterm"><a href="#var-PR" title="PR">PR</a>
                </em> variable needs to be increased (commonly referred to 
                as 'bumped') as part of that commit. Only integer values are used
                and <em class="glossterm"><a href="#var-PR" title="PR">PR</a></em> = 
                "r0" should not be added into new recipes as this is default value.
                When upgrading the version of a package (<em class="glossterm"><a href="#var-PV" title="PV">PV</a></em>), the <em class="glossterm"><a href="#var-PR" title="PR">PR</a></em> variable should be removed.
            </p><p>
                The aim is that the package version will only ever increase. If 
                for some reason <em class="glossterm"><a href="#var-PV" title="PV">PV</a></em> 
                will change and but not increase, the <em class="glossterm"><a href="#var-PE" title="PE">PE</a></em> (Package Epoch) can 
                be increased (it defaults to '0'). The version numbers aim to 
                follow the <a href="http://www.debian.org/doc/debian-policy/ch-controlfields.html" target="_top">
                Debian Version Field Policy Guidelines</a> which define how 
                versions are compared and hence what "increasing" means.
            </p><p>
                There are two reasons for doing this, the first is to ensure that 
                when a developer updates and rebuilds, they get all the changes to
                the repository and don't have to remember to rebuild any sections.
                The second is to ensure that target users are able to upgrade their
                devices via their package manager such as with the <span><strong class="command">
                ipkg update;ipkg upgrade</strong></span> commands (or similar for 
                dpkg/apt or rpm based systems). The aim is to ensure Poky has 
                upgradable packages in all cases.
            </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-modifing-packages"></a>5.�Modifying Package Source Code</h2></div></div></div><p>
            Poky is usually used to build software rather than modifying
            it. However, there are ways Poky can be used to modify software. 
        </p><p>
            During building, the sources are available in <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em> directory.
            Where exactly this is depends on the type of package and the
            architecture of target device. For a standard recipe not
            related to <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a></em> it will be
            <code class="filename">tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/</code>.
            Target device dependent packages use <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE
            </a></em> 
            instead of <em class="glossterm"><a href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH
            </a></em> 
            in the directory name.
        </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
                Check the package recipe sets the <em class="glossterm"><a href="#var-S" title="S">S</a></em> variable to something
            other than standard <code class="filename">WORKDIR/PN-PV/</code> value.
            </p></div><p>
            After building a package, a user can modify the package source code
            without problem. The easiest way to test changes is by calling the
            "compile" task:
        </p><pre class="programlisting">
bitbake --cmd compile --force NAME_OF_PACKAGE
        </pre><p>
            Other tasks may also be called this way.
        </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-modifying-packages-quilt"></a>5.1.�Modifying Package Source Code with quilt</h3></div></div></div><p>
                By default Poky uses <a href="http://savannah.nongnu.org/projects/quilt" target="_top">quilt</a>
                to manage patches in <code class="function">do_patch</code> task. 
                It is a powerful tool which can be used to track all
                modifications done to package sources.
            </p><p>
                Before modifying source code it is important to
                notify quilt so it will track changes into new patch
                file:
                </p><pre class="programlisting">
quilt new NAME-OF-PATCH.patch
                </pre><p>

                Then add all files which will be modified into that
                patch:
                </p><pre class="programlisting">
quilt add file1 file2 file3
                </pre><p>

                Now start editing. At the end quilt needs to be used
                to generate final patch which will contain all
                modifications:
                </p><pre class="programlisting">
quilt refresh
                </pre><p>

                The resulting patch file can be found in the
                <code class="filename">patches/</code> subdirectory of the source 
                (<em class="glossterm"><a href="#var-S" title="S">S</a></em>) directory. For future builds it
                should be copied into
                Poky metadata and added into <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em> of a recipe:
                </p><pre class="programlisting">
SRC_URI += "file://NAME-OF-PATCH.patch;patch=1"
                </pre><p>

                This also requires a bump of <em class="glossterm"><a href="#var-PR" title="PR">PR</a></em> value in the same recipe as we changed resulting packages.
            </p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="platdev"></a>Chapter�4.�Platform Development with Poky</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#platdev-appdev">1. Software development</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-appdev-external-anjuta">1.1. Developing externally using the Anjuta Plugin</a></span></dt><dt><span class="section"><a href="#platdev-appdev-external-sdk">1.2. Developing externally using the Poky SDK</a></span></dt><dt><span class="section"><a href="#platdev-appdev-qemu">1.3. Developing externally in QEMU</a></span></dt><dt><span class="section"><a href="#platdev-appdev-chroot">1.4. Developing externally in a chroot</a></span></dt><dt><span class="section"><a href="#platdev-appdev-insitu">1.5. Developing in Poky directly</a></span></dt><dt><span class="section"><a href="#platdev-appdev-devshell">1.6. Developing with 'devshell'</a></span></dt><dt><span class="section"><a href="#platdev-appdev-srcrev">1.7. Developing within Poky with an external SCM based package</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-gdb-remotedebug">2. Debugging with GDB Remotely</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdbserver">2.1. Launching GDBSERVER on the target</a></span></dt><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdb">2.2. Launching GDB on the host computer</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-oprofile">3. Profiling with OProfile</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-oprofile-target">3.1. Profiling on the target</a></span></dt><dt><span class="section"><a href="#platdev-oprofile-oprofileui">3.2. Using OProfileUI</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="platdev-appdev"></a>1.�Software development</h2></div></div></div><p>
        Poky supports several methods of software development. These different
        forms of development are explained below and can be switched
        between as needed.
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-external-anjuta"></a>1.1.�Developing externally using the Anjuta Plugin</h3></div></div></div><p>
            An Anjuta IDE plugin exists to make developing software within the Poky framework
            easier for the application developer. It presents a graphical IDE from which the 
            developer can cross compile an application then deploy and execute the output in a QEMU 
            emulation session. It also supports cross debugging and profiling.
        </p><p>
            To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta and the Anjuta 
            plugin. The Poky Anjuta plugin is available from the OpenedHand SVN repository located at
            http://svn.o-hand.com/repos/anjuta-poky/trunk/anjuta-plugin-sdk/; a web interface
            to the repository can be accessed at <a href="http://svn.o-hand.com/view/anjuta-poky/" target="_top">http://svn.o-hand.com/view/anjuta-poky/</a>.
            See the README file contained in the project for more information.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-external-sdk"></a>1.2.�Developing externally using the Poky SDK</h3></div></div></div><p>
            The meta-toolchain and meta-toolchain-sdk targets (<a href="#ref-images" title="Appendix�4.�Reference: Images">see
            the images section</a>) build tarballs which contain toolchains and 
            libraries suitable for application development outside Poky. These unpack into the 
            <code class="filename">/usr/local/poky</code> directory and contain
            a setup script, e.g. 
            <code class="filename">/usr/local/poky/eabi-glibc/arm/environment-setup</code> which
            can be sourced to initialise a suitable environment. After sourcing this, the 
            compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other 
            useful utilities are added to the PATH. Variables to assist pkgconfig and 
            autotools are also set so that, for example, configure can find pre-generated test 
            results for tests which need target hardware to run.
        </p><p>
            Using the toolchain with autotool enabled packages is straightforward, just pass the 
            appropriate host option to configure e.g. "./configure --host=arm-poky-linux-gnueabi".
            For other projects it is usually a case of ensuring the cross tools are used e.g.
            CC=arm-poky-linux-gnueabi-gcc and LD=arm-poky-linux-gnueabi-ld.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-qemu"></a>1.3.�Developing externally in QEMU</h3></div></div></div><p>
            Running Poky QEMU images is covered in the <a href="#intro-quickstart-qemu" title="4.2.�Downloading and Using Prebuilt Images">Running an Image</a> section.
        </p><p>
            Poky's QEMU images contain a complete native toolchain. This means 
            that applications can be developed within QEMU in the same was as a 
            normal system. Using qemux86 on an x86 machine is fast since the 
            guest and host architectures match, qemuarm is slower but gives 
            faithful emulation of ARM specific issues. To speed things up these 
            images support using distcc to call a cross-compiler outside the 
            emulated system too. If <span><strong class="command">runqemu</strong></span> was used to start
            QEMU, and distccd is present on the host system, any bitbake cross 
            compiling toolchain available from the build system will automatically
            be used from within qemu simply by calling distcc 
            (<span><strong class="command">export CC="distcc"</strong></span> can be set in the enviroment).
            Alterntatively, if a suitable SDK/toolchain is present in 
            <code class="filename">/usr/local/poky</code> it will also
            automatically be used.
        </p><p>
            There are several options for connecting into the emulated system. 
            QEMU provides a framebuffer interface which has standard consoles 
            available. There is also a serial connection available which has a 
            console to the system running on it and IP networking as standard. 
            The images have a dropbear ssh server running with the root password 
            disabled allowing standard ssh and scp commands to work. The images
            also contain an NFS server exporting the guest's root filesystem 
            allowing that to be made available to the host.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-chroot"></a>1.4.�Developing externally in a chroot</h3></div></div></div><p>
            If you have a system that matches the architecture of the Poky machine you're using,
            such as qemux86, you can run binaries directly from the image on the host system
            using a chroot combined with tools like <a href="http://projects.o-hand.com/xephyr" target="_top">Xephyr</a>.
        </p><p>
            Poky has some scripts to make using its qemux86 images within a chroot easier. To use
            these you need to install the poky-scripts package or otherwise obtain the 
            <code class="filename">poky-chroot-setup</code> and <code class="filename">poky-chroot-run</code> scripts.
            You also need Xephyr and chrootuid binaries available. To initialize a system use the setup script:
        </p><p>
            </p><pre class="literallayout">
# poky-chroot-setup &lt;qemux86-rootfs.tgz&gt; &lt;target-directory&gt;
</pre><p>
        </p><p>
            which will unpack the specified qemux86 rootfs tarball into the target-directory. 
            You can then start the system with:
        </p><p>
            </p><pre class="literallayout">
# poky-chroot-run &lt;target-directory&gt; &lt;command&gt;
</pre><p>
        </p><p>
            where the target-directory is the place the rootfs was unpacked to and command is 
            an optional command to run. If no command is specified, the system will drop you 
            within a bash shell. A Xephyr window will be displayed containing the emulated 
            system and you may be asked for a password since some of the commands used for 
            bind mounting directories need to be run using sudo.
        </p><p>
            There are limits as to how far the the realism of the chroot environment extends.
            It is useful for simple development work or quick tests but full system emulation 
            with QEMU offers a much more realistic environment for more complex development 
            tasks. Note that chroot support within Poky is still experimental.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-insitu"></a>1.5.�Developing in Poky directly</h3></div></div></div><p>
            Working directly in Poky is a fast and effective development technique.
            The idea is that you can directly edit files in 
            <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em> 
            or the source directory <em class="glossterm"><a href="#var-S" title="S">S</a></em> 
            and then force specific tasks to rerun in order to test the changes. 
            An example session working on the matchbox-desktop package might 
            look like this:
        </p><p>
            </p><pre class="literallayout">
$ bitbake matchbox-desktop
$ sh
$ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/
$ cd matchbox-desktop-2
$ vi src/main.c
$ exit
$ bitbake matchbox-desktop -c compile -f
$ bitbake matchbox-desktop
</pre><p>
        </p><p>
            Here, we build the package, change into the work directory for the package,
            change a file, then recompile the package. Instead of using sh like this,
            you can also use two different terminals. The risk with working like this 
            is that a command like unpack could wipe out the changes you've made to the
            work directory so you need to work carefully.
        </p><p>
            It is useful when making changes directly to the work directory files to do
            so using quilt as detailed in the <a href="#usingpoky-modifying-packages-quilt" title="5.1.�Modifying Package Source Code with quilt"> 
            modifying packages with quilt</a> section. The resulting patches can be copied 
            into the recipe directory and used directly in the <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em>.
        </p><p>
            For a review of the skills used in this section see Sections <a href="#usingpoky-components-bitbake" title="1.1.�Bitbake">2.1.1</a> and <a href="#usingpoky-debugging-taskrunning" title="4.2.�Running specific tasks">2.4.2</a>.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-devshell"></a>1.6.�Developing with 'devshell'</h3></div></div></div><p>
            When debugging certain commands or even to just edit packages, the
            'devshell' can be a useful tool. To start it you run a command like:
        </p><p>
            </p><pre class="literallayout">
$ bitbake matchbox-desktop -c devshell
</pre><p>
        </p><p>
            which will open a terminal with a shell prompt within the Poky 
            environment. This means PATH is setup to include the cross toolchain, 
            the pkgconfig variables are setup to find the right .pc files, 
            configure will be able to find the Poky site files etc. Within this 
            environment, you can run configure or compile command as if they 
            were being run by Poky itself. You are also changed into the 
            source (<em class="glossterm"><a href="#var-S" title="S">S</a></em>) 
            directory automatically. When finished with the shell just exit it
            or close the terminal window.
        </p><p>
            The default shell used by devshell is the gnome-terminal. Other 
            forms of terminal can also be used by setting the <em class="glossterm">
            <a href="#var-TERMCMD" title="TERMCMD">TERMCMD</a></em> and <em class="glossterm">
            <a href="#var-TERMCMDRUN" title="TERMCMDRUN">TERMCMDRUN</a></em> variables 
            in local.conf. For examples of the other options available, see 
            <code class="filename">meta/conf/bitbake.conf</code>. An external shell is 
            launched rather than opening directly into the original terminal 
            window to make interaction with bitbakes multiple threads easier 
            and also allow a client/server split of bitbake in the future 
            (devshell will still work over X11 forwarding or similar).
        </p><p>
            It is worth remembering that inside devshell you need to use the full
            compiler name such as <span><strong class="command">arm-poky-linux-gnueabi-gcc</strong></span> 
            instead of just <span><strong class="command">gcc</strong></span> and the same applies to other 
            applications from gcc, bintuils, libtool etc. Poky will have setup 
            environmental variables such as CC to assist applications, such as make,
            find the correct tools.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-srcrev"></a>1.7.�Developing within Poky with an external SCM based package</h3></div></div></div><p>
            If you're working on a recipe which pulls from an external SCM it 
            is possible to have Poky notice new changes added to the 
            SCM and then build the latest version. This only works for SCMs
            where its possible to get a sensible revision number for changes.
            Currently it works for svn, git and bzr repositories.
        </p><p>
            To enable this behaviour it is simply a case of adding <em class="glossterm">
            <a href="#var-SRCREV" title="SRCREV">SRCREV</a></em>_pn-<em class="glossterm">
            <a href="#var-PN" title="PN">PN</a></em> = "${AUTOREV}" to 
            local.conf where <em class="glossterm"><a href="#var-PN" title="PN">PN</a></em> 
            is the name of the package for which you want to enable automatic source 
            revision updating.
        </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="platdev-gdb-remotedebug"></a>2.�Debugging with GDB Remotely</h2></div></div></div><p>
        <a href="http://sourceware.org/gdb/" target="_top">GDB</a> (The GNU Project Debugger)
        allows you to examine running programs to understand and fix problems and
        also to perform postmortem style analsys of program crashes. It is available
        as a package within poky and installed by default in sdk images. It works best
        when -dbg packages for the application being debugged are installed as the 
        extra symbols give more meaningful output from GDB. 
    </p><p>
        Sometimes, due to memory or disk space constraints, it is not possible
        to use GDB directly on the remote target to debug applications. This is 
        due to the fact that
        GDB needs to load the debugging information and the binaries of the
        process being debugged. GDB then needs to perform many
        computations to locate information such as function names, variable
        names and values, stack traces, etc. even before starting the debugging
        process. This places load on the target system and can alter the
        characteristics of the program being debugged.
    </p><p>
        This is where GDBSERVER comes into play as it runs on the remote target
        and does not load any debugging information from the debugged process.
        Instead, the debugging information processing is done by a GDB instance
        running on a distant computer - the host GDB. The host GDB then sends 
        control commands to GDBSERVER to make it stop or start the debugged 
        program, as well as read or write some memory regions of that debugged
        program. All the debugging information loading and processing as well
        as the heavy debugging duty is done by the host GDB, giving the 
        GDBSERVER running on the target a chance to remain small and fast.
    </p><p>
        As the host GDB is responsible for loading the debugging information and 
        doing the necessary processing to make actual debugging happen, the 
        user has to make sure it can access the unstripped binaries complete
        with their debugging information and compiled with no optimisations. The
        host GDB must also have local access to all the libraries used by the 
        debugged program. On the remote target the binaries can remain stripped
        as GDBSERVER does not need any debugging information there. However they 
        must also be compiled without optimisation matching the host's binaries.
    </p><p>
        The binary being debugged on the remote target machine is hence referred
        to as the 'inferior' in keeping with GDB documentation and terminology.
        Further documentation on GDB, is available on 
        <a href="http://sourceware.org/gdb/documentation/" target="_top">on their site</a>.
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-gdb-remotedebug-launch-gdbserver"></a>2.1.�Launching GDBSERVER on the target</h3></div></div></div><p>
            First, make sure gdbserver is installed on the target. If not, 
            install the gdbserver package (which needs the libthread-db1
            package).
        </p><p>
            To launch GDBSERVER on the target and make it ready to "debug" a 
            program located at <span class="emphasis"><em>/path/to/inferior</em></span>, connect
            to the target and launch:
            </p><pre class="programlisting">$ gdbserver localhost:2345 /path/to/inferior</pre><p>
            After that, gdbserver should be listening on port 2345 for debugging
            commands coming from a remote GDB process running on the host computer.
            Communication between the GDBSERVER and the host GDB will be done using
            TCP. To use other communication protocols please refer to the 
            GDBSERVER documentation.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-gdb-remotedebug-launch-gdb"></a>2.2.�Launching GDB on the host computer</h3></div></div></div><p>
            Running GDB on the host computer takes a number of stages, described in the
            following sections.
        </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-gdb-remotedebug-launch-gdb-buildcross"></a>2.2.1.�Build the cross GDB package</h4></div></div></div><p>
                A suitable gdb cross binary is required which runs on your host computer but
                knows about the the ABI of the remote target. This can be obtained from
                the the Poky toolchain, e.g. 
                <code class="filename">/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb</code> 
                which "arm" is the target architecture and "linux-gnueabi" the target ABI.
            </p><p>
                Alternatively this can be built directly by Poky. To do this you would build 
                the gdb-cross package so for example you would run:
                </p><pre class="programlisting">bitbake gdb-cross</pre><p>
                Once built, the cross gdb binary can be found at
                </p><pre class="programlisting">tmp/cross/bin/&lt;target-abi&gt;-gdb </pre><p>
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-gdb-remotedebug-launch-gdb-inferiorbins"></a>2.2.2.�Making the inferior binaries available</h4></div></div></div><p>
                The inferior binary needs to be available to GDB complete with all debugging 
                symbols in order to get the best possible results along with any libraries
                the inferior depends on and their debugging symbols. There are a number of
                ways this can be done.
            </p><p>
                Perhaps the easiest is to have an 'sdk' image corresponding to the plain
                image installed on the device. In the case of 'pky-image-sato', 
                'poky-image-sdk' would contain suitable symbols. The sdk images already 
                have the debugging symbols installed so its just a question expanding the 
                archive to some location and telling GDB where this is. 
            </p><p>
                Alternatively, poky can build a custom directory of files for a specific 
                debugging purpose by reusing its tmp/rootfs directory, on the host computer
                in a slightly different way to normal. This directory contains the contents 
                of the last built image. This process assumes the image running on the
                target was the last image to be built by Poky, the package <span class="emphasis"><em>foo</em></span>
                contains the inferior binary to be debugged has been built without without 
                optimisation and has debugging information available.
            </p><p>
                Firstly you want to install the <span class="emphasis"><em>foo</em></span> package to tmp/rootfs 
                by doing:
                </p><pre class="programlisting">tmp/staging/i686-linux/usr/bin/ipkg-cl -f \
tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/ipkg.conf -o \
tmp/rootfs/ update</pre><p>
                then,
                </p><pre class="programlisting">tmp/staging/i686-linux/usr/bin/ipkg-cl -f \
tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/ipkg.conf \
-o tmp/rootfs install foo

tmp/staging/i686-linux/usr/bin/ipkg-cl -f \
tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/ipkg.conf \
-o tmp/rootfs install foo-dbg</pre><p>
                which installs the debugging information too.
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-gdb-remotedebug-launch-gdb-launchhost"></a>2.2.3.�Launch the host GDB</h4></div></div></div><p>
                To launch the host GDB, run the cross gdb binary identified above with
                the inferior binary specified on the commandline:
                </p><pre class="programlisting">&lt;target-abi&gt;-gdb rootfs/usr/bin/foo</pre><p>
                This loads the binary of program <span class="emphasis"><em>foo</em></span>
                as well as its debugging information. Once the gdb prompt
                appears, you must instruct GDB to load all the libraries
                of the inferior from tmp/rootfs:
                </p><pre class="programlisting">set solib-absolute-prefix /path/to/tmp/rootfs</pre><p>
                where <code class="filename">/path/to/tmp/rootfs</code> must be 
                the absolute path to <code class="filename">tmp/rootfs</code> or wherever the 
                binaries with debugging information are located.
            </p><p>
                Now, tell GDB to connect to the GDBSERVER running on the remote target:
                </p><pre class="programlisting">target remote remote-target-ip-address:2345</pre><p>
                Where remote-target-ip-address is the IP address of the
                remote target where the GDBSERVER is running. 2345 is the
                port on which the GDBSERVER is running.
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-gdb-remotedebug-launch-gdb-using"></a>2.2.4.�Using the Debugger</h4></div></div></div><p>
                Debugging can now proceed as normal, as if the debugging were being done on the 
                local machine, for example to tell GDB to break in the <span class="emphasis"><em>main</em></span> 
                function, for instance:
                </p><pre class="programlisting">break main</pre><p>
                and then to tell GDB to "continue" the inferior execution,
                </p><pre class="programlisting">continue</pre><p>
            </p><p>
                For more information about using GDB please see the 
                project's online documentation at <a href="http://sourceware.org/gdb/download/onlinedocs/" target="_top">http://sourceware.org/gdb/download/onlinedocs/</a>.
            </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="platdev-oprofile"></a>3.�Profiling with OProfile</h2></div></div></div><p>
        <a href="http://oprofile.sourceforge.net/" target="_top">OProfile</a> is a 
        statistical profiler well suited to finding performance 
        bottlenecks in both userspace software and the kernel. It provides 
        answers to questions like "Which functions does my application spend 
        the most time in when doing X?". Poky is well integrated with OProfile
        to make profiling applications on target hardware straightforward.
    </p><p>
        To use OProfile you need an image with OProfile installed. The easiest 
        way to do this is with "tools-profile" in <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em>. You also
        need debugging symbols to be available on the system where the analysis 
        will take place. This can be achieved with "dbg-pkgs" in <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em> or by
        installing the appropriate -dbg packages. For 
        successful call graph analysis the binaries must preserve the frame 
        pointer register and hence should be compiled with the 
        "-fno-omit-framepointer" flag. In Poky this can be achieved with 
        <em class="glossterm"><a href="#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION
        </a></em> = "-fexpensive-optimizations -fno-omit-framepointer 
        -frename-registers -O2" or by setting <em class="glossterm"><a href="#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a></em> = "1" in 
        local.conf (the latter will also add extra debug information making the
        debug packages large).
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-oprofile-target"></a>3.1.�Profiling on the target</h3></div></div></div><p>
            All the profiling work can be performed on the target device. A 
            simple OProfile session might look like:
        </p><p>
            </p><pre class="literallayout">
# opcontrol --reset
# opcontrol --start --separate=lib --no-vmlinux -c 5
[do whatever is being profiled]
# opcontrol --stop
$ opreport -cl
</pre><p>
        </p><p>
            Here, the reset command clears any previously profiled data, 
            OProfile is then started. The options used to start OProfile mean
            dynamic library data is kept separately per application, kernel 
            profiling is disabled and callgraphing is enabled up to 5 levels 
            deep. To profile the kernel, you would specify the 
            <em class="parameter"><code>--vmlinux=/path/to/vmlinux</code></em> option (the vmlinux file is usually in 
            <code class="filename">/boot/</code> in Poky and must match the running kernel). The profile is 
            then stopped and the results viewed with opreport with options
            to see the separate library symbols and callgraph information.
        </p><p>
            Callgraphing means OProfile not only logs infomation about which 
            functions time is being spent in but also which functions
            called those functions (their parents) and which functions that 
            function calls (its children). The higher the callgraphing depth, 
            the more accurate the results but this also increased the loging 
            overhead so it should be used with caution. On ARM, binaries need 
            to have the frame pointer enabled for callgraphing to work (compile
            with the gcc option -fno-omit-framepointer).
        </p><p>
            For more information on using OProfile please see the OProfile 
            online documentation at <a href="http://oprofile.sourceforge.net/docs/" target="_top">http://oprofile.sourceforge.net/docs/</a>.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-oprofile-oprofileui"></a>3.2.�Using OProfileUI</h3></div></div></div><p>
            A graphical user interface for OProfile is also available. You can
            either use prebuilt Debian packages from the <a href="http://debian.o-hand.com/" target="_top">OpenedHand repository</a> or
            download and build from svn at
            http://svn.o-hand.com/repos/oprofileui/trunk/. If the
            "tools-profile" image feature is selected, all necessary binaries
            are installed onto the target device for OProfileUI interaction.
        </p><p>
            In order to convert the data in the sample format from the target
            to the host the <code class="filename">opimport</code> program is needed. 
            This is not included in standard Debian OProfile packages but an 
            OProfile package with this addition is also available from the <a href="http://debian.o-hand.com/" target="_top">OpenedHand repository</a>.
            We recommend using OProfile 0.9.3 or greater. Other patches to
            OProfile may be needed for recent OProfileUI features, but Poky 
            usually includes all needed patches on the target device.  Please 
            see the <a href="http://svn.o-hand.com/repos/oprofileui/trunk/README" target="_top">
                OProfileUI README</a> for up to date information, and the 
            <a href="http://labs.o-hand.com/oprofileui" target="_top">OProfileUI website
            </a> for more information on the OProfileUI project. 
        </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-oprofile-oprofileui-online"></a>3.2.1.�Online mode</h4></div></div></div><p>
                This assumes a working network connection with the target 
                hardware. In this case you just need to run <span><strong class="command">
                "oprofile-server"</strong></span> on the device. By default it listens 
                on port 4224. This can be changed with the <em class="parameter"><code>--port</code></em> command line 
                option.

            </p><p>
                The client program is called <span><strong class="command">oprofile-viewer</strong></span>. The  
                UI is relatively straightforward, the key functionality is accessed
                through the buttons on the toolbar (which are duplicated in the 
                menus.) These buttons are:
            </p><div class="itemizedlist"><ul type="disc"><li><p>
                        Connect - connect to the remote host, the IP address or hostname for the
                        target can be supplied here.
                    </p></li><li><p>
                        Disconnect - disconnect from the target.
                    </p></li><li><p>
                        Start - start the profiling on the device.
                    </p></li><li><p>
                        Stop - stop the profiling on the device and download the data to the local
                        host. This will generate the profile and show it in the viewer.
                    </p></li><li><p>
                        Download - download the data from the target, generate the profile and show it
                        in the viewer.
                    </p></li><li><p>
                        Reset - reset the sample data on the device. This will remove the sample
                        information that was collected on a previous sampling run. Ensure you do this
                        if you do not want to include old sample information.
                    </p></li><li><p>
                        Save - save the data downloaded from the target to another directory for later
                        examination.
                    </p></li><li><p>
                        Open - load data that was previously saved.
                    </p></li></ul></div><p>
                The behaviour of the client is to download the complete 'profile archive' from
                the target to the host for processing. This archive is a directory containing
                the sample data, the object files and the debug information for said object
                files. This archive is then converted using a script included in this
                distribution ('oparchconv') that uses 'opimport' to convert the archive from
                the target to something that can be processed on the host.
            </p><p>
                Downloaded archives are kept in /tmp and cleared up when they are no longer in
                use.
            </p><p>
                If you wish to profile into the kernel, this is possible, you just need to ensure
                a vmlinux file matching the running kernel is available. In Poky this is usually 
                located in /boot/vmlinux-KERNELVERSION, where KERNEL-version is the version of 
                the kernel e.g. 2.6.23. Poky generates separate vmlinux packages for each kernel
                it builds so it should be a question of just ensuring a matching package is 
                installed (<span><strong class="command"> ipkg install kernel-vmlinux</strong></span>. These are automatically 
                installed into development and profiling images alongside OProfile. There is a 
                configuration option within the OProfileUI settings page where the location of 
                the vmlinux file can be entered. 
            </p><p>
                Waiting for debug symbols to transfer from the device can be slow and it's not     
                always necessary to actually have them on device for OProfile use. All that is 
                needed is a copy of the filesystem with the debug symbols present on the viewer 
                system. The <a href="#platdev-gdb-remotedebug-launch-gdb" title="2.2.�Launching GDB on the host computer">GDB remote debug
                section</a> covers how to create such a directory with Poky and the location 
                of this directory can again be specified in the OProfileUI settings dialog. If
                specified, it will be used where the file checksums match those on the system 
                being profiled.
            </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-oprofile-oprofileui-offline"></a>3.2.2.�Offline mode</h4></div></div></div><p>
                If no network access to the target is available an archive for processing in
                'oprofile-viewer' can be generated with the following set of command.
            </p><p>
                </p><pre class="literallayout">
# opcontrol --reset
# opcontrol --start --separate=lib --no-vmlinux -c 5
[do whatever is being profiled]
# opcontrol --stop
# oparchive -o my_archive
</pre><p>
            </p><p>
                Where my_archive is the name of the archive directory where you would like the
                profile archive to be kept. The directory will be created for you. This can
                then be copied to another host and loaded using 'oprofile-viewer''s open
                functionality. The archive will be converted if necessary.
            </p></div></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-structure"></a>Appendix�1.�Reference: Directory Structure</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#structure-core">1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">1.3. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-extras">1.4. <code class="filename">meta-extras/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">1.5. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-sources">1.6. <code class="filename">sources/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">1.7. <code class="filename">poky-init-build-env</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">2. <code class="filename">build/</code> - The Build Directory</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-conf-local.conf">2.1. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">2.2. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">2.3. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cross">2.4. <code class="filename">build/tmp/cross/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">2.5. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">2.6. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">2.7. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">2.8. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-rootfs">2.9. <code class="filename">build/tmp/rootfs/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-staging">2.10. <code class="filename">build/tmp/staging/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">2.11. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">2.12. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">3. <code class="filename">meta/</code> - The Metadata</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-packages">3.5. <code class="filename">meta/packages/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">3.6. <code class="filename">meta/site/</code></a></span></dt></dl></dd></dl></div><p>
    Poky consists of several components and understanding what these are 
    and where they're located is one of the keys to using it. This section walks 
    through the Poky directory structure giving information about the various 
    files and directories.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="structure-core"></a>1.�Top level core components</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-bitbake"></a>1.1.�<code class="filename">bitbake/</code></h3></div></div></div><p>
            A copy of BitBake is included within Poky for ease of use, and should 
            usually match the current BitBake stable release from the BitBake project. 
            Bitbake, a metadata interpreter, reads the Poky metadata and runs the tasks 
            defined in the Poky metadata. Failures are usually from the metadata, not 
            BitBake itself, so most users don't need to worry about BitBake. The 
            <code class="filename">bitbake/bin/</code> directory is placed 
            into the PATH environment variable by the <a href="#structure-core-script" title="1.7.�poky-init-build-env">poky-init-build-env</a> script.
        </p><p>
            For more information on BitBake please see the BitBake project site at 
            <a href="http://bitbake.berlios.de/" target="_top">http://bitbake.berlios.de/</a> 
            and the BitBake on-line manual at <a href="http://bitbake.berlios.de/manual/" target="_top">http://bitbake.berlios.de/manual/</a>.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-build"></a>1.2.�<code class="filename">build/</code></h3></div></div></div><p>
            This directory contains user configuration files and the output 
            from Poky.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-meta"></a>1.3.�<code class="filename">meta/</code></h3></div></div></div><p>
            This directory contains the core metadata, a key part of Poky. Within this 
            directory there are definitions of the machines, the Poky distribution 
            and the packages that make up a given system.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-meta-extras"></a>1.4.�<code class="filename">meta-extras/</code></h3></div></div></div><p>
            This directory is similar to <code class="filename">meta/</code>, 
            and contains some extra metadata not included in standard Poky.  These are 
            disabled by default, and are not supported as part of Poky.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-scripts"></a>1.5.�<code class="filename">scripts/</code></h3></div></div></div><p>
            This directory contains various integration scripts which implement 
            extra functionality in the Poky environment, such as the QEMU 
            scripts. This directory is appended to the PATH environment variable by the 
            <a href="#structure-core-script" title="1.7.�poky-init-build-env">poky-init-build-env</a> script.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-sources"></a>1.6.�<code class="filename">sources/</code></h3></div></div></div><p>
            While not part of a checkout, Poky will create this directory as 
            part of any build. Any downloads are placed in this directory (as 
            specified by the <em class="glossterm"><a href="#var-DL_DIR" title="DL_DIR">DL_DIR</a>
            </em> variable). This directory can be shared between Poky 
            builds to save downloading files multiple times. SCM checkouts are 
            also stored here as e.g. <code class="filename">sources/svn/
            </code>, <code class="filename">sources/cvs/</code> or 
            <code class="filename">sources/git/</code> and the 
            sources directory may contain archives of checkouts for various 
            revisions or dates.
        </p><p>
            It's worth noting that BitBake creates <code class="filename">.md5 
            </code> stamp files for downloads. It uses these to mark downloads as 
            complete as well as for checksum and access accounting purposes. If you add 
            a file manually to the directory, you need to touch the corresponding 
            <code class="filename">.md5</code> file too.
        </p><p>
            This location can be overridden by setting <em class="glossterm"><a href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></em> in <code class="filename">local.conf
            </code>. This directory can be shared between builds and even between 
            machines via NFS, so downloads are only made once, speeding up builds.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-script"></a>1.7.�<code class="filename">poky-init-build-env</code></h3></div></div></div><p>
            This script is used to setup the Poky build environment. Sourcing this file in
            a shell makes changes to PATH and sets other core BitBake variables based on the
            current working directory. You need to use this before running Poky commands.
            Internally it uses scripts within the <code class="filename">scripts/ 
            </code> directory to do the bulk of the work.
        </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="structure-build"></a>2.�<code class="filename">build/</code> - The Build Directory</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-conf-local.conf"></a>2.1.�<code class="filename">build/conf/local.conf</code></h3></div></div></div><p>
            This file contains all the local user configuration of Poky. If there
            is no <code class="filename">local.conf</code> present, it is created from 
            <code class="filename">local.conf.sample</code>. The <code class="filename">local.conf</code> 
            file contains documentation on the various configuration options.  Any 
            variable set here overrides any variable set elsewhere within Poky unless 
            that variable is hardcoded within Poky (e.g. by using '=' instead of '?='). 
            Some variables are hardcoded for various reasons but these variables are 
            relatively rare.
        </p><p>
            Edit this file to set the <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a></em> for which you want to build, which package types you
            wish to use (PACKAGE_CLASSES) or where downloaded files should go 
            (<em class="glossterm"><a href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></em>).
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp"></a>2.2.�<code class="filename">build/tmp/</code></h3></div></div></div><p>
            This is created by BitBake if it doesn't exist and is where all the Poky output
            is placed. To clean Poky and start a build from scratch (other than downloads), 
            you can wipe this directory. The <code class="filename">tmp/
            </code> directory has some important sub-components detailed below.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-cache"></a>2.3.�<code class="filename">build/tmp/cache/</code></h3></div></div></div><p>
            When BitBake parses the metadata it creates a cache file of the result which can
            be used when subsequently running commands. These are stored here on 
            a per machine basis.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-cross"></a>2.4.�<code class="filename">build/tmp/cross/</code></h3></div></div></div><p>
            The cross compiler when generated is placed into this directory and those
            beneath it.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-deploy"></a>2.5.�<code class="filename">build/tmp/deploy/</code></h3></div></div></div><p>Any 'end result' output from Poky is placed under here.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-deploy-deb"></a>2.6.�<code class="filename">build/tmp/deploy/deb/</code></h3></div></div></div><p>
            Any .deb packages emitted by Poky are placed here, sorted into feeds for 
            different architecture types.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-deploy-images"></a>2.7.�<code class="filename">build/tmp/deploy/images/</code></h3></div></div></div><p>
            Complete filesystem images are placed here. If you want to flash the resulting 
            image from a build onto a device, look here for them.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-deploy-ipk"></a>2.8.�<code class="filename">build/tmp/deploy/ipk/</code></h3></div></div></div><p>Any resulting .ipk packages emitted by Poky are placed here.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-rootfs"></a>2.9.�<code class="filename">build/tmp/rootfs/</code></h3></div></div></div><p>
            This is a temporary scratch area used when creating filesystem images. It is run
            under fakeroot and is not useful once that fakeroot session has ended as 
            information is lost. It is left around since it is still useful in debugging 
            image creation problems.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-staging"></a>2.10.�<code class="filename">build/tmp/staging/</code></h3></div></div></div><p>
            Any package needing to share output with other packages does so within staging.
            This means it contains any shared header files and any shared libraries amongst
            other data. It is subdivided by architecture so multiple builds can run within
            the one build directory.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-stamps"></a>2.11.�<code class="filename">build/tmp/stamps/</code></h3></div></div></div><p>
            This is used by BitBake for accounting purposes to keep track of which tasks 
            have been run and when. It is also subdivided by architecture. The files are 
            empty and the important information is the filenames and timestamps.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-work"></a>2.12.�<code class="filename">build/tmp/work/</code></h3></div></div></div><p>
            This directory contains various subdirectories for each architecture, and each package built by BitBake has its own work directory under the appropriate architecture subdirectory.  All tasks are executed from this work directory.  As an example, the source for a particular package will be unpacked, patched, configured and compiled all within its own work directory.
        </p><p>
            It is worth considering the structure of a typical work directory. An 
            example is the linux-rp kernel, version 2.6.20 r7 on the machine spitz 
            built within Poky.  For this package a work directory of <code class="filename">tmp/work/spitz-poky-linux-gnueabi/linux-rp-2.6.20-r7/
            </code>, referred to as <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR
            </a></em>, is created.  Within this directory, the source is 
            unpacked to linux-2.6.20 and then patched by quilt (see <a href="#usingpoky-modifying-packages-quilt" title="5.1.�Modifying Package Source Code with quilt">Section 3.5.1</a>).   
            Within the <code class="filename">linux-2.6.20</code> directory, 
            standard Quilt directories <code class="filename">linux-2.6.20/patches</code>
            and <code class="filename">linux-2.6.20/.pc</code> are created,
            and standard quilt commands can be used.
        </p><p>
            There are other directories generated within <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em>. The most important 
            is <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em><code class="filename">/temp/</code> which has log files for each 
            task (<code class="filename">log.do_*.pid</code>) and the scripts BitBake runs for 
            each task (<code class="filename">run.do_*.pid</code>). The <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em><code class="filename">/image/</code> directory is where <span><strong class="command">make 
            install</strong></span> places its output which is then split into subpackages 
            within <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em><code class="filename">/install/</code>.
        </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="structure-meta"></a>3.�<code class="filename">meta/</code> - The Metadata</h2></div></div></div><p>
        As mentioned previously, this is the core of Poky. It has several 
        important subdivisions:
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-classes"></a>3.1.�<code class="filename">meta/classes/</code></h3></div></div></div><p>
            Contains the <code class="filename">*.bbclass</code> files. Class 
            files are used to abstract common code allowing it to be reused by multiple 
            packages. The <code class="filename">base.bbclass</code> file is inherited by every 
            package. Examples of other important classes are 
            <code class="filename">autotools.bbclass</code> that in theory allows any 
            Autotool-enabled package to work with Poky with minimal effort, or 
            <code class="filename">kernel.bbclass</code> that contains common code and functions 
            for working with the linux kernel. Functions like image generation or 
            packaging also have their specific class files (<code class="filename">image.bbclass
            </code>, <code class="filename">rootfs_*.bbclass</code> and 
            <code class="filename">package*.bbclass</code>).
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-conf"></a>3.2.�<code class="filename">meta/conf/</code></h3></div></div></div><p>
            This is the core set of configuration files which start from 
            <code class="filename">bitbake.conf</code> and from which all other configuration 
            files are included (see the includes at the end of the file, even 
            <code class="filename">local.conf</code> is loaded from there!). While 
            <code class="filename">bitbake.conf</code> sets up the defaults, these can often be 
            overridden by user (<code class="filename">local.conf</code>), machine or 
            distribution configuration files.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-conf-machine"></a>3.3.�<code class="filename">meta/conf/machine/</code></h3></div></div></div><p>
            Contains all the machine configuration files. If you set MACHINE="spitz", the 
            end result is Poky looking for a <code class="filename">spitz.conf</code> file in this directory. The includes
            directory contains various data common to multiple machines. If you want to add
            support for a new machine to Poky, this is the directory to look in.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-conf-distro"></a>3.4.�<code class="filename">meta/conf/distro/</code></h3></div></div></div><p>
            Any distribution specific configuration is controlled from here. OpenEmbedded 
            supports multiple distributions of which Poky is one. Poky only contains the 
            Poky distribution so poky.conf is the main file here.  This includes the 
            versions and SRCDATES for applications which are configured here. An example of 
            an alternative configuration is poky-bleeding.conf although this mainly inherits
            its configuration from Poky itself.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-packages"></a>3.5.�<code class="filename">meta/packages/</code></h3></div></div></div><p>
            Each application (package) Poky can build has an associated .bb file which are 
            all stored under this directory. Poky finds them through the BBFILES variable 
            which defaults to packages/*/*.bb. Adding a new piece of software to Poky 
            consists of adding the appropriate .bb file. The .bb files from OpenEmbedded
            upstream are usually compatible although they are not supported.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-site"></a>3.6.�<code class="filename">meta/site/</code></h3></div></div></div><p>
            Certain autoconf test results cannot be determined when cross compiling since it 
            can't run tests on a live system. This directory therefore contains a list of 
            cached results for various architectures which is passed to autoconf.
        </p></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-bitbake"></a>Appendix�2.�Reference: Bitbake</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref-bitbake-parsing">1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">6. Commandline</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">7. Fetchers</a></span></dt></dl></div><p>
        Bitbake a program written in Python which interprets the metadata
        that makes up Poky. At some point, people wonder what actually happens 
        when you type <span><strong class="command">bitbake poky-image-sato</strong></span>. This section 
        aims to give an overview of what happens behind the scenes from a
        BitBake perspective.
    </p><p>
        It is worth noting that bitbake aims to be a generic "task" executor 
        capable of handling complex dependency relationships. As such it has no 
        real knowledge of what the tasks its executing actually do. It just 
        considers a list of tasks with dependencies and handles metadata 
        consisting of variables in a certain format which get passed to the 
        tasks.
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-parsing"></a>1.�Parsing</h2></div></div></div><p>
            The first thing BitBake does is work out its configuration by 
            looking for a file called <code class="filename">bitbake.conf</code>.
            Bitbake searches through the <code class="varname">BBPATH</code> environment 
            variable looking for a <code class="filename">conf/</code> 
            directory containing a <code class="filename">bitbake.conf</code> file and 
            adds the first <code class="filename">bitbake.conf</code> file found in
            <code class="varname">BBPATH</code> (similar to the PATH environment variable). 
            For Poky, <code class="filename">bitbake.conf</code> is found in <code class="filename">meta/conf/</code>. 
        </p><p>
            In Poky, <code class="filename">bitbake.conf</code> lists other configuration 
            files to include from a <code class="filename">conf/</code> 
            directory below the directories listed in <code class="varname">BBPATH</code>. 
            In general the most important configuration file from a user's perspective 
            is <code class="filename">local.conf</code>, which contains a users customized 
            settings for Poky. Other notable configuration files are the distribution 
            configuration file (set by the <em class="glossterm"><a href="#var-DISTRO" title="DISTRO">
            DISTRO</a></em> variable) and the machine configuration file 
            (set by the <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a>
            </em> variable).  The <em class="glossterm"><a href="#var-DISTRO" title="DISTRO">
            DISTRO</a></em> and <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">
            MACHINE</a></em> environment variables are both usually set in 
            the <code class="filename">local.conf</code> file. Valid distribution 
            configuration files are available in the <code class="filename">
            meta/conf/distro/</code> directory and valid machine configuration 
            files in the <code class="filename">meta/conf/machine/</code> 
            directory. Within the <code class="filename">
            meta/conf/machine/include/</code> directory are various <code class="filename">
            tune-*.inc</code> configuration files which provide common 
            "tuning" settings specific to and shared between particular 
            architectures and machines.
        </p><p>
            After the parsing of the configuration files some standard classes 
            are included. In particular, <code class="filename">base.bbclass</code> is 
            always included, as will any other classes 
            specified in the configuration using the <em class="glossterm"><a href="#var-INHERIT" title="INHERIT">INHERIT</a></em>
            variable. Class files are searched for in a classes subdirectory 
            under the paths in <code class="varname">BBPATH</code> in the same way as
            configuration files.
        </p><p>
            After the parsing of the configuration files is complete, the 
            variable <em class="glossterm"><a href="#var-BBFILES" title="BBFILES">BBFILES</a></em> 
            is set, usually in
            <code class="filename">local.conf</code>, and defines the list of places to search for 
            <code class="filename">.bb</code> files. By 
            default this specifies the <code class="filename">meta/packages/
            </code> directory within Poky, but other directories such as
            <code class="filename">meta-extras/</code> can be included 
            too. If multiple directories are specified a system referred to as 
            <a href="#usingpoky-changes-collections" title="4.1.�Bitbake Collections">"collections"</a> is used to 
            determine which files have priority.
        </p><p>
            Bitbake parses each <code class="filename">.bb</code> file in 
            <em class="glossterm"><a href="#var-BBFILES" title="BBFILES">BBFILES</a></em> and 
            stores the values of various variables.  In summary, for each 
            <code class="filename">.bb</code> 
            file the configuration + base class of variables are set, followed 
            by the data in the <code class="filename">.bb</code> file 
            itself, followed by any inherit commands that
            <code class="filename">.bb</code> file might contain.
        </p><p>
            Parsing <code class="filename">.bb</code> files is a time 
            consuming process, so a cache is kept to speed up subsequent parsing. 
            This cache is invalid if the timestamp of the <code class="filename">.bb</code> 
            file itself has changed, or if the timestamps of any of the include, 
            configuration or class files the <code class="filename">.bb</code>
            file depends on have changed.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-providers"></a>2.�Preferences and Providers</h2></div></div></div><p>
            Once all the <code class="filename">.bb</code> files have been 
            parsed, BitBake will proceed to build "poky-image-sato" (or whatever was
            specified on the commandline) and looks for providers of that target.
            Once a provider is selected, BitBake resolves all the dependencies for  
            the target. In the case of "poky-image-sato", it would lead to 
            <code class="filename">task-oh.bb</code> and <code class="filename">task-base.bb</code>  
            which in turn would lead to packages like <span class="application">Contacts</span>, 
            <span class="application">Dates</span>, <span class="application">BusyBox</span>
            and these in turn depend on glibc and the toolchain.
        </p><p>
            Sometimes a target might have multiple providers and a common example 
            is "virtual/kernel" that is provided by each kernel package. Each machine
            will often elect the best provider of its kernel with a line like the 
            following in the machine configuration file:
        </p><pre class="programlisting"><em class="glossterm"><a href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">PREFERRED_PROVIDER</a></em>_virtual/kernel = "linux-rp"</pre><p>
            The default <em class="glossterm"><a href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">
            PREFERRED_PROVIDER</a></em> is the provider with the same name as
            the target.
        </p><p>
            Understanding how providers are chosen is complicated by the fact
            multiple versions might be present. Bitbake defaults to the highest 
            version of a provider by default. Version comparisons are made using 
            the same method as Debian. The <em class="glossterm"><a href="#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></em>
            variable can be used to specify a particular version 
            (usually in the distro configuration) but the order can 
            also be influenced by the <em class="glossterm"><a href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></em> 
            variable. By default files 
            have a preference of "0". Setting the
            <em class="glossterm"><a href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></em> to "-1" will 
            make a package unlikely to be used unless it was explicitly referenced and
            "1" makes it likely the package will be used. 
            <em class="glossterm"><a href="#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></em> overrides 
            any default preference. <em class="glossterm"><a href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></em> 
            is often used to mark more 
            experimental new versions of packages until they've undergone sufficient 
            testing to be considered stable.
        </p><p>
            The end result is that internally, BitBake has now built a list of 
            providers for each target it needs in order of priority.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-dependencies"></a>3.�Dependencies</h2></div></div></div><p>
            Each target BitBake builds consists of multiple tasks (e.g. fetch, 
            unpack, patch, configure, compile etc.). For best performance on 
            multi-core systems, BitBake considers each task as an independent 
            entity with a set of dependencies. There are many variables that 
            are used to signify these dependencies and more information can be found 
            found about these in the <a href="http://bitbake.berlios.de/manual/" target="_top">
            BitBake manual</a>. At a basic level it is sufficient to know 
        that BitBake uses the <em class="glossterm"><a href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></em> and 
        <em class="glossterm"><a href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></em> variables when 
            calculating dependencies and descriptions of these variables are 
            available through the links. 
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-tasklist"></a>4.�The Task List</h2></div></div></div><p>
            Based on the generated list of providers and the dependency information, 
            BitBake can now calculate exactly which tasks it needs to run and in what 
            order. The build now starts with BitBake forking off threads up to
            the limit set in the <em class="glossterm"><a href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a></em> variable
            as long there are tasks ready to run, i.e. tasks with all their
            dependencies met.
        </p><p>
            As each task completes, a timestamp is written to the directory 
            specified by the <em class="glossterm"><a href="#var-STAMPS" title="STAMPS">STAMPS</a></em> variable (usually 
            <code class="filename">build/tmp/stamps/*/</code>). On 
            subsequent runs, BitBake looks at the <em class="glossterm"><a href="#var-STAMPS" title="STAMPS">STAMPS</a></em>
            directory and will not rerun 
            tasks its already completed unless a timestamp is found to be invalid. 
            Currently, invalid timestamps are only considered on a per <code class="filename">.bb</code> file basis so if for example the configure stamp has a timestamp greater than the 
            compile timestamp for a given target the compile task would rerun but this 
            has no effect on other providers depending on that target. This could 
            change or become configurable in future versions of BitBake. Some tasks 
            are marked as "nostamp" tasks which means no timestamp file will be written 
            and the task will always rerun.
        </p><p>Once all the tasks have been completed BitBake exits.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-runtask"></a>5.�Running a Task</h2></div></div></div><p>
            It's worth noting what BitBake does to run a task. A task can either
            be a shell task or a python task. For shell tasks, BitBake writes a
            shell script to <code class="filename">${WORKDIR}/temp/run.do_taskname.pid</code>
            and then executes the script. The generated
            shell script contains all the exported variables, and the shell functions 
            with all variables expanded. Output from the shell script is 
            sent to the file <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>.
            Looking at the
            expanded shell functions in the run file and the output in the log files 
            is a useful debugging technique.
        </p><p>
            Python functions are executed internally to BitBake itself and 
            logging goes to the controlling terminal. Future versions of BitBake will 
            write the functions to files in a similar way to shell functions and 
            logging will also go to the log files in a similar way.
        </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-commandline"></a>6.�Commandline</h2></div></div></div><p>
            To quote from "bitbake --help":
        </p><pre class="screen">Usage: bitbake [options] [package ...]

Executes the specified task (default is 'build') for a given set of BitBake files.
It expects that BBFILES is defined, which is a space separated list of files to
be executed.  BBFILES does support wildcards.
Default BBFILES are the .bb files in the current directory.

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -b BUILDFILE, --buildfile=BUILDFILE
                        execute the task against this .bb file, rather than a
                        package from BBFILES.
  -k, --continue        continue as much as possible after an error. While the
                        target that failed, and those that depend on it,
                        cannot be remade, the other dependencies of these
                        targets can be processed all the same.
  -f, --force           force run of specified cmd, regardless of stamp status
  -i, --interactive     drop into the interactive mode also called the BitBake
                        shell.
  -c CMD, --cmd=CMD     Specify task to execute. Note that this only executes
                        the specified task for the providee and the packages
                        it depends on, i.e. 'compile' does not implicitly call
                        stage for the dependencies (IOW: use only if you know
                        what you are doing). Depending on the base.bbclass a
                        listtasks tasks is defined and will show available
                        tasks
  -r FILE, --read=FILE  read the specified file before bitbake.conf
  -v, --verbose         output more chit-chat to the terminal
  -D, --debug           Increase the debug level. You can specify this more
                        than once.
  -n, --dry-run         don't execute, just go through the motions
  -p, --parse-only      quit after parsing the BB files (developers only)
  -d, --disable-psyco   disable using the psyco just-in-time compiler (not
                        recommended)
  -s, --show-versions   show current and preferred versions of all packages
  -e, --environment     show the global or per-package environment (this is
                        what used to be bbread)
  -g, --graphviz        emit the dependency trees of the specified packages in
                        the dot syntax
  -I IGNORED_DOT_DEPS, --ignore-deps=IGNORED_DOT_DEPS
                        Stop processing at the given list of dependencies when
                        generating dependency graphs. This can help to make
                        the graph more appealing
  -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
                        Show debug logging for the specified logging domains
  -P, --profile         profile the command and print a report</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-fetchers"></a>7.�Fetchers</h2></div></div></div><p>
            As well as the containing the parsing and task/dependency handling 
            code, bitbake also contains a set of "fetcher" modules which allow 
            fetching of source code from various types of sources. Example 
            sources might be from disk with the metadata, from websites, from 
            remote shell accounts or from SCM systems like cvs/subversion/git. 
        </p><p>
            The fetchers are usually triggered by entries in 
            <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em>. Information about the 
            options and formats of entries for specific fetchers can be found in the 
            <a href="http://bitbake.berlios.de/manual/" target="_top">BitBake manual</a>.
        </p><p>
            One useful feature for certain SCM fetchers is the ability to 
            "auto-update" when the upstream SCM changes version. Since this 
            requires certain functionality from the SCM only certain systems 
            support it, currently Subversion, Bazaar and to a limited extent, Git. It 
            works using the <em class="glossterm"><a href="#var-SRCREV" title="SRCREV">SRCREV</a>
            </em> variable. See the <a href="#platdev-appdev-srcrev" title="1.7.�Developing within Poky with an external SCM based package">
            developing with an external SCM based project</a> section for more
            information.
        </p></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-classes"></a>Appendix�3.�Reference: Classes</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref-classes-base">1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">12. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">13. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">14. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">15. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">16. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">17. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">18. Other Classes</a></span></dt></dl></div><p>
    Class files are used to abstract common functionality and share it amongst multiple 
    <code class="filename">.bb</code> files. Any metadata usually found in a 
    <code class="filename">.bb</code> file can also be placed in a class 
    file. Class files are identified by the extension 
    <code class="filename">.bbclass</code> and are usually placed 
    in a <code class="filename">classes/</code> directory beneath the 
    <code class="filename">meta/</code> directory or the <code class="filename">build/</code> directory in the same way as <code class="filename">.conf</code> files in the <code class="filename">conf</code> directory. Class files are searched for 
    in BBPATH in the same was as <code class="filename">.conf</code> files too.
</p><p>
    In most cases inheriting the class is enough to enable its features, although 
    for some classes you may need to set variables and/or override some of the 
    default behaviour.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-base"></a>1.�The base class - <code class="filename">base.bbclass</code></h2></div></div></div><p>
        The base class is special in that every <code class="filename">.bb</code> 
        file inherits it automatically. It contains definitions of standard basic 
        tasks such as fetching, unpacking, configuring (empty by default), compiling 
        (runs any Makefile present), installing (empty by default) and packaging 
        (empty by default). These are often overridden or extended by other classes 
        such as <code class="filename">autotools.bbclass</code> or 
        <code class="filename">package.bbclass</code>. The class contains some commonly
        some commonly used functions such as <code class="function">oe_libinstall</code>
        and <code class="function">oe_runmake</code>. The end of the class file has a 
        list of standard mirrors for software projects for use by the fetcher code.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-autotools"></a>2.�Autotooled Packages - <code class="filename">autotools.bbclass</code></h2></div></div></div><p>
        Autotools (autoconf, automake, libtool) brings standardisation and this
        class aims to define a set of tasks (configure, compile etc.) that will
        work for all autotooled packages.  It should usualy be enough to define
        a few standard variables as documented in the <a href="#usingpoky-extend-addpkg-autotools" title="1.2.�Autotooled Package">simple autotools
        example</a> section and then simply "inherit autotools". This class
        can also work with software that emulates autotools.
    </p><p>
        Its useful to have some idea of the tasks this class defines work and
        what they do behind the scenes.
    </p><div class="itemizedlist"><ul type="disc"><li><p>
            'do_configure' regenearates the configure script and
            then launches it with a standard set of arguments used during
            cross-compilation. Additional parameters can be passed to 
            <span><strong class="command">configure</strong></span> through the <em class="glossterm"><a href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></em> variable.
        </p></li><li><p>
            'do_compile' runs <span><strong class="command">make</strong></span> with arguments specifying 
            the compiler and linker. Additional arguments can be passed through 
            the <em class="glossterm"><a href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a>
            </em> variable.
        </p></li><li><p>
            'do_install' runs <span><strong class="command">make install</strong></span> passing a DESTDIR 
            option taking its value from the standard <em class="glossterm"><a href="#var-DESTDIR" title="DESTDIR">DESTDIR</a></em> variable.
        </p></li></ul></div><p>
        By default the class does not stage headers and libraries so
        the recipe author needs to add their own <code class="function">do_stage()</code>
        task. For typical recipes the following example code will usually be
        enough:
       </p><pre class="programlisting">
do_stage() {
autotools_stage_all
}</pre><p>
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-update-alternatives"></a>3.�Alternatives - <code class="filename">update-alternatives.bbclass</code></h2></div></div></div><p>
        Several programs can fulfill the same or similar function and
        they can be installed with the same name. For example the <span><strong class="command">ar</strong></span> 
        command is available from the "busybox", "binutils" and "elfutils" packages. 
        This class handles the renaming of the binaries so multiple packages 
        can be installed which would otherwise conflict and yet the 
        <span><strong class="command">ar</strong></span> command still works regardless of which are installed
        or subsequently removed. It renames the conflicting binary in each package 
        and symlinks the highest priority binary during installation or removal 
        of packages.

        Four variables control this class:
    </p><div class="variablelist"><dl><dt><span class="term">ALTERNATIVE_NAME</span></dt><dd><p>
            Name of binary which will be replaced (<span><strong class="command">ar</strong></span> in this example)
       </p></dd><dt><span class="term">ALTERNATIVE_LINK</span></dt><dd><p>
            Path to resulting binary ("/bin/ar" in this example)
        </p></dd><dt><span class="term">ALTERNATIVE_PATH</span></dt><dd><p>
            Path to real binary ("/usr/bin/ar.binutils" in this example)
        </p></dd><dt><span class="term">ALTERNATIVE_PRIORITY</span></dt><dd><p>
            Priority of binary, the version with the most features should have the highest priority
        </p></dd></dl></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-update-rc.d"></a>4.�Initscripts - <code class="filename">update-rc.d.bbclass</code></h2></div></div></div><p>
        This class uses update-rc.d to safely install an initscript on behalf of 
        the package. Details such as making sure the initscript is stopped before 
        a package is removed and started when the package is installed are taken 
        care of. Three variables control this class, 
        <a href="#var-INITSCRIPT_PACKAGES" title="INITSCRIPT_PACKAGES">INITSCRIPT_PACKAGES</a>, 
        <a href="#var-INITSCRIPT_NAME" title="INITSCRIPT_NAME">INITSCRIPT_NAME</a> and
        <a href="#var-INITSCRIPT_PARAMS" title="INITSCRIPT_PARAMS">INITSCRIPT_PARAMS</a>. See the 
        links for details.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-binconfig"></a>5.�Binary config scripts - <code class="filename">binconfig.bbclass</code></h2></div></div></div><p>
        Before pkg-config became widespread, libraries shipped shell
        scripts to give information about the libraries and include paths needed 
        to build software (usually named 'LIBNAME-config'). This class assists
        any recipe using such scripts.
    </p><p>
        During staging Bitbake installs such scripts into the <code class="filename">staging/</code> directory. It also changes all 
        paths to point into the <code class="filename">staging/</code>
        directory so all builds which use the script will use the correct 
        directories for the cross compiling layout.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-debian"></a>6.�Debian renaming - <code class="filename">debian.bbclass</code></h2></div></div></div><p>
        This class renames packages so that they follow the Debian naming
        policy, i.e. 'glibc' becomes 'libc6' and 'glibc-devel' becomes
        'libc6-dev'.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-pkgconfig"></a>7.�Pkg-config - <code class="filename">pkgconfig.bbclass</code></h2></div></div></div><p>
        Pkg-config brought standardisation and this class aims to make its
        integration smooth for all libraries which make use of it.
    </p><p>
        During staging Bitbake installs pkg-config data into the <code class="filename">staging/</code> directory. By making use of 
        sysroot functionality within pkgconfig this class no longer has to 
        manipulate the files.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-src-distribute"></a>8.�Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></h2></div></div></div><p>
        Many software licenses require providing the sources for compiled
        binaries. To simplify this process two classes were created:
        <code class="filename">src_distribute.bbclass</code> and 
        <code class="filename">src_distribute_local.bbclass</code>.
    </p><p>
        Result of their work are <code class="filename">tmp/deploy/source/</code> 
        subdirs with sources sorted by <em class="glossterm"><a href="#var-LICENSE" title="LICENSE">LICENSE</a>
        </em> field. If recipe lists few licenses (or has entries like "Bitstream Vera") source archive is put in each
        license dir.
    </p><p>
        Src_distribute_local class has three modes of operating:
    </p><div class="itemizedlist"><ul type="disc"><li><p>copy - copies the files to the distribute dir</p></li><li><p>symlink - symlinks the files to the distribute dir</p></li><li><p>move+symlink - moves the files into distribute dir, and symlinks them back</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-perl"></a>9.�Perl modules - <code class="filename">cpan.bbclass</code></h2></div></div></div><p>
        Recipes for Perl modules are simple - usually needs only
        pointing to source archive and inheriting of proper bbclass.
        Building is split into two methods dependly on method used by
        module authors.
    </p><p>
        Modules which use old Makefile.PL based build system require
        using of <code class="filename">cpan.bbclass</code> in their recipes.
    </p><p>
        Modules which use Build.PL based build system require
        using of <code class="filename">cpan_build.bbclass</code> in their recipes.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-distutils"></a>10.�Python extensions - <code class="filename">distutils.bbclass</code></h2></div></div></div><p>
        Recipes for Python extensions are simple - usually needs only
        pointing to source archive and inheriting of proper bbclass.
        Building is split into two methods dependly on method used by
        module authors.
    </p><p>
        Extensions which use autotools based build system require using
        of autotools and distutils-base bbclasses in their recipes.
    </p><p>
        Extensions which use distutils build system require using
        of <code class="filename">distutils.bbclass</code> in their recipes.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-devshell"></a>11.�Developer Shell - <code class="filename">devshell.bbclass</code></h2></div></div></div><p>
        This class adds the devshell task. Its usually up to distribution policy 
        to include this class (Poky does). See the <a href="#platdev-appdev-devshell" title="1.6.�Developing with 'devshell'">developing with 'devshell' section</a> 
        for more information about using devshell.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-package"></a>12.�Packaging - <code class="filename">package*.bbclass</code></h2></div></div></div><p>
        The packaging classes add support for generating packages from the output
        from builds. The core generic functionality is in 
        <code class="filename">package.bbclass</code>, code specific to particular package 
        types is contained in various sub classes such as 
        <code class="filename">package_deb.bbclass</code> and <code class="filename">package_ipk.bbclass</code>. 
        Most users will 
        want one or more of these classes and this is controlled by the <em class="glossterm">
        <a href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></em> 
        variable. The first class listed in this  variable will be used for image 
        generation. Since images are generated from packages a packaging class is 
        needed to enable image generation.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-kernel"></a>13.�Building kernels - <code class="filename">kernel.bbclass</code></h2></div></div></div><p>
        This class handle building of Linux kernels and the class contains code to know how to build both 2.4 and 2.6 kernel trees. All needed headers are
        staged into <em class="glossterm"><a href="#var-STAGING_KERNEL_DIR" title="STAGING_KERNEL_DIR">STAGING_KERNEL_DIR</a></em>
        directory to allow building of out-of-tree modules using <code class="filename">module.bbclass</code>.
    </p><p>
        The means that each kerel module built is packaged separately and inter-modules dependencies are
        created by parsing the <span><strong class="command">modinfo</strong></span> output. If all modules are
        required then installing "kernel-modules" package will install all
        packages with modules and various other kernel packages such as "kernel-vmlinux" are also generated.
    </p><p>
        Various other classes are used by the kernel and module classes internally including 
        <code class="filename">kernel-arch.bbclass</code>, <code class="filename">module_strip.bbclass</code>, 
        <code class="filename">module-base.bbclass</code> and <code class="filename">linux-kernel-base.bbclass</code>.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-image"></a>14.�Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></h2></div></div></div><p>
        Those classes add support for creating images in many formats. First the
        rootfs is created from packages by one of the <code class="filename">rootfs_*.bbclass</code> 
        files (depending on package format used) and then image is created.

        The <em class="glossterm"><a href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></em>
        variable controls which types of image to generate.
        
        The list of packages to install into the image is controlled by the
        <em class="glossterm"><a href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></em>
        variable.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-sanity"></a>15.�Host System sanity checks - <code class="filename">sanity.bbclass</code></h2></div></div></div><p>
        This class checks prerequisite software is present to try and identify
        and notify the user of problems which will affect their build. It also
        performs basic checks of the users configuration from local.conf to
        prevent common mistakes and resulting build failures. Its usually up to 
        distribution policy to include this class (Poky does).
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-insane"></a>16.�Generated output quality assurance checks - <code class="filename">insane.bbclass</code></h2></div></div></div><p>
        This class adds a step to package generation which sanity checks the
        packages generated by Poky. There are an ever increasing range of checks
        this makes, checking for common problems which break builds/packages/images,
        see the bbclass file for more information. Its usually up to distribution
        policy to include this class (Poky doesn't at the time of writing but plans 
        to soon).
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-siteinfo"></a>17.�Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></h2></div></div></div><p>
        Autotools can require tests which have to execute on the target hardware.
        Since this isn't possible in general when cross compiling, siteinfo is
        used to provide cached test results so these tests can be skipped over but
        the correct values used. The <a href="#structure-meta-site" title="3.6.�meta/site/">meta/site directory</a>
        contains test results sorted into different categories like architecture, endianess and
        the libc used. Siteinfo provides a list of files containing data relevant to 
        the current build in the <em class="glossterm"><a href="#var-CONFIG_SITE" title="CONFIG_SITE">CONFIG_SITE
        </a></em> variable which autotools will automatically pick up.
    </p><p>
        The class also provides variables like <em class="glossterm"><a href="#var-SITEINFO_ENDIANESS" title="SITEINFO_ENDIANESS">SITEINFO_ENDIANESS</a></em> 
        and <em class="glossterm"><a href="#var-SITEINFO_BITS" title="SITEINFO_BITS">SITEINFO_BITS</a>
        </em> which can be used elsewhere in the metadata.
    </p><p>
        This class is included from <code class="filename">base.bbclass</code> and is hence always active.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-others"></a>18.�Other Classes</h2></div></div></div><p>
        Only the most useful/important classes are covered here but there are 
        others, see the <code class="filename">meta/classes</code> directory for the rest. 
    </p></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-images"></a>Appendix�4.�Reference: Images</h2></div></div></div><p>
        Poky has several standard images covering most people's standard needs. A full 
        list of image targets can be found by looking in the <code class="filename">
        meta/packages/images/</code> directory. The standard images are listed below 
        along with details of what they contain:
    </p><div class="itemizedlist"><ul type="disc"><li><p>
                    <span class="emphasis"><em>poky-image-minimal</em></span> - A small image, just enough 
                    to allow a device to boot
                </p></li><li><p>
                    <span class="emphasis"><em>poky-image-base</em></span> - console only image with full
                    support of target device hardware
                </p></li><li><p>
                    <span class="emphasis"><em>poky-image-core</em></span> - X11 image with simple apps like
                    terminal, editor and file manager
                </p></li><li><p>
                    <span class="emphasis"><em>poky-image-sato</em></span> - X11 image with Sato theme and
                    Pimlico applications. Also contains terminal, editor and file manager.
                </p></li><li><p>
                    <span class="emphasis"><em>poky-image-sdk</em></span> - X11 image like poky-image-sato but
                    also include native toolchain and libraries needed to build applications 
                    on the device itself. Also includes testing and profiling tools and debug
                    symbols.
                </p></li><li><p>
                    <span class="emphasis"><em>meta-toolchain</em></span> - This generates a tarball containing
                    a standalone toolchain which can be used externally to Poky. It is self
                    contained and unpacks to the <code class="filename">/usr/local/poky</code>
                    directory. It also contains a copy of QEMU and the scripts neccessary to run 
                    poky QEMU images.
                </p></li><li><p>
                    <span class="emphasis"><em>meta-toolchain-sdk</em></span> - This includes everything in 
                    meta-toolchain but also includes development headers and libraries
                    forming a complete standalone SDK. See the <a href="#platdev-appdev-external-sdk" title="1.2.�Developing externally using the Poky SDK"> 
                    Developing using the Poky SDK</a> and <a href="#platdev-appdev-external-anjuta" title="1.1.�Developing externally using the Anjuta Plugin">
                    Developing using the Anjuta Plugin</a> sections for more information.
                </p></li></ul></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-features"></a>Appendix�5.�Reference: Features</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref-features-distro">1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">3. Reference: Images</a></span></dt></dl></div><p>'Features' provide a mechanism for working out which packages
        should be included in the generated images. Distributions can
        select which features they want to support through the
        <a href="#var-DISTRO_FEATURES"><em class="glossterm"><a href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></em></a>
        variable which is set in the distribution configuration file
        (poky.conf for Poky).  Machine features are set in the
        <a href="#var-MACHINE_FEATURES"><em class="glossterm"><a href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></em></a>
        variable which is set in the machine configuration file and
        specifies which hardware features a given machine has.
    </p><p>These two variables are combined to work out which kernel modules,
        utilities and other packages to include. A given distribution can 
        support a selected subset of features so some machine features might not
        be included if the distribution itself doesn't support them.
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-features-distro"></a>1.�Distro</h2></div></div></div><p>The items below are valid options for <a href="#var-DISTRO_FEATURES"><em class="glossterm"><a href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></em></a>.
        </p><div class="itemizedlist"><ul type="disc"><li><p>
                    alsa - ALSA support will be included (OSS compatibility
                    kernel modules will be installed if available)
                </p></li><li><p>
                    bluetooth - Include bluetooth support (integrated BT only)
                </p></li><li><p>
                    ext2 - Include tools for supporting for devices with internal
                    HDD/Microdrive for storing files (instead of Flash only devices)
                </p></li><li><p>
                    irda - Include Irda support
                </p></li><li><p>
                    keyboard - Include keyboard support (e.g. keymaps will be 
                    loaded during boot).
                </p></li><li><p>
                    pci - Include PCI bus support
                </p></li><li><p>
                    pcmcia - Include PCMCIA/CompactFlash support
                </p></li><li><p>
                    usbgadget - USB Gadget Device support (for USB
                    networking/serial/storage)
                </p></li><li><p>
                    usbhost - USB Host support (allows to connect external
                    keyboard, mouse, storage, network etc)
                </p></li><li><p>
                    wifi - WiFi support (integrated only)
                </p></li><li><p>
                    cramfs - CramFS support
                </p></li><li><p>
                    ipsec - IPSec support
                </p></li><li><p>
                    ipv6 - IPv6 support
                </p></li><li><p>
                    nfs - NFS client support (for mounting NFS exports on
                    device)
                </p></li><li><p>
                    ppp - PPP dialup support
                </p></li><li><p>
                    smbfs - SMB networks client support (for mounting
                    Samba/Microsoft Windows shares on device)
                </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-features-machine"></a>2.�Machine</h2></div></div></div><p>The items below are valid options for <a href="#var-MACHINE_FEATURES"><em class="glossterm"><a href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></em></a>.
        </p><div class="itemizedlist"><ul type="disc"><li><p>
                    acpi - Hardware has ACPI (x86/x86_64 only)
                </p></li><li><p>
                    alsa - Hardware has ALSA audio drivers
                </p></li><li><p>
                    apm - Hardware uses APM (or APM emulation)
                </p></li><li><p>
                    bluetooth - Hardware has integrated BT
                </p></li><li><p>
                    ext2 - Hardware HDD or Microdrive
                </p></li><li><p>
                    irda - Hardware has Irda support
                </p></li><li><p>
                    keyboard - Hardware has a keyboard
                </p></li><li><p>
                    pci - Hardware has a PCI bus
                </p></li><li><p>
                    pcmcia - Hardware has PCMCIA or CompactFlash sockets
                </p></li><li><p>
                    screen - Hardware has a screen
                </p></li><li><p>
                    serial - Hardware has serial support (usually RS232)
                </p></li><li><p>
                    touchscreen - Hardware has a touchscreen
                </p></li><li><p>
                    usbgadget - Hardware is USB gadget device capable
                </p></li><li><p>
                    usbhost - Hardware is USB Host capable
                </p></li><li><p>
                    wifi - Hardware has integrated WiFi
                </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-features-image"></a>3.�Reference: Images</h2></div></div></div><p>
            The contents of images generated by Poky can be controlled by the <a href="#var-IMAGE_FEATURES"><em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em></a>
        variable in local.conf. Through this you can add several different
        predefined packages such as development utilities or packages with debug
        information needed to investigate application problems or profile applications.
        </p><p>
            Current list of <a href="#var-IMAGE_FEATURES"><em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em></a> contains:
        </p><div class="itemizedlist"><ul type="disc"><li><p>
                    apps-console-core - Core console applications such as ssh daemon, 
                    avahi daemon, portmap (for mounting NFS shares)
                </p></li><li><p>
                    x11-base - X11 server + minimal desktop
                </p></li><li><p>
                    x11-sato - OpenedHand Sato environment
                </p></li><li><p>
                    apps-x11-core - Core X11 applications such as an X Terminal, file manager, file editor
                </p></li><li><p>
                    apps-x11-games - A set of X11 games
                </p></li><li><p>
                    apps-x11-pimlico - OpenedHand Pimlico application suite
                </p></li><li><p>
                    tools-sdk - A full SDK which runs on device
                </p></li><li><p>
                    tools-debug - Debugging tools such as strace and gdb
                </p></li><li><p>
                    tools-profile - Profiling tools such as oprofile, exmap and LTTng
                </p></li><li><p>
                    tools-testapps - Device testing tools (e.g. touchscreen debugging)
                </p></li><li><p>
                    nfs-server - NFS server (exports / over NFS to everybody)
                </p></li><li><p>
                    dev-pkgs - Development packages (headers and extra library links) for all packages
                    installed in a given image
                </p></li><li><p>
                    dbg-pkgs - Debug packages for all packages installed in a given image
                </p></li></ul></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-variables-glos"></a>Appendix�6.�Reference: Variables Glossary</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></div><p>
    This section lists common variables used in Poky and gives an overview
    of their function and contents.
</p><div class="glossary"><div class="titlepage"><div><div><h2 class="title"><a name="ref-variables-glossary"></a>Glossary</h2></div></div></div><p>
       <a href="#var-glossary-a" title="A">A</a> 
       <a href="#var-glossary-b" title="B">B</a> 
       <a href="#var-glossary-c" title="C">C</a> 
       <a href="#var-glossary-d" title="D">D</a> 
       <a href="#var-glossary-e" title="E">E</a> 
       <a href="#var-glossary-f" title="F">F</a> 

       <a href="#var-glossary-h" title="H">H</a> 
       <a href="#var-glossary-i" title="I">I</a> 

       <a href="#var-glossary-k" title="K">K</a>
       <a href="#var-glossary-l" title="L">L</a> 
       <a href="#var-glossary-m" title="M">M</a> 


       <a href="#var-glossary-p" title="P">P</a> 

       <a href="#var-glossary-r" title="R">R</a> 
       <a href="#var-glossary-s" title="S">S</a> 
       <a href="#var-glossary-t" title="T">T</a> 


       <a href="#var-glossary-w" title="W">W</a> 



    </p><div class="glossdiv"><h3 class="title">A</h3><dl><dt><a name="var-AUTHOR"></a>AUTHOR</dt><dd><p>E-mail address to contact original author(s) - to
                send patches, forward bugs...</p></dd><dt><a name="var-AUTOREV"></a>AUTOREV</dt><dd><p>Use current (newest) source revision - used with
                    <em class="glossterm"><a href="#var-SRCREV" title="SRCREV">SRCREV</a></em>
                    variable.</p></dd></dl></div><div class="glossdiv"><h3 class="title">B</h3><dl><dt><a name="var-BB_NUMBER_THREADS"></a>BB_NUMBER_THREADS</dt><dd><p>Number of BitBake threads</p></dd><dt><a name="var-BBFILES"></a>BBFILES</dt><dd><p>List of recipes used by BitBake to build software</p></dd><dt><a name="var-BBINCLUDELOGS"></a>BBINCLUDELOGS</dt><dd><p>Variable which controls how BitBake displays logs on build failure.</p></dd></dl></div><div class="glossdiv"><h3 class="title">C</h3><dl><dt><a name="var-CFLAGS"></a>CFLAGS</dt><dd><p>
                    Flags passed to C compiler for the target system. Evaluates to the same 
                    as <a href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a>.
                </p></dd><dt><a name="var-COMPATIBLE_MACHINES"></a>COMPATIBLE_MACHINES</dt><dd><p>A regular expression which evalutates to match the machines the recipe 
                works with. It stops recipes being run on machines they're incompatible with 
                which is partciuarly useful with kernels. It also helps to to increase parsing 
                speed as if its found the current machine is not compatible, further parsing 
                of the recipe is skipped.</p></dd><dt><a name="var-CONFIG_SITE"></a>CONFIG_SITE</dt><dd><p>
                    Contains a list of files which containing autoconf test results relevant 
                    to the current build. This variable is used by the autotools utilities 
                    when running configure.
                </p></dd><dt><a name="var-CVS_TARBALL_STASH"></a>CVS_TARBALL_STASH</dt><dd><p>Location to search for
                pre-generated tarballs when fetching from remote SCM
                repositories (CVS/SVN/GIT)</p></dd></dl></div><div class="glossdiv"><h3 class="title">D</h3><dl><dt><a name="var-D"></a>D</dt><dd><p>Destination directory</p></dd><dt><a name="var-DEBUG_BUILD"></a>DEBUG_BUILD</dt><dd><p>
                    Build packages with debugging information. This influences the value 
                    <a href="#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION</a> 
                    takes.
                </p></dd><dt><a name="var-DEBUG_OPTIMIZATION"></a>DEBUG_OPTIMIZATION</dt><dd><p>
                    The options to pass in <a href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a>
                    and <a href="#var-CFLAGS" title="CFLAGS">CFLAGS</a> when compiling a system for debugging.
                    This defaults to "-O -fno-omit-frame-pointer -g".
                </p></dd><dt><a name="var-DEFAULT_PREFERENCE"></a>DEFAULT_PREFERENCE</dt><dd><p>Priority of recipe</p></dd><dt><a name="var-DEPENDS"></a>DEPENDS</dt><dd><p>
                    A list of build time dependencies for a given recipe. These indicate 
                    recipes that must have staged before this recipe can configure.
                </p></dd><dt><a name="var-DESCRIPTION"></a>DESCRIPTION</dt><dd><p>Package description used by package
                    managers</p></dd><dt><a name="var-DESTDIR"></a>DESTDIR</dt><dd><p>Destination directory</p></dd><dt><a name="var-DISTRO"></a>DISTRO</dt><dd><p>Short name of distribution</p></dd><dt><a name="var-DISTRO_EXTRA_RDEPENDS"></a>DISTRO_EXTRA_RDEPENDS</dt><dd><p>List of packages required by distribution.</p></dd><dt><a name="var-DISTRO_EXTRA_RRECOMMENDS"></a>DISTRO_EXTRA_RRECOMMENDS</dt><dd><p>List of packages which extend usability of
                    image. Those packages will be automatically
                    installed but can be removed by user.</p></dd><dt><a name="var-DISTRO_FEATURES"></a>DISTRO_FEATURES</dt><dd><p>Features of the distribution.</p></dd><dt><a name="var-DISTRO_NAME"></a>DISTRO_NAME</dt><dd><p>Long name of distribution</p></dd><dt><a name="var-DISTRO_VERSION"></a>DISTRO_VERSION</dt><dd><p>Version of distribution</p></dd><dt><a name="var-DL_DIR"></a>DL_DIR</dt><dd><p>Directory where all fetched sources will be stored</p></dd></dl></div><div class="glossdiv"><h3 class="title">E</h3><dl><dt><a name="var-ENABLE_BINARY_LOCALE_GENERATION"></a>ENABLE_BINARY_LOCALE_GENERATION</dt><dd><p>Variable which control which locales for glibc are
                to be generated during build (useful if target device
                has 64M RAM or less)</p></dd><dt><a name="var-EXTRA_OECONF"></a>EXTRA_OECONF</dt><dd><p>Additional 'configure' script options</p></dd><dt><a name="var-EXTRA_OEMAKE"></a>EXTRA_OEMAKE</dt><dd><p>Additional GNU make options</p></dd></dl></div><div class="glossdiv"><h3 class="title">F</h3><dl><dt><a name="var-FILES"></a>FILES</dt><dd><p>list of directories/files which will be placed
                    in packages</p></dd><dt><a name="var-FULL_OPTIMIZATION"></a>FULL_OPTIMIZATION</dt><dd><p>
                    The options to pass in <a href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a>
                    and <a href="#var-CFLAGS" title="CFLAGS">CFLAGS</a> when compiling an optimised system.
                    This defaults to "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
                </p></dd></dl></div><div class="glossdiv"><h3 class="title">H</h3><dl><dt><a name="var-HOMEPAGE"></a>HOMEPAGE</dt><dd><p>Website where more info about package can be found</p></dd></dl></div><div class="glossdiv"><h3 class="title">I</h3><dl><dt><a name="var-IMAGE_FEATURES"></a>IMAGE_FEATURES</dt><dd><p><a href="#ref-features-image" title="3.�Reference: Images">List of
                features</a> present in resulting images</p></dd><dt><a name="var-IMAGE_FSTYPES"></a>IMAGE_FSTYPES</dt><dd><p>Formats of rootfs images which we want to have
                    created</p></dd><dt><a name="var-IMAGE_INSTALL"></a>IMAGE_INSTALL</dt><dd><p>List of packages used to build image</p></dd><dt><a name="var-INHIBIT_PACKAGE_STRIP"></a>INHIBIT_PACKAGE_STRIP</dt><dd><p>
                    This variable causes the build to not strip binaries in
                    resulting packages.
                </p></dd><dt><a name="var-INHERIT"></a>INHERIT</dt><dd><p>
                    This variable causes the named class to be inherited at 
                    this point during parsing. Its only valid in configuration 
                    files.
                </p></dd><dt><a name="var-INITSCRIPT_PACKAGES"></a>INITSCRIPT_PACKAGES</dt><dd><p>
                    Scope: Used in recipes when using update-rc.d.bbclass. Optional, defaults to PN.
                </p><p>
                    A list of the packages which contain initscripts. If multiple 
                    packages are specified you need to append the package name 
                    to the other INITSCRIPT_* as an override.
                </p></dd><dt><a name="var-INITSCRIPT_NAME"></a>INITSCRIPT_NAME</dt><dd><p>
                    Scope: Used in recipes when using update-rc.d.bbclass. Mandatory.
                </p><p>
                    The filename of the initscript (as installed to ${etcdir}/init.d).
                </p></dd><dt><a name="var-INITSCRIPT_PARAMS"></a>INITSCRIPT_PARAMS</dt><dd><p>
                    Scope: Used in recipes when using update-rc.d.bbclass. Mandatory.
                </p><p>
                    Specifies the options to pass to update-rc.d. An example is
                     "start 99 5 2 . stop 20 0 1 6 ." which gives the script a 
                    runlevel of 99, starts the script in initlevels 2 and 5 and 
                     stops it in levels 0, 1 and 6. 
                </p></dd></dl></div><div class="glossdiv"><h3 class="title">K</h3><dl><dt><a name="var-KERNEL_IMAGETYPE"></a>KERNEL_IMAGETYPE</dt><dd><p>The type of kernel to build for a device, usually set by the 
                machine configuration files and defaults to "zImage". This is used 
                when building the kernel and is passed to "make" as the target to 
                build.</p></dd></dl></div><div class="glossdiv"><h3 class="title">L</h3><dl><dt><a name="var-LICENSE"></a>LICENSE</dt><dd><p>List of package source licenses.</p></dd></dl></div><div class="glossdiv"><h3 class="title">M</h3><dl><dt><a name="var-MACHINE"></a>MACHINE</dt><dd><p>Target device</p></dd><dt><a name="var-MACHINE_ESSENTIAL_RDEPENDS"></a>MACHINE_ESSENTIAL_RDEPENDS</dt><dd><p>List of packages required to boot device</p></dd><dt><a name="var-MACHINE_ESSENTIAL_RRECOMMENDS"></a>MACHINE_ESSENTIAL_RRECOOMENDS</dt><dd><p>List of packages required to boot device (usually
                    additional kernel modules)</p></dd><dt><a name="var-MACHINE_EXTRA_RDEPENDS"></a>MACHINE_EXTRA_RDEPENDS</dt><dd><p>List of packages required to use device</p></dd><dt><a name="var-MACHINE_EXTRA_RRECOMMENDS"></a>MACHINE_EXTRA_RRECOMMNEDS</dt><dd><p>List of packages useful to use device (for example
                    additional kernel modules)</p></dd><dt><a name="var-MACHINE_FEATURES"></a>MACHINE_FEATURES</dt><dd><p>List of device features - defined in <a href="#ref-features-machine" title="2.�Machine">machine
                    features section</a></p></dd><dt><a name="var-MAINTAINER"></a>MAINTAINER</dt><dd><p>E-mail of distribution maintainer</p></dd></dl></div><div class="glossdiv"><h3 class="title">P</h3><dl><dt><a name="var-PACKAGE_ARCH"></a>PACKAGE_ARCH</dt><dd><p>Architecture of resulting package</p></dd><dt><a name="var-PACKAGE_CLASSES"></a>PACKAGE_CLASSES</dt><dd><p>List of resulting packages formats</p></dd><dt><a name="var-PACKAGE_EXTRA_ARCHS"></a>PACKAGE_EXTRA_ARCHS</dt><dd><p>List of architectures compatible with device
                    CPU. Usable when build is done for few different
                    devices with misc processors (like XScale and
                    ARM926-EJS)</p></dd><dt><a name="var-PACKAGES"></a>PACKAGES</dt><dd><p>List of packages to be created from recipe.
                    The default value is "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev"</p></dd><dt><a name="var-PN"></a>PN</dt><dd><p>Name of package.
                    </p></dd><dt><a name="var-PR"></a>PR</dt><dd><p>Revision of package.
                    </p></dd><dt><a name="var-PV"></a>PV</dt><dd><p>Version of package.
                    The default value is "1.0"</p></dd><dt><a name="var-PE"></a>PE</dt><dd><p>
                    Epoch of the package. The default value is "1". The field is used 
                    to make upgrades possible when the versioning scheme changes in 
                    some backwards incompatible way.
                </p></dd><dt><a name="var-PREFERRED_PROVIDER"></a>PREFERRED_PROVIDER</dt><dd><p>If multiple recipes provide an item, this variable
                    determines which one should be given preference. It 
                    should be set to the "$PN" of the recipe to be preferred.</p></dd><dt><a name="var-PREFERRED_VERSION"></a>PREFERRED_VERSION</dt><dd><p>
                    If there are multiple versions of recipe available, this
                    variable determines which one should be given preference. It
                    should be set to the "$PV" of the recipe to be preferred.
                </p></dd><dt><a name="var-POKYLIBC"></a>POKYLIBC</dt><dd><p>Libc implementation selector - glibc or uclibc can be selected.</p></dd><dt><a name="var-POKYMODE"></a>POKYMODE</dt><dd><p>Toolchain selector. It can be external toolchain
                built from Poky or few supported combinations of
                upstream GCC or CodeSourcery Labs toolchain.</p></dd></dl></div><div class="glossdiv"><h3 class="title">R</h3><dl><dt><a name="var-RCONFLICTS"></a>RCONFLICTS</dt><dd><p>List of packages which which conflict with this
                    one. Package will not be installed if they will not
                    be removed first.</p></dd><dt><a name="var-RDEPENDS"></a>RDEPENDS</dt><dd><p>
                    A list of run-time dependencies for a package. These packages 
                    need to be installed alongside the package it applies to so 
                    the package will run correctly, an example is a perl script
                    which would rdepend on perl. Since this variable applies to 
                    output packages there would usually be an override attached 
                    to this variable like RDEPENDS_${PN}-dev. Names in this field 
                    should be as they are in <a href="#var-PACKAGES" title="PACKAGES">PACKAGES
                    </a> namespave before any renaming of the output package
                    by classes like debian.bbclass.
                </p></dd><dt><a name="var-ROOT_FLASH_SIZE"></a>ROOT_FLASH_SIZE</dt><dd><p>Size of rootfs in megabytes</p></dd><dt><a name="var-RRECOMMENDS"></a>RRECOMMENDS</dt><dd><p>List of packages which extend usability of
                    package. Those packages will be automatically
                    installed but can be removed by user.</p></dd><dt><a name="var-RREPLACES"></a>RREPLACES</dt><dd><p>List of packages which are replaced with this
                    one.</p></dd></dl></div><div class="glossdiv"><h3 class="title">S</h3><dl><dt><a name="var-S"></a>S</dt><dd><p>
                    Path to unpacked sources (by default:
                    "${<a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a>}/${<a href="#var-PN" title="PN">PN</a>}-${<a href="#var-PV" title="PV">PV</a>}")
                </p></dd><dt><a name="var-SECTION"></a>SECTION</dt><dd><p>Section where package should be put - used
                    by package managers</p></dd><dt><a name="var-SELECTED_OPTIMIZATION"></a>SELECTED_OPTIMIZATION</dt><dd><p>
                    The variable takes the value of <a href="#var-FULL_OPTIMIZATION" title="FULL_OPTIMIZATION">FULL_OPTIMIZATION</a>
                    unless <a href="#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a> = "1" in which case 
                    <a href="#var-DEBUG_OPTIMIZATION" title="DEBUG_OPTIMIZATION">DEBUG_OPTIMIZATION</a> is used.
                </p></dd><dt><a name="var-SERIAL_CONSOLE"></a>SERIAL_CONSOLE</dt><dd><p>Speed and device for serial port used to attach
                    serial console. This is given to kernel as "console"
                    param and after boot getty is started on that port
                    so remote login is possible.</p></dd><dt><a name="var-SHELLCMDS"></a>SHELLCMDS</dt><dd><p>
                    A list of commands to run within the a shell, used by <em class="glossterm"><a href="#var-TERMCMDRUN" title="TERMCMDRUN">TERMCMDRUN</a></em>. It defaults to  
                    <em class="glossterm"><a href="#var-SHELLRCCMD" title="SHELLRCCMD">SHELLRCCMD</a></em>.
                </p></dd><dt><a name="var-SHELLRCCMD"></a>SHELLRCCMD</dt><dd><p>
                    How to launch a shell, defaults to bash.
                </p></dd><dt><a name="var-SITEINFO_ENDIANESS"></a>SITEINFO_ENDIANESS</dt><dd><p>
                    Contains "le" for little-endian or "be" for big-endian depending 
                    on the endian byte order of the target system.
                </p></dd><dt><a name="var-SITEINFO_BITS"></a>SITEINFO_BITS</dt><dd><p>
                    Contains "32" or "64" depending on the number of bits for the 
                    CPU of the target system.
                </p></dd><dt><a name="var-SRC_URI"></a>SRC_URI</dt><dd><p>List of source files (local or remote ones)</p></dd><dt><a name="var-SRC_URI_OVERRIDES_PACKAGE_ARCH"></a>SRC_URI_OVERRIDES_PACKAGE_ARCH</dt><dd><p>
                    By default there is code which automatically detects whether 
                    <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em>  
                    contains files which are machine specific and if this is the case it
                    automatically changes 
                    <em class="glossterm"><a href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></em>. 
                    Setting this variable to "0" disables that behaviour.
                </p></dd><dt><a name="var-SRCDATE"></a>SRCDATE</dt><dd><p>
                    Date of source code used to build package (if it was fetched
                    from SCM).
                </p></dd><dt><a name="var-SRCREV"></a>SRCREV</dt><dd><p>
                    Revision of source code used to build package (Subversion,
                    GIT, Bazaar only).
                </p></dd><dt><a name="var-STAGING_KERNEL_DIR"></a>STAGING_KERNEL_DIR</dt><dd><p>
                    Directory with kernel headers required to build out-of-tree
                    modules.
                </p></dd><dt><a name="var-STAMPS"></a>STAMPS</dt><dd><p>
                    Directory (usually TMPDIR/stamps) with timestamps of
                    executed tasks.
                </p></dd></dl></div><div class="glossdiv"><h3 class="title">T</h3><dl><dt><a name="var-TARGET_ARCH"></a>TARGET_ARCH</dt><dd><p>The architecture of the device we're building for. 
                A number of values are possible but Poky primarily supports
                "arm" and "i586".</p></dd><dt><a name="var-TARGET_CFLAGS"></a>TARGET_CFLAGS</dt><dd><p>
                    Flags passed to C compiler for the target system. Evaluates to the same 
                    as <a href="#var-CFLAGS" title="CFLAGS">CFLAGS</a>.
                </p></dd><dt><a name="var-TARGET_FPU"></a>TARGET_FPU</dt><dd><p>Method of handling FPU code. For FPU-less targets
                (most of ARM cpus) it has to be set to "soft" otherwise
                kernel emulation will get used which will result in
                performance penalty.</p></dd><dt><a name="var-TARGET_OS"></a>TARGET_OS</dt><dd><p>Type of target operating system. Can be "linux"
                for glibc based system, "linux-uclibc" for uClibc. For
                ARM/EABI targets there are also "linux-gnueabi" and
                "linux-uclibc-gnueabi" values possible.</p></dd><dt><a name="var-TERMCMD"></a>TERMCMD</dt><dd><p>
                    This command is used by bitbake to lauch a terminal window with a 
                    shell. The shell is unspecified so the user's default shell is used. 
                    By default it is set to <span><strong class="command">gnome-terminal</strong></span> but it can 
                    be any X11 terminal application or terminal multiplexers like screen.
                </p></dd><dt><a name="var-TERMCMDRUN"></a>TERMCMDRUN</dt><dd><p>
                    This command is similar to <em class="glossterm"><a href="#var-TERMCMD" title="TERMCMD">TERMCMD</a></em> however instead of the users shell it runs the command specified by the <em class="glossterm"><a href="#var-SHELLCMDS" title="SHELLCMDS">SHELLCMDS</a></em> variable.
                </p></dd></dl></div><div class="glossdiv"><h3 class="title">W</h3><dl><dt><a name="var-WORKDIR"></a>WORKDIR</dt><dd><p>Path to directory in tmp/work/ where package
                    will be built.</p></dd></dl></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-varlocality"></a>Appendix�7.�Reference: Variable Locality (Distro, Machine, Recipe etc.)</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">1. Distro Configuration</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">2. Machine Configuration</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">3. Local Configuration (local.conf)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-required">4. Recipe Variables - Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">5. Recipe Variables - Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">6. Recipe Variables - Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">7. Recipe Variables - Extra Build Information</a></span></dt></dl></div><p>
        Whilst most variables can be used in almost any context (.conf, .bbclass, 
        .inc or .bb file), variables are often associated with a particular 
        locality/context. This section describes some common associations.
    </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-config-distro"></a>1.�Distro Configuration</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="#var-DISTRO"><em class="glossterm"><a href="#var-DISTRO" title="DISTRO">DISTRO</a></em></a></p></li><li><p><a href="#var-DISTRO_NAME"><em class="glossterm"><a href="#var-DISTRO_NAME" title="DISTRO_NAME">DISTRO_NAME</a></em></a></p></li><li><p><a href="#var-DISTRO_VERSION"><em class="glossterm"><a href="#var-DISTRO_VERSION" title="DISTRO_VERSION">DISTRO_VERSION</a></em></a></p></li><li><p><a href="#var-MAINTAINER"><em class="glossterm"><a href="#var-MAINTAINER" title="MAINTAINER">MAINTAINER</a></em></a></p></li><li><p><a href="#var-PACKAGE_CLASSES"><em class="glossterm"><a href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></em></a></p></li><li><p><a href="#var-TARGET_OS"><em class="glossterm"><a href="#var-TARGET_OS" title="TARGET_OS">TARGET_OS</a></em></a></p></li><li><p><a href="#var-TARGET_FPU"><em class="glossterm"><a href="#var-TARGET_FPU" title="TARGET_FPU">TARGET_FPU</a></em></a></p></li><li><p><a href="#var-POKYMODE"><em class="glossterm"><a href="#var-POKYMODE" title="POKYMODE">POKYMODE</a></em></a></p></li><li><p><a href="#var-POKYLIBC"><em class="glossterm"><a href="#var-POKYLIBC" title="POKYLIBC">POKYLIBC</a></em></a></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-config-machine"></a>2.�Machine Configuration</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="#var-TARGET_ARCH"><em class="glossterm"><a href="#var-TARGET_ARCH" title="TARGET_ARCH">TARGET_ARCH</a></em></a></p></li><li><p><a href="#var-SERIAL_CONSOLE"><em class="glossterm"><a href="#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE</a></em></a></p></li><li><p><a href="#var-PACKAGE_EXTRA_ARCHS"><em class="glossterm"><a href="#var-PACKAGE_EXTRA_ARCHS" title="PACKAGE_EXTRA_ARCHS">PACKAGE_EXTRA_ARCHS</a></em></a></p></li><li><p><a href="#var-IMAGE_FSTYPES"><em class="glossterm"><a href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></em></a></p></li><li><p><a href="#var-ROOT_FLASH_SIZE"><em class="glossterm"><a href="#var-ROOT_FLASH_SIZE" title="ROOT_FLASH_SIZE">ROOT_FLASH_SIZE</a></em></a></p></li><li><p><a href="#var-MACHINE_FEATURES"><em class="glossterm"><a href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></em></a></p></li><li><p><a href="#var-MACHINE_EXTRA_RDEPENDS"><em class="glossterm"><a href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS</a></em></a></p></li><li><p><a href="#var-MACHINE_EXTRA_RRECOMMENDS"><em class="glossterm"><a href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMNEDS">MACHINE_EXTRA_RRECOMMENDS</a></em></a></p></li><li><p><a href="#var-MACHINE_ESSENTIAL_RDEPENDS"><em class="glossterm"><a href="#var-MACHINE_ESSENTIAL_RDEPENDS" title="MACHINE_ESSENTIAL_RDEPENDS">MACHINE_ESSENTIAL_RDEPENDS</a></em></a></p></li><li><p><a href="#var-MACHINE_ESSENTIAL_RRECOMMENDS"><em class="glossterm"><a href="#var-MACHINE_ESSENTIAL_RRECOMMENDS" title="MACHINE_ESSENTIAL_RRECOOMENDS">MACHINE_ESSENTIAL_RRECOMMENDS</a></em></a></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-config-local"></a>3.�Local Configuration (local.conf)</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="#var-DISTRO"><em class="glossterm"><a href="#var-DISTRO" title="DISTRO">DISTRO</a></em></a></p></li><li><p><a href="#var-MACHINE"><em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a></em></a></p></li><li><p><a href="#var-DL_DIR"><em class="glossterm"><a href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></em></a></p></li><li><p><a href="#var-BBFILES"><em class="glossterm"><a href="#var-BBFILES" title="BBFILES">BBFILES</a></em></a></p></li><li><p><a href="#var-IMAGE_FEATURES"><em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em></a></p></li><li><p><a href="#var-PACKAGE_CLASSES"><em class="glossterm"><a href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></em></a></p></li><li><p><a href="#var-BB_NUMBER_THREADS"><em class="glossterm"><a href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a></em></a></p></li><li><p><a href="#var-BBINCLUDELOGS"><em class="glossterm"><a href="#var-BBINCLUDELOGS" title="BBINCLUDELOGS">BBINCLUDELOGS</a></em></a></p></li><li><p><a href="#var-CVS_TARBALL_STASH"><em class="glossterm"><a href="#var-CVS_TARBALL_STASH" title="CVS_TARBALL_STASH">CVS_TARBALL_STASH</a></em></a></p></li><li><p><a href="#var-ENABLE_BINARY_LOCALE_GENERATION"><em class="glossterm"><a href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">ENABLE_BINARY_LOCALE_GENERATION</a></em></a></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-recipe-required"></a>4.�Recipe Variables - Required</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><em class="glossterm"><a href="#var-DESCRIPTION" title="DESCRIPTION">DESCRIPTION</a></em></p></li><li><p><em class="glossterm"><a href="#var-LICENSE" title="LICENSE">LICENSE</a></em></p></li><li><p><em class="glossterm"><a href="#var-SECTION" title="SECTION">SECTION</a></em></p></li><li><p><em class="glossterm"><a href="#var-HOMEPAGE" title="HOMEPAGE">HOMEPAGE</a></em></p></li><li><p><em class="glossterm"><a href="#var-AUTHOR" title="AUTHOR">AUTHOR</a></em></p></li><li><p><em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-recipe-dependencies"></a>5.�Recipe Variables - Dependencies</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><em class="glossterm"><a href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></em></p></li><li><p><em class="glossterm"><a href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></em></p></li><li><p><em class="glossterm"><a href="#var-RRECOMMENDS" title="RRECOMMENDS">RRECOMMENDS</a></em></p></li><li><p><em class="glossterm"><a href="#var-RCONFLICTS" title="RCONFLICTS">RCONFLICTS</a></em></p></li><li><p><em class="glossterm"><a href="#var-RREPLACES" title="RREPLACES">RREPLACES</a></em></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-recipe-paths"></a>6.�Recipe Variables - Paths</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em></p></li><li><p><em class="glossterm"><a href="#var-S" title="S">S</a></em></p></li><li><p><em class="glossterm"><a href="#var-FILES" title="FILES">FILES</a></em></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-recipe-build"></a>7.�Recipe Variables - Extra Build Information</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><em class="glossterm"><a href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></em></p></li><li><p><em class="glossterm"><a href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></em></p></li><li><p><em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></em></p></li><li><p><em class="glossterm"><a href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></em></p></li></ul></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="faq"></a>Appendix�8.�FAQ</h2></div></div></div><div class="qandaset"><dl><dt>8.1. <a href="#id1089074">
                How does Poky differ from OpenEmbedded?
            </a></dt><dt>8.2. <a href="#id1089095">
                How can you claim Poky is stable?
            </a></dt><dt>8.3. <a href="#id1089122">
                How do I get support for my board added to Poky?
            </a></dt><dt>8.4. <a href="#id1089143">
                Are there any products running poky ?
            </a></dt><dt>8.5. <a href="#id1089157">
                What is the Poky output ?
            </a></dt><dt>8.6. <a href="#id1089167">
                How do I add my package to Poky?
            </a></dt><dt>8.7. <a href="#id1089176">
                Do I have to reflash my entire board with a new poky image when recompiling a package?
            </a></dt><dt>8.8. <a href="#id1089187">
                What is GNOME Mobile? What's the difference between GNOME Mobile and GNOME?
            </a></dt><dt>8.9. <a href="#id1089203">
                How do I make Poky work in RHEL/CentOS?
            </a></dt><dt>8.10. <a href="#id1089270">
                I see lots of 404 responses for files on http://folks.o-hand.com/~richard/poky/sources/*. Is something wrong?
            </a></dt><dt>8.11. <a href="#id1089285">
                I have a machine specific data in a package for one machine only but the package is 
                 being marked as machine specific in all cases, how do I stop it?
            </a></dt></dl><table border="0" summary="Q and A Set"><col align="left" width="1%"><tbody><tr class="question"><td align="left" valign="top"><a name="id1089074"></a><a name="id1089075"></a><b>8.1.</b></td><td align="left" valign="top"><p>
                How does Poky differ from <a href="http://www.openembedded.org/" target="_top">OpenEmbedded</a>?
            </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
                Poky is a derivative of <a href="http://www.openembedded.org/" target="_top">OpenEmbedded</a>, a stable, 
                smaller subset focused on the GNOME Mobile environment. Development
                in Poky is closely tied to OpenEmbedded with features being merged
                regularly between the two for mutual benefit.
            </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089095"></a><a name="id1089096"></a><b>8.2.</b></td><td align="left" valign="top"><p>
                How can you claim Poky is stable?
            </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
                There are three areas that help with stability;

            </p><div class="itemizedlist"><ul type="disc"><li><p>
                        We keep Poky small and focused - around 650 packages compared to over 5000 for full OE
                    </p></li><li><p>
                        We only support hardware that we have access to for testing
                    </p></li><li><p>
                        We have a Buildbot which provides continuous build and integration tests
                    </p></li></ul></div><p>
            </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089122"></a><a name="id1089123"></a><b>8.3.</b></td><td align="left" valign="top"><p>
                How do I get support for my board added to Poky?
            </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
                There are two main ways to get a board supported in Poky;
            </p><div class="itemizedlist"><ul type="disc"><li><p>    
                    Send us the board if we don't have it yet
                    </p></li><li><p>
                    Send us bitbake recipes if you have them (see the Poky handbook to find out how to create recipes)
                    </p></li></ul></div><p>
                    Usually if it's not a completely exotic board then adding support in Poky should be fairly straightforward.
            </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089143"></a><a name="id1089144"></a><b>8.4.</b></td><td align="left" valign="top"><p>
                Are there any products running poky ?
            </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
                The <a href="http://vernier.com/labquest/" target="_top">Vernier Labquest</a> is using Poky (for more about the Labquest see the case study at OpenedHand). There are a number of pre-production devices using Poky and we will announce those as soon as they are released.
            </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089157"></a><a name="id1089158"></a><b>8.5.</b></td><td align="left" valign="top"><p>
                What is the Poky output ?
            </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
                The output of a Poky build will depend on how it was started, as the same set of recipes can be used to output various formats. Usually the output is a flashable image ready for the target device.
            </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089167"></a><a name="id1089168"></a><b>8.6.</b></td><td align="left" valign="top"><p>
                How do I add my package to Poky?
            </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
                To add a package you need to create a bitbake recipe - see the Poky handbook to find out how to create a recipe.
            </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089176"></a><a name="id1089177"></a><b>8.7.</b></td><td align="left" valign="top"><p>
                Do I have to reflash my entire board with a new poky image when recompiling a package?
            </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
                Poky can build packages in various formats, ipkg, Debian package, or RPM. The package can then be upgraded using the package tools on the device, much like on a desktop distribution like Ubuntu or Fedora.
            </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089187"></a><a name="id1089188"></a><b>8.8.</b></td><td align="left" valign="top"><p>
                What is GNOME Mobile? What's the difference between GNOME Mobile and GNOME?
            </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
                <a href="http://www.gnome.org/mobile/" target="_top">GNOME Mobile</a> is a subset of the GNOME platform targeted at mobile and embedded devices. The the main difference between GNOME Mobile and standard GNOME is that desktop-orientated libraries have been removed, along with deprecated libraries, creating a much smaller footprint. 
            </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089203"></a><a name="id1089204"></a><b>8.9.</b></td><td align="left" valign="top"><p>
                How do I make Poky work in RHEL/CentOS?
            </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
                To get Poky working under RHEL/CentOS 5.1 you need to first install some required packages. The standard CentOS packages needed are:
                </p><div class="itemizedlist"><ul type="disc"><li><p>
                            "Development tools" (selected during installation)
                        </p></li><li><p>
                            texi2html
                        </p></li><li><p>
                            compat-gcc-34
                        </p></li></ul></div><p>
            </p><p>
                On top of those the following external packages are needed:
                </p><div class="itemizedlist"><ul type="disc"><li><p>
                            python-sqlite2 from <a href="http://dag.wieers.com/rpm/packages/python-sqlite2/" target="_top">DAG
                                repository</a>
                        </p></li><li><p>
                            help2man from <a href="http://centos.karan.org/el5/extras/testing/i386/RPMS/help2man-1.33.1-2.noarch.rpm" target="_top">Karan
                                repository</a>
                        </p></li></ul></div><p>
            </p><p>
                Once these packages are installed Poky will be able to build standard images however there 
                may be a problem with QEMU segfaulting. You can either disable the generation of binary 
                locales by setting <em class="glossterm"><a href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">ENABLE_BINARY_LOCALE_GENERATION</a>
                </em> to "0" or remove the linux-2.6-execshield.patch from the kernel and rebuild 
                it since its that patch which causes the problems with QEMU.
            </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089270"></a><a name="id1089271"></a><b>8.10.</b></td><td align="left" valign="top"><p>
                I see lots of 404 responses for files on http://folks.o-hand.com/~richard/poky/sources/*. Is something wrong?
            </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
                Nothing is wrong, Poky will check any configured source mirrors before downloading 
                from the upstream sources. It does this searching for both source archives and 
                pre-checked out versions of SCM managed software. This is so in large installations, 
                it can reduce load on the SCM servers themselves. The address above is one of the 
                default mirrors configured into standard Poky so if an upstream source disappears, 
                we can place sources there so builds continue to work.
            </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089285"></a><a name="id1089286"></a><b>8.11.</b></td><td align="left" valign="top"><p>
                I have a machine specific data in a package for one machine only but the package is 
                 being marked as machine specific in all cases, how do I stop it?
            </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
                Set <em class="glossterm"><a href="#var-SRC_URI_OVERRIDES_PACKAGE_ARCH" title="SRC_URI_OVERRIDES_PACKAGE_ARCH">SRC_URI_OVERRIDES_PACKAGE_ARCH</a>
                </em> = "0" in the .bb file but make sure the package is manually marked as 
                machine specific in the case that needs it. The code which handles <em class="glossterm"><a href="#var-SRC_URI_OVERRIDES_PACKAGE_ARCH" title="SRC_URI_OVERRIDES_PACKAGE_ARCH">SRC_URI_OVERRIDES_PACKAGE_ARCH</a></em>
		is in base.bbclass.
            </p></td></tr></tbody></table></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="resources"></a>Appendix�9.�Contributing to Poky</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#resources-intro">1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">2. Bugtracker</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">3. Mailing list</a></span></dt><dt><span class="section"><a href="#resources-irc">4. IRC</a></span></dt><dt><span class="section"><a href="#resources-links">5. Links</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-intro"></a>1.�Introduction</h2></div></div></div><p>
        We're happy for people to experiment with Poky and there are a number of places to
        find help if you run into difficulties or find bugs. To find out how to download
        source code see the <a href="#intro-getit" title="5.�Obtaining Poky">Obtaining Poky</a> section of
        the Introduction.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-bugtracker"></a>2.�Bugtracker</h2></div></div></div><p>
        Problems with Poky should be reported in the 
        <a href="http://bugzilla.o-hand.com/" target="_top">bug tracker</a>.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-mailinglist"></a>3.�Mailing list</h2></div></div></div><p>
        To subscribe to the mailing list send mail to:
    </p><p>
        </p><pre class="literallayout">
poky+subscribe &lt;at&gt; openedhand &lt;dot&gt; com
        </pre><p>
    </p><p>
        Then follow the simple instructions in subsequent reply. Archives are
        available <a href="http://lists.o-hand.com/poky/" target="_top">here</a>.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-irc"></a>4.�IRC</h2></div></div></div><p> 
        Join #poky on freenode.
    </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-links"></a>5.�Links</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
            <a href="http://pokylinux.org" target="_top">The Poky website</a> 
        </p></li><li><p>
            <a href="http://www.openedhand.com/" target="_top">OpenedHand</a> - The
            company behind Poky.
        </p></li><li><p>
            <a href="http://www.openembedded.org/" target="_top">OpenEmbedded</a>
            - The upstream generic embedded distribution Poky derives
            from (and contributes to).
        </p></li><li><p>
            <a href="http://developer.berlios.de/projects/bitbake/" target="_top">Bitbake</a>
            - The tool used to process Poky metadata.
        </p></li><li><p>
            <a href="http://bitbake.berlios.de/manual/" target="_top">Bitbake User
                Manual</a>
        </p></li><li><p>
            <a href="http://pimlico-project.org/" target="_top">Pimlico</a> - A
            suite of lightweight Personal Information Management (PIM)
            applications designed primarily for handheld and mobile
            devices.
        </p></li><li><p>
            <a href="http://fabrice.bellard.free.fr/qemu/" target="_top">QEMU</a>
            - An open source machine emulator and virtualizer.
        </p></li></ul></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="contact"></a>Appendix�10.�OpenedHand Contact Information</h2></div></div></div><div class="literallayout"><p><br>
OpenedHand�Ltd<br>
Unit�R,�Homesdale�Business�Center<br>
216-218�Homesdale�Rd<br>
Bromley,�BR1�2QZ<br>
England<br>
+44�(0)�208�819�6559<br>
info@openedhand.com</p></div></div><div class="index"><div class="titlepage"><div><div><h2 class="title"><a name="index"></a>Index</h2></div></div></div><div class="index"></div></div></div></body></html>
generated by cgit 1.2.3-korg (git 2.39.0) at 2024-04-25 13:41:35 +0000