Merge pull request #536 from dra27/overhaul-install-docs

Overhaul Windows install docs 

6 files changed, 493 insertions, 587 deletions

diff --git a/.gitattributes b/.gitattributes
index f472b347f4..d83330eece 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -101,6 +101,7 @@ stdlib/sharpbang text eol=lf
 tools/check-typo text eol=lf
 tools/ci-build text eol=lf
 tools/cleanup-header text eol=lf
+tools/msvs-promote-path text eol=lf
 tools/gdb-macros text eol=lf
 tools/magic text eol=lf
 tools/make-opcodes text eol=lf
diff --git a/INSTALL.adoc b/INSTALL.adoc
index aaee76f3f9..cdea168dac 100644
--- a/INSTALL.adoc
+++ b/INSTALL.adoc
@@ -1,143 +1,145 @@
-= Installing OCaml on a Unix machine =
+= Installing OCaml on a Unix(-like) machine =
 
 == PREREQUISITES
 
-* The GNU C compiler gcc is recommended, as the bytecode
-  interpreter takes advantage of gcc-specific features to enhance
-  performance.  gcc is the standard compiler under Linux, MacOS X,
-  and many other systems.
+* The GNU C Compiler (gcc) is recommended, as the bytecode interpreter takes
+  advantage of GCC-specific features to enhance performance. gcc is the standard
+  compiler under Linux, OS X, and many other systems.
 
-* If you do not have write access to /tmp, you should set the environment
-  variable TMPDIR to the name of some other temporary directory.
+* If you do not have write access to `/tmp`, you should set the environment
+  variable `TMPDIR` to the name of some other temporary directory.
 
-* Under HP/UX, the GNU C compiler gcc, the GNU assembler gas, and GNU make
-  are all *required*.  The vendor-provided compiler, assembler and make
+* Under HP/UX, the GNU C Compiler (gcc), the GNU Assembler (gas), and GNU Make
+  are all *required*.  The vendor-provided compiler, assembler and make tools
   have major problems.
 
+* Under Cygwin, the `gcc-core` and `make` packages are required.  `flexdll` is
+  necessary for shared library support.  `libX11-devel` is necessary for graph
+  library support and `libintl-devel` is necessary for the `ocamlobjinfo` tool
+  to be able to process `.cmxs` files.  `diffutils` is necessary to run the test
+  suite.
+
 == INSTALLATION INSTRUCTIONS
 
 1. Configure the system. From the top directory, do:
 
         ./configure
 +
-This generates the three configuration files "Makefile", "m.h" and "s.h"
-in the config/ subdirectory.
+This generates the three configuration files `Makefile`, `m.h` and `s.h`
+in the `config/` subdirectory.
 +
 The `configure` script accepts the following options:
 +
--prefix <dir>::                   (default: '/usr/local')
-        Set the PREFIX variable used to define the defaults of the
-        following three options.  Must be an absolute path name.
+`-prefix <dir>`::                   (default: `/usr/local`)
+        Set the `PREFIX` variable used to define the defaults of the following
+        three options.  Must be an absolute path name.
 
--bindir <dir>::                   (default: '$(PREFIX)/bin')
-        Directory where the binaries will be installed.
-        Must be an absolute path name, or start with "$(PREFIX)"
+`-bindir <dir>`::                   (default: `$(PREFIX)/bin`)
+        Directory where the binaries will be installed.  Must be an absolute
+        path name, or start with `$(PREFIX)`.
 
--libdir <dir>::                   (default: '$(PREFIX)/lib/ocaml')
-        Directory where the OCaml library will be installed
-        Must be an absolute path name, or start with "$(PREFIX)"
+`-libdir <dir>`::                   (default: `$(PREFIX)/lib/ocaml`)
+        Directory where the OCaml library will be installed.  Must be an
+        absolute path name, or start with `$(PREFIX)`.
 
--mandir <dir>::                   (default: '$(PREFIX)/man/man1')
-        Directory where the manual pages will be installed
-        Must be an absolute path name, or start with "$(PREFIX)"
+`-mandir <dir>`::                   (default: `$(PREFIX)/man/man1`)
+        Directory where the manual pages will be installed.  Must be an absolute
+        path name, or start with `$(PREFIX)`.
 
--cc <C compiler and options>::    (default: gcc if available, cc otherwise)
-        C compiler to use for building the system
+`-cc <C compiler and options>`::    (default: `gcc` if found, otherwise `cc`)
+        C compiler to use for building the system.
 
--libs <extra libraries>::         (default: none)
-        Extra libraries to link with the system
+`-libs <extra libraries>`::         (default: none)
+        Extra libraries to link with the system.
 
--no-curses::
+`-no-curses`::
         Do not use the curses library.
 
--host <hosttype>::                (default: determined automatically)
-        The type of the host machine, in GNU's "configuration name"
-        format (CPU-COMPANY-SYSTEM or CPU-COMPANY-KERNEL-SYSTEM).
-        This info is generally determined automatically by the
-        "configure" script, and rarely ever needs to be provided by
-        hand. The installation instructions for gcc or emacs contain a
-        complete list of configuration names.
-
--target <targettype>::            (default: same as -host)
-        The type of the target machine, in GNU's "configuration name"
-        format (CPU-COMPANY-SYSTEM or CPU-COMPANY-KERNEL-SYSTEM).
-        Setting this will setup OCaml as a cross-compiler which runs on
-        $host and produces code for $target. This requires a C toolchain
-        which also produces code for $target and a native OCaml
-        compiler of the exact same version (if you want a cross 4.00.1,
-        you need a native 4.00.1).
-
--x11include <include_dir>::       (default: determined automatically)
--x11lib     <lib_dir>::           (default: determined automatically)
-        Location of the X11 include directory (e.g. /usr/X11R6/include)
-        and the X11 library directory (e.g. /usr/X11R6/lib).
-
--no-pthread::
+`-host <hosttype>`::                (default: determined automatically)
+        The type of the host machine, in GNU's "configuration name" format
+        (CPU-COMPANY-SYSTEM or CPU-COMPANY-KERNEL-SYSTEM).  This info is
+        generally determined automatically by the `configure` script, and rarely
+        ever needs to be provided by hand.  The installation instructions for
+        GCC or GNU Emacs contain a complete list of configuration names.
+
+`-target <targettype>`::            (default: same as `-host`)
+        The type of the target machine, in GNU's "configuration name" format
+        (CPU-COMPANY-SYSTEM or CPU-COMPANY-KERNEL-SYSTEM). Setting this will
+        setup OCaml as a cross-compiler which runs on `$host` and produces code
+        for `$target`. This requires a C toolchain which also produces code for
+        `$target` and a native OCaml compiler of the exact same version (if you
+        want a cross 4.00.1, you need a native 4.00.1).
+
+`-x11include <include_dir>`::       (default: determined automatically)
+`-x11lib <lib_dir>`::               (default: determined automatically)
+        Location of the X11 include directory (e.g. `/usr/X11R6/include`) and
+        the X11 library directory (e.g. `/usr/X11R6/lib`).
+
+`-no-pthread`::
         Do not attempt to use POSIX threads.
 
--with-pthread::
+`-with-pthread`::
         Attempt to use POSIX threads (this is the default).
 
--no-shared-libs::
-        Do not configure support for shared libraries
+`-no-shared-libs`::
+        Do not configure support for shared libraries.
 
--dldefs <cpp flags>::
--dllibs <flags and libraries>::
-        These options specify where to find the libraries for dynamic
-        linking (i.e. use of shared libraries).  "-dldefs" specifies
-        options for finding the header files, and "-dllibs" for finding
-        the C libraries.
+`-dldefs <cpp flags>`::
+`-dllibs <flags and libraries>`::
+        These options specify where to find the libraries for dynamic linking
+        (i.e. use of shared libraries).  `-dldefs` specifies options for finding
+        the header files, and `-dllibs` for finding the C libraries.
 
