[m-rev.] for review: documentation updates and fixes for MSVC port

Julien Fischer juliensf at csse.unimelb.edu.au
Mon Nov 7 15:18:45 AEDT 2011
Previous message: [m-rev.] For review: Fix a bug in automatic parallelism analysis.
Next message: [m-rev.] for review: documentation updates and fixes for MSVC port
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
For review by anyone.

Branches: 11.07, main

Improve and update documentation of the MSVC port.

Add batch files for invoking mdb and mprof; avoid problem with mercury.bat.

README.MS-VisualC:
 	Rewrite this file, it was very much out-of-date.
 	The major changes are:

 	+ we now describe how to set up a Cygwin or MSYS shell
   	  with MSVC available.

 	+ the source distribution now works with MSVC.

 	+ a list of the limitations of the MSVC port has been added.

 	+ a description of how to set up the compier so that it
 	  works from the Windows command prompt has been added.

scripts/mercury/mercury.bat.in:
 	Delete support for the MERCURY_COMPILER and MERCURY_CONFIG_DIR
 	enviorment variables; the handling of them in this batch file
 	doesn't appear to be portable across different versions of
 	Windows and it's more important that this file work in the
 	normal case.  (Keeping it simple is the way to ensure this.)

scripts/mdb.bat.in:
scripts/mprof.bat.in:
 	Templates for invoking mdb and mprof on Windows.
 	(I'm not sure how to reproduce all the functionality of the mdb
 	script in a batch file, so the command line options provided by
 	the mdb script aren't currently replicated here.)

configure.in:
scripts/Mmakefile:
 	Add the new batch files.

scripts/Mercury.config.in:
 	Use the Windows-style installation prefix on Cygwin systems.

browser/util.m:
 	Use the conventional name for the I/O state.

 	Use don't-care variables for the I/O state in foreign procs.
 	This avoids suprious warnings from MSVC.

Julien.

Index: README.MS-VisualC
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/README.MS-VisualC,v
retrieving revision 1.8
diff -u -r1.8 README.MS-VisualC
--- README.MS-VisualC	7 Mar 2006 06:40:39 -0000	1.8
+++ README.MS-VisualC	7 Nov 2011 04:06:56 -0000
@@ -1,90 +1,202 @@
  -----------------------------------------------------------------------------

-INTRODUCTION
+BUILDING WITH MICROSOFT VISUAL C++

-Mercury has been ported to use the Microsoft Visual C++ compiler.  It
-has been tested with both version 6.0 and 7.0.  However not all
-dependencies on Cygwin have been removed and Cygwin is still required
-for installation (see README.MS-Windows).
+Mercury has been ported to use the Microsoft Visual C++ compiler.
+It has been tested with both version 9.0 (2008) and version 10.0 (2010).
+Version 8.0 (2005) should also work but we have not tested that with 
+Mercury recently.

-If you wish to use Microsoft Visual C++ Toolkit 2003, or Microsoft
-Visual C++ Express 2005, you will require the Platform SDK.
+-----------------------------------------------------------------------------
+
+SETTING UP THE BUILD ENVIRONMENT
+
+A Unix-like environment is required for building and installing Mercury.
+Either Cygwin <http://www.cygwin.com/> or MSYS <http://www.mingw.org/> will
+suffice for this purpose.
+
+A Unix-like environment is *not* required in order to use Mercury once it
+has been installed.
+
+To make MSVC and its supporting tools available under the Cygwin or MSYS shells
+do the following:
+
+(1) Open the Windows Command Prompt.
+    (Start -> All Programs -> Accessories -> Command Prompt on Windows XP)
+    (Start -> Accessories -> Command Prompt on Windows 7)
+
+(2) Enter the following command:
+
+       C:\> "%VS90COMNTOOLS%"\vsvars32.bat
+ 
+    This command sets up the environment for MSVC version 9.0 (2008).
+    For MSVC version 10.0 (2010) the corresponding environment variable
+    is VS100COMNTOOLS.
+
+(3) Enter the following command to start the MSYS shell:
+
+        C:\> C:\MinGW\MSYS\1.0\msys.bat 
+
+    or this one to start the Cygwin shell:
+ 
+        C:\> C:\CYGWIN\cygwin.bat
+
+(We assume the default installation locations for MinGW/MSYS and Cygwin above.)
+
+In order to install the C#, Erlang or Java grades you will require a C#,
+Erlang or Java compiler to be included in the Windows PATH.
+(See the relevant README files for further details, e.g. README.Java etc)

  -----------------------------------------------------------------------------

-CONFIGURATION
+CONFIGURATION AND INSTALLATION
+
+The MSVC port of Mercury is compatible with the prebuilt C files contained in
+the Mercury source distribution.  The 'asm_fast' and 'reg' grades will not work
+with MSVC (see below), so when using prebuilt C files the compiler will be
+built in the 'none.gc' grade.
+
+Alternatively, if you have an existing Mercury installation that uses the MinGW
+or Cygwin GCC ports, or clang then you can checkout the Mercury source from the
+CVS repository and use your existing installation to cross-compile the MSVC
+port.  In this case the compiler will be built using the more efficient
+'hlc.gc' grade.
+
+In either case, to use MSVC as the C compiler with Mercury, invoke configure
+as follows:
+
+    $ ./configure --with-cc=cl [--with-msvcrt] [<any other options>]
+
+The `--with-msvcrt' flag causes executables built with this install of Mercury
+to be linked with the MS Visual C runtime, instead of the standard libC
+runtime.
+
+On Cygwin, configure and mmake will do translation of Unix style paths, so you
+may specify the installation directory using either a Unix- or Window-style
+path.  On MSYS, you must use a Window-style path.

-To use MSVC to build the compiler issue the following configure command.
+Be sure to quote Windows style paths used as arguments to the configure
+script's `--prefix' option, otherwise the shell will get confused.

-CC='CL /nologo' CPP='CL /nologo /E' ./configure [--with-msvcrt]
+Once configure has run, then you should do

-Pass the --with-msvcrt flag to configure, and the resulting Mercury
-executables built with the install of Mercury will be linked with MS
-Visual C runtime, instead of the standard libC runtime.
+    $ make 
+    $ make install

-Also ensure that the environment variable TMPDIR exists and is set to
-".".  This avoids problems with mixing Cygwin and Windows paths.
+as normal.

  -----------------------------------------------------------------------------

-SOURCE INSTALLATION
+LIMITATIONS

-In order to save time in compilation the source distribution comes with
-prebuilt C files.  These C files are generated using the asm_fast grade
-which is incompatible with hlc.gc.  In order to alleviate this problem:
+The MSVC port currently has a number of limitation:

-1. Install Cygwin (avoid the bug in sscanf with 1.3.1-1)
+* The 'asm_fast' and 'reg' grades do not work with MSVC.
+  Both use GNU extensions to C that MSVC does not provide.

-2. Install an asm_fast grade version of the compiler which uses gcc as
-   the C compiler.  This can be done from a source or binary
-   distribution.  Follow standard instructions.  I suggest:
+* Time profiling does not (currently) work with MSVC.
+  Time profiling grades (those whose name contains the 'prof' grade component)
+  will not be installed.

-   a) configure --prefix /usr/local/mercury-<VERSION>
-      (See the file VERSION in the top-level directory of the Mercury
-       distribution for details of the Mercury version number scheme.)
-   b) make install
+  Note that memory profiling _does_ work with MSVC.  (Memory profiling grades
+  are those whose name contains the 'memprof' grade component.)

