can all of the licensing discussion be centralized in an appendix?

can all of the licensing discussion be centralized in an appendix?

[Robert P. J. Day]

  still clawing my way through the ref manual and it seems that
there's *way* too much coverage of licensing sprinkled throughout.
most people are not going to care about licensing until the time comes
to maybe start distributing their BSP.

  as it stands, in the *development* version of the ref manual,
section 3.4 is all about licensing, then ch 4 is essentially the BSP
guide where section 4.2.1 is "License Files" and all of section 4.3 is
"BSP Licensing Considerations."

  that just seems like too much licensing info that breaks up the flow
of the reference manual.  can all of that be moved to one location and
referenced from there?

rday

p.s.  i'm also not keen on an entire chapter of the ref manual being
nothing more than an include of the BSP guide.  if you've got a
perfectly respectable BSP guide, there's no point having it magically
appear as part of another manual.  but that's just my $0.02.

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: can all of the licensing discussion be centralized in an appendix?

[Rifenbark, Scott M]

Is BSP licensing different than non-BSP licensing?  If not, then licensing could be combined into a single section.  Can someone answer this for me?

Also, good point on the BSP guide appearing as a chapter in the reference manual.  I have not liked this.  Is there any rational reason to have it this way?

Scott

-----Original Message-----
From: yocto-bounces@yoctoproject.org [mailto:yocto-bounces@yoctoproject.org] On Behalf Of Robert P. J. Day
Sent: Monday, March 26, 2012 5:53 AM
To: Yocto discussion list
Subject: [yocto] can all of the licensing discussion be centralized in an appendix?


  still clawing my way through the ref manual and it seems that
there's *way* too much coverage of licensing sprinkled throughout.
most people are not going to care about licensing until the time comes
to maybe start distributing their BSP.

  as it stands, in the *development* version of the ref manual,
section 3.4 is all about licensing, then ch 4 is essentially the BSP
guide where section 4.2.1 is "License Files" and all of section 4.3 is
"BSP Licensing Considerations."

  that just seems like too much licensing info that breaks up the flow
of the reference manual.  can all of that be moved to one location and
referenced from there?

rday

p.s.  i'm also not keen on an entire chapter of the ref manual being
nothing more than an include of the BSP guide.  if you've got a
perfectly respectable BSP guide, there's no point having it magically
appear as part of another manual.  but that's just my $0.02.

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================
_______________________________________________
yocto mailing list
yocto@yoctoproject.org
https://lists.yoctoproject.org/listinfo/yocto

Re: can all of the licensing discussion be centralized in an appendix?

[Tom Zanussi]

On Mon, 2012-03-26 at 14:26 +0000, Rifenbark, Scott M wrote:
> Is BSP licensing different than non-BSP licensing?  If not, then licensing could be combined into a single section.  Can someone answer this for me?
> 

The focus of those sections are different and should probably be in
separate sections - the BSP licensing section of the BSP Guide deals
mainly with the licensing considerations affecting BSP images, while the
rest of the Manual deals with the nuts and bolts of how to deal with
licenses when writing recipes.

> Also, good point on the BSP guide appearing as a chapter in the reference manual.  I have not liked this.  Is there any rational reason to have it this way?
> 

I guess it's there for convenience, but the only reason I can see for
keeping it there other than that is that it's the only chapter that
deals with the kernel.

It would probably make sense would be to remove everything in the the
BSP Guide from the reference manual, except for the kernel section,
which should stay since it's of general interest and not just to people
dealing with BSPs.

Does that make sense?

Tom

> Scott
> 
> -----Original Message-----
> From: yocto-bounces@yoctoproject.org [mailto:yocto-bounces@yoctoproject.org] On Behalf Of Robert P. J. Day
> Sent: Monday, March 26, 2012 5:53 AM
> To: Yocto discussion list
> Subject: [yocto] can all of the licensing discussion be centralized in an appendix?
> 
> 
>   still clawing my way through the ref manual and it seems that
> there's *way* too much coverage of licensing sprinkled throughout.
> most people are not going to care about licensing until the time comes
> to maybe start distributing their BSP.
> 
>   as it stands, in the *development* version of the ref manual,
> section 3.4 is all about licensing, then ch 4 is essentially the BSP
> guide where section 4.2.1 is "License Files" and all of section 4.3 is
> "BSP Licensing Considerations."
> 
>   that just seems like too much licensing info that breaks up the flow
> of the reference manual.  can all of that be moved to one location and
> referenced from there?
> 
> rday
> 
> p.s.  i'm also not keen on an entire chapter of the ref manual being
> nothing more than an include of the BSP guide.  if you've got a
> perfectly respectable BSP guide, there's no point having it magically
> appear as part of another manual.  but that's just my $0.02.
> 

