From 94467d5087ca3b13e7baac670af107550701b333 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 11 Apr 2017 11:55:38 -0700 Subject: 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 Signed-off-by: Richard Purdie --- .../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(-) (limited to 'documentation') 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 + + + 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: + + + Binary Package: The binary package that is eventually + built and installed into an image. + + + 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. + + + - 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: + 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 variable. + PR and/or + PV variables. - 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 - "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. -- cgit v1.2.3-54-g00ecf