Description of public vs internal headers in pdsc

[massonal]

Hi,

I think I have found a use case that is not yet covered in the spec; I'd appreciate some guidance on how to handle it, and/or suggest the pdsc specification be extended to cover it.

Here is the case: a component I'm developing has headers files (.h):

• some of which documenting the public interfaces I want exposed to users,
• and others meant for internal use (implementation details, if you will).

While I want [my component and] my users to be able to include the public headers, I would like the internal ones to only be in scope in my component, not to my users.

In the current PDSC specification, I have found the following:

Table: File Categories

category=	Description
header	Header file used in the component. Sets an include file path and adds the file name attribute to the list of files to be added to a module using the #include statement. Note: specify only those files as header files that form part of the API of the component, required to use the component

As said the note, this category is only meant for "public" headers.
However, I could find no suitable category for "internal" headers -- how is this case currently supposed to be handled, if at all?

Regards --

[jkrech]

Conceptually the "internal" header files are not explicitly listed in the meta information. Only the necessary include paths are specified in order to ensure a successful build. The assumption is that user's of a component will only make use of the public header file(s), as internal headers must not be included outside of the component.
Are we missing something here?

[LMESTM]

@jkrech Thanks for quick feedback.

We know that indeed "include" is a way forward and this is not blocking (this is why @massonal raised the point as a discussion).

2 further questions to dig in further into point:

• in case all the files are in the same folder, this means other modules may have same level of access to internal and public header files. This is a point @massonal reported when we pointed out the "include" category. Or is there an extra check in the build chain to verify that only the public headers are included ?
• I remember that we discussed in the past that pack owners may want to list exhaustively all the files in the pack, so does it mean that current proposal wouldn't allow it ?

[ReinhardKeil]

• Today, the various tools have not way to automatically categorize header files (private vs. public). Do you have any ideas on how to solve that?

• You are right, since there is an include path added, any file could include private headers, provided that the name is known. A solution would be not to define the include path but use relative path names in the source files that use this private header files.

• The current implementation has no way to differ between "public" or "private" header files. The discussion about exhaustively lists all files has never concluded.

[LMESTM]

Thanks @ReinhardKeil - status is clear.
We can definitely proceed for now with one of the current solutions and I'll discuss with @fred-r and other teammates to see whether we want to propose any evolution.

[LMESTM]

• Today, the various tools have not way to automatically categorize header files (private vs. public). Do you have any ideas on how to solve that?

With today's spec, my first idea was to consider adding "include" path for building the component itself only, not for the users of this component. But I am afraid that would break many packs that use include/ for also listing their headers. So not a good idea ... that leaves us with the question whether it's worth adding a new category

[ReinhardKeil]

Maybe you take a look to https://github.com/ARM-software/CMSIS-FreeRTOS/blob/main/ARM.CMSIS-FreeRTOS.pdsc#L980

It defines just the include path for non-public headers. Only the public headers are explicitly stated in the PDSC file.

[massonal]

Let me illustrate my point:
This is what I have in the pdsc regarding the public header, and I'm fine with it:

<file category="header" name="my_public.h"/>

Now, regarding the internal header, I have several approaches:

• <file category="header" name="Inc/my_internal.h"/>
  <!-- or, with similar advantages and drawbacks: -->
  <file category="include" name="Inc/"/>

  -> this is unsatisfying, because then the internal header is reachable from user code.

• <!-- nothing regarding my_internal.h -->

  -> this is unsatisfying, because then even the module has no access to the internal header.

Is the issue clearer this way? I really mean this as a kind of access right control: giving access to each stakeholder to exactly what it needs, and no more.
If you know CMake, you can relate this to the PUBLIC and PRIVATE keywords from e.g., target_include_directories() -- that's the kind of effect I would like to implement.

[ReinhardKeil]

Clearly we need to define additional file categories to solve this.

However for your case (3), the source file may use

#include "Inc/myinternal.h"

[jkrech]

It is my understanding that CMake can have an include path being private or public but not individual header files. Also private header files shall be located in a different include directory than the public ones. Am I missing something?

[massonal]

It is my understanding that CMake can have an include path being private or public but not individual header files.

That's right. Anyway all this stuff about header files ends up as include paths in the compiler command (-I...), so we should really talk about "public headers directories" and "private headers directories"...
So, yeah, you can't really mix public and private headers in the same directory, or there will be holes in the access control.

[fred-r]

See also #176: can be extended not only to public/private but to the visibility of selected components header files only