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

[Morten Brørup]

> From: Jerin Jacob [mailto:jerinjacobk at gmail.com]
> Sent: Friday, 17 November 2023 05.34
> 
> On Thu, Sep 28, 2023 at 11:10 AM <jerinj at marvell.com> wrote:
> >
> > From: Jerin Jacob <jerinj at 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
> >
> > Signed-off-by: Jerin Jacob <jerinj at marvell.com>
> 
> Ping for review and/or merge.
> 
> 
> > ---
> > 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
> >
> > 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..687a3b6cef
> > --- /dev/null
> > +++ b/doc/guides/contributing/library_dependency.rst
> > @@ -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.

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.

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

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

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

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.