Re: [PATCH] docs/devel: Document conventional file prefixes and suffixes

["Philippe Mathieu-Daudé" <philmd@linaro.org>]

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é <philmd@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.bennee@linaro.org>
>> Signed-off-by: Philippe Mathieu-Daudé <philmd@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.