RFC Rules for installation of header files

[Aurélien Gâteau]

On 14.11.2013 18:20, Kevin Ottens wrote:
> On Thursday 14 November 2013 18:04:57 Aurélien Gâteau wrote:
>> On 10.11.2013 18:27, Kevin Ottens wrote:
>> > Hello,
>> >
>> > On Wednesday 06 November 2013 08:52:29 Aurélien Gâteau wrote:
>> >> Yesterday frameworks meeting spawned a discussion regarding 
>> folders
>> >> in header files.
>> >
>> > I think there's an aspect missing in your proposal. There's the
>> > convention we want for #include and where we install. That's in 
>> the
>> > end two different things even though related.
>> >
>> > I think, that for all the frameworks, headers should be installed 
>> in:
>> > $PREFIX/include/KF5/FrameworkName/
>> >
>> > FrameworkName would then contain both the regular .h headers and 
>> the
>> > convenience camel case ones. If we go for that, we get something
>> > consistent install wise and easy to deal with. Then the 
>> distinction
>> > you make below is just about the include path we want when someone
>> > pulls a framework in.
>> >
>> >> I think the consensus is there should be two different 
>> situations:
>> >>
>> >> 1. 'k' prefixed header files
>> >>
>> >> If the header files of a framework are prefixed with a 'k', then
>> >> headers should be installed in include and convenience headers
>> >> should
>> >> be installed in include/KDE.
>> >
>> > I think in a case like that we still want the includes installed 
>> in
>> > $PREFIX/include/KF5/FrameworkName/ (convenience or not). But when
>> > someone pulls the framework as a dependency then both
>> > $PREFIX/include/KF5/ and $PREFIX/include/KF5/FrameworkName/  are
>> > added
>> > in the include path, thus supporting the #include <kfoo.h> and
>> > #include <KFoo> styles.
>>
>> To support #include <kfoo.h> and #include <KFoo> you only need to 
>> have
>> $PREFIX/include/KF5/FrameworkName/ in the include path. Adding
>> $PREFIX/include/KF5/ would add support for
>> #include <FrameworkName/kfoo.h> and #include <FrameworkName/KFoo>.
>
> In fact I initially mentionned $PREFIX/include/KF5/ because of your 
> initial
> proposal of having *_version.h and *_export.h one level up.
>
>> Do we want to support this as well? (I have no strong opinion on 
>> this
>> topic)
>
> Honestly I don't have a strong opinion either. I'd say we probably
> don't want
> it (they have it in Qt and we've seen the kind of issues it can
> create during
> ports when something is splitted for instance). If it turns out to be
> troublesome to not have it, we'll be able to reintroduce it later 
> easily
> anyway.
>
>> >> 2. Non-prefixed header files
>> >>
>> >> If the header files of a framework are not prefixed, then they
>> >> should
>> >> be installed in include/{lowercaseframework} and convenience 
>> headers
>> >> should be installed in include/KDE/{CamelCaseFramework}.
>> >
>> > I think in a case like that we still want the includes installed 
>> in
>> > $PREFIX/include/KF5/FrameworkName/ (convenience or not). But when
>> > someone pulls the framework as a dependency then only
>> > $PREFIX/include/KF5/ is added in the include path, thus supporting
>> > the
>> > #include <FrameworkName/foo.h> and #include <FrameworkName/Foo>
>> > styles.
>> >
>> >> Some special files should still go in include:
>> >>     {lowercaseframework}_export.h {lowercaseframework}_version.h
>> >
>> > Make that $PREFIX/include/KF5/ instead of just include and I 
>> agree.
>>
>> Wouldn't it be more self-contained to have those in
>> $PREFIX/include/KF5/FrameworkName as well?
>>
>> After all, those includes are mostly internal, so they should not be
>> the first files you meet if you wander in $PREFIX/include/KF5 IMO.
>
> Right. Let's put them in the FrameworkName directory as well then.

Looks like we have an agreement then. Let me recap:

# Installation dir

All header files are installed in $PREFIX/include/KF5/$Framework.
This includes 'k' prefixed headers like kfoo and KFoo,
non-prefixed headers such as bar.h and Bar, as well as special headers
such as ${framework}_export.h and ${framework}_version.h.

# Include path

For 'k' prefixed headers, include path is
$PREFIX/include/KF5/$Framework.

For non-prefixed headers, include path is $PREFIX/include/KF5.

Is this correct?

Aurélien