README.win32

   1        Release notes on the MS Windows ports of Objective Caml
   2        -------------------------------------------------------
   3
   4 There are no less than four ports of Objective Caml for MS Windows available:
   5   - a native Win32 port, built with the Microsoft development tools;
   6   - a native Win32 port, built with the Cygwin/MinGW development tools;
   7   - a port consisting of the Unix sources compiled under the Cygwin
   8     Unix-like environment for Windows;
   9   - a native Win64 port (64-bit Windows), built with the Microsoft
  10     development tools.
  11
  12 Here is a summary of the main differences between these ports:
  13
  14                                       Native MS     Native MinGW        Cygwin
  15
  16 64 bits?                            Win32 or Win64    Win32 only      Win32 only
  17
  18 Third-party software required
  19   - for base bytecode system            none            none            none
  20   - for ocamlc -custom                  MSVC            Cygwin          Cygwin
  21   - for native-code generation          MSVC+MASM       Cygwin          Cygwin
  22
  23 Speed of bytecode interpreter           70%             100%            100%
  24
  25 Replay debugger                         no              no              yes
  26
  27 The Unix library                        partial         partial         full
  28
  29 The Threads library                     yes             yes             yes
  30
  31 The Graphics library                    yes             yes             no
  32
  33 Restrictions on generated executables?  none            none            yes (*)
  34
  35 (*) Cygwin-generated .exe files refer to a DLL that is distributed under
  36 the GPL.  Thus, these .exe files can only be distributed under a license
  37 that is compatible with the GPL.  Executables generated by MSVC or by
  38 MinGW have no such restrictions.
  39
  40 The remainder of this document gives more information on each port.
  41
  42 ------------------------------------------------------------------------------
  43
  44            The native Win32 port built with Microsoft Visual C
  45            ---------------------------------------------------
  46
  47 REQUIREMENTS:
  48
  49 This port runs under MS Windows NT, 2000 and XP.
  50 Windows 95, 98 and ME are no longer supported.
  51
  52 The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
  53 runs without any additional tools.
  54
  55 Statically linking Caml bytecode with C code (ocamlc -custom) requires the
  56 Microsoft Visual C++ compiler (items [1] and [2] in the section
  57 "third-party software" below).  Dynamic loading of DLLs is supported
  58 out of the box, without additional software.
  59
  60 The native-code compiler (ocamlopt) requires Visual C++ (items [1], [2])
  61 and the Microsoft assembler MASM (item [3]).
  62
  63 The LablTk GUI requires Tcl/Tk 8.4 (item [4]).
  64
  65
  66 INSTALLATION:
  67
  68 The binary distribution is a self-installing executable archive.
  69 Just run it and it should install OCaml automatically.
  70
  71 To run programs that use the LablTK GUI, the directory where the
  72 DLLs tk84.dll and tcl84.dll were installed (by the Tcl/Tk
  73 installer) must be added to the PATH environment variable.
  74
  75 To compile programs that use the LablTK GUI, the directory where the
  76 libraries tk84.lib and tcl84.lib were installed (by the Tcl/Tk
  77 installer) must be added to the library search path in the LIB
  78 environment variable.  E.g. if Tcl/Tk was installed in C:\tcl, add
  79 "C:\tcl\lib" to the LIB environment variable.
  80
  81
  82 THIRD-PARTY SOFTWARE:
  83
  84 [1] Visual C++ version 2005, 2003, or 6.
  85     We use Visual C++ 2005 Express Edition, which can be downloaded for free
  86     from http://www.microsoft.com.
  87
  88 [2] Windows header files and development libraries.  We found them in
  89     the Microsoft Windows Server 2003 SP1 Platform SDK, which can
  90     be downloaded for free from http://www.microsoft.com/.
  91
  92 [3] MASM version 6.11 or later. The full distribution of Visual C++ 2005
  93     contains MASM version 8.  Users of the Express Edition of Visual C++
  94     2005 can download MASM version 8 from
  95 http://www.microsoft.com/downloads/details.aspx?FamilyID=7A1C9DA0-0510-44A2-B042-7EF370530C64&displaylang=en
  96     To obtain MASM version 6.11, see
  97     http://users.easystreet.com/jkirwan/new/pctools.html.
  98
  99 [4] TCL/TK version 8.4.  Windows binaries are available as part of the
 100     ActiveTCL distribution at http://www.activestate.com/products/ActiveTcl/
 101
 102 RECOMPILATION FROM THE SOURCES:
 103
 104 The command-line tools can be recompiled from the Unix source
 105 distribution (ocaml-X.YZ.tar.gz), which also contains the files modified
 106 for Windows.
 107
 108 You will need the following software components to perform the recompilation:
 109 - Windows NT, 2000, XP, or Vista.
 110 - Items [1], [2], [3] and [4] from the list of recommended software above.
 111 - The Cygwin port of GNU tools, available from http://www.cygwin.com/
 112
 113 Remember to add the directory where the libraries tk84.lib and
 114 tcl84.lib were installed (by the Tcl/Tk installer) to the LIB variable
 115 (library search path).
 116
 117 To recompile, start a Cygwin shell and change to the top-level
 118 directory of the OCaml distribution.  Then, do
 119
 120         cp config/m-nt.h config/m.h
 121         cp config/s-nt.h config/s.h
 122         cp config/Makefile.msvc config/Makefile
 123
 124 Then, edit config/Makefile as needed, following the comments in this file.
 125 Normally, the only variables that need to be changed are
 126         PREFIX      where to install everything
 127         TK_ROOT     where TCL/TK was installed
 128
 129 Finally, use "make -f Makefile.nt" to build the system, e.g.
 130
 131         make -f Makefile.nt world
 132         make -f Makefile.nt bootstrap
 133         make -f Makefile.nt opt
 134         make -f Makefile.nt opt.opt
 135         make -f Makefile.nt install
 136
 137 Alternatively you can use the experimental build procedure using ocamlbuild:
 138
 139         ./build/fastworld.sh
 140         ./build/install.sh
 141
 142 NOTES:
 143
 144 * The VC++ compiler does not implement "computed gotos", and therefore
 145 generates inefficient code for byterun/interp.c. Consequently, the
 146 performance of bytecode programs is about 2/3 of that obtained under
 147 Unix/GCC or Cygwin or Mingw on similar hardware.
 148
 149 * Libraries available in this port: "num", "str", "threads", "graphics",
 150 "labltk", and large parts of "unix".
 151
 152 * The replay debugger is not supported.
 153
 154 CREDITS:
 155
 156 The initial port of Caml Special Light (the ancestor of Objective Caml)
 157 to Windows NT was done by Kevin Gallo at Microsoft Research, who
 158 kindly contributed his changes to the Caml project.
 159
 160 The graphical user interface for the toplevel was initially developed
 161 by Jacob Navia, then significantly improved by Christopher A. Watford.
 162
 163 ------------------------------------------------------------------------------
 164
 165            The native Win32 port built with Mingw
 166            --------------------------------------
 167
 168 REQUIREMENTS:
 169
 170 This port runs under MS Windows NT, 2000 and XP.
 171 Windows 95, 98 and ME are also supported, but less reliably.
 172
 173 The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
 174 runs without any additional tools.
 175
 176 The native-code compiler (ocamlopt), as well as static linking of
 177 Caml bytecode with C code (ocamlc -custom), require
 178 the Cygwin development tools, available at
 179         http://www.cygwin.com/
 180 You will need to install at least the following Cygwin packages (use
 181 the Setup tool from Cygwin):
 182 binutils, gcc-core, gcc-mingw-core, mingw-runtime, w32-api.
 183
 184 Do *not* install the Mingw/MSYS development tools from www.mingw.org:
 185 these are not compatible with this Caml port (@responsefile not
 186 recognized on the command line).
 187
 188 The LablTk GUI requires Tcl/Tk 8.4.  Windows binaries are available
 189 as part of the ActiveTCL distribution at
 190 http://www.activestate.com/products/ActiveTcl/
 191
 192 INSTALLATION:
 193
 194 The binary distribution is a self-installing executable archive.
 195 Just run it and it should install OCaml automatically.
 196
 197 To run programs that use the LablTK GUI, the directory where the
 198 DLLs tk84.dll and tcl84.dll were installed (by the Tcl/Tk
 199 installer) must be added to the PATH environment variable.
 200
 201 To compile programs that use the LablTK GUI, the directory where the
 202 libraries tk84.lib and tcl84.lib were installed (by the Tcl/Tk
 203 installer) must be added to the library search path in the LIB
 204 environment variable.  E.g. if Tcl/Tk was installed in C:\tcl, add
 205 "C:\tcl\lib" to the LIB environment variable.
 206
 207
 208 RECOMPILATION FROM THE SOURCES:
 209
 210 You will need the following software components to perform the recompilation:
 211 - Windows NT, 2000, XP, or Vista.
 212 - Cygwin: http://sourceware.cygnus.com/cygwin/
 213 - TCL/TK version 8.4 (see above).
 214
 215 Do *not* install the standalone distribution of MinGW, nor the
 216 companion MSYS tools: these have problems with long command lines.
 217 Instead, use the version of MinGW that is installed along with Cygwin.
 218
 219 Start a Cygwin shell and unpack the source distribution
 220 (ocaml-X.YZ.tar.gz) with "tar xzf".  Change to the top-level
 221 directory of the OCaml distribution.  Then, do
 222
 223         cp config/m-nt.h config/m.h
 224         cp config/s-nt.h config/s.h
 225         cp config/Makefile.mingw config/Makefile
 226
 227 Then, edit config/Makefile as needed, following the comments in this file.
 228 Normally, the only variables that need to be changed are
 229         PREFIX      where to install everything
 230         TK_ROOT     where TCL/TK was installed
 231
 232 Finally, use "make -f Makefile.nt" to build the system, e.g.
 233
 234         make -f Makefile.nt world
 235         make -f Makefile.nt bootstrap
 236         make -f Makefile.nt opt
 237         make -f Makefile.nt opt.opt
 238         make -f Makefile.nt install
 239
 240
 241 NOTES:
 242
 243 * Libraries available in this port: "num", "str", "threads", "graphics",
 244   "labltk", and large parts of "unix".
 245
 246 * The replay debugger is not supported.
 247
 248 ------------------------------------------------------------------------------
 249
 250                   The Cygwin port of Objective Caml
 251                   ---------------------------------
 252
 253 REQUIREMENTS:
 254
 255 This port requires the Cygwin environment from Cygnus/RedHat, which
 256 is freely available at:
 257           http://www.cygwin.com/
 258
 259 This port runs under all versions of MS Windows supported by Cygwin.
 260
 261
 262 INSTALLATION:
 263
 264 We do not distribute binaries for this port, but they can be found
 265 in the Cygwin distribution (use the Setup tool from Cygwin and select
 266 the OCaml packages).  Alternatively, recompile from the source distribution.
 267
 268
 269 RECOMPILATION FROM THE SOURCES:
 270
 271 Just follow the instructions for Unix machines given in the file INSTALL.
 272
 273
 274 NOTES:
 275
 276 The libraries available in this port are "num", "str", "threads",
 277 "unix" and "labltk".  "graph" is not available.
 278 The replay debugger is supported.
 279
 280 ------------------------------------------------------------------------------
 281
 282        The native Win64 port built with the Microsoft Platform SDK compilers
 283        ---------------------------------------------------------------------
 284
 285 REQUIREMENTS:
 286
 287 This port runs under MS Windows XP 64 and Server 64 on Intel64/AMD64 machines.
 288
 289 The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
 290 runs without any additional tools.
 291
 292 Statically linking Caml bytecode with C code (ocamlc -custom) requires the
 293 Microsoft Platform SDK compiler (item [1] in the section
 294 "third-party software" below).  Dynamic loading of DLLs is supported
 295 out of the box, without additional software.
 296
 297 The native-code compiler (ocamlopt) requires the Microsoft compiler
 298 and the Microsoft assembler MASM64 (item [1]).
 299
 300
 301 INSTALLATION:
 302
 303 There is no binary distribution yet.  Please compile from sources as
 304 described below.
 305
 306
 307 THIRD-PARTY SOFTWARE:
 308
 309 [1] Microsoft Windows Server 2003 R2 Platform SDK for AMD64 (PSDK-amd64.exe).
 310     Can be downloaded for free from http://www.microsoft.com/.
 311     Includes all we need, namely a C compiler, the masm64 assembler,
 312     Windows libraries and include files.
 313
 314
 315 RECOMPILATION FROM THE SOURCES:
 316
 317 The command-line tools can be recompiled from the Unix source
 318 distribution (ocaml-X.YZ.tar.gz), which also contains the files modified
 319 for Windows.
 320
 321 You will need the following software components to perform the recompilation:
 322 - Windows XP 64 or Server 64.
 323 - The Platform SDK (item [1] from the list of recommended software above).
 324 - The Cygwin port of GNU tools, available from http://www.cygwin.com/
 325
 326 To recompile, start a Cygwin shell and change to the top-level
 327 directory of the OCaml distribution.  Then, do
 328
 329         cp config/m-nt.h config/m.h
 330         cp config/s-nt.h config/s.h
 331         cp config/Makefile.msvc64 config/Makefile
 332
 333 Then, edit config/Makefile as needed, following the comments in this file.
 334 Normally, the only variable that need to be changed is
 335         PREFIX      where to install everything
 336
 337 If, for whatever reason, you want to use the Microsoft Visual C++ 2005
 338 compiler for AMD64 instead of the Platform SDK compiler, replace the line
 339         EXTRALIBS=bufferoverflowu.lib
 340 by
 341         EXTRALIBS=
 342
 343 Finally, use "make -f Makefile.nt" to build the system, e.g.
 344
 345         make -f Makefile.nt world
 346         make -f Makefile.nt bootstrap
 347         make -f Makefile.nt opt
 348         make -f Makefile.nt opt.opt
 349         make -f Makefile.nt install
 350
 351
 352 NOTES:
 353
 354 * Libraries available in this port: "num", "str", "threads", "graphics",
 355   and large parts of "unix".
 356
 357 * The replay debugger and the graphical browser are not supported.
 358