From ba9fc8aaf3597fb4ea128cb965d973f3ee831550 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 8 Feb 2013 12:59:27 -0600 Subject: dev-manual: First draft of the PR Service section. Fixes YOCTO #2684 Completed first draft. (From yocto-docs rev: c8b81e372578b1964bca4aa26d1085162115a2b0) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 260 +++++++++++++++++---- 1 file changed, 211 insertions(+), 49 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index e9555e6168..479362fca5 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1974,71 +1974,233 @@ -
+
Incrementing a Package Revision Number If a committed change results in changing the package output, then the value of the - PR - variable needs to be increased - (or "bumped") as part of that commit. - For new recipes you should add the PR - variable and set its initial value equal to "r0", which is the default. - Even though the default value is "r0", the practice of adding it to a new recipe makes - it harder to forget to bump the variable when you make changes - to the recipe in future. + PR + variable needs to be increased (or "bumped"). + Increasing PR occurs one of two ways: + + Automatically using a Package Revision + Service (PR Service). + Manually incrementing the + PR variable. + - If you are sharing a common .inc file with multiple recipes, - you can also use the - INC_PR - variable to ensure that - the recipes sharing the .inc file are rebuilt when the - .inc file itself is changed. - The .inc file must set INC_PR - (initially to "r0"), and all recipes referring to it should set PR - to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. - If the .inc file is changed then its - INC_PR should be incremented. + 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 version + numbering increases in a linear fashion and that a number of + version components exist that support that linear progression. - When upgrading the version of a package, assuming the - PV - changes, the PR variable should be reset to "r0" - (or "$(INC_PR).0" if you are using INC_PR). + The following two sections provide information on the PR Service + and on manual PR bumping. - - Usually, version increases occur only to packages. - However, if for some reason PV changes but does not - increase, you can increase the - PE - variable (Package Epoch). - The PE variable defaults to "0". - +
+ Working With a PR Service - - Version numbering strives to follow the - - Debian Version Field Policy Guidelines. - These guidelines define how versions are compared and what "increasing" a version means. - + + As mentioned, attempting to maintain revision numbers in the + Metadata + is error prone, inaccurate and causes problems for people + submitting recipes. + Conversely, the PR Service automatically generates + increasing numbers, particularly the revision field, + which removes the human element. + + For additional information on using a PR Service, you + can see the + PR Service + wiki page. + + - - There are two reasons for following the previously mentioned guidelines. - First, to ensure that when a developer updates and rebuilds, they get all the changes to - the repository and do not have to remember to rebuild any sections. - Second, to ensure that target users are able to upgrade their - devices using package manager commands such as opkg upgrade - (or similar commands for dpkg/apt or rpm-based systems). - + + The Yocto Project uses variables in order of + decreasing priority to facilitate revision numbering (i.e. + PE, + PV, and + PR + for epoch, version and revision, respectively). + The values are highly dependent on the policies and + procedures of a given distribution and package feed. + - - The goal is to ensure the Yocto Project has packages that can be upgraded in all cases. - + + Because the OpenEmbedded build system uses "signatures", + which are unique to a given build, the build system + knows when to rebuild packages. + 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. + The signatures, however, can be used to generate + PR values. + + + + The PR Service works with both + OEBasic and + OEBasicHash generators. + The value of PR bumps when the + checksum changes and the different generator mechanisms + change signatures under different circumstances. + + + + As implemented, the build system includes values from + the PR Service into the PR field as + an addition using the form ".x" so + r0 becomes r0.1, + r0.2 and so forth. + This scheme allows existing PR values + to be used for whatever reasons, which include manual + PR bumps should it be necessary. + + + + By default, there is no server that runs the PR Service. + Thus, the packages generated are just "self consistent". + The build system adds and removes packages and + there are no guarantees about upgrade paths. + + + + The simplest form for a PR Service is for it to exist + for a single host development system that builds the + package feed (building system). + For this scenario, you can enable the PR Service by adding + the following to your local.conf + file in the + Build Directory: + + PRSERV_HOST = "localhost:0" + + Once the service is started, packages will automatically + get increasing PR values and + BitBake will take care of starting and stopping the server. + + + + If you have a more complex setup where multiple host + development systems work against a common, shared package + feed, you have a single PR Service running and it is + connected to each building system. + For this scenario, you need to start the PR Service using + the bitbake-prserv command: + + bitbake-prserve ‐‐host <ip> ‐‐port <port> ‐‐start + + In addition to hand-starting the service, you need to + update the local.conf file of each + building system as described earlier so each system + points to the server and port. + + + + 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. + To enable build history, add the following to each building + system's local.conf file: + + # It is recommended to activate "buildhistory" for testing the PR service + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "1" + + For information on build history, see the + "Maintaining Build Output Quality" + 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. + +
+ +
+ Manually Bumping PR + + + If a committed change results in changing the package output, + then the value of the PR variable needs to be increased + (or "bumped") as part of that commit. + For new recipes you should add the PR + variable and set its initial value equal to "r0", which is the default. + Even though the default value is "r0", the practice of adding it to a new recipe makes + it harder to forget to bump the variable when you make changes + to the recipe in future. + + + + If you are sharing a common .inc file with multiple recipes, + you can also use the + INC_PR + variable to ensure that + the recipes sharing the .inc file are rebuilt when the + .inc file itself is changed. + The .inc file must set INC_PR + (initially to "r0"), and all recipes referring to it should set PR + to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. + If the .inc file is changed then its + INC_PR should be incremented. + + + + When upgrading the version of a package, assuming the + PV + changes, the PR variable should be reset to "r0" + (or "$(INC_PR).0" if you are using INC_PR). + + + + Usually, version increases occur only to packages. + However, if for some reason PV changes but does not + increase, you can increase the + PE + variable (Package Epoch). + The PE variable defaults to "0". + + + + Version numbering strives to follow the + + Debian Version Field Policy Guidelines. + These guidelines define how versions are compared and what "increasing" a version means. + + + + There are two reasons for following the previously mentioned guidelines. + First, to ensure that when a developer updates and rebuilds, they get all the changes to + the repository and do not have to remember to rebuild any sections. + Second, to ensure that target users are able to upgrade their + devices using package manager commands such as opkg upgrade + (or similar commands for dpkg/apt or rpm-based systems). + + + + The goal is to ensure the Yocto Project has packages that can be upgraded in all cases. + +
-- cgit v1.2.3-54-g00ecf