summaryrefslogtreecommitdiffstats
path: root/handbook
diff options
context:
space:
mode:
authorZhai Edwin <edwin.zhai@intel.com>2010-09-09 16:23:01 +0800
committerRichard Purdie <rpurdie@linux.intel.com>2010-09-10 12:20:44 +0100
commit8c7e1aced86cbef5f7856bb59c2190bb408dd024 (patch)
tree27720d67eccdc586709168bdd03a27bd57ba3184 /handbook
parent2beaecb35133aa9006a8b3ce79b4dee202fc35b2 (diff)
downloadopenembedded-core-contrib-8c7e1aced86cbef5f7856bb59c2190bb408dd024.tar.gz
handbook: review and modify CH4 (BSP) and Appendix B
Besides basic corrections, also add .bbappend to bsp introduction and update bitbake help to match latest output Signed-off-by: Zhai Edwin <edwin.zhai@intel.com> Signed-off-by: Dexuan Cui <dexuan.cui@intel.com> Signed-off-by: Kevin Tian <kevin.tian@intel.com>
Diffstat (limited to 'handbook')
-rw-r--r--handbook/bsp.xml60
-rw-r--r--handbook/ref-bitbake.xml35
2 files changed, 66 insertions, 29 deletions
diff --git a/handbook/bsp.xml b/handbook/bsp.xml
index 37dd166749..b897f0691d 100644
--- a/handbook/bsp.xml
+++ b/handbook/bsp.xml
@@ -28,18 +28,18 @@
OpenEmbedded build systems. It is intended that this information can be
used by other systems besides Poky/OpenEmbedded and that it will be simple
to extract information and convert to other formats if required. The format
- descriped can be directly accepted as a layer by Poky using its standard
- layers mechanism but its important to recognise that the BSP captures all
- the hardware specific details in one place in a standard format which is
+ described can be directly accepted as a layer by Poky using its standard
+ layers mechanism, but it is important to recognise that the BSP captures all
+ the hardware specific details in one place in a standard format, which is
useful for any person wishing to use the hardware platform regardless of
the build system in use.
</para>
<para>
- The BSP specification does not include a build system or other tooling,
+ The BSP specification does not include a build system or other tools,
it is concerned with the hardware specific components only. At the end
distribution point the BSP may be shipped combined with a build system
- and other tools but it is important to maintain the distinction that these
+ and other tools, but it is important to maintain the distinction that these
are separate components which may just be combined in certain end products.
</para>
@@ -47,7 +47,7 @@
<title>Example Filesystem Layout</title>
<para>
- The BSP consists of a file structure inside a base directory, meta-bsp in this example where "bsp" is a placeholder for the machine or platform name. Examples of some files that it could contain are:
+ The BSP consists of a file structure inside a base directory, meta-bsp in this example, where "bsp" is a placeholder for the machine or platform name. Examples of some files that it could contain are:
</para>
<para>
@@ -108,9 +108,9 @@ BBPATH := "${BBPATH}${LAYERDIR}"
# We have a packages directory, add to BBFILES
BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb"
-BBFILE_COLLECTIONS += "meta-bsp"
-BBFILE_PATTERN_meta-bsp := "^${LAYERDIR}/"
-BBFILE_PRIORITY_meta-bsp = "5"
+BBFILE_COLLECTIONS += "bsp"
+BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
+BBFILE_PRIORITY_bsp = "5"
</programlisting>
</para>
@@ -129,7 +129,7 @@ BBFILE_PRIORITY_meta-bsp = "5"
<para>
The machine files bind together all the information contained elsewhere
- in the BSP into a format that Poky/OpenEmbedded can understand it in. If
+ in the BSP into a format that Poky/OpenEmbedded can understand. If
the BSP supports multiple machines, multiple machine configuration files
can be present. These filenames correspond to the values users set the
MACHINE variable to.
@@ -139,7 +139,7 @@ BBFILE_PRIORITY_meta-bsp = "5"
These files would define things like which kernel package to use
(PREFERRED_PROVIDER of virtual/kernel), which hardware drivers to
include in different types of images, any special software components
- that are needed, any bootloader information and also any special image
+ that are needed, any bootloader information, and also any special image
format requirements.
</para>
@@ -165,7 +165,7 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
</para>
<para>
which defines a new package architecture called "core2" and uses the
- optimisation flags specified which are carefully chosen to give best
+ optimization flags specified, which are carefully chosen to give best
performance on atom cpus.
</para>
<para>
@@ -182,7 +182,7 @@ TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
<para>
These files make up the definition of a kernel to use with this
- hardware. In this case its a complete self contained kernel with its own
+ hardware. In this case it is a complete self contained kernel with its own
configuration and patches but kernels can be shared between many
machines as well. Taking some specific example files:
</para>
@@ -197,7 +197,7 @@ meta-bsp/packages/linux/linux-bsp_2.6.50.bb
be a release tarball, some git repository or source included in
the directory within the BSP itself. It then contains information about which
patches to apply and how to configure and build it. It can reuse the main
- Poky kernel build class meaning the definitions here can remain very simple.
+ Poky kernel build class, so the definitions here can remain very simple.
</para>
<para>
<programlisting>
@@ -229,7 +229,7 @@ meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
<para>
This area includes other pieces of software which the hardware may need for best
operation. These are just examples of the kind of things that may be
- encountered. The are standard .bb file recipes in the usual Poky format
+ encountered. The are standard .bb file recipes in the usual Poky format,
so for examples, see standard Poky recipes. The source can be included directly,
referred to in source control systems or release tarballs of external software projects.
</para>
@@ -269,6 +269,36 @@ meta-bsp/packages/image-creator/image-creator-native_0.1.bb
</para>
</section>
+ <section id='bs-filelayout-bbappend'>
+ <title>Append BSP specific information to existing recipes</title>
+
+ <para>
+ Say you have a recipe like pointercal which has machine specific information in it,
+ and then you have your new bsp code in a layer. Before .bbappend extension is
+ introduced, you have to copy the whole pointercal recipe and files into your layer,
+ and then add the single file for your machine which is ugly.
+
+ .bbappend makes above work much easier, to allow bsp specific information merged
+ with original recipe easily. When bitbake finds any X.bbappend files, they will be
+ included after bitbake loads X.bb but before finalise and any anonymous methods run.
+ This allows bsp layer to poke around and do whatever it might want to customise
+ the original recipe.
+
+ .bbappend is expected to include below two lines in the head (which may be changed
+ in the future):
+ </para>
+
+ <programlisting>
+THISDIR := "${@os.path.dirname(bb.data.getVar('FILE', d, True))}"
+FILESPATH =. "${@base_set_filespath(["${THISDIR}/${PN}"], d)}:"
+ </programlisting>
+
+ <para>
+ Then bsp could add machine specific config files in layer directory, which will be
+ added by bitbake. You could look at meta-emenlow/packages/formfactor as example
+ </para>
+ </section>
+
<section id='bsp-filelayout-prebuilds'>
<title>Prebuild Data (meta-bsp/prebuilds/*)</title>
diff --git a/handbook/ref-bitbake.xml b/handbook/ref-bitbake.xml
index ddf3c760f2..eaf9467950 100644
--- a/handbook/ref-bitbake.xml
+++ b/handbook/ref-bitbake.xml
@@ -6,7 +6,7 @@
<title>Reference: Bitbake</title>
<para>
- Bitbake a program written in Python which interprets the metadata
+ Bitbake is a program written in Python that interprets the metadata
that makes up Poky. At some point, people wonder what actually happens
when you type <command>bitbake poky-image-sato</command>. This section
aims to give an overview of what happens behind the scenes from a
@@ -16,7 +16,7 @@
<para>
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
+ real knowledge of what the tasks it is 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.
@@ -26,7 +26,7 @@
<title>Parsing</title>
<para>
- The first thing BitBake does is work out its configuration by
+ The first thing BitBake does is that work out its configuration by
looking for a file called <filename>bitbake.conf</filename>.
Bitbake searches through the <varname>BBPATH</varname> environment
variable looking for a <filename class="directory">conf/</filename>
@@ -117,7 +117,7 @@
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
- <filename>task-oh.bb</filename> and <filename>task-base.bb</filename>
+ <filename>task-base.bb</filename>
which in turn would lead to packages like <application>Contacts</application>,
<application>Dates</application>, <application>BusyBox</application>
and these in turn depend on glibc and the toolchain.
@@ -154,7 +154,8 @@
"1" makes it likely the package will be used.
<glossterm><link
linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm> overrides
- any default preference. <glossterm><link
+ any <glossterm><link
+ linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>. <glossterm><link
linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>
is often used to mark more
experimental new versions of packages until they've undergone sufficient
@@ -176,7 +177,7 @@
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 <ulink url='http://bitbake.berlios.de/manual/'>
+ about these in the <ulink url='http://bitbake.berlios.de/manual/'>
BitBake manual</ulink>. At a basic level it is sufficient to know
that BitBake uses the <glossterm><link
linkend='var-DEPENDS'>DEPENDS</link></glossterm> and
@@ -196,7 +197,7 @@
order. The build now starts with BitBake forking off threads up to
the limit set in the <glossterm><link
linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm> variable
- as long there are tasks ready to run, i.e. tasks with all their
+ as long as there are tasks ready to run, i.e. tasks with all their
dependencies met.
</para>
@@ -271,9 +272,9 @@ Options:
target that failed, and those that depend on it,
cannot be remade, the other dependencies of these
targets can be processed all the same.
+ -a, --tryaltconfigs continue with builds by trying to use alternative
+ providers where possible.
-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
@@ -286,6 +287,9 @@ Options:
-D, --debug Increase the debug level. You can specify this more
than once.
-n, --dry-run don't execute, just go through the motions
+ -S, --dump-signatures
+ don't execute, just dump out the signature
+ construction information
-p, --parse-only quit after parsing the BB files (developers only)
-d, --disable-psyco disable using the psyco just-in-time compiler (not
recommended)
@@ -294,13 +298,16 @@ Options:
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
+ -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
+ Assume these dependencies don't exist and are already
+ provided (equivalent to ASSUME_PROVIDED). Useful to
+ make dependency graphs 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</screen>
+ -P, --profile profile the command and print a report
+ -u UI, --ui=UI userinterface to use
+ --revisions-changed Set the exit code depending on whether upstream
+ floating revisions have changed or not</screen>
</section>