--as <assembler and options>::     (default: determined automatically)
+`-as <assembler and options>`::     (default: determined automatically)
         The assembler to use for assembling ocamlopt-generated code.
 
--aspp <assembler and options>::   (default: determined automatically)
-        The assembler to use for assembling the parts of the
-        run-time system manually written in assembly language.
-        This assembler must preprocess its input with the C preprocessor.
+`-aspp <assembler and options>`::   (default: determined automatically)
+        The assembler to use for assembling the parts of the run-time system
+        manually written in assembly language. This assembler must pre-process
+        its input with the C preprocessor.
 
--with-debug-runtime::
-        Compile and install the debug version of the runtimes, useful
-        for debugging C stubs and other low-level code.
+`-with-debug-runtime`::
+        Compile and install the debug version of the runtimes, useful for
+        debugging C stubs and other low-level code.
 
--with-instrumented-runtime::
-        Compile and install the instrumented version of the runtimes,
-        useful mainly for fine-tuning the GC. Works only on Linux.
+`-with-instrumented-runtime`::
+        Compile and install the instrumented version of the runtimes, useful
+        mainly for fine-tuning the GC.  Works only on Linux.
 
--verbose::
-        Verbose output of the configuration tests. Use it if the outcome
-        of configure is not what you were expecting.
+`-verbose`::
+        Verbose output of the configuration tests.  Use it if the outcome of
+        `configure` is not what you were expecting.
 
--no-debugger::
-        Do not build ocamldebug.
+`-no-debugger`::
+        Do not build `ocamldebug`.
 
--no-native-compiler::
+`-no-native-compiler`::
         Do not build the native compiler -- bytecode compilation only.
 
--no-ocamldoc::
-        Do not build ocamldoc.
+`-no-ocamldoc`::
+        Do not build `ocamldoc`.
 
--no-ocamlbuild::
-        Deprecated since 4.03.0, as ocamlbuild is now distributed separately
+`-no-ocamlbuild`::
+        Deprecated since 4.03.0, as `ocamlbuild` is now distributed separately
         from the compiler distribution.
 
--no-graph::
+`-no-graph`::
         Do not compile the Graphics library.
 
--partialld <linker and options>::  (default: determined automatically)
-        The linker and options to use for producing an object file
-        (rather than an executable) from several other object files.
+`-partialld <linker and options>`:: (default: determined automatically)
+        The linker and options to use for producing an object file (rather than
+        an executable) from several other object files.
 
--no-cfi::
+`-no-cfi`::
         Do not compile support for CFI directives.
 +
 Examples:
 
-* Standard installation in /usr/{bin,lib,man} instead of /usr/local:
+* Standard installation in `/usr/{bin,lib,man}` instead of `/usr/local`:
     ./configure -prefix /usr
 
 
-* Installation in /usr, man pages in section "l":
+* Installation in `/usr`, man pages in section "l":
 
     ./configure -bindir /usr/bin -libdir /usr/lib/ocaml -mandir /usr/man/manl
 +
@@ -150,32 +152,32 @@ or:
     ./configure -cc "gcc -m32" -as "as --32" -aspp "gcc -m32 -c" \
                 -host i386-linux -partialld "ld -r -melf_i386"
 
-* On a Linux x86-64 host, to build the run-time system in PIC mode,
-  no special options should be required---the libraries should be built
-  automatically.  The old instructions were:
+* On a Linux x86-64 host, to build the run-time system in PIC mode, no special
+  options should be required -- the libraries should be built automatically.
+  The old instructions were:
 
     ./configure -cc "gcc -fPIC" -aspp "gcc -c -fPIC"
 +
-On a 64-bit POWER architecture host running Linux, OCaml only operates
-  in a 32-bit environment.  If your system compiler is configured as 32-bit,
-  e.g. Red Hat 5.9, you don't need to do anything special.  If that is
-  not the case (e.g. Red Hat 6.4), then IBM's "Advance Toolchain" can
-  be used.  For example:
+On a 64-bit POWER architecture host running Linux, OCaml only operates in a
+  32-bit environment.  If your system compiler is configured as 32-bit, e.g.
+  Red Hat 5.9, you don't need to do anything special.  If that is not the case
+  (e.g. Red Hat 6.4), then IBM's "Advance Toolchain" can be used.  For example:
 
     export PATH=/opt/at7.0/bin:$PATH
     ./configure -cc "gcc -m32" -as "as -a32" -aspp "gcc -m32 -c" \
       -partialld "ld -r -m elf32ppc"
 
-* On a MacOSX 10.5/Intel Core 2 or MacOSX 10.5/PowerPC host,
-  to build a 64-bit version of OCaml:
+* On a OS X 10.5/Intel Core 2 or OS X 10.5/PowerPC host, to build a 64-bit
+  version of OCaml:
+
     ./configure -cc "gcc -m64"
 
-* On Intel Mac OS X, to build a 32-bit version of OCaml:
+* On OS X Intel, to build a 32-bit version of OCaml:
 
     ./configure -host "i386-apple-darwin13.2.0" -cc "gcc -arch i386 -m32" \
       -as "as -arch i386" -aspp "gcc -arch i386 -m32 -c"
 
-* For Sun Solaris with the "acc" compiler:
+* For Sun Solaris with the `acc` compiler:
 
     ./configure -cc "acc -fast" -libs "-lucb"
 
@@ -183,12 +185,12 @@ On a 64-bit POWER architecture host running Linux, OCaml only operates
 
     ./configure -cc "gcc -m32" -as "as -32" -aspp "gcc -m32 -c"
 
-* For AIX 4.3 with the IBM compiler xlc:
+* For AIX 4.3 with the IBM compiler `xlc`:
 
     ./configure -cc "xlc_r -D_AIX43 -Wl,-bexpall,-brtl -qmaxmem=8192"
 +
-If something goes wrong during the automatic configuration, or if the
-generated files cause errors later on, then look at the template files
+If something goes wrong during the automatic configuration, or if the generated
+files cause errors later on, then look at the template files:
 
         config/Makefile-templ
         config/m-templ.h
@@ -200,15 +202,15 @@ for guidance on how to edit the generated files by hand.
 
         make world
 +
-This builds the OCaml bytecode compiler for the first time.  This
-phase is fairly verbose; consider redirecting the output to a file:
+This builds the OCaml bytecode compiler for the first time.  This phase is
+fairly verbose; consider redirecting the output to a file:
 
         make world > log.world 2>&1     # in sh
         make world >& log.world         # in csh
 
-3. (Optional) To be sure everything works well, you can try to
-bootstrap the system --- that is, to recompile all OCaml sources with
-the newly created compiler. From the top directory, do:
+3. (Optional) To be sure everything works well, you can try to bootstrap the
+   system -- that is, to recompile all OCaml sources with the newly created
+   compiler. From the top directory, do:
 
         make bootstrap
 +
@@ -217,18 +219,17 @@ or, better:
         make bootstrap > log.bootstrap 2>&1     # in sh
         make bootstrap >& log.bootstrap         # in csh
 +
