On Fri, Mar 9, 2012 at 1:48 PM, Nick Wellnhofer <[email protected]> wrote:
> I just had a look at the required .h files and from my limited
> understanding we have to install parcel.h, charmony.h and the
> per-class headers.
Correct.
We may also want to consider exposing some of the Perl <-> Clownfish
conversion routines which live in perl/xs/XSBind.h -- but that's not
mandatory just yet.
> I wonder if this would work when installing more than one parcel. It
> seems to me that every parcel would need a separate header file with a
> unique filename, and that some common definitions of parcel.h should
> be factored out to separate header file. The latter could be installed
> together with Clownfish.
You're right, there would be a filename collision there. This stuff is
a bit messy at the moment because the implementation has only needed
to be "good enough". :)
That file is currently named "parcel.h" rather than "Lucy.h" so that CFC
can avoid a collision between the autogenerated header file for a class
named "Lucy" and the autogenerated header file for the Lucy "parcel".
(In Clownfish, a "parcel" is unit of distribution roughly akin to to a
Java package, Python module, Ruby module, etc. -- as opposed to a class
in any of those languages or a Perl package/class/module/namespace).
After mulling this over, here's what I've come to believe:
* "parcel.h" should be renamed to take the name of the parcel. In
Lucy's case, that means it will become "Lucy.h".
* The parcel header file (e.g. "Lucy.h") should expose the entire
public API for the parcel's contents. It will thus be the *only*
header file that an extension author needs to know about with
regards to a given parcel.
To elaborate, the source code for a compiled Lucy extension will only
need this line...
#include "Lucy.h"
... and not a stack of pound-includes, e.g.:
#include "Lucy/Search/IndexSearcher.h"
#include "Lucy/Search/TermQuery.h"
#include "Lucy/Search/ORQuery.h"
Compilation resource consumption will be greater because we're lumping
everything together, but I think that's OK.
At some point in the future, we will probably break a bunch of stuff out
of the Lucy parcel, creating Lucy::Test, individual LucyX parcels and so
on. If you had an extension that needed both Lucy and e.g.
Lucy::Search::ProximityQuery, you would need one pound-include per
parcel (*not* per class):
#include "Lucy.h" #include "Lucy/Search/ProximityQuery.h"
I'm not exactly sure how to deal with the namespace conflict between
parcels and classes, but that's a detail we can work out later -- the
important thing right this moment is to establish a sane public API for
extension authors.
> charmony.h maybe should be installed in a system include directory,
> not in a location depending on the host language.
For the record, out of all our header files, charmony.h is the *only*
one which contains system-specific configuration information. (All C
code output by the CFC transpiler is OS-neutral and compiler-neutral.)
I think we should move charmony.h to "Lucy/_charmony.h". That will get
it out of the way for now.
The reason "charmony.h" doesn't belong in a system include dir is that
Charmonizer is designed to be a modular library, and so at some point
there may be different "charmony.h" configuration files floating around
which were generated by different Charmonizer-powered applications.
Marvin Humphrey
