nut/lib/README

ifndef::external_title[]
NUT libraries complementary information
=======================================
endif::external_title[]

This chapter provides some complementary information about the creation process
of NUT libraries, and using these in your program.

Introduction
------------

NUT provides several libraries, to ease interfacing with 3rd party programs:

- *libupsclient*, to interact with NUT server (upsd),
- *libnutclient*, to interact with NUT server at high level,
- *libnutscan*, to discover NUT supported devices.

External applications, such as asapm-ups, wmnut, and others, currently use it.
But it is also used internally (by upsc, upsrw, upscmd, upsmon and dummy-ups)
to reduce storage footprint and memory consumption.

The runtime libraries are installed by default. However, to install other
development files (header, additional static and shared libraries, and
compilation helpers below), you will have to provide the '--with-dev' flag to
the 'configure' script.

libupsclient-config
-------------------

In case pkgconfig is not available on the system, an alternate helper script is
provided: 'libupsclient-config'.

It will be installed in the same directory as NUT client programs (BINDIR),
providing that you have enabled the '--with-dev' flag to the 'configure' script.

The usage is about the same as pkg-config and similar tools.

To get CFLAGS, use:

	$ libupsclient-config --cflags

To get LD_FLAGS, use:

	$ libupsclient-config --libs

References: linkman:libupsclient-config[1] manual page,

NOTE: this feature may evolve (name change), or even disappear in the future.

pkgconfig support
-----------------

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

To check if NUT is available, use:

	$ pkg-config --exists libupsclient --silence-errors

To get CFLAGS, use:

	$ pkg-config --cflags libupsclient

To get LD_FLAGS, use:

	$ pkg-config --libs libupsclient

pkgconfig support ('.pc') files are provided in the present directory of the
source distribution ('nut-X.Y.Z/lib/'), and installed in the suitable system
directory if you have enabled '--with-dev'.

The default installation directory ("/usr/lib/pkgconfig/") can be changed with
the following command:

	./configure --with-pkgconfig-dir=PATH


You can also use this if you are sure that pkg-config is installed:

	PKG_CHECK_MODULES(LIBUPSCLI, libupsclient >= 2.4.0)
	PKG_CHECK_MODULES(LIBNUTSCAN, libnutscan >= 2.6.2)


Example configure script
------------------------

To use NUT libraries in your program, use the following code in your
configure (.in or .ac) script:

	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

This code will test for pkgconfig support for NUT client library, and fall back
to libupsclient-config if not available. It will issue an error if none is
found!

The same is also valid for other NUT libraries, such as libnutscan.
Simply replace 'libupsclient' occurrences in the above example, by the name
of the desired library (for example, 'libnutscan').

NOTE: this is an alternate method. Use of PKG_CHECK_MODULES macro should be
preferred.


Future consideration
--------------------

We are considering the following items:

- provide libupsclient-config support for libnutscan, and libnutconfig when
available. This requires to rename and rewrite the script in a more generic way
(libnut-config), with options to address specific libraries.
- provide pkgconfig support for libnutconfig, when available.


Libtool information
-------------------

NUT libraries are 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.

References:

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