Directory organization for frameworks with a namespace

[Kevin Ottens]

On Thursday 25 October 2012 00:13:23 David Faure wrote:
> Our standard directory structure for frameworks is like
> staging/kwidgets/src/dialogs/kdialog.h
> where "dialogs" is an arbitrary subdir name,
> which works fine for such easy cases (#include <kdialog.h>)
> 
> But what about frameworks which want to use a namespace for their headers,
> (#include <framework/foo.h>), like kjs and kio?
> 
> I solved the issue for kjs by using "kjs" as the name of the subdirectory:
> tier1/kjs/src/kjs/
> 
> But in KIO, for source compat reasons, we want kio/job.h and
> kio/renamedialog.h although the first one will be in "kiocore" and the
> second in "kiowidgets". So a single subdir doesn't work.
> 
> I started to create a staging/kio/src/core but this will break "kio/job.h"
> from other public headers.
> 
> The only "quick" solution I can think of is
> staging/kio/src/core/kio/ and
> staging/kio/src/widgets/kio/
> with nothing else under core and widgets, which looks a bit ugly.

Agreed.

> The Qt solution would be to generate headers in staging/kio/include/kio
> which forward to src/core and src/widgets ... but we don't have such a
> solution at hand AFAIK. Any volunteer? Should I write this?
> 
> Preferences?

Generated forward headers definitely have my preference as they indeed 
separate the include organization from the "implementation detail" of how the 
sources are organized.

> Any other ideas?

The only alternative I see would be:
staging/kio/src/kio/core with a Kio::Core namespace
staging/kio/src/kio/widgets with a Kio::Widgets namespace

It's not a quick solution in any way though. It will break lots of includes 
(although porting can be automated afaict).

What I like about it is that it pushes us more in the direction of having the 
filesystem layout to follow the namespace layout. That's something which is 
enforced in the Java world and I actually liked it. In C++ it's all decoupled 
and people can create interesting mazes. :-)

> I don't think we want <kiocore/job.h> because this is like
> <QtGui/QLineEdit>, which as we've seen creates stupid source
> incompatibilities in the long term. A conceptual namespace, yes, but not an
> implementation detail shining through.

Not sure I'd consider that an implementation detail, at the end of the day, it 
shows a rather large architectural change in Qt. It's definitely debatable 
depending the point of view you adopt (class level API vs package 
organization).

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

KDAB - proud patron 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/20121029/e6e5d950/attachment.sig>