-   Ensure your path has been modified so you can see the new mmc once it
-   is built.  For example:
+* Parallel grades (those whose name contains the `par' component) do not
+  currently work with MSVC.

-   a) edit /etc/profile and add /usr/local/mercury-<VERSION> to PATH
+  In parallel grades the Mercury runtime currently requires the use of POSIX
+  threads; it has not currently been ported to use Windows threads.
+  (It might be possible to use the pthreads-win32 library with MSVC to
+  provide POSIX threads but we have not tested that yet.)

-3. To build a version of the mercury compiler with MSVC++ instead of
-   gcc, remotely check out a fresh version of the compiler, eg.
+* Deep profiling, e.g. the *.profdeep grades, does not (currently) work
+  with MSVC.  (In principle, it should work if the clock tick metric is
+  disabled.)

-   a) cvs -d :pserver:guest at cvs.mercury.cs.mu.oz.au:/home/mercury1/repository login
-   (password is guest)
-   b) cvs -d :pserver:guest at cvs.mercury.cs.mu.oz.au:/home/mercury1/repository co mercury
+* The deep profiling tool (mdprof_cgi) does not currently work with MSVC.
+  This is due to it containing a number of Unix dependencies.  (Other
+  tools that work with deep profiles should be fine.)

-   Alternatively, you can just run mmake realclean to create a fresh version
-   of the compiler.
+* Mercury has not yet been ported to 64-bit Windows.
+
+* When used directly from the Windows command prompt, mmake will not work.
+  You should use `mmc --make' instead.  (mmake requires a POSIX-like shell
+  and GNU make; it will however work with the Cygwin or MSYS shells.)
+
+  Note that we have no intention of ever supporting mmake directly on
+  Windows.
+
+* Creation of shared libraries (DLLs) is not currently supported.
+
+-----------------------------------------------------------------------------
+
+POST-INSTALLATION CONFIGURATION
+
+The above instructions create a Mercury installation that targets MSVC that
+works from within the Cygwin or MSYS shells.  If you want to be able to run the
+Mercury compiler directly from the Windows command prompt (e.g. cmd.exe)
+then you need to manually edit some configuration files in the installation.
+(In future releases, this will all hopefully be automated.)
+
+All references to files in the following are within the Mercury installation
+directory
+
+* By default, the Mercury compiler will attempt to use the "cp" command to
+  install files.  Since Windows does not provide this, you will need to provide
+  an alternative (see the next section for details of how to do this).
+
+  We recommend installing the UnxUtils port of "cp" and using that with
+  Mercury.  See: <http://sourceforge.net/projects/unxutils/>.
+
+* In the file lib/mercury/conf/Mercury.config:

