[asterisk-dev] install path of asterisk.h

[Luigi Rizzo]

On Tue, Nov 20, 2007 at 07:39:04PM +0200, Tzafrir Cohen wrote:
> Hi
> 
> With all of Luigi's work on reducing the number of include files, we're
> still left with the need to include several files.
> 
> Currently there are two include files directly under include/ -
> asterisk.h and jitterbuffer.h . jitterbuffer.h is not installed on 'make
> install' (should it be available to external channels, such as 
> chan_ooh323c? ). asterisk.h is explicitly copied to
> /usr/include/ [*] and the files under include/asterisk - to under 
> /usr/include/asterisk/ .
> 
> Is there a real point in keeping asterisk.h outside of the asterisk
> include directory? It is not a header that saves you the need to include
> the rest. So there's really no point in just "exposing" it. 
> 
> Also, looking at the way the Makefile handles asterisk.h, I noticed that
> in the case of SunOS it seems to install asterisk.h to $includedir but
> the rest of the include files go to /opt/asterisk/include . Does
> includedir indeed default to /opt/include in that case? If so: why set
> ASTHEADERDIR in a separate case?
> 

Don't take the status quo as an example, i am under the impression
that the handling of installations is mostly random on !linux
platforms (including FreeBSD), because nobody is taking care of it.

With this in mind, i think we have three type of headers in asterisk
(i use the current name/location only as a reference, but they might
well deserve a renaming or relocation):

 1. those of general use that should be included by a large set of files;
    these include "asterisk.h", "asterisk/module.h", "asterisk/lock.h"
    and another small set of files;

 2. those exporting a very specific API, that a smaller set of files could
    be interested in. E.g. i think the various speech.h, say.h, rtp.h
    and so on fall in this second category;

 3. those for internal use only, whose role is to export prototypes for
    functions defined in one file and used in another one. Such functions
    are the various foo_init() etc. (at the moment they are in the same
    foo.h that exports the API for module foo, but this is a mistake because
    clients are normally not interested in them).
    I think these "internal" interfaces should be listed in a small set
    of header files for system use.

Clearly the boundary between #1 and #2 is a bit fuzzy but the extremes
should be relatively clear.

Accordingly, we could think of putting these files in 3 different
directories, e.g. #1 in include/asterisk/*h, #2 in include/asterisk/modules/*.h,
and #3 in include/asterisk/private/*h to make it clear to the developer
what they are for.

We could then (probably) spare the installation of #3 files,
but not of the others. Given the number, we should probably
install the entire include/asterisk/ and be done with it.

	cheers
	luigi