Re: [dpdk-dev] [v5] doc: define qualification criteria for external library

[Jerin Jacob <jerinjacobk@gmail.com>]

On Mon, Jan 8, 2024 at 2:55 PM Morten Brørup <mb@smartsharesystems.com> wrote:
>
> > From: jerinj@marvell.com [mailto:jerinj@marvell.com]
> > Sent: Monday, 8 January 2024 08.59
> >
> > Define qualification criteria for external library
> > based on a techboard meeting minutes [1] and past
> > learnings from mailing list discussion.
>
> According to the DPDK project charter, the Governing Board deals with legal and licensing issues, so we need their approval before publishing this.
> Perhaps the Governing Board should be invited to join the discussion?

+ govboard@dpdk.org

Not sure. I will Cc the govboard@dpdk.org in next version of patch anyway.

>
> >
> > [1]
> > http://mails.dpdk.org/archives/dev/2019-June/135847.html
> > https://mails.dpdk.org/archives/dev/2024-January/284849.html
> >
> > Signed-off-by: Jerin Jacob <jerinj@marvell.com>
> > Acked-by: Thomas Monjalon <thomas@monjalon.net>
> > ---
> >  doc/guides/contributing/index.rst             |  1 +
> >  .../contributing/library_dependency.rst       | 52 +++++++++++++++++++
> >  2 files changed, 53 insertions(+)
> >  create mode 100644 doc/guides/contributing/library_dependency.rst
> >
> > v5:
> > - Added "Dependency nature" section based on Stephen's input
> >
> > v4:
> > - Address Thomas comments from
> > https://patches.dpdk.org/project/dpdk/patch/20240105121215.3950532-1-
> > jerinj@marvell.com/
> >
> > v3:
> > - Updated the content based on TB discussion which is documented at
> > https://mails.dpdk.org/archives/dev/2024-January/284849.html
> >
> > v2:
> > - Added "Meson build integration" and "Code readability" sections.
> >
> >
> > diff --git a/doc/guides/contributing/index.rst
> > b/doc/guides/contributing/index.rst
> > index dcb9b1fbf0..e5a8c2b0a3 100644
> > --- a/doc/guides/contributing/index.rst
> > +++ b/doc/guides/contributing/index.rst
> > @@ -15,6 +15,7 @@ Contributor's Guidelines
> >      documentation
> >      unit_test
> >      new_library
> > +    library_dependency
> >      patches
> >      vulnerability
> >      stable
> > diff --git a/doc/guides/contributing/library_dependency.rst
> > b/doc/guides/contributing/library_dependency.rst
> > new file mode 100644
> > index 0000000000..94025fdf60
> > --- /dev/null
> > +++ b/doc/guides/contributing/library_dependency.rst
> > @@ -0,0 +1,52 @@
> > +.. SPDX-License-Identifier: BSD-3-Clause
> > +   Copyright(c) 2024 Marvell.
> > +
> > +External Library dependency
> > +===========================
> > +
> > +This document defines the qualification criteria for external
> > libraries that may be
> > +used as dependencies in DPDK drivers or libraries.
>
> More background information could be added here, for context.
>
> Although DPDK is a BSD licensed project, we want to open the door for non-BSD licensed external libraries in those drivers and libraries, where the developer has the choice to omit them at build time. But not in the core parts of DPDK, which must remain fully BSD licensed.
>
> Stephen shared some concerns about source code availability, so DPDK doesn't become a shim for a bunch of binary blobs, like some other "open" project (I cannot remember the name of the project he mentioned). We are allowing binary blobs, but it would be nice if we could somehow state our intentions in this regard.
>
> > +
> > +#. **Documentation:**
> > +
> > +   - Must have adequate documentation for the steps to build it.
> > +   - Must have clear license documentation on distribution and usage
> > aspects of external library.
> > +
> > +#. **Free availability:**
> > +
> > +   - The library must be freely available to build in either source or
> > binary form.
> > +   - It shall be downloadable from a direct link. There shall not be
> > any requirement to explicitly
> > +     login or sign a user agreement.
>
> Remove "explicitly".

Adding "explicitly" was decided in the meeting. There may “implicit"
signing of user agreement by the distribution installation procedure.
Like clicking allowing to install non permissive license libraries in
the context of general OS installation. Not at the time of
installing a specific package.