-The "make bootstrap" checks that the bytecode programs compiled with
-the new compiler are identical to the bytecode programs compiled with
-the old compiler. If this is the case, you can be pretty sure the
-system has been correctly compiled. Otherwise, this does not
-necessarily mean something went wrong. The best thing to do is to try
-a second bootstrapping phase: just do "make bootstrap" again.  It will
-either crash almost immediately, or re-re-compile everything correctly
-and reach the fixpoint.
-
-4. If your platform is supported by the native-code compiler (as
-reported during the autoconfiguration), you can now build the
-native-code compiler. From the top directory, do:
+The `make bootstrap` checks that the bytecode programs compiled with the new
+compiler are identical to the bytecode programs compiled with the old compiler.
+If this is the case, you can be pretty sure the system has been correctly
+compiled. Otherwise, this does not necessarily mean something went wrong.  The
+best thing to do is to try a second bootstrapping phase: just do
+`make bootstrap` again.  It will either crash almost immediately, or
+re-re-compile everything correctly and reach the fix-point.
+
+4. If your platform is supported by the native-code compiler (as reported during
+   the auto-configuration), you can now build the native-code compiler.  From
+   the top directory, do:
 
         make opt
 +
@@ -237,62 +238,62 @@ or:
         make opt > log.opt 2>&1     # in sh
         make opt >& log.opt         # in csh
 
-5. anchor:step-5[] Compile fast versions of the OCaml compilers, by
-compiling them with the native-code compiler (you have only compiled
-them to bytecode so far).  Just do:
+5. anchor:step-5[] Compile fast versions of the OCaml compilers, by compiling
+   them with the native-code compiler (you will have only compiled them to
+   bytecode in steps 2-4).  Just do:
 
         make opt.opt
 +
-Later, you can compile your programs to bytecode using ocamlc.opt
-instead of ocamlc, and to native-code using ocamlopt.opt instead of
-ocamlopt.  The ".opt" compilers should run faster than the normal
-compilers, especially on large input files, but they may take longer
-to start due to increased code size.  If compilation times are an issue on
-your programs, try the ".opt" compilers to see if they make a
-significant difference.
+Later, you can compile your programs to bytecode using ocamlc.opt instead of
+ocamlc, and to native-code using ocamlopt.opt instead of ocamlopt.  The ".opt"
+compilers should run faster than the normal compilers, especially on large input
+files, but they may take longer to start due to increased code size.  If
+compilation times are an issue on your programs, try the ".opt" compilers to see
+if they make a significant difference.
 +
 An alternative, and faster approach to steps 2 to 5 is
 
         make world.opt          # to build using native-code compilers
 +
-The result is equivalent to "make world opt opt.opt", but this may
-fail if anything goes wrong in native-code generation.
-
-6. You can now install the OCaml system. This will create the
-following commands (in the binary directory selected during
-autoconfiguration):
-
-        ocamlc           the batch bytecode compiler
-        ocamlopt         the batch native-code compiler (if supported)
-        ocamlrun         the runtime system for the bytecode compiler
-        ocamlyacc        the parser generator
-        ocamllex         the lexer generator
-        ocaml            the interactive, toplevel-based system
-        ocamlmktop       a tool to make toplevel systems that integrate
-                         user-defined C primitives and OCaml code
-        ocamldebug       the source-level replay debugger
-        ocamldep         generator of "make" dependencies for OCaml sources
-        ocamldoc         documentation generator
-        ocamlprof        execution count profiler
-        ocamlcp          the bytecode compiler in profiling mode
-+
-and also, if you built them during <<step-5,step 5>>,
+The result is equivalent to `make world opt opt.opt`, but this may fail if
+anything goes wrong in native-code generation.
 
-        ocamlc.opt       the batch bytecode compiler compiled with ocamlopt
-        ocamlopt.opt     the batch native-code compiler compiled with ocamlopt
-        ocamllex.opt     the lexer generator compiled with ocamlopt
+6. You can now install the OCaml system. This will create the following commands
+   (in the binary directory selected during autoconfiguration):
++
+[width="70%",frame="topbot",cols="25%,75%"]
+|===============================================================================
+| `ocamlc`     | the batch bytecode compiler
+| `ocamlopt`   | the batch native-code compiler (if supported)
+| `ocamlrun`   | the runtime system for the bytecode compiler
+| `ocamlyacc`  | the parser generator
+| `ocamllex`   | the lexer generator
+| `ocaml`      | the interactive, toplevel-based system
+| `ocamlmktop` | a tool to make toplevel systems that integrate user-defined C
+                 primitives and OCaml code
+| `ocamldebug` | the source-level replay debugger
+| `ocamldep`   | generator of "make" dependencies for OCaml sources
+| `ocamldoc`   | the documentation generator
+| `ocamlprof`  | the execution count profiler
+| `ocamlcp`    | the bytecode compiler in profiling mode
+|===============================================================================
++
+and also, if you built them during <<step-5,step 5>>: `ocamlc.opt`,
+`ocamlopt.opt`, `ocamllex.opt`, `ocamldep.opt` and `ocamldoc.opt`
 +
 From the top directory, become superuser and do:
 
         umask 022       # make sure to give read & execute permission to all
         make install
 
-7. Installation is complete. Time to clean up. From the toplevel
-directory, do "make clean".
+7. Installation is complete. Time to clean up. From the toplevel directory,
+   do:
+
+        make clean
 
-8. (Optional) The emacs/ subdirectory contains Emacs-Lisp files for an
-OCaml editing mode and an interface for the debugger.  To install
-these files, change to the emacs/ subdirectory and do
+8. (Optional) The `emacs/` subdirectory contains Emacs-Lisp files for an OCaml
+   editing mode and an interface for the debugger.  To install these files,
+   change to the `emacs/` subdirectory and do:
 
         make EMACSDIR=<directory where to install the files> install
 +
@@ -301,71 +302,65 @@ or
         make install
 +
 In the latter case, the destination directory defaults to the
-"site-lisp" directory of your Emacs installation.
+`site-lisp` directory of your Emacs installation.
 
-9. After installation, do *not* strip the ocamldebug and ocamlbrowser
-executables.  (These are mixed-mode executables, containing both
-compiled C code and OCaml bytecode; stripping erases the bytecode!)
-Other executables such as ocamlrun can safely be stripped.
+9. After installation, do *not* strip the `ocamldebug` and `ocamlbrowser`
+   executables. These are mixed-mode executables (containing both compiled C
+   code and OCaml bytecode) and stripping erases the bytecode!  Other
+   executables such as `ocamlrun` can safely be stripped.
 
 == IF SOMETHING GOES WRONG
 
-Read the "common problems" and "machine-specific hints" section at the
-end of this file.
+Read the "common problems" and "machine-specific hints" section at the end of
+this file.
 
-Check the files m.h and s.h in config/. Wrong endianness or alignment
-constraints in m.h will immediately crash the bytecode interpreter.
+Check the files `m.h` and `s.h` in `config/`. Wrong endian-ness or alignment
+constraints in `m.h` will immediately crash the bytecode interpreter.
 
-If you get a "segmentation violation" signal, check the limits on the
-stack size and data segment size (type "limit" under csh or
-"ulimit -a" under bash). Make sure the limit on the stack size is
-at least 4M.
+If you get a "segmentation violation" signal, check the limits on the stack size
+and data segment size (type `limit` under csh or `ulimit -a` under bash). Make
+sure the limit on the stack size is at least 4M.
 
-Try recompiling the runtime system with optimizations turned off
-(change CFLAGS in byterun/Makefile and asmrun/Makefile).
-The runtime system contains some complex, atypical pieces of C code
-that can uncover bugs in optimizing compilers. Alternatively, try
-another C compiler (e.g. gcc instead of the vendor-supplied cc).
+Try recompiling the runtime system with optimizations turned off (change
+`CFLAGS` in `byterun/Makefile` and `asmrun/Makefile`). The runtime system
+contains some complex, atypical pieces of C code which can uncover bugs in
+optimizing compilers.  Alternatively, try another C compiler (e.g. `gcc` instead
+of the vendor-supplied `cc`).
 
