From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
	by inbox.dpdk.org (Postfix) with ESMTP id 1DA8BA09E4;
	Thu, 28 Jan 2021 12:47:53 +0100 (CET)
Received: from [217.70.189.124] (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id 8E76F4067A;
	Thu, 28 Jan 2021 12:47:52 +0100 (CET)
Received: from mga11.intel.com (mga11.intel.com [192.55.52.93])
 by mails.dpdk.org (Postfix) with ESMTP id 1C68340395
 for <dev@dpdk.org>; Thu, 28 Jan 2021 12:47:50 +0100 (CET)
IronPort-SDR: 6SD18RIKSdtPtfnrjn8uEfXd0C/SLOVRp6z8NRqZIuQXcIWs4SqNtNdAUDHSE9jB07Rkjjbpj3
 7PxydtDJBdTw==
X-IronPort-AV: E=McAfee;i="6000,8403,9877"; a="176712497"
X-IronPort-AV: E=Sophos;i="5.79,382,1602572400"; d="scan'208";a="176712497"
Received: from orsmga008.jf.intel.com ([10.7.209.65])
 by fmsmga102.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
 28 Jan 2021 03:47:50 -0800
IronPort-SDR: dPgc2umFWlF4t3OFY9uLG+4zcA2EOOXwHB+SBQ+l30YiJtfv+jYfSaWwGhHHCLvgWOErOvfKpp
 an9Pgb/JM20A==
X-IronPort-AV: E=Sophos;i="5.79,382,1602572400"; d="scan'208";a="388773832"
Received: from bricha3-mobl.ger.corp.intel.com ([10.252.11.53])
 by orsmga008-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-SHA;
 28 Jan 2021 03:47:48 -0800
Date: Thu, 28 Jan 2021 11:47:45 +0000
From: Bruce Richardson <bruce.richardson@intel.com>
To: David Marchand <david.marchand@redhat.com>
Cc: dev <dev@dpdk.org>, Thomas Monjalon <thomas@monjalon.net>,
 Ray Kinsella <mdr@ashroe.eu>
Message-ID: <20210128114745.GG899@bricha3-MOBL.ger.corp.intel.com>
References: <20210114110606.21142-1-bruce.richardson@intel.com>
 <20210127173330.1671341-1-bruce.richardson@intel.com>
 <CAJFAV8zhnkEN2k=L-GziXV8p5W_4mTsR+tJis7ASbPmkhatDbA@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <CAJFAV8zhnkEN2k=L-GziXV8p5W_4mTsR+tJis7ASbPmkhatDbA@mail.gmail.com>
Subject: Re: [dpdk-dev] [PATCH v6 0/8] add checking of header includes
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>

On Thu, Jan 28, 2021 at 11:55:34AM +0100, David Marchand wrote:
> On Wed, Jan 27, 2021 at 6:33 PM Bruce Richardson
> <bruce.richardson@intel.com> wrote:
> >
> > As a general principle, each header file should include any other
> > headers it needs to provide data type definitions or macros. For
> > example, any header using the uintX_t types in structures or function
> > prototypes should include "stdint.h" to provide those type definitions.
> >
> > In practice, while many, but not all, headers in DPDK did include all
> > necessary headers, it was never actually checked that each header could
> > be included in a C file and compiled without having any compiler errors
> > about missing definitions.  The script "check-includes.sh" could be used
> > for this job, but it was not called out in the documentation, so many
> > contributors may not have been aware of it's existance. It also was
> > difficult to run from a source-code directory, as the script did not
> > automatically allow finding of headers from one DPDK library directory
> > to another [this was probably based on running it on a build created by
> > the "make" build system, where all headers were in a single directory].
> > To attempt to have a build-system integrated replacement, this patchset
> > adds a "chkincs" app in the buildtools directory to verify this on an
> > ongoing basis.
> >
> > This chkincs app does nothing when run, and is not installed as part of
> > a DPDK "ninja install", it's for build-time checking only. Its source
> > code consists of one C file per public DPDK header, where that C file
> > contains nothing except an include for that header.  Therefore, if any
> > header is added to the lib folder which fails to compile when included
> > alone, the build of chkincs will fail with a suitable error message.
> > Since this compile checking is not needed on most builds of DPDK, the
> > building of chkincs is disabled by default, but can be enabled by the
> > "test_includes" meson option. To catch errors with patch submissions,
> > the final patch of this series enables it for a single build in
> > test-meson-builds script.
> >
> > Future work could involve doing similar checks on headers for C++
> > compatibility, which was something done by the check-includes.sh script
> > but which is missing here.
> >
> > V6:
> > * Added release notes updates for:
> >    - renamed, no-longer-installed header files
> >    - new "check_includes" build option
> >    - removal of old check_includes script
> > * Included acks from previous versions
> 
> I have some comments, see replies on patches.
> I can address them if you are ok, and I would take this series for
> -rc2 without needing a respin.
> 

Thomas has some feedback too now, and I think there are one or two patches
where we might want to wait for consensus. However, if you are happy to
take these as they are and do any fixups yourself feel free.

> Sidenote: I like how we are hiding API by simply not exporting headers.
> We need more cleanups like this.
> Ethdev has been cleaned; this will probably remove the need for the
> ABI exception on eth_dev_ops.
> Eventdev, other driver classes and bus drivers will probably be the
> next to look at.
> 

Yes, there is plenty more cleanup work still needed.

* The chkincs support added here integrates nicely into the build but does
  not fully support everything that the old script did, so investigation is
  needed especially for c++ checking support.

* Beyond that we should also look to do cleanup based on IWYU to remove excess
  headers. This work gives us a nice safety-net for that as it should flag to
  us if we every remove too much from a public header.