Skip to contentSkip to conversation

doc: define qualification criteria for external library

PATCH Superseded [email protected] 8 participants 30 messages Sep 28, 2023 – Mar 19, 2024

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 doc: define qualification criteria for external library

From: Jerin Jacob <[email protected]>

Define qualification criteria for external library based on a Techboard meeting minutes [1].

[1]
http://mails.dpdk.org/archives/dev/2019-June/135847.html

---
 doc/guides/contributing/index.rst              |  1 +
 doc/guides/contributing/library_dependency.rst | 17 +++++++++++++++++
 2 files changed, 18 insertions(+)
 create mode 100644 doc/guides/contributing/library_dependency.rst
doc/guides/contributing/index.rst +1 -0
index dcb9b1fbf0..e5a8c2b0a3 100644
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
doc/guides/contributing/library_dependency.rst new file +17 -0
new file mode 100644
index 0000000000..9170525d47
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2023 Marvell.
+
+Library dependency
+==================
+
+This document defines the qualification criteria for external libraries that may be
+used as dependencies in DPDK drivers or libraries.
+
+- **Free availability**: The library must be freely available to build in either source or binary
+  form, with a preference for source form.
+
+- **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.
+
+- **Documentation**: The library must have adequate documentation for the steps to build it.
Signature · 1 line
2.42.0
#1 lore raw

PATCH v2 1/1 doc: define qualification criteria for external library

From: Jerin Jacob <[email protected]>

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

---
v2:
- Added "Meson build integration" and "Code readability" sections.

 doc/guides/contributing/index.rst             |  1 +
 .../contributing/library_dependency.rst       | 23 +++++++++++++++++++
 2 files changed, 24 insertions(+)
 create mode 100644 doc/guides/contributing/library_dependency.rst
doc/guides/contributing/index.rst +1 -0
index dcb9b1fbf0..e5a8c2b0a3 100644
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
doc/guides/contributing/library_dependency.rst new file +23 -0
new file mode 100644
index 0000000000..687a3b6cef
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2023 Marvell.
+
+Library dependency
+==================
+
+This document defines the qualification criteria for external libraries that may be
+used as dependencies in DPDK drivers or libraries.
+
+- **Free availability**: The library must be freely available to build in either source or binary
+  form, with a preference for source form.
+
+- **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.
+
+- **Documentation**: Must have adequate documentation for the steps to build it.
+
+- **Meson build integration**: The library must have standard method like ``pkg-config``
+  for seamless integration with DPDK's build environment.
+
+- **Code readability**: When the depended library is optional, use stubs to reduce the ``ifdef``
+  clutter to enable better code readability.
Signature · 1 line
2.42.0
#2 lore raw
Quoted 11 lines · On Thu, Sep 28, 2023 at 11:10 AM <[email protected]> wrote:

From: Jerin Jacob <[email protected]>

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

Ping for review and/or merge.

Quoted 53 lines

---
v2:
- Added "Meson build integration" and "Code readability" sections.

 doc/guides/contributing/index.rst             |  1 +
 .../contributing/library_dependency.rst       | 23 +++++++++++++++++++
 2 files changed, 24 insertions(+)
 create mode 100644 doc/guides/contributing/library_dependency.rst
doc/guides/contributing/index.rst +1 -0
index dcb9b1fbf0..e5a8c2b0a3 100644
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
doc/guides/contributing/library_dependency.rst new file +23 -1
new file mode 100644
index 0000000000..687a3b6cef
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2023 Marvell.
+
+Library dependency
+==================
+
+This document defines the qualification criteria for external libraries that may be
+used as dependencies in DPDK drivers or libraries.
+
+- **Free availability**: The library must be freely available to build in either source or binary
+  form, with a preference for source form.
+
+- **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.
+
+- **Documentation**: Must have adequate documentation for the steps to build it.
+
+- **Meson build integration**: The library must have standard method like ``pkg-config``
+  for seamless integration with DPDK's build environment.
+
+- **Code readability**: When the depended library is optional, use stubs to reduce the ``ifdef``
+  clutter to enable better code readability.
--

2.42.0

#3 lore raw
Quoted 57 lines

From: Jerin Jacob [mailto:[email protected]]
Sent: Friday, 17 November 2023 05.34

Quoted 11 lines · On Thu, Sep 28, 2023 at 11:10 AM <[email protected]> wrote:

From: Jerin Jacob <[email protected]>

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

Ping for review and/or merge.

Quoted 6 lines

---
v2:
- Added "Meson build integration" and "Code readability" sections.

 doc/guides/contributing/index.rst             |  1 +
 .../contributing/library_dependency.rst       | 23

+++++++++++++++++++

Review

Quoted 4 lines
 2 files changed, 24 insertions(+)
 create mode 100644 doc/guides/contributing/library_dependency.rst
(quoted diff) +0 -0

b/doc/guides/contributing/index.rst

Review

Quoted 12 lines

index dcb9b1fbf0..e5a8c2b0a3 100644

doc/guides/contributing/index.rst +1 -0
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
(quoted diff) +0 -0

b/doc/guides/contributing/library_dependency.rst

doc/guides/contributing/library_dependency.rst line 7

Quoted 12 lines

new file mode 100644
index 0000000000..687a3b6cef

doc/guides/contributing/library_dependency.rst new file +7 -0
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2023 Marvell.
+
+Library dependency
+==================
+
+This document defines the qualification criteria for external

libraries that may be

Quoted 5 lines

doc/guides/contributing/library_dependency.rst

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+used as dependencies in DPDK drivers or libraries.
+
+- **Free availability**: The library must be freely available to

build in either source or binary

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  form, with a preference for source form.

Suggest adding:

- **Free use and distribution license**: The library must be freely available to use and distribute without any attached conditions.

We must require a BSD-like license, to ensure that DPDK as a whole (including 3rd party libraries) remains BSD licensed, and can be used in commercial (closed source) applications.

Quoted 5 lines

doc/guides/contributing/library_dependency.rst line 13

Quoted 2 lines
doc/guides/contributing/library_dependency.rst new file +2 -0
+
+- **Compiler compatibility**: The library must be able to compile

with a DPDK supported compiler

doc/guides/contributing/library_dependency.rst line 14

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  for the given execution environment. For example, For Linux, the

library must be able to compile

Typo (after "For example,"): For -> for

Quoted 12 lines

doc/guides/contributing/library_dependency.rst

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+  with GCC and/or clang.
+
+- **Documentation**: Must have adequate documentation for the steps

to build it.

doc/guides/contributing/library_dependency.rst line 19

Quoted 2 lines
doc/guides/contributing/library_dependency.rst new file +2 -0
+
+- **Meson build integration**: The library must have standard method

like ``pkg-config``

doc/guides/contributing/library_dependency.rst

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+  for seamless integration with DPDK's build environment.
+
+- **Code readability**: When the depended library is optional, use