-   If you wish to checkout a specific release of Mercury, use the -r option
-   to co and one of the following release tags:
+  + Replace any Unix-style paths with their Windows-style equivalent. 
+
+  + Add the following option in the value of the variable DEFAULT_MCFLAGS
+ 
+    --env-type windows
+
+  + To specify the commands used to install files and directories include
+    the following options in the value of the variable DEFAULT_MCFLAGS
+ 
+    --install-command <cp>
+    --install-command-dir-option <opt>
+
+    (NOTE: if you are using the UnxUtils port of "cp" then you don't need to
+    do anything here; the default settings will suffice.)
+
+* In the file lib/mercury/mdb/mdbrc
+
+  + The backslash character, `\`, is used as an escape character in mdbrc
+    files.  You need to escape it if it occurs in any paths used in argument
+    of source commands, e.g.
+
+        source c:\mercury-11.07\lib\mercury\mdb\mdb_doc
+
+    needs to be replaced with:
+
+        source c:\\mercury-11.07\\lib\\mercury\\mdb\\mdb_doc

-   	Release		Release Tag
-	-------		-----------
-	0.11.0		version-0_11_0
-	0.12.0		version-0_12_0
-	0.12.1		version-0_12_1
-	0.12.2		version-0_12_2
+  + Delete the aliases for the "open" and "grep" commands.
+    The scripts that implement these commands assume a Unix-style environment.

-   Then to use MSVC++ to build the compiler issue the following configure
-   command.  (You must be able to run MSVC++ from command line):
+* The bin directory contains batch files equivalent to the mmc, mdb and prof
+  scripts.  Note that the batch file equivalent to the mmc script is named
+  mercury.bat in order to avoid clashing with the executable for the
+  Microsoft Management Console.

-   CC='CL /nologo' CPP='CL /nologo /E' configure --prefix /usr/local/msmercury
-   (configure defaults to using the hlc.gc grade as this is the only
-   grade currently supported).
+* The following scripts do not currently have a Windows equivalent.

-4. make install
+    + mprof_merge_runs
+    + mtc

-DO NOT USE THE SOURCE DISTRIBUTION TO BUILD THE MS-VisualC VERSION OF
-THE COMPILER!!  CONFIGURE DOES NOT DETERMINE THAT THE PRE-BUILT C
-FILES ARE INCOMPATIBLE IT JUST TRIES TO USE THEM ANYWAY.
+* The other shell scripts in the bin directory do not have (or need) Windows
+  equivalents.  (Most of them are part of the implementation of mmake which
+  is not supported on Windows systems.)

  -----------------------------------------------------------------------------

-INSTALLING ON NETWORK DRIVES
+INSTALLING ON NETWORK DRIVES (Cygwin only)

  If you want to install on the machine, foo, in the directory \usr\local
  you need to add `--prefix //foo/usr/local' as an option to configure.
