Coding Convention: Sorting Order of Includes?

[Gedare Bloom]

On Wed, Jan 8, 2020 at 9:33 AM Joel Sherrill <joel at rtems.org> wrote:
>
>
>
> On Wed, Jan 8, 2020 at 8:03 AM Sebastian Huber <sebastian.huber at embedded-brains.de> wrote:
>>
>> On 03/01/2020 17:52, Gedare Bloom wrote:
>> > Hello all,
>> >
>> > Vijay noted in another thread that:
>> > "For RTEMS, I don't see any preference mentioned in the docs for the
>> > order or includes:
>> > https://docs.rtems.org/branches/master/eng/coding-conventions.html
>> >
>> > In libbsd, however, the FreeBSD style guide is followed which has a
>> > preference for the order of header includes:
>> > https://www.freebsd.org/cgi/man.cgi?query=style&apropos=0&sektion=9"
>> >
>> > Should we consider any rules? I would suspect that at least ordering
>> > by API layering could be helpful. Lexical sorting is nice but probably
>> > there will be some exceptions based on dependencies.
>>
>> I would use the Google rule:
>>
>> https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes
>>
>> It is compatible to the FreeBSD style (except the include related header
>> first).
>
>
> FWIW I don't like how they worded that. I think they mean the public header files.
> Related would include private header files which are grouped later. But the rationale
> makes sense as long as there isn't a conditional for "inside the package" which covers
> up issues.
>
> There is also the issue of defining conditionals like POSIX level, GNU misc,
> IN_KERNEL, etc.. I try to do that before any includes.
>
> --joel
>
The 'related header' raises for me one question, which is how to treat
*impl.h headers.

In general the style rules I have seen go from "general to specific"
ordering. As mentioned, the Google guide makes one exception to
include "related" header, which appears to be singular "the related
header" implies to me (in agreement with Joel) the header that defines
the functions of this source file.  I suspect there would be no such
"related header" in a header file, except maybe we would consider our
*impl.h header to be a "related header" of a public header file?  That
would be one issue to clarify before moving forward with a proposal on
header file order.

Once we decide whether to use the 'related header' or not, I think we
can define the rules following the FreeBSD/Google style and
Sebastian's suggestion. We have the somewhat odd position of having
both "kernel" (supercore) includes as well as userspace includes
(C/C++ libs), so we can't just point to either of those style guides
and  say "use it". A bit of writing has to be done :)

-Gedare

>>
>>
>> --
>> Sebastian Huber, embedded brains GmbH
>>
>> Address : Dornierstr. 4, D-82178 Puchheim, Germany
>> Phone   : +49 89 189 47 41-16
>> Fax     : +49 89 189 47 41-09
>> E-Mail  : sebastian.huber at embedded-brains.de
>> PGP     : Public key available on request.
>>
>> Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
>> _______________________________________________
>> devel mailing list
>> devel at rtems.org
>> http://lists.rtems.org/mailman/listinfo/devel