stubs to reduce the ``ifdef``

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  clutter to enable better code readability.

Why does everyone keep insisting that stubs make code more readable? Sometimes #ifdef is better.

Please use something like this instead:

- **Code readability**: When the depended library is optional, use either stubs or ``#ifdef`` consistently, not a mix of both, to ensure code readability.

#4 lore raw
Quoted 61 lines · Morten Brørup
Quoted 61 lines

From: Jerin Jacob [mailto:[email protected]]
Sent: Friday, 17 November 2023 05.34

Quoted 11 lines · On Thu, Sep 28, 2023 at 11:10 AM <[email protected]> wrote:

From: Jerin Jacob <[email protected]>

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

Ping for review and/or merge.

Quoted 6 lines

---
v2:
- Added "Meson build integration" and "Code readability" sections.

 doc/guides/contributing/index.rst             |  1 +
 .../contributing/library_dependency.rst       | 23

+++++++++++++++++++

Review

Quoted 4 lines
 2 files changed, 24 insertions(+)
 create mode 100644 doc/guides/contributing/library_dependency.rst
(quoted diff) +0 -0

b/doc/guides/contributing/index.rst

Review

Quoted 12 lines

index dcb9b1fbf0..e5a8c2b0a3 100644

doc/guides/contributing/index.rst +1 -0
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
(quoted diff) +0 -0

b/doc/guides/contributing/library_dependency.rst

doc/guides/contributing/library_dependency.rst line 7

Quoted 12 lines

new file mode 100644
index 0000000000..687a3b6cef

doc/guides/contributing/library_dependency.rst new file +7 -0
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2023 Marvell.
+
+Library dependency
+==================
+
+This document defines the qualification criteria for external

libraries that may be

doc/guides/contributing/library_dependency.rst

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+used as dependencies in DPDK drivers or libraries.
+
+- **Free availability**: The library must be freely available to

build in either source or binary

Quoted 8 lines
Quoted 1 line

doc/guides/contributing/library_dependency.rst line 11

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  form, with a preference for source form.

Suggest adding:

- **Free use and distribution license**: The library must be freely available to use and distribute without any attached conditions.

We must require a BSD-like license, to ensure that DPDK as a whole (including 3rd party libraries) remains BSD licensed, and can be used in commercial (closed source) applications.

I think the situation is a bit more complex. Firstly, we need to ensure that there are no license incompatibilities. Beyond that though, the importance of the library will depend on how strict we are going to be about open-source licensing etc.

For example, for a particular driver - nic, crypto, whatever - we have in the past allowed linking against non-opensource libraries in order to build that component. That (thankfully) has not caused us any serious issues to date, and I don't think we should change things by completely disallowing it in future.

On the other hand, a library that becomes key for building more than just a driver or rarely used library, e.g. one that adds key functionality to EAL, would be held to a much higher standard. In that case we likely would look for an open-source, appropriately licensed, version.

/Bruce

#5 lore raw
Quoted 74 lines

From: Bruce Richardson [mailto:[email protected]]
Sent: Friday, 17 November 2023 10.52

Quoted 14 lines · Morten Brørup
Quoted 14 lines

From: Jerin Jacob [mailto:[email protected]]
Sent: Friday, 17 November 2023 05.34

Quoted 10 lines · On Thu, Sep 28, 2023 at 11:10 AM <[email protected]> wrote:

From: Jerin Jacob <[email protected]>

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

Quoted 8 lines
Quoted 8 lines
Quoted 1 line

Ping for review and/or merge.

Quoted 3 lines

---
v2:
- Added "Meson build integration" and "Code readability"

sections.

Quoted 6 lines
Quoted 6 lines
Quoted 3 lines
 doc/guides/contributing/index.rst             |  1 +
 .../contributing/library_dependency.rst       | 23

+++++++++++++++++++

Quoted 2 lines
 2 files changed, 24 insertions(+)
 create mode 100644

doc/guides/contributing/library_dependency.rst

Quoted 33 lines
Quoted 33 lines

Review

Quoted 2 lines
(quoted diff) +0 -0

b/doc/guides/contributing/index.rst

Review

Quoted 12 lines

index dcb9b1fbf0..e5a8c2b0a3 100644

doc/guides/contributing/index.rst +1 -0
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
(quoted diff) +0 -0

b/doc/guides/contributing/library_dependency.rst

doc/guides/contributing/library_dependency.rst line 7

Quoted 12 lines

new file mode 100644
index 0000000000..687a3b6cef

doc/guides/contributing/library_dependency.rst new file +7 -0
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2023 Marvell.
+
+Library dependency
+==================
+
+This document defines the qualification criteria for external

libraries that may be

doc/guides/contributing/library_dependency.rst

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+used as dependencies in DPDK drivers or libraries.
+
+- **Free availability**: The library must be freely available to

build in either source or binary

Quoted 5 lines
Quoted 1 line

doc/guides/contributing/library_dependency.rst line 11

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  form, with a preference for source form.

Suggest adding:

- **Free use and distribution license**: The library must be freely

available to use and distribute without any attached conditions.

Quoted 1 line
Quoted 8 lines
Quoted 1 line

We must require a BSD-like license, to ensure that DPDK as a whole

(including 3rd party libraries) remains BSD licensed, and can be used in commercial (closed source) applications.

Quoted 1 line

I think the situation is a bit more complex. Firstly, we need to ensure that there are no license incompatibilities. Beyond that though, the importance of the library will depend on how strict we are going to be about open-source licensing etc.

My point about the license was not related to source code availability, it was related to conditions for use and distribution of the library.

The license needs to allow unrestricted and unconditional use and distribution, like the BSD license does.

In principle, this requirement only applies to binary form; we don't need to be able to distribute the source code of external libraries, regardless if it is open source or NDA-protected "view only" source code or other restricted access source code (e.g. Microsoft's Shared Source Initiative).

Quoted 11 lines

For example, for a particular driver - nic, crypto, whatever - we have in
the past allowed linking against non-opensource libraries in order to build
that component. That (thankfully) has not caused us any serious issues to
date, and I don't think we should change things by completely disallowing
it in future.

Quoted 7 lines

On the other hand, a library that becomes key for building more than just a
driver or rarely used library, e.g. one that adds key functionality to EAL,
would be held to a much higher standard. In that case we likely would look
for an open-source, appropriately licensed, version.

I agree that the required degree of open source principles should vary with DPDK's dependency of the library.

We can be more lenient with hardware PMDs, where end users ultimately can choose another hardware vendor if a dependent library is unacceptable for the end user.

There is no doubt we should keep allowing opaque binary BLOBs for hardware, such as on-board firmware and FPGA images.

#6 lore raw
In reply to Morten Brørup
Quoted 62 lines · Morten Brørup
Quoted 62 lines