-You can also build a debug version of the runtime system. Go to the
-byterun/ directory and do "make ocamlrund". Then, copy ocamlrund to
-'../boot/ocamlrun', and try again. This version of the runtime system
-contains lots of assertions and sanity checks that could help you
-pinpoint the problem.
+You can also build a debug version of the runtime system. Go to the `byterun/`
+directory and do `make ocamlrund`.  Then, copy `ocamlrund` to
+`../boot/ocamlrun`, and try again.  This version of the runtime system contains
+lots of assertions and sanity checks that could help you pinpoint the problem.
 
 
 == COMMON PROBLEMS
 
-* The Makefiles do not support parallel make (e.g. make -j2).
-Fix: do not pass the -j option to make, and be patient.
-
-* The Makefiles use the "include" directive, which is not supported by
-all versions of make. Use GNU make if this is a problem.
+* The Makefiles use the `include` directive, which is not supported by all
+  versions of make. Use GNU Make if this is a problem.
 
-* Solaris make mishandles a space in our Makefiles, so you have to use GNU
-make to build on Solaris.
+* Solaris make mishandles a space in our Makefiles, so you have to use GNU make
+  to build on Solaris.
 
-* The Makefiles assume that make executes commands by calling /bin/sh. They
-won't work if /bin/csh is called instead. You may have to unset the SHELL
-environment variable, or set it to /bin/sh.
+* The Makefiles assume that make executes commands by calling `/bin/sh`. They
+  won't work if `/bin/csh` is called instead.  You may have to unset the `SHELL`
+  environment variable, or set it to `/bin/sh`.
 
-* On some systems, localization causes build problems.  You should
-try to set the C locale (export LC_ALL=C) before compiling if you have
-strange errors while compiling OCaml.
+* On some systems, localization causes build problems.  You should try to set
+  the C locale (`export LC_ALL=C`) before compiling if you have strange errors
+  while compiling OCaml.
 
-* gcc 2.7.2.1 generates incorrect code for the runtime system in -O mode
-on some Intel x86 platforms (e.g. Linux RedHat 4.1 and 4.2).
-If this causes a problem, the solution is to upgrade to 2.7.2.3 or above.
+* GCC 2.7.2.1 generates incorrect code for the runtime system in `-O` mode on
+  some Intel x86 platforms (e.g. Linux RedHat 4.1 and 4.2). If this causes a
+  problem, the solution is to upgrade to 2.7.2.3 or above.
 
-* Some versions of gcc 2.96 for the Intel x86 (as found in RedHat 7.2,
-Mandrake 8.0 and Mandrake 8.1) generates incorrect code for the runtime
-system.  The "configure" script tries to work around this problem.
+* Some versions of GCC 2.96 for the Intel x86 (as found in RedHat 7.2,
+  Mandrake 8.0 and Mandrake 8.1) generate incorrect code for the runtime system.
+  The `configure` script tries to work around this problem.
 
-* On HP 9000/700 machines under HP/UX 9.  Some versions of cc are
-unable to compile correctly the runtime system (wrong code is
-generated for (x - y) where x is a pointer and y an integer).
-Fix: use gcc.
+* On HP 9000/700 machines under HP/UX 9, some versions of `cc` are unable to
+  compile correctly the runtime system (wrong code is generated for `(x - y)`
+  where `x` is a pointer and `y` an integer). Fix: use `gcc`.
 
-* Under MacOS X 10.6, with XCode 4.0.2, the configure script mistakenly
-detects support for CFI directives in the assembler.
-Fix: give the "-no-cfi" option to configure.
+* Under OS X 10.6, with XCode 4.0.2, the `configure` script mistakenly detects
+  support for CFI directives in the assembler. Fix: give the `-no-cfi` option to
+  `configure`.
diff --git a/README.adoc b/README.adoc
index 3219e25cf8..73e477a89b 100644
--- a/README.adoc
+++ b/README.adoc
@@ -23,9 +23,9 @@ native-code compiler currently runs on the following platforms:
 
 Tier 1 (actively used and maintained by the core OCaml team):
 
-AMD64 (Opteron)::    Linux, MacOS X, MS Windows
-IA32 (Pentium)::     Linux, FreeBSD, MacOS X, MS Windows
-PowerPC::            Linux, MacOS X
+AMD64 (Opteron)::    Linux, OS X, MS Windows
+IA32 (Pentium)::     Linux, FreeBSD, OS X, MS Windows
+PowerPC::            Linux, OS X
 ARM::                Linux
 
 Tier 2 (maintained when possible, with help from users):
@@ -82,8 +82,9 @@ conditions stated in file LICENSE.
 
 == INSTALLATION
 
-See the file INSTALL for installation instructions on Unix, Linux and
-MacOS X machines.  For MS Windows, see link:README.win32.adoc[].
+See the file INSTALL for installation instructions on machines running Unix,
+Linux, OS X and Cygwin.  For native Microsoft Windows, see
+link:README.win32.adoc[].
 
 == DOCUMENTATION
 
diff --git a/README.win32.adoc b/README.win32.adoc
index 30316aaccd..f8b65eaf4a 100644
--- a/README.win32.adoc
+++ b/README.win32.adoc
@@ -1,471 +1,329 @@
-= Release notes on the MS Windows ports of OCaml =
+= Release notes for the Microsoft Windows ports of OCaml =
 :toc: macro
 
-There are no less than five ports of OCaml for MS Windows available:
+There are no fewer than three ports of OCaml for Microsoft Windows, each
+available in 32 and 64-bit versions:
 
