diff options
| author | Scott Rifenbark <srifenbark@gmail.com> | 2018-04-12 10:52:45 -0700 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-05-24 17:16:12 +0100 |
| commit | c555881ac8e62e1bc1ddd9e0337e0c70a560b3b6 (patch) | |
| tree | 80925d3cd31d9fe7e0b6692cd9ea39fb3e947146 /documentation/overview-manual/overview-manual-yp-intro.xml | |
| parent | 4fd8b39b243f1b0d49971c233a5db2b09f1a2048 (diff) | |
| download | poky-c555881ac8e62e1bc1ddd9e0337e0c70a560b3b6.tar.gz | |
poky.ent: Added YOCTO_DOCS_OM_URL entity
The variabe for the "getting-started" manual goes away and is
replaced by this one for the new "overview-manual."
(From yocto-docs rev: 45fc9beac6db4c40c3660fc9e54cc11e9c1f96c4)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/overview-manual/overview-manual-yp-intro.xml')
| -rw-r--r-- | documentation/overview-manual/overview-manual-yp-intro.xml | 1335 |
1 files changed, 1335 insertions, 0 deletions
diff --git a/documentation/overview-manual/overview-manual-yp-intro.xml b/documentation/overview-manual/overview-manual-yp-intro.xml new file mode 100644 index 0000000000..437635842a --- /dev/null +++ b/documentation/overview-manual/overview-manual-yp-intro.xml | |||
| @@ -0,0 +1,1335 @@ | |||
| 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
| 4 | |||
| 5 | <chapter id='overview-yp'> | ||
| 6 | <title>Introducing the Yocto Project</title> | ||
| 7 | |||
| 8 | <section id='what-is-the-yocto-project'> | ||
| 9 | <title>What is the Yocto Project?</title> | ||
| 10 | |||
| 11 | <para> | ||
| 12 | The Yocto Project is an open source collaboration project | ||
| 13 | that helps developers create custom Linux-based systems that are | ||
| 14 | designed for embedded products regardless of the product's hardware | ||
| 15 | architecture. | ||
| 16 | Yocto Project provides a flexible toolset and a development | ||
| 17 | environment that allows embedded device developers across the | ||
| 18 | world to collaborate through shared technologies, software stacks, | ||
| 19 | configurations, and best practices used to create these tailored | ||
| 20 | Linux images. | ||
| 21 | </para> | ||
| 22 | |||
| 23 | <para> | ||
| 24 | Thousands of developers worldwide have discovered that Yocto | ||
| 25 | Project provides advantages in both systems and applications | ||
| 26 | development, archival and management benefits, and customizations | ||
| 27 | used for speed, footprint, and memory utilization. | ||
| 28 | The project is a standard when it comes to delivering hardware | ||
| 29 | support and software stacks, allowing software configuration | ||
| 30 | and build interchange, and build and support customizations for | ||
| 31 | multiple hardware platforms and software stacks that can be | ||
| 32 | maintained and scaled. | ||
| 33 | </para> | ||
| 34 | |||
| 35 | <para id='yp-key-dev-elements'> | ||
| 36 | <imagedata fileref="figures/key-dev-elements.png" format="PNG" align='center' width="8in"/> | ||
| 37 | </para> | ||
| 38 | |||
| 39 | <para> | ||
| 40 | For further introductory information on the Yocto Project, you | ||
| 41 | might be interested in this | ||
| 42 | <ulink url='https://www.embedded.com/electronics-blogs/say-what-/4458600/Why-the-Yocto-Project-for-my-IoT-Project-'>article</ulink> | ||
| 43 | by Drew Moseley and in this short introductory | ||
| 44 | <ulink url='https://www.youtube.com/watch?v=utZpKM7i5Z4'>video</ulink>. | ||
| 45 | </para> | ||
| 46 | |||
| 47 | <para> | ||
| 48 | The remainder of this section overviews advantages and challenges | ||
| 49 | tied to the Yocto Project. | ||
| 50 | </para> | ||
| 51 | |||
| 52 | <section id='gs-features'> | ||
| 53 | <title>Features</title> | ||
| 54 | |||
| 55 | <para> | ||
| 56 | The following list describes features and advantages of the | ||
| 57 | Yocto Project: | ||
| 58 | <itemizedlist> | ||
| 59 | <listitem><para> | ||
| 60 | <emphasis>Widely Adopted Across the Industry:</emphasis> | ||
| 61 | Semiconductor, operating system, software, and | ||
| 62 | service vendors exist whose products and services | ||
| 63 | adopt and support the Yocto Project. | ||
| 64 | For a look at the companies involved with the Yocto | ||
| 65 | Project, see the membership, associate, and | ||
| 66 | participant pages on the Yocto Project home page. | ||
| 67 | </para></listitem> | ||
| 68 | <listitem><para> | ||
| 69 | <emphasis>Architecture Agnostic:</emphasis> | ||
| 70 | Yocto Project supports Intel, ARM, MIPS, AMD, PPC | ||
| 71 | and other architectures. | ||
| 72 | Most ODMs, OSVs, and chip vendors create and supply | ||
| 73 | BSPs that support their hardware. | ||
| 74 | If you have custom silicon, you can create a BSP | ||
| 75 | that supports that architecture.</para> | ||
| 76 | |||
| 77 | <para>Aside from lots of architecture support, the | ||
| 78 | Yocto Project fully supports a wide range of device | ||
| 79 | emulation through the Quick EMUlator (QEMU). | ||
| 80 | </para></listitem> | ||
| 81 | <listitem><para> | ||
| 82 | <emphasis>Images and Code Transfer Easily:</emphasis> | ||
| 83 | Yocto Project output can easily move between | ||
| 84 | architectures without moving to new development | ||
| 85 | environments. | ||
| 86 | Additionally, if you have used the Yocto Project to | ||
| 87 | create an image or application and you find yourself | ||
| 88 | not able to support it, commercial Linux vendors such | ||
| 89 | as Wind River, Mentor Graphics, Timesys, and ENEA could | ||
| 90 | take it and provide ongoing support. | ||
| 91 | These vendors have offerings that are built using | ||
| 92 | the Yocto Project. | ||
| 93 | </para></listitem> | ||
| 94 | <listitem><para> | ||
| 95 | <emphasis>Flexibility:</emphasis> | ||
| 96 | Corporations use the Yocto Project many different ways. | ||
| 97 | One example is to create an internal Linux distribution | ||
| 98 | as a code base the corporation can use across multiple | ||
| 99 | product groups. | ||
| 100 | Through customization and layering, a project group | ||
| 101 | can leverage the base Linux distribution to create | ||
| 102 | a distribution that works for their product needs. | ||
| 103 | </para></listitem> | ||
| 104 | <listitem><para> | ||
| 105 | <emphasis>Ideal for Constrained Embedded and IoT devices:</emphasis> | ||
| 106 | Unlike a full Linux distribution, you can use the | ||
| 107 | Yocto Project to create exactly what you need for | ||
| 108 | embedded devices. | ||
| 109 | You only add the feature support or packages that you | ||
| 110 | absolutely need for the device. | ||
| 111 | For devices that have display hardware, you can use | ||
| 112 | available system components such as X11, GTK+, Qt, | ||
| 113 | Clutter, and SDL (among others) to create a rich user | ||
| 114 | experience. | ||
| 115 | For devices that do not have a display or where you | ||
| 116 | want to use alternative UI frameworks, you can choose | ||
| 117 | to not install these components. | ||
| 118 | </para></listitem> | ||
| 119 | <listitem><para> | ||
| 120 | <emphasis>Comprehensive Toolchain Capabilities:</emphasis> | ||
| 121 | Toolchains for supported architectures satisfy most | ||
| 122 | use cases. | ||
| 123 | However, if your hardware supports features that are | ||
| 124 | not part of a standard toolchain, you can easily | ||
| 125 | customize that toolchain through specification of | ||
| 126 | platform-specific tuning parameters. | ||
| 127 | And, should you need to use a third-party toolchain, | ||
| 128 | mechanisms built into the Yocto Project allow for that. | ||
| 129 | </para></listitem> | ||
| 130 | <listitem><para> | ||
| 131 | <emphasis>Mechanism Rules Over Policy:</emphasis> | ||
| 132 | Focusing on mechanism rather than policy ensures that | ||
| 133 | you are free to set policies based on the needs of your | ||
| 134 | design instead of adopting decisions enforced by some | ||
| 135 | system software provider. | ||
| 136 | </para></listitem> | ||
| 137 | <listitem><para> | ||
| 138 | <emphasis>Uses a Layer Model:</emphasis> | ||
| 139 | The Yocto Project layer infrastructure groups related | ||
| 140 | functionality into separate bundles. | ||
| 141 | You can incrementally add these grouped functionalities | ||
| 142 | to your project as needed. | ||
| 143 | Using layers to isolate and group functionality | ||
| 144 | reduces project complexity and redundancy, allows you | ||
| 145 | to easily extend the system, make customizations, | ||
| 146 | and keep functionality organized. | ||
| 147 | </para></listitem> | ||
| 148 | <listitem><para> | ||
| 149 | <emphasis>Supports Partial Builds:</emphasis> | ||
| 150 | You can build and rebuild individual packages as | ||
| 151 | needed. | ||
| 152 | Yocto Project accomplishes this through its | ||
| 153 | shared-state cache (sstate) scheme. | ||
| 154 | Being able to build and debug components individually | ||
| 155 | eases project development. | ||
| 156 | </para></listitem> | ||
| 157 | <listitem><para> | ||
| 158 | <emphasis>Releases According to a Strict Schedule:</emphasis> | ||
| 159 | Major releases occur on a six-month cycle predictably | ||
| 160 | in October and April. | ||
| 161 | The most recent two releases support point releases | ||
| 162 | to address common vulnerabilities and exposures. | ||
| 163 | This predictability is crucial for projects based on | ||
| 164 | the Yocto Project and allows development teams to | ||
| 165 | plan activities. | ||
| 166 | </para></listitem> | ||
| 167 | <listitem><para> | ||
| 168 | <emphasis>Rich Ecosystem of Individuals and Organizations:</emphasis> | ||
| 169 | For open source projects, the value of community is | ||
| 170 | very important. | ||
| 171 | Support forums, expertise, and active developers who | ||
| 172 | continue to push the Yocto Project forward are readily | ||
| 173 | available. | ||
| 174 | </para></listitem> | ||
| 175 | <listitem><para> | ||
| 176 | <emphasis>Binary Reproducibility:</emphasis> | ||
| 177 | The Yocto Project allows you to be very specific about | ||
| 178 | dependencies and achieves very high percentages of | ||
| 179 | binary reproducibility (e.g. 99.8% for | ||
| 180 | <filename>core-image-minimal</filename>). | ||
| 181 | When distributions are not specific about which | ||
| 182 | packages are pulled in and in what order to support | ||
| 183 | dependencies, other build systems can arbitrarily | ||
| 184 | include packages. | ||
| 185 | </para></listitem> | ||
| 186 | <listitem><para> | ||
| 187 | <emphasis>License Manifest:</emphasis> | ||
| 188 | The Yocto Project provides a license manifest for | ||
| 189 | review by people who need to track the use of open | ||
| 190 | source licenses (e.g.legal teams). | ||
| 191 | </para></listitem> | ||
| 192 | </itemizedlist> | ||
| 193 | </para> | ||
| 194 | </section> | ||
| 195 | |||
| 196 | <section id='gs-challenges'> | ||
| 197 | <title>Challenges</title> | ||
| 198 | |||
| 199 | <para> | ||
| 200 | The following list presents challenges you might encounter | ||
| 201 | when developing using the Yocto Project: | ||
| 202 | <itemizedlist> | ||
| 203 | <listitem><para> | ||
| 204 | <emphasis>Steep Learning Curve:</emphasis> | ||
| 205 | The Yocto Project has a steep learning curve and has | ||
| 206 | many different ways to accomplish similar tasks. | ||
| 207 | It can be difficult to choose how to proceed when | ||
| 208 | varying methods exist by which to accomplish a given | ||
| 209 | task. | ||
| 210 | </para></listitem> | ||
| 211 | <listitem><para> | ||
| 212 | <emphasis>Understanding What Changes You Need to Make | ||
| 213 | For Your Design Requires Some Research:</emphasis> | ||
| 214 | Beyond the simple tutorial stage, understanding what | ||
| 215 | changes need to be made for your particular design | ||
| 216 | can require a significant amount of research and | ||
| 217 | investigation. | ||
| 218 | For information that helps you transition from | ||
| 219 | trying out the Yocto Project to using it for your | ||
| 220 | project, see the "What I wish I'd Known" and | ||
| 221 | "Transitioning to a Custom Environment for Systems | ||
| 222 | Development" documents on the Yocto Project website. | ||
| 223 | </para></listitem> | ||
| 224 | <listitem><para> | ||
| 225 | <emphasis>Project Workflow Could Be Confusing:</emphasis> | ||
| 226 | The Yocto Project workflow could be confusing if you | ||
| 227 | are used to traditional desktop and server software | ||
| 228 | development. | ||
| 229 | In a desktop development environment, mechanisms exist | ||
| 230 | to easily pull and install new packages, which are | ||
| 231 | typically pre-compiled binaries from servers accessible | ||
| 232 | over the Internet. | ||
| 233 | Using the Yocto Project, you must modify your | ||
| 234 | configuration and rebuild to add additional packages. | ||
| 235 | </para></listitem> | ||
| 236 | <listitem><para> | ||
| 237 | <emphasis>Working in a Cross-Build Environment Can | ||
| 238 | Feel Unfamiliar:</emphasis> | ||
| 239 | When developing code to run on a target, compilation, | ||
| 240 | execution, and testing done on the actual target | ||
| 241 | can be faster than running a BitBake build on a | ||
| 242 | development host and then deploying binaries to the | ||
| 243 | target for test. | ||
| 244 | While the Yocto Project does support development tools | ||
| 245 | on the target, the additional step of integrating your | ||
| 246 | changes back into the Yocto Project build environment | ||
| 247 | would be required. | ||
| 248 | Yocto Project supports an intermediate approach that | ||
| 249 | involves making changes on the development system | ||
| 250 | within the BitBake environment and then deploying only | ||
| 251 | the updated packages to the target.</para> | ||
| 252 | |||
| 253 | <para>The Yocto Project OpenEmbedded build system | ||
| 254 | produces packages in standard formats (i.e. RPM, | ||
| 255 | DEB, IPK, and TAR). | ||
| 256 | You can deploy these packages into the running system | ||
| 257 | on the target by using utilities on the target such | ||
| 258 | as <filename>rpm</filename> or | ||
| 259 | <filename>ipk</filename>. | ||
| 260 | </para></listitem> | ||
| 261 | <listitem><para> | ||
| 262 | <emphasis>Initial Build Times Can be Significant:</emphasis> | ||
| 263 | Long initial build times are unfortunately unavoidable | ||
| 264 | due to the large number of packages initially built | ||
| 265 | from scratch for a fully functioning Linux system. | ||
| 266 | Once that initial build is completed, however, the | ||
| 267 | shared-state (sstate) cache mechanism Yocto Project | ||
| 268 | uses keeps the system from rebuilding packages that | ||
| 269 | have not been "touched" since the last build. | ||
| 270 | The sstate mechanism significantly reduces times | ||
| 271 | for successive builds. | ||
| 272 | </para></listitem> | ||
| 273 | </itemizedlist> | ||
| 274 | </para> | ||
| 275 | </section> | ||
| 276 | </section> | ||
| 277 | |||
| 278 | <section id='the-yocto-project-layer-model'> | ||
| 279 | <title>The Yocto Project Layer Model</title> | ||
| 280 | |||
| 281 | <para> | ||
| 282 | The Yocto Project's "Layer Model" is a development model for | ||
| 283 | embedded and IoT Linux creation that distinguishes the | ||
| 284 | Yocto Project from other simple build systems. | ||
| 285 | The Layer Model simultaneously supports collaboration and | ||
| 286 | customization. | ||
| 287 | Layers are repositories that contain related sets of instructions | ||
| 288 | that tell the OpenEmbedded build system what to do. | ||
| 289 | You can collaborate, share, and reuse layers. | ||
| 290 | </para> | ||
| 291 | |||
| 292 | <para> | ||
| 293 | Layers can contain changes to previous instructions or settings | ||
| 294 | at any time. | ||
| 295 | This powerful override capability is what allows you to customize | ||
| 296 | previously supplied collaborative or community layers to suit your | ||
| 297 | product requirements. | ||
| 298 | </para> | ||
| 299 | |||
| 300 | <para> | ||
| 301 | You use different layers to logically separate information in your | ||
| 302 | build. | ||
| 303 | As an example, you could have BSP, GUI, distro configuration, | ||
| 304 | middleware, or application layers. | ||
| 305 | Putting your entire build into one layer limits and complicates | ||
| 306 | future customization and reuse. | ||
| 307 | Isolating information into layers, on the other hand, helps | ||
| 308 | simplify future customizations and reuse. | ||
| 309 | You might find it tempting to keep everything in one layer when | ||
| 310 | working on a single project. | ||
| 311 | However, the more modular your Metadata, the easier | ||
| 312 | it is to cope with future changes. | ||
| 313 | <note><title>Notes</title> | ||
| 314 | <itemizedlist> | ||
| 315 | <listitem><para> | ||
| 316 | Use Board Support Package (BSP) layers from silicon | ||
| 317 | vendors when possible. | ||
| 318 | </para></listitem> | ||
| 319 | <listitem><para> | ||
| 320 | Familiarize yourself with the | ||
| 321 | <ulink url='https://caffelli-staging.yoctoproject.org/software-overview/layers/'>Yocto Project curated layer index</ulink> | ||
| 322 | or the | ||
| 323 | <ulink url='http://layers.openembedded.org/layerindex/branch/master/layers/'>OpenEmbedded layer index</ulink>. | ||
| 324 | The latter contains more layers but they are less | ||
| 325 | universally validated. | ||
| 326 | </para></listitem> | ||
| 327 | <listitem><para> | ||
| 328 | Layers support the inclusion of technologies, hardware | ||
| 329 | components, and software components. | ||
| 330 | The Yocto Project Compatible designation provides a | ||
| 331 | minimum level of standardization that contributes to a | ||
| 332 | strong ecosystem. | ||
| 333 | "YP Compatible" is applied to appropriate products and | ||
| 334 | software components such as BSPs, other OE-compatible | ||
| 335 | layers, and related open-source projects, allowing the | ||
| 336 | producer to use Yocto Project badges and branding | ||
| 337 | assets. | ||
| 338 | </para></listitem> | ||
| 339 | </itemizedlist> | ||
| 340 | </note> | ||
| 341 | </para> | ||
| 342 | |||
| 343 | <para> | ||
| 344 | To illustrate how layers are used to keep things modular, consider | ||
| 345 | machine customizations. | ||
| 346 | These types of customizations typically reside in a special layer, | ||
| 347 | rather than a general layer, called a BSP Layer. | ||
| 348 | Furthermore, the machine customizations should be isolated from | ||
| 349 | recipes and Metadata that support a new GUI environment, | ||
| 350 | for example. | ||
| 351 | This situation gives you a couple of layers: one for the machine | ||
| 352 | configurations, and one for the GUI environment. | ||
| 353 | It is important to understand, however, that the BSP layer can | ||
| 354 | still make machine-specific additions to recipes within the GUI | ||
| 355 | environment layer without polluting the GUI layer itself | ||
| 356 | with those machine-specific changes. | ||
| 357 | You can accomplish this through a recipe that is a BitBake append | ||
| 358 | (<filename>.bbappend</filename>) file, which is described later | ||
| 359 | in this section. | ||
| 360 | <note> | ||
| 361 | For general information on BSP layer structure, see the | ||
| 362 | <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Board Support Packages (BSP) - Developer's Guide</ulink>. | ||
| 363 | </note> | ||
| 364 | </para> | ||
| 365 | |||
| 366 | <para> | ||
| 367 | The | ||
| 368 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> | ||
| 369 | contains both general layers and BSP layers right out of the box. | ||
| 370 | You can easily identify layers that ship with a Yocto Project | ||
| 371 | release in the Source Directory by their names. | ||
| 372 | Layers typically have names that begin with the string | ||
| 373 | <filename>meta-</filename>. | ||
| 374 | <note> | ||
| 375 | It is not a requirement that a layer name begin with the | ||
| 376 | prefix <filename>meta-</filename>, but it is a commonly | ||
| 377 | accepted standard in the Yocto Project community. | ||
| 378 | </note> | ||
| 379 | For example, if you were to examine the | ||
| 380 | <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/'>tree view</ulink> | ||
| 381 | of the <filename>poky</filename> repository, you will see several | ||
| 382 | layers: <filename>meta</filename>, | ||
| 383 | <filename>meta-skeleton</filename>, | ||
| 384 | <filename>meta-selftest</filename>, | ||
| 385 | <filename>meta-poky</filename>, and | ||
| 386 | <filename>meta-yocto-bsp</filename>. | ||
| 387 | Each of these repositories represents a distinct layer. | ||
| 388 | </para> | ||
| 389 | |||
| 390 | <para> | ||
| 391 | For procedures on how to create layers, see the | ||
| 392 | "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" | ||
| 393 | section in the Yocto Project Development Tasks Manual. | ||
| 394 | </para> | ||
| 395 | </section> | ||
| 396 | |||
| 397 | <section id='components-and-tools'> | ||
| 398 | <title>Components and Tools</title> | ||
| 399 | |||
| 400 | <para> | ||
| 401 | The Yocto Project employs a collection of components and | ||
| 402 | tools used by the project itself, by project developers, | ||
| 403 | and by those using the Yocto Project. | ||
| 404 | These components and tools are open source projects and | ||
| 405 | metadata that are separate from the reference distribution | ||
| 406 | (Poky) and the OpenEmbedded build system. | ||
| 407 | Most of the components and tools are downloaded separately. | ||
| 408 | </para> | ||
| 409 | |||
| 410 | <para> | ||
| 411 | This section provides brief overviews of the components and | ||
| 412 | tools associated with the Yocto Project. | ||
| 413 | </para> | ||
| 414 | |||
| 415 | <section id='gs-development-tools'> | ||
| 416 | <title>Development Tools</title> | ||
| 417 | |||
| 418 | <para> | ||
| 419 | The following list consists of tools that help you develop | ||
| 420 | images and applications using the Yocto Project: | ||
| 421 | <itemizedlist> | ||
| 422 | <listitem><para id='gs-crops-overview'> | ||
| 423 | <emphasis>CROPS:</emphasis> | ||
| 424 | <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink> | ||
| 425 | is an open source, cross-platform development framework | ||
| 426 | that leverages | ||
| 427 | <ulink url='https://www.docker.com/'>Docker Containers</ulink>. | ||
| 428 | CROPS provides an easily managed, extensible environment | ||
| 429 | that allows you to build binaries for a variety of | ||
| 430 | architectures on Windows, Linux and Mac OS X hosts. | ||
| 431 | </para></listitem> | ||
| 432 | <listitem><para> | ||
| 433 | <emphasis><filename>devtool</filename>:</emphasis> | ||
| 434 | This command-line tool is available as part of the | ||
| 435 | extensible SDK (eSDK) and is its cornerstone. | ||
| 436 | You can use <filename>devtool</filename> to help build, | ||
| 437 | test, and package software within the eSDK. | ||
| 438 | You can use the tool to optionally integrate what you | ||
| 439 | build into an image built by the OpenEmbedded build | ||
| 440 | system.</para> | ||
| 441 | |||
| 442 | <para>The <filename>devtool</filename> command employs | ||
| 443 | a number of sub-commands that allow you to add, modify, | ||
| 444 | and upgrade recipes. | ||
| 445 | As with the OpenEmbedded build system, “recipes” | ||
| 446 | represent software packages within | ||
| 447 | <filename>devtool</filename>. | ||
| 448 | When you use <filename>devtool add</filename>, a recipe | ||
| 449 | is automatically created. | ||
| 450 | When you use <filename>devtool modify</filename>, the | ||
| 451 | specified existing recipe is used in order to determine | ||
| 452 | where to get the source code and how to patch it. | ||
| 453 | In both cases, an environment is set up so that when | ||
| 454 | you build the recipe a source tree that is under your | ||
| 455 | control is used in order to allow you to make changes | ||
| 456 | to the source as desired. | ||
| 457 | By default, both new recipes and the source go into | ||
| 458 | a “workspace” directory under the eSDK. | ||
| 459 | The <filename>devtool upgrade</filename> command | ||
| 460 | updates an existing recipe so that you can build it | ||
| 461 | for an updated set of source files.</para> | ||
| 462 | |||
| 463 | <para>You can read about the | ||
| 464 | <filename>devtool</filename> workflow in the Yocto | ||
| 465 | Project Application Development and Extensible | ||
| 466 | Software Development Kit (eSDK) Manual in the | ||
| 467 | "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow'</ulink>" | ||
| 468 | section. | ||
| 469 | </para></listitem> | ||
| 470 | <listitem><para> | ||
| 471 | <emphasis>Extensible Software Development Kit (eSDK):</emphasis> | ||
| 472 | The eSDK provides a cross-development toolchain and | ||
| 473 | libraries tailored to the contents of a specific image. | ||
| 474 | The eSDK makes it easy to add new applications and | ||
| 475 | libraries to an image, modify the source for an | ||
| 476 | existing component, test changes on the target | ||
| 477 | hardware, and integrate into the rest of the | ||
| 478 | OpenEmbedded build system. | ||
| 479 | The eSDK gives you a toolchain experience supplemented | ||
| 480 | with the powerful set of <filename>devtool</filename> | ||
| 481 | commands tailored for the Yocto Project environment. | ||
| 482 | </para> | ||
| 483 | |||
| 484 | <para>For information on the eSDK, see the | ||
| 485 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and Extensible Software Development Kit (eSDK) Manual</ulink>. | ||
| 486 | </para></listitem> | ||
| 487 | <listitem><para> | ||
| 488 | <emphasis><trademark class='trade'>Eclipse</trademark> IDE Plug-in:</emphasis> | ||
| 489 | This plug-in enables you to use the popular Eclipse | ||
| 490 | Integrated Development Environment (IDE), which allows | ||
| 491 | for development using the Yocto Project all within the | ||
| 492 | Eclipse IDE. | ||
| 493 | You can work within Eclipse to cross-compile, deploy, | ||
| 494 | and execute your output into a QEMU emulation session | ||
| 495 | as well as onto actual target hardware.</para> | ||
| 496 | |||
| 497 | <para>The environment also supports performance | ||
| 498 | enhancing tools that allow you to perform remote | ||
| 499 | profiling, tracing, collection of power data, | ||
| 500 | collection of latency data, and collection of | ||
| 501 | performance data.</para> | ||
| 502 | |||
| 503 | <para>Once you enable the plug-in, standard Eclipse | ||
| 504 | functions automatically use the cross-toolchain | ||
| 505 | and target system libraries. | ||
| 506 | You can build applications using any of these | ||
| 507 | libraries.</para> | ||
| 508 | |||
| 509 | <para>For more information on the Eclipse plug-in, | ||
| 510 | see the | ||
| 511 | "<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working Within Eclipse</ulink>" | ||
| 512 | section in the Yocto Project Application Development | ||
| 513 | and the Extensible Software Development Kit (eSDK) | ||
| 514 | manual. | ||
| 515 | </para></listitem> | ||
| 516 | <listitem><para> | ||
| 517 | <emphasis>Toaster:</emphasis> | ||
| 518 | Toaster is a web interface to the Yocto Project | ||
| 519 | OpenEmbedded build system. | ||
| 520 | Toaster allows you to configure, run, and view | ||
| 521 | information about builds. | ||
| 522 | </para></listitem> | ||
| 523 | </itemizedlist> | ||
| 524 | </para> | ||
| 525 | </section> | ||
| 526 | |||
| 527 | <section id='gs-production-tools'> | ||
| 528 | <title>Production Tools</title> | ||
| 529 | |||
| 530 | <para> | ||
| 531 | The following list consists of tools that help production | ||
| 532 | related activities using the Yocto Project: | ||
| 533 | <itemizedlist> | ||
| 534 | <listitem><para> | ||
| 535 | <emphasis>Auto Upgrade Helper:</emphasis> | ||
| 536 | This utility when used in conjunction with the | ||
| 537 | OpenEmbedded build system (BitBake and OE-Core) | ||
| 538 | automatically generates upgrades for recipes that | ||
| 539 | are based on new versions of the recipes published | ||
| 540 | upstream. | ||
| 541 | </para></listitem> | ||
| 542 | <listitem><para> | ||
| 543 | <emphasis>Recipe Reporting System:</emphasis> | ||
| 544 | The Recipe Reporting System tracks recipe versions | ||
| 545 | available for Yocto Project. | ||
| 546 | The main purpose of the system is to help you | ||
| 547 | manage the recipes you maintain and to offer a dynamic | ||
| 548 | overview of the project. | ||
| 549 | The Recipe Reporting System is built on top | ||
| 550 | the of OpenEmbedded Metadata Index, which is a website | ||
| 551 | that indexes layers for the OpenEmbedded build system. | ||
| 552 | </para></listitem> | ||
| 553 | <listitem><para> | ||
| 554 | <emphasis>Patchwork:</emphasis> | ||
| 555 | <ulink url='http://jk.ozlabs.org/projects/patchwork/'>Patchwork</ulink> | ||
| 556 | is a fork of a project originally started by | ||
| 557 | <ulink url='http://ozlabs.org/'>OzLabs</ulink>. | ||
| 558 | The project is a web-based tracking system designed | ||
| 559 | to streamline the process of bringing contributions | ||
| 560 | into a project. | ||
| 561 | The Yocto Project uses Patchwork as an organizational | ||
| 562 | tool to handle patches, which number in the thousands | ||
| 563 | for every release. | ||
| 564 | </para></listitem> | ||
| 565 | <listitem><para> | ||
| 566 | <emphasis>AutoBuilder:</emphasis> | ||
| 567 | AutoBuilder is a project that automates build tests | ||
| 568 | and quality assurance (QA). | ||
| 569 | By using the public AutoBuilder, anyone can determine | ||
| 570 | the status of the current "master" branch of Poky. | ||
| 571 | </para> | ||
| 572 | |||
| 573 | <para>A goal of the Yocto Project is to lead the | ||
| 574 | open source industry with a project that automates | ||
| 575 | testing and QA procedures. | ||
| 576 | In doing so, the project encourages a development | ||
| 577 | community that publishes QA and test plans, publicly | ||
| 578 | demonstrates QA and test plans, and encourages | ||
| 579 | development of tools that automate and test and QA | ||
| 580 | procedures for the benefit of the development | ||
| 581 | community.</para> | ||
| 582 | |||
| 583 | <para>You can learn more about the AutoBuilder used | ||
| 584 | by the Yocto Project | ||
| 585 | <ulink url='&YOCTO_AB_URL;'>here</ulink>. | ||
| 586 | </para></listitem> | ||
| 587 | <listitem><para> | ||
| 588 | <emphasis>Cross-Prelink:</emphasis> | ||
| 589 | Prelinking is the process of pre-computing the load | ||
| 590 | addresses and link tables generated by the dynamic | ||
| 591 | linker as compared to doing this at runtime. | ||
| 592 | Doing this ahead of time results in performance | ||
| 593 | improvements when the application is launched and | ||
| 594 | reduced memory usage for libraries shared by many | ||
| 595 | applications.</para> | ||
| 596 | |||
| 597 | <para>Historically, cross-prelink is a variant of | ||
| 598 | prelink, which was conceived by | ||
| 599 | <ulink url='http://people.redhat.com/jakub/prelink.pdf'>Jakub Jelínek</ulink> | ||
| 600 | a number of years ago. | ||
| 601 | Both prelink and cross-prelink are maintained in the | ||
| 602 | same repository albeit on separate branches. | ||
| 603 | By providing an emulated runtime dynamic linker | ||
| 604 | (i.e. <filename>glibc</filename>-derived | ||
| 605 | <filename>ld.so</filename> emulation), the | ||
| 606 | cross-prelink project extends the prelink software’s | ||
| 607 | ability to prelink a sysroot environment. | ||
| 608 | Additionally, the cross-prelink software enables the | ||
| 609 | ability to work in sysroot style environments.</para> | ||
| 610 | |||
| 611 | <para>The dynamic linker determines standard load | ||
| 612 | address calculations based on a variety of factors | ||
| 613 | such as mapping addresses, library usage, and library | ||
| 614 | function conflicts. | ||
| 615 | The prelink tool uses this information, from the | ||
| 616 | dynamic linker, to determine unique load addresses | ||
| 617 | for executable and linkable format (ELF) binaries | ||
| 618 | that are shared libraries and dynamically linked. | ||
| 619 | The prelink tool modifies these ELF binaries with the | ||
| 620 | pre-computed information. | ||
| 621 | The result is faster loading and often lower memory | ||
| 622 | consumption because more of the library code can | ||
| 623 | be re-used from shared Copy-On-Write (COW) pages. | ||
| 624 | </para> | ||
| 625 | |||
| 626 | <para>The original upstream prelink project only | ||
| 627 | supports running prelink on the end target device | ||
| 628 | due to the reliance on the target device’s dynamic | ||
| 629 | linker. | ||
| 630 | This restriction causes issues when developing a | ||
| 631 | cross-compiled system. | ||
| 632 | The cross-prelink adds a synthesized dynamic loader | ||
| 633 | that runs on the host, thus permitting cross-prelinking | ||
| 634 | without ever having to run on a read-write target | ||
| 635 | filesystem. | ||
| 636 | </para></listitem> | ||
| 637 | <listitem><para> | ||
| 638 | <emphasis>Pseudo:</emphasis> | ||
| 639 | Pseudo is the Yocto Project implementation of | ||
| 640 | <ulink url='http://man.he.net/man1/fakeroot'>fakeroot</ulink>, | ||
| 641 | which is used to run commands in an environment | ||
| 642 | that seemingly has root privileges.</para> | ||
| 643 | |||
| 644 | <para>During a build, it can be necessary to perform | ||
| 645 | operations that require system administrator | ||
| 646 | privileges. | ||
| 647 | For example, file ownership or permissions might need | ||
| 648 | definition. | ||
| 649 | Pseudo is a tool that you can either use directly or | ||
| 650 | through the environment variable | ||
| 651 | <filename>LD_PRELOAD</filename>. | ||
| 652 | Either method allows these operations to succeed as | ||
| 653 | if system administrator privileges exist even | ||
| 654 | when they do not.</para> | ||
| 655 | |||
| 656 | <para>You can read more about Pseudo in the | ||
| 657 | "<ulink url='&YOCTO_DOCS_GS_URL;#fakeroot-and-pseudo'>Fakeroot and Pseudo</ulink>" | ||
| 658 | section of the Yocto Project Overview and Concepts | ||
| 659 | Manual. | ||
| 660 | </para></listitem> | ||
| 661 | </itemizedlist> | ||
| 662 | </para> | ||
| 663 | </section> | ||
| 664 | |||
| 665 | <section id='gs-openembedded-build-system'> | ||
| 666 | <title>Open-Embedded Build System Components</title> | ||
| 667 | |||
| 668 | <para> | ||
| 669 | The following list consists of components associated with the | ||
| 670 | Open-Embedded build system: | ||
| 671 | <itemizedlist> | ||
| 672 | <listitem><para> | ||
| 673 | <emphasis>BitBake:</emphasis> | ||
| 674 | BitBake is a core component of the Yocto Project and is | ||
| 675 | used by the OpenEmbedded build system to build images. | ||
| 676 | While BitBake is key to the build system, BitBake | ||
| 677 | is maintained separately from the Yocto Project.</para> | ||
| 678 | |||
| 679 | <para>BitBake is a generic task execution engine that | ||
| 680 | allows shell and Python tasks to be run efficiently | ||
| 681 | and in parallel while working within complex inter-task | ||
| 682 | dependency constraints. | ||
| 683 | In short, BitBake is a build engine that works | ||
| 684 | through recipes written in a specific format in order | ||
| 685 | to perform sets of tasks.</para> | ||
| 686 | |||
| 687 | <para>You can learn more about BitBake in the | ||
| 688 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | ||
| 689 | </para></listitem> | ||
| 690 | <listitem><para> | ||
| 691 | <emphasis>OpenEmbedded-Core:</emphasis> | ||
| 692 | OpenEmbedded-Core (OE-Core) is a common layer of | ||
| 693 | metadata (i.e. recipes, classes, and associated files) | ||
| 694 | used by OpenEmbedded-derived systems, which includes | ||
| 695 | the Yocto Project. | ||
| 696 | The Yocto Project and the OpenEmbedded Project both | ||
| 697 | maintain the OpenEmbedded-Core. | ||
| 698 | You can find the OE-Core metadata in the Yocto | ||
| 699 | Project | ||
| 700 | <ulink url='&YOCTO_DOCS_GS_URL;#source-repositories'>Source Repositories</ulink> | ||
| 701 | <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta'>here</ulink>. | ||
| 702 | </para> | ||
| 703 | |||
| 704 | <para>Historically, the Yocto Project integrated the | ||
| 705 | OE-Core metadata throughout the Yocto Project | ||
| 706 | source repository reference system (Poky). | ||
| 707 | After Yocto Project Version 1.0, the Yocto Project | ||
| 708 | and OpenEmbedded agreed to work together and share a | ||
| 709 | common core set of metadata (OE-Core), which contained | ||
| 710 | much of the functionality previously found in Poky. | ||
| 711 | This collaboration achieved a long-standing | ||
| 712 | OpenEmbedded objective for having a more tightly | ||
| 713 | controlled and quality-assured core. | ||
| 714 | The results also fit well with the Yocto Project | ||
| 715 | objective of achieving a smaller number of fully | ||
| 716 | featured tools as compared to many different ones. | ||
| 717 | </para> | ||
| 718 | |||
| 719 | <para>Sharing a core set of metadata results in Poky | ||
| 720 | as an integration layer on top of OE-Core. | ||
| 721 | You can see that in this | ||
| 722 | <link linkend='yp-key-dev-elements'>figure</link>. | ||
| 723 | The Yocto Project combines various components such as | ||
| 724 | BitBake, OE-Core, script “glue”, and documentation | ||
| 725 | for its build system. | ||
| 726 | </para></listitem> | ||
| 727 | </itemizedlist> | ||
| 728 | </para> | ||
| 729 | </section> | ||
| 730 | |||
| 731 | <section id='gs-reference-distribution-poky'> | ||
| 732 | <title>Reference Distribution (Poky)</title> | ||
| 733 | |||
| 734 | <para> | ||
| 735 | Poky is the Yocto Project reference distribution. | ||
| 736 | It contains the OpenEmbedded build system (BitBake and OE-Core) | ||
| 737 | as well as a set of metadata to get you started building your | ||
| 738 | own distribution. | ||
| 739 | See the | ||
| 740 | <link linkend='what-is-the-yocto-project'>figure</link> in | ||
| 741 | "What is the Yocto Project?" section for an illustration | ||
| 742 | that shows Poky and its relationship with other parts of the | ||
| 743 | Yocto Project.</para> | ||
| 744 | |||
| 745 | <para>To use the Yocto Project tools and components, you | ||
| 746 | can download (<filename>clone</filename>) Poky and use it | ||
| 747 | to bootstrap your own distribution. | ||
| 748 | <note> | ||
| 749 | Poky does not contain binary files. | ||
| 750 | It is a working example of how to build your own custom | ||
| 751 | Linux distribution from source. | ||
| 752 | </note> | ||
| 753 | You can read more about Poky in the | ||
| 754 | "<link linkend='reference-embedded-distribution'>Reference Embedded Distribution (Poky)</link>" | ||
| 755 | section. | ||
| 756 | </para> | ||
| 757 | </section> | ||
| 758 | |||
| 759 | <section id='gs-packages-for-finished-targets'> | ||
| 760 | <title>Packages for Finished Targets</title> | ||
| 761 | |||
| 762 | <para> | ||
| 763 | The following lists components associated with packages | ||
| 764 | for finished targets: | ||
| 765 | <itemizedlist> | ||
| 766 | <listitem><para> | ||
| 767 | <emphasis>Matchbox:</emphasis> | ||
| 768 | Matchbox is an Open Source, base environment for the | ||
| 769 | X Window System running on non-desktop, embedded | ||
| 770 | platforms such as handhelds, set-top boxes, kiosks, | ||
| 771 | and anything else for which screen space, input | ||
| 772 | mechanisms, or system resources are limited.</para> | ||
| 773 | |||
| 774 | <para>Matchbox consists of a number of interchangeable | ||
| 775 | and optional applications that you can tailor to a | ||
| 776 | specific, non-desktop platform to enhance usability | ||
| 777 | in constrained environments.</para> | ||
| 778 | |||
| 779 | <para>You can find the Matchbox source in its | ||
| 780 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>repository</ulink> | ||
| 781 | listed in the Yocto Project | ||
| 782 | <ulink url='&YOCTO_DOCS_GS_URL;#source-repositories'>Source Repositories</ulink>. | ||
| 783 | </para></listitem> | ||
| 784 | <listitem><para> | ||
| 785 | <emphasis>Opkg</emphasis> | ||
| 786 | Open PacKaGe management (opkg) is a lightweight | ||
| 787 | package management system based on the itsy package | ||
| 788 | (ipkg) management system. | ||
| 789 | Opkg is written in C and resembles Advanced Package | ||
| 790 | Tool (APT) and Debian Package (dpkg) in operation. | ||
| 791 | </para> | ||
| 792 | |||
| 793 | <para>Opkg is intended for use on embedded Linux | ||
| 794 | devices and is used in this capacity in the | ||
| 795 | <ulink url='http://www.openembedded.org/wiki/Main_Page'>OpenEmbedded</ulink> | ||
| 796 | and | ||
| 797 | <ulink url='https://openwrt.org/'>OpenWrt</ulink> | ||
| 798 | projects, as well as the Yocto Project. | ||
| 799 | <note> | ||
| 800 | As best it can, opkg maintains backwards | ||
| 801 | compatibility with ipkg and conforms to a subset | ||
| 802 | of Debian’s policy manual regarding control files. | ||
| 803 | </note> | ||
| 804 | </para></listitem> | ||
| 805 | </itemizedlist> | ||
| 806 | </para> | ||
| 807 | </section> | ||
| 808 | |||
| 809 | <section id='gs-archived-components'> | ||
| 810 | <title>Archived Components</title> | ||
| 811 | |||
| 812 | <para> | ||
| 813 | The Build Appliance is a virtual machine image that enables | ||
| 814 | you to build and boot a custom embedded Linux image with | ||
| 815 | the Yocto Project using a non-Linux development system. | ||
| 816 | </para> | ||
| 817 | |||
| 818 | <para> | ||
| 819 | Historically, the Build Appliance was the second of three | ||
| 820 | methods by which you could use the Yocto Project on a system | ||
| 821 | that was not native to Linux. | ||
| 822 | <orderedlist> | ||
| 823 | <listitem><para> | ||
| 824 | <emphasis>Hob:</emphasis> | ||
| 825 | Hob, which is now deprecated and is no longer available | ||
| 826 | since the 2.1 release of the Yocto Project provided | ||
| 827 | a rudimentary, GUI-based interface to the Yocto | ||
| 828 | Project. | ||
| 829 | Toaster has fully replaced Hob. | ||
| 830 | </para></listitem> | ||
| 831 | <listitem><para> | ||
| 832 | <emphasis>Build Appliance:</emphasis> | ||
| 833 | Post Hob, the Build Appliance became available. | ||
| 834 | It was never recommended that you use the Build | ||
| 835 | Appliance as a day-to-day production development | ||
| 836 | environment with the Yocto Project. | ||
| 837 | Build Appliance was useful as a way to try out | ||
| 838 | development in the Yocto Project environment. | ||
| 839 | </para></listitem> | ||
| 840 | <listitem><para> | ||
| 841 | <emphasis>CROPS:</emphasis> | ||
| 842 | The final and best solution available now for | ||
| 843 | developing using the Yocto Project on a system | ||
| 844 | not native to Linux is with | ||
| 845 | <link linkend='gs-crops-overview'>CROPS</link>. | ||
| 846 | </para></listitem> | ||
| 847 | </orderedlist> | ||
| 848 | </para> | ||
| 849 | </section> | ||
| 850 | </section> | ||
| 851 | |||
| 852 | <section id='gs-development-methods'> | ||
| 853 | <title>Development Methods</title> | ||
| 854 | |||
| 855 | <para> | ||
| 856 | The Yocto Project development environment usually involves a | ||
| 857 | <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink> | ||
| 858 | and target hardware. | ||
| 859 | You use the Build Host to build images and develop applications, | ||
| 860 | while you use the target hardware to test deployed software. | ||
| 861 | </para> | ||
| 862 | |||
| 863 | <para> | ||
| 864 | This section provides an introduction to the choices or | ||
| 865 | development methods you have when setting up your Build Host. | ||
| 866 | Depending on the your particular workflow preference and the | ||
| 867 | type of operating system your Build Host runs, several choices | ||
| 868 | exist that allow you to use the Yocto Project. | ||
| 869 | <note> | ||
| 870 | For additional detail about the Yocto Project development | ||
| 871 | environment, see the | ||
| 872 | "<link linkend='overview-development-environment'>The Yocto Project Development Environment</link>" | ||
| 873 | chapter. | ||
| 874 | </note> | ||
| 875 | <itemizedlist> | ||
| 876 | <listitem><para> | ||
| 877 | <emphasis>Native Linux Host:</emphasis> | ||
| 878 | By far the best option for a Build Host. | ||
| 879 | A system running Linux as its native operating system | ||
| 880 | allows you to develop software by directly using the | ||
| 881 | <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> | ||
| 882 | tool. | ||
| 883 | You can accomplish all aspects of development from a | ||
| 884 | familiar shell of a supported Linux distribution.</para> | ||
| 885 | |||
| 886 | <para>For information on how to set up a Build Host on | ||
| 887 | a system running Linux as its native operating system, | ||
| 888 | see the | ||
| 889 | "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host'>Setting Up a Native Linux Host</ulink>" | ||
| 890 | section in the Yocto Project Development Tasks Manual. | ||
| 891 | </para></listitem> | ||
| 892 | <listitem><para> | ||
| 893 | <emphasis>CROss PlatformS (CROPS):</emphasis> | ||
| 894 | Typically, you use | ||
| 895 | <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>, | ||
| 896 | which leverages | ||
| 897 | <ulink url='https://www.docker.com/'>Docker Containers</ulink>, | ||
| 898 | to set up a Build Host that is not running Linux (e.g. | ||
| 899 | <trademark class='registered'>Microsoft</trademark> | ||
| 900 | <trademark class='trademark'>Windows</trademark> | ||
| 901 | or | ||
| 902 | <trademark class='registered'>macOS</trademark>). | ||
| 903 | <note> | ||
| 904 | You can, however, use CROPS on a Linux-based system. | ||
| 905 | </note> | ||
| 906 | CROPS is an open source, cross-platform development | ||
| 907 | framework that provides an easily managed, extensible | ||
| 908 | environment for building binaries targeted for a variety | ||
| 909 | of architectures on Windows, macOS, or Linux hosts. | ||
| 910 | Once the Build Host is set up using CROPS, you can prepare | ||
| 911 | a shell environment to mimic that of a shell being used | ||
| 912 | on a system natively running Linux.</para> | ||
| 913 | |||
| 914 | <para>For information on how to set up a Build Host with | ||
| 915 | CROPS, see the | ||
| 916 | "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>" | ||
| 917 | section in the Yocto Project Development Tasks Manual. | ||
| 918 | </para></listitem> | ||
| 919 | <listitem><para> | ||
| 920 | <emphasis>Toaster:</emphasis> | ||
| 921 | Regardless of what your Build Host is running, you can | ||
| 922 | use Toaster to develop software using the Yocto Project. | ||
| 923 | Toaster is a web interface to the Yocto Project's | ||
| 924 | OpenEmbedded build system. | ||
| 925 | The interface enables you to configure and run your | ||
| 926 | builds. | ||
| 927 | Information about builds is collected and stored in a | ||
| 928 | database. | ||
| 929 | You can use Toaster to configure and start builds on | ||
| 930 | multiple remote build servers.</para> | ||
| 931 | |||
| 932 | <para>For information about and how to use Toaster, | ||
| 933 | see the | ||
| 934 | <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>. | ||
| 935 | </para></listitem> | ||
| 936 | <listitem><para> | ||
| 937 | <emphasis><trademark class='trade'>Eclipse</trademark> IDE:</emphasis> | ||
| 938 | If your Build Host supports and runs the popular | ||
| 939 | Eclipse IDE, you can install the Yocto Project Eclipse | ||
| 940 | plug-in and use the Yocto Project to develop software. | ||
| 941 | The plug-in integrates the Yocto Project functionality | ||
| 942 | into Eclipse development practices.</para> | ||
| 943 | |||
| 944 | <para>For information about how to install and use the | ||
| 945 | Yocto Project Eclipse plug-in, see the | ||
| 946 | "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-eclipse-project'>Developing Applications Using Eclipse</ulink>" | ||
| 947 | section in the Yocto Project Application Development and | ||
| 948 | the Extensible Software Development Kit (eSDK) Manual. | ||
| 949 | </para></listitem> | ||
| 950 | </itemizedlist> | ||
| 951 | </para> | ||
| 952 | </section> | ||
| 953 | |||
| 954 | <section id='reference-embedded-distribution'> | ||
| 955 | <title>Reference Embedded Distribution (Poky)</title> | ||
| 956 | |||
| 957 | <para> | ||
| 958 | "Poky", which is pronounced <emphasis>Pock</emphasis>-ee, is the | ||
| 959 | name of the Yocto Project's reference distribution or Reference OS | ||
| 960 | Kit. | ||
| 961 | Poky contains the | ||
| 962 | <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded Build System</ulink> | ||
| 963 | build system | ||
| 964 | (<ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> and | ||
| 965 | <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core</ulink>) | ||
| 966 | as well as a set of | ||
| 967 | <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>metadata</ulink> to get | ||
| 968 | you started building your own distro. | ||
| 969 | In other words, Poky is a base specification of the functionality | ||
| 970 | needed for a typical embedded system as well as the components | ||
| 971 | from the Yocto Project that allow you to build a distribution into | ||
| 972 | a usable binary image. | ||
| 973 | </para> | ||
| 974 | |||
| 975 | <para> | ||
| 976 | Poky is a combined repository of BitBake, OpenEmbedded-Core | ||
| 977 | (which is found in <filename>meta</filename>), | ||
| 978 | <filename>meta-poky</filename>, | ||
| 979 | <filename>meta-yocto-bsp</filename>, and documentation provided | ||
| 980 | all together and known to work well together. | ||
| 981 | You can view these items that make up the Poky repository in the | ||
| 982 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/'>Source Repositories</ulink>. | ||
| 983 | <note> | ||
| 984 | If you are interested in all the contents of the | ||
| 985 | <filename>poky</filename> Git repository, see the | ||
| 986 | "<ulink url='&YOCTO_DOCS_REF_URL;#structure-core'>Top-Level Core Components</ulink>" | ||
| 987 | section in the Yocto Project Reference Manual. | ||
| 988 | </note> | ||
| 989 | </para> | ||
| 990 | |||
| 991 | <para id='gs-poky-reference-distribution'> | ||
| 992 | The following figure illustrates what generally comprises Poky: | ||
| 993 | <imagedata fileref="figures/poky-reference-distribution.png" format="PNG" align='center' width="8in"/> | ||
| 994 | <itemizedlist> | ||
| 995 | <listitem><para> | ||
| 996 | BitBake is a task executor and scheduler that is the heart of | ||
| 997 | the OpenEmbedded build system. | ||
| 998 | </para></listitem> | ||
| 999 | <listitem><para> | ||
| 1000 | <filename>meta-poky</filename>, which is Poky-specific | ||
| 1001 | metadata. | ||
| 1002 | </para></listitem> | ||
| 1003 | <listitem><para> | ||
| 1004 | <filename>meta-yocto-bsp</filename>, which is Yocto | ||
| 1005 | Project-specific Board Support Packages (BSPs). | ||
| 1006 | </para></listitem> | ||
| 1007 | <listitem><para> | ||
| 1008 | OpenEmbedded-Core (OE-Core) metadata, which includes | ||
| 1009 | shared configurations, global variable definitions, | ||
| 1010 | shared classes, packaging, and recipes. | ||
| 1011 | Classes define the encapsulation and inheritance of build | ||
| 1012 | logic. | ||
| 1013 | Recipes are the logical units of software and images | ||
| 1014 | to be built. | ||
| 1015 | </para></listitem> | ||
| 1016 | <listitem><para> | ||
| 1017 | Documentation, which contains the Yocto Project source | ||
| 1018 | files used to make the set of user manuals. | ||
| 1019 | </para></listitem> | ||
| 1020 | </itemizedlist> | ||
| 1021 | <note> | ||
| 1022 | While Poky is a "complete" distribution specification and is | ||
| 1023 | tested and put through QA, you cannot use it as a product | ||
| 1024 | "out of the box" in its current form. | ||
| 1025 | </note> | ||
| 1026 | </para> | ||
| 1027 | |||
| 1028 | <para> | ||
| 1029 | To use the Yocto Project tools, you can use Git to clone (download) | ||
| 1030 | the Poky repository then use your local copy of the reference | ||
| 1031 | distribution to bootstrap your own distribution. | ||
| 1032 | <note> | ||
| 1033 | Poky does not contain binary files. | ||
| 1034 | It is a working example of how to build your own custom Linux distribution | ||
| 1035 | from source. | ||
| 1036 | </note> | ||
| 1037 | </para> | ||
| 1038 | |||
| 1039 | <para> | ||
| 1040 | Poky has a regular, well established, six-month release cycle | ||
| 1041 | under its own version. | ||
| 1042 | Major releases occur at the same time major releases (point | ||
| 1043 | releases) occur for the Yocto Project, which are typically in the | ||
| 1044 | Spring and Fall. | ||
| 1045 | For more information on the Yocto Project release schedule and | ||
| 1046 | cadence, see the | ||
| 1047 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-release-process'>Yocto Project Releases and the Stable Release Process</ulink>" | ||
| 1048 | chapter in the Yocto Project Reference Manual. | ||
| 1049 | </para> | ||
| 1050 | |||
| 1051 | <para> | ||
| 1052 | Much has been said about Poky being a "default configuration." | ||
| 1053 | A default configuration provides a starting image footprint. | ||
| 1054 | You can use Poky out of the box to create an image ranging from a | ||
| 1055 | shell-accessible minimal image all the way up to a Linux | ||
| 1056 | Standard Base-compliant image that uses a GNOME Mobile and | ||
| 1057 | Embedded (GMAE) based reference user interface called Sato. | ||
| 1058 | </para> | ||
| 1059 | |||
| 1060 | <para> | ||
| 1061 | One of the most powerful properties of Poky is that every aspect | ||
| 1062 | of a build is controlled by the metadata. | ||
| 1063 | You can use metadata to augment these base image types by | ||
| 1064 | adding metadata layers that extend functionality. | ||
| 1065 | These layers can provide, for example, an additional software | ||
| 1066 | stack for an image type, add a board support package (BSP) for | ||
| 1067 | additional hardware, or even create a new image type. | ||
| 1068 | </para> | ||
| 1069 | |||
| 1070 | <para> | ||
| 1071 | Metadata is loosely grouped into configuration files or package | ||
| 1072 | recipes. | ||
| 1073 | A recipe is a collection of non-executable metadata used by | ||
| 1074 | BitBake to set variables or define additional build-time tasks. | ||
| 1075 | A recipe contains fields such as the recipe description, the recipe | ||
| 1076 | version, the license of the package and the upstream source | ||
| 1077 | repository. | ||
| 1078 | A recipe might also indicate that the build process uses autotools, | ||
| 1079 | make, distutils or any other build process, in which case the basic | ||
| 1080 | functionality can be defined by the classes it inherits from | ||
| 1081 | the OE-Core layer's class definitions in | ||
| 1082 | <filename>./meta/classes</filename>. | ||
| 1083 | Within a recipe you can also define additional tasks as well as | ||
| 1084 | task prerequisites. | ||
| 1085 | Recipe syntax through BitBake also supports both | ||
| 1086 | <filename>_prepend</filename> and <filename>_append</filename> | ||
| 1087 | operators as a method of extending task functionality. | ||
| 1088 | These operators inject code into the beginning or end of a task. | ||
| 1089 | For information on these BitBake operators, see the | ||
| 1090 | "<ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending-override-style-syntax'>Appending and Prepending (Override Style Syntax)</ulink>" | ||
| 1091 | section in the BitBake User's Manual. | ||
| 1092 | </para> | ||
| 1093 | </section> | ||
| 1094 | |||
| 1095 | <section id='openembedded-build-system-workflow'> | ||
| 1096 | <title>The OpenEmbedded Build System Workflow</title> | ||
| 1097 | |||
| 1098 | <para> | ||
| 1099 | The OpenEmbedded build system uses a "workflow" to accomplish | ||
| 1100 | image and SDK generation. | ||
| 1101 | The following figure overviews that workflow: | ||
| 1102 | <imagedata fileref="figures/YP-flow-diagram.png" | ||
| 1103 | format="PNG" align='center' width="8in"/> | ||
| 1104 | Following is a brief summary of the "workflow": | ||
| 1105 | <orderedlist> | ||
| 1106 | <listitem><para> | ||
| 1107 | Developers specify architecture, policies, patches and | ||
| 1108 | configuration details. | ||
| 1109 | </para></listitem> | ||
| 1110 | <listitem><para> | ||
| 1111 | The build system fetches and downloads the source code | ||
| 1112 | from the specified location. | ||
| 1113 | The build system supports standard methods such as tarballs | ||
| 1114 | or source code repositories systems such as Git. | ||
| 1115 | </para></listitem> | ||
| 1116 | <listitem><para> | ||
| 1117 | Once downloaded, the build system extracts the sources | ||
| 1118 | into a local work area where patches are applied and | ||
| 1119 | common steps for configuring and compiling the software | ||
| 1120 | are run. | ||
| 1121 | </para></listitem> | ||
| 1122 | <listitem><para> | ||
| 1123 | The build system then installs the software into a | ||
| 1124 | temporary staging area where the binary package format you | ||
| 1125 | select (DEB, RPM, or IPK) is used to roll up the software. | ||
| 1126 | </para></listitem> | ||
| 1127 | <listitem><para> | ||
| 1128 | Different QA and sanity checks run throughout entire | ||
| 1129 | build process. | ||
| 1130 | </para></listitem> | ||
| 1131 | <listitem><para> | ||
| 1132 | After the binaries are created, the build system | ||
| 1133 | generates a binary package feed that is used to create | ||
| 1134 | the final root file image. | ||
| 1135 | </para></listitem> | ||
| 1136 | <listitem><para> | ||
| 1137 | The build system generates the file system image and a | ||
| 1138 | customized Extensible SDK (eSDSK) for application | ||
| 1139 | development in parallel. | ||
| 1140 | </para></listitem> | ||
| 1141 | </orderedlist> | ||
| 1142 | </para> | ||
| 1143 | |||
| 1144 | <para> | ||
| 1145 | For a very detailed look at this workflow, see the | ||
| 1146 | "<ulink url='&YOCTO_DOCS_GS_URL;#development-concepts'>Development Concepts</ulink>" | ||
| 1147 | section in the Yocto Project Overview and Concepts Manual. | ||
| 1148 | </para> | ||
| 1149 | </section> | ||
| 1150 | |||
| 1151 | |||
| 1152 | <section id='some-basic-terms'> | ||
| 1153 | <title>Some Basic Terms</title> | ||
| 1154 | |||
| 1155 | <para> | ||
| 1156 | It helps to understand some basic fundamental terms when | ||
| 1157 | learning the Yocto Project. | ||
| 1158 | Although a list of terms exists in the | ||
| 1159 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-terms'>Yocto Project Terms</ulink>" | ||
| 1160 | section of the Yocto Project Reference Manual, this section | ||
| 1161 | provides the definitions of some terms helpful for getting started: | ||
| 1162 | <itemizedlist> | ||
| 1163 | <listitem><para> | ||
| 1164 | <emphasis>Configuration Files:</emphasis> | ||
| 1165 | Files that hold global definitions of variables, | ||
| 1166 | user-defined variables, and hardware configuration | ||
| 1167 | information. | ||
| 1168 | These files tell the OpenEmbedded build system what to | ||
| 1169 | build and what to put into the image to support a | ||
| 1170 | particular platform. | ||
| 1171 | </para></listitem> | ||
| 1172 | <listitem><para> | ||
| 1173 | <emphasis>Extensible Software Development Kit (eSDK):</emphasis> | ||
| 1174 | A custom SDK for application developers. | ||
| 1175 | This eSDK allows developers to incorporate their library | ||
| 1176 | and programming changes back into the image to make | ||
| 1177 | their code available to other application developers. | ||
| 1178 | For information on the eSDK, see the | ||
| 1179 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and Extensible Software Development Kit (eSDK)</ulink> | ||
| 1180 | manual. | ||
| 1181 | </para></listitem> | ||
| 1182 | <listitem><para> | ||
| 1183 | <emphasis>Layer:</emphasis> | ||
| 1184 | A collection of related recipes. | ||
| 1185 | Layers allow you to consolidate related metadata to | ||
| 1186 | customize your build. | ||
| 1187 | Layers also isolate information used when building | ||
| 1188 | for multiple architectures. | ||
| 1189 | Layers are hierarchical in their ability to override | ||
| 1190 | previous specifications. | ||
| 1191 | You can include any number of available layers from the | ||
| 1192 | Yocto Project and customize the build by adding your | ||
| 1193 | layers after them. | ||
| 1194 | You can search the Layer Index for layers used within | ||
| 1195 | Yocto Project.</para> | ||
| 1196 | |||
| 1197 | <para>For more detailed information on layers, see the | ||
| 1198 | "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" | ||
| 1199 | section in the Yocto Project Development Tasks Manual. | ||
| 1200 | For a discussion specifically on BSP Layers, see the | ||
| 1201 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" | ||
| 1202 | section in the Yocto Project Board Support Packages (BSP) | ||
| 1203 | Developer's Guide. | ||
| 1204 | </para></listitem> | ||
| 1205 | <listitem><para> | ||
| 1206 | <emphasis>Metadata:</emphasis> | ||
| 1207 | A key element of the Yocto Project is the Metadata that | ||
| 1208 | is used to construct a Linux distribution and is contained | ||
| 1209 | in the files that the | ||
| 1210 | <link linkend='gs-term-openembedded-build-system'>OpenEmbedded build system</link> parses | ||
| 1211 | when building an image. | ||
| 1212 | In general, Metadata includes recipes, configuration | ||
| 1213 | files, and other information that refers to the build | ||
| 1214 | instructions themselves, as well as the data used to | ||
| 1215 | control what things get built and the effects of the | ||
| 1216 | build. | ||
| 1217 | Metadata also includes commands and data used to | ||
| 1218 | indicate what versions of software are used, from | ||
| 1219 | where they are obtained, and changes or additions to the | ||
| 1220 | software itself (patches or auxiliary files) that | ||
| 1221 | are used to fix bugs or customize the software for use | ||
| 1222 | in a particular situation. | ||
| 1223 | OpenEmbedded-Core is an important set of validated | ||
| 1224 | metadata. | ||
| 1225 | </para></listitem> | ||
| 1226 | <listitem><para id='gs-term-openembedded-build-system'> | ||
| 1227 | <emphasis>OpenEmbedded Build System:</emphasis> | ||
| 1228 | The terms "BitBake" and "build system" are sometimes | ||
| 1229 | used for the OpenEmbedded Build System.</para> | ||
| 1230 | |||
| 1231 | <para>BitBake is a task scheduler and execution engine | ||
| 1232 | that parses instructions (i.e. recipes) and configuration | ||
| 1233 | data. | ||
| 1234 | After a parsing phase, BitBake creates a dependency tree | ||
| 1235 | to order the compilation, schedules the compilation of | ||
| 1236 | the included code, and finally executes the building | ||
| 1237 | of the specified custom Linux image (distribution). | ||
| 1238 | BitBake is similar to the <filename>make</filename> | ||
| 1239 | tool.</para> | ||
| 1240 | |||
| 1241 | <para>During a build process, the build system tracks | ||
| 1242 | dependencies and performs a native or cross-compilation | ||
| 1243 | of the package. | ||
| 1244 | As a first step in a cross-build setup, the framework | ||
| 1245 | attempts to create a cross-compiler toolchain | ||
| 1246 | (i.e. Extensible SDK) suited for the target platform. | ||
| 1247 | </para></listitem> | ||
| 1248 | <listitem><para> | ||
| 1249 | <emphasis>OpenEmbedded-Core (OE-Core):</emphasis> | ||
| 1250 | OE-Core is metadata comprised of foundation recipes, | ||
| 1251 | classes, and associated files that are meant to be | ||
| 1252 | common among many different OpenEmbedded-derived systems, | ||
| 1253 | including the Yocto Project. | ||
| 1254 | OE-Core is a curated subset of an original repository | ||
| 1255 | developed by the OpenEmbedded community that has been | ||
| 1256 | pared down into a smaller, core set of continuously | ||
| 1257 | validated recipes. | ||
| 1258 | The result is a tightly controlled and quality-assured | ||
| 1259 | core set of recipes.</para> | ||
| 1260 | |||
| 1261 | <para>You can see the Metadata in the | ||
| 1262 | <filename>meta</filename> directory of the Yocto Project | ||
| 1263 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink>. | ||
| 1264 | </para></listitem> | ||
| 1265 | <listitem><para> | ||
| 1266 | <emphasis>Packages:</emphasis> | ||
| 1267 | In the context of the Yocto Project, this term refers to a | ||
| 1268 | recipe's packaged output produced by BitBake (i.e. a | ||
| 1269 | "baked recipe"). | ||
| 1270 | A package is generally the compiled binaries produced from the | ||
| 1271 | recipe's sources. | ||
| 1272 | You "bake" something by running it through BitBake.</para> | ||
| 1273 | |||
| 1274 | <para>It is worth noting that the term "package" can, | ||
| 1275 | in general, have subtle meanings. | ||
| 1276 | For example, the packages referred to in the | ||
| 1277 | "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" | ||
| 1278 | section in the Yocto Project Reference Manual are compiled | ||
| 1279 | binaries that, when installed, add functionality to your | ||
| 1280 | Linux distribution.</para> | ||
| 1281 | |||
| 1282 | <para>Another point worth noting is that historically within | ||
| 1283 | the Yocto Project, recipes were referred to as packages - thus, | ||
| 1284 | the existence of several BitBake variables that are seemingly | ||
| 1285 | mis-named, | ||
| 1286 | (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>, | ||
| 1287 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, | ||
| 1288 | and | ||
| 1289 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>). | ||
| 1290 | </para></listitem> | ||
| 1291 | <listitem><para> | ||
| 1292 | <emphasis>Poky:</emphasis> | ||
| 1293 | Poky is a reference embedded distribution and a reference | ||
| 1294 | test configuration. | ||
| 1295 | Poky provides the following: | ||
| 1296 | <itemizedlist> | ||
| 1297 | <listitem><para> | ||
| 1298 | A base-level functional distro used to illustrate | ||
| 1299 | how to customize a distribution. | ||
| 1300 | </para></listitem> | ||
| 1301 | <listitem><para> | ||
| 1302 | A means by which to test the Yocto Project | ||
| 1303 | components (i.e. Poky is used to validate | ||
| 1304 | the Yocto Project). | ||
| 1305 | </para></listitem> | ||
| 1306 | <listitem><para> | ||
| 1307 | A vehicle through which you can download | ||
| 1308 | the Yocto Project. | ||
| 1309 | </para></listitem> | ||
| 1310 | </itemizedlist> | ||
| 1311 | Poky is not a product level distro. | ||
| 1312 | Rather, it is a good starting point for customization. | ||
| 1313 | <note> | ||
| 1314 | Poky is an integration layer on top of OE-Core. | ||
| 1315 | </note> | ||
| 1316 | </para></listitem> | ||
| 1317 | <listitem><para> | ||
| 1318 | <emphasis>Recipe:</emphasis> | ||
| 1319 | The most common form of metadata. | ||
| 1320 | A recipe contains a list of settings and tasks | ||
| 1321 | (i.e. instructions) for building packages that are then | ||
| 1322 | used to build the binary image. | ||
| 1323 | A recipe describes where you get source code and which | ||
| 1324 | patches to apply. | ||
| 1325 | Recipes describe dependencies for libraries or for other | ||
| 1326 | recipes as well as configuration and compilation options. | ||
| 1327 | Related recipes are consolidated into a layer. | ||
| 1328 | </para></listitem> | ||
| 1329 | </itemizedlist> | ||
| 1330 | </para> | ||
| 1331 | </section> | ||
| 1332 | </chapter> | ||
| 1333 | <!-- | ||
| 1334 | vim: expandtab tw=80 ts=4 | ||
| 1335 | --> | ||