Re: can all of the licensing discussion be centralized in an appendix?

[Rudolf Streif]

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

>
> >> there's *way* too much coverage of licensing sprinkled throughout.
> >> most people are not going to care about licensing until the time comes
> >> to maybe start distributing their BSP.
>
> The ability of collecting licensing information, tracking license changes
and providing the license information automatically with the images and
packages for deployment is in my opinion a major feature of Yocto albeit
underestimated. Most people will only appreciate it once they have to
deliver that information with a product for the end user. However, it
starts much earlier, with the recipe.

How to include licensing tracking information with your recipe needs to be
part of the section explaining how to write recipes of the reference
manual. In both, the current 1.1 and the upcoming 1.1.1, versions of the
manual the license tracking section is a little disjoint from the sections
explaining how to add packages/recipes in my opinion. The examples include
the license tracking info, of course because otherwise the sanity checker
will not allow building the recipe, but they don't explain that you
actually need it (unless you use LICENSE = "CLOSED").

Since the license tracking and deployment feature follows the rule "garbage
in, garbage out" the manual cannot stress enough providing the correct info
in particular when writing recipes for upstream projects.

Side note: And nice features for a future release are SPDX info (already
worked on as far as I know) and providing the license info in
${TMPDIR}/deploy/licenses according to the images in ${TMPDIR}/images so
that one knows what licenses are in use for what image. That would be very
convenient when building multiple images with different package content.

Rudi

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

Re: can all of the licensing discussion be centralized in an appendix?

[Rifenbark, Scott M]

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

Rudi,

I would like you to examine the "latest" documents (the ones under development).  I have added some new licensing information and would like your feedback for this upcoming version.  There are licensing discussions in both the latest versions of the BSP Guide and the reference manual.  Since, at the moment, the BSP Guide is included as a chapter in the reference manual, I'll point you to the latest version of the reference manual:

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


Thanks,
Scott

From: yocto-bounces@yoctoproject.org [mailto:yocto-bounces@yoctoproject.org] On Behalf Of Rudolf Streif
Sent: Monday, March 26, 2012 2:52 PM
To: yocto@yoctoproject.org
Subject: Re: [yocto] can all of the licensing discussion be centralized in an appendix?

>> there's *way* too much coverage of licensing sprinkled throughout.
>> most people are not going to care about licensing until the time comes
>> to maybe start distributing their BSP.
The ability of collecting licensing information, tracking license changes and providing the license information automatically with the images and packages for deployment is in my opinion a major feature of Yocto albeit underestimated. Most people will only appreciate it once they have to deliver that information with a product for the end user. However, it starts much earlier, with the recipe.

How to include licensing tracking information with your recipe needs to be part of the section explaining how to write recipes of the reference manual. In both, the current 1.1 and the upcoming 1.1.1, versions of the manual the license tracking section is a little disjoint from the sections explaining how to add packages/recipes in my opinion. The examples include the license tracking info, of course because otherwise the sanity checker will not allow building the recipe, but they don't explain that you actually need it (unless you use LICENSE = "CLOSED").

Since the license tracking and deployment feature follows the rule "garbage in, garbage out" the manual cannot stress enough providing the correct info in particular when writing recipes for upstream projects.

Side note: And nice features for a future release are SPDX info (already worked on as far as I know) and providing the license info in ${TMPDIR}/deploy/licenses according to the images in ${TMPDIR}/images so that one knows what licenses are in use for what image. That would be very convenient when building multiple images with different package content.

Rudi

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

Re: can all of the licensing discussion be centralized in an appendix?

[Rudolf Streif]

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

Scott,

 **
>
> >>
> http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html
> .****
>
> ** **
>
> Yes, I looked at that one but I now noticed that I referenced it
incorrectly. This is the latest version, however, in the revision history
it shows "Revision 1.1, October 6, 2011, Released with the Yocto Project
Release 1.1".

Now, this one
http://www.yoctoproject.org/docs/current/poky-ref-manual/poky-ref-manual.html
is
the current one but its revision history shows "Revision 1.1.1, March 15,
2012, Released with the Yocto Project Release 1.1.1".

