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 library (static and/or dynamic, depending on what your platform supports), 
  called libupsclient.a, libupsclient.so, etc. 
- 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:
-----------------

- next libs to come may be libupsconfig, libupscmd, libupsrw, ...


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

NUT libraries are currently built using Libtool. This tool is
integrated with automake, and can create static and dynamic libraries
for a variety of platforms in a transparent way.

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