-  - a native Win32 port, built with the Microsoft development tools;
-  - a native Win32 port, built with the 32-bit version of the gcc
-    compiler from the mingw-w64 project, packaged in Cygwin
-    (under the name mingw64-i686);
-  - a native Win64 port, built with the 64-bit version of the gcc
-    compiler from the mingw-w64 project, packaged in Cygwin
-    (under the name mingw64-x86_64);
-  - a port consisting of the Unix sources compiled under the Cygwin
-    Unix-like environment for Windows (both 32-bit and 64-bit).
-  - a native Win64 port (64-bit Windows), built with the Microsoft
-    development tools.
+  - native Windows, built with the Microsoft C/C++ Optimizing Compiler
+  - native Windows, built using the Mingw-w64 version of GCC
+  - Cygwin (http://www.cygwin.com[www.cygwin.com])
 
 Here is a summary of the main differences between these ports:
 
 |=====
-|           | Native MS       | Native MinGW        | Cygwin
-|64 bits?   | Win32 or Win64  | Win32 or Win64      | Win32 or Win64
+|                                        | Native Microsoft       | Native Mingw-w64 | Cygwin
 4+^| Third-party software required
-| for base bytecode system              | none          | none          | none
-| for ocamlc -custom                    | MSVC          | Cygwin        | Cygwin
-| for native-code generation            | MSVC+MASM     | Cygwin        | Cygwin
-| Speed of bytecode interpreter         | 70%           | 100%          | 100%
-| Replay debugger                       | yes <<tb2,(**)>>   | yes <<tb2,(**)>> | yes
-| The Unix library                      | partial       | partial       | full
-| The Threads library                   | yes           | yes           | yes
-| The Graphics library                  | yes           | yes           | no
-| Restrictions on generated executables?  | none        | none          | yes <<tb1,(*)>>
+| for base bytecode system               | none                   | none             | none
+| for `ocamlc -custom`                     | Microsoft Visual C++   | Cygwin           | Cygwin
+| for native-code generation             | Microsoft Visual C++   | Cygwin           | Cygwin
+4+^| Features
+| Speed of bytecode interpreter          | 70%                    | 100%             | 100%
+| Replay debugger                        | yes <<tb2,(**)>>       | yes <<tb2,(**)>> | yes
+| The Unix library                       | partial                | partial          | full
+| The Threads library                    | yes                    | yes              | yes
+| The Graphics library                   | yes                    | yes              | no
+| Restrictions on generated executables? | none                   | none             | yes <<tb1,(*)>>
 |=====
 
 [[tb1]]
-(*):: Cygwin-generated .exe files refer to a DLL that is distributed under
-the GPL.  Thus, these .exe files can only be distributed under a license
-that is compatible with the GPL.  Executables generated by MSVC or by
-MinGW have no such restrictions.
+(*):: Cygwin-generated `.exe` files refer to a DLL that is distributed under the
+GPL.  Thus, these `.exe` files can only be distributed under a license that is
+compatible with the GPL.  Executables generated by Microsoft Visual C++ or
+Mingw-w64 have no such restrictions.
 
 [[tb2]]
 (**):: The debugger is supported but the "replay" functions are not enabled.
 Other functions are available (step, goto, run...).
 
-The remainder of this document gives more information on each port.
+Cygwin aims to provide a Unix-like environment on Windows, and the build
+procedure for it is the same as for other flavours of Unix.  See
+link:INSTALL.adoc[] for full instructions.
 
-toc::[]
-
-== The native Win32 port built with Microsoft Windows SDK
-
-=== REQUIREMENTS
-
-This port runs under MS Windows 7 (32 and 64 bits), Vista, XP, and 2000.
-
-The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
-runs without any additional tools.
+The native ports require Windows XP or later and naturally the 64-bit versions
+need a 64-bit edition of Windows (note that this is both to run *and* build).
 
-The native-code compiler (ocamlopt) requires the Microsoft Windows SDK
-(item <<tps1,[1]>>) and the flexdll tool (item <<tps2,[2]>>).
+The two native Windows ports have to be built differently, and the remainder of
+this document gives more information.
 
-Statically linking OCaml bytecode with C code (ocamlc -custom) also requires
-items <<tps1,[1]>> and <<tps2,[2]>>.
-
-=== INSTALLATION
-
-The binary distribution is a self-installing executable archive.
-Just run it and it should install OCaml automatically.
+toc::[]
 
-=== THIRD-PARTY SOFTWARE
+== PREREQUISITES
 
-[[tps1]]
-[1]:: Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 Service Pack 1.
-    Can be downloaded for free from
-    http://www.microsoft.com/downloads/en/default.aspx
-    under the name "Microsoft Windows 7 SDK".
+All the Windows ports require a Unix-like build environment.  Although other
+methods are available, the officially supported environment for doing this is
+32-bit (x86) Cygwin.
 
-[[tps2]]
-[2]:: flexdll version 0.31 or later.
-    Can be downloaded from http://alain.frisch.fr/flexdll.html
+Only the `make` Cygwin package is required. `diffutils` is required if you wish
+to be able to run the test suite.
 
-=== RECOMPILATION FROM THE SOURCES
+Unless you are also compiling the Cygwin port of OCaml, you should not install
+the `gcc-core` or `flexdll` packages. If you do, care may be required to ensure
+that a particular build is using the correct installation of `flexlink`.
 
-The command-line tools can be recompiled from the Unix source
-distribution (ocaml-X.YY.Z.tar.gz), which also contains the files modified
-for Windows.
+[[bmflex]]
+In addition to Cygwin, FlexDLL must also be installed, which is available from
+http://alain.frisch.fr/flexdll.html. A binary distribution is available;
+instructions on how to build FlexDLL from sources, including how to bootstrap
+FlexDLL and OCaml are given <<seflexdll,later in this document>>.  Unless you
+bootstrap FlexDLL, you will need to ensure that the directory to which you
+install FlexDLL is included in your `PATH` environment variable.
 
-You will need the following software components to perform the recompilation:
+The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...) of all three
+ports runs without any additional tools.
 
-- Windows NT, 2000, XP, Vista, or 7 (32 or 64 bits).
-- Items <<tps1,[1]>> and <<tps2,[2]>> from the list of recommended software
-  above.
-- The Cygwin port of GNU tools, available from http://www.cygwin.com/
-  Install at least the following packages (and their dependencies):
-  diffutils, dos2unix, gcc-core, make, ncurses.
+== Microsoft Visual C/C++ Ports
 
-First, you need to set up your cygwin environment for using the MS
-tools.  The following assumes that you have installed <<tps1,[1]>>,
-<<tps2,[2]>>, and [3] in their default directories.  If this is not
-the case, you will need to adjust the paths accordingly.
+=== REQUIREMENTS
 
-. Open a Windows Command Prompt and enter the following command:
+The native-code compiler (`ocamlopt`) and static linking of OCaml bytecode with
+C code (`ocamlc -custom`) require a Microsoft Visual C/C++ Compiler and the
+`flexlink` tool (see <<bmflex,above>>).
 
-    set PFPATH=C:\Program Files
+Any edition (including Express/Community editions) of Microsoft Visual Studio
+2005 or later may be used to provide the required Windows headers and the C
+compiler. Additionally, some older Microsoft Windows SDKs include the
+Visual C/C++ Compiler.
 
-. If you are compiling on the 64-bit version of Windows 7, enter the
-  following instead:
+|=====
+|                    | `cl` Version | Express                 | SDK
+| Visual Studio 2005 | 14.00.x.x    | 32-bit only <<vs1,(*)>> |
+| Visual Studio 2008 | 15.00.x.x    | 32-bit only             | Windows SDK 7.0 also provides 32/64-bit compilers
+| Visual Studio 2010 | 16.00.x.x    | 32-bit only             | Windows SDK 7.1 also provides 32/64-bit compilers
+| Visual Studio 2012 | 17.00.x.x    | 32/64-bit               |
+| Visual Studio 2013 | 18.00.x.x    | 32/64-bit               |
+| Visual Studio 2015 | 19.00.x.x    | 32/64-bit               |
+|=====
 
-    set PFPATH=C:\Program Files (x86)
+[[vs1]]
+(*):: Visual C++ 2005 Express Edition does not provide an assembler; this can be
+      downloaded separately from
+      https://www.microsoft.com/en-gb/download/details.aspx?id=12654
 
-. Then enter the following commands:
+=== COMPILATION FROM THE SOURCES
 
-    cd "%PFPATH%\Microsoft Visual Studio 9.0\VC\bin"
-    set FLEXDLLDIR=%PFPATH%\flexdll
-    vcvars32
-    echo VCPATH="`cygpath -p '%Path%'`" >C:\cygwin\tmp\msenv
-    echo LIB="%LIB%" >>C:\cygwin\tmp\msenv
-    echo LIBPATH="%LIBPATH%" >>C:\cygwin\tmp\msenv
-    echo INCLUDE="%INCLUDE%;%FLEXDLLDIR%" >>C:\cygwin\tmp\msenv
-    echo FLPATH="`cygpath '%FLEXDLLDIR%'`" >>C:\cygwin\tmp\msenv
-    echo PATH="$VCPATH:$FLPATH:$PATH" >>C:\cygwin\tmp\msenv
-    echo export PATH LIB LIBPATH INCLUDE >>C:\cygwin\tmp\msenv
-    echo export OCAMLBUILD_FIND=/usr/bin/find >>C:\cygwin\tmp\msenv
+The command-line tools must be compiled from the Unix source distribution
+(`ocaml-X.YY.Z.tar.gz`), which also contains the files modified for Windows.
 
-. Open a Cygwin shell and enter the following commands:
+Microsoft Visual C/C++ is designed to be used from special developer mode
+Command Prompts which set the environment variables for the required compiler.
+There are multiple ways of setting up your environment ready for their use.  The
+simplest is to start the appropriate command prompt shortcut from the program
+group of the compiler you have installed.
 
-    tr -d '\r' </tmp/msenv >.msenv32
-    echo '. $HOME/.msenv32' >>.bashrc
+The details differ depending on whether you are using a Windows SDK to provide
+the compiler or Microsoft Visual Studio itself.
 
