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

290
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,18 +8070,23 @@
</para> </para>
<note> <note>
<para>The OpenEmbedded build system does not maintain <para>
<filename>PR</filename> information as part of the The OpenEmbedded build system does not maintain
shared state (sstate) packages. <filename>PR</filename> information as part of the
If you maintain an sstate feed, its expected that either shared state (sstate) packages.
all your building systems that contribute to the sstate If you maintain an sstate feed, its expected that either
feed use a shared PR Service, or you do not run a PR all your building systems that contribute to the sstate
Service on any of your building systems. feed use a shared PR Service, or you do not run a PR
Having some systems use a PR Service while others do Service on any of your building systems.
not leads to obvious problems.</para> Having some systems use a PR Service while others do
<para>For more information on shared state, see the not leads to obvious problems.
"<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>" </para>
section in the Yocto Project Reference Manual.</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> </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,95 +8146,89 @@
</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
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
variable to determine the specific revision from which to variable to determine the specific revision from which to
build. build.
You set the <filename>SRCREV</filename> variable to You set the <filename>SRCREV</filename> variable to
<ulink url='&YOCTO_DOCS_REF_URL;#var-AUTOREV'><filename>AUTOREV</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-AUTOREV'><filename>AUTOREV</filename></ulink>
to cause the OpenEmbedded build system to automatically use the to cause the OpenEmbedded build system to automatically use the
latest revision of the package: latest revision of the package:
<literallayout class='monospaced'> <literallayout class='monospaced'>
SRCREV = "${AUTOREV}" SRCREV = "${AUTOREV}"
</literallayout> </literallayout>
</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. Here is an example:
<filename>PV</filename>), <literallayout class='monospaced'>
they do this with the help of <filename>SRCPV</filename>.
Here is an example:
<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 The OpenEmbedded build system substitutes
previous example, to automatically update the package version <filename>SRCPV</filename> with the following:
whenever the revision of the package changes. <literallayout class='monospaced'>
The OpenEmbedded build system substitutes AUTOINC+<replaceable>source_code_revision</replaceable>
<filename>SRCPV</filename> with the following: </literallayout>
<literallayout class='monospaced'> The build system replaces the <filename>AUTOINC</filename> with
AUTOINC+<replaceable>source_revision</replaceable> a number.
</literallayout> The number used depends on the state of the PR Service:
The build system replaces the <filename>AUTOINC</filename> with <itemizedlist>
a number. <listitem><para>
The number used depends on the state of the PR Service: If PR Service is enabled, the build system increments
<itemizedlist> the number, which is similar to the behavior of
<listitem><para> <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>.
If PR Service is enabled, the build system increments This behavior results in linearly increasing package
the number, which is similar to the behavior of versions, which is desirable.
<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>. Here is an example:
This behavior results in linearly increasing package <literallayout class='monospaced'>
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+git0+b6558dd387-r0.0_armv7a-neon.ipk
hello-world-git_0.0+git1+dd2f5c3565-r0.0_armv7a-neon.ipk hello-world-git_0.0+git1+dd2f5c3565-r0.0_armv7a-neon.ipk
</literallayout> </literallayout>
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
If PR Service is not enabled, the build system If PR Service is not enabled, the build system
replaces the <filename>AUTOINC</filename> replaces the <filename>AUTOINC</filename>
placeholder with zero (i.e. "0"). placeholder with zero (i.e. "0").
This results in changing the package version since This results in changing the package version since
the source revision is included. the source revision is included.
However, package versions are not increased linearly. However, package versions are not increased linearly.
Here is an example: Here is an example:
<literallayout class='monospaced'> <literallayout class='monospaced'>
hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk
hello-world-git_0.0+git0+dd2f5c3565-r0.0_armv7a-neon.ipk hello-world-git_0.0+git0+dd2f5c3565-r0.0_armv7a-neon.ipk
</literallayout> </literallayout>
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<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>
in the package version is simply replaced by "0". in the package version is simply replaced by "0".
If PR server is enabled, the build system keeps track of the If PR server is enabled, the build system keeps track of the
package versions and bumps the number when the package package versions and bumps the number when the package
revision changes. revision changes.
</para> </para>
</section>
</section> </section>
<section id='handling-optional-module-packaging'> <section id='handling-optional-module-packaging'>

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>