Mailing-List: contact lucy-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: lucy-dev@incubator.apache.org
Received-SPF: neutral (athena.apache.org: local policy)
MIME-Version: 1.0
In-Reply-To: 
 <CAAS6=7h=WtoLGozXX3CN4SHra7rc=D2YMXjQUnmV=rf76OZ+JA@mail.gmail.com>
References: <20120224205425.GA16270@rectangular.com>
	<4F5A7AC8.1060806@aevum.de>
	<CAAS6=7h=WtoLGozXX3CN4SHra7rc=D2YMXjQUnmV=rf76OZ+JA@mail.gmail.com>
Date: Sun, 11 Mar 2012 10:01:54 -0700
Message-ID: 
 <CAAS6=7h+jEuY4nRWUJ6ZVmLrKY5=b-i75n+sjH647oP26Rf3tw@mail.gmail.com>
From: Marvin Humphrey <marvin@rectangular.com>
To: lucy-dev@incubator.apache.org
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Subject: Re: [lucy-dev] Installing parcel.h and charmony.h

On Sat, Mar 10, 2012 at 11:34 AM, Marvin Humphrey
<marvin@rectangular.com> wrote:
> 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. =A0If 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):
>
> =A0 =A0#include "Lucy.h" #include "Lucy/Search/ProximityQuery.h"

D'oh!  There were two mistakes in that code sample -- accidental line
rewrap, and putting ProximityQuery under "Lucy" instead of "LucyX".  It
should have read like this:

    #include "Lucy.h"
    #include "LucyX/Search/ProximityQuery.h"

> I'm not exactly sure how to deal with the namespace conflict between
> parcels and classes

OK, I think I've got it.  Here's a variant of the code sample above:

    #include "org/apache/Lucy/0/parcel.h"
    #include "org/apache/LucyX/Search/ProximityQuery/0/parcel.h"

This scheme avoids three kinds of conflicts:

    * Conflicts between Clownfish parcels and classes.
    * Conflicts between similarly named parcels published by different
      organizations.
    * Conflicts between major versions of the same parcel.  (Note that
      there is only a single digit for the version number.)

I see two possible techniques for how we could install the per-class
header files[1].

We can install into a per-version directory...

    $CLOWNFISH_INC/org/apache/Lucy/0.4.0/Lucy/Analysis/Analyzer.h
    $CLOWNFISH_INC/org/apache/Lucy/0.4.0/Lucy/Analysis/Normalizer.h
    [...]

... and then symlink the version dir to the single-digit major API dir:

    $CLOWNFISH_INC/org/apache/Lucy/0  <-- points at e.g. ../0.4.0

The other possibility is to clobber the contents of the major version
dir when installing minor/bugfix/etc releases:

    $CLOWNFISH_INC/org/apache/Lucy/0/Lucy/Analysis/Analyzer.h
    $CLOWNFISH_INC/org/apache/Lucy/0/Lucy/Analysis/Normalizer.h
    [...]

This has the advantage of compatibility with file systems that do not
support directory symlinks.

Regardless of which installation mechanism we choose...

  * The extension author only needs to know about major versions.
  * There is still only one include dir for all Clownfish-powered
    distros.

Marvin Humphrey

[1] Our "per-class" header files are not technically per-class right now,
    though we could choose to start enforcing that.