[m-rev.] for review: update documentation for Cygwin
Julien Fischer
jfischer at opturion.com
Sun Aug 13 14:34:12 AEST 2023
For review by anyone.
---------------------
Update documentation for Cygwin.
README.Cygwin:
Rename -> README.Cygwin.md.
Replace the contents of this file; its existing contents were
horribly out-of-date.
README.MS-VisualC.md:
README.MS-Windows.md:
Update links.
NEWS.md:
Announce that 32-bit Cygwin is no longer supported.
Julien.
diff --git a/NEWS.md b/NEWS.md
index 6dd5443..77685c0 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -56,6 +56,8 @@ Changes that may break compatibility
operators. (Mercury switched to using `.` as the module name separator
around 2003.)
+* We have dropped support for x86 (32-bit) version of Cygwin.
+
Changes to the Mercury standard library
---------------------------------------
diff --git a/README.Cygwin.md b/README.Cygwin.md
index b584000..a94fa82 100644
--- a/README.Cygwin.md
+++ b/README.Cygwin.md
@@ -1,168 +1,17 @@
------------------------------------------------------------------------------
+Mercury on Cygwin
+=================
-INTRODUCTION
+This file documents the port of Mercury to Windows using
+[Cygwin](https://www.cygwin.com) (i.e the `x86_64-pc-cygwin` configuration).
-Mercury has been ported to Windows using the "Cygwin"
-(formerly also known as "Cygwin32" and "gnu-win32") Unix emulation
-package. We have tested the port on the following versions of Windows:
+The x86 (32-bit) version of Cygwin has reached its end-of-life and
+is no longer supported by Mercury.
- * Windows XP SP3
- * Windows 7
- * Windows Server 2008 R2
+Installations of Mercury on Cygwin will use the Cygwin port of the GNU C
+compiler (GCC) by default. When using the Cygwin port of GCC, programs will
+have a dependency on the Cygwin DLL (`cygwin1.dll`).
-It should also work with Windows XP SP2 and Windows Vista but we have not
-tested it with those.
-
-In the past Mercury worked with Windows, 95, 98, ME, 2000 and NT but we no
-longer actively maintain support for those versions.
-
-This file documents how to install the binary distribution of
-Mercury on Windows and how to build the source distribution
-of Mercury on Windows using Cygwin. This installation will use the GNU
-C compiler by default. If you want to use the Microsoft Visual C
-compiler, please see the file README.MS-VisualC.md.
-
------------------------------------------------------------------------------
-
-PREPARATION
-
-To use or build Mercury on Windows, you need to first get Cygwin and
-install it. Cygwin version 1.3.1 is buggy and should not be used, but
-Cygwin 1.1.* or Cygwin 1.3.2 or later should be OK. Recent versions of
-Cygwin can be installed directly from:
-
- <http://cygwin.com/setup-x86.exe>
-
-This program will download and install the required components.
-
-If you want more information on Cygwin, see the site:
-
- <https://cygwin.com>
-
-If you're going to use a binary distribution of Mercury for Windows,
-you need to make sure that you get a version of Cygwin that is
-compatible with the one that the binary distribution was compiled
-with. This will normally be specified in the filename of the
-Mercury binary distribution. For example, if the file name is
-mercury-0.9.1.pc-windows-cygwin-1.1.4.tar.gz then you need version
-1.1.4 of Cygwin. Later versions may work also, however it is always
-possible that compatibility might break at some point. Cygwin will
-create a file C:\cygwin\setup.txt that lists the versions of every
-package installed.
-
-Before continuing, check that you can run Cygwin and get a command line
-shell, and that `gcc' (the GNU C compiler) works.
-
-For more information on Cygwin, see the Cygwin web site mentioned above.
-
------------------------------------------------------------------------------
-
-UNPACKING THE SOURCES
-
-After installing Cygwin, you should download the Mercury source or
-binary distribution, and unpack it.
-
-You should use Cygwin's tar program to unpack the Mercury distribution.
-From a cygwin command shell, use the `cd' command to change directory
-to the directory where you saved the source or binary distribution that
-you downloaded, and then use `tar zxf <filename>' to unpack it,
-where <filename> is the filename that you downloaded, e.g.
-mercury-compiler-<VERSION>.tar.gz (for the source distribution), or
-mercury-<VERSION>.i686-pc-cygwin-windows.tar.gz (for the binary distribution).
-
-Note that other programs which understand tar.gz files (e.g. WinZip)
-may not be able to unpack them in the correct manner for use with Cygwin.
-
------------------------------------------------------------------------------
-
-RUNNING CONFIGURE
-
-Use the `cd' command to change directory to the directory that you just
-unpacked, and then configure with
-
- sh configure
-
-as described in the INSTALL file.
-On Windows 2000 or XP, it may start up the "Microsoft Management Console"
-program (the autoconfiguration process looks for a program named "mmc").
-If so, just close that application, e.g. by selecting "Exit" from
-the "Console" menu.
-
------------------------------------------------------------------------------
-
-RUNNING MAKE INSTALL
-
-Just type
-
- make install
-
------------------------------------------------------------------------------
-
-USING MERCURY
-
-Once you've finished installing, you need to add the appropriate
-directory, normally /usr/local/mercury-<VERSION>/bin, to your PATH.
-If you are familiar with how to set the PATH for command-line programs
-in Windows you can add
-
- C:\cygwin\usr\local\mercury-<VERSION>\bin
-
-to that path.
-
-Otherwise you can just set the path in Cygwin by creating a file called
-`.bashrc' in your Cygwin home directory that contains the line:
-
- PATH=/usr/local/mercury-<VERSION>/bin:$PATH
-
-You Cygwin home directory can be found in C:\cygwin\home\username\
-if using Windows Explorer (Cygwin will call your home directory
-`/home/username' or simply `~').
-
-On Windows 2000, you need to make sure that this directory precedes
-the Windows system directory in the PATH, otherwise `mmc' will invoke the
-Microsoft Management Console rather than the Melbourne Mercury Compiler.
-In this case it might be a good idea to modify your path in your
-.bashrc rather than in the Windows PATH environment variable, so as to
-not confuse any other programs that might be looking for the Microsoft
-Management Console.
-
-You should be able to read the HTML version of the Mercury
-documentation, which by default gets installed in
-C:\cygwin\usr\local\mercury-<VERSION>\lib\mercury\html, using Netscape
-or MS Internet Explorer. Or you can get a copy of GNU Emacs
-for NT and use it to browse the INFO version.
-
-If you use mmake files named `Mmake' rather than `Mmakefile',
-there can be some problems with case-insensitive filenames
-and the name clash between `mmake' and `Mmake'. If you run into any
-such problems, rename your `Mmake' file to `Mmakefile'.
-
-To write Mercury programs, simply create a new .m file in your favourite
-editor. Run `mmc <filename>.m' on the Cygwin command line to compile
-small programs, or use `mmake' to handle larger systems. See the
-Mercury Users Guide for more information about the command line tools.
-There is currently no GUI for editing and compiling Mercury programs,
-although it is quite likely you can hook up a sophisticated editor to
-run `mmc' and/or `mmake' for you.
-
------------------------------------------------------------------------------
-
-MEMORY ALLOCATION
-
-By default no Cygwin program can allocate more than 384 MB of memory
-(program+data). It is possible to exceed this limit, especially if one
-is using a debugging grade. In which case the runtime will report the
-following error
-
- "GC Warning: Out of Memory! Returning NIL!"
-
-To increase the maximum amount of memory a cygwin program can consume
-execute the following command, replacing 1024 with a value that makes
-sense for your system.
-
-regtool -i set /HKLM/Software/Cygnus\ Solutions/Cygwin/heap_chunk_in_mb 1024
-
-See <http://cygwin.com/cygwin-ug-net/setup-maxmem.html> for more
-details.
-
------------------------------------------------------------------------------
+You may also use the Cygwin environment to build a Mercury installation that
+uses an alternative C compiler, such as Microsoft Visual C.
+(See [README.MS-VisualC.md](README.MS-VisualC.md) and
+[README.MS-Windows.md](README.MS-Windows.md) for further details.)
diff --git a/README.MS-VisualC.md b/README.MS-VisualC.md
index b080d6e..26984d0 100644
--- a/README.MS-VisualC.md
+++ b/README.MS-VisualC.md
@@ -56,7 +56,7 @@ shells do the following:
or this one to start the Cygwin shell:
- C:\> C:\CYGWIN\cygwin.bat
+ C:\> C:\cygwin64\Cygwin.bat
(We assume the default installation locations for MinGW/MSYS and Cygwin above.)
diff --git a/README.MS-Windows.md b/README.MS-Windows.md
index 29f93b4..07238af 100644
--- a/README.MS-Windows.md
+++ b/README.MS-Windows.md
@@ -31,7 +31,7 @@ build Mercury on Windows.
Three such environments are supported:
-1. [Cygwin](https://www.cygwin.com). See [README.Cygwin](README.Cygwin).
+1. [Cygwin](https://www.cygwin.com). See [README.Cygwin.md](README.Cygwin.md).
2. [MSYS](https://osdn.net/projects/mingw/). See [README.MinGW](README.MinGW).
diff --git a/README.md b/README.md
index 2fad795..c78c5b7 100644
--- a/README.md
+++ b/README.md
@@ -52,7 +52,7 @@ Specific information is contained in individual README files:
* [Windows](README.MS-Windows.md)
([Visual C](README.MS-VisualC.md),
[MinGW](README.MinGW),
- [Cygwin](README.Cygwin))
+ [Cygwin](README.Cygwin.md)
* Other platform information
* [Cross compilation](README.cross.md)
More information about the reviews
mailing list