[prog] Publishing an interface to a shared C lib.

[Almut Behrens]

On Fri, Nov 17, 2006 at 04:02:29PM +0000, Conor Daly wrote:
> Hi all,
> 
> So I'm not sure how to go about this.  I'm working on a shared library in
> C for use in qc programming.  I want to publish an interface as one or
> more include files.  My current layout within the sources looks like:
> 
> metdate.c datahandle.c sql.c 
> metdate.h datahandle.h sql.h structs.h
> 
> where datahandle.h #includes"structs.h".  My normal mode for multi-file
> sources for programs is to use a structs.h as a common header and a foo.h
> header for each foo.c .  foo.h typically includes structs.h and all that
> works fine.  However, in publishing a lib, I presumably need to have a
> single libqc.h header file in /usr/local/include/... My main question is:
> 
> Do I keep each of my foo.h header files and repeat them in libqc.h or do I
> have to dispense with the foo.h headers?
> 
> metdate.h publishes date_interval(struct, struct, int)
> datahandle.h publishes qc_timeseries_add_datapoint(struct *, struct, struct)
> qcrun.h will publish qc_check_delta(int[], int[], foo, bar)
> 
> However, I don't want to require users to 
> #include <metdate.h>
> #include <datahandle.h>
> #include <qcrun.h>
> 
> Instead they should 
> 
> #include <libqc.h>
> 
> which will include all the stuff.  However, should users be able to look
> in libqc.h and see the function declarations and associated commentary?
> Or should they see references to metdate.h, datahandle.h and qcrun.h and
> look in there for the details.   Needless to say, there are (already)
> corresponding man pages detailing the functions.
> 
> Know what I mean?

...think so, though there's always room for misinterpretation :)

I wouldn't worry too much about restructuring the header files, as I
don't think there's any commonly accepted good practices for this anyway.
Some like one single huge file, others prefer many smaller files
dedicated to the individual subtasks (the latter is more common, AFAICT).

As long as you document the philosophy (a short note in the lib's
README file should do), either way is fine.

In case the project is larger, I'd just distribute the header files in
some subdirectory (to be put into /usr/local/include/, and named after
the project, typically) and provide a convenience meta header file
(your libqc.h) which just includes everything as required.

You could either specify the includes in libqc.h as

#include <libqc/metdate.h>                                                                                                    
#include <libqc/datahandle.h>
...

(and optionally drop the libqc.h into one of the common include
directories [1]),  or otherwise, the average programmer will know how
to add the required additional -I option to their makefile. And I think
it isn't asking too much of them to look up the declarations in the
respective individual files (grep is their friend anyway, if they can't
find it in the man pages...).

Was that what you meant?

Almut


[1] though I wouldn't - I personally prefer the "have everything in one
place" strategy (i.e. in the same dir), rather than scattering stuff
all over the place. Main point is that when people are doing what you
tell them, the rest should preferably work out of the box...