>
> > +
> > +#. **Usage License:**
> > +
> > +   - Both permissive (e.g., BSD-3 or Apache) and non-permissive (e.g.,
> > GPLv3) licenses are acceptable.
> > +   - In the case of a permissive license, automatic inclusion in the
> > build process is assumed.
> > +     For non-permissive licenses, an additional build configuration
> > option is required.
>
> We must ensure that automatic inclusion only applies to libraries with a license that allows both free usage and free distribution. IANAL, so please confirm that this bullet covers both?
>
> The default DPDK build should not include anything that is not freely distributable, comes with an EULA or any other limitations or restrictions. Optimally, the default DPDK build should remain 100 % compatible with the BSD license. DPDK is a BSD licensed project, so any deviations from the BSD license must be explicitly selected (opt-in) at build time.
>
> > +
> > +#. **Distributions License:**
>
> Distributions -> Distribution

Ack


>
> > +
> > +   - No specific constraints beyond documentation.
> > +
> > +#. **Compiler compatibility:**
> > +
> > +   - The library must be able to compile with a DPDK supported
> > compiler for the given execution
> > +     environment.
>
> We should consider cross build requirements, or at least use cross build terminology.
>
> E.g. "execution environment" -> "target environment".

No strong opinion. I will change to target environment.

>
> > +     For example, for Linux, the library must be able to compile with
> > GCC and/or clang.
> > +   - Library may be limited to a specific OS.
>
> Since we allow limiting to a specific OS, we should probably also allow limiting to specific architecture and/or hardware, e.g. something only present in a specific CPU/SoC/ASIC/FPGA:
>
> -   - Library may be limited to a specific OS.
> +   - Library may be limited to a specific operating system and/or specific hardware.

Ack

>
> > +
> > +#. **Meson build integration:**
> > +
> > +   - The library must have standard method like ``pkg-config`` for
> > seamless integration with
> > +     DPDK's build environment.
> > +
> > +#. **Code readability:**
> > +
> > +   - Optional dependencies should use stubs to minimize ``ifdef``
> > clutter, promoting improved
> > +     code readability.
> > +
> > +#. **Dependency nature:**
> > +
> > +   - The external library dependency should be optional.
>
> should -> must ?

Ack

>
> > +     i.e Missing external library must not impact the core
> > functionality of the DPDK, specific
> > +     library and/or driver will not built if dependencies are not
> > meet.
>
> Typo: meet -> met

Ack

>
> Is the above dependency text sufficient to highlight that stricter rules apply to DPDK core libraries?
>
> Do we also have sub-dependency requirements? E.g.:
>
> +   - All of the above requirements also apply to libraries that the library itself depends on.

Above text may not be needed.

So, diff for next version,

[main]dell[dpdk.org] $ git diff
diff --git a/doc/guides/contributing/library_dependency.rst
b/doc/guides/contributing/library_dependency.rst
index 94025fdf60..de62fec209 100644
--- a/doc/guides/contributing/library_dependency.rst
+++ b/doc/guides/contributing/library_dependency.rst
@@ -6,6 +6,7 @@ External Library dependency

 This document defines the qualification criteria for external
libraries that may be
 used as dependencies in DPDK drivers or libraries.
+The final decision to accept or reject is at the discretion of the
DPDK Project's Technical Board.

 #. **Documentation:**

@@ -24,16 +25,16 @@ used as dependencies in DPDK drivers or libraries.
    - In the case of a permissive license, automatic inclusion in the
build process is assumed.
      For non-permissive licenses, an additional build configuration
option is required.

-#. **Distributions License:**
+#. **Distribution License:**

-   - No specific constraints beyond documentation.
+   - No specific constraints, but clear documentation on distribution
usage aspects is required.

 #. **Compiler compatibility:**

-   - The library must be able to compile with a DPDK supported
compiler for the given execution
+   - The library must be able to compile with a DPDK supported
compiler for the given target
      environment.
      For example, for Linux, the library must be able to compile with
GCC and/or clang.
-   - Library may be limited to a specific OS.
+   - Library may be limited to a specific OS and/or specific hardware.

 #. **Meson build integration:**

@@ -47,6 +48,6 @@ used as dependencies in DPDK drivers or libraries.

 #. **Dependency nature:**

-   - The external library dependency should be optional.
+   - The external library dependency must be optional.
      i.e Missing external library must not impact the core
functionality of the DPDK, specific
-     library and/or driver will not built if dependencies are not meet.
+     library and/or driver will not be built if dependencies are not met.

>
>
> > --
> > 2.43.0
>