Bug 8634

Summary: Document LICENSE_CREATE_PACKAGE feature
Product: [Documentation] Development Manual Reporter: Bevenson <bevenson>
Component: developmentAssignee: Scott Rifenbark <srifenbark>
Status: RESOLVED FIXED QA Contact:
Severity: normal    
Priority: Medium CC: bluelightning, srifenbark
Version: 2.0   
Target Milestone: 2.1 M4   
Hardware: x86   
OS: Multiple   
Whiteboard: 15 Feb 2016: IN PROGRESS REVIEW
OS type for building Yocto: --- Type of Regression: ---
Verified: Documentation change: Done (doc changes complete)
Bug Depends on: 8633    
Bug Blocks:    

Description Bevenson 2015-11-03 14:47:40 UTC 
Section 5.25.2 documents how to use COPY_LIC_DIRS and COPY_LIC_MANIFEST to create and copy the source code license texts and the license manifest into the image when the image is built.  There is also the variable LICENSE_CREATE_PACKAGE which creates a -lic package for each package in the image so the licenses can be included/updated on firmware upgrade. However, LICENSE_CREATE_PACKAGE is not described in this section or anywhere in the Development Manual.

Add documentation to the Development Manual to describe how to use this variable in relation to FOSS compliance.

Adding a dependency on bug 8633 as there is also no reference to this variable in the Variables Glossary.  Describing the variable in the Development Manual with no description of it in the Reference Manual could be confusing.
Comment 1 Scott Rifenbark 2016-02-05 23:18:13 UTC 
Hi, 

Please look at http://www.yoctoproject.org/docs/2.1/dev-manual/dev-manual.html#providing-license-text and let me know if this is adequate.  We do also now have an entry in the glossary for the LICENSE_CREATE_PACKAGE variable at http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#var-LICENSE_CREATE_PACKAGE.

Thanks,
Scott
Comment 2 Bevenson 2016-02-08 13:15:35 UTC 
As a user I'd also like to see a short paragraph describing the difference between the three variables as all three are not required to get the license files in the image.  COPY_LIC_DIRS and COPY_LIC_MANIFEST add copy of the licenses at image build time but do not offer a path for adding licenses for newly installed packages to an image; this may be most suitable (in my opinion) for read-only filesystems which cannot be upgraded.  LICENSE_CREATE_PACKAGE adds a separate package and an upgrade path for adding licenses to an image.  If all three variables are set to 1, then the image will have two copies of the same license file with one copy under /usr/share/common-licenses and the other under /usr/share/license.  This isn't immediately obvious unless someone is looking at the definition of COPY_LIC_DIRS and LICENSE_CREATE_PACKAGE at the same time.
Comment 3 Scott Rifenbark 2016-02-15 18:14:41 UTC 
There is a section in the dev-manual that addressed setting all these variables to "1".  I have added some explanation there in the form of a note that helps explains what is going on based on the information you provided.  See http://www.yoctoproject.org/docs/2.1/dev-manual/dev-manual.html#providing-license-text.

I have also added some further information to the variable descriptions in the glossary.  See the following:

 * http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#var-COPY_LIC_DIRS

 * http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#var-COPY_LIC_MANIFEST

 * http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#var-LICENSE_CREATE_PACKAGE

I have tried to cross-reference all this information to try and tie it together better for the user.

Scott
Comment 4 Bevenson 2016-02-15 18:55:55 UTC 
Scott,

The additional text is clear to me.  Thanks for adding this to the documentation.

Thanks,
Bryan
Comment 5 Scott Rifenbark 2016-02-15 19:05:30 UTC 
Great... thanks.  Resetting to RESOLVED and putting the doc flag to "done."

Scott