Hi,
On 27/12/23 08:12, Zhao Liu wrote:
Hi Philippe,
On Tue, Dec 26, 2023 at 04:04:41PM +0100, Philippe Mathieu-Daudé wrote:
Date: Tue, 26 Dec 2023 16:04:41 +0100
From: Philippe Mathieu-Daudé <phi...@linaro.org>
Subject: [PATCH] docs/devel: Document conventional file prefixes and
suffixes
X-Mailer: git-send-email 2.41.0
Some header and source file names use common prefix / suffix
but we never really ruled a convention. Start doing so with
the current patterns from the tree.
Suggested-by: Alex Bennée <alex.ben...@linaro.org>
Signed-off-by: Philippe Mathieu-Daudé <phi...@linaro.org>
---
docs/devel/style.rst | 49 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 49 insertions(+)
diff --git a/docs/devel/style.rst b/docs/devel/style.rst
index 2f68b50079..4da50eb2ea 100644
--- a/docs/devel/style.rst
+++ b/docs/devel/style.rst
@@ -162,6 +162,55 @@ pre-processor. Another common suffix is ``_impl``; it is
used for the
concrete implementation of a function that will not be called
directly, but rather through a macro or an inline function.
+File Naming Conventions
+-----------------------
+
+Public headers
+~~~~~~~~~~~~~~
+
+Headers expected to be access by multiple subsystems must reside in
+the ``include/`` folder. Headers local to a subsystem should reside in
+the sysbsystem folder, if any (for example ``qobject/qobject-internal.h``
+can only be included by files within the ``qobject/`` folder).
+
+Header file prefix and suffix hints
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When headers relate to common concept, it is useful to use a common
+prefix or suffix.
+
+When headers relate to the same (guest) subsystem, the subsystem name is
+often used as prefix. If headers are already in a folder named as the
+subsystem, prefixing them is optional.
+
+For example, hardware models related to the Aspeed systems are named
+using the ``aspeed_`` prefix.
+
+Headers related to the same (host) concept can also use a common prefix.
^^^^^^
Maybe "suffix"?
since below you provide examples of "suffix".
Oops, indeed :)
+For example OS specific headers use the ``-posix`` and ``-win32`` suffixes.
+
+Registered file suffixes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+* ``.inc``
+
+ Source files meant to be included by other source files as templates
+ must use the ``.c.inc`` suffix. Similarly, headers meant to be included
+ multiple times as template must use the ``.h.inc`` suffix.
+
+Recommended file prefixes / suffixes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* ``target`` and ``common`` suffixes
+
+ Files which are specific to a target should use the ``target`` suffix.
emm, it seems linux-use/* and bsd-user/* have many ``target`` prefix
headers. Should they get cleaned up?
No, these are special to user emulation, and are defined for each
target, to be included once per target build, i.e. for Linux:
$ git grep '#include "target_' linux-user
linux-user/elfload.c:23:#include "target_signal.h"
linux-user/flatload.c:43:#include "target_flat.h"
linux-user/main.c:50:#include "target_elf.h"
linux-user/mmap.c:26:#include "target_mman.h"
linux-user/qemu.h:12:#include "target_syscall.h"
linux-user/strace.c:21:#include "target_mman.h"
linux-user/syscall.c:27:#include "target_mman.h"
linux-user/syscall.c:6313:#include "target_prctl.h"
linux-user/syscall.c:8252:#include "target_proc.h"
linux-user/syscall_defs.h:497:#include "target_signal.h"
linux-user/syscall_defs.h:701:#include "target_resource.h"
linux-user/syscall_defs.h:1230:#include "target_mman.h"
linux-user/syscall_defs.h:2256:#include "target_fcntl.h"
linux-user/syscall_defs.h:2577:#include "target_errno_defs.h"
linux-user/user-internals.h:184:#include "target_cpu.h"
linux-user/user-internals.h:185:#include "target_structs.h"
I'll add a paragraph to describe that.
+ Such ``target`` suffixed headers usually *taint* the files including them
+ by making them target specific.
+
+ Files common to all targets should use the ``common`` suffix, to provide
+ a hint that these files can be safely included from common code.
+
+
An additional question that kind of confuses me is whether header file
naming should use "-" or "_" to connect prefixes/suffixes?
Yeah, we use a mix of both with no particular preference.
Not sure it is worth cleaning only for aesthetic style, let's see
what other think.
Block structure
===============
--
2.41.0
Thanks!
Phil.
