Re: Coding Convention: Sorting Order of Includes?
On 08/01/2020 20:09, Gedare Bloom wrote: On Wed, Jan 8, 2020 at 9:33 AM Joel Sherrill wrote: On Wed, Jan 8, 2020 at 8:03 AM Sebastian Huber 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. Yes, I would consider XZY.h a related header to XYZimpl.h and include XYZ.h here first. In general the "related header" is only meaningful for includes done in implementation source files (*.c and *.cc). 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 :) The "kernel" includes are "8. Your project's .h files." from my point of view. Yes, some writing is necessary. -- 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.hu...@embedded-brains.de PGP : Public key available on request. Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG. ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
Re: Coding Convention: Sorting Order of Includes?
On Wed, Jan 8, 2020 at 9:33 AM Joel Sherrill wrote: > > > > On Wed, Jan 8, 2020 at 8:03 AM Sebastian Huber > 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.hu...@embedded-brains.de >> PGP : Public key available on request. >> >> Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG. >> ___ >> devel mailing list >> devel@rtems.org >> http://lists.rtems.org/mailman/listinfo/devel ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
Re: Coding Convention: Sorting Order of Includes?
On Wed, Jan 8, 2020 at 8:03 AM Sebastian Huber < sebastian.hu...@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 > > -- > 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.hu...@embedded-brains.de > PGP : Public key available on request. > > Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG. > ___ > devel mailing list > devel@rtems.org > http://lists.rtems.org/mailman/listinfo/devel ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
Re: Coding Convention: Sorting Order of Includes?
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). -- 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.hu...@embedded-brains.de PGP : Public key available on request. Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG. ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
Re: Coding Convention: Sorting Order of Includes?
On Fri, Jan 3, 2020, 10:53 AM 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. > Those look pretty good as rules. I try to alphabetize headers but you are right, sometimes it isn't possible. I'd be ok if this was added to our style. The linked page mentions how they do the beginning of a license block with /*- so a program they have recovnizes it as a license but indent doesn't like that so use /** when you need indent. They don't mention that /** turns it into a Doxygen comment which creates another problem. We may want to discuss doing something on these blocks. Personally I'd like to see licenses start to change and spdx tags added even if the license can't change. > Gedare > ___ > devel mailing list > devel@rtems.org > http://lists.rtems.org/mailman/listinfo/devel > ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
Coding Convention: Sorting Order of Includes?
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. Gedare ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
