dev-manual: First draft of the PR Service section.
Fixes YOCTO #2684 Completed first draft. (From yocto-docs rev: c8b81e372578b1964bca4aa26d1085162115a2b0) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
parent
717c56caff
commit
ba9fc8aaf3
|
@ -1974,71 +1974,233 @@
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<section id="usingpoky-changes-prbump">
|
<section id='incrementing-a-package-revision-number'>
|
||||||
<title>Incrementing a Package Revision Number</title>
|
<title>Incrementing a Package Revision Number</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
If a committed change results in changing the package output,
|
If a committed change results in changing the package output,
|
||||||
then the value of the
|
then the value of the
|
||||||
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
|
||||||
variable needs to be increased
|
variable needs to be increased (or "bumped").
|
||||||
(or "bumped") as part of that commit.
|
Increasing <filename>PR</filename> occurs one of two ways:
|
||||||
For new recipes you should add the <filename>PR</filename>
|
<itemizedlist>
|
||||||
variable and set its initial value equal to "r0", which is the default.
|
<listitem><para>Automatically using a Package Revision
|
||||||
Even though the default value is "r0", the practice of adding it to a new recipe makes
|
Service (PR Service).</para></listitem>
|
||||||
it harder to forget to bump the variable when you make changes
|
<listitem><para>Manually incrementing the
|
||||||
to the recipe in future.
|
<filename>PR</filename> variable.</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
If you are sharing a common <filename>.inc</filename> file with multiple recipes,
|
Given that one of the challenges any build system and its
|
||||||
you can also use the
|
users face is how to maintain a package feed that is compatible
|
||||||
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
|
with existing package manager applications such as
|
||||||
variable to ensure that
|
RPM, APT, and OPKG, using an automated system is much
|
||||||
the recipes sharing the <filename>.inc</filename> file are rebuilt when the
|
preferred over a manual system.
|
||||||
<filename>.inc</filename> file itself is changed.
|
In either system, the main requirement is that version
|
||||||
The <filename>.inc</filename> file must set <filename>INC_PR</filename>
|
numbering increases in a linear fashion and that a number of
|
||||||
(initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
|
version components exist that support that linear progression.
|
||||||
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>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
When upgrading the version of a package, assuming the
|
The following two sections provide information on the PR Service
|
||||||
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
|
and on manual <filename>PR</filename> bumping.
|
||||||
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>
|
||||||
|
|
||||||
<para>
|
<section id='working-with-a-pr-service'>
|
||||||
Usually, version increases occur only to packages.
|
<title>Working With a PR Service</title>
|
||||||
However, if for some reason <filename>PV</filename> changes but does not
|
|
||||||
increase, you can increase the
|
|
||||||
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
|
|
||||||
variable (Package Epoch).
|
|
||||||
The <filename>PE</filename> variable defaults to "0".
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Version numbering strives to follow the
|
As mentioned, attempting to maintain revision numbers in the
|
||||||
<ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
|
<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
|
||||||
Debian Version Field Policy Guidelines</ulink>.
|
is error prone, inaccurate and causes problems for people
|
||||||
These guidelines define how versions are compared and what "increasing" a version means.
|
submitting recipes.
|
||||||
</para>
|
Conversely, the PR Service automatically generates
|
||||||
|
increasing numbers, particularly the revision field,
|
||||||
|
which removes the human element.
|
||||||
|
<note>
|
||||||
|
For additional information on using a PR Service, you
|
||||||
|
can see the
|
||||||
|
<ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink>
|
||||||
|
wiki page.
|
||||||
|
</note>
|
||||||
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
There are two reasons for following the previously mentioned guidelines.
|
The Yocto Project uses variables in order of
|
||||||
First, to ensure that when a developer updates and rebuilds, they get all the changes to
|
decreasing priority to facilitate revision numbering (i.e.
|
||||||
the repository and do not have to remember to rebuild any sections.
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>,
|
||||||
Second, to ensure that target users are able to upgrade their
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
|
||||||
devices using package manager commands such as <filename>opkg upgrade</filename>
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
|
||||||
(or similar commands for dpkg/apt or rpm-based systems).
|
for epoch, version and revision, respectively).
|
||||||
</para>
|
The values are highly dependent on the policies and
|
||||||
|
procedures of a given distribution and package feed.
|
||||||
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.
|
Because the OpenEmbedded build system uses "signatures",
|
||||||
</para>
|
which are unique to a given build, the build system
|
||||||
|
knows when to rebuild packages.
|
||||||
|
All the inputs into a given task are represented by a
|
||||||
|
signature, which can trigger a rebuild when different.
|
||||||
|
Thus, the build system itself does not rely on the
|
||||||
|
<filename>PR</filename> numbers to trigger a rebuild.
|
||||||
|
The signatures, however, can be used to generate
|
||||||
|
<filename>PR</filename> values.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The PR Service works with both
|
||||||
|
<filename>OEBasic</filename> and
|
||||||
|
<filename>OEBasicHash</filename> generators.
|
||||||
|
The value of <filename>PR</filename> bumps when the
|
||||||
|
checksum changes and the different generator mechanisms
|
||||||
|
change signatures under different circumstances.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
As implemented, the build system includes values from
|
||||||
|
the PR Service into the <filename>PR</filename> field as
|
||||||
|
an addition using the form "<filename>.x</filename>" so
|
||||||
|
<filename>r0</filename> becomes <filename>r0.1</filename>,
|
||||||
|
<filename>r0.2</filename> and so forth.
|
||||||
|
This scheme allows existing <filename>PR</filename> values
|
||||||
|
to be used for whatever reasons, which include manual
|
||||||
|
<filename>PR</filename> bumps should it be necessary.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
By default, there is no server that runs the PR Service.
|
||||||
|
Thus, the packages generated are just "self consistent".
|
||||||
|
The build system adds and removes packages and
|
||||||
|
there are no guarantees about upgrade paths.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The simplest form for a PR Service is for it to exist
|
||||||
|
for a single host development system that builds the
|
||||||
|
package feed (building system).
|
||||||
|
For this scenario, you can enable the PR Service by adding
|
||||||
|
the following to your <filename>local.conf</filename>
|
||||||
|
file in the
|
||||||
|
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
PRSERV_HOST = "localhost:0"
|
||||||
|
</literallayout>
|
||||||
|
Once the service is started, packages will automatically
|
||||||
|
get increasing <filename>PR</filename> values and
|
||||||
|
BitBake will take care of starting and stopping the server.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If you have a more complex setup where multiple host
|
||||||
|
development systems work against a common, shared package
|
||||||
|
feed, you have a single PR Service running and it is
|
||||||
|
connected to each building system.
|
||||||
|
For this scenario, you need to start the PR Service using
|
||||||
|
the <filename>bitbake-prserv</filename> command:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
bitbake-prserve ‐‐host <ip> ‐‐port <port> ‐‐start
|
||||||
|
</literallayout>
|
||||||
|
In addition to hand-starting the service, you need to
|
||||||
|
update the <filename>local.conf</filename> file of each
|
||||||
|
building system as described earlier so each system
|
||||||
|
points to the server and port.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
It is also recommended you use build history, which adds
|
||||||
|
some sanity checks to package versions, in conjunction with
|
||||||
|
the server that is running the PR Service.
|
||||||
|
To enable build history, add the following to each building
|
||||||
|
system's <filename>local.conf</filename> file:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
# It is recommended to activate "buildhistory" for testing the PR service
|
||||||
|
INHERIT += "buildhistory"
|
||||||
|
BUILDHISTORY_COMMIT = "1"
|
||||||
|
</literallayout>
|
||||||
|
For information on build history, see the
|
||||||
|
"<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
|
||||||
|
section in the Yocto Project Reference Manual.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
The OpenEmbedded build system does not maintain
|
||||||
|
<filename>PR</filename> information as part of the
|
||||||
|
shared state (sstate) packages.
|
||||||
|
If you maintain an sstate feed, its expected that either
|
||||||
|
all your building systems that contribute to the sstate
|
||||||
|
feed use a shared PR Service, or you do not run a PR
|
||||||
|
Service on any of your building systems.
|
||||||
|
Having some systems use a PR Service while others do
|
||||||
|
not leads to obvious problems.
|
||||||
|
</note>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id='manually-bumping-pr'>
|
||||||
|
<title>Manually Bumping PR</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If a committed change results in changing the package output,
|
||||||
|
then the value of the PR variable needs to be increased
|
||||||
|
(or "bumped") as part of that commit.
|
||||||
|
For new recipes you should add the <filename>PR</filename>
|
||||||
|
variable and set its initial value equal to "r0", which is the default.
|
||||||
|
Even though the default value is "r0", the practice of adding it to a new recipe makes
|
||||||
|
it harder to forget to bump the variable when you make changes
|
||||||
|
to the recipe in future.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If you are sharing a common <filename>.inc</filename> file with multiple recipes,
|
||||||
|
you can also use the
|
||||||
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#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='&YOCTO_DOCS_REF_URL;#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='&YOCTO_DOCS_REF_URL;#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>
|
</section>
|
||||||
|
|
||||||
<section id="usingpoky-configuring-DISTRO_PN_ALIAS">
|
<section id="usingpoky-configuring-DISTRO_PN_ALIAS">
|
||||||
|
|
Loading…
Reference in New Issue