documentation/dev-manual: Re-org of topics
Several topics in the "Common Tasks" chapter really fit better in the "Newbie" chapter. I moved these sections out. I also combined information from the section on submitting changes from the "Common Tasks" and the "Newbie" chapter to live in the "Newbie" chapter only. (From yocto-docs rev: 90fa8c125e545c57a5a994dd59715b73c5c4882f) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
Richard Purdie
parent
25f74b31b7
commit
2cae64b94f
|
|
@ -1774,6 +1774,91 @@ so that there are some definite steps on how to do this. I need more detail her
|
|||
</section>
|
||||
</section>
|
||||
|
||||
<section id="usingpoky-changes-updatingimages">
|
||||
<title>Updating Existing Images</title>
|
||||
|
||||
<para>
|
||||
Often, rather than re-flashing a new image, you might wish to install updated
|
||||
packages into an existing running system.
|
||||
You can do this by first sharing the <filename>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:
|
||||
<literallayout class='monospaced'>
|
||||
$ src/gz all http://www.mysite.com/somedir/deploy/ipk/all
|
||||
$ src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
|
||||
$ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="usingpoky-changes-prbump">
|
||||
<title>Incrementing a Package Revision Number</title>
|
||||
|
||||
<para>
|
||||
If a committed change results in changing the package output,
|
||||
then the value of the
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PR'>PR</ulink></filename>
|
||||
variable needs to be increased
|
||||
(or "bumped") as part of that commit.
|
||||
This means that for new recipes you must be sure to add the <filename>PR</filename>
|
||||
variable and set its initial value equal to "r0".
|
||||
Failing to define <filename>PR</filename> makes it easy to miss when you bump a package.
|
||||
Note that you can only use integer values following the "r" in the
|
||||
<filename>PR</filename> variable.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you are sharing a common <filename>.inc</filename> file with multiple recipes,
|
||||
you can also use the
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-INC_PR'>INC_PR</ulink></filename>
|
||||
variable to ensure that
|
||||
the recipes sharing the <filename>.inc</filename> file are rebuilt when the
|
||||
<filename>.inc</filename> file itself is changed.
|
||||
The <filename>.inc</filename> file must set <filename>INC_PR</filename>
|
||||
(initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
|
||||
to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
|
||||
If the <filename>.inc</filename> file is changed then its
|
||||
<filename>INC_PR</filename> should be incremented.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When upgrading the version of a package, assuming the
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PV'>PV</ulink></filename>
|
||||
changes, the <filename>PR</filename> variable should be reset to "r0"
|
||||
(or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Usually, version increases occur only to packages.
|
||||
However, if for some reason <filename>PV</filename> changes but does not
|
||||
increase, you can increase the
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PE'>PE</ulink></filename>
|
||||
variable (Package Epoch).
|
||||
The <filename>PE</filename> 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 the previously mentioned guidelines.
|
||||
First, to ensure that when a developer updates and rebuilds, they get all the changes to
|
||||
the repository and do not have to remember to rebuild any sections.
|
||||
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 the Yocto Project has packages that can be upgraded in all cases.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="usingpoky-configuring-DISTRO_PN_ALIAS">
|
||||
<title>Handling a Package Name Alias</title>
|
||||
<para>
|
||||
|
|
@ -1870,218 +1955,6 @@ so that there are some definite steps on how to do this. I need more detail her
|
|||
build directory that is different than the source directory.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="usingpoky-changes">
|
||||
<title>Making and Maintaining Changes</title>
|
||||
<para>
|
||||
Because the Yocto Project is extremely configurable and flexible,
|
||||
we recognize that developers will want
|
||||
to extend, configure or optimize it for their specific uses.
|
||||
To best keep pace with future Yocto Project changes,
|
||||
we recommend you make controlled changes to the Yocto Project.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The Yocto Project supports a "<link linkend='understanding-and-creating-layers'>layers</link>" concept.
|
||||
If you use layers properly, you can ease future upgrades and allow segregation
|
||||
between the Yocto Project core and a given developer's changes.
|
||||
The following section provides more advice on managing changes to the Yocto Project.
|
||||
</para>
|
||||
|
||||
<section id="usingpoky-changes-commits">
|
||||
<title>Committing Changes</title>
|
||||
|
||||
<para>
|
||||
Modifications to the Yocto Project are often managed under some kind of source
|
||||
revision control system.
|
||||
Because some simple practices can significantly improve usability, policy for committing changes
|
||||
is important.
|
||||
It helps to use a consistent documentation style when committing changes.
|
||||
The Yocto Project development team has found the following practices work 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.</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:
|
||||
<literallayout class='monospaced'>
|
||||
bitbake/data.py: Add emit_func() and generate_dependencies() functions
|
||||
|
||||
These functions allow generation of dependency data between functions and
|
||||
variables allowing moves to be made towards generating checksums and allowing
|
||||
use of the dependency information in other parts of BitBake.
|
||||
|
||||
Signed-off-by: Richard Purdie richard.purdie@linuxfoundation.org
|
||||
</literallayout>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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 practice to follow, it helps ensure autobuilder test results
|
||||
are valid.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="usingpoky-changes-prbump">
|
||||
<title>Package Revision Incrementing</title>
|
||||
|
||||
<para>
|
||||
If a committed change results in changing the package output,
|
||||
then the value of the
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PR'>PR</ulink></filename>
|
||||
variable needs to be increased
|
||||
(or "bumped") as part of that commit.
|
||||
This means that for new recipes you must be sure to add the <filename>PR</filename>
|
||||
variable and set its initial value equal to "r0".
|
||||
Failing to define <filename>PR</filename> makes it easy to miss when you bump a package.
|
||||
Note that you can only use integer values following the "r" in the
|
||||
<filename>PR</filename> variable.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you are sharing a common <filename>.inc</filename> file with multiple recipes,
|
||||
you can also use the
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-INC_PR'>INC_PR</ulink></filename>
|
||||
variable to ensure that
|
||||
the recipes sharing the <filename>.inc</filename> file are rebuilt when the
|
||||
<filename>.inc</filename> file itself is changed.
|
||||
The <filename>.inc</filename> file must set <filename>INC_PR</filename>
|
||||
(initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
|
||||
to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
|
||||
If the <filename>.inc</filename> file is changed then its
|
||||
<filename>INC_PR</filename> should be incremented.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When upgrading the version of a package, assuming the
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PV'>PV</ulink></filename>
|
||||
changes, the <filename>PR</filename> variable should be reset to "r0"
|
||||
(or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Usually, version increases occur only to packages.
|
||||
However, if for some reason <filename>PV</filename> changes but does not
|
||||
increase, you can increase the
|
||||
<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PE'>PE</ulink></filename>
|
||||
variable (Package Epoch).
|
||||
The <filename>PE</filename> 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 the previously mentioned guidelines.
|
||||
First, to ensure that when a developer updates and rebuilds, they get all the changes to
|
||||
the repository and do not have to remember to rebuild any sections.
|
||||
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 the Yocto Project has packages that can be upgraded in all cases.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="usingpoky-changes-collaborate">
|
||||
<title>Using The Yocto Project in a Team Environment</title>
|
||||
|
||||
<para>
|
||||
It might not be immediately clear how you can use the Yocto Project in a team environment,
|
||||
or scale it for a large team of developers.
|
||||
The specifics of any situation determine the best solution.
|
||||
Granted that the Yocto Project offers immense flexibility regarding this, practices do exist
|
||||
that experience has shown work well.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The core component of any development effort with the Yocto Project is often an
|
||||
automated build and testing framework along with an image generation process.
|
||||
You can use these core components to check that the metadata can be built,
|
||||
highlight when commits break the build, and provide up-to-date images that
|
||||
allow developers 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.yoctoproject.org:8010/'>the buildbot for the
|
||||
Yocto Project</ulink> for an example implementation that uses buildbot.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
These types of builds usually happen at predetermined 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 the Yocto Project (i.e. Git or Subversion (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.
|
||||
The Yocto Project easily supports testing configurations that use both a
|
||||
stable known good revision and a floating revision.
|
||||
The Yocto Project 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
|
||||
the Yocto Project metadata policies that surround the different source control systems.
|
||||
Of course circumstances will be different in each case.
|
||||
However, this situation reveals one of the Yocto Project's advantages -
|
||||
the system itself does not
|
||||
force any particular policy on users, unlike a lot of build systems.
|
||||
The system allows the best policies to be chosen for the given circumstances.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id="usingpoky-changes-updatingimages">
|
||||
<title>Updating Existing Images</title>
|
||||
|
||||
<para>
|
||||
Often, rather than re-flashing a new image, you might wish to install updated
|
||||
packages into an existing running system.
|
||||
You can do this by first sharing the <filename>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:
|
||||
<literallayout class='monospaced'>
|
||||
$ src/gz all http://www.mysite.com/somedir/deploy/ipk/all
|
||||
$ src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
|
||||
$ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
</chapter>
|
||||
|
||||
<!--
|
||||
|
|
|
|||
|
|
@ -53,6 +53,70 @@
|
|||
</para>
|
||||
</section>
|
||||
|
||||
<section id="usingpoky-changes-collaborate">
|
||||
<title>Using The Yocto Project in a Team Environment</title>
|
||||
|
||||
<para>
|
||||
It might not be immediately clear how you can use the Yocto Project in a team environment,
|
||||
or scale it for a large team of developers.
|
||||
The specifics of any situation determine the best solution.
|
||||
Granted that the Yocto Project offers immense flexibility regarding this, practices do exist
|
||||
that experience has shown work well.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The core component of any development effort with the Yocto Project is often an
|
||||
automated build and testing framework along with an image generation process.
|
||||
You can use these core components to check that the metadata can be built,
|
||||
highlight when commits break the build, and provide up-to-date images that
|
||||
allow developers 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.yoctoproject.org:8010/'>the buildbot for the
|
||||
Yocto Project</ulink> for an example implementation that uses buildbot.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
These types of builds usually happen at predetermined 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 the Yocto Project (i.e. Git or Subversion (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.
|
||||
The Yocto Project easily supports testing configurations that use both a
|
||||
stable known good revision and a floating revision.
|
||||
The Yocto Project 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
|
||||
the Yocto Project metadata policies that surround the different source control systems.
|
||||
Of course circumstances will be different in each case.
|
||||
However, this situation reveals one of the Yocto Project's advantages -
|
||||
the system itself does not
|
||||
force any particular policy on users, unlike a lot of build systems.
|
||||
The system allows the best policies to be chosen for the given circumstances.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='yocto-project-repositories'>
|
||||
<title>Yocto Project Source Repositories</title>
|
||||
|
||||
|
|
@ -797,6 +861,8 @@
|
|||
|
||||
<para>
|
||||
Contributions to the Yocto Project are very welcome.
|
||||
Because the Yocto Project is extremely configurable and flexible, we recognize that developers
|
||||
will want to extend, configure or optimize it for their specific uses.
|
||||
You should send patches to the appropriate Yocto Project mailing list to get them
|
||||
in front of the Yocto Project Maintainer.
|
||||
For a list of the Yocto Project mailing lists, see the
|
||||
|
|
@ -866,7 +932,10 @@
|
|||
<para>
|
||||
In a collaborative environment, it is necessary to have some sort of standard
|
||||
or method through which you submit changes.
|
||||
Otherwise, things could get quite chaotic.
|
||||
Otherwise, things could get quite chaotic.
|
||||
One general practice to follow is to make small, controlled changes to the
|
||||
Yocto Project.
|
||||
Keeping changes small and isolated lets you best keep pace with future Yocto Project changes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
|
|
|||
Loading…
Reference in New Issue