C library package design

[Ivan Leben]

Hi!

I am going to release an ANSI C library soon but I am still confused
about the automake package design I should use. The main trouble is
that I am also distributing some example programs to show the use of
library but don't really know how / where the compilation of those
should take place.

First thing that troubles me is, whether I should build the examples
in the same run as the library itself, using a single configure script
with an additional --with-examples argument added to conditionally run
the makefile in the examples directory?

Or should I rather use another configure script inside the examples
directory and invoke it from the main script via AC_CONFIGURE_SUBDIRS?
Would this mean I would need to run automake, autoheader, autoconf in
the examples folder separately? Would I also need then to maintain the
examples subfolder as a complete separate package and add standard
files for an automake package there as well (COPYING, AUTHORS,
NEWS...)?

The design of the package is quite important because the examples
depend on the library being built so the library must be built first
and maybe there should be another check in the configuration of
example to see if the library was really built. Furthermore, should
the examples link to the uninstalled library file and include the
uninstalled headers directly from the source or should they use the
installed files?

Moreover, one of the examples requires some additional libraries to
link to. This means that the configuration should also check whether
that one is installed in the system. And now I'm puzzled because it
seems like the AC_CHECK_LIB always adds the library it found to the
LIBS string automatically and thus the library only required by one
example would be used when linking the library itself as well. Does
this mean I should definitely use another configure script for
examples?

Basically, I am just asking which of these ways is the usual one, the
one that a user would expect from a library package and is common
among existing libraries.  What I want is to give the user of the
library a choice whether to build the examples or not and there should
be additional configuration checks in case the examples are going to
be built. I am just asking about the most common way to achieve this.

thanks,
Ivan Leben