[m-rev.] for review: improve documentation about running csharp grade programs

Julien Fischer juliensf at csse.unimelb.edu.au
Tue Feb 15 16:00:28 AEDT 2011

For review by PeterW.

The following describes the situation with the csharp grade as the current
implementation supports it -- matters on .NET would be much simplified if
the compiler supported signing assemblies, (e.g if mmc had a --keyfile option
that caused /keyfile to be passed to the C# compiler).  I will look into this

Branches: main, 11.01

Improve documentation that describes how to run Mercury csharp grade programs.

 	Describe how to run Mercury csharp grade programs with Mono and .NET

 	Mention that with Mono on Unix we will create a wrapper script.

 	Describe how to run Mercury csharp grade program with .NET on Windows.
 	(In particularly, describe how add the Mercury standard library assemblies
 	to the GAC manually.)


Index: README.CSharp
RCS file: /home/mercury/mercury1/repository/mercury/README.CSharp,v
retrieving revision 1.1
diff -u -r1.1 README.CSharp
--- README.CSharp	26 Oct 2010 04:59:09 -0000	1.1
+++ README.CSharp	15 Feb 2011 04:51:50 -0000
@@ -43,9 +43,110 @@
  	cd samples
  	mmc --make --csharp hello

-Now you can run hello
+For the example in the previous section on a Unix (ore more generally,
+non-Windows) system using Mono, the Mercury compiler will generate a process
+assembly, e.g. hello.exe, and a wrapper shell script named hello.
+The wrapper shell script will set the MONO_PATH environment variable
+to point to the location of the Mercury standard library assemblies.
+It will then invoke CLI execution environment on the above process assembly,
+i.e. you can run the program by simply running the wrapper shell script,
+for example
+      ./hello
+On Windows, the Mercury compiler will only generate a process assembly, e.g.
+hello.exe.  (On Windows there is no need to generate a wrapper shell script.)
+With .NET, the library assemblies (.dlls) for the Mercury standard
+libraries must either (1) reside in (or under) the same directory as the process
+assembly (.exe) or (2) be entered into the global assembly cache (GAC).
+If neither of these things is done then execution will abort with a message that
+     Unhandled Exception: System.IO.FileNotFoundException: Could not load file
+     or assembly 'mer_std',  Version=...
+For (1), you will need to copy the library assemblies from the Mercury library
+installation into the the same directory as the process assembly.
+The files for the library assemblies are located in
+     <prefix>\lib\mercury\lib\csharp
+where <prefix> is the location of the Mercury installation.
+Copy all of the dll files in the above directory into that of the process
+As for (2), in order to enter assemblies into the GAC they must be strongly-
+named; unfortunately the Mercury compiler does not currently support creating
+strongly-named assemblies in the csharp grade.  If you're feeling particularly
+fearless, then you can give the standard library assemblies strong-names and
+enter them into the GAC manually using the following instructions.
+(0) We require the .NET SDK tools, such as gacutil.exe, to be available
+    from the command line.  (You can use the ``Visual Studio Command Prompt''
+    shortcut to start a command line session with the environment suitably
+    set up.)
+(1) Copy the standard library assemblies out of <prefix>\lib\mercury\lib\csharp
+    and into a separate directory.
+(2) Create a new strong-name key-pair with which to sign the assemblies.
+    A key-pair can be created by using the sn.exe tool, for example
+        sn -k mercury.snk
+    will create a new key-pair and place it in the file mercury.snk.
+    (You may skip this step if you already have a strong-name key-pair
+    that you wish to use.)
+(3) For each dll file do the following.  (We illustrate using mer_std.dll.)
+    (i) Disassemble the assembly into MSIL.
+            ildasm mer_std.dll /out:mer_std.il
+        Note that this may also result in the creation of a resource file
+        mer_std.res.
+    (ii) Delete mer_std.dll.
+    (iii) Reassemble the assembly and sign it using the key-pair.
+            ilasm mer_std.il /dll /output=mer_std.dll /resource=mer_std.res /key=mercury.snk
+          Note that the /resource switch is only required if a resource file
+          is generated during disassembly.
+     (iv) Enter the assembly in the GAC.
+            gacutil /i mer_std.dll
+     (v) Replace Mercury's copy of the assembly with the newly signed one.
+           copy mer_std.dll <prefix>\lib\mercury\lib\csharp
+         This last step is important - the C# compiler does not look for
+         assemblies in the GAC at compile-time.  We need to keep the "reference"
+         copy of the assembly in the Mercury library installation consistent with
+         the one in the GAC.  (If something goes wrong here, the symptom will
+         typically be an abort from the runtime with a message saying that it
+         could not find the assembly.)
+Assemblies can be removed from the GAC by doing, for example
+    gacutil /u mer_std.dll

-	./hello
+We hope to improve support for signing assemblies in future versions of the
+Mercury compiler.


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

More information about the reviews mailing list