diff options
author | Bruno Haible <bruno@clisp.org> | 2009-04-26 21:59:27 +0200 |
---|---|---|
committer | Bruno Haible <bruno@clisp.org> | 2009-04-26 22:01:24 +0200 |
commit | 20f6f97f001d35f7c08434b24b5e9a69a5ce6b39 (patch) | |
tree | b4efb20ab741a94916b6791d79a15fc2fd7640a3 /doc/libunistring.texi | |
parent | c93dadda7ce4a5d27a79b97e7de5ddf9e116c64d (diff) | |
download | libunistring-20f6f97f001d35f7c08434b24b5e9a69a5ce6b39.tar.gz |
New doc chapter "Using the library".
Diffstat (limited to 'doc/libunistring.texi')
-rw-r--r-- | doc/libunistring.texi | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/doc/libunistring.texi b/doc/libunistring.texi index e40c70e..b5eb976 100644 --- a/doc/libunistring.texi +++ b/doc/libunistring.texi @@ -5,6 +5,7 @@ @settitle GNU libunistring @finalout @c Indices: +@c am = autoconf macro @amindex @c cp = concept @cindex @c fn = function @findex @c tp = type @tindex @@ -12,6 +13,8 @@ @c ky = keystroke @kindex @c pg = program @pindex @c vr = variable @vindex +@defcodeindex am +@syncodeindex am cp @syncodeindex fn cp @syncodeindex tp cp @ifclear texi2html @@ -142,6 +145,7 @@ A copy of the license is included in @ref{GNU GPL}. * uninorm.h:: Normalization forms * unicase.h:: Case mappings * uniregex.h:: Regular expressions +* Using the library:: How to link with the library and use it? * More functionality:: More advanced functionality * Licenses:: Licenses @@ -213,6 +217,14 @@ unicase,h * Case insensitive comparison:: * Case detection:: +Using the library + +* Installation:: +* Compiler options:: +* Include files:: +* Autoconf macro:: +* Reporting problems:: + Licenses * GNU GPL:: GNU General Public License @@ -728,6 +740,151 @@ NULL is returned and @code{errno} is set. @include unicase.texi @include uniregex.texi +@node Using the library +@chapter Using the library + +This chapter explains some practical considerations, regarding the +installation and compiler options that are needed in order to use this +library. + +@menu +* Installation:: +* Compiler options:: +* Include files:: +* Autoconf macro:: +* Reporting problems:: +@end menu + +@node Installation +@section Installation + +@cindex dependencies +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 +@file{DEPENDENCIES}. + +@cindex installation +Then you can proceed to build and install the library, as described in the +file @file{INSTALL}. For installation on Windows systems, please refer to +the file @file{README.woe32}. + +@node Compiler options +@section Compiler options + +Let's denote as @code{LIBUNISTRING_PREFIX} the value of the @samp{--prefix} +option that you passed to @code{configure} while installing this package. +If you didn't pass any @samp{--prefix} option, then the package is installed +in @file{/usr/local}. + +Let's denote as @code{LIBUNISTRING_INCLUDEDIR} the directory where the +include files were installed. This is usually the same as +@code{$@{LIBUNISTRING_PREFIX@}/include}. Except that if you passed an +@samp{--includedir} option to @code{configure}, it is the value of that +option. + +Let's further denote as @code{LIBUNISTRING_LIBDIR} the directory where +the library itself was installed. This is the value that you passed +with the @samp{--libdir} option to @code{configure}, or otherwise the +same as @code{$@{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 +@code{--libdir=$@{LIBUNISTRING_PREFIX@}/lib64}. + +@cindex compiler options +So that the compiler finds the include files, you have to pass it the +option @code{-I$@{LIBUNISTRING_INCLUDEDIR@}}. + +So that the compiler finds the library during its linking pass, you have +to pass it the options @code{-L$@{LIBUNISTRING_LIBDIR@} -lunistring}. +On some systems, in some configurations, you also have to pass options +needed for linking with @code{libiconv}. The autoconf macro +@code{gl_LIBUNISTRING} (see @ref{Autoconf macro}) deals with this +particularity. + +@node Include files +@section Include files + +Most of the include files have been presented in the introduction, see +@ref{Introduction}, and subsequent detailed chapters. + +Another include file is @code{<unistring/version.h>}. It contains the +version number of the libunistring library. + +@deftypevr 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 @code{(major<<8) + minor}. +@end deftypevr + +@deftypevr 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 @code{(major<<8) + minor}. +@end deftypevr + +It is possible that @code{_libunistring_version} is greater than +@code{_LIBUNISTRING_VERSION}. This can happen when you use +@code{libunistring} as a shared library, and a newer, binary +backward-compatible version has been installed after your program +that uses @code{libunistring} was installed. + +@node Autoconf macro +@section Autoconf macro + +@cindex autoconf macro +GNU Gnulib provides an autoconf macro that test for the availability +of @code{libunistring}. It is contained in the Gnulib module +@url{http://www.gnu.org/software/gnulib/MODULES.html#module=libunistring}. + +@amindex gl_LIBUNISTRING +The macro is called @code{gl_LIBUNISTRING}. It searches for an installed +libunistring. If found, it sets and AC_SUBSTs @code{HAVE_LIBUNISTRING=yes} +and the @code{LIBUNISTRING} and @code{LTLIBUNISTRING} variables and augments +the @code{CPPFLAGS} variable, and defines the C macro +@code{HAVE_LIBUNISTRING} to 1. Otherwise, it sets and AC_SUBSTs +@code{HAVE_LIBUNISTRING=no} and @code{LIBUNISTRING} and @code{LTLIBUNISTRING} +to empty. + +The complexities that @code{AM_ICONV} deals with are the following: + +@itemize @bullet +@item +On some operating systems, in some configurations, libunistring depends +on @code{libiconv}, and the options for linking with libiconv must be +mentioned explicitly on the link command line. + +@item +GNU @code{libunistring}, if installed, is not necessarily already in the +search path (@code{CPPFLAGS} for the include file search path, +@code{LDFLAGS} for the library search path). + +@item +GNU @code{libunistring}, if installed, is not necessarily already in the +run time library search path. To avoid the need for setting an environment +variable like @code{LD_LIBRARY_PATH}, the macro adds the appropriate +run time search path options to the @code{LIBUNISTRING} variable. This works +on most systems. +@end itemize + +@node Reporting problems +@section Reporting problems + +@cindex bug reports +@cindex bug tracker +@cindex mailing list +If you encounter any problem, please don't hesitate to send a detailed +bug report to the @code{bug-libunistring@@gnu.org} mailing list. You can +alternatively also use the bug tracker at the project page +@url{https://savannah.gnu.org/projects/libunistring}. + +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 @code{libunistring}, +for which you don't find the remedy in the @file{INSTALL} file, please include +a description of the options that you passed to the @samp{configure} script. + @node More functionality @chapter More advanced functionality |