| Message ID | 20230221184156.65816-1-michael.opdenacker@bootlin.com |
|---|---|
| State | New |
| Headers | show |
| Series | [v2] manuals: document COMMERCIAL_[AUDIO|VIDEO]_PLUGINS variables | expand |
Hi Michael, On 2/21/23 19:41, 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> > > --- > > Changes in V2: > - Style fixes > - Highlight that the "bad" status is according to GStreamer contributors > - Add a new "gstreamer-commercial-licenses" target so that we can refer > to the modified section without hardcoding the title and the manual > name in the reference. That's more resistant to changes. > According to the review from Quentin Schulz (thanks!) > --- > documentation/dev-manual/licenses.rst | 32 +++++++++++++++----------- > documentation/ref-manual/variables.rst | 18 +++++++++++++++ > 2 files changed, 37 insertions(+), 13 deletions(-) > > diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst > index 65914e5efe..91a2ebce81 100644 > --- a/documentation/dev-manual/licenses.rst > +++ b/documentation/dev-manual/licenses.rst > @@ -232,6 +232,8 @@ Here are some other scenarios: > in the :term:`LICENSE_FLAGS_ACCEPTED` list (e.g. > "commercial_foo_1.2") to specifically match a versioned recipe. > > +.. _gstreamer-commercial-licenses: > + My bad, I thought there were more examples, unrelated to GStreamer, in the "Other Variables Related to Commercial Licenses" section. But here I don't think it makes much sense to add this target actually since we already have some automatically added by sphinx for sections/subsections. Otherwise, Reviewed-by: Quentin Schulz <foss+yocto@0leil.net> Cheers, Quentin
Hi Quentin, On 22.02.23 at 14:49, Quentin Schulz via lists.yoctoproject.org wrote: > Hi Michael, > > On 2/21/23 19:41, 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> >> >> --- >> >> Changes in V2: >> - Style fixes >> - Highlight that the "bad" status is according to GStreamer contributors >> - Add a new "gstreamer-commercial-licenses" target so that we can refer >> to the modified section without hardcoding the title and the manual >> name in the reference. That's more resistant to changes. >> According to the review from Quentin Schulz (thanks!) >> --- >> documentation/dev-manual/licenses.rst | 32 +++++++++++++++----------- >> documentation/ref-manual/variables.rst | 18 +++++++++++++++ >> 2 files changed, 37 insertions(+), 13 deletions(-) >> >> diff --git a/documentation/dev-manual/licenses.rst >> b/documentation/dev-manual/licenses.rst >> index 65914e5efe..91a2ebce81 100644 >> --- a/documentation/dev-manual/licenses.rst >> +++ b/documentation/dev-manual/licenses.rst >> @@ -232,6 +232,8 @@ Here are some other scenarios: >> in the :term:`LICENSE_FLAGS_ACCEPTED` list (e.g. >> "commercial_foo_1.2") to specifically match a versioned recipe. >> +.. _gstreamer-commercial-licenses: >> + > > My bad, I thought there were more examples, unrelated to GStreamer, in > the "Other Variables Related to Commercial Licenses" section. But here > I don't think it makes much sense to add this target actually since we > already have some automatically added by sphinx for sections/subsections. > > Otherwise, > Reviewed-by: Quentin Schulz <foss+yocto@0leil.net> I'm not sure I understand, because the idea to use references to targets without referring to the document name made sense to me. Here's a V3 anyway, that may help clarify any misunderstanding. Thanks Michael.
Hi Michael, On 2/23/23 10:57, Michael Opdenacker wrote: > Hi Quentin, > > On 22.02.23 at 14:49, Quentin Schulz via lists.yoctoproject.org wrote: >> Hi Michael, >> >> On 2/21/23 19:41, 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> >>> >>> --- >>> >>> Changes in V2: >>> - Style fixes >>> - Highlight that the "bad" status is according to GStreamer contributors >>> - Add a new "gstreamer-commercial-licenses" target so that we can refer >>> to the modified section without hardcoding the title and the manual >>> name in the reference. That's more resistant to changes. >>> According to the review from Quentin Schulz (thanks!) >>> --- >>> documentation/dev-manual/licenses.rst | 32 +++++++++++++++----------- >>> documentation/ref-manual/variables.rst | 18 +++++++++++++++ >>> 2 files changed, 37 insertions(+), 13 deletions(-) >>> >>> diff --git a/documentation/dev-manual/licenses.rst >>> b/documentation/dev-manual/licenses.rst >>> index 65914e5efe..91a2ebce81 100644 >>> --- a/documentation/dev-manual/licenses.rst >>> +++ b/documentation/dev-manual/licenses.rst >>> @@ -232,6 +232,8 @@ Here are some other scenarios: >>> in the :term:`LICENSE_FLAGS_ACCEPTED` list (e.g. >>> "commercial_foo_1.2") to specifically match a versioned recipe. >>> +.. _gstreamer-commercial-licenses: >>> + >> >> My bad, I thought there were more examples, unrelated to GStreamer, in >> the "Other Variables Related to Commercial Licenses" section. But here >> I don't think it makes much sense to add this target actually since we >> already have some automatically added by sphinx for sections/subsections. >> >> Otherwise, >> Reviewed-by: Quentin Schulz <foss+yocto@0leil.net> > > > I'm not sure I understand, because the idea to use references to targets > without referring to the document name made sense to me. > What would be the use for the autogeneration of sphinx targets from sphinx sections if we have some sections with additional manual targets? What I wanted to use manual targets for is for pointing at content **within** a Sphinx section. e.g. https://docs.yoctoproject.org/3.1.23/ref-manual/faq.html. We could have had a target for each Q: line for example instead of migrating to sections and subsections like we did recently (c.f. what's in langdale). Hope I explained myself a bit better this time :) Cheers, Quentin
Hi Quentin, On 23.02.23 at 11:27, Quentin Schulz via lists.yoctoproject.org wrote: > What would be the use for the autogeneration of sphinx targets from > sphinx sections if we have some sections with additional manual targets? > > What I wanted to use manual targets for is for pointing at content > **within** a Sphinx section. e.g. > https://docs.yoctoproject.org/3.1.23/ref-manual/faq.html. We could > have had a target for each Q: line for example instead of migrating to > sections and subsections like we did recently (c.f. what's in langdale). > > Hope I explained myself a bit better this time :) Good idea. It think I got it this time :-D Thanks Michael.
diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst index 65914e5efe..91a2ebce81 100644 --- a/documentation/dev-manual/licenses.rst +++ b/documentation/dev-manual/licenses.rst @@ -232,6 +232,8 @@ Here are some other scenarios: in the :term:`LICENSE_FLAGS_ACCEPTED` list (e.g. "commercial_foo_1.2") to specifically match a versioned recipe. +.. _gstreamer-commercial-licenses: + Other Variables Related to Commercial Licenses ---------------------------------------------- @@ -242,10 +244,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 +253,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" string 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 :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 deemed unreliable by the + GStreamer community and should therefore 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..1848791938 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -1313,6 +1313,24 @@ 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:`gstreamer-commercial-licenses` section 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:`gstreamer-commercial-licenses` section for usage details. + :term:`COMMON_LICENSE_DIR` Points to ``meta/files/common-licenses`` in the :term:`Source Directory`, which is where generic license