GNU libunistring: 16. Using the library

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 16. Using the library

This chapter explains some practical considerations, regarding the installation and compiler options that are needed in order to use this library.

## 16.1 Installation

Before you can use the library, it must be installed. First, you have to make sure all dependencies are installed. They are listed in the file ‘`DEPENDENCIES`’.

Then you can proceed to build and install the library, as described in the file ‘`INSTALL`’. For installation on Windows systems, please refer to the file ‘`INSTALL.windows`’.

## 16.2 Compiler options

Let's denote as `LIBUNISTRING_PREFIX` the value of the ‘`--prefix`’ option that you passed to `configure` while installing this package. If you didn't pass any ‘`--prefix`’ option, then the package is installed in ‘`/usr/local`’.

Let's denote as `LIBUNISTRING_INCLUDEDIR` the directory where the include files were installed. This is usually the same as `${LIBUNISTRING_PREFIX}/include`. Except that if you passed an ‘`--includedir`’ option to `configure`, it is the value of that option.

Let's further denote as `LIBUNISTRING_LIBDIR` the directory where the library itself was installed. This is the value that you passed with the ‘`--libdir`’ option to `configure`, or otherwise the same as `${LIBUNISTRING_PREFIX}/lib`. Recall that when building in 64-bit mode on a 64-bit GNU/Linux system that supports executables in either 64-bit mode or 32-bit mode, you should have used the option `--libdir=${LIBUNISTRING_PREFIX}/lib64`.

So that the compiler finds the include files, you have to pass it the option `-I${LIBUNISTRING_INCLUDEDIR}`.

So that the compiler finds the library during its linking pass, you have to pass it the options `-L${LIBUNISTRING_LIBDIR} -lunistring`. On some systems, in some configurations, you also have to pass options needed for linking with `libiconv`. The autoconf macro `gl_LIBUNISTRING` (see Autoconf macro) deals with this particularity.

## 16.3 Include files

Most of the include files have been presented in the introduction, see Introduction, and subsequent detailed chapters.

Another include file is `<unistring/version.h>`. It contains the version number of the libunistring library.

Macro: int _LIBUNISTRING_VERSION

  This constant contains the version of libunistring that is being used at compile time. It encodes the major and minor parts of the version number only. These parts are encoded in the form `(major<<8) + minor`.

Constant: int _libunistring_version

  This constant contains the version of libunistring that is being used at run time. It encodes the major and minor parts of the version number only. These parts are encoded in the form `(major<<8) + minor`.

It is possible that `_libunistring_version` is greater than `_LIBUNISTRING_VERSION`. This can happen when you use `libunistring` as a shared library, and a newer, binary backward-compatible version has been installed after your program that uses `libunistring` was installed.

## 16.4 Autoconf macro

GNU Gnulib provides an autoconf macro that tests for the availability of `libunistring`. It is contained in the Gnulib module ‘`libunistring`’, see https://www.gnu.org/software/gnulib/MODULES.html#module=libunistring.

The macro is called `gl_LIBUNISTRING`. It searches for an installed libunistring. If found, it sets and AC_SUBSTs `HAVE_LIBUNISTRING=yes` and the `LIBUNISTRING` and `LTLIBUNISTRING` variables and augments the `CPPFLAGS` variable, and defines the C macro `HAVE_LIBUNISTRING` to 1. Otherwise, it sets and AC_SUBSTs `HAVE_LIBUNISTRING=no` and `LIBUNISTRING` and `LTLIBUNISTRING` to empty.

The complexities that `gl_LIBUNISTRING` deals with are the following:

- On some operating systems, in some configurations, libunistring depends on `libiconv`, and the options for linking with libiconv must be mentioned explicitly on the link command line.
- GNU `libunistring`, if installed, is not necessarily already in the search path (`CPPFLAGS` for the include file search path, `LDFLAGS` for the library search path).
- GNU `libunistring`, if installed, is not necessarily already in the run time library search path. To avoid the need for setting an environment variable like `LD_LIBRARY_PATH`, the macro adds the appropriate run time search path options to the `LIBUNISTRING` variable. This works on most systems.

## 16.5 Reporting problems

If you encounter any problem, please don't hesitate to submit a detailed bug report either in the bug tracker at the project page https://savannah.gnu.org/projects/libunistring, or by email to the `bug-libunistring@gnu.org` mailing list.

Please always include the version number of this library, and a short description of your operating system and compilation environment with corresponding version numbers.

For problems that appear while building and installing `libunistring`, for which you don't find the remedy in the ‘`INSTALL`’ file, please include a description of the options that you passed to the ‘`configure`’ script.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Bruno Haible on October, 16 2022 using texi2html 1.78a.