doc/libunistring_15.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
   2 <html>
   3 <!-- Created on March, 30 2010 by texi2html 1.78a -->
   4 <!--
   5 Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
   6             Karl Berry  <karl@freefriends.org>
   7             Olaf Bachmann <obachman@mathematik.uni-kl.de>
   8             and many others.
   9 Maintained by: Many creative people.
  10 Send bugs and suggestions to <texi2html-bug@nongnu.org>
  11
  12 -->
  13 <head>
  14 <title>GNU libunistring: 15. Using the library</title>
  15
  16 <meta name="description" content="GNU libunistring: 15. Using the library">
  17 <meta name="keywords" content="GNU libunistring: 15. Using the library">
  18 <meta name="resource-type" content="document">
  19 <meta name="distribution" content="global">
  20 <meta name="Generator" content="texi2html 1.78a">
  21 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  22 <style type="text/css">
  23 <!--
  24 a.summary-letter {text-decoration: none}
  25 pre.display {font-family: serif}
  26 pre.format {font-family: serif}
  27 pre.menu-comment {font-family: serif}
  28 pre.menu-preformatted {font-family: serif}
  29 pre.smalldisplay {font-family: serif; font-size: smaller}
  30 pre.smallexample {font-size: smaller}
  31 pre.smallformat {font-family: serif; font-size: smaller}
  32 pre.smalllisp {font-size: smaller}
  33 span.roman {font-family:serif; font-weight:normal;}
  34 span.sansserif {font-family:sans-serif; font-weight:normal;}
  35 ul.toc {list-style: none}
  36 -->
  37 </style>
  38
  39
  40 </head>
  41
  42 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  43
  44 <table cellpadding="1" cellspacing="1" border="0">
  45 <tr><td valign="middle" align="left">[<a href="libunistring_14.html#SEC54" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  46 <td valign="middle" align="left">[<a href="libunistring_16.html#SEC61" title="Next chapter"> &gt;&gt; </a>]</td>
  47 <td valign="middle" align="left"> &nbsp; </td>
  48 <td valign="middle" align="left"> &nbsp; </td>
  49 <td valign="middle" align="left"> &nbsp; </td>
  50 <td valign="middle" align="left"> &nbsp; </td>
  51 <td valign="middle" align="left"> &nbsp; </td>
  52 <td valign="middle" align="left">[<a href="libunistring.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
  53 <td valign="middle" align="left">[<a href="libunistring.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  54 <td valign="middle" align="left">[<a href="libunistring_18.html#SEC71" title="Index">Index</a>]</td>
  55 <td valign="middle" align="left">[<a href="libunistring_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  56 </tr></table>
  57
  58 <hr size="2">
  59 <a name="Using-the-library"></a>
  60 <a name="SEC55"></a>
  61 <h1 class="chapter"> <a href="libunistring.html#TOC55">15. Using the library</a> </h1>
  62
  63 <p>This chapter explains some practical considerations, regarding the
  64 installation and compiler options that are needed in order to use this
  65 library.
  66 </p>
  67
  68 <hr size="6">
  69 <a name="Installation"></a>
  70 <a name="SEC56"></a>
  71 <h2 class="section"> <a href="libunistring.html#TOC56">15.1 Installation</a> </h2>
  72
  73 <p>Before you can use the library, it must be installed.  First, you have to
  74 make sure all dependencies are installed.  They are listed in the file
  75 &lsquo;<tt>DEPENDENCIES</tt>&rsquo;.
  76 </p>
  77 <a name="IDX770"></a>
  78 <p>Then you can proceed to build and install the library, as described in the
  79 file &lsquo;<tt>INSTALL</tt>&rsquo;.  For installation on Windows systems, please refer to
  80 the file &lsquo;<tt>README.woe32</tt>&rsquo;.
  81 </p>
  82 <hr size="6">
  83 <a name="Compiler-options"></a>
  84 <a name="SEC57"></a>
  85 <h2 class="section"> <a href="libunistring.html#TOC57">15.2 Compiler options</a> </h2>
  86
  87 <p>Let's denote as <code>LIBUNISTRING_PREFIX</code> the value of the &lsquo;<samp>--prefix</samp>&rsquo;
  88 option that you passed to <code>configure</code> while installing this package.
  89 If you didn't pass any &lsquo;<samp>--prefix</samp>&rsquo; option, then the package is installed
  90 in &lsquo;<tt>/usr/local</tt>&rsquo;.
  91 </p>
  92 <p>Let's denote as <code>LIBUNISTRING_INCLUDEDIR</code> the directory where the
  93 include files were installed.  This is usually the same as
  94 <code>${LIBUNISTRING_PREFIX}/include</code>.  Except that if you passed an
  95 &lsquo;<samp>--includedir</samp>&rsquo; option to <code>configure</code>, it is the value of that
  96 option.
  97 </p>
  98 <p>Let's further denote as <code>LIBUNISTRING_LIBDIR</code> the directory where
  99 the library itself was installed.  This is the value that you passed
 100 with the &lsquo;<samp>--libdir</samp>&rsquo; option to <code>configure</code>, or otherwise the
 101 same as <code>${LIBUNISTRING_PREFIX}/lib</code>.  Recall that when building
 102 in 64-bit mode on a 64-bit GNU/Linux system that supports executables
 103 in either 64-bit mode or 32-bit mode, you should have used the option
 104 <code>--libdir=${LIBUNISTRING_PREFIX}/lib64</code>.
 105 </p>
 106 <a name="IDX771"></a>
 107 <p>So that the compiler finds the include files, you have to pass it the
 108 option <code>-I${LIBUNISTRING_INCLUDEDIR}</code>.
 109 </p>
 110 <p>So that the compiler finds the library during its linking pass, you have
 111 to pass it the options <code>-L${LIBUNISTRING_LIBDIR} -lunistring</code>.
 112 On some systems, in some configurations, you also have to pass options
 113 needed for linking with <code>libiconv</code>.  The autoconf macro
 114 <code>gl_LIBUNISTRING</code> (see <a href="#SEC59">Autoconf macro</a>) deals with this
 115 particularity.
 116 </p>
 117 <hr size="6">
 118 <a name="Include-files"></a>
 119 <a name="SEC58"></a>
 120 <h2 class="section"> <a href="libunistring.html#TOC58">15.3 Include files</a> </h2>
 121
 122 <p>Most of the include files have been presented in the introduction, see
 123 <a href="libunistring_1.html#SEC1">Introduction</a>, and subsequent detailed chapters.
 124 </p>
 125 <p>Another include file is <code>&lt;unistring/version.h&gt;</code>. It contains the
 126 version number of the libunistring library.
 127 </p>
 128 <dl>
 129 <dt><u>Macro:</u> int <b>_LIBUNISTRING_VERSION</b>
 130 <a name="IDX772"></a>
 131 </dt>
 132 <dd><p>This constant contains the version of libunistring that is being used
 133 at compile time.  It encodes the major and minor parts of the version
 134 number only.  These parts are encoded in the form <code>(major&lt;&lt;8) + minor</code>.
 135 </p></dd></dl>
 136
 137 <dl>
 138 <dt><u>Constant:</u> int <b>_libunistring_version</b>
 139 <a name="IDX773"></a>
 140 </dt>
 141 <dd><p>This constant contains the version of libunistring that is being used
 142 at run time.  It encodes the major and minor parts of the version
 143 number only.  These parts are encoded in the form <code>(major&lt;&lt;8) + minor</code>.
 144 </p></dd></dl>
 145
 146 <p>It is possible that <code>_libunistring_version</code> is greater than
 147 <code>_LIBUNISTRING_VERSION</code>.  This can happen when you use
 148 <code>libunistring</code> as a shared library, and a newer, binary
 149 backward-compatible version has been installed after your program
 150 that uses <code>libunistring</code> was installed.
 151 </p>
 152 <hr size="6">
 153 <a name="Autoconf-macro"></a>
 154 <a name="SEC59"></a>
 155 <h2 class="section"> <a href="libunistring.html#TOC59">15.4 Autoconf macro</a> </h2>
 156
 157 <p>GNU Gnulib provides an autoconf macro that tests for the availability
 158 of <code>libunistring</code>.  It is contained in the Gnulib module
 159 &lsquo;<samp>libunistring</samp>&rsquo;, see
 160 <a href="http://www.gnu.org/software/gnulib/MODULES.html#module=libunistring">http://www.gnu.org/software/gnulib/MODULES.html#module=libunistring</a>.
 161 </p>
 162 <a name="IDX774"></a>
 163 <p>The macro is called <code>gl_LIBUNISTRING</code>.  It searches for an installed
 164 libunistring.  If found, it sets and AC_SUBSTs <code>HAVE_LIBUNISTRING=yes</code>
 165 and the <code>LIBUNISTRING</code> and <code>LTLIBUNISTRING</code> variables and augments
 166 the <code>CPPFLAGS</code> variable, and defines the C macro
 167 <code>HAVE_LIBUNISTRING</code> to 1.  Otherwise, it sets and AC_SUBSTs
 168 <code>HAVE_LIBUNISTRING=no</code> and <code>LIBUNISTRING</code> and <code>LTLIBUNISTRING</code>
 169 to empty.
 170 </p>
 171 <p>The complexities that <code>gl_LIBUNISTRING</code> deals with are the following:
 172 </p>
 173 <ul>
 174 <li>
 175 On some operating systems, in some configurations, libunistring depends
 176 on <code>libiconv</code>, and the options for linking with libiconv must be
 177 mentioned explicitly on the link command line.
 178
 179 </li><li>
 180 GNU <code>libunistring</code>, if installed, is not necessarily already in the
 181 search path (<code>CPPFLAGS</code> for the include file search path,
 182 <code>LDFLAGS</code> for the library search path).
 183
 184 </li><li>
 185 GNU <code>libunistring</code>, if installed, is not necessarily already in the
 186 run time library search path.  To avoid the need for setting an environment
 187 variable like <code>LD_LIBRARY_PATH</code>, the macro adds the appropriate
 188 run time search path options to the <code>LIBUNISTRING</code> variable.  This works
 189 on most systems.
 190 </li></ul>
 191
 192 <hr size="6">
 193 <a name="Reporting-problems"></a>
 194 <a name="SEC60"></a>
 195 <h2 class="section"> <a href="libunistring.html#TOC60">15.5 Reporting problems</a> </h2>
 196
 197 <p>If you encounter any problem, please don't hesitate to send a detailed
 198 bug report to the <code>bug-libunistring@gnu.org</code> mailing list.  You can
 199 alternatively also use the bug tracker at the project page
 200 <a href="https://savannah.gnu.org/projects/libunistring">https://savannah.gnu.org/projects/libunistring</a>.
 201 </p>
 202 <p>Please always include the version number of this library, and a short
 203 description of your operating system and compilation environment with
 204 corresponding version numbers.
 205 </p>
 206 <p>For problems that appear while building and installing <code>libunistring</code>,
 207 for which you don't find the remedy in the &lsquo;<tt>INSTALL</tt>&rsquo; file, please include
 208 a description of the options that you passed to the &lsquo;<samp>configure</samp>&rsquo; script.
 209 </p>
 210 <hr size="6">
 211 <table cellpadding="1" cellspacing="1" border="0">
 212 <tr><td valign="middle" align="left">[<a href="#SEC55" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
 213 <td valign="middle" align="left">[<a href="libunistring_16.html#SEC61" title="Next chapter"> &gt;&gt; </a>]</td>
 214 <td valign="middle" align="left"> &nbsp; </td>
 215 <td valign="middle" align="left"> &nbsp; </td>
 216 <td valign="middle" align="left"> &nbsp; </td>
 217 <td valign="middle" align="left"> &nbsp; </td>
 218 <td valign="middle" align="left"> &nbsp; </td>
 219 <td valign="middle" align="left">[<a href="libunistring.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
 220 <td valign="middle" align="left">[<a href="libunistring.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
 221 <td valign="middle" align="left">[<a href="libunistring_18.html#SEC71" title="Index">Index</a>]</td>
 222 <td valign="middle" align="left">[<a href="libunistring_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
 223 </tr></table>
 224 <p>
 225  <font size="-1">
 226   This document was generated by <em>Bruno Haible</em> on <em>March, 30 2010</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html 1.78a</em></a>.
 227  </font>
 228  <br>
 229
 230 </p>
 231 </body>
 232 </html>