nut-debian/lib/README

145 lines
4.4 KiB
Plaintext
Raw Normal View History

2012-01-24 12:22:33 +02:00
ifndef::external_title[]
NUT libraries complementary information
=======================================
endif::external_title[]
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
This chapter provides some complementary information about the creation process
of NUT libraries, and using these in your program.
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
Introduction
------------
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
NUT provides several libraries, to ease interfacing with 3rd party programs:
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
- *libupsclient*, to interact with NUT server (upsd),
2013-11-24 17:00:12 +02:00
- *libnutclient*, to interact with NUT server at high level,
2012-01-24 12:22:33 +02:00
- *libnutscan*, to discover NUT supported devices.
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
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.
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
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,
2022-07-10 10:23:45 +03:00
NOTE: this feature may evolve (name change), or even disappear in the future.
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
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
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
To get LD_FLAGS, use:
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
$ pkg-config --libs libupsclient
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
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'.
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
The default installation directory ("/usr/lib/pkgconfig/") can be changed with
the following command:
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
./configure --with-pkgconfig-dir=PATH
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
You can also use this if you are sure that pkg-config is installed:
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
PKG_CHECK_MODULES(LIBUPSCLI, libupsclient >= 2.4.0)
PKG_CHECK_MODULES(LIBNUTSCAN, libnutscan >= 2.6.2)
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
Example configure script
------------------------
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
To use NUT libraries in your program, use the following code in your
configure (.in or .ac) script:
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
AC_MSG_CHECKING(for NUT client library (libupsclient))
pkg-config --exists libupsclient --silence-errors
2010-03-26 01:20:59 +02:00
if test $? -eq 0
then
2012-01-24 12:22:33 +02:00
AC_MSG_RESULT(found (using pkg-config))
LDFLAGS="$LDFLAGS `pkg-config --libs libupsclient`"
NUT_HEADER="`pkg-config --cflags libupsclient`"
2010-03-26 01:20:59 +02:00
else
2012-01-24 12:22:33 +02:00
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
2010-03-26 01:20:59 +02:00
fi
2012-01-24 12:22:33 +02:00
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!
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
The same is also valid for other NUT libraries, such as libnutscan.
2022-07-10 10:23:45 +03:00
Simply replace 'libupsclient' occurrences in the above example, by the name
2012-01-24 12:22:33 +02:00
of the desired library (for example, 'libnutscan').
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
NOTE: this is an alternate method. Use of PKG_CHECK_MODULES macro should be
2016-07-18 03:11:41 +03:00
preferred.
2012-01-24 12:22:33 +02:00
Future consideration
--------------------
We are considering the following items:
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
- 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.
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
Libtool information
-------------------
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
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.
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
References:
2010-03-26 01:20:59 +02:00
2012-01-24 12:22:33 +02:00
- 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]