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".
> +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?
> + 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?
> Block structure
> ===============
>
> --
> 2.41.0
>
Thanks,
Zhao
