incubator-lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marvin Humphrey <>
Subject Re: [lucy-dev] Installing parcel.h and charmony.h
Date Sat, 10 Mar 2012 19:34:05 GMT
On Fri, Mar 9, 2012 at 1:48 PM, Nick Wellnhofer <> 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.


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

View raw message