From: Jerin Jacob [mailto:[email protected]]
Sent: Friday, 17 November 2023 05.34

Quoted 11 lines · On Thu, Sep 28, 2023 at 11:10 AM <[email protected]> wrote:

From: Jerin Jacob <[email protected]>

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

Ping for review and/or merge.

Quoted 6 lines

---
v2:
- Added "Meson build integration" and "Code readability" sections.

 doc/guides/contributing/index.rst             |  1 +
 .../contributing/library_dependency.rst       | 23

+++++++++++++++++++

Review

Quoted 4 lines
 2 files changed, 24 insertions(+)
 create mode 100644 doc/guides/contributing/library_dependency.rst
(quoted diff) +0 -0

b/doc/guides/contributing/index.rst

Review

Quoted 12 lines

index dcb9b1fbf0..e5a8c2b0a3 100644

doc/guides/contributing/index.rst +1 -0
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
(quoted diff) +0 -0

b/doc/guides/contributing/library_dependency.rst

doc/guides/contributing/library_dependency.rst line 7

Quoted 12 lines

new file mode 100644
index 0000000000..687a3b6cef

doc/guides/contributing/library_dependency.rst new file +7 -0
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2023 Marvell.
+
+Library dependency
+==================
+
+This document defines the qualification criteria for external

libraries that may be

doc/guides/contributing/library_dependency.rst

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+used as dependencies in DPDK drivers or libraries.
+
+- **Free availability**: The library must be freely available to

build in either source or binary

Quoted 7 lines
Quoted 1 line

doc/guides/contributing/library_dependency.rst line 11

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  form, with a preference for source form.

Suggest adding:

- **Free use and distribution license**: The library must be freely available to use and distribute without any attached conditions.

We must require a BSD-like license, to ensure that DPDK as a whole (including 3rd party libraries) remains BSD licensed, and can be used in commercial (closed source) applications.

As far as I understand, The initial scope of was “free availability” for building.
Free distribution is much wider scope. I don't think, current external libraries[1] have free distribution rights.
[1]
https://github.com/DPDK/dpdk/blob/main/doc/guides/gpus/cuda.rst
https://gitlab.com/nvidia/headers/cuda-individual/cudart/-/blob/main/LICENSE?ref_type=heads

I am fine with either way, Feedback from others?

Quoted 8 lines
Quoted 6 lines

doc/guides/contributing/library_dependency.rst line 13

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +2 -0
+
+- **Compiler compatibility**: The library must be able to compile

with a DPDK supported compiler

doc/guides/contributing/library_dependency.rst line 14

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  for the given execution environment. For example, For Linux, the

library must be able to compile

Typo (after "For example,"): For -> for

Ack. Will fix next version.

Quoted 7 lines
Quoted 7 lines

doc/guides/contributing/library_dependency.rst

Quoted 4 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+  with GCC and/or clang.
+
+- **Documentation**: Must have adequate documentation for the steps

to build it.

Quoted 2 lines
doc/guides/contributing/library_dependency.rst new file +2 -0
+
+- **Meson build integration**: The library must have standard method
Quoted 8 lines
Quoted 6 lines

like ``pkg-config``

doc/guides/contributing/library_dependency.rst

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+  for seamless integration with DPDK's build environment.
+
+- **Code readability**: When the depended library is optional, use

stubs to reduce the ``ifdef``

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  clutter to enable better code readability.

Why does everyone keep insisting that stubs make code more readable? Sometimes #ifdef is better.

Could you share a case where when #ifdefs is better(Just to understand the view).?

Quoted 5 lines

Please use something like this instead:

- **Code readability**: When the depended library is optional, use either stubs or ``#ifdef`` consistently, not a mix of both, to ensure code readability.

#7 lore raw
Quoted 80 lines

From: Jerin Jacob [mailto:[email protected]]
Sent: Sunday, 19 November 2023 08.08

Quoted 15 lines · Morten Brørup
Quoted 15 lines

From: Jerin Jacob [mailto:[email protected]]
Sent: Friday, 17 November 2023 05.34

Quoted 10 lines · On Thu, Sep 28, 2023 at 11:10 AM <[email protected]> wrote:

From: Jerin Jacob <[email protected]>

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

Quoted 8 lines
Quoted 8 lines
Quoted 1 line

Ping for review and/or merge.

Quoted 3 lines

---
v2:
- Added "Meson build integration" and "Code readability"

sections.

Quoted 6 lines
Quoted 6 lines
Quoted 3 lines
 doc/guides/contributing/index.rst             |  1 +
 .../contributing/library_dependency.rst       | 23

+++++++++++++++++++

Quoted 2 lines
 2 files changed, 24 insertions(+)
 create mode 100644

doc/guides/contributing/library_dependency.rst

Quoted 33 lines
Quoted 33 lines

Review

Quoted 2 lines
(quoted diff) +0 -0

b/doc/guides/contributing/index.rst

Review

Quoted 12 lines

index dcb9b1fbf0..e5a8c2b0a3 100644

doc/guides/contributing/index.rst +1 -0
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
(quoted diff) +0 -0

b/doc/guides/contributing/library_dependency.rst

doc/guides/contributing/library_dependency.rst line 7

Quoted 12 lines

new file mode 100644
index 0000000000..687a3b6cef

doc/guides/contributing/library_dependency.rst new file +7 -0
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2023 Marvell.
+
+Library dependency
+==================
+
+This document defines the qualification criteria for external

libraries that may be

doc/guides/contributing/library_dependency.rst

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+used as dependencies in DPDK drivers or libraries.
+
+- **Free availability**: The library must be freely available to

build in either source or binary

Quoted 5 lines
Quoted 1 line

doc/guides/contributing/library_dependency.rst line 11

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  form, with a preference for source form.

Suggest adding:

- **Free use and distribution license**: The library must be freely

available to use and distribute without any attached conditions.

Quoted 2 lines

We must require a BSD-like license, to ensure that DPDK as a whole

(including 3rd party libraries) remains BSD licensed, and can be used in commercial (closed source) applications.

Quoted 8 lines

As far as I understand, The initial scope of was “free availability” for building.
Free distribution is much wider scope. I don't think, current external libraries[1] have free distribution rights.
[1]
https://github.com/DPDK/dpdk/blob/main/doc/guides/gpus/cuda.rst
https://gitlab.com/nvidia/headers/cuda-individual/cudart/-
/blob/main/LICENSE?ref_type=heads

I didn't mean the library source code; I only meant the library in binary form.

It is nice if the library's header files may be distributed too, but I don't see it as a requirement, especially if they are freely available elsewhere (preferably without imposing additional restrictions on the ability to use and distribute the library in binary form).

How about this instead:

- **License permitting free use and distribution in binary form**:
The library's license must allow free and unconditional use and distribution of the library in binary form.

