[Qt5-feedback] The #include directives for Qt Essentials and Qt Add-on modules

[Charley Bay]

>
> > Henry spaketh:
> > I had a brief chat with Lars, and based on that I updated a proposal to
> > the product definition wiki:
> > http://developer.qt.nokia.com/groups/qt_contributors_summit/wiki/Qt5Pro
> ductDefinition
> >
>

Shane respondeth:

> What about #include for a single class, rather than the whole module?
>
> For essentials, I assume that you would still use:
> #include <QString>
>
> For add-ons, the clean looking option:
> #include <QtAddOn/Foo/Bar>
> has the problem that <QtAddOn/Foo>, the file, clashes with the
> subdirectory.
>
> #include <Bar>
> is no good because of potential class name clashes
>
> I don't have a suggestion for avoiding this yet - just wanted to point out
> the problem.
>

Our "#include<>" conventions, and class name clashes (across add-ons)
*are* a problem for trade-offs.  However, I read our "#include<>" plans on
the Qt5ProductDefinition page, and am very concerned:

// ARE YOU SURE YOU WANT TO DO THIS?
#include <some/path/SomeFile.hpp>

...is really pretty dangerous.  It's a general nightmare for build systems
and configuration management, since the "INCLUDE_PATH" is no
longer "in-charge":

(1) Many more directories are considered beyond "INCLUDE_PATH"
(it explodes subdirectories off EVERY directory in your "INCLUDE_PATH")

(2) It slows the build, especially searching every path for subdirs, even
though you may not want those directories in your "INCLUDE_PATH"
to be searched for subdirs.

(3) Your build is no longer documented.  "INCLUDE_PATH" no longer
reflects the directories from which files are included.  Accidental
location of files can violate the build target, and you would NEVER
KNOW (e.g., you can't reproduce it on different machines, or on the
same machine on different days, unless you *always* started
with a "virgin build".)

(4) These "auto-include-subdirs" would be sprinkled in the source,
which means developers must not violate a "virgin build system"
directory structure, but the user will never know if they *did*
violate that structure.  For example, "#include<abc/SomeFile.hpp>"
means the user should be VERY careful about EVER creating
a directory called "abc", especially if it is accidentally in a directory
that may accidentally be placed into an "INCLUDE_PATH".  Thus,
each "some/path" creates global namespace collision problems
that are NOT remedied merely through which version of the module
you placed in your "INCLUDE_PATH".

I recognize that some products do this "#include<some/path/SomeFile.hpp>",
but due to the dangers, we are very careful when we integrate them
into our code base (and builds).  However, we DO NOT allow those
constructs in *our* code base.

So, I'll use whatever Qt5 requires, but I'm not convinced it's a good
idea.

In contrast, I rather like the current Qt distribution model that
"standardizes" includes:

#include <QWidget.hxx> // Did I find it?
#include <QWidget.hpp> // Did I find it?
#include <QWidget.hh> // Did I find it?
#include <QWidget.H> // Did I find it?
...plus the above with different case...

#include <QWidget>  // Found it!  (Good convention!)

For these plugins, I really think there is very low likelihood of
name collisions across packages:

#include <Foo>  // for QtAddOn/Foo

...But, if we wanted explicit namespaces, I'd prefer:

#include <QtAddOn.Foo>

This way, we are looking for an *explicit* file, and the
packaging/distribution
would merely need to standardize the file exports in the distribution
(like we already do with "#include<QWidget>").

Just my vote.

--charley
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.qt.nokia.com/pipermail/qt5-feedback/attachments/20110630/073d0a94/attachment.html