[v6] doc: define qualification criteria for external library
Checks
Commit Message
From: Jerin Jacob <jerinj@marvell.com>
Define qualification criteria for external library
based on a techboard meeting minutes [1] and past
learnings from mailing list 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@marvell.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
---
v6:
- Address Morten's comments at https://mails.dpdk.org/archives/dev/2024-January/285029.html
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.
doc/guides/contributing/index.rst | 1 +
.../contributing/library_dependency.rst | 53 +++++++++++++++++++
2 files changed, 54 insertions(+)
create mode 100644 doc/guides/contributing/library_dependency.rst
Comments
On Tue, Jan 9, 2024 at 7:40 PM <jerinj@marvell.com> wrote:
>
> From: Jerin Jacob <jerinj@marvell.com>
>
> Define qualification criteria for external library
> based on a techboard meeting minutes [1] and past
> learnings from mailing list 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@marvell.com>
> Acked-by: Thomas Monjalon <thomas@monjalon.net>
Ping for merge
> ---
>
> v6:
> - Address Morten's comments at https://mails.dpdk.org/archives/dev/2024-January/285029.html
>
> 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.
>
> doc/guides/contributing/index.rst | 1 +
> .../contributing/library_dependency.rst | 53 +++++++++++++++++++
> 2 files changed, 54 insertions(+)
> create mode 100644 doc/guides/contributing/library_dependency.rst
>
> 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..3b275f1c52
> --- /dev/null
> +++ b/doc/guides/contributing/library_dependency.rst
> @@ -0,0 +1,53 @@
> +.. 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.
> +The final decision to accept or reject is at the discretion of the DPDK Project's Technical Board.
> +
> +#. **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.
> +
> +#. **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.
> +
> +#. **Distribution License:**
> +
> + - 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 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 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 must be optional.
> + i.e Missing external library must not impact the core functionality of the DPDK, specific
> + library and/or driver will not be built if dependencies are not met.
> --
> 2.43.0
>
Acked-by: Hemant Agrawal <hemant.agrawal@nxp.com>
On 1/9/2024 2:10 PM, jerinj@marvell.com wrote:
> From: Jerin Jacob <jerinj@marvell.com>
>
> Define qualification criteria for external library
> based on a techboard meeting minutes [1] and past
> learnings from mailing list 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@marvell.com>
> Acked-by: Thomas Monjalon <thomas@monjalon.net>
> ---
>
> v6:
> - Address Morten's comments at https://mails.dpdk.org/archives/dev/2024-January/285029.html
>
> 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.
>
> doc/guides/contributing/index.rst | 1 +
> .../contributing/library_dependency.rst | 53 +++++++++++++++++++
> 2 files changed, 54 insertions(+)
> create mode 100644 doc/guides/contributing/library_dependency.rst
>
> 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..3b275f1c52
> --- /dev/null
> +++ b/doc/guides/contributing/library_dependency.rst
> @@ -0,0 +1,53 @@
> +.. 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.
> +The final decision to accept or reject is at the discretion of the DPDK Project's Technical Board.
> +
> +#. **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.
>
As binary form can't be built, just for language can we drop "to build":
"The library must be freely available 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.
> +
> +#. **Usage License:**
> +
> + - Both permissive (e.g., BSD-3 or Apache) and non-permissive (e.g., GPLv3) licenses are acceptable.
>
Both above sample licenses are open source licenses, but as far as I can
see proprietary licenses are accepted.
Does it make sense to clarify it, like:
"Both open-source and proprietary licenses are acceptable."
I believe it is OK to have binary or proprietary dependencies for the
device support (drivers) code, but this may have consequences for
libraries, if specially a core library ends up having this kind of
dependency.
We don't have a guarantee that a proprietary licensed dependency won't
be stopped distributing or changing its license conditions, right?
Does it make sense to make this distinction, as driver and library code,
for binary or proprietary dependencies?
Or are we freely open to any kind of binary or proprietary dependency?
> + - 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.
> +
>
As this is about external dependency, what is about "inclusion in the
build process", in build system we just detect the availability of the
library, right? How it changes for different license type?
What kind of 'additional build configuration option' mentioned, can it
be possible to elaborate?
> +#. **Distribution License:**
> +
> + - 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 target
> + environment.
>
Item says 'must', but as there is an option to deliver as binary, this
requirement is only for source distribution, although this is kind of
obvious does it worth to mention it?
> + For example, for Linux, the library must be able to compile with GCC and/or clang.
> + - Library may be limited to a specific OS 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 must be optional.
> + i.e Missing external library must not impact the core functionality of the DPDK, specific
> + library and/or driver will not be built if dependencies are not met.
>
There is a possibility that a DPDK library is just a wrapper to external
proprietary library, should we try to add clarification to prevent this
kind of usage?
@@ -15,6 +15,7 @@ Contributor's Guidelines
documentation
unit_test
new_library
+ library_dependency
patches
vulnerability
stable
new file mode 100644
@@ -0,0 +1,53 @@
+.. 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.
+The final decision to accept or reject is at the discretion of the DPDK Project's Technical Board.
+
+#. **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.
+
+#. **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.
+
+#. **Distribution License:**
+
+ - 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 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 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 must be optional.
+ i.e Missing external library must not impact the core functionality of the DPDK, specific
+ library and/or driver will not be built if dependencies are not met.