From patchwork Mon Jun 15 18:16:25 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 26890 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 40989C324C for ; Mon, 15 Jun 2026 18:16:28 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 58315623F6; Mon, 15 Jun 2026 20:16:27 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="uS/O5ift"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id B6594623CB for ; Mon, 15 Jun 2026 20:16:26 +0200 (CEST) Received: from killaraus.ideasonboard.com (2001-14ba-70f3-e800--a06.rev.dnainternet.fi [IPv6:2001:14ba:70f3:e800::a06]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 96A80241 for ; Mon, 15 Jun 2026 20:15:53 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1781547353; bh=RkNnVwNFAkO5mXBpnrVOQWDZtt5EahvnxLFnr6EugiA=; h=From:To:Subject:Date:From; b=uS/O5ift1GGNnUytk9LJ74xY2W9YRaSXSciYATJjl6Nx9RASL+xW/slRQleTChB6B bC6dYQ07V51ox7qrEAzKcYmTDNofd2O5RsdhCUSvRJu0oBYzuEs4hhj62jnqpRGaGq Kj0uMkVb65KgbL9c5I/UJ2/BtCTJsl43lVWbIFqg= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH] Documentation: coding-style: Document rule about indirect includes Date: Mon, 15 Jun 2026 21:16:25 +0300 Message-ID: <20260615181625.2934965-1-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.53.0 MIME-Version: 1.0 X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" libcamera has a coding style policy that forbids relying on indirect includes, with some exceptions. As many policies, it is currently undocumented. Fix it. Signed-off-by: Laurent Pinchart --- Documentation/coding-style.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) base-commit: ff5cb4f17b0b9989dd853b4d4320ddb2c59a9c0e diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst index 5b90a43a6813..2154331596ac 100644 --- a/Documentation/coding-style.rst +++ b/Documentation/coding-style.rst @@ -61,6 +61,35 @@ document: Code Style for indentation, braces, spacing, etc * Headers are guarded by the use of '#pragma once' + +Headers +------- + +Every source file shall ensure that all types and symbols it uses are declared, +either by including corresponding headers, or providing forward declarations. +Forward declarations should be used as much as possible in header files to +reduce compilation time. + +Relying on types and symbols being provided by indirect includes increases the +risk of compilation breakages, due either to code changes altering which +headers get indirectly include, or to indirect inclusions not being identical +across all configurations. The latter category is particularly difficult to +guard against through CI and can affect end users. + +For these reasons, relying on indirect includes to provide type declarations is +prohibited, except when the nature of an included headers guarantees that it +provides such declarations: + +* Code that declares a class inheriting from a base class can assume the header + for the base class provides declarations for all types used as arguments of + virtual functions. +* Code that implements member functions of a class can assume the header for + the class provides declarations for all types used as arguments to the class' + member functions. + +In those cases, header files may skip forward declarations and source files may +skip inclusion of headers. + Order of Includes ~~~~~~~~~~~~~~~~~