We might want lawyers to verify the wording when we have agreed on our intentions.

Quoted 30 lines

I am fine with either way, Feedback from others?

Quoted 3 lines
Quoted 3 lines

doc/guides/contributing/library_dependency.rst line 13

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +2 -0
+
+- **Compiler compatibility**: The library must be able to

compile

Quoted 2 lines
Quoted 2 lines

with a DPDK supported compiler

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  for the given execution environment. For example, For Linux,

the

Quoted 3 lines
Quoted 1 line

library must be able to compile

Typo (after "For example,"): For -> for

Ack. Will fix next version.

Quoted 4 lines
Quoted 4 lines

doc/guides/contributing/library_dependency.rst

Quoted 4 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+  with GCC and/or clang.
+
+- **Documentation**: Must have adequate documentation for the

steps

Quoted 3 lines
Quoted 3 lines

to build it.

Quoted 2 lines
doc/guides/contributing/library_dependency.rst new file +2 -0
+
+- **Meson build integration**: The library must have standard

method

Quoted 4 lines
Quoted 4 lines

like ``pkg-config``

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+  for seamless integration with DPDK's build environment.
+
+- **Code readability**: When the depended library is optional,

use

Quoted 8 lines
Quoted 4 lines
Quoted 2 lines

stubs to reduce the ``ifdef``

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  clutter to enable better code readability.

Why does everyone keep insisting that stubs make code more readable?

Sometimes #ifdef is better.

Could you share a case where when #ifdefs is better(Just to understand the view).?

If an external library provides some simple functions, and a group (i.e. a subset) of functions in a DPDK library depends on that external library, then it might be more readable if those functions are enabled/disabled as a group in the DPDK library rather than individually.

E.g. the external library provides functions for statistical processing, and the DPDK library can be built with or without statistics, depending on using the external library or not. If the DPDK library is built without statistics, it should not register statistics availability towards a management module (e.g. telemetry) if it is not really implemented within the DPDK library (because the underlying functions are stubs).

It might also be a matter of personal preferences. When reviewing some source code, an #ifdef makes the availability of an underlying function perfectly clear. Blindly calling a function (of an external library) doesn't really show if the function is implemented for real, or just a stub.

My opinion on this might be tainted by my preference for building from scratch. The distro people might see it very differently!

Quoted 8 lines
Quoted 5 lines

Please use something like this instead:

- **Code readability**: When the depended library is optional, use

either stubs or ``#ifdef`` consistently, not a mix of both, to ensure code readability.

Quoted 1 line
#8 lore raw
Quoted 90 lines · Morten Brørup
Quoted 81 lines

From: Jerin Jacob [mailto:[email protected]]
Sent: Sunday, 19 November 2023 08.08

Quoted 15 lines · Morten Brørup
Quoted 15 lines

From: Jerin Jacob [mailto:[email protected]]
Sent: Friday, 17 November 2023 05.34

Quoted 10 lines · On Thu, Sep 28, 2023 at 11:10 AM <[email protected]> wrote:

From: Jerin Jacob <[email protected]>

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

Quoted 8 lines
Quoted 8 lines
Quoted 1 line

Ping for review and/or merge.

Quoted 3 lines

---
v2:
- Added "Meson build integration" and "Code readability"

sections.

Quoted 6 lines
Quoted 6 lines
Quoted 3 lines
 doc/guides/contributing/index.rst             |  1 +
 .../contributing/library_dependency.rst       | 23

+++++++++++++++++++

Quoted 2 lines
 2 files changed, 24 insertions(+)
 create mode 100644

doc/guides/contributing/library_dependency.rst

Quoted 33 lines
Quoted 33 lines

Review

Quoted 2 lines
(quoted diff) +0 -0

b/doc/guides/contributing/index.rst

Review

Quoted 12 lines

index dcb9b1fbf0..e5a8c2b0a3 100644

doc/guides/contributing/index.rst +1 -0
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
(quoted diff) +0 -0

b/doc/guides/contributing/library_dependency.rst

doc/guides/contributing/library_dependency.rst line 7

Quoted 12 lines

new file mode 100644
index 0000000000..687a3b6cef

doc/guides/contributing/library_dependency.rst new file +7 -0
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2023 Marvell.
+
+Library dependency
+==================
+
+This document defines the qualification criteria for external

libraries that may be

doc/guides/contributing/library_dependency.rst

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+used as dependencies in DPDK drivers or libraries.
+
+- **Free availability**: The library must be freely available to

build in either source or binary

Quoted 5 lines
Quoted 1 line

doc/guides/contributing/library_dependency.rst line 11

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  form, with a preference for source form.

Suggest adding:

- **Free use and distribution license**: The library must be freely

available to use and distribute without any attached conditions.

Quoted 2 lines

We must require a BSD-like license, to ensure that DPDK as a whole

(including 3rd party libraries) remains BSD licensed, and can be used in commercial (closed source) applications.

Quoted 8 lines

As far as I understand, The initial scope of was “free availability” for building.
Free distribution is much wider scope. I don't think, current external libraries[1] have free distribution rights.
[1]
https://github.com/DPDK/dpdk/blob/main/doc/guides/gpus/cuda.rst
https://gitlab.com/nvidia/headers/cuda-individual/cudart/-
/blob/main/LICENSE?ref_type=heads

Quoted 8 lines

I didn't mean the library source code; I only meant the library in binary form.

It is nice if the library's header files may be distributed too, but I don't see it as a requirement, especially if they are freely available elsewhere (preferably without imposing additional restrictions on the ability to use and distribute the library in binary form).

How about this instead:

- **License permitting free use and distribution in binary form**:
The library's license must allow free and unconditional use and distribution of the library in binary form.

Distribution and unconditional use is not the case for existing library dependencies such as
https://gitlab.com/nvidia/headers/cuda-individual/cudart/-/blob/main/LICENSE?ref_type=heads

So I am not sure, Which is the correct thing to do. Maybe we can discuss more in tech board meeting if there are no other comments in mailing list on this topic.

Quoted 39 lines

We might want lawyers to verify the wording when we have agreed on our intentions.

Quoted 36 lines

I am fine with either way, Feedback from others?

Quoted 3 lines
Quoted 3 lines

doc/guides/contributing/library_dependency.rst line 13

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +2 -0
+
+- **Compiler compatibility**: The library must be able to

compile

Quoted 2 lines
Quoted 2 lines

with a DPDK supported compiler

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  for the given execution environment. For example, For Linux,

the

Quoted 3 lines
Quoted 1 line

library must be able to compile

Typo (after "For example,"): For -> for

Ack. Will fix next version.

Quoted 4 lines
Quoted 4 lines

doc/guides/contributing/library_dependency.rst

Quoted 4 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+  with GCC and/or clang.
+
+- **Documentation**: Must have adequate documentation for the