Ok, now I get how I confused myself successfully. I presume that the first
is the newer one although its revision history suggests otherwise? Would
you mind updating the revision history with something like "Revision 1.2,
WIP, To be released with Yocto Project Release 1.2"?

The latest one does not seem to have a section about writing recipes
anymore at all. Are you planning on putting it back? While the previous one
had a section on writing recipes it did so in a "vacuum". It told you how
to write a recipe but not really where to put it and how to include it with
an image. The latter it explained in the next section about customizing an
image.

The info about the licensing is great and dead-nuts on, however, a reader
new to the Yocto Project would be missing the context. A good add-on to
that paragraph would be that if you omit the md5 parameter in the
LIC_FILES_CHKSUM variable Bitbake will actually spit it out for you which
is in particular useful if the checksum is calculated over a subset of a
license file specified by startline and endline because md5sum won't easily
do that for you.


These are my suggestions:

* Remove 3.3 x32 and 3.4 Licenses from section 3. Section 3 currently looks
a little bit like a kitchen sink. The first two paragraphs deal with build
system components and architecture, x32 then mixes a very specific
technology into it for particular targets, and then Licenses tops it off
with package licensing details. I would dedicate Section 3 to Yocto Project
Build System Architecture only.

* Then I would dedicate a section 4 to Build Customization:
** The first subsection could deal with the most trivial customization
through local.conf: EXTRA_IMAGE_FEATURES, IMAGE_INSTALL_append and
CORE_IMAGE_EXTRA_INSTALL (formerly known as POKY_EXTRA_INSTALL)
** The second subsection should then explain how to create your own layer
within the build environment because before adding any recipe you need to
have a layer to add it to. Mixing your own recipes in with meta or
meta-yocto works but is not sustainable when upgrading to a newer release
of the Yocto Project. And it's good practice too to keep your own stuff
separate.
** The third subsection should then explain how to extend images writing
your own recipes:
*** writing a recipe that includes a base image and then adds more packages:
    require recipes-core/images/core-imabg-base.bb
    IMAGE_INSTALL += "strace"
*** writing an image that inherits from core-image
    IMAGE_INSTALL = "task-core-boot task-core-extended"
    IMAGE_FEATURES += "blabla"
    inherit core-image
** the fourth subsection should then explain how to add your own packages
with your own recipes. Now you already have everything in place: a layer to
add to and a ways of including your recipes with an image. And here we then
also need to explain the licensing stuff because recipes for building
packages won't fly without.
** the fifth section should then just reference the BSP manual for BSPs.

Finally for my concept, we need to find a home for x32. I would put that
under an "Advanced Topics" section which could act as a container for other
stuff too such as multi-lib etc.

Rudi


>
>
> *From:* yocto-bounces@yoctoproject.org [mailto:
> yocto-bounces@yoctoproject.org] *On Behalf Of *Rudolf Streif
> *Sent:* Monday, March 26, 2012 2:52 PM
> *To:* yocto@yoctoproject.org
> *Subject:* Re: [yocto] can all of the licensing discussion be centralized
> in an appendix?****
>
> ** **
>
> >> there's *way* too much coverage of licensing sprinkled throughout.
> >> most people are not going to care about licensing until the time comes
> >> to maybe start distributing their BSP.****
>
>  The ability of collecting licensing information, tracking license
> changes and providing the license information automatically with the images
> and packages for deployment is in my opinion a major feature of Yocto
> albeit underestimated. Most people will only appreciate it once they have
> to deliver that information with a product for the end user. However, it
> starts much earlier, with the recipe.****
>
> ** **
>
> How to include licensing tracking information with your recipe needs to be
> part of the section explaining how to write recipes of the reference
> manual. In both, the current 1.1 and the upcoming 1.1.1, versions of the
> manual the license tracking section is a little disjoint from the sections
> explaining how to add packages/recipes in my opinion. The examples include
> the license tracking info, of course because otherwise the sanity checker
> will not allow building the recipe, but they don't explain that you
> actually need it (unless you use LICENSE = "CLOSED").****
>
> ** **
>
> Since the license tracking and deployment feature follows the rule
> "garbage in, garbage out" the manual cannot stress enough providing the
> correct info in particular when writing recipes for upstream projects.****
>
> ** **
>
> Side note: And nice features for a future release are SPDX info (already
> worked on as far as I know) and providing the license info in
> ${TMPDIR}/deploy/licenses according to the images in ${TMPDIR}/images so
> that one knows what licenses are in use for what image. That would be very
> convenient when building multiple images with different package content.**
> **
>
> ** **
>
> Rudi****
>

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

