Desc: NUT libraries complementary information
File: README
Date: 23 Aug 2003
Auth: Arnaud Quette <arnaud.quette@free.fr>

This file provides some complementary information
about the creation process of NUT libraries, and
the use of it.

1) Introduction
---------------

This represents an evolution toward a fully standard NUT
library usage for external programs, such as clients.

The aim is to provide facilities to incorporate NUT functions
into external programs such as asapm-ups, wmnut, and others.
But it is also used internally (upsc, ...)

NUT (install-lib or legacy install-misc) currently provides:
- a static libraries (if "ar" is available) called
libupsclient.a, or object files (upsclient.o)
- and header files (upsclient.h).
- an helper script called libupsclient-config,
- and a pkgconfig file, called libupsclient.pc, if it is supported

2) pkgconfig support
--------------------

pkgconfig enables a high level of integration with minimal effort.
No more needs to manage hosts of possible NUT installation path in
your configure script !

It is as simple to use as calling:

$> `pkg-config  --exists libupsclient --silence-errors` to see if NUT is usable
$> `pkg-config --cflags libupsclient` to get CFLAGS
$> `pkg-config --libs libupsclient` to get LD_FLAGS

A file called "libupsclient.pc" is provided in the present directory,
and installed in the according directory to enable the above
feature. The default installation directory ("/usr/lib/pkgconfig/")
may be changed with "configure --with-pkgconfig-dir=PATH".


3) libupsclient-config:
-----------------------

Even if pkgconfig is supported/installed, an alternate
helper script will be installed in the same directory
as NUT client programs (BINDIR).

The usage is about the same as pkg-config:

$> `libupsclient-config --cflags` to get CFLAGS
$> `libupsclient-config --libs` to get LD_FLAGS


4) Example of configure.in:
---------------------------

For using libupsclient in your program, simply copy/paste
the below into your configure.in file. It will test for
pkgconfig support for NUT, and fall back to
libupsclient-config if not available. It will issue an
error if none is found!

...
AC_MSG_CHECKING(for NUT client library (libupsclient))
pkg-config --exists libupsclient --silence-errors
if test $? -eq 0
then
	AC_MSG_RESULT(found (using pkg-config))
	LDFLAGS="$LDFLAGS `pkg-config --libs libupsclient`"
	NUT_HEADER="`pkg-config --cflags libupsclient`"
else
	libupsclient-config --version
	if test $? -eq 0
	then
		AC_MSG_RESULT(found (using libupsclient-config))
		LDFLAGS="$LDFLAGS `libupsclient-config --libs`"
		NUT_HEADER="`libupsclient-config --cflags`"
	else
		AC_MSG_ERROR("libupsclient not found")
	fi
fi
...


You can also use this if you are sure that pkg-config
is installed:
...
PKG_CHECK_MODULES(LIBUPSCLI, libupsclient >= 1.5.2)
...

5) Future things:
-----------------

- dyn/shared lib => not possible for the moment (internal problems)
- next libs to come may be libupsconfig, libupscmd, libupsrw, ...
- libtool might be a solution, but unsure for now (see below).


6) Libtool information:
-----------------------

The process would use GNU libtool to assemble the various existing
object files, and output NUT libraries.

As we would simply be linking existing objects, we would need to
define a dummy source file (dummy.c rule in libs/Makefile.am) as
*_SOURCES, otherwise libtool would fail to compile. For more
information, have a look at:
http://mail.gnu.org/archive/html/libtool/2000-11/msg00069.html

An example lib/Makefile.am would be:

+lib_LTLIBRARIES		= libupsclient.la
+libupsclient_la_SOURCES =  dummy.c
+libupsclient_la_LIBADD	= ../clients/upsclient.o @LIBOBJ@ @NETLIBS@
+dummy.c:
+		touch dummy.c

Note that all NUT object files would have to be build using
Libtool. Otherwise, you would get:
*** Warning: Linking the shared library libupsclient.la against the non-libtool
*** objects  ../clients/upsclient.o ../common/common.o is not portable!

Why not using libtool?
======================
we would be forced to either:
- use automake for just 1 Makefile.am file!
- integrated an autogenerated lib/Makefile.in, not quite
easilly maintainable!
- have portability problems!
- ...

7) References:
--------------

- libtool: http://www.gnu.org/software/libtool/
- David MacKenzie's Autobook (RedHat):
http://sources.redhat.com/autobook/autobook/autobook.html
- DebianLinux.Net: The GNU Build System
http://debianlinux.net/~jama/howto/gnu_build_steps.html
