diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 28a97f14bc..d2bd56dc13 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -7792,10 +7792,7 @@
Excluding packages from an image
- Incrementing a package version number
-
-
- Incrementing a package revision number
+ Incrementing a binary package version
Handling optional module packaging
@@ -7853,43 +7850,102 @@
-
- Incrementing a Package Version Number
+
+ Incrementing a Package Version
- If a committed change results in changing the package output,
- then the value of the
- PR
- variable needs to be increased (or "bumped").
- Increasing PR occurs one of two ways:
+ 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.
+
+
+
+ In order to understand binary package versioning, you need
+ to consider the following:
- Automatically using a Package Revision
- Service (PR Service).
+
+ Binary Package: The binary package that is eventually
+ built and installed into an image.
- Manually incrementing the
- PR variable.
+
+ Binary Package Version: The binary package version
+ is composed of two components - a version and a
+ revision.
+
+ Technically, the "epoch" (i.e.
+ PE)
+ is involved but this discussion for the most part
+ ignores PE.
+
+ The version and revision are taken from the
+ PV
+ and
+ PR
+ variables, respectively.
+
+
+ PV: The recipe version, which is
+ not to be confused with the binary package version.
+
+
+ PR: The recipe revision.
+
+
+ SRCPV:
+ The Version string of the binary package.
+ The OpenEmbedded build system uses this string
+ to help define the value of PV.
+
+
+ PR Service:
+ A network-based service that helps automate keeping
+ package feeds compatible with existing package
+ manager applications such as RPM, APT, and OPKG.
- 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.
+ Whenever the binary package output changes, the binary package
+ version must change.
+ Changing the binary package version is accomplished by changing
+ or "bumping" the PR and/or
+ PV values.
+ Increasing these values occurs one of two ways:
+
+ Automatically using a Package Revision
+ Service (PR Service).
+
+ Manually incrementing the
+ PR and/or
+ PV variables.
+
+
+
+
+
+ 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
- "Incrementing a Package Revision Number"
+ "Incrementing a Binary Package Revision Number"
section.
- The following two sections provide information on the PR Service
- and on manual PR bumping.
+ The following three sections provide related information on the
+ PR Service, the manual method for "bumping"
+ PR and/or PV, and
+ on how to ensure binary package revisioning remains linear.
@@ -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
- PR numbers to trigger a rebuild.
+ PR, PV, and
+ PE numbers to trigger a rebuild.
The signatures, however, can be used to generate
- PR values.
+ these values.
@@ -7977,7 +8034,7 @@
Once the service is started, packages will automatically
get increasing PR values and
- BitBake will take care of starting and stopping the server.
+ BitBake takes care of starting and stopping the server.
@@ -7998,8 +8055,8 @@
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 local.conf file:
@@ -8013,18 +8070,23 @@
- The OpenEmbedded build system does not maintain
- PR 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.
- For more information on shared state, see the
- "Shared State Cache"
- section in the Yocto Project Reference Manual.
+
+ The OpenEmbedded build system does not maintain
+ PR 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.
+
+
+
+ For more information on shared state, see the
+ "Shared State Cache"
+ section in the Yocto Project Reference Manual.
+
@@ -8033,7 +8095,7 @@
The alternative to setting up a PR Service is to manually
- bump the
+ "bump" the
PR
variable.
@@ -8067,7 +8129,7 @@
- When upgrading the version of a package, assuming the
+ When upgrading the version of a binary package, assuming the
PV
changes, the PR variable should be
reset to "r0" (or "${INC_PR}.0" if you are using
@@ -8075,7 +8137,7 @@
- Usually, version increases occur only to packages.
+ Usually, version increases occur only to binary packages.
However, if for some reason PV changes
but does not increase, you can increase the
PE
@@ -8084,95 +8146,89 @@
- Version numbering strives to follow the
+ Binary package version numbering strives to follow the
Debian Version Field Policy Guidelines.
These guidelines define how versions are compared and what
"increasing" a version means.
-
-
- Incrementing a Package Revision Number
+
+ Incrementing a Binary Package Revision Number
-
- When fetching a repository, BitBake uses the
- SRCREV
- variable to determine the specific revision from which to
- build.
- You set the SRCREV variable to
- AUTOREV
- to cause the OpenEmbedded build system to automatically use the
- latest revision of the package:
+
+ When fetching a repository, BitBake uses the
+ SRCREV
+ variable to determine the specific revision from which to
+ build.
+ You set the SRCREV variable to
+ AUTOREV
+ to cause the OpenEmbedded build system to automatically use the
+ latest revision of the package:
SRCREV = "${AUTOREV}"
-
+
-
- Furthermore, the SRCPV variable returns
- the version string of the current package.
- This string is used to help define the value of
- PV.
- If your recipe needs to define the package version (i.e.
- PV),
- they do this with the help of SRCPV.
- Here is an example:
-
+
+ Furthermore, you need to reference SRCPV
+ in PV in order to automatically update
+ the binary package version whenever the revision of the
+ source code changes.
+ Here is an example:
+
PV = "1.0+git${SRCPV}"
-
- You can use SRCPV, as shown in the
- previous example, to automatically update the package version
- whenever the revision of the package changes.
- The OpenEmbedded build system substitutes
- SRCPV with the following:
-
- AUTOINC+source_revision
-
- The build system replaces the AUTOINC with
- a number.
- The number used depends on the state of the PR Service:
-
-
- If PR Service is enabled, the build system increments
- the number, which is similar to the behavior of
- PR.
- This behavior results in linearly increasing package
- versions, which is desirable.
- Here is an example:
-
+
+ The OpenEmbedded build system substitutes
+ SRCPV with the following:
+
+ AUTOINC+source_code_revision
+
+ The build system replaces the AUTOINC with
+ a number.
+ The number used depends on the state of the PR Service:
+
+
+ If PR Service is enabled, the build system increments
+ the number, which is similar to the behavior of
+ PR.
+ This behavior results in linearly increasing package
+ versions, which is desirable.
+ Here is an example:
+
hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk
hello-world-git_0.0+git1+dd2f5c3565-r0.0_armv7a-neon.ipk
-
-
-
- If PR Service is not enabled, the build system
- replaces the AUTOINC
- 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:
-
+
+
+
+ If PR Service is not enabled, the build system
+ replaces the AUTOINC
+ 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:
+
hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk
hello-world-git_0.0+git0+dd2f5c3565-r0.0_armv7a-neon.ipk
-
-
-
-
+
+
+
+
-
- In summary, the OpenEmbedded build system does not track the
- history of package versions for this purpose.
- AUTOINC, in this case, is comparable to
- PR.
- If PR server is not enabled, AUTOINC
- 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.
-
+
+ In summary, the OpenEmbedded build system does not track the
+ history of binary package versions for this purpose.
+ AUTOINC, in this case, is comparable to
+ PR.
+ If PR server is not enabled, AUTOINC
+ 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.
+
+
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 2671e3cb4d..55f7a28c21 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -487,7 +487,7 @@
For more information see the
- "Incrementing a Package Revision Number"
+ "Incrementing a Binary Package Revision Number"
section in the Yocto Project Development Manual.
@@ -12691,7 +12691,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
SRCREV, see the
AUTOREV
variable description and the
- "Incrementing a Package Revision Number"
+ "Incrementing a Binary Package Revision Number"
section, which is in the Yocto Project Development Manual.
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 87145a48f6..e3b7fec353 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 PR information, see the
- "Incrementing a Package Revision Number"
+ "Incrementing a Binary Package Revision Number"
section.