Re: can all of the licensing discussion be centralized in an appendix?

[Rifenbark, Scott M]

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

Rudi,

Great comments!  Thanks very much.  I will immediately update the revision history tables to show the 1.2 release as WIP.  Not having it there did cause you confusion.  Good suggestion.

Regarding your other observations.  If you have the time I would appreciate you looking at the YP Development manual, particularly Chapter 4.  Much of the "how-to" stuff that was in the YP reference manual has been moved to there.  "Adding a Package" section that you noted was now missing is in fact in that area.  Let me give you some background on the strategy of the two manuals....

I am trying to eventually turn the YP reference guide into a "reference" guide with minimal "how-to" information.  That is the long-term goal.  The YP Development Manual has been getting some how-to stuff added to it.  Chapter 4 (Common Tasks) tells how to create layers, add a package, customize images, etc.).

Here is the link to the "latest" YP Development Manual:  http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html.  With this new context, maybe you can augment or comment on your previous comments :)

I appreciate your help,
Scott

From: rstreif@linuxfoundation.org [mailto:rstreif@linuxfoundation.org] On Behalf Of Rudolf Streif
Sent: Monday, March 26, 2012 4:02 PM
To: Rifenbark, Scott M
Cc: yocto@yoctoproject.org
Subject: Re: [yocto] can all of the licensing discussion be centralized in an appendix?

Scott,


>> http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html.

Yes, I looked at that one but I now noticed that I referenced it incorrectly. This is the latest version, however, in the revision history it shows "Revision 1.1, October 6, 2011, Released with the Yocto Project Release 1.1".

Now, this one http://www.yoctoproject.org/docs/current/poky-ref-manual/poky-ref-manual.html is the current one but its revision history shows "Revision 1.1.1, March 15, 2012, Released with the Yocto Project Release 1.1.1".

Ok, now I get how I confused myself successfully. I presume that the first is the newer one although its revision history suggests otherwise? Would you mind updating the revision history with something like "Revision 1.2, WIP, To be released with Yocto Project Release 1.2"?

The latest one does not seem to have a section about writing recipes anymore at all. Are you planning on putting it back? While the previous one had a section on writing recipes it did so in a "vacuum". It told you how to write a recipe but not really where to put it and how to include it with an image. The latter it explained in the next section about customizing an image.

The info about the licensing is great and dead-nuts on, however, a reader new to the Yocto Project would be missing the context. A good add-on to that paragraph would be that if you omit the md5 parameter in the LIC_FILES_CHKSUM variable Bitbake will actually spit it out for you which is in particular useful if the checksum is calculated over a subset of a license file specified by startline and endline because md5sum won't easily do that for you.


These are my suggestions:

* Remove 3.3 x32 and 3.4 Licenses from section 3. Section 3 currently looks a little bit like a kitchen sink. The first two paragraphs deal with build system components and architecture, x32 then mixes a very specific technology into it for particular targets, and then Licenses tops it off with package licensing details. I would dedicate Section 3 to Yocto Project Build System Architecture only.

* Then I would dedicate a section 4 to Build Customization:
** The first subsection could deal with the most trivial customization through local.conf: EXTRA_IMAGE_FEATURES, IMAGE_INSTALL_append and CORE_IMAGE_EXTRA_INSTALL (formerly known as POKY_EXTRA_INSTALL)
** The second subsection should then explain how to create your own layer within the build environment because before adding any recipe you need to have a layer to add it to. Mixing your own recipes in with meta or meta-yocto works but is not sustainable when upgrading to a newer release of the Yocto Project. And it's good practice too to keep your own stuff separate.
** The third subsection should then explain how to extend images writing your own recipes:
*** writing a recipe that includes a base image and then adds more packages:
    require recipes-core/images/core-imabg-base.bb<http://core-imabg-base.bb>
    IMAGE_INSTALL += "strace"
*** writing an image that inherits from core-image
    IMAGE_INSTALL = "task-core-boot task-core-extended"
    IMAGE_FEATURES += "blabla"
    inherit core-image
** the fourth subsection should then explain how to add your own packages with your own recipes. Now you already have everything in place: a layer to add to and a ways of including your recipes with an image. And here we then also need to explain the licensing stuff because recipes for building packages won't fly without.
** the fifth section should then just reference the BSP manual for BSPs.

Finally for my concept, we need to find a home for x32. I would put that under an "Advanced Topics" section which could act as a container for other stuff too such as multi-lib etc.

