[asterisk-dev] Headers: Incomplete and Cyclic Referenced

[Matt Fredrickson]

On Sun, Jun 3, 2018 at 9:47 AM, Alexander Traud
<pabstraud at compuserve.com> wrote:
> The Google tool include-what-you-use (iwyu) works in Asterisk (for more
> details see ASTERISK-25591). You can pick one single file, it goes
> through the code and checks that all #include <my_required_header> are
> there. I love iwyu, because it helps me to complete the inclusion
> headers, especially when I submit a new module or have to update/add
> stuff to existing modules. Works great.
>
> iwyu detects a lot of issues in existing source modules:
> - missing header files, previously included indirectly via other files
> - orphan inclusions from removed code
> - too broad inclusions, instead use a more dedicated header file
> Normal stuff one would expect in a 20-year-old open-source project which
> is as big as Asterisk is.
>
> However, iwyu detects issues not only in source files (.c) but also in
> public header files (include/asterisk/*.h). Those face the very same
> issues above. Surprisingly many headers files in Asterisk are incomplete
> themselves. Plus, with iwyu you find cyclic references, because you can
> test each header file individually. These are nasty because you have to
> include other headers in a specific order in your source file to build
> Asterisk at all.
>
> However however, as an external contributor, although many of those
> issues are small and fast to fix, I cannot do much about those issues in
> headers because decisions must be made. Sometimes, even about the
> architecture.
>
> Could someone at Digium go through at least the public header files in
> include/asterisk and complete those? That would help module maintainers
> to keep their inclusions correct. By this, you are going to find cyclic
> references, some easy to fix via forward declarations. However, some are
> not that easy to fix because structures do not use pointers as they
> should.

Hey Alex,

Thanks *so* much for taking the time to write up your findings.

To be honest, I think in some form or fashion the project goes through
a header inclusion audit every few years due to someone showing innate
interest in it.  I'm leaning more towards this being a janitor type
project, since it has a relatively low barrier to entry and might be a
good project for someone getting started in Asterisk development.

If there are challenging ones that affect header file architecture,
those are appropriate topics to discuss on this mailing list and they
don't necessarily have to be determined by the author of the patch, as
long as the patch expresses the architectural intent of the decision
on this list.

-- 
Matthew Fredrickson
Digium, Inc. | Engineering Manager
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA