moving global headers into one top-level location

[Bjoern Michaelsen]

Hi,

ignited by:

 https://bugs.freedesktop.org/show_bug.cgi?id=61627

There was a discussion on moving the global headers to one central location.

I am writing this mail mainly to work out the pros and cons of such a move, so
we can carefully evaluate and prepare for impact should we go for that.

First up, what are we talking about?

This is the first option:

Move the headers from $(SRCDIR)/$(MODULE)/inc/$(MODULE) to
$(SRCDIR)/include/$(MODULE).

What would the impact of that be?

pros:
- less include paths to the compiler (might give a slight speedup e.g. on windows)
- no copying of static files to $(OUTDIR)
  (might give a noticable speedup on non-symlink, slow-forking windows)
- a lot less targets to consider (might be noticable on slow-stating windows)
- no confusion of were a header comes from
- should prevent such bugs as fdo#61627
- reduces the space needed for a build (at least on non-symlink platforms)
- possibly unconfuses ccache for cache misses between the $(OUTDIR) and
  $(SRCDIR) headers
- its what the Linux kernel does
- makes the separation between a 'public' header and a module-private one more explicit
- no change to source files needed
- cherry-picking across the change might need some simple script-foo

cons:
- breaks traditions: old neckbeards might miss their headers in the module itself
  (though that would be easily mitigated with a trivial script creating e.g. symlinks)


This is the second option:

- $(SRCDIR)/$(MODULE)/inc contains the public headers of the module
- $(SRCDIR)/$(MODULE)/source/inc contains internal headers of the module
- put top-level dir in include path

What would be the impact of that be?
pros:
- less include paths to the compiler (might give a slight speedup e.g. on windows)
- no copying of static files to $(OUTDIR)
  (might give a significant speedup on non-symlink, slow-forking windows)
- a lot less targets to consider (might be noticable on slow-stating windows)
- should prevent such bugs as fdo#61627
- reduces the space needed for a build (at least on non-symlink platforms)
- possibly unconfuses ccache for cache misses between the $(OUTDIR) and
  $(SRCDIR) headers
- no change to source files needed
- cherry-picking across the change might need some complex script-foo
  (not only changing locations, but also #include statements)
- doesnt break tradition: headers are still in one module

cons:
- its not what the Linux kernel does
- keeps the separation between a 'public' header and a module-private header
  somewhat non-obvious
- need rewrite of all source files includes from $(MODULE)/foo to $(MODULE)/inc/foo
- having -I$(SRCDIR) might introduce troubles like e.g.:
  - making linking against a 'private' header from another module a bit to easy

As you might guess, if we go for this I would clearly prefer the first option,
but am happy to hear other opinions and input on the issue. We should gather
all areas this might impact and go into it wellprepared.

Comments welcome!

Best,

Bjoern