RFC Rules for installation of header files

[Kevin Ottens]

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.

Cheers.
-- 
Kévin Ottens, http://ervin.ipsquad.net

KDAB - proud supporter of KDE, http://www.kdab.com

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-frameworks-devel/attachments/20131114/6d194611/attachment-0001.sig>