Rudi


From: yocto-bounces@yoctoproject.org<mailto:yocto-bounces@yoctoproject.org> [mailto:yocto-bounces@yoctoproject.org<mailto:yocto-bounces@yoctoproject.org>] On Behalf Of Rudolf Streif
Sent: Monday, March 26, 2012 2:52 PM
To: yocto@yoctoproject.org<mailto:yocto@yoctoproject.org>
Subject: Re: [yocto] can all of the licensing discussion be centralized in an appendix?

>> there's *way* too much coverage of licensing sprinkled throughout.
>> most people are not going to care about licensing until the time comes
>> to maybe start distributing their BSP.
The ability of collecting licensing information, tracking license changes and providing the license information automatically with the images and packages for deployment is in my opinion a major feature of Yocto albeit underestimated. Most people will only appreciate it once they have to deliver that information with a product for the end user. However, it starts much earlier, with the recipe.

How to include licensing tracking information with your recipe needs to be part of the section explaining how to write recipes of the reference manual. In both, the current 1.1 and the upcoming 1.1.1, versions of the manual the license tracking section is a little disjoint from the sections explaining how to add packages/recipes in my opinion. The examples include the license tracking info, of course because otherwise the sanity checker will not allow building the recipe, but they don't explain that you actually need it (unless you use LICENSE = "CLOSED").

Since the license tracking and deployment feature follows the rule "garbage in, garbage out" the manual cannot stress enough providing the correct info in particular when writing recipes for upstream projects.

Side note: And nice features for a future release are SPDX info (already worked on as far as I know) and providing the license info in ${TMPDIR}/deploy/licenses according to the images in ${TMPDIR}/images so that one knows what licenses are in use for what image. That would be very convenient when building multiple images with different package content.

Rudi


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

Re: can all of the licensing discussion be centralized in an appendix?

[Rudolf Streif]

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

Scott,

That's great. The dev manual is very comprehensive and at the right level
of detail. I think many new as well as more experienced users of YP will
appreciate it. From a quick read the only suggestion I have for now is to
place the section on "Customizing Images" before the section on "Adding
Packages". Most users will probably first build custom images by adding
packages using readily available recipes before writing recipes for their
own packages.

The reference sections in the reference manual are great. The other
sections need more work on coherence. Layers should be added, also a
section that deals with the syntax and semantics of setting variables e.g.
+=, .= vs. _append etc. This is where most people get confused.

Another thing worth explaining in the reference manual is the use of the
Bitbake data structures in Python functions in recipes. This is where I can
see folks pulling their hair out too.

I will keep on rummaging through.

Rudi




On Mon, Mar 26, 2012 at 3:28 PM, Rifenbark, Scott M <
scott.m.rifenbark@intel.com> wrote:

