Directory organization for frameworks with a namespace

[David Faure]

On Monday 29 October 2012 07:40:29 Kevin Ottens wrote:
> 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.

In fact we don't even *have* to generate them. Unlike the CamelCase Qt 
headers, I'm thinking of lowercase forwarding headers here, not installed, so 
no need for them to be ever changed-before-install. This makes it rather 
simple:

src/include/kio/job.h: #include "../../../core/job.h"

Well I can ship a script to create them, but still commit them (not have cmake 
run the script). Better for dependency handling, and simpler overall.

> > 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).

It breaks a lot more than includes -- it breaks all the app code too.

> 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 like the idea of creating so much porting work for so little gain.

> > 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).

If I just want to use a QLineEdit or a KIO::get in my old code, I don't care 
for large architectural changes in Qt or KIO :-)
Sorry for being so pragmatic, but I think we have enough work ahead of us 
without creating even more work for ourselves.
We don't have KConfig::Core::ConfigGroup either, nor KCoreAddons::KJob. Let's go 
easy with the namespacing. Qt doesn't put all of QtCore inside a Core 
namespace either.

-- 
David Faure, faure at kde.org, http://www.davidfaure.fr
Working on KDE, in particular KDE Frameworks 5