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

[Morten Brørup]

> From: jerinj at marvell.com [mailto:jerinj at 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?

> 
> [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 at marvell.com>
> Acked-by: Thomas Monjalon <thomas at 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 at 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".

> +
> +#. **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

> +
> +   - 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".

> +     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.

> +
> +#. **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 ?

> +     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

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.


> --
> 2.43.0