-Now, close the Command Prompt and the shell and you're set up for
-using the MS tools under Cygwin.
+For the Windows SDK, there is only one command prompt called "CMD Shell" in
+versions 6.1 and 7.0 and "Windows SDK 7.1 Command Prompt" in version 7.1. This
+launches a Command Prompt which will usually select a `DEBUG` build environment
+for the operating system that you are running. You should then run:
 
+  SetEnv /Release /x86
 
-To recompile OCaml, start a new Cygwin shell and change to the top-level
-directory of the OCaml distribution.  Then, do
+for 32-bit or:
 
-        cp config/m-nt.h config/m.h
-        cp config/s-nt.h config/s.h
-        cp config/Makefile.msvc config/Makefile
+  SetEnv /Release /x64
 
-Then, edit config/Makefile as needed, following the comments in this file.
-Normally, the only variable that need to be changed is
+for 64-bit. For Visual Studio 2005-2013, you need to use one of the shortcuts in
+the "Visual Studio Tools" program group under the main program group for the
+version of Visual Studio you installed. For Visual Studio 2015, you need to use
+the shortcuts in the "Windows Desktop Command Prompts" group under the
+"Visual Studio Tools" group.
 
-        PREFIX      where to install everything
+Unlike `SetEnv` for the Windows SDK, the architecture is selected by using a
+different shortcut, rather than by running a command.
 
-Finally, use `make -f Makefile.nt` to build the system, e.g.
+For Visual Studio 2005-2010, excluding version-specific prefixes, these are
+named "Command Prompt" for 32-bit and "x64 Cross Tools Command Prompt" or
+"x64 Win64 Command Prompt" for 64-bit. It does not matter whether you use a
+"Cross Tools" or "Win64" version for x64, this simply refers to whether the
+compiler itself is a 32-bit or 64-bit program; both produce 64-bit output and
+work with OCaml.
 
-        make -f Makefile.nt world
-        make -f Makefile.nt bootstrap
-        make -f Makefile.nt opt
-        make -f Makefile.nt opt.opt
-        make -f Makefile.nt install
+For Visual Studio 2012 and 2013, both x86 and x64 Command Prompt shortcuts
+indicate if they are the "Native Tools" or "Cross Tools" versions. Visual Studio
+2015 makes the shortcuts even clearer by including the full name of the
+architecture.
 
-=== NOTES
+You cannot at present use a cross-compiler to compile 64-bit OCaml on 32-bit
+Windows.
 
-* The VC++ compiler does not implement "computed gotos", and therefore
-generates inefficient code for 'byterun/interp.c'. Consequently, the
-performance of bytecode programs is about 2/3 of that obtained under
-Unix/GCC or Cygwin or Mingw on similar hardware.
+Once you have started a Command Prompt, you can verify that you have the
+compiler you are expecting simply by running:
 
-* Libraries available in this port: `num`, `str`, `threads`, `graphics`,
-and large parts of `unix`.
+  cl
+  Microsoft (R) C/C++ Optimizing Compiler Version 19.00.23506 for x86
+  ...
 
-* The replay debugger is partially supported (no reverse execution).
+You then need to start Cygwin from this Command Prompt.  Assuming you have
+installed it to its default location of `C:\cygwin`, simply run:
 
-=== CREDITS
+  C:\cygwin\bin\mintty -
 
-The initial port of Caml Special Light (the ancestor of OCaml) to
-Windows NT was done by Kevin Gallo at Microsoft Research, who kindly
-contributed his changes to the OCaml project.
+(note the space and hyphen at the end of the command).
 
+This should open a terminal window and start bash.  You should be able to run
+`cl` from this.  You can now change to the top-level directory of the directory
+of the OCaml distribution.
 
-== The native Win32 and Win64 ports built with Mingw
+The Microsoft Linker is provided by a command called `link` which unfortunately
+conflicts with a Cygwin command of the same name.  It is therefore necessary to
+ensure that the directory containing the Microsoft C/C++ Compiler appears at
+the beginning of `PATH`, before Cygwin's `/usr/bin`.  You can automate this from
+the top-level of the OCaml distribution by running:
 
-=== REQUIREMENTS
+  eval $(tools/msvs-promote-path)
 
-Those ports run under MS Windows Seven, Vista, XP, and 2000.
+If you forget to do this, `make -f Makefile.nt world` will fail relatively
+quickly as it will be unable to link `ocamlrun`.
 
-The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
-runs without any additional tools.
+Now run:
 
-The native-code compiler (ocamlopt), as well as static linking of
-OCaml bytecode with C code (ocamlc -custom), require
-the Cygwin development tools, available at
-        http://www.cygwin.com/
-and the flexdll tool, available at
-        http://alain.frisch.fr/flexdll.html
-You will need to install at least the following Cygwin packages for
-the 32-bit flavor (use the Setup tool from Cygwin):
+        cp config/m-nt.h config/m.h
+        cp config/s-nt.h config/s.h
 
- mingw64-i686-binutils
- mingw64-i686-gcc-core
- mingw64-i686-runtime
+followed by:
 
-and the following packages for the 64-bit:
+        cp config/Makefile.msvc config/Makefile
 
- mingw64-x86_64-binutils
- mingw64-x86_64-gcc-core
- mingw64-x86_64-runtime
+for 32-bit, or:
 
-=== NOTES
+        cp config/Makefile.msvc64 config/Makefile
 
-  - Do not use the Cygwin version of flexdll for this port.
+for 64-bit. Then, edit `config/Makefile` as needed, following the comments in
+this file. Normally, the only variable that needs to be changed is `PREFIX`,
+which indicates where to install everything.
 
-  - There is another 32-bit gcc compiler, from the MinGW.org
-    project, packaged in Cygwin under the name mingw-gcc.
-    It is not currently supported by flexdll and OCaml.
+Finally, use `make -f Makefile.nt` to build the system, e.g.
 
-  - The standard gcc compiler shipped with Cygwin used to
-    support a `-mno-cygwin` option, which turned the compiler
-    into a mingw compiler. This option was used
-    by previous versions of flexdll and OCaml, but it is no
-    longer available in recent version, hence the switch
-    to another toolchain packaged in Cygwin.
+        make -f Makefile.nt world bootstrap opt opt.opt install
 
