helm/DEVEL/pxp/netstring/doc/INSTALL.xml

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