diff mbox series

[v3] doc: define qualification criteria for external library

Message ID 20240105121215.3950532-1-jerinj@marvell.com (mailing list archive)
State Changes Requested, archived
Delegated to: Thomas Monjalon
Headers
Series [v3] doc: define qualification criteria for external library |

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/loongarch-compilation success Compilation OK
ci/loongarch-unit-testing success Unit Testing PASS
ci/Intel-compilation success Compilation OK
ci/intel-Testing success Testing PASS
ci/intel-Functional success Functional PASS

Commit Message

Jerin Jacob Kollanukkaran Jan. 5, 2024, 12:12 p.m. UTC 
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>
---
 doc/guides/contributing/index.rst             |  1 +
 .../contributing/library_dependency.rst       | 45 +++++++++++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 doc/guides/contributing/library_dependency.rst

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.

Comments

Thomas Monjalon Jan. 5, 2024, 12:24 p.m. UTC | #1 
05/01/2024 13:12, jerinj@marvell.com:
> 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
[...]
> +#. **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.
> +
> +#. **Distributions License:**
> +
> +   - No specific constraints beyond documentation.
> +
> +#. **Compiler compatibility:**
> +
> +   - The library must be able to compile with a DPDK supported compiler for the given execution
> +     environment. For example, For Linux, the library must be able to compile with GCC and/or clang.

Please go to next line when starting a sentence.
There is an extra uppercasing in "For Linux".

> +   - Library may be limited to a specific OS.
> +
> +#. **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.


Acked-by: Thomas Monjalon <thomas@monjalon.net>
Stephen Hemminger Jan. 5, 2024, 5:27 p.m. UTC | #2 
On Fri, 5 Jan 2024 17:42:15 +0530
<jerinj@marvell.com> wrote:



I would a clause about optional dependency.
Something like:

	If external dependency is not available, then it must be detectable by the
	build process. Missing external library must not impact the core functionality
	of the DPDK; only the library or driver in DPDK will not be built.
Jerin Jacob Jan. 8, 2024, 7:53 a.m. UTC | #3 
On Sat, Jan 6, 2024 at 12:14 AM Stephen Hemminger
<stephen@networkplumber.org> wrote:
>
> On Fri, 5 Jan 2024 17:42:15 +0530
> <jerinj@marvell.com> wrote:
>
>
>
> I would a clause about optional dependency.
> Something like:
>
>         If external dependency is not available, then it must be detectable by the
>         build process. Missing external library must not impact the core functionality
>         of the DPDK; only the library or driver in DPDK will not be built.

OK. I will send the next verison with following update

[main][dpdk.org] $ git diff
diff --git a/doc/guides/contributing/library_dependency.rst
b/doc/guides/contributing/library_dependency.rst
index 367e380a89..7b008d7e8a 100644
--- a/doc/guides/contributing/library_dependency.rst
+++ b/doc/guides/contributing/library_dependency.rst
@@ -44,3 +44,9 @@ used as dependencies in DPDK drivers or libraries.

    - Optional dependencies should use stubs to minimize ``ifdef``
clutter, promoting improved
      code readability.
+
+#. **Dependency nature:**
+
+   - The external library dependency should be optional.
+     i.e Missing external library must not impact the core
functionality of the DPDK, specififc
+     library and/or driver will not built if dependencies are not meet.
diff mbox series

Patch

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..4242919475
--- /dev/null
+++ b/doc/guides/contributing/library_dependency.rst
@@ -0,0 +1,45 @@ 
+.. 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.
+
+#. **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.
+
+#. **Distributions License:**
+
+   - No specific constraints beyond documentation.
+
+#. **Compiler compatibility:**
+
+   - The library must be able to compile with a DPDK supported compiler for the given execution
+     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.
+
+#. **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.