144 lines
4.4 KiB
Text
144 lines
4.4 KiB
Text
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 disapear 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' occurences 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]
|