Bug 3095

Can someone give me a rough paragraph or two describing the use for PRINC?  In comment 1 two uses are shown.  Are these the only valid uses?  What are the parameters for use? What is the general purpose for the variable, etc. 

Once I get this information I can create a glossary entry for the variable and, if appropriate, find a place in the mainstream documentation where it is used and expand on it.

Scott

Some discussion from the Yocto mailing list:

https://lists.yoctoproject.org/pipermail/yocto/2012-September/011411.html

>>> +PR .= ".1"
>>
>> why not
>> PRINC := "${@int(PRINC) + 1}"
>> ?
>
> I understood that the .1 adds more finer granularity instead of 
> incrementing the base PR itself.  You end up with a potential r1.2.1 
> which is still legal.

Yes but also makes order of .bbappends applied even more important.

In case one layer has
PR .= ".2"

and other
PR .= ".1"

Then it will provide r1.2.1 or r1.1.2 depending on order of bbappends
applied. Hopefully you want change order of layers to break every
upgrade path, but why not use PRINC which does not suffer from this?
 
> What happens with a r1.2 and the above @int(PRINC) + 1?

I guess it will produce r2.2

    princ = d.getVar('PRINC', True)
    if princ and princ != "0":
        pr = d.getVar('PR', True)
        pr_prefix = re.search("\D+",pr)
        prval = re.search("\d+",pr)
        if pr_prefix is None or prval is None:
            bb.error("Unable to analyse format of PR variable: %s" % pr)
        nval = int(prval.group(0)) + int(princ)
        pr = pr_prefix.group(0) + str(nval) + pr[prval.end():]
        d.setVar('PR', pr)


And another discussion:
https://lists.yoctoproject.org/pipermail/yocto/2012-July/009887.html

> PRINC := "${@int(PRINC) + 2}"

This is the correct method to use in a bbappend. Start with 1,
obviously, and bump it each time the bbappend changes.


From what I have gathered from the above is that the proper way to use PRINC is as follows:

"
PRINC will dynamically increment the PR value of a recipe while minimizing the impact of layer ordering. In order to ensure multiple bbappend files can co-exist, PRINC should be self referencing (it defaults to 0):

PRINC := "${@int(PRINC) + 2}"

It is adviseable not to use strings such as ".= '.1'" as this usage is very sensitive to layer ordering. Explicit assignments should be avoided as they cannot adequately represent multiple bbappend files.
"

Here is a first cut at the PRINC glossary entry.  Previously emailed to Darren Hart only.  this makes it more visible to the community.  Please comment on the entry for improvements or inacurracies:

PRINC

    Causes the PR variable to dynamically increment. This incrementation increases the value of a recipe's revision (PR) while minimizing the impact of layer ordering.

    In order to ensure multiple .bbappend files can co-exist, PRINC should be self referencing. The variable defaults to 0.

    Following is an example that increments PR by two:

         PRINC := "${@int(PRINC) + 2}"
                        

    It is adviseable not to use strings such as ".= '.1'" with the variable because this usage is very sensitive to layer ordering. Explicit assignments should be avoided as they cannot adequately represent multiple .bbappend files.

I just came across this, which adds another perspective to this, the INC_PR variable seems very similar to PRINC:
http://www.yoctoproject.org/docs/current/poky-ref-manual/poky-ref-manual.html#var-INC_PR

Does PRINC duplicate INC_PR? if not, what are the situations where one is more appropriate than the other?

(In reply to comment #4)
> I just came across this, which adds another perspective to this, the INC_PR
> variable seems very similar to PRINC:
> http://www.yoctoproject.org/docs/current/poky-ref-manual/poky-ref-manual.
> html#var-INC_PR
> 
> Does PRINC duplicate INC_PR? if not, what are the situations where one is
> more appropriate than the other?


PRINC is used to INCrement the PR value when bbappend'ing recipes.

INC_PR is used to reference, and typically append to, an INClude file's PR value. It is used when multiple recipes are built from a common include file.

The naminig is seriously unfortunately, but they perform distinct functions.

I have been hacking away at both glossary definitions (INC_PR and PRINC) off and on for the last few days.  Here are links to the definitions I have.  Input into these definitions have come from Paul Eggleton, Scott Garman, and Darren Hart.  Further comments?

INC_PR - http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-INC_PR

PRINC - http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PRINC

Scott

(In reply to comment #6)

These look good to me.

Looks fine to me too.

I am marking this bug FIXED/RESOLVED.  Three commits combined to come to the final solution.

http://git.yoctoproject.org/cgit.cgi/yocto-docs/commit/?id=053e4558cc90eb1618e697394aff6d40edbeb3b1

http://git.yoctoproject.org/cgit.cgi/yocto-docs/commit/?id=7647cef96643b3723f80013c2c51ba6d7480122a

http://git.yoctoproject.org/cgit.cgi/yocto-docs/commit/?id=418862011e79940ee378f64c6171618d29568014

Scott

Verified