steps

Quoted 3 lines
Quoted 3 lines

to build it.

Quoted 2 lines
doc/guides/contributing/library_dependency.rst new file +2 -0
+
+- **Meson build integration**: The library must have standard

method

Quoted 4 lines
Quoted 4 lines

like ``pkg-config``

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+  for seamless integration with DPDK's build environment.
+
+- **Code readability**: When the depended library is optional,

use

Quoted 4 lines
Quoted 2 lines

stubs to reduce the ``ifdef``

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+  clutter to enable better code readability.

Why does everyone keep insisting that stubs make code more readable?

Sometimes #ifdef is better.

Quoted 8 lines
Quoted 2 lines

Could you share a case where when #ifdefs is better(Just to understand the view).?

If an external library provides some simple functions, and a group (i.e. a subset) of functions in a DPDK library depends on that external library, then it might be more readable if those functions are enabled/disabled as a group in the DPDK library rather than individually.

E.g. the external library provides functions for statistical processing, and the DPDK library can be built with or without statistics, depending on using the external library or not. If the DPDK library is built without statistics, it should not register statistics availability towards a management module (e.g. telemetry) if it is not really implemented within the DPDK library (because the underlying functions are stubs).

It might also be a matter of personal preferences. When reviewing some source code, an #ifdef makes the availability of an underlying function perfectly clear. Blindly calling a function (of an external library) doesn't really show if the function is implemented for real, or just a stub.

In general theme in DPDK code base that we are trying to avoid a lot of #ifdef in a given C file.
Instead, we are doing following scheme.

https://github.com/DPDK/dpdk/blob/main/drivers/ml/cnxk/meson.build#L84
https://github.com/DPDK/dpdk/blob/main/drivers/ml/cnxk/meson.build#L60
https://github.com/DPDK/dpdk/blob/main/drivers/ml/cnxk/mvtvm_ml_stubs.c

Quoted 2 lines

My opinion on this might be tainted by my preference for building from scratch. The distro people might see it very differently!

Yeah. I don't have a strong opinion, I can change to following, if there are no comments on this. Or we can discuss more in TB meeting if there are no review comments in mailing list on this topic.

**Code readability**: When the depended library is optional, use either stubs or ``#ifdef`` consistently, not a mix of both, to ensure code readability.

Quoted 9 lines
Quoted 9 lines
Quoted 6 lines

Please use something like this instead:

- **Code readability**: When the depended library is optional, use

either stubs or ``#ifdef`` consistently, not a mix of both, to ensure code readability.

Quoted 1 line
#9 lore raw

20/11/2023 18:46, Jerin Jacob:

Quoted 37 lines · Morten Brørup
Quoted 27 lines
Quoted 18 lines

From: Jerin Jacob [mailto:[email protected]]
On Fri, Nov 17, 2023 at 1:57 PM Morten Brørup

Quoted 10 lines
Quoted 6 lines

From: Jerin Jacob [mailto:[email protected]]

Quoted 2 lines · On Thu, Sep 28, 2023 at 11:10 AM <[email protected]> wrote:

From: Jerin Jacob <[email protected]>
+- **Free availability**: The library must be freely available to

build in either source or binary

Quoted 1 line

+ form, with a preference for source form.

Suggest adding:

- **Free use and distribution license**: The library must be freely

available to use and distribute without any attached conditions.

Quoted 2 lines

We must require a BSD-like license, to ensure that DPDK as a whole

(including 3rd party libraries) remains BSD licensed, and can be used in commercial (closed source) applications.

Quoted 8 lines

As far as I understand, The initial scope of was “free availability” for building.
Free distribution is much wider scope. I don't think, current external libraries[1] have free distribution rights.
[1]
https://github.com/DPDK/dpdk/blob/main/doc/guides/gpus/cuda.rst
https://gitlab.com/nvidia/headers/cuda-individual/cudart/-
/blob/main/LICENSE?ref_type=heads

Quoted 8 lines

I didn't mean the library source code; I only meant the library in binary form.

It is nice if the library's header files may be distributed too, but I don't see it as a requirement, especially if they are freely available elsewhere (preferably without imposing additional restrictions on the ability to use and distribute the library in binary form).

How about this instead:

- **License permitting free use and distribution in binary form**:
The library's license must allow free and unconditional use and distribution of the library in binary form.

Quoted 7 lines

Distribution and unconditional use is not the case for existing library dependencies such as
https://gitlab.com/nvidia/headers/cuda-individual/cudart/-/blob/main/LICENSE?ref_type=heads

So I am not sure, Which is the correct thing to do. Maybe we can discuss more in tech board meeting if there are no other comments in mailing list on this topic.

I don't think we should make mandatory to have rights of redistribution. To me, being to download and install the dependency without any restriction is enough *for a driver*.
If distribution of the dependency is restricted,
then the driver will be disabled by the distro.
It is not our problem I think.

And I agree we must have stricter requirements for libraries dependencies. I am OK to mandate free distribution for such library dependencies.

Quoted 3 lines
Quoted 3 lines

We might want lawyers to verify the wording when we have agreed on our intentions.

Quoted 1 line

I am fine with either way, Feedback from others?

[...]

Quoted 27 lines
Quoted 8 lines
Quoted 8 lines
Quoted 1 line
Quoted 1 line
Quoted 1 line

+- **Code readability**: When the depended library is optional,

use

Quoted 4 lines
Quoted 2 lines

stubs to reduce the ``ifdef``

Quoted 1 line

+ clutter to enable better code readability.

Why does everyone keep insisting that stubs make code more readable?

Sometimes #ifdef is better.

Quoted 8 lines
Quoted 2 lines

Could you share a case where when #ifdefs is better(Just to understand the view).?

If an external library provides some simple functions, and a group (i.e. a subset) of functions in a DPDK library depends on that external library, then it might be more readable if those functions are enabled/disabled as a group in the DPDK library rather than individually.

E.g. the external library provides functions for statistical processing, and the DPDK library can be built with or without statistics, depending on using the external library or not. If the DPDK library is built without statistics, it should not register statistics availability towards a management module (e.g. telemetry) if it is not really implemented within the DPDK library (because the underlying functions are stubs).

It might also be a matter of personal preferences. When reviewing some source code, an #ifdef makes the availability of an underlying function perfectly clear. Blindly calling a function (of an external library) doesn't really show if the function is implemented for real, or just a stub.

In general theme in DPDK code base that we are trying to avoid a lot of #ifdef in a given C file.
Instead, we are doing following scheme.

https://github.com/DPDK/dpdk/blob/main/drivers/ml/cnxk/meson.build#L84
https://github.com/DPDK/dpdk/blob/main/drivers/ml/cnxk/meson.build#L60
https://github.com/DPDK/dpdk/blob/main/drivers/ml/cnxk/mvtvm_ml_stubs.c