>  Rudi, ****
>
> ** **
>
> Great comments!  Thanks very much.  I will immediately update the revision
> history tables to show the 1.2 release as WIP.  Not having it there did
> cause you confusion.  Good suggestion. ****
>
> ** **
>
> Regarding your other observations.  If you have the time I would
> appreciate you looking at the YP Development manual, particularly Chapter
> 4.  Much of the “how-to” stuff that was in the YP reference manual has been
> moved to there.  “Adding a Package” section that you noted was now missing
> is in fact in that area.  Let me give you some background on the strategy
> of the two manuals….****
>
> ** **
>
> I am trying to eventually turn the YP reference guide into a “reference”
> guide with minimal “how-to” information.  That is the long-term goal.  The
> YP Development Manual has been getting some how-to stuff added to it.
> Chapter 4 (Common Tasks) tells how to create layers, add a package,
> customize images, etc.).  ****
>
> ** **
>
> Here is the link to the “latest” YP Development Manual:
> http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html.  With
> this new context, maybe you can augment or comment on your previous
> comments J****
>
> ** **
>
> I appreciate your help, ****
>
> Scott****
>
> ** **
>
> *From:* rstreif@linuxfoundation.org [mailto:rstreif@linuxfoundation.org] *On
> Behalf Of *Rudolf Streif
> *Sent:* Monday, March 26, 2012 4:02 PM
> *To:* Rifenbark, Scott M
> *Cc:* yocto@yoctoproject.org
>
> *Subject:* Re: [yocto] can all of the licensing discussion be centralized
> in an appendix?****
>
>  ** **
>
> Scott,****
>
> ** **
>
>   ****
>
> >>
> http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html
> .****
>
>  ****
>
>  Yes, I looked at that one but I now noticed that I referenced it
> incorrectly. This is the latest version, however, in the revision history
> it shows "Revision 1.1, October 6, 2011, Released with the Yocto Project
> Release 1.1".****
>
> ** **
>
> Now, this one
> http://www.yoctoproject.org/docs/current/poky-ref-manual/poky-ref-manual.html is
> the current one but its revision history shows "Revision 1.1.1, March 15,
> 2012, Released with the Yocto Project Release 1.1.1".****
>
> ** **
>
> Ok, now I get how I confused myself successfully. I presume that the first
> is the newer one although its revision history suggests otherwise? Would
> you mind updating the revision history with something like "Revision 1.2,
> WIP, To be released with Yocto Project Release 1.2"?****
>
> ** **
>
> The latest one does not seem to have a section about writing recipes
> anymore at all. Are you planning on putting it back? While the previous one
> had a section on writing recipes it did so in a "vacuum". It told you how
> to write a recipe but not really where to put it and how to include it with
> an image. The latter it explained in the next section about customizing an
> image.****
>
> ** **
>
> The info about the licensing is great and dead-nuts on, however, a reader
> new to the Yocto Project would be missing the context. A good add-on to
> that paragraph would be that if you omit the md5 parameter in the
> LIC_FILES_CHKSUM variable Bitbake will actually spit it out for you which
> is in particular useful if the checksum is calculated over a subset of a
> license file specified by startline and endline because md5sum won't easily
> do that for you.****
>
> ** **
>
> ** **
>
> These are my suggestions:****
>
> ** **
>
> * Remove 3.3 x32 and 3.4 Licenses from section 3. Section 3 currently
> looks a little bit like a kitchen sink. The first two paragraphs deal with
> build system components and architecture, x32 then mixes a very specific
> technology into it for particular targets, and then Licenses tops it off
> with package licensing details. I would dedicate Section 3 to Yocto Project
> Build System Architecture only.****
>
> ** **
>
> * Then I would dedicate a section 4 to Build Customization:****
>
> ** The first subsection could deal with the most trivial customization
> through local.conf: EXTRA_IMAGE_FEATURES, IMAGE_INSTALL_append and
> CORE_IMAGE_EXTRA_INSTALL (formerly known as POKY_EXTRA_INSTALL)****
>
> ** The second subsection should then explain how to create your own layer
> within the build environment because before adding any recipe you need to
> have a layer to add it to. Mixing your own recipes in with meta or
> meta-yocto works but is not sustainable when upgrading to a newer release
> of the Yocto Project. And it's good practice too to keep your own stuff
> separate.****
>
> ** The third subsection should then explain how to extend images writing
> your own recipes:****
>
> *** writing a recipe that includes a base image and then adds more
> packages:****
>
>     require recipes-core/images/core-imabg-base.bb****
>
>     IMAGE_INSTALL += "strace"****
>
> *** writing an image that inherits from core-image****
>
>     IMAGE_INSTALL = "task-core-boot task-core-extended"****
>
>     IMAGE_FEATURES += "blabla"****
>
>     inherit core-image****
>
> ** the fourth subsection should then explain how to add your own packages
> with your own recipes. Now you already have everything in place: a layer to
> add to and a ways of including your recipes with an image. And here we then
> also need to explain the licensing stuff because recipes for building
> packages won't fly without.****
>
> ** the fifth section should then just reference the BSP manual for BSPs.**
> **
>
> ** **
>
> Finally for my concept, we need to find a home for x32. I would put that
> under an "Advanced Topics" section which could act as a container for other
> stuff too such as multi-lib etc.****
>
> ** **
>
> Rudi****
>
>  ****
>
>   ****
>
> *From:* yocto-bounces@yoctoproject.org [mailto:
> yocto-bounces@yoctoproject.org] *On Behalf Of *Rudolf Streif
> *Sent:* Monday, March 26, 2012 2:52 PM
> *To:* yocto@yoctoproject.org
> *Subject:* Re: [yocto] can all of the licensing discussion be centralized
> in an appendix?****
>
>  ****
>
> >> there's *way* too much coverage of licensing sprinkled throughout.
> >> most people are not going to care about licensing until the time comes
> >> to maybe start distributing their BSP.****
>
>  The ability of collecting licensing information, tracking license
> changes and providing the license information automatically with the images
> and packages for deployment is in my opinion a major feature of Yocto
> albeit underestimated. Most people will only appreciate it once they have
> to deliver that information with a product for the end user. However, it
> starts much earlier, with the recipe.****
>
>  ****
>
> How to include licensing tracking information with your recipe needs to be
> part of the section explaining how to write recipes of the reference
> manual. In both, the current 1.1 and the upcoming 1.1.1, versions of the
> manual the license tracking section is a little disjoint from the sections
> explaining how to add packages/recipes in my opinion. The examples include
> the license tracking info, of course because otherwise the sanity checker
> will not allow building the recipe, but they don't explain that you
> actually need it (unless you use LICENSE = "CLOSED").****
>
>  ****
>
> Since the license tracking and deployment feature follows the rule
> "garbage in, garbage out" the manual cannot stress enough providing the
> correct info in particular when writing recipes for upstream projects.****
>
>  ****
>
> Side note: And nice features for a future release are SPDX info (already
> worked on as far as I know) and providing the license info in
> ${TMPDIR}/deploy/licenses according to the images in ${TMPDIR}/images so
> that one knows what licenses are in use for what image. That would be very
> convenient when building multiple images with different package content.**
> **
>
>  ****
>
> Rudi****
>
>  ** **
>

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