-  - The standalone mingw toolchain from the MinGW-w64 project
-    (http://mingw-w64.org/) is not supported. Please use the
-    version packaged in Cygwin instead.
+After installing, it is not necessary to keep the Cygwin installation (although
+you may require it to build additional third party libraries and tools).  You
+will need to use `ocamlopt` (or `ocamlc -custom`) from the same Visual Studio or
+Windows SDK Command Prompt as you compiled OCaml from, or `ocamlopt` will not
+be able to find `cl`.
 
-=== INSTALLATION
+If you wish to use `ocamlopt` from Cygwin's bash on a regular basis, you may
+like to copy the `tools/msvs-promote-path` script and add the `eval` line to
+your `~/.bashrc` file.
 
-The binary distribution is a self-installing executable archive.
-Just run it and it should install OCaml automatically.
+* The Microsoft Visual C/C++ compiler does not implement "computed gotos", and
+  therefore generates inefficient code for `byterun/interp.c`.  Consequently,
+  the performance of bytecode programs is about 2/3 of that obtained under
+  Unix/GCC,  Cygwin or Mingw-w64 on similar hardware.
 
+* Libraries available in this port: `bigarray`, `dynlink`, `graphics`, `num`,
+  `str`, `threads`, and large parts of `unix`.
 
-=== RECOMPILATION FROM THE SOURCES
+* The replay debugger is partially supported (no reverse execution).
 
-You will need the following software components to perform the recompilation:
-- Windows NT, 2000, XP, Vista, or Seven.
-- Cygwin: http://cygwin.com/
-  Install at least the following packages (and their dependencies, as
-  computed by Cygwin's setup.exe):
+=== CREDITS
 
-  * For both flavor of OCaml (32-bit and 64-bit):
+The initial port of Caml Special Light (the ancestor of OCaml) to Windows NT
+was done by Kevin Gallo at Microsoft Research, who kindly contributed his
+changes to the OCaml project.
 
-     diffutils
-     make
-     ncurses
+== Mingw-w64 Ports
 
-  * For the 32 bit flavor of OCaml:
+=== REQUIREMENTS
 
-     mingw64-i686-binutils
-     mingw64-i686-gcc-core
-     mingw64-i686-runtime
+The native-code compiler (`ocamlopt`) and static linking of OCaml bytecode with
+C code (`ocamlc -custom`) require the appropriate Mingw-w64 gcc and the
+`flexlink` tool (see <<bmflex,above>>). Mingw-w64 gcc is provided by the
+`mingw64-i686-gcc-core` package for 32-bit and the `mingw64-x86_64-gcc-core`
+package for 64-bit.
 
-  * For the 64 bit flavor of OCaml:
+  - Do not try to use the Cygwin version of flexdll for this port.
 
-     mingw64-x86_64-binutils
-     mingw64-x86_64-gcc-core
-     mingw64-x86_64-runtime
+  - The standalone mingw toolchain from the Mingw-w64 project
+    (http://mingw-w64.org/) is not supported. Please use the version packaged in
+    Cygwin instead.
 
-- The flexdll tool (see above).  Do not forget to add the flexdll directory
-  to your PATH
+=== COMPILATION FROM THE SOURCES
 
-The standalone mingw toolchain from the MinGW-w64 project
-(http://mingw-w64.org/) is not supported.  Please use the
-version packaged in Cygwin instead.
+The command-line tools must be compiled from the Unix source distribution
+(`ocaml-X.YY.Z.tar.gz`), which also contains the files modified for Windows.
 
-Start a new Cygwin shell and unpack the source distribution
-(ocaml-X.YY.Z.tar.gz) with `tar xzf`.  Change to the top-level
-directory of the OCaml distribution.  Then, do
+Now run:
 
         cp config/m-nt.h config/m.h
         cp config/s-nt.h config/s.h
 
-For a 32 bit OCaml:
+followed by:
 
         cp config/Makefile.mingw config/Makefile
 
-For a 64 bit OCaml:
+for 32-bit, or:
 
         cp config/Makefile.mingw64 config/Makefile
 
-Then, edit config/Makefile as needed, following the comments in this file.
-Normally, the only variable that need to be changed is
-
-        PREFIX      where to install everything
+for 64-bit. Then, edit `config/Makefile` as needed, following the comments in
+this file. Normally, the only variable that needs to be changed is `PREFIX`,
+which indicates where to install everything.
 
 Finally, use `make -f Makefile.nt` to build the system, e.g.
 
-        make -f Makefile.nt world
-        make -f Makefile.nt bootstrap
-        make -f Makefile.nt opt
-        make -f Makefile.nt opt.opt
-        make -f Makefile.nt install
-
+        make -f Makefile.nt world bootstrap opt opt.opt install
 
-=== NOTES
+After installing, you will need to ensure that `ocamlopt` (or `ocamlc -custom`)
+can access the C compiler.  You can do this either by using OCaml from Cygwin's
+bash or by adding Cygwin's bin directory (e.g. `C:\cygwin\bin`) to your `PATH`.
 
-* Libraries available in this port: `num`, `str`, `threads`, `graphics`,
-  and large parts of `unix`.
+* Libraries available in this port: `bigarray`, `dynlink`, `graphics`, `num`,
+  `str`, `threads`, and large parts of `unix`.
 
 * The replay debugger is partially supported (no reverse execution).
 
-* The default Makefile.mingw and Makefile.mingw64 pass `-static-libgcc` to
-  the linker.
-  For more information on this topic:
+* The default `config/Makefile.mingw` and `config/Makefile.mingw64` pass
+  `-static-libgcc` to the linker. For more information on this topic:
 
   - http://gcc.gnu.org/onlinedocs/gcc-4.9.1/gcc/Link-Options.html#Link-Options
   - http://caml.inria.fr/mantis/view.php?id=6411
 
-== The Cygwin port of OCaml
-
-=== REQUIREMENTS
-
-This port requires the Cygwin environment from Cygnus/RedHat, which
-is freely available at:
-
-http://www.cygwin.com/
-
-It also requires the flexdll tool, available at:
-
-http://alain.frisch.fr/flexdll.html
-
-This port runs under all versions of MS Windows supported by Cygwin.
-
-=== INSTALLATION
-
-We do not distribute binaries for this port, but they can be found
-in the Cygwin distribution (use the Setup tool from Cygwin and select
-the OCaml packages).  Alternatively, recompile from the source distribution.
-
-
-=== RECOMPILATION FROM THE SOURCES
-
-Before starting, make sure that the gcc version installed by cygwin
-is not 4.5.3 (it has a bug that affects OCaml).  If needed, use cygwin's
-setup.exe to downgrade to 4.3.4.
-
-You will need to recompile (and install) flexdll from source with
-Cygwin's C compiler because the official binary version of flexdll
-doesn't handle Cygwin's symbolic links and sometimes fails to
-launch the C compiler.
-
-In order to recompile flexdll, you first need to configure, compile,
-and install OCaml without flexdll support (configure with options
--no-shared-libs), then modify the flexdll Makefile to change
-line 51 from:
-
-  LINKFLAGS = -ccopt "-link version_res.o"
-
-to:
-
-  LINKFLAGS = -cclib version_res.o
-
-Then `make CHAINS=cygwin` and add the flexdll directory to your PATH.
-Make sure to add it before '/usr/bin' or you will get cygwin's flexlink.
-
-Then, in OCaml's source directory, type:
-
-  make clean
-  make distclean
-
-and follow the instructions for Unix machines given in the file INSTALL.
-
-
-=== NOTES
-
-- There is a problem with cygwin's port of gcc version 4.5.3.  You should
-  use cygwin's setup program to downgrade to 4.3.4 before compiling OCaml.
-- The replay debugger is fully supported.
-- In order to use the "graph" library, you will need to use Cygwin's
-  setup.exe to install the xinit, and libX11-devel packages before compiling
-  OCaml.
-
-== The native Win64 port built with Microsoft Windows SDK
-
-=== REQUIREMENTS
-
-This port runs under MS Windows XP 64, Windows Server 64, and
-Windows 7 64 on Intel64/AMD64 machines.
-
-The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
-runs without any additional tools.
-
-Statically linking OCaml bytecode with C code (ocamlc -custom) requires the
-Microsoft Platform SDK compiler (item <<tps-native1,[1]>> in the section
-"third-party software" below) and the flexdll tool (item <<tps-native2,[2]>>).
-
-The native-code compiler (ocamlopt) requires the Microsoft compiler
-and the Microsoft assembler MASM64 (item link:tps-native1[(1(])
-and the flexdll tool (item <<tps-native2,[2]>>).
-
-=== INSTALLATION:
-
-There is no binary distribution yet.  Please compile from sources as
-described below.
-
-
-=== THIRD-PARTY SOFTWARE
-
-[[tps-native1]]
-[1]:: Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 Service Pack 1.
-    Can be downloaded for free from
-    http://www.microsoft.com/downloads/en/default.aspx
-    under the name "Microsoft Windows 7 SDK".
-
-[[tps-native2]]
-[2]:: flexdll version 0.31 or later.
-    Can be downloaded from http://alain.frisch.fr/flexdll.html
-
-
-=== RECOMPILATION FROM THE SOURCES
-
-The command-line tools can be recompiled from the Unix source
-distribution ('ocaml-X.YZ.tar.gz'), which also contains the files modified
-for Windows.
-
-You will need the following software components to perform the recompilation:
-- Windows XP 64, Windows Server 64, or Windows 7 64.
-- Items <<tps-native1,[1]>> and <<tps-native2,[2]>> from the list of
-  recommended software above.
-- The Cygwin port of GNU tools, available from http://www.cygwin.com/
-  Install at least the following packages: diffutils, make, ncurses.
-
-First, you need to set up your cygwin environment for using the MS
-tools.  The following assumes that you have installed <<tps-native1,[1]>>
-and <<tps-native2,[2]>> in their default directories.  If this is not
-the case, you will need to adjust the paths accordingly.
-
-. Open a Windows Command Prompt and enter the following commands:
-
-    set PFPATH=C:\Program Files (x86)
-    cd "%PFPATH%\Microsoft Visual Studio 9.0\VC\bin"
-    vcvars64
-    echo VCPATH="`cygpath -p '%Path%'`" >C:\cygwin\tmp\msenv
-    echo LIB="%LIB%" >>C:\cygwin\tmp\msenv
-    echo LIBPATH="%LIBPATH%" >>C:\cygwin\tmp\msenv
-    echo INCLUDE="%INCLUDE%" >>C:\cygwin\tmp\msenv
-    echo FLPATH="`cygpath '%PFPATH%\flexdll'`" >>C:\cygwin\tmp\msenv
-    echo PATH="$VCPATH:$FLPATH:$PATH" >>C:\cygwin\tmp\msenv
-    echo export PATH LIB LIBPATH INCLUDE >>C:\cygwin\tmp\msenv
-    echo export OCAMLBUILD_FIND=/usr/bin/find >>C:\cygwin\tmp\msenv
-
-. Open a Cygwin shell and enter the following commands:
-
-    tr -d '\r' </tmp/msenv >.msenv64
-    echo '. $HOME/.msenv64' >>.bashrc
-
-Now, close the Command Prompt and the shell and you're set up for
-using the MS tools under Cygwin.
-
-
-To recompile OCaml, start a new Cygwin shell and change to the top-level
-directory of the OCaml distribution.  Then, do
-
-        cp config/m-nt.h config/m.h
-        cp config/s-nt.h config/s.h
-        cp config/Makefile.msvc64 config/Makefile
-
-Then, edit config/Makefile as needed, following the comments in this file.
-Normally, the only variable that need to be changed is
-
-        PREFIX      where to install everything
-
-Finally, use `make -f Makefile.nt` to build the system, e.g.
-
-        make -f Makefile.nt world
-        make -f Makefile.nt bootstrap
-        make -f Makefile.nt opt
-        make -f Makefile.nt opt.opt
-        make -f Makefile.nt install
-
-
-=== NOTES
-
-* Libraries available in this port: `num`, `str`, `threads`, `graphics`,
-  and large parts of `unix`.
-
-* The replay debugger is partially supported (no reverse execution).
-
-* The graphical browser ocamlbrowser is not supported.
+[[seflexdll]]
+== FlexDLL
+Although the core of FlexDLL is necessarily written in C, the `flexlink` program
+is, naturally, written in OCaml.  This creates a circular dependency if you wish
+to build entirely from sources.  Since OCaml 4.03 and FlexDLL 0.35, it is now
+possible to bootstrap the two programs simultaneously.  The process is identical
+for both ports.  If you choose to compile this way, it is not necessary to
+install FlexDLL separately -- indeed, if you do install FlexDLL separately, you
+may need to be careful to ensure that `ocamlopt` picks up the correct `flexlink`
+in your `PATH`.
+
+You must place the FlexDLL sources for Version 0.35 or later in the directory
+`flexdll/` at the top-level directory of the directory of the OCaml
+distribution.  This can be done in one of three ways:
+
+ * Extracting the sources from a tarball from
+   http://alain.frisch.fr/flexdll.html#download
+ * Cloning the git repository by running:
++
+  git clone https://github.com/alainfrisch/flexdll.git
+
+ * If you are compiling from a git clone of the OCaml repository, instead of
+   using a sources tarball, you can run:
++
+  git submodule update --init
+
+OCaml is then compiled as normal for the port you require, except that before
+compiling `world`, you must compile `flexdll`, i.e.:
+
+  make -f Makefile.nt flexdll world [bootstrap] opt opt.opt install
+
+ * `make -f Makefile.nt install` will install FlexDLL by placing `flexlink.exe`
+   (and the default manifest file for the Microsoft port) in `bin/` and the
+   FlexDLL object files in `lib/`.
+ * If you don't include `make -f Makefile.nt opt.opt`, `flexlink.exe` will be a
+   bytecode program.  `make -f Makefile.nt install` always installs the "best"
+   `flexlink.exe` (i.e. there is never a `flexlink.opt.exe` installed).
+ * If you have populated `flexdll/`, you *must* run
+   `make -f Makefile.nt flexdll`.  If you wish to revert to using an externally
+   installed FlexDLL, you must erase the contents of `flexdll/` before
+   compiling.
+
+== Trademarks
+
+Microsoft, Visual C++, Visual Studio and Windows are registered trademarks of
+Microsoft Corporation in the United States and/or other countries.
diff --git a/configure b/configure
index 036cd3606d..0bb2d35f9d 100755
--- a/configure
+++ b/configure
@@ -394,7 +394,7 @@ case "$bytecc,$target" in
     dllccompopts="-U_WIN32 -DCAML_DLL"
     if test $with_sharedlibs = yes; then
       flexlink="flexlink -chain $flavor -merge-manifest -stack 16777216"
-      flexdir=`$flexlink -where | dos2unix`
+      flexdir=`$flexlink -where | tr -d '\015'`
       if test -z "$flexdir"; then
         wrn "flexlink not found: native shared libraries won't be available."
         with_sharedlibs=no
diff --git a/tools/msvs-promote-path b/tools/msvs-promote-path
new file mode 100755
index 0000000000..668fc55de2
--- /dev/null
+++ b/tools/msvs-promote-path
@@ -0,0 +1,51 @@
+#!/bin/bash
+#**************************************************************************
+#*                                                                        *
+#*                                 OCaml                                  *
+#*                                                                        *
+#*                David Allsopp, MetaStack Solutions Ltd.                 *
+#*                                                                        *
+#*   Copyright 2015 MetaStack Solutions Ltd.                              *
+#*                                                                        *
+#*   All rights reserved.  This file is distributed under the terms of    *
+#*   the GNU Lesser General Public License version 2.1, with the          *
+#*   special exception on linking described in the file LICENSE.          *
+#*                                                                        *
+#**************************************************************************
+
+# Ensure that the Microsoft Linker isn't being messed up by /usr/bin/link
+if [ "`link --version | head -1 | \
+     fgrep "Microsoft (R) Incremental Linker"`" != "" ] ; then
+  echo "link already refers to the Microsoft Linker">&2
+  exit 0
+fi
+
+IFS=:
+T=
+FOUND=0
+FIRST=1
+for i in $PATH
+do
+  if [ $FIRST -eq 1 ] ; then
+    T="$i"
+    FIRST=0
+  else
+    if [ $FOUND -eq 0 -a -x $i/link ] && [ "`$i/link --version | head -1 | \
+                       fgrep "Microsoft (R) Incremental Linker"`" != "" ] ; then
+      FOUND=1
+      T="$i:$T"
+      PROM=$i
+    else
+      T="$T:$i"
+    fi
+  fi
+done
+unset IFS
+
+if [ $FOUND -eq 0 ] ; then
+  echo The Microsoft Linker was not found in any of the PATH entries!>&2
+  exit 1
+else
+  echo "$PROM moved to the front of \$PATH">&2
+  echo export PATH=\"$T\"
+fi