Imported Upstream version 2.6.3
This commit is contained in:
Arnaud Quette
parent
45043b58d0
commit
fad6ced6f6
255 changed files with 11081 additions and 4629 deletions
211
lib/README
211
lib/README
|
|
@ -1,116 +1,143 @@
|
|||
Desc: NUT libraries complementary information
|
||||
File: README
|
||||
Date: 23 Aug 2003
|
||||
Auth: Arnaud Quette <arnaud.quette@free.fr>
|
||||
ifndef::external_title[]
|
||||
NUT libraries complementary information
|
||||
=======================================
|
||||
endif::external_title[]
|
||||
|
||||
This file provides some complementary information
|
||||
about the creation process of NUT libraries, and
|
||||
the use of it.
|
||||
This chapter provides some complementary information about the creation process
|
||||
of NUT libraries, and using these in your program.
|
||||
|
||||
1) Introduction
|
||||
---------------
|
||||
Introduction
|
||||
------------
|
||||
|
||||
This represents an evolution toward a fully standard NUT
|
||||
library usage for external programs, such as clients.
|
||||
NUT provides several libraries, to ease interfacing with 3rd party programs:
|
||||
|
||||
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, ...)
|
||||
- *libupsclient*, to interact with NUT server (upsd),
|
||||
- *libnutscan*, to discover NUT supported devices.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
2) pkgconfig support
|
||||
--------------------
|
||||
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.
|
||||
|
||||
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 !
|
||||
libupsclient-config
|
||||
-------------------
|
||||
|
||||
It is as simple to use as calling:
|
||||
In case pkgconfig is not available on the system, an alternate helper script is
|
||||
provided: 'libupsclient-config'.
|
||||
|
||||
$> `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
|
||||
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.
|
||||
|
||||
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".
|
||||
The usage is about the same as pkg-config and similar tools.
|
||||
|
||||
To get CFLAGS, use:
|
||||
|
||||
3) libupsclient-config:
|
||||
-----------------------
|
||||
$ libupsclient-config --cflags
|
||||
|
||||
Even if pkgconfig is supported/installed, an alternate
|
||||
helper script will be installed in the same directory
|
||||
as NUT client programs (BINDIR).
|
||||
To get LD_FLAGS, use:
|
||||
|
||||
The usage is about the same as pkg-config:
|
||||
$ libupsclient-config --libs
|
||||
|
||||
$> `libupsclient-config --cflags` to get CFLAGS
|
||||
$> `libupsclient-config --libs` to get LD_FLAGS
|
||||
References: linkman:libupsclient-config[1] manual page,
|
||||
|
||||
NOTE: this feature may evolve (name change), or even disapear in the future.
|
||||
|
||||
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:
|
||||
pkgconfig support
|
||||
-----------------
|
||||
|
||||
- next libs to come may be libupsconfig, libupscmd, libupsrw, ...
|
||||
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
|
||||
|
||||
|
||||
6) Libtool information:
|
||||
-----------------------
|
||||
You can also use this if you are sure that pkg-config is installed:
|
||||
|
||||
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.
|
||||
PKG_CHECK_MODULES(LIBUPSCLI, libupsclient >= 2.4.0)
|
||||
PKG_CHECK_MODULES(LIBNUTSCAN, libnutscan >= 2.6.2)
|
||||
|
||||
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
|
||||
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
|
||||
prefered.
|
||||
|
||||
|
||||
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]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue