helm/DEVEL/pxp/netstring/doc/INSTALL

   1 ******************************************************************************
   2 INSTALL - Netstring, string processing functions for the net
   3 ******************************************************************************
   4
   5
   6 ==============================================================================
   7 The "Netstring" package
   8 ==============================================================================
   9
  10 ------------------------------------------------------------------------------
  11 Prerequisites
  12 ------------------------------------------------------------------------------
  13
  14 Netstring does not need any other packages besides the O'Caml core. Netstring
  15 needs at least O'Caml 3.00. The installation procedure defined in the Makefile
  16 requires findlib [1] to work [2].
  17
  18 ------------------------------------------------------------------------------
  19 Configuration
  20 ------------------------------------------------------------------------------
  21
  22 It is not necessary to configure "Netstring".
  23
  24 ------------------------------------------------------------------------------
  25 Compilation
  26 ------------------------------------------------------------------------------
  27
  28 The Makefile defines the following goals:
  29
  30 -  make all
  31    compiles with the bytecode compiler and creates netstring.cma,
  32    netstring_mt.cmo, netstring_top.cmo, netmappings_iso.cmo, and
  33    netmappings_other.cmo
  34
  35 -  make opt
  36    compiles with the native compiler and creates netstring.cmxa,
  37    netstring_mt.cmx, netmappings_iso.cmx, and netmappings_other.cmx
  38
  39 The archive netstring.cmx?a contains the functionality, and the two
  40 single-module files netmappings_iso.cm[ox] and netmappings_other.cm[ox] add
  41 configurations to the character set conversion module. These configurations are
  42 optional:
  43
  44 -  Netmappings_iso: Conversion tables for the character sets ISO-8859-2, -3,
  45    -4, -5, -6, -7, -8, -9, -10, 13, -14, and -15.
  46
  47 -  Netmappings_other: Conversion tables for the character sets WINDOWS-1250,
  48    -1251, -1252, -1253, -1254, -1255, -1256, -1257, -1258; code pages 037, 424,
  49    437, 500, 737, 775, 850, 852, 855, 856, 857, 860, 861, 862, 863, 864, 865,
  50    866, 869, 874, 875, 1006, 1026; JIS-0201; KOI8R; Macintosh Roman encoding;
  51    Adobe Standard Encoding, Symbol Encoding, and Zapf Dingbats Encodings.
  52
  53 Even without these configuration files, the conversion module is able to handle
  54 the encodings ISO-8859-1, US-ASCII, UTF-16, UTF-8, and the Java variant of
  55 UTF-8.
  56
  57 The module Netstring_mt must be linked into multi-threaded applications;
  58 otherwise some mutexes remain uninitialized.
  59
  60 The module Netstring_top loads several printers for abstract values (for
  61 toploops).
  62
  63 ------------------------------------------------------------------------------
  64 Installation
  65 ------------------------------------------------------------------------------
  66
  67 The Makefile defines the following goals:
  68
  69 -  make install
  70    installs the bytecode archive, the interface definitions, and if present,
  71    the native archive in the default location of findlib
  72
  73 -  make install-cgi
  74    Installs a pseudo package "cgi" which is compatible with the old cgi
  75    package. This has the effect that software searching the "cgi" package will
  76    find the netstring package instead. This is recommended.
  77
  78 -  make install-base64
  79    Installs a pseudo package "base64" which is compatible with the old base64
  80    package. This has the effect that software searching the "base64" package
  81    will find the netstring package instead. This is recommended.
  82
  83 -  make uninstall
  84    removes the package
  85
  86 -  make uninstall-cgi
  87    removes the "cgi" compatibility package
  88
  89 -  make uninstall-base64
  90    removes the "base64" compatibility package
  91
  92 ------------------------------------------------------------------------------
  93 Linking netstring with findlib
  94 ------------------------------------------------------------------------------
  95
  96 The command
  97
  98 ocamlfind ocamlc ... -package netstring ... -linkpkg ...
  99
 100 links as much as possible code from netstring into your application: All
 101 conversion tables; when -thread is specified, the initialization code for
 102 multi-threaded programs; when a toploop is created, the code setting the value
 103 printers.
 104
 105 The following predicates reduce the amount of linked code:
 106
 107 -  netstring_only_iso: Only the conversion tables for the ISO-8859 series of
 108    character sets are linked.
 109
 110 -  netstring_minimum: No additional conversion tables are linked; only
 111    ISO-8859-1 and the UTF encodings work.
 112
 113 For example, the command may look like
 114
 115 ocamlfind ocamlc ...
 116           -package netstring -predicates netstring_only_iso ... -linkpkg ...
 117
 118 to link only the ISO-8859 conversion tables.
 119
 120
 121 --------------------------
 122
 123 [1]   see http://www.ocaml-programming.de/packages/documentation/findlib/
 124
 125 [2]   Findlib is a package manager, see the file ABOUT-FINDLIB.
 126
 127
 128