Quoted 1 line

My opinion on this might be tainted by my preference for building from scratch. The distro people might see it very differently!

Quoted 13 lines

Yeah. I don't have a strong opinion, I can change to following, if there are no comments on this. Or we can discuss more in TB meeting if there are no review comments in mailing list on this topic.

**Code readability**: When the depended library is optional, use either stubs or ``#ifdef`` consistently, not a mix of both, to ensure code readability.

Quoted 5 lines
Quoted 5 lines
Quoted 3 lines

Please use something like this instead:

- **Code readability**: When the depended library is optional, use

either stubs or ``#ifdef`` consistently, not a mix of both, to ensure code readability.

We should better focus on code organisation for technical reasons:
we don't want to mix OS-specific code in a common file.
That's why stubs are preferred to implement functions with OS-specific includes, etc. If it's just a matter of disabling some code, #ifdef is fine.

#10 lore raw
Quoted 16 lines · On Mon, 27 Nov 2023 17:25:55 +0100 Thomas Monjalon <[email protected]> wrote:
Quoted 8 lines

Distribution and unconditional use is not the case for existing library dependencies such as
https://gitlab.com/nvidia/headers/cuda-individual/cudart/-/blob/main/LICENSE?ref_type=heads

So I am not sure, Which is the correct thing to do. Maybe we can discuss more in tech board meeting if there are no other comments in mailing list on this topic.

I don't think we should make mandatory to have rights of redistribution. To me, being to download and install the dependency without any restriction is enough *for a driver*.
If distribution of the dependency is restricted,
then the driver will be disabled by the distro.
It is not our problem I think.

Quoted 2 lines

And I agree we must have stricter requirements for libraries dependencies. I am OK to mandate free distribution for such library dependencies.

For me, the policy should meet these goals:

1. A developer should be able to test any driver and library for free. Ok, with any dependencies as long as they are freely available, and do not require giving up all rights in the process (click through agreements).

2. A distro maintainer should be able to build DPDK with the component if any dependent packages are available for that distribution.

3. DPDK must not become a sham front end for proprietary binary blobs. That is what Open Dataplane was, just a wrapper API around proprietary binary blob backends.

#11 lore raw

PATCH v3 1/1 doc: define qualification criteria for external library

In reply to [email protected]

From: Jerin Jacob <[email protected]>

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

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

doc/guides/contributing/index.rst +1 -0
index dcb9b1fbf0..e5a8c2b0a3 100644
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
doc/guides/contributing/library_dependency.rst new file +45 -0

45 lines not on this page · raw message

Signature · 1 line
2.43.0
Acked-by on v3 1/1
#12 lore raw

05/01/2024 13:12, [email protected]:

Quoted 9 lines

From: Jerin Jacob <[email protected]>

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

[...]

Quoted 15 lines
doc/guides/contributing/library_dependency.rst new file +15 -0
+#. **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.

doc/guides/contributing/library_dependency.rst line 34

Quoted 10 lines
doc/guides/contributing/library_dependency.rst new file +10 -0
+     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".

doc/guides/contributing/library_dependency.rst line 45

Quoted 11 lines
doc/guides/contributing/library_dependency.rst new file +11 -0
+   - 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.
#13 lore raw

PATCH v4 1/1 doc: define qualification criteria for external library

In reply to [email protected]

From: Jerin Jacob <[email protected]>

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

---
 doc/guides/contributing/index.rst             |  1 +
 .../contributing/library_dependency.rst       | 46 +++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 doc/guides/contributing/library_dependency.rst

v4:
- Address Thomas comments from https://patches.dpdk.org/project/dpdk/patch/[email protected]/

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 -0
index dcb9b1fbf0..e5a8c2b0a3 100644
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
doc/guides/contributing/library_dependency.rst new file +46 -0

46 lines not on this page · raw message

Signature · 1 line
2.43.0
#14 lore raw

PATCH v5 1/1 doc: define qualification criteria for external library

From: Jerin Jacob <[email protected]>

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

---
 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/[email protected]/

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 -0
index dcb9b1fbf0..e5a8c2b0a3 100644
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
doc/guides/contributing/library_dependency.rst new file +52 -0

52 lines not on this page · raw message

Signature · 1 line
2.43.0
#15 lore raw
Quoted 18 lines · On 08-Jan-24 1:28 PM, [email protected] wrote:

From: Jerin Jacob <[email protected]>

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

---
 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
Quoted 5 lines

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/

Review

Quoted 10 lines

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.

(quoted diff) +0 -0

b/doc/guides/contributing/index.rst

Review

Quoted 12 lines

index dcb9b1fbf0..e5a8c2b0a3 100644

doc/guides/contributing/index.rst +1 -0
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
(quoted diff) +0 -0

b/doc/guides/contributing/library_dependency.rst

doc/guides/contributing/library_dependency.rst line 7

Quoted 12 lines

new file mode 100644
index 0000000000..94025fdf60

doc/guides/contributing/library_dependency.rst new file +7 -0
@@ -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

doc/guides/contributing/library_dependency.rst

Quoted 6 lines
doc/guides/contributing/library_dependency.rst new file +6 -0
+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.

doc/guides/contributing/library_dependency.rst

Quoted 4 lines
doc/guides/contributing/library_dependency.rst new file +4 -0
+
+#. **Free availability:**
+
+   - The library must be freely available to build in either source or

binary form.

doc/guides/contributing/library_dependency.rst line 18

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+   - It shall be downloadable from a direct link. There shall not be any

requirement to explicitly

doc/guides/contributing/library_dependency.rst

Quoted 5 lines
doc/guides/contributing/library_dependency.rst new file +5 -0
+     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.

doc/guides/contributing/library_dependency.rst line 24

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+   - In the case of a permissive license, automatic inclusion in the

build process is assumed.

doc/guides/contributing/library_dependency.rst line 25

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+     For non-permissive licenses, an additional build configuration

option is required.

doc/guides/contributing/library_dependency.rst line 29

Quoted 4 lines
doc/guides/contributing/library_dependency.rst new file +4 -0
+
+#. **Distributions License:**
+
+   - No specific constraints beyond documentation.

Though we are not mandatory open distribution. However we should ask for the defining the distribution aspect clearly in the library.

doc/guides/contributing/library_dependency.rst

Quoted 5 lines
doc/guides/contributing/library_dependency.rst new file +4 -0
+
+#. **Compiler compatibility:**
+
+   - The library must be able to compile with a DPDK supported compiler

for the given execution

doc/guides/contributing/library_dependency.rst line 35

Quoted 2 lines
doc/guides/contributing/library_dependency.rst new file +2 -0
+     environment.
+     For example, for Linux, the library must be able to compile with GCC

and/or clang.

doc/guides/contributing/library_dependency.rst

