lib/README

   1 ifndef::external_title[]
   2 NUT libraries complementary information
   3 =======================================
   4 endif::external_title[]
   5
   6 This chapter provides some complementary information about the creation process
   7 of NUT libraries, and using these in your program.
   8
   9 Introduction
  10 ------------
  11
  12 NUT provides several libraries, to ease interfacing with 3rd party programs:
  13
  14 - *libupsclient*, to interact with NUT server (upsd),
  15 - *libnutclient*, to interact with NUT server at high level,
  16 - *libnutscan*, to discover NUT supported devices.
  17
  18 External applications, such as asapm-ups, wmnut, and others, currently use it.
  19 But it is also used internally (by upsc, upsrw, upscmd, upsmon and dummy-ups)
  20 to reduce storage footprint and memory consumption.
  21
  22 The runtime libraries are installed by default. However, to install other
  23 development files (header, additional static and shared libraries, and
  24 compilation helpers below), you will have to provide the '--with-dev' flag to
  25 the 'configure' script.
  26
  27 libupsclient-config
  28 -------------------
  29
  30 In case pkgconfig is not available on the system, an alternate helper script is
  31 provided: 'libupsclient-config'.
  32
  33 It will be installed in the same directory as NUT client programs (BINDIR),
  34 providing that you have enabled the '--with-dev' flag to the 'configure' script.
  35
  36 The usage is about the same as pkg-config and similar tools.
  37
  38 To get CFLAGS, use:
  39
  40         $ libupsclient-config --cflags
  41
  42 To get LD_FLAGS, use:
  43
  44         $ libupsclient-config --libs
  45
  46 References: linkman:libupsclient-config[1] manual page,
  47
  48 NOTE: this feature may evolve (name change), or even disapear in the future.
  49
  50 pkgconfig support
  51 -----------------
  52
  53 pkgconfig enables a high level of integration with minimal effort. There is no
  54 more needs to handle hosts of possible NUT installation path in your configure
  55 script !
  56
  57 To check if NUT is available, use:
  58
  59         $ pkg-config --exists libupsclient --silence-errors
  60
  61 To get CFLAGS, use:
  62
  63         $ pkg-config --cflags libupsclient
  64
  65 To get LD_FLAGS, use:
  66
  67         $ pkg-config --libs libupsclient
  68
  69 pkgconfig support ('.pc') files are provided in the present directory of the
  70 source distribution ('nut-X.Y.Z/lib/'), and installed in the suitable system
  71 directory if you have enabled '--with-dev'.
  72
  73 The default installation directory ("/usr/lib/pkgconfig/") can be changed with
  74 the following command:
  75
  76         ./configure --with-pkgconfig-dir=PATH
  77
  78
  79 You can also use this if you are sure that pkg-config is installed:
  80
  81         PKG_CHECK_MODULES(LIBUPSCLI, libupsclient >= 2.4.0)
  82         PKG_CHECK_MODULES(LIBNUTSCAN, libnutscan >= 2.6.2)
  83
  84
  85 Example configure script
  86 ------------------------
  87
  88 To use NUT libraries in your program, use the following code in your
  89 configure (.in or .ac) script:
  90
  91         AC_MSG_CHECKING(for NUT client library (libupsclient))
  92         pkg-config --exists libupsclient --silence-errors
  93         if test $? -eq 0
  94         then
  95                 AC_MSG_RESULT(found (using pkg-config))
  96                 LDFLAGS="$LDFLAGS `pkg-config --libs libupsclient`"
  97                 NUT_HEADER="`pkg-config --cflags libupsclient`"
  98         else
  99                 libupsclient-config --version
 100                 if test $? -eq 0
 101                 then
 102                         AC_MSG_RESULT(found (using libupsclient-config))
 103                         LDFLAGS="$LDFLAGS `libupsclient-config --libs`"
 104                         NUT_HEADER="`libupsclient-config --cflags`"
 105                 else
 106                         AC_MSG_ERROR("libupsclient not found")
 107                 fi
 108         fi
 109
 110 This code will test for pkgconfig support for NUT client library, and fall back
 111 to libupsclient-config if not available. It will issue an error if none is
 112 found!
 113
 114 The same is also valid for other NUT libraries, such as libnutscan.
 115 Simply replace 'libupsclient' occurences in the above example, by the name
 116 of the desired library (for example, 'libnutscan').
 117
 118 NOTE: this is an alternate method. Use of PKG_CHECK_MODULES macro should be
 119 prefered.
 120
 121
 122 Future consideration
 123 --------------------
 124
 125 We are considering the following items:
 126
 127 - provide libupsclient-config support for libnutscan, and libnutconfig when
 128 available. This requires to rename and rewrite the script in a more generic way
 129 (libnut-config), with options to address specific libraries.
 130 - provide pkgconfig support for libnutconfig, when available.
 131
 132
 133 Libtool information
 134 -------------------
 135
 136 NUT libraries are built using Libtool. This tool is integrated with automake,
 137 and can create static and dynamic libraries for a variety of platforms in a
 138 transparent way.
 139
 140 References:
 141
 142 - link:http://www.gnu.org/software/libtool/[libtool]
 143 - link:http://sources.redhat.com/autobook/autobook/autobook.html[David MacKenzie's Autobook (RedHat)]
 144 - link:http://debianlinux.net/~jama/howto/gnu_build_steps.html[DebianLinux.Net, The GNU Build System]