BitBake/UserManual: Difference between revisions

From Yocto Project
Jump to navigationJump to search
(Added a few conceptual ideas.)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Introduction ==
== 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 the bring the User Manual up to date.
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 ==
== Current TOC ==
Line 11: Line 11:
# File Download Support
# File Download Support
# The bitbake command
# The bitbake command
=== Working TOC ===
This is the new document structure I'm working with:
#Introduction
##History and Goals
##Concepts - This section will introduce the relationship between the BitBake executable and the metadata file types.  I'll introduce Layers here as well.
#BitBake Quickstart - this Chapter will include 2-3 real world examples.
## Hello World - documents the development of a Hello World BitBake example, exclusive of OE or Yocto.
## Building an OE Image - documents how to build a reference image based on an OE layer, probably core-image-minimal.
## Building a Yocto Project Image - similar to the latter, but specific to a Yocto Project image.
#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.
##Conf Files
##Recipes
##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? ==
== What to Include? ==
Line 26: Line 44:


* Using the Bitbake Env Utility
* 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 [http://www.crashcourse.ca/wiki/index.php/BitBake_fetching_and_patching here].
* Section 2.2.1 of current BitBake manual opens with discussion of "VAR_<override>_append" construct; that appears to be simply [http://lists.linuxtogo.org/pipermail/bitbake-devel/2013-January/003984.html 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:
** <tt>BB_DANGLINGAPPENDS_WARNONLY = "1"</tt>
== 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.

Latest revision as of 15:24, 15 January 2013

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

  • 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.