Quoted 5 lines
doc/guides/contributing/library_dependency.rst new file +5 -0
+   - Library may be limited to a specific OS.
+
+#. **Meson build integration:**
+
+   - The library must have standard method like ``pkg-config`` for

seamless integration with

doc/guides/contributing/library_dependency.rst

Quoted 5 lines
doc/guides/contributing/library_dependency.rst new file +5 -0
+     DPDK's build environment.
+
+#. **Code readability:**
+
+   - Optional dependencies should use stubs to minimize ``ifdef``

clutter, promoting improved

doc/guides/contributing/library_dependency.rst

Quoted 6 lines
doc/guides/contributing/library_dependency.rst new file +6 -0
+     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, specific

Quoted 1 line
doc/guides/contributing/library_dependency.rst new file +1 -0
+     library and/or driver will not built if dependencies are not meet.
#16 lore raw
Quoted 16 lines · Hemant Agrawal
Quoted 12 lines · On 08-Jan-24 1:28 PM, [email protected] wrote:

From: Jerin Jacob <[email protected]>

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

Quoted 6 lines

doc/guides/contributing/library_dependency.rst line 29

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+#. **Distributions License:**
+
+   - No specific constraints beyond documentation.

Though we are not mandatory open distribution. However we should ask for the defining the distribution aspect clearly in the library.

How about following then,

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

If not, please suggest the exact wording.

#17 lore raw
Quoted 24 lines · Jerin Jacob
Quoted 16 lines · Hemant Agrawal
Quoted 12 lines · On 08-Jan-24 1:28 PM, [email protected] wrote:

From: Jerin Jacob <[email protected]>

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

Quoted 6 lines

doc/guides/contributing/library_dependency.rst line 29

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+#. **Distributions License:**
+
+   - No specific constraints beyond documentation.

Though we are not mandatory open distribution. However we should ask for the defining the distribution aspect clearly in the library.

Quoted 6 lines

How about following then,

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

If not, please suggest the exact wording.

I think above is ok.

Quoted 1 line
#18 lore raw
Quoted 27 lines · Hemant Agrawal
Quoted 24 lines · Jerin Jacob
Quoted 22 lines · Hemant Agrawal
Quoted 13 lines · On 08-Jan-24 1:28 PM, [email protected] wrote:

From: Jerin Jacob <[email protected]>

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

doc/guides/contributing/library_dependency.rst line 29

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+#. **Distributions License:**
+
+   - No specific constraints beyond documentation.

Though we are not mandatory open distribution. However we should ask for the defining the distribution aspect clearly in the library.

Quoted 8 lines
Quoted 6 lines

How about following then,

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

If not, please suggest the exact wording.

I think above is ok.

I will add it next version.

Quoted 3 lines
Quoted 3 lines
#19 lore raw
In reply to Jerin Jacob
Quoted 24 lines · On Mon, 8 Jan 2024 14:01:37 +0530 Jerin Jacob <[email protected]> wrote:
Quoted 16 lines · Hemant Agrawal
Quoted 12 lines · On 08-Jan-24 1:28 PM, [email protected] wrote:

From: Jerin Jacob <[email protected]>

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

Quoted 6 lines

doc/guides/contributing/library_dependency.rst line 29

Quoted 3 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+#. **Distributions License:**
+
+   - No specific constraints beyond documentation.  

Though we are not mandatory open distribution. However we should ask for the defining the distribution aspect clearly in the library.

Quoted 6 lines

How about following then,

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

If not, please suggest the exact wording.

The wording specifies the intent here, and that is not what matters. This is not a legal document where someone will take us to court if the board doesn't accept a library.

#20 lore raw
Quoted 6 lines

From: Stephen Hemminger [mailto:[email protected]]
Sent: Monday, 8 January 2024 18.19

The wording specifies the intent here, and that is not what matters. This is not a legal document where someone will take us to court if the board doesn't accept a library.

The introduction/preamble of the page should mention this, or we risk upsetting people very much if we don't accept a compliant library. E.g.:

This document serves as an overall description of what is expected of dependent libraries. The final decision to accept or reject is at the discretion of the DPDK Project's Technical Board.

#21 lore raw
Quoted 11 lines · Morten Brørup
Quoted 7 lines

From: Stephen Hemminger [mailto:[email protected]]
Sent: Monday, 8 January 2024 18.19

The wording specifies the intent here, and that is not what matters. This is not a legal document where someone will take us to court if the board doesn't accept a library.

The introduction/preamble of the page should mention this, or we risk upsetting people very much if we don't accept a compliant library. E.g.:

This document serves as an overall description of what is expected of dependent libraries.

The similar text already present.

Quoted 1 line

The final decision to accept or reject is at the discretion of the DPDK Project's Technical Board.

I will add the above in next version.

[main]dell[dpdk.org] $ git diff

(quoted diff) +0 -0

b/doc/guides/contributing/library_dependency.rst
index 94025fdf60..f60ed92a64 100644

doc/guides/contributing/library_dependency.rst +0 -0
@@ -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.

Quoted 1 line
#22 lore raw
In reply to [email protected]
Quoted 6 lines

From: [email protected] [mailto:[email protected]]
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?

Quoted 56 lines

[1]
http://mails.dpdk.org/archives/dev/2019-June/135847.html
https://mails.dpdk.org/archives/dev/2024-January/284849.html

---
 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-
[email protected]/

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 -0
index dcb9b1fbf0..e5a8c2b0a3 100644
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
doc/guides/contributing/library_dependency.rst new file +7 -0
new file mode 100644
index 0000000000..94025fdf60
@@ -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
Quoted 2 lines

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.

Quoted 10 lines
doc/guides/contributing/library_dependency.rst new file +5 -0
+
+#. **Documentation:**
+
+   - Must have adequate documentation for the steps to build it.
+   - Must have clear license documentation on distribution and usage

aspects of external library.

doc/guides/contributing/library_dependency.rst new file +4 -0
+
+#. **Free availability:**
+
+   - The library must be freely available to build in either source or
Quoted 4 lines

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

Quoted 9 lines
doc/guides/contributing/library_dependency.rst new file +4 -0
+
+#. **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.

doc/guides/contributing/library_dependency.rst

Quoted 2 lines
doc/guides/contributing/library_dependency.rst new file +2 -0
+
+#. **Distributions License:**

Distributions -> Distribution

Quoted 8 lines
doc/guides/contributing/library_dependency.rst new file +6 -0
+
+   - 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".

Quoted 3 lines

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

Quoted 11 lines
doc/guides/contributing/library_dependency.rst new file +4 -0
+
+#. **Meson build integration:**
+
+   - The library must have standard method like ``pkg-config`` for

seamless integration with

doc/guides/contributing/library_dependency.rst new file +5 -0
+     DPDK's build environment.
+
+#. **Code readability:**
+
+   - Optional dependencies should use stubs to minimize ``ifdef``