Re: can all of the licensing discussion be centralized in an appendix?

[Rifenbark, Scott M]

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

Rudi,

Thanks for taking the time to look this stuff over.  I will place customizing images ahead of adding packages in the dev manual.

I will dig into the other issues and see what I can get in the way of information from the development team.

Scott

From: rstreif@linuxfoundation.org [mailto:rstreif@linuxfoundation.org] On Behalf Of Rudolf Streif
Sent: Thursday, March 29, 2012 1:05 PM
To: Rifenbark, Scott M
Cc: yocto@yoctoproject.org
Subject: Re: [yocto] can all of the licensing discussion be centralized in an appendix?

Scott,

That's great. The dev manual is very comprehensive and at the right level of detail. I think many new as well as more experienced users of YP will appreciate it. From a quick read the only suggestion I have for now is to place the section on "Customizing Images" before the section on "Adding Packages". Most users will probably first build custom images by adding packages using readily available recipes before writing recipes for their own packages.

The reference sections in the reference manual are great. The other sections need more work on coherence. Layers should be added, also a section that deals with the syntax and semantics of setting variables e.g. +=, .= vs. _append etc. This is where most people get confused.

Another thing worth explaining in the reference manual is the use of the Bitbake data structures in Python functions in recipes. This is where I can see folks pulling their hair out too.

I will keep on rummaging through.

Rudi



On Mon, Mar 26, 2012 at 3:28 PM, Rifenbark, Scott M <scott.m.rifenbark@intel.com<mailto:scott.m.rifenbark@intel.com>> wrote:
Rudi,

Great comments!  Thanks very much.  I will immediately update the revision history tables to show the 1.2 release as WIP.  Not having it there did cause you confusion.  Good suggestion.

Regarding your other observations.  If you have the time I would appreciate you looking at the YP Development manual, particularly Chapter 4.  Much of the "how-to" stuff that was in the YP reference manual has been moved to there.  "Adding a Package" section that you noted was now missing is in fact in that area.  Let me give you some background on the strategy of the two manuals....

I am trying to eventually turn the YP reference guide into a "reference" guide with minimal "how-to" information.  That is the long-term goal.  The YP Development Manual has been getting some how-to stuff added to it.  Chapter 4 (Common Tasks) tells how to create layers, add a package, customize images, etc.).

Here is the link to the "latest" YP Development Manual:  http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html.  With this new context, maybe you can augment or comment on your previous comments :)

I appreciate your help,
Scott

From: rstreif@linuxfoundation.org<mailto:rstreif@linuxfoundation.org> [mailto:rstreif@linuxfoundation.org<mailto:rstreif@linuxfoundation.org>] On Behalf Of Rudolf Streif
Sent: Monday, March 26, 2012 4:02 PM
To: Rifenbark, Scott M
Cc: yocto@yoctoproject.org<mailto:yocto@yoctoproject.org>

Subject: Re: [yocto] can all of the licensing discussion be centralized in an appendix?

Scott,


>> http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html.

Yes, I looked at that one but I now noticed that I referenced it incorrectly. This is the latest version, however, in the revision history it shows "Revision 1.1, October 6, 2011, Released with the Yocto Project Release 1.1".

Now, this one http://www.yoctoproject.org/docs/current/poky-ref-manual/poky-ref-manual.html is the current one but its revision history shows "Revision 1.1.1, March 15, 2012, Released with the Yocto Project Release 1.1.1".

