external/bsd/bind/dist/contrib/idn/idnkit-1.0-src/INSTALL

   1
   2                                 idnkit
   3                      Compilation and Installation
   4                Japan Network Information Center (JPNIC)
   5
   6
   7 This file explains how to compile and install the source package.
   8 These procedures take the following steps:
   9
  10     + Prerequisite: making iconv() available
  11     + System Configuration: running `configure' script
  12     + Compilation: running `make'
  13     + Test: running `make test' (optional)
  14     + Installation: running `make install'
  15     + Site Configuration: tailoring `idn.conf'
  16     + Configuration Check (optional)
  17     + Clean up (optional)
  18
  19 See also the following section if you'd like to apply patch and install
  20 BIND9.
  21
  22     + Applying patches
  23
  24 0. Prerequisite
  25
  26 If you want to install generic idnkit library with code conversion
  27 support, and also if your system's library does not have iconv()
  28 function, which is a general codeset conversion utility, install iconv
  29 as an external library.  You also need external library if the
  30 system's implementation cannot handle UTF-8 encoding, or it doesn't
  31 support some encodings which your client applications uses.
  32
  33 You can get a free version of iconv() implementation (under LGPL
  34 license, aka GNU libiconv) from:
  35
  36         ftp://ftp.gnu.org/gnu/libiconv/
  37         and mirrors of that site.
  38
  39 But if you don't want code conversion support and you want to install
  40 idnkitlite library without iconv support alone, you have not install
  41 external library.  Instead, set `--enable-liteonly' value to "yes" at
  42 configure script execution.
  43
  44
  45 1. Running configure script
  46
  47 Run `configure' script in the top directory.  This checks various
  48 characteristics of your system and it will create Makefiles and
  49 config.h appropriate for your system.
  50
  51         % ./configure
  52
  53 `configure' accepts many options.  Here is a list of some important
  54 options.
  55
  56     --prefix=PREFIX
  57         Specifies the prefix of install directories of idnkit.  The
  58         default is /usr/local.
  59
  60     --enable-runidn
  61         Build `runidn' command.  The default is "no".
  62
  63         You cannot set this option "yes" when `--enable-liteonly' is
  64         also set "yes".
  65
  66     --with-libiconv=LIBICONV_PREFIX
  67         If you have installed GNU libiconv and would like to link it
  68         to idnkit, specify this option.  The argument LIBICONV_PREFIX
  69         is install prefix of GNU libiconv.  If the argument is omitted,
  70         PREFIX (derived from --prefix=PREFIX option) is assumed.
  71
  72         --with-libiconv is shorthand option for GNU libiconv.
  73
  74             --with-libiconv=/usr/local
  75
  76         This is equivalent to:
  77
  78             --with-iconv-include='-I/usr/local/include'
  79             --with-iconv='-L/usr/local/lib -R/usr/local/lib -liconv'
  80
  81         If both the shorthand option (--with-libiconv) and longhand
  82         options (--with-iconv-include and/or --with-iconv) are specified,
  83         the longhand options have priority.
  84
  85         You cannot set this option when --enable-liteonly is set
  86         "yes", because libidnkitlite library doesn't need iconv
  87         support.
  88
  89     --with-iconv-include=ICONV_INCDIR
  90         If the header file "iconv.h" resides in a directory where your
  91         C compiler doesn't search by default, specify the directory as
  92         DIR like this:
  93
  94             --with-iconv-include=/usr/local/include
  95
  96         You cannot set this option when `--enable-liteonly' is set
  97         "yes", because libidnkitlite library doesn't need iconv
  98         support.
  99
 100     --with-iconv=ICONV_LIB
 101         If your libc doesn't contain iconv(), specify the library
 102         that contains iconv().  For example, if iconv() is libiconv
 103         in /usr/local/lib, you should specify:
 104
 105             --with-iconv="-L/usr/local/lib -liconv"
 106
 107         Note that if the library is a shared one, you might also want
 108         to specify -R option, like:
 109
 110             --with-iconv="-L/usr/local/lib -R/usr/local/lib -liconv"
 111
 112         You cannot set this option when `--enable-liteonly' is set
 113         "yes", because libidnkitlite library doesn't need iconv
 114         support.
 115
 116     --with-iconv-sofile=SOFILE_PATH
 117         The runidn command in this kit needs to know the pathname of
 118         shared library file that contains iconv(), if iconv() is not
 119         part of libc.  idnkit tries to find out the pathname from the
 120         informaiton provided by `--with-iconv' option described above.
 121         But when it fails, you have to specify it with this option,
 122         like:
 123
 124             --with-iconv-sofile=/usr/local/lib/libiconv.so.2.0
 125
 126         You cannot set this option when `--enable-liteonly' is set
 127         "yes", because libidnkitlite library doesn't need iconv
 128         support.
 129
 130     --with-utf8=UTF8_NAME
 131         If your iconv() (precisely, iconv_open()) does not accept
 132         "UTF-8" as the name of UTF-8 encoding, specify the name for
 133         it.  For example if your iconv() uses "utf8" instead, you
 134         should specify:
 135
 136             --with-utf8=utf8
 137
 138
 139 2. Other configure options
 140
 141 The configure script has many other options though they are not widely
 142 used:
 143
 144     --exec-prefix=EXEC_PREFIX
 145         Specifies the prefix of install directories for machine-specific
 146         files.  The default is PREFIX (derived from `--prefix=PREFIX'
 147         and its default is /usr/local).
 148
 149     --bindir=BINDIR
 150         Specifies the install directory for idnconv and runidn.
 151         The default is EXEC_PREFIX/bin.
 152
 153     --libdir=LIBDIR
 154         Specifies the install directory for the libraries (libidnkit
 155         and libidnkitlite).  The default is EXEC_PREFIX/lib.
 156
 157     --includedir=INCDIR
 158         Specifies the install directory for the header files of the
 159         libraries.  The default is PREFIX/include.
 160
 161     --sysconfdir=SYSCONFDIR
 162         Specifies the install directory for sample configuration files
 163         of the libraries.  The default is PREFIX/etc.
 164
 165     --mandir=MANDIR
 166         Specifies the base install directory for online manuals.
 167         The default is PREFIX/man.
 168
 169     --datadir=DATADIR
 170         Specifies the base install directory for machine independent
 171         data files.  The default is PREFIX/share.  Some data files for
 172         idnkit will be put under the DATADIR/idnkit directory.
 173
 174     --enable-debug
 175         Enable debugging codes.  The fault is "no".
 176
 177     --enable-shared
 178         Build shared library.  The fault is "yes".
 179
 180     --enable-static
 181         Build static library.  The fault is "yes".
 182
 183     --enable-liteonly
 184         Build the `libidnlkitite' library only.  Do not build the
 185         `libidnkit' library, idnconv and runidn.  The fault is "no".
 186
 187         If you want to set "yes" to this option, you cannot specify it
 188         together with `--enable-runidn', `--with-libiconv',
 189         `--with-iconv-include', `--with-iconv' or `--with-iconv-sofile'.
 190
 191 To see the list of available options, you should run it with --help
 192 option.
 193
 194         % ./configure --help
 195
 196
 197 3. Compiling
 198
 199 Run `make' for compilation.
 200
 201         % make
 202
 203
 204 4. Test
 205
 206 Optionally, type `make test' to compile and run test programs.
 207 Note that Perl 5 is required for comipilation of the test programs.
 208
 209         % make test
 210
 211 The test programs assume that iconv() on the system recognizes the
 212 encoding name "EUC-JP" as Japanese EUC, and "SJIS" as Japanese Shift
 213 JIS.  If iconv() on the system doesn't support the encoding name,
 214 please edit `lib/tests/codeset.h' before `make test'.
 215
 216 *Note*
 217   If you use standard iconv which is attached as default on Solaris,
 218   converter's test "idn_converter_convfromucs4()" may fail.  But it's
 219   not the problem because the result is derived from the difference of
 220   specification of iconv.  So please ignore it if you run the test on
 221   Solaris.
 222
 223
 224 5. Installation
 225
 226 Run `make install' to install binaries and manuals.  Don't forget to
 227 become a super-user before the installation.
 228
 229         % su
 230         # make install
 231
 232 *Note*
 233   If you have installed pre-release versions of idnkit (such as 1.0pr1),
 234   idnkit-1.0 may not work correctly because of the old configuration
 235   file 'idn.conf'.  If this is the case, you should overwrite existing
 236   configuration files with the new ones by executing the following command
 237   after 'make install'.
 238
 239         # make install-config
 240
 241
 242 6. Configuration and usage
 243
 244 Edit the `idn.conf' configuation file if you'd like to cosutomize
 245 conversion/normalization rules of idnkit.  Please refer the manual
 246 for `idn.conf' for details.  A sample configuration (`idn.conf.sample')
 247 is also provided for your convenience.
 248
 249 The sample configuration file has also been installed as `idn.conf'
 250 if it has not exist on your system.
 251
 252 Also online manuals for `idnconv' and `runidn' commands are available.
 253 Please refer them for the usage and configuration of these commands.
 254
 255         % man idn.conf
 256         % man idnconv
 257         % man runidn
 258
 259
 260 7. Check your configuration
 261
 262 A simple shell script `idnslookup' is available in the directory
 263 `tools/idnconv', with which you can make queries for internationalized
 264 domain names.  It may help you check your configuration.
 265
 266 The usage of `idnslookup' is:
 267
 268         % tools/idnconv/idnslookup <domain-name> <dns-server>
 269
 270 Suppose that <domain-name> is an internationalized domain name written
 271 in the local codeset (see ``LOCAL CODESET'' in the `idn.conf' man page
 272 for details), and <dns-server> is a hostname or IP address of DNS
 273 server.
 274
 275 `idnslookup' inquires <idn-domain-name> from <dns-server>, using
 276 `idnconv' and `nslookup' commands.  If something is wrong, you will
 277 see an error message output by `idnconv', `nslookup' or `idnslookup'
 278 itself.
 279
 280
 281 8. Clean up
 282
 283 Run `make clean' to delete files generated by `make' and `make test'
 284 from the idnkit source directory.  (Files installed by `make install'
 285 are not removed.)
 286
 287         % make clean
 288
 289 Run `make distclean' instead to also delete files generated by
 290 `configure'.
 291
 292         % make distclean
 293
 294 After `make distclean', you can run `configure' and compile idnkit for
 295 another system using the source directory.
 296
 297
 298 Appendix A. Applying patches
 299
 300 This distribution also contains patches for BIND9.
 301 The top of these patch files describe how to apply the patch and
 302 (re)install.
 303
 304 Note that on Solaris, "patch" command that comes with the system
 305 sometimes doesn't work correctly.  You may want to install the GNU
 306 version of the command (http://www.gnu.org/software/patch/) and use
 307 it.
 308
 309 ; Id: INSTALL,v 1.1 2003/06/04 00:24:59 marka Exp