The term Package as used in the YP docs

The term Package as used in the YP docs

[Rifenbark, Scott M]

[-- Attachment #1: Type: text/plain, Size: 1813 bytes --]

This post will have some strong opinions and responses.  But, I want to throw this out as a re-write of the term "Package" as defined in the YP Development Manual's "Terms" section.  I gave this a shot based on my brief understanding and on some email that was tossed about a while back on the term.  What I would like to ultimately come up with is a definition that works for the term as we want to use it in the YP docs and also as an explanation for some of our older variable names like PR, PV, and so forth that really refer to recipes.  Please thrash over it....


*         Package: In the context of the Yocto Project, this term refers to the packaged output from a baked recipe. A package is generally the compiled binaries produced from the recipe's sources. You 'bake' something by running it through BitBake.

It is worth noting that the term "package" can, in general, have subtle meanings. For example, the packages refered to in the "The Packages<http://www.yoctoproject.org/docs/1.3/yocto-project-qs/yocto-project-qs.html#packages>" section are compiled binaries that when installed add functionality to your Linux distribution.

Another point worth noting is that historically within the Yocto Project, recipes were referred to as packages - thus, the existence of several BitBake variables that are seemingly mis-named, (e.g. PR<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#var-PR>, PRINC<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#var-PRINC>, PV<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#var-PV>, and PE<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#var-PE>).


Scott Rifenbark
Intel Corporation
Yocto Project Documentation
503.712.2702
503.341.0418 (cell)


[-- Attachment #2: Type: text/html, Size: 6188 bytes --]

Re: The term Package as used in the YP docs

[Paul Eggleton]

Hi Scott,

On Friday 28 September 2012 18:14:31 Rifenbark, Scott M wrote:
> *         Package: In the context of the Yocto Project, this term refers to
> the packaged output from a baked recipe. A package is generally the
> compiled binaries produced from the recipe's sources. You 'bake' something
> by running it through BitBake.
> 
> It is worth noting that the term "package" can, in general, have subtle
> meanings. For example, the packages refered to in the "The
> Packages<http://www.yoctoproject.org/docs/1.3/yocto-project-qs/yocto-projec
> t-qs.html#packages>" section are compiled binaries that when installed add
> functionality to your Linux distribution.

The thing is, this is actually the same meaning, we're just talking about 
packages for your host distribution rather than packages for the custom distro 
you're building - the concept is the same. If we do need to clarify it I would 
suggest using the term "host package" or something very similar for packages 
to be installed as pre-requisites on the host system.

> Another point worth noting is that historically within the Yocto Project,
> recipes were referred to as packages - thus, the existence of several
> BitBake variables that are seemingly mis-named, (e.g.
> PR<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.htm
> l#var-PR>,
> PRINC<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.
> html#var-PRINC>,
> PV<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.htm
> l#var-PV>, and
> PE<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.htm
> l#var-PE>).

I have to say, whilst this is an interesting point of history, I'm not sure 
anyone really needs to know this in the manual, particularly if we've replaced 
all historical use of the word "package" when we mean "recipe" (as I think we 
now have for this release).

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre

Re: The term Package as used in the YP docs

[Rifenbark, Scott M]

Paul, 

Thanks for the clarification on the host packages.  Maybe I should rewrite "The Packages" section to use that term.  That seems best.  I guess the reason I wanted to explain the weird variable names was because they caused me a lot of angst as I tried to figure things out.  Maybe this is not so for others.  I certainly don't need to provide a history lesson if I am the minority.

Scott

-----Original Message-----
From: Paul Eggleton [mailto:paul.eggleton@linux.intel.com] 
Sent: Friday, September 28, 2012 11:23 AM
To: Rifenbark, Scott M
Cc: yocto@yoctoproject.org
Subject: Re: [yocto] The term Package as used in the YP docs

Hi Scott,

On Friday 28 September 2012 18:14:31 Rifenbark, Scott M wrote:
> *         Package: In the context of the Yocto Project, this term refers to
> the packaged output from a baked recipe. A package is generally the
> compiled binaries produced from the recipe's sources. You 'bake' something
> by running it through BitBake.
> 
> It is worth noting that the term "package" can, in general, have subtle
> meanings. For example, the packages refered to in the "The
> Packages<http://www.yoctoproject.org/docs/1.3/yocto-project-qs/yocto-projec
> t-qs.html#packages>" section are compiled binaries that when installed add
> functionality to your Linux distribution.

The thing is, this is actually the same meaning, we're just talking about 
packages for your host distribution rather than packages for the custom distro 
you're building - the concept is the same. If we do need to clarify it I would 
suggest using the term "host package" or something very similar for packages 
to be installed as pre-requisites on the host system.

> Another point worth noting is that historically within the Yocto Project,
> recipes were referred to as packages - thus, the existence of several
> BitBake variables that are seemingly mis-named, (e.g.
> PR<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.htm
> l#var-PR>,
> PRINC<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.
> html#var-PRINC>,
> PV<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.htm
> l#var-PV>, and
> PE<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.htm
> l#var-PE>).

I have to say, whilst this is an interesting point of history, I'm not sure 
anyone really needs to know this in the manual, particularly if we've replaced 
all historical use of the word "package" when we mean "recipe" (as I think we 
now have for this release).

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre

Re: The term Package as used in the YP docs

[Rudolf Streif]

[-- Attachment #1: Type: text/plain, Size: 3000 bytes --]

+1

I agree with Scott's definition. In the general Linux context a Package is
a compilation of binaries, documentation, development files, etc. wrapped
up in a format that can be used by a package management system to install
it on a target system.

It is somewhat confusing that YP and OE use the term 'package' synonymously
with 'recipe'. In most cases a package is the output of a recipe.

I am all for making this more consistent at least to start with in the
documentation. Unfortunately, changing variables like P, PN, PV, PR etc.
may cause some pain. If a transition is what the broader community would
like to achieve then a period where old and new variables can be used
interchangeably (if possible) would be the way to go.

:rjs

On Fri, Sep 28, 2012 at 11:14 AM, Rifenbark, Scott M <
scott.m.rifenbark@intel.com> wrote:

>  This post will have some strong opinions and responses.  But, I want to
> throw this out as a re-write of the term “Package” as defined in the YP
> Development Manual’s “Terms” section.  I gave this a shot based on my brief
> understanding and on some email that was tossed about a while back on the
> term.  What I would like to ultimately come up with is a definition that
> works for the term as we want to use it in the YP docs and also as an
> explanation for some of our older variable names like PR, PV, and so forth
> that really refer to recipes.  Please thrash over it….****
>
> ** **
>
> **·         ***Package:* In the context of the Yocto Project, this term
> refers to the packaged output from a baked recipe. A package is generally
> the compiled binaries produced from the recipe's sources. You ‘bake’
> something by running it through BitBake.****
>
> It is worth noting that the term "package" can, in general, have subtle
> meanings. For example, the packages refered to in the "The Packages<http://www.yoctoproject.org/docs/1.3/yocto-project-qs/yocto-project-qs.html#packages>"
> section are compiled binaries that when installed add functionality to your
> Linux distribution.****
>
> Another point worth noting is that historically within the Yocto Project,
> recipes were referred to as packages - thus, the existence of several
> BitBake variables that are seemingly mis-named, (e.g. PR<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#var-PR>,
> PRINC<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#var-PRINC>,
> PV<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#var-PV>,
> and PE<http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#var-PE>).
> ****
>
> ** **
>
> ** **
>
> *Scott Rifenbark***
>
> Intel Corporation****
>
> Yocto Project Documentation****
>
> 503.712.2702****
>
> 503.341.0418 (cell)****
>
> ** **
>
> _______________________________________________
> yocto mailing list
> yocto@yoctoproject.org
> https://lists.yoctoproject.org/listinfo/yocto
>
>

[-- Attachment #2: Type: text/html, Size: 5557 bytes --]

Re: The term Package as used in the YP docs

[Paul Eggleton]

On Friday 28 September 2012 11:27:37 Rudolf Streif wrote:
> +1
> 
> I agree with Scott's definition. In the general Linux context a Package is
> a compilation of binaries, documentation, development files, etc. wrapped
> up in a format that can be used by a package management system to install
> it on a target system.

No dispute there.

> It is somewhat confusing that YP and OE use the term 'package' synonymously
> with 'recipe'. In most cases a package is the output of a recipe.

The thing is, we no longer do that - we've fixed a number of references in the 
documentation, help text and error messages for this release so that "recipe" 
is used when that's what we mean. If we've left any references that should be 
considered a bug.
 
> Unfortunately, changing variables like P, PN, PV, PR etc.
> may cause some pain. If a transition is what the broader community would
> like to achieve then a period where old and new variables can be used
> interchangeably (if possible) would be the way to go.

I'm not sure there's a huge amount to be gained by doing this when weighed 
against the cost - it would certainly cause a massive amount of churn, with 
the potential for problems with layer interaction where one layer has done the 
big rename and another that bbappends recipes in the first hasn't.

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre

Re: The term Package as used in the YP docs

[Rifenbark, Scott M]

I have tried to weed out the ambiguous use of "package" for this upcoming version of the manual set.  I don't think I would want to suggest changing any of the "P*" type variable names in the code.  I agree with Paul here that the potential for really messing things up out-weighs any other benefit.  This is why I was trying to worm in a bit of history behind those names for the people that might struggle like me.

Scott

-----Original Message-----
From: yocto-bounces@yoctoproject.org [mailto:yocto-bounces@yoctoproject.org] On Behalf Of Paul Eggleton
Sent: Friday, September 28, 2012 11:34 AM
To: Rudolf Streif
Cc: yocto@yoctoproject.org
Subject: Re: [yocto] The term Package as used in the YP docs

On Friday 28 September 2012 11:27:37 Rudolf Streif wrote:
> +1
> 
> I agree with Scott's definition. In the general Linux context a Package is
> a compilation of binaries, documentation, development files, etc. wrapped
> up in a format that can be used by a package management system to install
> it on a target system.

No dispute there.

> It is somewhat confusing that YP and OE use the term 'package' synonymously
> with 'recipe'. In most cases a package is the output of a recipe.

The thing is, we no longer do that - we've fixed a number of references in the 
documentation, help text and error messages for this release so that "recipe" 
is used when that's what we mean. If we've left any references that should be 
considered a bug.
 
> Unfortunately, changing variables like P, PN, PV, PR etc.
> may cause some pain. If a transition is what the broader community would
> like to achieve then a period where old and new variables can be used
> interchangeably (if possible) would be the way to go.

I'm not sure there's a huge amount to be gained by doing this when weighed 
against the cost - it would certainly cause a massive amount of churn, with 
the potential for problems with layer interaction where one layer has done the 
big rename and another that bbappends recipes in the first hasn't.

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre
_______________________________________________
yocto mailing list
yocto@yoctoproject.org
https://lists.yoctoproject.org/listinfo/yocto

Re: The term Package as used in the YP docs

[Rudolf Streif]

[-- Attachment #1: Type: text/plain, Size: 3022 bytes --]

I am not advocating changing the variable names. I know that this is a huge
undertaking and prone to many problems. This probably one of the many
legacy things people will have to live with and understand. In most cases
recipe name and version exactly reflect the name and version of the package
it is intended to build which to some extend mitigates the issue.

As far as the Terms section in the manuals is concerned, I see that you
already changed the describing text for the variables. That's sufficient, I
think.

:rjs

On Fri, Sep 28, 2012 at 11:37 AM, Rifenbark, Scott M <
scott.m.rifenbark@intel.com> wrote:

> I have tried to weed out the ambiguous use of "package" for this upcoming
> version of the manual set.  I don't think I would want to suggest changing
> any of the "P*" type variable names in the code.  I agree with Paul here
> that the potential for really messing things up out-weighs any other
> benefit.  This is why I was trying to worm in a bit of history behind those
> names for the people that might struggle like me.
>
> Scott
>
> -----Original Message-----
> From: yocto-bounces@yoctoproject.org [mailto:
> yocto-bounces@yoctoproject.org] On Behalf Of Paul Eggleton
> Sent: Friday, September 28, 2012 11:34 AM
> To: Rudolf Streif
> Cc: yocto@yoctoproject.org
> Subject: Re: [yocto] The term Package as used in the YP docs
>
> On Friday 28 September 2012 11:27:37 Rudolf Streif wrote:
> > +1
> >
> > I agree with Scott's definition. In the general Linux context a Package
> is
> > a compilation of binaries, documentation, development files, etc. wrapped
> > up in a format that can be used by a package management system to install
> > it on a target system.
>
> No dispute there.
>
> > It is somewhat confusing that YP and OE use the term 'package'
> synonymously
> > with 'recipe'. In most cases a package is the output of a recipe.
>
> The thing is, we no longer do that - we've fixed a number of references in
> the
> documentation, help text and error messages for this release so that
> "recipe"
> is used when that's what we mean. If we've left any references that should
> be
> considered a bug.
>
> > Unfortunately, changing variables like P, PN, PV, PR etc.
> > may cause some pain. If a transition is what the broader community would
> > like to achieve then a period where old and new variables can be used
> > interchangeably (if possible) would be the way to go.
>
> I'm not sure there's a huge amount to be gained by doing this when weighed
> against the cost - it would certainly cause a massive amount of churn, with
> the potential for problems with layer interaction where one layer has done
> the
> big rename and another that bbappends recipes in the first hasn't.
>
> Cheers,
> Paul
>
> --
>
> Paul Eggleton
> Intel Open Source Technology Centre
> _______________________________________________
> yocto mailing list
> yocto@yoctoproject.org
> https://lists.yoctoproject.org/listinfo/yocto
>

[-- Attachment #2: Type: text/html, Size: 3955 bytes --]

Re: The term Package as used in the YP docs

[Rifenbark, Scott M]

[-- Attachment #1: Type: text/plain, Size: 3479 bytes --]

Rudolf,

This is good feedback on the descriptions for the variable names Rudolf.  I did try and clean things up there a bit.

Thanks,
Scott

From: rstreif@linuxfoundation.org [mailto:rstreif@linuxfoundation.org] On Behalf Of Rudolf Streif
Sent: Friday, September 28, 2012 11:45 AM
To: Rifenbark, Scott M
Cc: Paul Eggleton; yocto@yoctoproject.org
Subject: Re: [yocto] The term Package as used in the YP docs

I am not advocating changing the variable names. I know that this is a huge undertaking and prone to many problems. This probably one of the many legacy things people will have to live with and understand. In most cases recipe name and version exactly reflect the name and version of the package it is intended to build which to some extend mitigates the issue.

As far as the Terms section in the manuals is concerned, I see that you already changed the describing text for the variables. That's sufficient, I think.

:rjs
On Fri, Sep 28, 2012 at 11:37 AM, Rifenbark, Scott M <scott.m.rifenbark@intel.com<mailto:scott.m.rifenbark@intel.com>> wrote:
I have tried to weed out the ambiguous use of "package" for this upcoming version of the manual set.  I don't think I would want to suggest changing any of the "P*" type variable names in the code.  I agree with Paul here that the potential for really messing things up out-weighs any other benefit.  This is why I was trying to worm in a bit of history behind those names for the people that might struggle like me.

Scott

-----Original Message-----
From: yocto-bounces@yoctoproject.org<mailto:yocto-bounces@yoctoproject.org> [mailto:yocto-bounces@yoctoproject.org<mailto:yocto-bounces@yoctoproject.org>] On Behalf Of Paul Eggleton
Sent: Friday, September 28, 2012 11:34 AM
To: Rudolf Streif
Cc: yocto@yoctoproject.org<mailto:yocto@yoctoproject.org>
Subject: Re: [yocto] The term Package as used in the YP docs
On Friday 28 September 2012 11:27:37 Rudolf Streif wrote:
> +1
>
> I agree with Scott's definition. In the general Linux context a Package is
> a compilation of binaries, documentation, development files, etc. wrapped
> up in a format that can be used by a package management system to install
> it on a target system.

No dispute there.

> It is somewhat confusing that YP and OE use the term 'package' synonymously
> with 'recipe'. In most cases a package is the output of a recipe.

The thing is, we no longer do that - we've fixed a number of references in the
documentation, help text and error messages for this release so that "recipe"
is used when that's what we mean. If we've left any references that should be
considered a bug.

> Unfortunately, changing variables like P, PN, PV, PR etc.
> may cause some pain. If a transition is what the broader community would
> like to achieve then a period where old and new variables can be used
> interchangeably (if possible) would be the way to go.

I'm not sure there's a huge amount to be gained by doing this when weighed
against the cost - it would certainly cause a massive amount of churn, with
the potential for problems with layer interaction where one layer has done the
big rename and another that bbappends recipes in the first hasn't.

Cheers,
Paul

--

Paul Eggleton
Intel Open Source Technology Centre
_______________________________________________
yocto mailing list
yocto@yoctoproject.org<mailto:yocto@yoctoproject.org>
https://lists.yoctoproject.org/listinfo/yocto


[-- Attachment #2: Type: text/html, Size: 7718 bytes --]

Re: The term Package as used in the YP docs

[Tim Bird]

On 09/28/2012 11:44 AM, Rudolf Streif wrote:
> I am not advocating changing the variable names. I know that this is a huge undertaking and prone to many problems. This probably one of the many legacy things people will have to live with and
> understand. In most cases recipe name and version exactly reflect the name and version of the package it is intended to build which to some extend mitigates the issue.
> 
> As far as the Terms section in the manuals is concerned, I see that you already changed the describing text for the variables. That's sufficient, I think.

(I answered Scott privately by mistake - here's some feedback on-list)

I'm in favor of mentioning the history somewhere, because the names
do have a 'P' in them, and this is confusing otherwise.

Overall, I think the new wording is worthwhile.
 -- Tim

=============================
Tim Bird
Architecture Group Chair, CE Workgroup of the Linux Foundation
Senior Staff Engineer, Sony Network Entertainment
=============================

Re: The term Package as used in the YP docs

[Trevor Woerner]

On Fri, Sep 28, 2012 at 2:34 PM, Paul Eggleton
<paul.eggleton@linux.intel.com> wrote:
> On Friday 28 September 2012 11:27:37 Rudolf Streif wrote:
>> Unfortunately, changing variables like P, PN, PV, PR etc.
>> may cause some pain. If a transition is what the broader community would
>> like to achieve then a period where old and new variables can be used
>> interchangeably (if possible) would be the way to go.
>
> I'm not sure there's a huge amount to be gained by doing this when weighed
> against the cost - it would certainly cause a massive amount of churn, with
> the potential for problems with layer interaction where one layer has done the
> big rename and another that bbappends recipes in the first hasn't.

Not that it matters in the grand scheme of things, but I would be in
favour of switching the variable names. Consistency is as consistency
does; if there's any hope people can stop confusing "poky" for
"yocto", "yocto" with "the yocto project", and "packages" for
"recipes" then it needs to be pervasively correct.

Provided the Yocto Project continues to grow, changes like this only
get harder with time, and if the project gets bigger (i.e. more uses)
the confusion only spreads further the longer it is left unchecked.

In any case I applaud all the efforts to standardize the wording,
especially in the documentation. As such I think it would be quite
helpful to have the proposed historical note included. Hopefully, the
sooner newcomers are aware of the issue, the less they're likely to
trip up over it.

Re: The term Package as used in the YP docs

[Brian Lloyd]

From the perspective of a new, easily confused and overwhelmed user, I
whole heartedly agree with the index entry.  And now it makes sense why
there is a PV to store version of a recipe.


On Fri, 2012-09-28 at 18:46 +0000, Rifenbark, Scott M wrote:
> Rudolf, 
> 
>  
> 
> This is good feedback on the descriptions for the variable names
> Rudolf.  I did try and clean things up there a bit. 
> 
>  
> 
> Thanks,
> 
> Scott
> 
>  
> 
> From: rstreif@linuxfoundation.org [mailto:rstreif@linuxfoundation.org]
> On Behalf Of Rudolf Streif
> Sent: Friday, September 28, 2012 11:45 AM
> To: Rifenbark, Scott M
> Cc: Paul Eggleton; yocto@yoctoproject.org
> Subject: Re: [yocto] The term Package as used in the YP docs
> 
> 
>  
> 
> I am not advocating changing the variable names. I know that this is a
> huge undertaking and prone to many problems. This probably one of the
> many legacy things people will have to live with and understand. In
> most cases recipe name and version exactly reflect the name and
> version of the package it is intended to build which to some extend
> mitigates the issue.
> 
>  
> 
> 
> As far as the Terms section in the manuals is concerned, I see that
> you already changed the describing text for the variables. That's
> sufficient, I think.
> 
> 
>  
> 
> 
> :rjs
> 
> On Fri, Sep 28, 2012 at 11:37 AM, Rifenbark, Scott M
> <scott.m.rifenbark@intel.com> wrote:
> 
> I have tried to weed out the ambiguous use of "package" for this
> upcoming version of the manual set.  I don't think I would want to
> suggest changing any of the "P*" type variable names in the code.  I
> agree with Paul here that the potential for really messing things up
> out-weighs any other benefit.  This is why I was trying to worm in a
> bit of history behind those names for the people that might struggle
> like me.
> 
> Scott
> 
> 
> -----Original Message-----
> From: yocto-bounces@yoctoproject.org
> [mailto:yocto-bounces@yoctoproject.org] On Behalf Of Paul Eggleton
> Sent: Friday, September 28, 2012 11:34 AM
> To: Rudolf Streif
> Cc: yocto@yoctoproject.org
> Subject: Re: [yocto] The term Package as used in the YP docs
> 
> 
> On Friday 28 September 2012 11:27:37 Rudolf Streif wrote:
> > +1
> >
> > I agree with Scott's definition. In the general Linux context a
> Package is
> > a compilation of binaries, documentation, development files, etc.
> wrapped
> > up in a format that can be used by a package management system to
> install
> > it on a target system.
> 
> No dispute there.
> 
> > It is somewhat confusing that YP and OE use the term 'package'
> synonymously
> > with 'recipe'. In most cases a package is the output of a recipe.
> 
> The thing is, we no longer do that - we've fixed a number of
> references in the
> documentation, help text and error messages for this release so that
> "recipe"
> is used when that's what we mean. If we've left any references that
> should be
> considered a bug.
> 
> > Unfortunately, changing variables like P, PN, PV, PR etc.
> > may cause some pain. If a transition is what the broader community
> would
> > like to achieve then a period where old and new variables can be
> used
> > interchangeably (if possible) would be the way to go.
> 
> I'm not sure there's a huge amount to be gained by doing this when
> weighed
> against the cost - it would certainly cause a massive amount of churn,
> with
> the potential for problems with layer interaction where one layer has
> done the
> big rename and another that bbappends recipes in the first hasn't.
> 
> Cheers,
> Paul
> 
> --
> 
> Paul Eggleton
> Intel Open Source Technology Centre
> 
> 
> _______________________________________________
> yocto mailing list
> yocto@yoctoproject.org
> https://lists.yoctoproject.org/listinfo/yocto
> 
> 
>  
> 
> 
> _______________________________________________
> yocto mailing list
> yocto@yoctoproject.org
> https://lists.yoctoproject.org/listinfo/yocto