Re: C library package design

[Ralf Wildenhues]

Hello Ivan,

* Ivan Leben wrote on Wed, May 16, 2007 at 04:05:23AM CEST:
>
> First thing that troubles me is, whether I should build the examples
> in the same run as the library itself,

Yes, for simplicity I would do that.

> using a single configure script

Yes.

> with an additional --with-examples argument added to conditionally run
> the makefile in the examples directory?

I would make things even simpler than that.  If you want to build them
unconditionally, use noinst_PROGRAMS.  If you don't want them built by
default, you can for example use check_PROGRAMS, and advise your users
to run `make check' to build and run the examples (use TESTS to run
them; see the manual for more information).

> 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?

If you decide to go that way, then yes, they need to be run separately
there.  Running autoreconf from the toplevel package will cause the
recursion to happen by default though.

> 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...)?

Not separate, but complete.  You can use the `foreign' option to relax
package requirements (see manual for more information).

> 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.

No.  Assuming you use Libtool to build the library, and assuming for the
moment that you build all in one package, then you pass the library
dependency like this:
  check_PROGRAMS = example1
  example1_LDADD = ../lib/libfoo.la

The directory ordering induced by the SUBDIRS variables should ensure
that libfoo.la is built before example1.

> 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?

Libtool will take care of this detail: uninstalled programs will use
uninstalled libraries, installed programs (given that you use
bin_PROGRAMS or a similar directory prefix that causes installation)
will use installed libraries; it may happen that libraries and programs
are relinked upon `make install' so as to use the correct dependent
libraries.

> 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.

Yes.

> 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?

No.  It means that if you want more fine-grained dependencies, you
should save and restore $LIBS before and after the test, and save the
test result in another variable, say, $LIBS_FOR_EXAMPLE2 (pick a better
name, please ;-).

> 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.

The --enable-examples is certainly a possibility (prefer --enable over
--with, because the latter is supposed to deal with package-external
additions, as per GNU Coding Standards).

Hope that helps.

Cheers,
Ralf