Ok, now I get how I confused myself successfully. I presume that the first is the newer one although its revision history suggests otherwise? Would you mind updating the revision history with something like "Revision 1.2, WIP, To be released with Yocto Project Release 1.2"?

The latest one does not seem to have a section about writing recipes anymore at all. Are you planning on putting it back? While the previous one had a section on writing recipes it did so in a "vacuum". It told you how to write a recipe but not really where to put it and how to include it with an image. The latter it explained in the next section about customizing an image.

The info about the licensing is great and dead-nuts on, however, a reader new to the Yocto Project would be missing the context. A good add-on to that paragraph would be that if you omit the md5 parameter in the LIC_FILES_CHKSUM variable Bitbake will actually spit it out for you which is in particular useful if the checksum is calculated over a subset of a license file specified by startline and endline because md5sum won't easily do that for you.


These are my suggestions:

* Remove 3.3 x32 and 3.4 Licenses from section 3. Section 3 currently looks a little bit like a kitchen sink. The first two paragraphs deal with build system components and architecture, x32 then mixes a very specific technology into it for particular targets, and then Licenses tops it off with package licensing details. I would dedicate Section 3 to Yocto Project Build System Architecture only.

* Then I would dedicate a section 4 to Build Customization:
** The first subsection could deal with the most trivial customization through local.conf: EXTRA_IMAGE_FEATURES, IMAGE_INSTALL_append and CORE_IMAGE_EXTRA_INSTALL (formerly known as POKY_EXTRA_INSTALL)
** The second subsection should then explain how to create your own layer within the build environment because before adding any recipe you need to have a layer to add it to. Mixing your own recipes in with meta or meta-yocto works but is not sustainable when upgrading to a newer release of the Yocto Project. And it's good practice too to keep your own stuff separate.
** The third subsection should then explain how to extend images writing your own recipes:
*** writing a recipe that includes a base image and then adds more packages:
    require recipes-core/images/core-imabg-base.bb<http://core-imabg-base.bb>
    IMAGE_INSTALL += "strace"
*** writing an image that inherits from core-image
    IMAGE_INSTALL = "task-core-boot task-core-extended"
    IMAGE_FEATURES += "blabla"
    inherit core-image
** the fourth subsection should then explain how to add your own packages with your own recipes. Now you already have everything in place: a layer to add to and a ways of including your recipes with an image. And here we then also need to explain the licensing stuff because recipes for building packages won't fly without.
** the fifth section should then just reference the BSP manual for BSPs.

Finally for my concept, we need to find a home for x32. I would put that under an "Advanced Topics" section which could act as a container for other stuff too such as multi-lib etc.

Rudi


From: yocto-bounces@yoctoproject.org<mailto:yocto-bounces@yoctoproject.org> [mailto:yocto-bounces@yoctoproject.org<mailto:yocto-bounces@yoctoproject.org>] On Behalf Of Rudolf Streif
Sent: Monday, March 26, 2012 2:52 PM
To: yocto@yoctoproject.org<mailto:yocto@yoctoproject.org>
Subject: Re: [yocto] can all of the licensing discussion be centralized in an appendix?

>> there's *way* too much coverage of licensing sprinkled throughout.
>> most people are not going to care about licensing until the time comes
>> to maybe start distributing their BSP.
The ability of collecting licensing information, tracking license changes and providing the license information automatically with the images and packages for deployment is in my opinion a major feature of Yocto albeit underestimated. Most people will only appreciate it once they have to deliver that information with a product for the end user. However, it starts much earlier, with the recipe.

How to include licensing tracking information with your recipe needs to be part of the section explaining how to write recipes of the reference manual. In both, the current 1.1 and the upcoming 1.1.1, versions of the manual the license tracking section is a little disjoint from the sections explaining how to add packages/recipes in my opinion. The examples include the license tracking info, of course because otherwise the sanity checker will not allow building the recipe, but they don't explain that you actually need it (unless you use LICENSE = "CLOSED").

Since the license tracking and deployment feature follows the rule "garbage in, garbage out" the manual cannot stress enough providing the correct info in particular when writing recipes for upstream projects.

Side note: And nice features for a future release are SPDX info (already worked on as far as I know) and providing the license info in ${TMPDIR}/deploy/licenses according to the images in ${TMPDIR}/images so that one knows what licenses are in use for what image. That would be very convenient when building multiple images with different package content.

Rudi



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