[PATCH] ref-manual: document image-specific variant of INCOMPATIBLE_LICENSE

[PATCH] ref-manual: document image-specific variant of INCOMPATIBLE_LICENSE

[Alexander Kanavin]

This has been around without being properly documented since 2019 (!!!),
and is nowadays the preferred method for enforcing license restrictions,
especially since meta-gplv2 is officially obsolete.

Signed-off-by: Alexander Kanavin <alex@linutronix.de>
---
 documentation/ref-manual/images.rst    | 16 +++++++++-------
 documentation/ref-manual/variables.rst | 13 +++++++++++--
 2 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/documentation/ref-manual/images.rst b/documentation/ref-manual/images.rst
index d3aeb0829..19c31e0fc 100644
--- a/documentation/ref-manual/images.rst
+++ b/documentation/ref-manual/images.rst
@@ -14,15 +14,17 @@ image you want.
    Building an image without GNU General Public License Version 3
    (GPLv3), GNU Lesser General Public License Version 3 (LGPLv3), and
    the GNU Affero General Public License Version 3 (AGPL-3.0) components
-   is only supported for minimal and base images. Furthermore, if you
-   are going to build an image using non-GPLv3 and similarly licensed
-   components, you must make the following changes in the ``local.conf``
-   file before using the BitBake command to build the minimal or base
-   image:
+   is only tested for core-image-minimal image. Furthermore, if you would like to
+   build an image and verify that it does not include GPLv3 and similarly licensed
+   components, you must make the following changes in the image recipe
+   file before using the BitBake command to build the image:
 
-   #. Comment out the :term:`EXTRA_IMAGE_FEATURES` line
+       INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0*"
 
-   #. Set :term:`INCOMPATIBLE_LICENSE` to "GPL-3.0* LGPL-3.0* AGPL-3.0*"
+   Alternatively, you can adjust ``local.conf`` file, repeating and adjusting the line
+   for all images where the license restriction must apply:
+
+       INCOMPATIBLE_LICENSE:pn:your-image-name = "GPL-3.0* LGPL-3.0*"
 
 From within the ``poky`` Git repository, you can use the following
 command to display the list of directories within the :term:`Source Directory`
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index ac5b97a52..e0d3b880d 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3905,9 +3905,18 @@ system and gives an overview of their function and contents.
    :term:`INCOMPATIBLE_LICENSE`
       Specifies a space-separated list of license names (as they would
       appear in :term:`LICENSE`) that should be excluded
-      from the build. Recipes that provide no alternatives to listed
+      from the build (if set globally), or from an image (if set locally
+      in an image recipe). 
+
+      When the variable is set globally, recipes that provide no alternatives to listed
       incompatible licenses are not built. Packages that are individually
-      licensed with the specified incompatible licenses will be deleted.
+      licensed with the specified incompatible licenses will be deleted. 
+      Most of the time this does not allow a feasible build (because it becomes impossible
+      to satisfy build time dependencies), so the recommended way to
+      implement license restrictions is to set the variable in specific
+      image recipes where the restrictions must apply. That way there 
+      are no build time restrictions, but the license check is still
+      performed when the image's filesystem is assembled from packages.
 
       There is some support for wildcards in this variable's value,
       however it is restricted to specific licenses. Currently only
-- 
2.30.2

Re: [docs] [PATCH] ref-manual: document image-specific variant of INCOMPATIBLE_LICENSE

[Michael Opdenacker]

Hi Alex,

On 28.07.23 at 18:50, Alexander Kanavin wrote:
> This has been around without being properly documented since 2019 (!!!),
> and is nowadays the preferred method for enforcing license restrictions,
> especially since meta-gplv2 is officially obsolete.


Many thanks for this update!
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
... not too late for further comments though.

I will submit backports for at least Mickledore and Kirkstone on Monday.
Thanks again,
Michael

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] ref-manual: document image-specific variant of INCOMPATIBLE_LICENSE

[Quentin Schulz]

Hi Alex,