clutter, promoting improved

doc/guides/contributing/library_dependency.rst line 50

Quoted 5 lines
doc/guides/contributing/library_dependency.rst new file +5 -0
+     code readability.
+
+#. **Dependency nature:**
+
+   - The external library dependency should be optional.

should -> must ?

Quoted 4 lines

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

Quoted 2 lines

--
2.43.0

#23 lore raw
Quoted 10 lines · Morten Brørup
Quoted 7 lines

From: [email protected] [mailto:[email protected]]
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?

+ [email protected]

Not sure. I will Cc the [email protected] in next version of patch anyway.

Quoted 66 lines
Quoted 57 lines

[1]
http://mails.dpdk.org/archives/dev/2019-June/135847.html
https://mails.dpdk.org/archives/dev/2024-January/284849.html

---
 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-
[email protected]/

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 -0
index dcb9b1fbf0..e5a8c2b0a3 100644
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
doc/guides/contributing/library_dependency.rst new file +7 -0
new file mode 100644
index 0000000000..94025fdf60
@@ -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
Quoted 2 lines

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.

Quoted 16 lines
Quoted 10 lines
doc/guides/contributing/library_dependency.rst new file +5 -0
+
+#. **Documentation:**
+
+   - Must have adequate documentation for the steps to build it.
+   - Must have clear license documentation on distribution and usage

aspects of external library.

doc/guides/contributing/library_dependency.rst new file +4 -0
+
+#. **Free availability:**
+
+   - The library must be freely available to build in either source or
Quoted 4 lines

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.

Quoted 13 lines
Quoted 10 lines
doc/guides/contributing/library_dependency.rst new file +4 -0
+
+#. **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?

Quoted 6 lines

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.

doc/guides/contributing/library_dependency.rst

Quoted 2 lines
doc/guides/contributing/library_dependency.rst new file +2 -0
+
+#. **Distributions License:**

Distributions -> Distribution

Ack

Quoted 12 lines
Quoted 9 lines
doc/guides/contributing/library_dependency.rst new file +6 -0
+
+   - 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.

Quoted 1 line

E.g. "execution environment" -> "target environment".

No strong opinion. I will change to target environment.

Review

Quoted 9 lines
Quoted 4 lines

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

(quoted diff) +1 -1
-   - Library may be limited to a specific OS.
+   - Library may be limited to a specific operating system and/or specific hardware.

Ack

Quoted 11 lines
Quoted 11 lines
doc/guides/contributing/library_dependency.rst new file +4 -0
+
+#. **Meson build integration:**
+
+   - The library must have standard method like ``pkg-config`` for

seamless integration with

doc/guides/contributing/library_dependency.rst new file +5 -0
+     DPDK's build environment.
+
+#. **Code readability:**
+
+   - Optional dependencies should use stubs to minimize ``ifdef``
Quoted 8 lines

doc/guides/contributing/library_dependency.rst

Quoted 6 lines

clutter, promoting improved

doc/guides/contributing/library_dependency.rst new file +5 -0
+     code readability.
+
+#. **Dependency nature:**
+
+   - The external library dependency should be optional.

should -> must ?

Ack

Quoted 7 lines
Quoted 5 lines

+ 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

Quoted 6 lines

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

(quoted diff) +0 -0

b/doc/guides/contributing/library_dependency.rst
index 94025fdf60..de62fec209 100644

doc/guides/contributing/library_dependency.rst +0 -0
@@ -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.

Quoted 5 lines
Quoted 4 lines

--
2.43.0

#24 lore raw

PATCH v6 1/1 doc: define qualification criteria for external library

In reply to [email protected]

From: Jerin Jacob <[email protected]>

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

---

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/[email protected]/

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
doc/guides/contributing/index.rst +1 -0
index dcb9b1fbf0..e5a8c2b0a3 100644
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
doc/guides/contributing/library_dependency.rst new file +53 -0

53 lines not on this page · raw message

Signature · 1 line
2.43.0
#25 lore raw
Quoted 7 lines · On Tue, Jan 9, 2024 at 7:40 PM <[email protected]> wrote:

From: Jerin Jacob <[email protected]>

Define qualification criteria for external library based on a techboard meeting minutes [1] and past learnings from mailing list discussion.

Quoted 6 lines

[1]
http://mails.dpdk.org/archives/dev/2019-June/135847.html
https://mails.dpdk.org/archives/dev/2024-January/284849.html

Ping for merge

Quoted 97 lines

---

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/[email protected]/

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
doc/guides/contributing/index.rst +1 -0
index dcb9b1fbf0..e5a8c2b0a3 100644
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
doc/guides/contributing/library_dependency.rst new file +53 -1
new file mode 100644
index 0000000000..3b275f1c52
@@ -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

#27 lore raw
In reply to [email protected]
Quoted 62 lines · On 1/9/2024 2:10 PM, [email protected] wrote:

From: Jerin Jacob <[email protected]>

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

---

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/[email protected]/

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
doc/guides/contributing/index.rst +1 -0
index dcb9b1fbf0..e5a8c2b0a3 100644
@@ -15,6 +15,7 @@ Contributor's Guidelines
     documentation
     unit_test
     new_library
+    library_dependency
     patches
     vulnerability
     stable
doc/guides/contributing/library_dependency.rst new file +8 -0
new file mode 100644
index 0000000000..3b275f1c52
@@ -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.

doc/guides/contributing/library_dependency.rst line 18

Quoted 10 lines
doc/guides/contributing/library_dependency.rst new file +10 -0
+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."

doc/guides/contributing/library_dependency.rst line 24

Quoted 7 lines
doc/guides/contributing/library_dependency.rst new file +6 -0
+   - 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?

doc/guides/contributing/library_dependency.rst line 27

Quoted 4 lines
doc/guides/contributing/library_dependency.rst new file +3 -0
+   - 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?

doc/guides/contributing/library_dependency.rst line 35

Quoted 9 lines
doc/guides/contributing/library_dependency.rst new file +8 -0
+#. **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?

Quoted 9 lines
doc/guides/contributing/library_dependency.rst new file +8 -0
+     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.
+

doc/guides/contributing/library_dependency.rst line 53

Quoted 10 lines
doc/guides/contributing/library_dependency.rst new file +10 -0
+#. **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?

#28 lore raw
In reply to [email protected]

On Fri, 5 Jan 2024 17:42:15 +0530
<[email protected]> 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.

#29 lore raw
Quoted 6 lines · Stephen Hemminger

On Fri, 5 Jan 2024 17:42:15 +0530
<[email protected]> wrote:

Quoted 6 lines

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

(quoted diff) +0 -0

b/doc/guides/contributing/library_dependency.rst
index 367e380a89..7b008d7e8a 100644

doc/guides/contributing/library_dependency.rst +0 -0
@@ -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.