5.13.2.1. Working With a PR Service

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.

Note

For additional information on using a PR Service, you can see the PR Service wiki page.

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.

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, the PR Service is not enabled or running. Thus, the packages generated are just "self consistent". The build system adds and removes packages and there are no guarantees about upgrade paths but images will be consistent and correct with the latest changes.

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 a local PR Service by setting PRSERV_HOST in 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-prserv ‐‐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.

Note

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.