On 7/28/23 18:50, Alexander Kanavin via lists.yoctoproject.org wrote:
> This has been around without being properly documented since 2019 (!!!),
> and is nowadays the preferred method for enforcing license restrictions,
> especially since meta-gplv2 is officially obsolete.
> 
> Signed-off-by: Alexander Kanavin <alex@linutronix.de>
> ---
>   documentation/ref-manual/images.rst    | 16 +++++++++-------
>   documentation/ref-manual/variables.rst | 13 +++++++++++--
>   2 files changed, 20 insertions(+), 9 deletions(-)
> 
> diff --git a/documentation/ref-manual/images.rst b/documentation/ref-manual/images.rst
> index d3aeb0829..19c31e0fc 100644
> --- a/documentation/ref-manual/images.rst
> +++ b/documentation/ref-manual/images.rst
> @@ -14,15 +14,17 @@ image you want.
>      Building an image without GNU General Public License Version 3
>      (GPLv3), GNU Lesser General Public License Version 3 (LGPLv3), and
>      the GNU Affero General Public License Version 3 (AGPL-3.0) components
> -   is only supported for minimal and base images. Furthermore, if you
> -   are going to build an image using non-GPLv3 and similarly licensed
> -   components, you must make the following changes in the ``local.conf``
> -   file before using the BitBake command to build the minimal or base
> -   image:
> +   is only tested for core-image-minimal image. Furthermore, if you would like to
> +   build an image and verify that it does not include GPLv3 and similarly licensed
> +   components, you must make the following changes in the image recipe
> +   file before using the BitBake command to build the image:
>   
> -   #. Comment out the :term:`EXTRA_IMAGE_FEATURES` line
> +       INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0*"
>   
> -   #. Set :term:`INCOMPATIBLE_LICENSE` to "GPL-3.0* LGPL-3.0* AGPL-3.0*"
> +   Alternatively, you can adjust ``local.conf`` file, repeating and adjusting the line
> +   for all images where the license restriction must apply:
> +
> +       INCOMPATIBLE_LICENSE:pn:your-image-name = "GPL-3.0* LGPL-3.0*"
>   

I believe there's a typo here in the override and we should read:

INCOMPATIBLE_LICENSE:pn-your-image-name = "GPL-3.0* LGPL-3.0*"

(note the `:` transformed into `-`).

Is this a correct assumption?

Cheers,
Quentin

Re: [docs] [PATCH] ref-manual: document image-specific variant of INCOMPATIBLE_LICENSE

[Alexander Kanavin]

That's right. Needs to be fixed. Michael, can you squash the fixup in
master-next please?

Alex

On Mon, 31 Jul 2023 at 11:11, Quentin Schulz
<quentin.schulz@theobroma-systems.com> wrote:
>
> Hi Alex,
>
> On 7/28/23 18:50, Alexander Kanavin via lists.yoctoproject.org wrote:
> > This has been around without being properly documented since 2019 (!!!),
> > and is nowadays the preferred method for enforcing license restrictions,
> > especially since meta-gplv2 is officially obsolete.
> >
> > Signed-off-by: Alexander Kanavin <alex@linutronix.de>
> > ---
> >   documentation/ref-manual/images.rst    | 16 +++++++++-------
> >   documentation/ref-manual/variables.rst | 13 +++++++++++--
> >   2 files changed, 20 insertions(+), 9 deletions(-)
> >
> > diff --git a/documentation/ref-manual/images.rst b/documentation/ref-manual/images.rst
> > index d3aeb0829..19c31e0fc 100644
> > --- a/documentation/ref-manual/images.rst
> > +++ b/documentation/ref-manual/images.rst
> > @@ -14,15 +14,17 @@ image you want.
> >      Building an image without GNU General Public License Version 3
> >      (GPLv3), GNU Lesser General Public License Version 3 (LGPLv3), and
> >      the GNU Affero General Public License Version 3 (AGPL-3.0) components
> > -   is only supported for minimal and base images. Furthermore, if you
> > -   are going to build an image using non-GPLv3 and similarly licensed
> > -   components, you must make the following changes in the ``local.conf``
> > -   file before using the BitBake command to build the minimal or base
> > -   image:
> > +   is only tested for core-image-minimal image. Furthermore, if you would like to
> > +   build an image and verify that it does not include GPLv3 and similarly licensed
> > +   components, you must make the following changes in the image recipe
> > +   file before using the BitBake command to build the image:
> >
> > -   #. Comment out the :term:`EXTRA_IMAGE_FEATURES` line
> > +       INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0*"
> >
> > -   #. Set :term:`INCOMPATIBLE_LICENSE` to "GPL-3.0* LGPL-3.0* AGPL-3.0*"
> > +   Alternatively, you can adjust ``local.conf`` file, repeating and adjusting the line
> > +   for all images where the license restriction must apply:
> > +
> > +       INCOMPATIBLE_LICENSE:pn:your-image-name = "GPL-3.0* LGPL-3.0*"
> >
>
> I believe there's a typo here in the override and we should read:
>
> INCOMPATIBLE_LICENSE:pn-your-image-name = "GPL-3.0* LGPL-3.0*"
>
> (note the `:` transformed into `-`).
>
> Is this a correct assumption?
>
> Cheers,
> Quentin

