BitBake/UserManual

Introduction

The current BitBake User Manual, as of Dec. 31, 2012 is quite out dated. This page serves a a place to collect ideas for revisions that are required to bring the User Manual up to date.

Current TOC

The chapter layout of the BitBake User Manual is currently:

1. Introduction
2. Metadata
3. File Download Support
4. The bitbake command

Working TOC

This is the new document structure I'm working with:

1. Introduction
   1. History and Goals
   2. Concepts - This section will introduce the relationship between the BitBake executable and the metadata file types. I'll introduce Layers here as well.
2. BitBake Quickstart - this Chapter will include 2-3 real world examples.
   1. Hello World - documents the development of a Hello World BitBake example, exclusive of OE or Yocto.
   2. Building an OE Image - documents how to build a reference image based on an OE layer, probably core-image-minimal.
   3. Building a Yocto Project Image - similar to the latter, but specific to a Yocto Project image.
3. Metadata - this chapter will build on what already exists in the manual, adding context, more examples, etc. Variable will be organized into applicable metadata file types.
   1. Conf Files
   2. Recipes
   3. Classes

I'll likely delete the File Download Support Chapter, and The BitBake Command chapters and integrate that information into the latter chapters.

What to Include?

• As pointed out by rday, the patch function is inherent to oe-core, while the fetch function is inherent to bitbake. So can one be discussed without the other?

• Concepts:
  • Explain each step in the bitbake process thoroughly.
  • Provide context to commands. The why, not just the how.

Lessons to Include

• The Bitbaked Hello World
  • Build on the work by Eren Turkey and the original tutorial at the OpenEmbedded wiki.

• Using the Bitbake Env Utility

Random observations by rday

• While BitBake fetcher supports numerous fetching protocols, only half of them are even used so I would simply ignore the unused ones. I made a bunch of notes on fetching here.

• Section 2.2.1 of current BitBake manual opens with discussion of "VAR_<override>_append" construct; that appears to be simply broken and unused. I would ignore it. The other form, "VAR_append_<override>" is, of course, used massively and should be documented.

• Variables that probably deserve more coverage:
  • BB_DANGLINGAPPENDS_WARNONLY = "1"

Deprecated/weird/dead stuff

• All "proto=" should now be replaced with "protocol=" in SRC_URI, although the old form is still allowed but deprecated.
• All "pnum=" should now be replaced with "striplevel=" in SRC_URI for patches.
• Current BitBake manual shows a "this=ignored" parm for patches; total mystery what that means, nothing uses it, Chris Larson has no idea what it's for. Ignore it.

Add Hob Documentation

With Hob getting better and better, it would seem appropriate to include a chapter in the Bitbake User Manual documenting it.