Index: configure.in
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/configure.in,v
retrieving revision 1.601
diff -u -r1.601 configure.in
--- configure.in	25 Oct 2011 13:57:01 -0000	1.601
+++ configure.in	7 Nov 2011 02:57:47 -0000
@@ -5351,12 +5351,14 @@
  scripts/mmc
  scripts/mercury.bat
  scripts/mprof
+scripts/mprof.bat
  scripts/mercury_update_interface
  scripts/mgnuc
  scripts/ml
  scripts/c2init
  scripts/mmake
  scripts/mdb
+scripts/mdb.bat
  scripts/mdprof
  scripts/mtags
  scripts/canonical_grade
Index: browser/util.m
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/browser/util.m,v
retrieving revision 1.41
diff -u -r1.41 util.m
--- browser/util.m	20 Oct 2011 13:44:31 -0000	1.41
+++ browser/util.m	1 Nov 2011 15:01:16 -0000
@@ -142,7 +142,7 @@

  :- pragma foreign_proc("C",
      trace_get_command(Prompt::in, Line::out, MdbIn::in,
-        MdbOut::in, State0::di, State::uo),
+        MdbOut::in, _IO0::di, _IO::uo),
      [may_call_mercury, promise_pure, tabled_for_io],
  "
      char        *line;
@@ -160,8 +160,6 @@
      } else {
          ML_BROWSER_trace_get_command_fallback(Prompt, &Line, MdbIn, MdbOut);
      }
-
-    State = State0;
  ").

  trace_get_command(Prompt, Line, MdbIn, MdbOut, !IO) :-
Index: scripts/Mercury.config.in
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/scripts/Mercury.config.in,v
retrieving revision 1.26
diff -u -r1.26 Mercury.config.in
--- scripts/Mercury.config.in	14 Dec 2010 07:01:55 -0000	1.26
+++ scripts/Mercury.config.in	28 Oct 2011 15:13:54 -0000
@@ -111,7 +111,7 @@
  		--linker-allow-undefined-flag "@ALLOW_UNDEFINED@" \
  		--linker-error-undefined-flag "@ERROR_UNDEFINED@" \
  		--fullarch "@FULLARCH@" \
-		--install-prefix "@prefix@" \
+		--install-prefix "@PREFIX@" \
  		--num-real-r-regs "@NUM_REAL_R_REGS@" \
  		--num-real-r-temps "@NUM_REAL_R_TEMPS@" \
  		--conf-low-tag-bits "@LOW_TAG_BITS@" \
Index: scripts/Mmakefile
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/scripts/Mmakefile,v
retrieving revision 1.46
diff -u -r1.46 Mmakefile
--- scripts/Mmakefile	1 Sep 2009 23:54:38 -0000	1.46
+++ scripts/Mmakefile	7 Nov 2011 02:55:57 -0000
@@ -23,6 +23,7 @@
  	c2init \
  	canonical_grade \
  	mdb \
+	mdb.bat \
  	mdprof \
  	mercury.bat \
  	mercury_config \
@@ -33,6 +34,7 @@
  	mmake \
  	mmc \
  	mprof \
+	mprof.bat \
  	mtags \
  	prepare_install_dir

