sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

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>
This commit is contained in:
Scott Rifenbark 2017-04-11 11:55:38 -07:00 committed by Richard Purdie
parent f9e7fba02f
commit 94467d5087
3 changed files with 176 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

164
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@ -7792,10 +7792,7 @@
<link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link> <link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link>
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
<link linkend='incrementing-a-package-version-number'>Incrementing a package version number</link> <link linkend='incrementing-a-binary-package-version'>Incrementing a binary package version</link>
</para></listitem>
<listitem><para>
<link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link>
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
<link linkend='handling-optional-module-packaging'>Handling optional module packaging</link> <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link>
@ -7853,43 +7850,102 @@
</para> </para>
</section> </section>
<section id='incrementing-a-package-version-number'> <section id='incrementing-a-binary-package-version'>
<title>Incrementing a Package Version Number</title> <title>Incrementing a Package Version</title>
<para> <para>
If a committed change results in changing the package output, The scheme the OpenEmbedded build system uses for binary
then the value of the package versioning is a bit involved.
<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> This section provides some background on how binary package
variable needs to be increased (or "bumped"). versioning is accomplished and presents some of the services,
Increasing <filename>PR</filename> occurs one of two ways: variables, and terminology involved.
</para>
<para>
In order to understand binary package versioning, you need
to consider the following:
<itemizedlist> <itemizedlist>
<listitem><para>Automatically using a Package Revision <listitem><para>
Service (PR Service). Binary Package: The binary package that is eventually
built and installed into an image.
</para></listitem> </para></listitem>
<listitem><para>Manually incrementing the <listitem><para>
<filename>PR</filename> variable. 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> </para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
Given that one of the challenges any build system and its Whenever the binary package output changes, the binary package
users face is how to maintain a package feed that is compatible version must change.
with existing package manager applications such as Changing the binary package version is accomplished by changing
RPM, APT, and OPKG, using an automated system is much or "bumping" the <filename>PR</filename> and/or
preferred over a manual system. <filename>PV</filename> values.
In either system, the main requirement is that package version Increasing these values occurs one of two ways:
numbering increases in a linear fashion and that a number of <itemizedlist>
version components exist that support that linear progression. <listitem><para>Automatically using a Package Revision
Service (PR Service).
</para></listitem>
<listitem><para>Manually incrementing the
<filename>PR</filename> and/or
<filename>PV</filename> variables.
</para></listitem>
</itemizedlist>
</para>
<para>
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 For information on how to ensure package revisioning remains
linear, see the 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. section.
</para> </para>
<para> <para>
The following two sections provide information on the PR Service The following three sections provide related information on the
and on manual <filename>PR</filename> bumping. 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> </para>
<section id='working-with-a-pr-service'> <section id='working-with-a-pr-service'>
@ -7930,9 +7986,10 @@
All the inputs into a given task are represented by a All the inputs into a given task are represented by a
signature, which can trigger a rebuild when different. signature, which can trigger a rebuild when different.
Thus, the build system itself does not rely on the 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 The signatures, however, can be used to generate
<filename>PR</filename> values. these values.
</para> </para>
<para> <para>
@ -7977,7 +8034,7 @@
</literallayout> </literallayout>
Once the service is started, packages will automatically Once the service is started, packages will automatically
get increasing <filename>PR</filename> values and 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>
<para> <para>
@ -7998,8 +8055,8 @@
<para> <para>
It is also recommended you use build history, which adds It is also recommended you use build history, which adds
some sanity checks to package versions, in conjunction with some sanity checks to binary package versions, in
the server that is running the PR Service. conjunction with the server that is running the PR Service.
To enable build history, add the following to each building To enable build history, add the following to each building
system's <filename>local.conf</filename> file: system's <filename>local.conf</filename> file:
<literallayout class='monospaced'> <literallayout class='monospaced'>
@ -8013,7 +8070,8 @@
</para> </para>
<note> <note>
<para>The OpenEmbedded build system does not maintain <para>
The OpenEmbedded build system does not maintain
<filename>PR</filename> information as part of the <filename>PR</filename> information as part of the
shared state (sstate) packages. shared state (sstate) packages.
If you maintain an sstate feed, its expected that either If you maintain an sstate feed, its expected that either
@ -8021,10 +8079,14 @@
feed use a shared PR Service, or you do not run a PR feed use a shared PR Service, or you do not run a PR
Service on any of your building systems. Service on any of your building systems.
Having some systems use a PR Service while others do Having some systems use a PR Service while others do
not leads to obvious problems.</para> not leads to obvious problems.
<para>For more information on shared state, see the </para>
<para>
For more information on shared state, see the
"<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>" "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
section in the Yocto Project Reference Manual.</para> section in the Yocto Project Reference Manual.
</para>
</note> </note>
</section> </section>
@ -8033,7 +8095,7 @@
<para> <para>
The alternative to setting up a PR Service is to manually 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> <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
variable. variable.
</para> </para>
@ -8067,7 +8129,7 @@
</para> </para>
<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> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
changes, the <filename>PR</filename> variable should be changes, the <filename>PR</filename> variable should be
reset to "r0" (or "${INC_PR}.0" if you are using reset to "r0" (or "${INC_PR}.0" if you are using
@ -8075,7 +8137,7 @@
</para> </para>
<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 However, if for some reason <filename>PV</filename> changes
but does not increase, you can increase the but does not increase, you can increase the
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename> <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
@ -8084,17 +8146,16 @@
</para> </para>
<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'> <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
Debian Version Field Policy Guidelines</ulink>. Debian Version Field Policy Guidelines</ulink>.
These guidelines define how versions are compared and what These guidelines define how versions are compared and what
"increasing" a version means. "increasing" a version means.
</para> </para>
</section> </section>
</section>
<section id='incrementing-a-package-revision-number'> <section id='incrementing-a-binary-package-revision-number'>
<title>Incrementing a Package Revision Number</title> <title>Incrementing a Binary Package Revision Number</title>
<para> <para>
When fetching a repository, BitBake uses the When fetching a repository, BitBake uses the
@ -8111,24 +8172,18 @@
</para> </para>
<para> <para>
Furthermore, the <filename>SRCPV</filename> variable returns Furthermore, you need to reference <filename>SRCPV</filename>
the version string of the current package. in <filename>PV</filename> in order to automatically update
This string is used to help define the value of the binary package version whenever the revision of the
<ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>. source code changes.
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: Here is an example:
<literallayout class='monospaced'> <literallayout class='monospaced'>
PV = "1.0+git${SRCPV}" PV = "1.0+git${SRCPV}"
</literallayout> </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 The OpenEmbedded build system substitutes
<filename>SRCPV</filename> with the following: <filename>SRCPV</filename> with the following:
<literallayout class='monospaced'> <literallayout class='monospaced'>
AUTOINC+<replaceable>source_revision</replaceable> AUTOINC+<replaceable>source_code_revision</replaceable>
</literallayout> </literallayout>
The build system replaces the <filename>AUTOINC</filename> with The build system replaces the <filename>AUTOINC</filename> with
a number. a number.
@ -8164,7 +8219,7 @@
<para> <para>
In summary, the OpenEmbedded build system does not track the In summary, the OpenEmbedded build system does not track the
history of package versions for this purpose. history of binary package versions for this purpose.
<filename>AUTOINC</filename>, in this case, is comparable to <filename>AUTOINC</filename>, in this case, is comparable to
<filename>PR</filename>. <filename>PR</filename>.
If PR server is not enabled, <filename>AUTOINC</filename> If PR server is not enabled, <filename>AUTOINC</filename>
@ -8174,6 +8229,7 @@
revision changes. revision changes.
</para> </para>
</section> </section>
</section>
<section id='handling-optional-module-packaging'> <section id='handling-optional-module-packaging'>
<title>Handling Optional Module Packaging</title> <title>Handling Optional Module Packaging</title>

4
documentation/ref-manual/ref-variables.xml
View File

@ -487,7 +487,7 @@
<para> <para>
For more information see the 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. section in the Yocto Project Development Manual.
</para> </para>
</glossdef> </glossdef>
@ -12691,7 +12691,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<filename>SRCREV</filename>, see the <filename>SRCREV</filename>, see the
<link linkend='var-AUTOREV'><filename>AUTOREV</filename></link> <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link>
variable description and the 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. section, which is in the Yocto Project Development Manual.
</note> </note>
</para> </para>

2
documentation/ref-manual/technical-details.xml
View File

@ -432,7 +432,7 @@
For information on how the OpenEmbedded build system For information on how the OpenEmbedded build system
works with packages and can works with packages and can
track incrementing <filename>PR</filename> information, see the 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. section.
</note> </note>