| Message ID | 20230221104436.20516-1-michael.opdenacker@bootlin.com |
|---|---|
| State | New |
| Headers | show |
| Series | manuals: document COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables | expand |
Hi Michael, On 2/21/23 11:44, Michael Opdenacker via lists.yoctoproject.org wrote: > From: Michael Opdenacker <michael.opdenacker@bootlin.com> > > - Add COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables to the > variable index. > - Clarify that these plugins are still open-source > - Improve line width > > Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com> > --- > documentation/dev-manual/licenses.rst | 30 +++++++++++++++----------- > documentation/ref-manual/variables.rst | 20 +++++++++++++++++ > 2 files changed, 37 insertions(+), 13 deletions(-) > > diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst > index 65914e5efe..54d3a2e5f1 100644 > --- a/documentation/dev-manual/licenses.rst > +++ b/documentation/dev-manual/licenses.rst > @@ -242,10 +242,8 @@ defined in the > COMMERCIAL_AUDIO_PLUGINS ?= "" > COMMERCIAL_VIDEO_PLUGINS ?= "" > > -If you > -want to enable these components, you can do so by making sure you have > -statements similar to the following in your ``local.conf`` configuration > -file:: > +If you want to enable these components, you can do so by making sure you have > +statements similar to the following in your ``local.conf`` configuration file:: > > COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ > gst-plugins-ugly-mpegaudioparse" > @@ -253,20 +251,26 @@ file:: > gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse" > LICENSE_FLAGS_ACCEPTED = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" > > - > -Of course, you could also create a matching list for those > -components using the more general "commercial" in the > -:term:`LICENSE_FLAGS_ACCEPTED` variable, but that would also enable all > -the other packages with :term:`LICENSE_FLAGS` > +Of course, you could also create a matching list for those components using > +the more general "commercial" in the :term:`LICENSE_FLAGS_ACCEPTED` variable, > +but that would also enable all the other packages with :term:`LICENSE_FLAGS` > containing "commercial", which you may or may not want:: > > LICENSE_FLAGS_ACCEPTED = "commercial" > > Specifying audio and video plugins as part of the > -``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements > -(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the > -plugins or components into built images, thus adding support for media > -formats or components. > +:term:`COMMERCIAL_AUDIO_PLUGINS` and :term:`COMMERCIAL_VIDEO_PLUGINS` statements > +(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the plugins or s/with the/with/ or s/with the enabling/with the enabling of/ as "along with the enabling <smth>" feels wrong to me. > +components into built images, thus adding support for media formats or > +components. > + > +.. note:: > + > + GStreamer "ugly" and "bad" plugins are actually available through > + open source licenses. However, the "ugly" ones can be subject to software > + patents in some countries, making it necessary to pay licensing fees > + to distribute them. The "bad" ones are just unreliable and therefore s/are just unreliable/are deemed unreliable/ Also mention that this isn't a choice of Yocto but rather gstreamer community's? > + should be used with care. > > Maintaining Open Source License Compliance During Your Product's Lifecycle > ========================================================================== > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst > index 760c608bde..26215f679f 100644 > --- a/documentation/ref-manual/variables.rst > +++ b/documentation/ref-manual/variables.rst > @@ -1313,6 +1313,26 @@ system and gives an overview of their function and contents. > optional at the distribution level, in case the hardware supports > Bluetooth but you do not ever intend to use it. > > + :term:`COMMERCIAL_AUDIO_PLUGINS` > + This variable is specific to the :yocto_git:`GStreamer recipes > + </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. > + It allows to build the GStreamer `"ugly" > + <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-ugly__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1avSgpDo$ >`__ and > + `"bad" <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-bad__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1Wm8oVT2$ >`__ audio plugins. > + > + See the ":ref:`dev-manual/licenses:other variables related to commercial licenses`" > + section in the Development Tasks Manual for usage details. > + > + :term:`COMMERCIAL_VIDEO_PLUGINS` > + This variable is specific to the :yocto_git:`GStreamer recipes > + </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. > + It allows to build the GStreamer `"ugly" > + <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-ugly__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1avSgpDo$ >`__ and > + `"bad" <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-bad__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1Wm8oVT2$ >`__ video plugins. > + > + See the ":ref:`dev-manual/licenses:other variables related to commercial licenses`" > + section in the Development Tasks Manual for usage details. > + Please don't mention where to find the documentation if you link it. It allows to move the source across manuals without having to update the text, only the links. If you want to point to a specific section of the paragraph about commercial licenses, maybe add a target in there? e.g. .. _gstreamer-commercial-licenses: Cheers, Quentin
Hi Quentin, Many thanks for the review! On 21.02.23 at 13:01, Quentin Schulz wrote: > -``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements >> -(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the >> -plugins or components into built images, thus adding support for media >> -formats or components. >> +:term:`COMMERCIAL_AUDIO_PLUGINS` and >> :term:`COMMERCIAL_VIDEO_PLUGINS` statements >> +(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes >> the plugins or > > s/with the/with/ or s/with the enabling/with the enabling of/ > > as "along with the enabling <smth>" feels wrong to me. Right. I'll fix this. There were a few style issues in the existing text. I'll double check in other places. > >> +components into built images, thus adding support for media formats or >> +components. >> + >> +.. note:: >> + >> + GStreamer "ugly" and "bad" plugins are actually available through >> + open source licenses. However, the "ugly" ones can be subject to >> software >> + patents in some countries, making it necessary to pay licensing fees >> + to distribute them. The "bad" ones are just unreliable and therefore > > s/are just unreliable/are deemed unreliable/ > > Also mention that this isn't a choice of Yocto but rather gstreamer > community's? Right, this makes sense. This was my text this time. > >> + should be used with care. >> Maintaining Open Source License Compliance During Your Product's >> Lifecycle >> ========================================================================== >> diff --git a/documentation/ref-manual/variables.rst >> b/documentation/ref-manual/variables.rst >> index 760c608bde..26215f679f 100644 >> --- a/documentation/ref-manual/variables.rst >> +++ b/documentation/ref-manual/variables.rst >> @@ -1313,6 +1313,26 @@ system and gives an overview of their function >> and contents. >> optional at the distribution level, in case the hardware >> supports >> Bluetooth but you do not ever intend to use it. >> + :term:`COMMERCIAL_AUDIO_PLUGINS` >> + This variable is specific to the :yocto_git:`GStreamer recipes >> + >> </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. >> + It allows to build the GStreamer `"ugly" >> + >> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-ugly__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1avSgpDo$ >> >`__ and >> + `"bad" >> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-bad__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1Wm8oVT2$ >> >`__ audio plugins. >> + >> + See the ":ref:`dev-manual/licenses:other variables related to >> commercial licenses`" >> + section in the Development Tasks Manual for usage details. >> + >> + :term:`COMMERCIAL_VIDEO_PLUGINS` >> + This variable is specific to the :yocto_git:`GStreamer recipes >> + >> </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. >> + It allows to build the GStreamer `"ugly" >> + >> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-ugly__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1avSgpDo$ >> >`__ and >> + `"bad" >> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-bad__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1Wm8oVT2$ >> >`__ video plugins. >> + >> + See the ":ref:`dev-manual/licenses:other variables related to >> commercial licenses`" >> + section in the Development Tasks Manual for usage details. >> + > > Please don't mention where to find the documentation if you link it. > It allows to move the source across manuals without having to update > the text, only the links. > > If you want to point to a specific section of the paragraph about > commercial licenses, maybe add a target in there? e.g. > > .. _gstreamer-commercial-licenses: Good idea. We have tons of references like that in the manual, but we could gradually update them. Thanks again! Cheers Michael.
Hi Michael, On 2/21/23 13:57, Michael Opdenacker wrote: > Hi Quentin, > > Many thanks for the review! > > On 21.02.23 at 13:01, Quentin Schulz wrote: >> -``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements >>> -(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the >>> -plugins or components into built images, thus adding support for media >>> -formats or components. >>> +:term:`COMMERCIAL_AUDIO_PLUGINS` and >>> :term:`COMMERCIAL_VIDEO_PLUGINS` statements >>> +(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes >>> the plugins or >> >> s/with the/with/ or s/with the enabling/with the enabling of/ >> >> as "along with the enabling <smth>" feels wrong to me. > > > Right. I'll fix this. There were a few style issues in the existing > text. I'll double check in other places. > >> >>> +components into built images, thus adding support for media formats or >>> +components. >>> + >>> +.. note:: >>> + >>> + GStreamer "ugly" and "bad" plugins are actually available through >>> + open source licenses. However, the "ugly" ones can be subject to >>> software >>> + patents in some countries, making it necessary to pay licensing fees >>> + to distribute them. The "bad" ones are just unreliable and therefore >> >> s/are just unreliable/are deemed unreliable/ >> >> Also mention that this isn't a choice of Yocto but rather gstreamer >> community's? > > > Right, this makes sense. This was my text this time. > >> >>> + should be used with care. >>> Maintaining Open Source License Compliance During Your Product's >>> Lifecycle >>> ========================================================================== >>> diff --git a/documentation/ref-manual/variables.rst >>> b/documentation/ref-manual/variables.rst >>> index 760c608bde..26215f679f 100644 >>> --- a/documentation/ref-manual/variables.rst >>> +++ b/documentation/ref-manual/variables.rst >>> @@ -1313,6 +1313,26 @@ system and gives an overview of their function >>> and contents. >>> optional at the distribution level, in case the hardware >>> supports >>> Bluetooth but you do not ever intend to use it. >>> + :term:`COMMERCIAL_AUDIO_PLUGINS` >>> + This variable is specific to the :yocto_git:`GStreamer recipes >>> + >>> </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. >>> + It allows to build the GStreamer `"ugly" >>> + >>> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-ugly__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1avSgpDo$ >`__ and >>> + `"bad" >>> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-bad__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1Wm8oVT2$ >`__ audio plugins. >>> + >>> + See the ":ref:`dev-manual/licenses:other variables related to >>> commercial licenses`" >>> + section in the Development Tasks Manual for usage details. >>> + >>> + :term:`COMMERCIAL_VIDEO_PLUGINS` >>> + This variable is specific to the :yocto_git:`GStreamer recipes >>> + >>> </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. >>> + It allows to build the GStreamer `"ugly" >>> + >>> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-ugly__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1avSgpDo$ >`__ and >>> + `"bad" >>> <https://urldefense.com/v3/__https://github.com/GStreamer/gst-plugins-bad__;!!OOPJP91ZZw!g3-jyo-zyCDgt8PzhEQCODfcdBgZFn81oApK_JDf-SOUZOj7xU1NTcsM3TiT7ijx5ktBKoVFrB10eWRqoTwwCKsmaV88ozoHJZrdCVVHKI1r1Wm8oVT2$ >`__ video plugins. >>> + >>> + See the ":ref:`dev-manual/licenses:other variables related to >>> commercial licenses`" >>> + section in the Development Tasks Manual for usage details. >>> + >> >> Please don't mention where to find the documentation if you link it. >> It allows to move the source across manuals without having to update >> the text, only the links. >> >> If you want to point to a specific section of the paragraph about >> commercial licenses, maybe add a target in there? e.g. >> >> .. _gstreamer-commercial-licenses: > > > Good idea. We have tons of references like that in the manual, but we > could gradually update them. > Correct. And I'm now cursing myself for having updated some links to the sections and losing the exact location the old xml documentation was pointing at when I reviewed the xml to sphinx update. Specifically, we lost that for the QA section where everything is a list now and we have no automatic way for Sphinx to reference those items elsewhere (well, if I had known/thought about those manual targets... :) ). More work for future me/us :) Cheers, Quentin
diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst index 65914e5efe..54d3a2e5f1 100644 --- a/documentation/dev-manual/licenses.rst +++ b/documentation/dev-manual/licenses.rst @@ -242,10 +242,8 @@ defined in the COMMERCIAL_AUDIO_PLUGINS ?= "" COMMERCIAL_VIDEO_PLUGINS ?= "" -If you -want to enable these components, you can do so by making sure you have -statements similar to the following in your ``local.conf`` configuration -file:: +If you want to enable these components, you can do so by making sure you have +statements similar to the following in your ``local.conf`` configuration file:: COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ gst-plugins-ugly-mpegaudioparse" @@ -253,20 +251,26 @@ file:: gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse" LICENSE_FLAGS_ACCEPTED = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" - -Of course, you could also create a matching list for those -components using the more general "commercial" in the -:term:`LICENSE_FLAGS_ACCEPTED` variable, but that would also enable all -the other packages with :term:`LICENSE_FLAGS` +Of course, you could also create a matching list for those components using +the more general "commercial" in the :term:`LICENSE_FLAGS_ACCEPTED` variable, +but that would also enable all the other packages with :term:`LICENSE_FLAGS` containing "commercial", which you may or may not want:: LICENSE_FLAGS_ACCEPTED = "commercial" Specifying audio and video plugins as part of the -``COMMERCIAL_AUDIO_PLUGINS`` and ``COMMERCIAL_VIDEO_PLUGINS`` statements -(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the -plugins or components into built images, thus adding support for media -formats or components. +:term:`COMMERCIAL_AUDIO_PLUGINS` and :term:`COMMERCIAL_VIDEO_PLUGINS` statements +(along with the enabling :term:`LICENSE_FLAGS_ACCEPTED`) includes the plugins or +components into built images, thus adding support for media formats or +components. + +.. note:: + + GStreamer "ugly" and "bad" plugins are actually available through + open source licenses. However, the "ugly" ones can be subject to software + patents in some countries, making it necessary to pay licensing fees + to distribute them. The "bad" ones are just unreliable and therefore + should be used with care. Maintaining Open Source License Compliance During Your Product's Lifecycle ========================================================================== diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 760c608bde..26215f679f 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -1313,6 +1313,26 @@ system and gives an overview of their function and contents. optional at the distribution level, in case the hardware supports Bluetooth but you do not ever intend to use it. + :term:`COMMERCIAL_AUDIO_PLUGINS` + This variable is specific to the :yocto_git:`GStreamer recipes + </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. + It allows to build the GStreamer `"ugly" + <https://github.com/GStreamer/gst-plugins-ugly>`__ and + `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ audio plugins. + + See the ":ref:`dev-manual/licenses:other variables related to commercial licenses`" + section in the Development Tasks Manual for usage details. + + :term:`COMMERCIAL_VIDEO_PLUGINS` + This variable is specific to the :yocto_git:`GStreamer recipes + </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. + It allows to build the GStreamer `"ugly" + <https://github.com/GStreamer/gst-plugins-ugly>`__ and + `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ video plugins. + + See the ":ref:`dev-manual/licenses:other variables related to commercial licenses`" + section in the Development Tasks Manual for usage details. + :term:`COMMON_LICENSE_DIR` Points to ``meta/files/common-licenses`` in the :term:`Source Directory`, which is where generic license