Index: scripts/mdb.bat.in
===================================================================
RCS file: scripts/mdb.bat.in
diff -N scripts/mdb.bat.in
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ scripts/mdb.bat.in	7 Nov 2011 02:54:58 -0000
@@ -0,0 +1,18 @@
+ at echo off
+rem @configure_input@
+rem ---------------------------------------------------------------------------
+rem Copyright (C) The University of Melbourne.
+rem This file may only be copied under the terms of the GNU General
+rem Public License - see the file COPYING in the Mercury distribution.
+rem ---------------------------------------------------------------------------
+rem
+rem mdb.bat - Mercury debugger
+rem Usage: mdb [<options>] <executable> [<args>] ...
+rem
+rem ---------------------------------------------------------------------------
+ at echo off
+setlocal
+
+set MERCURY_OPTIONS=%MERCURY_OPTIONS% -Di
+set MERCURY_DEBUGGER_INIT="@PREFIX@\lib\mercury\mdb\mdbrc"
+%*
Index: scripts/mercury.bat.in
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/scripts/mercury.bat.in,v
retrieving revision 1.4
diff -u -r1.4 mercury.bat.in
--- scripts/mercury.bat.in	16 Feb 2011 04:43:05 -0000	1.4
+++ scripts/mercury.bat.in	7 Nov 2011 02:28:28 -0000
@@ -10,8 +10,6 @@
  rem
  rem Use `mercury -h' for help.
  rem
-rem Environment variables: 
-rem MERCURY_COMPILER, MERCURY_CONFIG_DIR.
  rem ---------------------------------------------------------------------------
  rem This is a Windows batch file version of the `mmc' Bourne shell script.
  rem (We don't use that name because it conflicts with that of the Microsoft
@@ -21,26 +19,7 @@
  rem Don't export any local environment changes.
  setlocal

-if "%MERCURY_CONFIG_DIR%"=="^%MERCURY_CONFIG_DIR^%" goto :config_dir_not_set
-
-goto :config_dir_set
-
-:config_dir_not_set
-
-if "%MERCURY_STDLIB_DIR%"=="" goto :stdlib_dir_not_set
-if "%MERCURY_STDLIB_DIR%"=="^%MERCURY_STDLIB_DIR^%" goto :stdlib_dir_not_set
-
-set MERCURY_CONFIG_DIR="%MERCURY_CONFIG_DIR%"
-
-goto :config_dir_set
-
-:stdlib_dir_not_set
-
  set MERCURY_CONFIG_DIR="@CONFIG_LIBDIR@"
-
-:config_dir_set
-
-if "%MERCURY_COMPILER%"=="" set MERCURY_COMPILER="@PREFIX@\bin\mercury_compile"
-if "%MERCURY_COMPILER%"=="^%MERCURY_COMPILER^%" set MERCURY_COMPILER="@PREFIX@\bin\mercury_compile"
+set MERCURY_COMPILER="@PREFIX@\bin\mercury_compile"

  %MERCURY_COMPILER% %*
Index: scripts/mprof.bat.in
===================================================================
RCS file: scripts/mprof.bat.in
diff -N scripts/mprof.bat.in
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ scripts/mprof.bat.in	7 Nov 2011 02:57:09 -0000
@@ -0,0 +1,17 @@
+ at echo off
+rem @configure_input@
+rem ---------------------------------------------------------------------------
+rem Copyright (C) The University of Melbourne.
+rem This file may only be copied under the terms of the GNU General
+rem Public License - see the file COPYING in the Mercury distribution.
+rem ---------------------------------------------------------------------------
+rem
+rem mprof - MercuryProfiler
+rem Use `mprof -h' for help.
+rem
+rem ---------------------------------------------------------------------------
+ at echo off
+setlocal
+
+set MPROF="@PREFIX@\bin\mercury_profile"
+%MPROF% %*

--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------
Previous message: [m-rev.] For review: Fix a bug in automatic parallelism analysis.
Next message: [m-rev.] for review: documentation updates and fixes for MSVC port
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the reviews mailing list