From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id B929143381; Mon, 20 Nov 2023 18:47:19 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 43D0242DD2; Mon, 20 Nov 2023 18:47:19 +0100 (CET) Received: from mail-pl1-f177.google.com (mail-pl1-f177.google.com [209.85.214.177]) by mails.dpdk.org (Postfix) with ESMTP id 2BB204027A; Mon, 20 Nov 2023 18:47:18 +0100 (CET) Received: by mail-pl1-f177.google.com with SMTP id d9443c01a7336-1cf52e5e07eso12665305ad.0; Mon, 20 Nov 2023 09:47:18 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1700502437; x=1701107237; darn=dpdk.org; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=7YebTRYjPcMfccVvIHEFRbyX/0c78iWOr/QBpW1w6cw=; b=MEk5+uNUbCQTOmkDTk/g+FNFDwMy1Ut/EvBa0AiFCBGHpDj3vqFXWCcET8Dx96fQ44 wiWWi0YCsvKDeeloLKl4NMlfJ1qu8Nbt1KYrxqYUiPAt8qnoMcUoXSCtSGE6U4209qXx qtr+Ld7N8I/YB6mqFMWCOMxxOZaZvHU9uzBRrXtHY8MQ4A8y9s9P/r6XGkvWucvB0Hdw NoW/7r5jZz4GRa3tqxULuHdXLN+5tXv+lSVfVcL6vf+UUX8+xNbMuwksULDTJfWIzAkJ jine41DvOi/bz3crB8EsLP8/J5zab+sTt/Gwuo42HEN+GjMvT1Ec1Zb09ZekbYimURXQ SiZA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700502437; x=1701107237; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=7YebTRYjPcMfccVvIHEFRbyX/0c78iWOr/QBpW1w6cw=; b=uTiWDJG8yo9WhCANS01Nu60EtzPPQ+XD+uB4zS3+ABld9NtFpBR4/0totT/mnkRY9X IIMZTs8EgXs0Lli0fyuA1cJzzJS6wE163Ojy2JZweRqpdE1jelYYNX9YiInpCZYgcUTq oNqCpD4UoU0vDkxgI1ZrWSTiScgaETzSBc0g40EwEizlIOzswBSdBhQ1xPiTScCwx2Qk Z3QfrbiV8EKqs5k5FsGJILIitP1uW6Lki5RB6I3PBiR4MfdNqOsMw2V4kZ2zwrvSRGD7 Yqmc5tS0xH8Wt0urRP1JqnYNc0k79u3BapKtiR4XsIb6OZYnu9ygH8f4iqeSFIvcgx7J aaTQ== X-Gm-Message-State: AOJu0YwfaQdn56tiarJWpq7X9zGZBO7KhOIyoO5PYWfdeZxyl0fEgXKf YGU/Z0HBmt1+YJplK2hPdHpSdX5b5rQamtWtW60V0H1JQLNy/A== X-Google-Smtp-Source: AGHT+IEC1s9EQTPjrzIt0FF1cVqvKJyzev53Gchzv/6CROgKe4sxIYfDtBEz4LLFemb5rwIxigA3DSrMExhsOI22I24= X-Received: by 2002:a17:90b:1a92:b0:27f:e955:5682 with SMTP id ng18-20020a17090b1a9200b0027fe9555682mr283422pjb.3.1700502437030; Mon, 20 Nov 2023 09:47:17 -0800 (PST) MIME-Version: 1.0 References: <20230928051648.562526-1-jerinj@marvell.com> <20230928054036.645183-1-jerinj@marvell.com> <98CBD80474FA8B44BF855DF32C47DC35E9F036@smartserver.smartshare.dk> <98CBD80474FA8B44BF855DF32C47DC35E9F043@smartserver.smartshare.dk> In-Reply-To: <98CBD80474FA8B44BF855DF32C47DC35E9F043@smartserver.smartshare.dk> From: Jerin Jacob Date: Mon, 20 Nov 2023 23:16:50 +0530 Message-ID: Subject: Re: [dpdk-dev] [PATCH v2] doc: define qualification criteria for external library To: =?UTF-8?Q?Morten_Br=C3=B8rup?= Cc: jerinj@marvell.com, dev@dpdk.org, techboard@dpdk.org, bruce.richardson@intel.com Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org On Sun, Nov 19, 2023 at 2:23=E2=80=AFPM Morten Br=C3=B8rup wrote: > > > From: Jerin Jacob [mailto:jerinjacobk@gmail.com] > > Sent: Sunday, 19 November 2023 08.08 > > > > On Fri, Nov 17, 2023 at 1:57=E2=80=AFPM Morten Br=C3=B8rup > > wrote: > > > > > > > From: Jerin Jacob [mailto:jerinjacobk@gmail.com] > > > > Sent: Friday, 17 November 2023 05.34 > > > > > > > > On Thu, Sep 28, 2023 at 11:10=E2=80=AFAM wrote= : > > > > > > > > > > From: Jerin Jacob > > > > > > > > > > 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 > > > > > > > > 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 > > > > > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > > > > + > > > > > +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. > > > > As far as I understand, The initial scope of was =E2=80=9Cfree availabi= lity=E2=80=9D > > 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=3Dheads > > 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 do= n't see it as a requirement, especially if they are freely available elsewh= ere (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 distribut= ion 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/LICENS= E?ref_type=3Dheads 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. > > We might want lawyers to verify the wording when we have agreed on our in= tentions. > > > > > I am fine with either way, Feedback from others? > > > > > > > > > > + > > > > > +- **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 > > > > Ack. Will fix next version. > > > > > > > > > > + 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. > > > > 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 sta= tistics, it should not register statistics availability towards a managemen= t module (e.g. telemetry) if it is not really implemented within the DPDK l= ibrary (because the underlying functions are stubs). > > It might also be a matter of personal preferences. When reviewing some so= urce code, an #ifdef makes the availability of an underlying function perfe= ctly clear. Blindly calling a function (of an external library) doesn't rea= lly 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 > > My opinion on this might be tainted by my preference for building from sc= ratch. 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. > > > > > > > > > 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. > > >