Re: [docs] [PATCH] ref-manual: document image-specific variant of INCOMPATIBLE_LICENSE

[Michael Opdenacker]

On 31.07.23 at 11:21, Alexander Kanavin wrote:
> That's right. Needs to be fixed. Michael, can you squash the fixup in
> master-next please?
>
> Alex
>
> On Mon, 31 Jul 2023 at 11:11, Quentin Schulz
> <quentin.schulz@theobroma-systems.com> wrote:
>> Hi Alex,
>>
>> On 7/28/23 18:50, Alexander Kanavin via lists.yoctoproject.org wrote:
>>> This has been around without being properly documented since 2019 (!!!),
>>> and is nowadays the preferred method for enforcing license restrictions,
>>> especially since meta-gplv2 is officially obsolete.
>>>
>>> Signed-off-by: Alexander Kanavin <alex@linutronix.de>
>>> ---
>>>    documentation/ref-manual/images.rst    | 16 +++++++++-------
>>>    documentation/ref-manual/variables.rst | 13 +++++++++++--
>>>    2 files changed, 20 insertions(+), 9 deletions(-)
>>>
>>> diff --git a/documentation/ref-manual/images.rst b/documentation/ref-manual/images.rst
>>> index d3aeb0829..19c31e0fc 100644
>>> --- a/documentation/ref-manual/images.rst
>>> +++ b/documentation/ref-manual/images.rst
>>> @@ -14,15 +14,17 @@ image you want.
>>>       Building an image without GNU General Public License Version 3
>>>       (GPLv3), GNU Lesser General Public License Version 3 (LGPLv3), and
>>>       the GNU Affero General Public License Version 3 (AGPL-3.0) components
>>> -   is only supported for minimal and base images. Furthermore, if you
>>> -   are going to build an image using non-GPLv3 and similarly licensed
>>> -   components, you must make the following changes in the ``local.conf``
>>> -   file before using the BitBake command to build the minimal or base
>>> -   image:
>>> +   is only tested for core-image-minimal image. Furthermore, if you would like to
>>> +   build an image and verify that it does not include GPLv3 and similarly licensed
>>> +   components, you must make the following changes in the image recipe
>>> +   file before using the BitBake command to build the image:
>>>
>>> -   #. Comment out the :term:`EXTRA_IMAGE_FEATURES` line
>>> +       INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0*"
>>>
>>> -   #. Set :term:`INCOMPATIBLE_LICENSE` to "GPL-3.0* LGPL-3.0* AGPL-3.0*"
>>> +   Alternatively, you can adjust ``local.conf`` file, repeating and adjusting the line
>>> +   for all images where the license restriction must apply:
>>> +
>>> +       INCOMPATIBLE_LICENSE:pn:your-image-name = "GPL-3.0* LGPL-3.0*"
>>>
>> I believe there's a typo here in the override and we should read:
>>
>> INCOMPATIBLE_LICENSE:pn-your-image-name = "GPL-3.0* LGPL-3.0*"
>>
>> (note the `:` transformed into `-`).
>>
>> Is this a correct assumption?


Sure, done.
Thanks Quentin for the review!
Cheers
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com