Poky Reference Manual: Completed editing pass of Chapter 3.
I completed the editing pass of this chapter by doing sections 3.3.3 on. Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
This commit is contained in:
parent
890a794e38
commit
09ef6a4e13
|
@ -109,6 +109,7 @@ inherit autotools gettext
|
|||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-extend-addpkg-makefile'>
|
||||
<title>Makefile-Based Package</title>
|
||||
<para>
|
||||
|
@ -160,6 +161,7 @@ do_install () {
|
|||
</programlisting>
|
||||
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-extend-addpkg-files'>
|
||||
<title>Controlling Package Content</title>
|
||||
<para>
|
||||
|
@ -348,8 +350,7 @@ RRECOMMENDS_task-custom-tools = "\
|
|||
</section>
|
||||
|
||||
<section id='usingpoky-extend-customimage-imagefeatures'>
|
||||
<title>Customising Images Using Custom <glossterm>
|
||||
<link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm></title>
|
||||
<title>Customising Images Using Custom IMAGE_FEATURES</title>
|
||||
<para>
|
||||
Ultimately users might want to add extra image "features" as used by Poky with the
|
||||
<glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
|
||||
|
@ -401,14 +402,14 @@ DISTRO_EXTRA_RDEPENDS += "strace"
|
|||
dependencies - it only rebuilds the specified package.
|
||||
</para>
|
||||
<programlisting>
|
||||
bitbake -c clean task-boot task-base task-poky
|
||||
bitbake poky-image-sato
|
||||
$ bitbake -c clean task-boot task-base task-poky
|
||||
$ bitbake poky-image-sato
|
||||
</programlisting>
|
||||
</section>
|
||||
|
||||
</section>
|
||||
|
||||
<section id="platdev-newmachine">
|
||||
<section id="platdev-newmachine">
|
||||
<title>Porting Poky to a New Machine</title>
|
||||
<para>
|
||||
Adding a new machine to Poky is a straightforward process.
|
||||
|
@ -486,20 +487,21 @@ COMPATIBLE_MACHINE = '(qemux86|qemumips)'
|
|||
<para>
|
||||
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
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
Sane defaults should be used in most cases, but if customisation is
|
||||
Reasonable defaults are used in most cases, but if customization is
|
||||
necessary you need to create a <filename>machconfig</filename> file
|
||||
under <filename>meta/packages/formfactor/files/MACHINENAME/</filename>
|
||||
under <filename>meta/packages/formfactor/files/MACHINENAME/</filename>,
|
||||
where <literal>MACHINENAME</literal> is the name for which this infomation
|
||||
applies. For information about the settings available and the defaults, please see
|
||||
<filename>meta/packages/formfactor/files/config</filename>. Below is one
|
||||
example for qemuarm:
|
||||
applies.
|
||||
For information about the settings available and the defaults, see
|
||||
<filename>meta/packages/formfactor/files/config</filename>.
|
||||
Following is an example for qemuarm:
|
||||
</para>
|
||||
<programlisting>
|
||||
HAVE_TOUCHSCREEN=1
|
||||
|
@ -514,43 +516,42 @@ DISPLAY_DPI=150
|
|||
DISPLAY_SUBPIXEL_ORDER=vrgb
|
||||
</programlisting>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-changes'>
|
||||
<section id="usingpoky-changes">
|
||||
<title>Making and Maintaining Changes</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
Because Poky offers extreme configurability and fliexibility, we recognize that people will want
|
||||
to extend, configure or optimise Poky for their specific uses.
|
||||
To best keep pace with future Poky changes we recommend you make controlled changes to Poky.
|
||||
</para>
|
||||
<para>
|
||||
Poky supports the idea of <link
|
||||
linkend='usingpoky-changes-layers'>"layers"</link> 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.
|
||||
Poky supports the idea of <link linkend='usingpoky-changes-layers'>"layers"</link>.
|
||||
If you use layers properly you can ease future upgrades and allow segregation
|
||||
between the Poky core and a given developer's changes.
|
||||
The following section provides more advice on managing changes to Poky.
|
||||
</para>
|
||||
|
||||
<section id="usingpoky-changes-layers">
|
||||
<title>Bitbake Layers</title>
|
||||
|
||||
<para>
|
||||
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
|
||||
layers which provides a way to handle this extension in a fully
|
||||
Often, people want to extend Poky either by adding packages
|
||||
or by overriding files contained within Poky to add their own
|
||||
functionality.
|
||||
Bitbake has a powerful mechanism called
|
||||
"layers", which provides a way to handle this extension in a fully
|
||||
supported and non-invasive fashion.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The Poky tree includes several additional layers which demonstrate
|
||||
this functionality, such as meta-emenlow and meta-extras.
|
||||
The meta-emenlow layer is an example layer enabled by default. The meta-extras
|
||||
repostory is not enabled by default but enabling any layer is as easy as adding
|
||||
the layers path to the BBLAYERS variable in your bblayers.conf. this is how
|
||||
meta-extras are enabled in Poky builds:
|
||||
The Poky tree includes several additional layers such as meta-emenlow and meta-extras
|
||||
that demonstrate this functionality.
|
||||
The meta-emenlow layer is an example layer that by default is enabled.
|
||||
However, the meta-extras repostory is not enabled by default.
|
||||
It is easy though to enable any layer.
|
||||
You simply add the layer's path to the
|
||||
<glossterm><link linkend='var-BBLAYERS'>BBLAYERS</link></glossterm> variable in your
|
||||
<filename>bblayers.conf</filename> file.
|
||||
The following example shows how to enable meta-extras in the Poky build:
|
||||
</para>
|
||||
<para>
|
||||
<literallayout class='monospaced'>LCONF_VERSION = "1"
|
||||
|
@ -565,15 +566,14 @@ BBLAYERS = " \
|
|||
</para>
|
||||
|
||||
<para>
|
||||
Bitbake parses the conf/layer.conf of each of the layers in BBLAYERS
|
||||
to add the recipes, classes and configuration contained within the layer to Poky.
|
||||
Bitbake parses each <filename>conf/layer.conf</filename> file for each layer in BBLAYERS
|
||||
and adds the recipes, classes and configuration contained within the layer to Poky.
|
||||
To create your own layer, independent of the main Poky repository,
|
||||
you need only create a directory with a conf/layer.conf file and
|
||||
add the directory to your bblayers.conf.
|
||||
simply create a directory with a <filename>conf/layer.conf</filename> file and
|
||||
add the directory to your <filename>bblayers.conf</filename> file.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The meta-emenlow/conf/layer.conf demonstrates the required syntax:
|
||||
The <filename>meta-emenlow/conf/layer.conf</filename> file demonstrates the required syntax:
|
||||
<literallayout class='monospaced'># We have a conf and classes directory, add to BBPATH
|
||||
BBPATH := "${BBPATH}:${LAYERDIR}"
|
||||
|
||||
|
@ -586,66 +586,74 @@ BBFILE_PATTERN_emenlow := "^${LAYERDIR}/"
|
|||
BBFILE_PRIORITY_emenlow = "6"
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
As can be seen, the layers recipes are added to
|
||||
<glossterm> <link linkend='var-BBFILES'>BBFILES</link></glossterm>. The
|
||||
BBFILE_COLLECTIONS variable is then appended to with the
|
||||
layer name. The BBFILE_PATTERN variable is immediately expanded
|
||||
with a regular expression used to match files from BBFILES into
|
||||
In the previous example, the recipes for the layers are added to
|
||||
<glossterm> <link linkend='var-BBFILES'>BBFILES</link></glossterm>.
|
||||
The <glossterm><link linkend='var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link></glossterm>
|
||||
variable is then appended with the layer name.
|
||||
The <glossterm><link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN</link></glossterm> variable
|
||||
immediately expands with a regular expression used to match files from BBFILES into
|
||||
a particular layer, in this case by using the base pathname.
|
||||
The BBFILE_PRIORITY variable then assigns different
|
||||
priorities to the files in different layers. This is useful
|
||||
in situations where the same package might appear in multiple
|
||||
layers and allows you to choose which layer should 'win'.
|
||||
Note the use of <glossterm><link linkend='var-LAYERDIR'>
|
||||
LAYERDIR</link></glossterm> with the immediate expansion operator.
|
||||
<glossterm><link linkend='var-LAYERDIR'>LAYERDIR</link></glossterm>
|
||||
expands to the directory of the current layer and
|
||||
requires use of the immediate expansion operator so that Bitbake
|
||||
does not lazily expand the variable when it's parsing a
|
||||
different directory.
|
||||
The <glossterm><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></glossterm> variable
|
||||
then assigns different priorities to the files in different layers.
|
||||
This technique useful in situations where the same package might appear in multiple
|
||||
layers and allows you to choose what layer should take precedence.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Additional bbclass and configuration files can be locationed by
|
||||
bitbake through the addition to 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. It is therefore recommended
|
||||
that you use unique bbclass and configuration file names in your
|
||||
Note the use of the <glossterm><link linkend='var-LAYERDIR'>LAYERDIR</link></glossterm>
|
||||
variable with the immediate expansion operator.
|
||||
The LAYERDIR variable expands to the directory of the current layer and
|
||||
requires the immediate expansion operator so that Bitbake does not wait to expand the variable
|
||||
when it's parsing a different directory.
|
||||
</para>
|
||||
<para>
|
||||
Bitbake can locate where other bbclass and configuration files are applied through
|
||||
the <glossterm><link linkend='var-BBPATH'>BBPATH</link></glossterm>
|
||||
environment variable.
|
||||
For these cases, Bitake uses the first file with the matching name found in BBPATH.
|
||||
This is similar to the way the PATH variable is used for binaries.
|
||||
We recommend, therefore, that you use unique bbclass and configuration file names in your
|
||||
custom layer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The recommended approach for custom layers is to store them in a
|
||||
git repository of the format meta-prvt-XXXX and have this repository
|
||||
cloned alongside the other meta directories in the Poky tree.
|
||||
This way you can keep your Poky tree and it's configuration entirely
|
||||
We also recommend the following:
|
||||
<itemizedlist>
|
||||
<listitem><para>Store custom layers in a git repository that uses the
|
||||
meta-prvt-XXXX format.</para></listitem>
|
||||
<listitem><para>Clone the repository alongside other meta directories in the Poky
|
||||
tree.</para></listitem>
|
||||
</itemizedlist>
|
||||
Following these recommendations keeps your Poky tree and its configuration entirely
|
||||
inside POKYBASE.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-changes-commits'>
|
||||
<section id="usingpoky-changes-commits">
|
||||
<title>Committing Changes</title>
|
||||
|
||||
<para>
|
||||
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 followed for the
|
||||
Poky core.
|
||||
revision control system.
|
||||
Because some simple practices can significantly improve usability, policy for committing changes
|
||||
is important.
|
||||
Following are suggestions for committing changes to the Poky core:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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:
|
||||
It helps to use a consistent documentation style when committing changes.
|
||||
We have found the following style works well.
|
||||
<itemizedlist>
|
||||
<listitem><para>The first line of the commit summarizes the change and begins with the
|
||||
name of the affected package or packages.
|
||||
However, not all changes apply to specific packages.
|
||||
Consequently, the prefix could also be a machine name or class name for
|
||||
example.</para></listitem>
|
||||
<listitem><para>The second part of the commit (if needed) is a longer more detailed
|
||||
description of the changes. Placing a blank line between the first and second parts
|
||||
helps with readability.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<para>
|
||||
Following is an example commit:
|
||||
</para>
|
||||
|
||||
<literallayout class='monospaced'>
|
||||
bitbake/data.py: Add emit_func() and generate_dependencies() functions
|
||||
|
||||
|
@ -657,111 +665,121 @@ BBFILE_PRIORITY_emenlow = "6"
|
|||
</literallayout>
|
||||
|
||||
<para>
|
||||
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.
|
||||
All commits should be self-contained such that they leave the
|
||||
metadata in a consistent state that builds both before and after the
|
||||
commit is made.
|
||||
Besides being a good policy to follow, this helps ensure the autobuilder test results
|
||||
are valid.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-changes-prbump'>
|
||||
<section id="usingpoky-changes-prbump">
|
||||
<title>Package Revision Incrementing</title>
|
||||
|
||||
<para>
|
||||
If a committed change will result in changing the package output
|
||||
If a committed change results in changing the package output
|
||||
then the value of the <glossterm><link linkend='var-PR'>PR</link>
|
||||
</glossterm> variable needs to be increased (commonly referred to
|
||||
as 'bumped') as part of that commit. Only integer values are used
|
||||
and <glossterm><link linkend='var-PR'>PR</link></glossterm> =
|
||||
"r0" should be added into new recipes as, while this is the
|
||||
default value, not having the variable defined in a recipe makes
|
||||
it easy to miss incrementing it when updating the recipe.
|
||||
When upgrading the version of a package (<glossterm><link
|
||||
linkend='var-PV'>PV</link></glossterm>), the <glossterm><link
|
||||
linkend='var-PR'>PR</link></glossterm> variable should be reset to "r0".
|
||||
</glossterm> variable needs to be increased ('bumped') as part of that commit.
|
||||
This means that for new recipes you be sure to add the PR variable and set its initial value
|
||||
equal to "r0".
|
||||
Not initially defining PR makes makes it easy to miss when you bump a package.
|
||||
Note that you can only use integer values for the PR variable.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The aim is that the package version will only ever increase. If
|
||||
for some reason <glossterm><link linkend='var-PV'>PV</link></glossterm>
|
||||
will change and but not increase, the <glossterm><link
|
||||
linkend='var-PE'>PE</link></glossterm> (Package Epoch) can
|
||||
be increased (it defaults to '0'). The version numbers aim to
|
||||
follow the <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
|
||||
Debian Version Field Policy Guidelines</ulink> which define how
|
||||
versions are compared and hence what "increasing" means.
|
||||
When upgrading the version of a package the (<glossterm><link
|
||||
linkend='var-PV'>PV</link></glossterm>) and PR variables should be reset to "r0".
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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
|
||||
Usually a package version only increases.
|
||||
However, if for some reason PV changes but does not increase, you can increase the
|
||||
<glossterm><link linkend='var-PE'>PE</link></glossterm> variable (Package Epoch).
|
||||
The PE variable defaults to '0'.
|
||||
</para>
|
||||
<para>
|
||||
Version numbering strives to follow the
|
||||
<ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
|
||||
Debian Version Field Policy Guidelines</ulink>.
|
||||
These guidelines define how versions are compared and what "increasing" a version means.
|
||||
</para>
|
||||
<para>
|
||||
There are two reasons for following these guidelines.
|
||||
First, 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 <command>
|
||||
opkg upgrade</command> commands (or similar for
|
||||
dpkg/apt or rpm based systems). The aim is to ensure Poky has
|
||||
upgradable packages in all cases.
|
||||
Second, to ensure that target users are able to upgrade their
|
||||
devices using package manager commands such as <filename>
|
||||
opkg upgrade</filename> (or similar commands for dpkg/apt or rpm-based systems).
|
||||
</para>
|
||||
<para>
|
||||
The goal is to ensure Poky has upgradable packages in all cases.
|
||||
</para>
|
||||
</section>
|
||||
<section id='usingpoky-changes-collaborate'>
|
||||
|
||||
<section id="usingpoky-changes-collaborate">
|
||||
<title>Using Poky in a Team Environment</title>
|
||||
|
||||
<para>
|
||||
It may not be immediately clear how Poky can work in a team environment,
|
||||
or scale to a large team of developers. The specifics of any situation
|
||||
will determine the best solution and poky offers immense flexibility in
|
||||
that aspect but there are some practises that experience has shown to work
|
||||
well.
|
||||
It may not be immediately clear how you can use Poky in a team environment,
|
||||
or scale it for a large team of developers.
|
||||
The specifics of any situation determine the best solution.
|
||||
Granted that Poky offers immense flexibility regarding this, practices do exist
|
||||
that experience has shown work well.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The core component of any development effort with Poky is often an
|
||||
automated build testing framework and image generation process. This
|
||||
can be used to check that the metadata is buildable, highlight when
|
||||
commits break the builds and provide up to date images allowing people
|
||||
to test the end result and use them as a base platform for further
|
||||
development. Experience shows that buildbot is a good fit for this role
|
||||
and that it works well to configure it to make two types of build -
|
||||
incremental builds and 'from scratch'/full builds. The incremental builds
|
||||
can be tied to a commit hook which triggers them each time a commit is
|
||||
made to the metadata and are a useful acid test of whether a given commit
|
||||
breaks the build in some serious way. They catch lots of simple errors
|
||||
and whilst they won't catch 100% of failures, the tests are fast so
|
||||
developers can get feedback on their changes quickly. The full builds
|
||||
are builds that build everything from the ground up and test everything.
|
||||
They usually happen at preset times such as at night when the machine
|
||||
load isn't high from the incremental builds.
|
||||
<ulink url='http://autobuilder.pokylinux.org:8010'>poky autobuilder</ulink>
|
||||
is an example implementation with buildbot.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Most teams have pieces of software undergoing active development. It is of
|
||||
significant benefit to put these under control of a source control system
|
||||
compatible with Poky such as git or svn. The autobuilder can then be set to
|
||||
pull the latest revisions of these packages so the latest commits get tested
|
||||
by the builds allowing any issues to be highlighted quickly. Poky easily
|
||||
supports configurations where there is both a stable known good revision
|
||||
and a floating revision to test. Poky can also only take changes from specific
|
||||
source control branches giving another way it can be used to track/test only
|
||||
specified changes.
|
||||
automated build testing framework and an image generation process.
|
||||
You can use these core components to check that the metadata is buildable,
|
||||
highlight when commits break the builds, and provide up-to-date images that
|
||||
allow people to test the end result and use it as a base platform for further
|
||||
development.
|
||||
Experience shows that buildbot is a good fit for this role.
|
||||
What works well is to configure buildbot to make two types of builds:
|
||||
incremental and full (from scratch).
|
||||
See <ulink url='http://autobuilder.pokylinux.org:8010'>poky autobuilder</ulink>
|
||||
for an example implementation that uses buildbot.
|
||||
</para>
|
||||
<para>
|
||||
Perhaps the hardest part of setting this up is the policy that surrounds
|
||||
the different source control systems, be them software projects or the Poky
|
||||
metadata itself. The circumstances will be different in each case but this is
|
||||
one of Poky's advantages - the system itself doesn't force any particular policy
|
||||
unlike a lot of build systems, allowing the best policy to be chosen for the
|
||||
circumstances.
|
||||
You can tie incremental builds to a commit hook that triggers the build
|
||||
each time a commit is made to the metadata.
|
||||
This practice results in useful acid tests that determine whether a given commit
|
||||
breaks the build in some serious way.
|
||||
Associating a build to a commit can catch a lot of simple errors.
|
||||
Furthermore, the tests are fast so developers can get quick feedback on changes.
|
||||
</para>
|
||||
<para>
|
||||
Full builds build and test everything from the ground up.
|
||||
They usually happen at preset times like during the night when the machine
|
||||
load is low.
|
||||
</para>
|
||||
<para>
|
||||
Most teams have many pieces of software undergoing active development at any given time.
|
||||
You can derive large benefits by putting these pieces under the control of a source
|
||||
control system that is compatible with Poky (i.e. git or svn).
|
||||
You can then set the autobuilder to pull the latest revisions of the packages
|
||||
and test the latest commits by the builds.
|
||||
This practice quickly highlights issues.
|
||||
Poky easily supports testing configurations that use both a stable known good revision
|
||||
and a floating revision.
|
||||
Poky can also take just the changes from specific source control branches.
|
||||
This capability allows you to track and test specific changes.
|
||||
</para>
|
||||
<para>
|
||||
Perhaps the hardest part of setting this up is defining the software project or
|
||||
Poky metadata policies that surround the different source control systems.
|
||||
Of course circumstances will be different in each case.
|
||||
However, this situation reveals one of Poky's advantages - the system itself does not
|
||||
force any particular policy on users, unlike a lot of build systems.
|
||||
The system allows the best policy to be chosen for the given circumstances.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-changes-updatingimages'>
|
||||
<section id="usingpoky-changes-updatingimages">
|
||||
<title>Updating Existing Images</title>
|
||||
|
||||
<para>
|
||||
Often, rather than reflashing a new image you might wish to install updated
|
||||
packages into an existing running system. This can be done by sharing the <filename class="directory">tmp/deploy/ipk/</filename> directory through a web server and then on the device, changing <filename>/etc/opkg/base-feeds.conf</filename> to point at this server, for example by adding:
|
||||
packages into an existing running system.
|
||||
You can do this by first sharing the
|
||||
<filename class="directory">tmp/deploy/ipk/</filename> directory
|
||||
through a web server and then by changing <filename>/etc/opkg/base-feeds.conf</filename>
|
||||
to point at the shared server.
|
||||
Following is an example:
|
||||
</para>
|
||||
<literallayout class='monospaced'>
|
||||
src/gz all http://www.mysite.com/somedir/deploy/ipk/all
|
||||
|
@ -770,41 +788,33 @@ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard</literal
|
|||
</section>
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-modifing-packages'>
|
||||
<section id="usingpoky-modifing-packages">
|
||||
<title>Modifying Package Source Code</title>
|
||||
|
||||
<para>
|
||||
Poky is usually used to build software rather than modifying
|
||||
it. However, there are ways Poky can be used to modify software.
|
||||
Although Poky is usually used to build software, you can use it to modify software.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
During building, the sources are available in <glossterm><link
|
||||
linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory.
|
||||
Where exactly this is depends on the type of package and the
|
||||
architecture of target device. For a standard recipe not
|
||||
related to <glossterm><link
|
||||
linkend='var-MACHINE'>MACHINE</link></glossterm> it will be
|
||||
During building, source is available in the
|
||||
<glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory.
|
||||
The actual location depends on the type of package and the architecture of the target device.
|
||||
For a standard recipe not related to
|
||||
<glossterm><link linkend='var-MACHINE'>MACHINE</link></glossterm> the location is
|
||||
<filename>tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/</filename>.
|
||||
Target device dependent packages use <glossterm><link
|
||||
linkend='var-MACHINE'>MACHINE
|
||||
</link></glossterm>
|
||||
instead of <glossterm><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH
|
||||
</link></glossterm>
|
||||
For target device-dependent packages you should use the MACHINE variable instead of
|
||||
<glossterm><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></glossterm>
|
||||
in the directory name.
|
||||
</para>
|
||||
|
||||
<tip>
|
||||
<para>
|
||||
Check the package recipe sets the <glossterm><link
|
||||
linkend='var-S'>S</link></glossterm> variable to something
|
||||
Be sure the package recipe sets the
|
||||
<glossterm><link linkend='var-S'>S</link></glossterm> variable to something
|
||||
other than standard <filename>WORKDIR/PN-PV/</filename> value.
|
||||
</para>
|
||||
</tip>
|
||||
<para>
|
||||
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:
|
||||
After building a package, you can modify the package source code without problems.
|
||||
The easiest way to test your changes is by calling the "compile" task as shown in the
|
||||
following example:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
|
@ -812,184 +822,179 @@ bitbake -c compile -f NAME_OF_PACKAGE
|
|||
</programlisting>
|
||||
|
||||
<para>
|
||||
"-f" or "--force" is used to force re-execution of the specified task.
|
||||
Other tasks may also be called this way. But note that all the modifications
|
||||
in <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>
|
||||
are gone once you executes "-c clean" for a package.
|
||||
The "-f" or "--force" option forces re-execution of the specified task.
|
||||
You can call other tasks this way as well.
|
||||
But note that all the modifications in
|
||||
<glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>
|
||||
are gone once you execute "-c clean" for a package.
|
||||
</para>
|
||||
|
||||
<section id='usingpoky-modifying-packages-quilt'>
|
||||
<section id="usingpoky-modifying-packages-quilt">
|
||||
<title>Modifying Package Source Code with quilt</title>
|
||||
|
||||
<para>
|
||||
By default Poky uses <ulink
|
||||
url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink>
|
||||
to manage patches in <function>do_patch</function> task.
|
||||
It is a powerful tool which can be used to track all
|
||||
modifications done to package sources.
|
||||
By default Poky uses <ulink url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink>
|
||||
to manage patches in the <filename>do_patch</filename> task.
|
||||
This is a powerful tool that you can use to track all modifications to package sources.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Before modifying source code it is important to
|
||||
notify quilt so it will track changes into new patch
|
||||
file:
|
||||
Before modifying source code, it is important to notify quilt so it can track the changes
|
||||
into the new patch file:
|
||||
|
||||
<programlisting>
|
||||
quilt new NAME-OF-PATCH.patch
|
||||
</programlisting>
|
||||
|
||||
Then add all files which will be modified into that
|
||||
patch:
|
||||
After notifying quilt, add all modified files into that patch:
|
||||
<programlisting>
|
||||
quilt add file1 file2 file3
|
||||
</programlisting>
|
||||
|
||||
Now start editing. At the end quilt needs to be used
|
||||
to generate final patch which will contain all
|
||||
modifications:
|
||||
You can now start editing.
|
||||
Once you are done editing, you need to use quilt to generate the final patch that
|
||||
will contain all your modifications.
|
||||
<programlisting>
|
||||
quilt refresh
|
||||
</programlisting>
|
||||
|
||||
The resulting patch file can be found in the
|
||||
You can find the resulting patch file in the
|
||||
<filename class="directory">patches/</filename> subdirectory of the source
|
||||
(<glossterm><link linkend='var-S'>S</link></glossterm>) directory. For future builds it
|
||||
should be copied into
|
||||
Poky metadata and added into <glossterm><link
|
||||
linkend='var-SRC_URI'>SRC_URI</link></glossterm> of a recipe:
|
||||
(<glossterm><link linkend='var-S'>S</link></glossterm>) directory.
|
||||
For future builds you should copy the patch into Poky metadata and add it into the
|
||||
<glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm> of a recipe.
|
||||
Here is an example:
|
||||
<programlisting>
|
||||
SRC_URI += "file://NAME-OF-PATCH.patch"
|
||||
</programlisting>
|
||||
|
||||
This also requires a bump of <glossterm><link
|
||||
linkend='var-PR'>PR</link></glossterm> value in the same recipe as we changed resulting packages.
|
||||
Finally, don't forget to 'bump' the
|
||||
<glossterm><link linkend='var-PR'>PR</link></glossterm> value in the same recipe.
|
||||
The resulting packages have changed.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
</section>
|
||||
<section id='usingpoky-configuring-LIC_FILES_CHKSUM'>
|
||||
<title>Track license change</title>
|
||||
|
||||
<section id="usingpoky-configuring-LIC_FILES_CHKSUM">
|
||||
<title>Track License Change</title>
|
||||
<para>
|
||||
The license of one upstream project may change in the future, and Poky provides
|
||||
one mechanism to track such license change - <glossterm>
|
||||
<link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> variable.
|
||||
The license of an upstream project might change in the future.
|
||||
To address this situation, Poky uses the
|
||||
<glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> variable
|
||||
to track license changes.
|
||||
</para>
|
||||
|
||||
<section id='usingpoky-specifying-LIC_FILES_CHKSUM'>
|
||||
<title>Specifying the LIC_FILES_CHKSUM variable </title>
|
||||
|
||||
<section id="usingpoky-specifying-LIC_FILES_CHKSUM">
|
||||
<title>Specifying the LIC_FILES_CHKSUM Variable </title>
|
||||
<para>
|
||||
The <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm>
|
||||
variable contains checksums of the license text in the recipe source code.
|
||||
Poky uses this to track changes in the license text of the source code files.
|
||||
Following is an example of LIC_FILES_CHKSUM:
|
||||
</para>
|
||||
<programlisting>
|
||||
LIC_FILES_CHKSUM = "file://COPYING; md5=xxxx \
|
||||
file://licfile1.txt; beginline=5; endline=29;md5=yyyy \
|
||||
file://licfile2.txt; endline=50;md5=zzzz \
|
||||
..."
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
<glossterm><link linkend='var-S'>S</link></glossterm> is the default directory
|
||||
for searching files listed in <glossterm><link linkend='var-LIC_FILES_CHKSUM'>
|
||||
LIC_FILES_CHKSUM</link></glossterm>. Relative path could be used too:
|
||||
Poky uses the <glossterm><link linkend='var-S'>S</link></glossterm> variable as the
|
||||
default directory used when searching files listed in LIC_FILES_CHKSUM.
|
||||
The previous example employs the default directory.
|
||||
</para>
|
||||
<para>
|
||||
You can also use relative paths as shown in the following example:
|
||||
</para>
|
||||
|
||||
<programlisting>
|
||||
LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
|
||||
md5=bb14ed3c4cda583abc85401304b5cd4e"
|
||||
LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
The first line locates a file in <glossterm><link linkend='var-S'>
|
||||
S</link></glossterm>/src/ls.c, and the second line refers to a file in
|
||||
In this example the first line locates a file in
|
||||
<glossterm><link linkend='var-S'>S</link></glossterm><filename>/src/ls.c</filename>.
|
||||
The second line refers to a file in
|
||||
<glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>, which is the parent
|
||||
of <glossterm><link linkend='var-S'>S</link></glossterm>
|
||||
of <glossterm><link linkend='var-S'>S</link></glossterm>.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
<section id='usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax'>
|
||||
<title>Explanation of syntax</title>
|
||||
|
||||
<section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
|
||||
<title>Explanation of Syntax</title>
|
||||
<para>
|
||||
This parameter lists all the important files containing the text
|
||||
of licenses for the
|
||||
source code. It is also possible to specify on which line the license text
|
||||
starts and on which line it ends within that file using the "beginline" and
|
||||
"endline" parameters. If the "beginline" parameter is not specified then license
|
||||
text begins from the 1st line is assumed. Similarly if "endline" parameter is
|
||||
not specified then the license text ends at the last line in the file is
|
||||
assumed. So if a file contains only licensing information, then there is no need
|
||||
to specify "beginline" and "endline" parameters.
|
||||
As mentioned in the previous section the LIC_FILES_CHKSUM variable lists all the
|
||||
important files that contain the license text for the source code.
|
||||
Using this variable you can specify the line on which the license text starts and ends
|
||||
by supplyiing "beginline" and "endline" parameters.
|
||||
If you do not use the "beginline" parameter then it is assumed that the text begins on the
|
||||
first line of the file.
|
||||
Similarly, if you do not use the "endline" parameter it is assumed that the license text
|
||||
ends as the last line of the file.
|
||||
</para>
|
||||
<para>
|
||||
The "md5" parameter stores the md5 checksum of the license text. So if
|
||||
the license text changes in any way from a file, then its md5 sum will differ and will not
|
||||
match with the previously stored md5 checksum. This mismatch will trigger build
|
||||
failure, notifying developer about the license text md5 mismatch, and allowing
|
||||
the developer to review the license text changes. Also note that if md5 checksum
|
||||
is not matched while building, the correct md5 checksum is printed in the build
|
||||
log which can be easily copied to .bb file.
|
||||
The "md5" parameter stores the md5 checksum of the license text.
|
||||
If the license text changes in any way as compared to this parameter
|
||||
then a mis-match occurs.
|
||||
This mismatch triggers a build failure and notifies the developer.
|
||||
Notification allows the developer to review and address the license text changes.
|
||||
Also note that if a mis-match occurs during the build, the correct md5
|
||||
checksum is placed in the build log, which can be easily copied to a .bb file.
|
||||
</para>
|
||||
<para>
|
||||
There is no limit on how many files can be specified on this parameter. But generally every
|
||||
project would need specifying of just one or two files for license tracking.
|
||||
Many projects would have a "COPYING" file which will store all the
|
||||
license information for all the source code files. If the "COPYING" file
|
||||
is valid then tracking only that file would be enough.
|
||||
There is no limit to how many files you can specify using the LIC_FILES_CHKSUM variable.
|
||||
Generally, however, every project requires a few specifications for license tracking.
|
||||
Many projects have a "COPYING" file that stores the license information for all the source
|
||||
code files.
|
||||
This practice allow you to just track the "COPYING" file as long as it is kept up to date.
|
||||
</para>
|
||||
<tip>
|
||||
<para>
|
||||
1. If you specify empty or invalid "md5" parameter; then while building
|
||||
the package, bitbake will give md5 not matched error, and also show the correct
|
||||
"md5" parameter value both on the screen and in the build log
|
||||
</para>
|
||||
<para>
|
||||
2. If the whole file contains only license text, then there is no need to
|
||||
specify "beginline" and "endline" parameters.
|
||||
</para>
|
||||
If you specify an empty or invalid "md5" parameter, bitback returns an md5 mis-match
|
||||
error and displays the correct "md5" parameter value during the build. The correct parameter
|
||||
is also captured in the build log.
|
||||
</tip>
|
||||
<tip>
|
||||
If the whole file contains only license text, you do not need to use the "beginline" and
|
||||
"endline" parameters.
|
||||
</tip>
|
||||
</section>
|
||||
</section>
|
||||
<section id='usingpoky-configuring-DISTRO_PN_ALIAS'>
|
||||
<title>Handle package name alias</title>
|
||||
|
||||
<section id="usingpoky-configuring-DISTRO_PN_ALIAS">
|
||||
<title>Handling Package Name Alias</title>
|
||||
<para>
|
||||
Poky implements a distro_check task which automatically connects to major distributions
|
||||
and checks whether they contains same package. Sometimes the same package has different
|
||||
names in different distributions, which results in a mismatch from distro_check task
|
||||
This can be solved by defining per distro recipe name alias -
|
||||
<glossterm><link linkend='var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</link></glossterm>
|
||||
Sometimes a package name you are using might exist under an alias or as a similarly named
|
||||
package in a different distribution.
|
||||
Poky implements a distro_check task that automatically connects to major distributions
|
||||
and checks for these situations.
|
||||
If the package exists under a different name in a different distribution you get a
|
||||
distro_check mismatch.
|
||||
You can resolve this problem by defining a per-distro recipe name alias using the
|
||||
<glossterm><link linkend='var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</link></glossterm> variable.
|
||||
</para>
|
||||
|
||||
<section id='usingpoky-specifying-DISTRO_PN_ALIAS'>
|
||||
<title>Specifying the DISTRO_PN_ALIAS variable </title>
|
||||
|
||||
<section id="usingpoky-specifying-DISTRO_PN_ALIAS">
|
||||
<title>Specifying the DISTRO_PN_ALIAS Variable</title>
|
||||
<para>
|
||||
Following is an example that shows how you specify the DISTRO_PN_ALIAS variable:
|
||||
<programlisting>
|
||||
DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
|
||||
distro2=package_name_alias2 \
|
||||
distro3=package_name_alias3 \
|
||||
..."
|
||||
</programlisting>
|
||||
<para>
|
||||
Use space as the delimiter if there're multiple distro aliases
|
||||
</para>
|
||||
<tip>
|
||||
<para>
|
||||
The current code can check if the src package for a recipe exists in the latest
|
||||
releases of these distributions automatically.
|
||||
If you have more than one distribution alias separate them with a space.
|
||||
Note that Poky currently automatically checks the Fedora, OpenSuSE, Debian, Ubuntu,
|
||||
and Mandriva distributions for source package recipes without having to specify them
|
||||
using the DISTRO_PN_ALIAS variable.
|
||||
For example, the following command generates a report that lists the Linux distributions
|
||||
that include the sources for each of the Poky recipes.
|
||||
<literallayout class='monospaced'>
|
||||
$ bitbake world -f -c distro_check
|
||||
</literallayout>
|
||||
The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
|
||||
file.
|
||||
</para>
|
||||
<programlisting>
|
||||
Fedora, OpenSuSE, Debian, Ubuntu, Mandriva
|
||||
</programlisting>
|
||||
<para>
|
||||
For example, this command will generate a report, listing which linux distros include the
|
||||
sources for each of the poky recipe.
|
||||
</para>
|
||||
<programlisting>
|
||||
bitbake world -f -c distro_check
|
||||
</programlisting>
|
||||
<para>
|
||||
The results will be stored in the build/tmp/log/distro_check-${DATETIME}.results file.
|
||||
</para>
|
||||
</tip>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
|
|
Loading…
Reference in New Issue