[gnome-continuous-yocto/gnomeostree-3.28-rocko: 5635/8267] dev-manual, ref-manual: Edits to the "Incrementing Binary Package" section.
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-continuous-yocto/gnomeostree-3.28-rocko: 5635/8267] dev-manual, ref-manual: Edits to the "Incrementing Binary Package" section.
- Date: Sun, 17 Dec 2017 03:43:00 +0000 (UTC)
commit 94467d5087ca3b13e7baac670af107550701b333
Author: Scott Rifenbark <srifenbark gmail com>
Date: Tue Apr 11 11:55:38 2017 -0700
dev-manual, ref-manual: Edits to the "Incrementing Binary Package" section.
Fixes [YOCTO #10995]
I applied some revisions to the related sections for incrementing
a binary package version and revision sections. Mainly clarified
terminology and pulled the sections into one single section head.
I also cleaned up referencing to all these sections throughout the
YP manual set (i.e. the ref-manual).
(From yocto-docs rev: 7deda18dd496cc383c5de71a10f2b11b1ca0688f)
Signed-off-by: Scott Rifenbark <srifenbark gmail com>
Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>
.../dev-manual/dev-manual-common-tasks.xml | 284 ++++++++++++--------
documentation/ref-manual/ref-variables.xml | 4 +-
documentation/ref-manual/technical-details.xml | 2 +-
3 files changed, 173 insertions(+), 117 deletions(-)
---
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml
b/documentation/dev-manual/dev-manual-common-tasks.xml
index 28a97f1..d2bd56d 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -7792,10 +7792,7 @@
<link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link>
</para></listitem>
<listitem><para>
- <link linkend='incrementing-a-package-version-number'>Incrementing a package version
number</link>
- </para></listitem>
- <listitem><para>
- <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision
number</link>
+ <link linkend='incrementing-a-binary-package-version'>Incrementing a binary package
version</link>
</para></listitem>
<listitem><para>
<link linkend='handling-optional-module-packaging'>Handling optional module
packaging</link>
@@ -7853,43 +7850,102 @@
</para>
</section>
- <section id='incrementing-a-package-version-number'>
- <title>Incrementing a Package Version Number</title>
+ <section id='incrementing-a-binary-package-version'>
+ <title>Incrementing a Package Version</title>
+
+ <para>
+ The scheme the OpenEmbedded build system uses for binary
+ package versioning is a bit involved.
+ This section provides some background on how binary package
+ versioning is accomplished and presents some of the services,
+ variables, and terminology involved.
+ </para>
+
+ <para>
+ In order to understand binary package versioning, you need
+ to consider the following:
+ <itemizedlist>
+ <listitem><para>
+ Binary Package: The binary package that is eventually
+ built and installed into an image.
+ </para></listitem>
+ <listitem><para>
+ Binary Package Version: The binary package version
+ is composed of two components - a version and a
+ revision.
+ <note>
+ Technically, the "epoch" (i.e.
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>)
+ is involved but this discussion for the most part
+ ignores <filename>PE</filename>.
+ </note>
+ The version and revision are taken from the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
+ variables, respectively.
+ </para></listitem>
+ <listitem><para>
+ <filename>PV</filename>: The recipe version, which is
+ not to be confused with the binary package version.
+ </para></listitem>
+ <listitem><para>
+ <filename>PR</filename>: The recipe revision.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>:
+ The Version string of the binary package.
+ The OpenEmbedded build system uses this string
+ to help define the value of <filename>PV</filename>.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='https://wiki.yoctoproject.org/wiki/PR_Service'>PR Service</ulink>:
+ A network-based service that helps automate keeping
+ package feeds compatible with existing package
+ manager applications such as RPM, APT, and OPKG.
+ </para></listitem>
+ </itemizedlist>
+ </para>
<para>
- If a committed change results in changing the package output,
- then the value of the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
- variable needs to be increased (or "bumped").
- Increasing <filename>PR</filename> occurs one of two ways:
+ Whenever the binary package output changes, the binary package
+ version must change.
+ Changing the binary package version is accomplished by changing
+ or "bumping" the <filename>PR</filename> and/or
+ <filename>PV</filename> values.
+ Increasing these values occurs one of two ways:
<itemizedlist>
<listitem><para>Automatically using a Package Revision
Service (PR Service).
</para></listitem>
<listitem><para>Manually incrementing the
- <filename>PR</filename> variable.
+ <filename>PR</filename> and/or
+ <filename>PV</filename> variables.
</para></listitem>
</itemizedlist>
</para>
<para>
- Given that one of the challenges any build system and its
- users face is how to maintain a package feed that is compatible
- with existing package manager applications such as
- RPM, APT, and OPKG, using an automated system is much
- preferred over a manual system.
- In either system, the main requirement is that package version
- numbering increases in a linear fashion and that a number of
- version components exist that support that linear progression.
+ Given a primary challenge of any build system and its users
+ is how to maintain a package feed that is compatible with
+ existing package manager applications such as RPM, APT, and
+ OPKG, using an automated system is much preferred over a
+ manual system.
+ In either system, the main requirement is that binary package
+ version numbering increases in a linear fashion and that a
+ number of version components exist that support that linear
+ progression.
For information on how to ensure package revisioning remains
linear, see the
- "<link linkend='incrementing-a-package-revision-number'>Incrementing a Package Revision
Number</link>"
+ "<link linkend='incrementing-a-binary-package-revision-number'>Incrementing a Binary Package
Revision Number</link>"
section.
</para>
<para>
- The following two sections provide information on the PR Service
- and on manual <filename>PR</filename> bumping.
+ The following three sections provide related information on the
+ PR Service, the manual method for "bumping"
+ <filename>PR</filename> and/or <filename>PV</filename>, and
+ on how to ensure binary package revisioning remains linear.
</para>
<section id='working-with-a-pr-service'>
@@ -7930,9 +7986,10 @@
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.
+ <filename>PR</filename>, <filename>PV</filename>, and
+ <filename>PE</filename> numbers to trigger a rebuild.
The signatures, however, can be used to generate
- <filename>PR</filename> values.
+ these values.
</para>
<para>
@@ -7977,7 +8034,7 @@
</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.
+ BitBake takes care of starting and stopping the server.
</para>
<para>
@@ -7998,8 +8055,8 @@
<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.
+ some sanity checks to binary 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'>
@@ -8013,18 +8070,23 @@
</para>
<note>
- <para>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.</para>
- <para>For more information on shared state, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
- section in the Yocto Project Reference Manual.</para>
+ <para>
+ 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.
+ </para>
+
+ <para>
+ For more information on shared state, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
+ section in the Yocto Project Reference Manual.
+ </para>
</note>
</section>
@@ -8033,7 +8095,7 @@
<para>
The alternative to setting up a PR Service is to manually
- bump the
+ "bump" the
<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
variable.
</para>
@@ -8067,7 +8129,7 @@
</para>
<para>
- When upgrading the version of a package, assuming the
+ When upgrading the version of a binary 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
@@ -8075,7 +8137,7 @@
</para>
<para>
- Usually, version increases occur only to packages.
+ Usually, version increases occur only to binary 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>
@@ -8084,95 +8146,89 @@
</para>
<para>
- Version numbering strives to follow the
+ Binary package 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>
</section>
- </section>
- <section id='incrementing-a-package-revision-number'>
- <title>Incrementing a Package Revision Number</title>
+ <section id='incrementing-a-binary-package-revision-number'>
+ <title>Incrementing a Binary Package Revision Number</title>
- <para>
- When fetching a repository, BitBake uses the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
- variable to determine the specific revision from which to
- build.
- You set the <filename>SRCREV</filename> variable to
- <ulink url='&YOCTO_DOCS_REF_URL;#var-AUTOREV'><filename>AUTOREV</filename></ulink>
- to cause the OpenEmbedded build system to automatically use the
- latest revision of the package:
+ <para>
+ When fetching a repository, BitBake uses the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
+ variable to determine the specific revision from which to
+ build.
+ You set the <filename>SRCREV</filename> variable to
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-AUTOREV'><filename>AUTOREV</filename></ulink>
+ to cause the OpenEmbedded build system to automatically use the
+ latest revision of the package:
<literallayout class='monospaced'>
SRCREV = "${AUTOREV}"
</literallayout>
- </para>
+ </para>
- <para>
- Furthermore, the <filename>SRCPV</filename> variable returns
- the version string of the current package.
- This string is used to help define the value of
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>.
- If your recipe needs to define the package version (i.e.
- <filename>PV</filename>),
- they do this with the help of <filename>SRCPV</filename>.
- Here is an example:
- <literallayout class='monospaced'>
+ <para>
+ Furthermore, you need to reference <filename>SRCPV</filename>
+ in <filename>PV</filename> in order to automatically update
+ the binary package version whenever the revision of the
+ source code changes.
+ Here is an example:
+ <literallayout class='monospaced'>
PV = "1.0+git${SRCPV}"
- </literallayout>
- You can use <filename>SRCPV</filename>, as shown in the
- previous example, to automatically update the package version
- whenever the revision of the package changes.
- The OpenEmbedded build system substitutes
- <filename>SRCPV</filename> with the following:
- <literallayout class='monospaced'>
- AUTOINC+<replaceable>source_revision</replaceable>
- </literallayout>
- The build system replaces the <filename>AUTOINC</filename> with
- a number.
- The number used depends on the state of the PR Service:
- <itemizedlist>
- <listitem><para>
- If PR Service is enabled, the build system increments
- the number, which is similar to the behavior of
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>.
- This behavior results in linearly increasing package
- versions, which is desirable.
- Here is an example:
- <literallayout class='monospaced'>
+ </literallayout>
+ The OpenEmbedded build system substitutes
+ <filename>SRCPV</filename> with the following:
+ <literallayout class='monospaced'>
+ AUTOINC+<replaceable>source_code_revision</replaceable>
+ </literallayout>
+ The build system replaces the <filename>AUTOINC</filename> with
+ a number.
+ The number used depends on the state of the PR Service:
+ <itemizedlist>
+ <listitem><para>
+ If PR Service is enabled, the build system increments
+ the number, which is similar to the behavior of
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>.
+ This behavior results in linearly increasing package
+ versions, which is desirable.
+ Here is an example:
+ <literallayout class='monospaced'>
hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk
hello-world-git_0.0+git1+dd2f5c3565-r0.0_armv7a-neon.ipk
- </literallayout>
- </para></listitem>
- <listitem><para>
- If PR Service is not enabled, the build system
- replaces the <filename>AUTOINC</filename>
- placeholder with zero (i.e. "0").
- This results in changing the package version since
- the source revision is included.
- However, package versions are not increased linearly.
- Here is an example:
- <literallayout class='monospaced'>
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ If PR Service is not enabled, the build system
+ replaces the <filename>AUTOINC</filename>
+ placeholder with zero (i.e. "0").
+ This results in changing the package version since
+ the source revision is included.
+ However, package versions are not increased linearly.
+ Here is an example:
+ <literallayout class='monospaced'>
hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk
hello-world-git_0.0+git0+dd2f5c3565-r0.0_armv7a-neon.ipk
- </literallayout>
- </para></listitem>
- </itemizedlist>
- </para>
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
- <para>
- In summary, the OpenEmbedded build system does not track the
- history of package versions for this purpose.
- <filename>AUTOINC</filename>, in this case, is comparable to
- <filename>PR</filename>.
- If PR server is not enabled, <filename>AUTOINC</filename>
- in the package version is simply replaced by "0".
- If PR server is enabled, the build system keeps track of the
- package versions and bumps the number when the package
- revision changes.
- </para>
+ <para>
+ In summary, the OpenEmbedded build system does not track the
+ history of binary package versions for this purpose.
+ <filename>AUTOINC</filename>, in this case, is comparable to
+ <filename>PR</filename>.
+ If PR server is not enabled, <filename>AUTOINC</filename>
+ in the package version is simply replaced by "0".
+ If PR server is enabled, the build system keeps track of the
+ package versions and bumps the number when the package
+ revision changes.
+ </para>
+ </section>
</section>
<section id='handling-optional-module-packaging'>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 2671e3c..55f7a28 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -487,7 +487,7 @@
<para>
For more information see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#incrementing-a-package-revision-number'>Incrementing a
Package Revision Number</ulink>"
+ "<ulink
url='&YOCTO_DOCS_DEV_URL;#incrementing-a-binary-package-revision-number'>Incrementing a Binary Package
Revision Number</ulink>"
section in the Yocto Project Development Manual.
</para>
</glossdef>
@@ -12691,7 +12691,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<filename>SRCREV</filename>, see the
<link linkend='var-AUTOREV'><filename>AUTOREV</filename></link>
variable description and the
- "<ulink
url='&YOCTO_DOCS_DEV_URL;#incrementing-a-package-revision-number'>Incrementing a Package Revision
Number</ulink>"
+ "<ulink
url='&YOCTO_DOCS_DEV_URL;#incrementing-a-binary-package-revision-number'>Incrementing a Binary Package
Revision Number</ulink>"
section, which is in the Yocto Project Development Manual.
</note>
</para>
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 87145a4..e3b7fec 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -432,7 +432,7 @@
For information on how the OpenEmbedded build system
works with packages and can
track incrementing <filename>PR</filename> information, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#incrementing-a-package-revision-number'>Incrementing a Package
Revision Number</ulink>"
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#incrementing-a-binary-package-revision-number'>Incrementing a
Binary Package Revision Number</ulink>"
section.
</note>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
