[m-rev.] for review: announce C# backend

[Peter Wang]

Branches: main

NEWS:
        Announce C# backend.

doc/user_guide.texi:
        Mention C# in a few more places.

doc/reference_manual.texi:
        Delete documentation about foreign language interfacing with IL
        backend.

diff --git a/NEWS b/NEWS
index 31134b6..b9dfa45 100644
--- a/NEWS
+++ b/NEWS
@@ -66,6 +66,8 @@ Changes to the Mercury standard library:
 
 Changes to the Mercury compiler:
 
+* We have added a new backend that generates C#.
+
 * Support for building and linking against frameworks on Mac OS X has
   been improved.
 
@@ -75,6 +77,12 @@ DETAILED LISTING
 
 Changes to the Mercury compiler:
 
+* We have added a new backend that generates C#.
+  For more details, see the README.CSharp.
+
+  The new backend was contributed by Mission Critical IT
+  <http://www.missioncriticalit.com/>.
+
 * We have added two new options, --framework and --framework-directory
   in order to simplify building and linking against frameworks on Mac OS X.
   (-F is supported as a synonym for --framework-directory.)
diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
index e98e118..cf654ca 100644
--- a/doc/reference_manual.texi
+++ b/doc/reference_manual.texi
@@ -253,7 +253,7 @@ of octal digits must be terminated with a closing backslash.
 @c hexadecimal digits.
 @c The encoding used for Unicode characters is implementation dependent.
 @c For the Melbourne Mercury compiler, it is UTF-8 for the C backends and UTF-16
- at c for the Java and IL backends.
+ at c for the Java, C# and IL backends.
 
 A backslash followed immediately by a newline is deleted; thus an
 escaped newline can be used to continue a string over more than one
@@ -6599,7 +6599,6 @@ to the foreign language's parameter passing convention.
 @menu
 * C data passing conventions ::
 * C# data passing conventions ::
-* IL data passing conventions ::
 * Java data passing conventions ::
 * Erlang data passing conventions ::
 @end menu
@@ -6803,63 +6802,6 @@ List_1    list.cons(object head, List_1 tail)
                                          //  the given head and tail
 @end example
 
- at node IL data passing conventions
- at subsection IL data passing conventions
-
-The Mercury types @code{int}, @code{float}, @code{char},
-and @code{string} are mapped to the Common Language Infrastructure (CLI) types
- at code{System.Int32}, @code{System.Double}, @code{System.Char} and
- at code{System.String} respectively, which correspond
-to the IL assembler types
- at samp{int}, @samp{float64}, @samp{char} and @samp{string}.
-
-Mercury variables whose type is a type variable will be passed as
- at code{System.Object}.
-Mercury array types are mapped to CLR array types.
-When compiling with @samp{--no-high-level-data}, all other Mercury variables
-are passed as @code{System.Object[]}.
-When compiling with @samp{--high-level-data},
-Mercury variables whose type is a Mercury discriminated union type
-will be passed as a CLR type whose type name is determined from
-the Mercury type name (ignoring any type parameters) followed by
-an underscore and then the type arity,
-expressed as a decimal integer.
-Mercury module qualifiers are converted to CLR namespace qualifiers.
-For example the Mercury type @samp{foo.bar.baz/1} will be passed as the CLR
-type @samp{foo.bar.baz_1}.
-Note an extra namespace qualifier, @samp{mercury}, will be prepended to the
-beginning of names residing in the Mercury standard library.
-Mercury variables whose type is a Mercury equivalence type
-will be passed as the representation of the right hand side of the
-equivalence type.
-
-This mapping is subject to change and you should try to avoid writing
-code that relies heavily upon a particular representation of Mercury
-terms.
-
-Mercury arguments declared with input modes are passed by value to the
-IL or C# function.
-For output arguments,
-the Mercury implementation will pass to the IL or C# function a reference to
-the location in which to store the result; for example, a Mercury output
-argument of type @samp{int} would map to a C# @samp{ref int}
-function parameter.  (Note that we map to @samp{ref int}, not @samp{out int};
-for procedures that can fail, output arguments only need to be set if the
-procedure succeeds.)
-If the Mercury procedure can fail,
-then its IL or C# function should return a truth value of type
- at samp{bool} (i.e.@: @samp{System.Bool}) indicating success or failure:
- at code{true} indicates success, and @code{false} indicates failure.
-If the Mercury procedure is a Mercury function that cannot fail,
-and the function result has an output mode,
-then the IL function should return the Mercury function result value.
-Otherwise the function result is appended as an extra argument.
-Arguments of type @samp{io.state} or @samp{store.store(_)} are not
-passed or returned at all.
-(The reason for this is that these types represent mutable state,
-and in IL modifications to mutable state are done via side effects,
-rather than argument passing.)
-
 @node Java data passing conventions
 @subsection Java data passing conventions
 
@@ -7384,7 +7326,6 @@ foreign language and occur in the same Mercury module.
 @menu
 * Interfacing with C 		:: How to write code to interface with C
 * Interfacing with C# 		:: How to write code to interface with C#
-* Interfacing with IL 		:: How to write code to interface with IL
 * Interfacing with Java 	:: How to write code to interface with Java
 * Interfacing with Erlang 	:: How to write code to interface with Erlang
 @end menu
@@ -7407,11 +7348,6 @@ Use the string @code{"C"} to set the foreign language to C.
 @item @samp{C#}
 Use the string @code{"C#"} to set the foreign language to C#.
       
- at item @samp{IL}
-Use the string @code{"IL"} to set the foreign language to IL.
-IL (sometimes also known as CIL or MSIL) is the Intermediate Language
-for the .NET Common Language Runtime.
-
 @item @samp{Java}
 Use the string @code{"Java"} to set the foreign language to Java.
 
@@ -7998,196 +7934,6 @@ For example:
 
 @c ----------------------------------------------------------------------------
 
- at node Interfacing with IL
- at subsection Interfacing with IL
-
- at menu
-* Using pragma foreign_type for IL	:: Declaring IL types in Mercury
-* Using pragma foreign_proc for IL 	:: Calling IL code from Mercury
-* Using pragma foreign_export for IL    :: Calling Mercury code from IL
-* Using pragma foreign_decl for IL 	:: Including IL declarations in Mercury
-* Using pragma foreign_code for IL 	:: Including IL code in Mercury
- at end menu
-
- at node Using pragma foreign_type for IL
- at subsubsection Using pragma foreign_type for IL
-
-The IL @samp{pragma foreign_type} declaration has the form:
-
- at example
-:- pragma foreign_type("IL", @var{MercuryTypeName}, @var{DotNetForeignType}).
- at end example
-
-If the @var{MercuryTypeName} is the type of a parameter of a procedure
-defined using @samp{pragma foreign_proc} for any of the .NET CLR
-languages, it will be passed to the foreign_proc's foreign language code
-as @var{DotNetForeignType}.
-
-Furthermore, any Mercury procedure exported with @samp{pragma foreign_export}
-will use @var{DotNetForeignType} as the .NET CLR parameter type for
-parameters whose Mercury type is @var{MercuryTypeName}.
-
-The IL assembler syntax is used to specify type names for all the .NET CLR
-languages (IL and C#) supported by Mercury's
- at samp{foreign_proc} mechanism.  
-This syntax is documented in the ECMA specifications for .NET.
-The .NET CLR backend supports reference and value types 
-using @samp{pragma foreign_type}, where DotNetForeignType is
-specified using the syntax 
- at samp{"class [AssemblyName]ReferenceTypeName"} for reference types and
- at samp{"valuetype [AssemblyName]ValueTypeName"} for value types.
-Note that extra whitespace is not handled --- there should only be a single
-space between the class keyword and the assembly specifier.
- at c XXX we should handle whitespace better
-Value types which have a special name (such as @samp{int32}) can be
-named using their valuetype syntax or their special name;
-they will be marshalled using their special name
-(as is required by section 7.2 of Partition II of the ECMA CLI documentation).
-
-For example:
-
- at example
-:- type xmldoc.
-:- pragma foreign_type("IL", xmldoc,
-	"class [System.Xml]System.Xml.XmlDocument").
-:- type int32.
-:- pragma foreign_type("IL", int32,
-	"valuetype [mscorlib]System.Int32").
- at end example
-
-ensures that on the .NET CLR backend the Mercury type @samp{xmldoc} is
-marshalled by the backend as @samp{System.Xml.XmlDocument} from assembly
- at samp{System.Xml}, and that the Mercury type @samp{int32} will be
-marshalled by the backend as the CLR type @samp{int32}.
-
-The following example shows how one can use the marshalled data from C#. 
-
- at example
-:- pred loadxml(string::in, xmldoc::di, xmldoc::uo) is det.
-
-:- pragma foreign_proc("C#", load(String::in, XML0::di, XML::uo),
-        [will_not_call_mercury, promise_pure],
-"
-    XML0.LoadXml(String);
-    XML = XML0;
-").
- at end example
-
- at node Using pragma foreign_proc for IL
- at subsubsection Using pragma foreign_proc for IL
-
-Variables can be accessed from IL by using ldloc (for input parameters) 
-and stloc (for output parameters).
-Do not use ret or jmp instructions or tail calls within the handwritten
-IL code.
-The stack must be empty at the end of the IL code.
-
- at example
-:- pred add(int::in, int::in, int::out) det.
-:- pragma foreign_proc("IL", add(X::in, Y::in, Z::out), [max_stack_size(2)], "
-	ldloc X
-	ldloc Y
-	add
-	stloc Z
-").
- at end example
-
-IL code for procedures whose determinism indicates they can fail 
-is currently not supported.
-
- at c XXX document how semidet works -- but get it working first.
- at c
- at c The IL code in a @code{pragma foreign_proc} declaration
- at c for any procedure whose determinism indicates that it can fail
- at c must assign a truth value to the local variable @samp{SUCCESS_INDICATOR}.
- at c For example:
- at c
- at c @example
- at c :- pred same(int::in, int::in) is semidet.
- at c :- pragma foreign_proc("IL", same(X::in, Y::in), [max_stack_size(2)], "
- at c 	ldloc X
- at c 	ldloc Y
- at c 	ceq
- at c 	stloc SUCCESS_INDICATOR
- at c ").
- at c @end example
-
-Arguments whose mode is input will have their values set by the
-Mercury implementation on entry to the IL code.  If the procedure
-succeeds, the IL code must set the values of all output arguments.
-
- at c If the procedure fails, the IL code need only
- at c set @code{success} to false (zero).
-
-Each of the head variables will be represented by the Common Language
-Runtime types as specified in @ref{IL data passing conventions}.
-
- at node Using pragma foreign_export for IL
- at subsubsection Using pragma foreign_export for IL
-
-A @samp{pragma foreign_export} declaration for IL has the form:
-
- at example
-:- pragma foreign_export("IL", @var{MercuryMode}, "@var{IL_Name}").
- at end example
-
-For example,
-
- at example
-:- pragma foreign_export("IL", foo(in, in, out), "foo").
- at end example
-
-For each Mercury module containing @samp{pragma foreign_export} declarations
-for IL, the Mercury implementation will automatically create a static method
- at var{IL_Name}() in the <module_name>.mercury_code class for each of the
- at samp{pragma foreign_export} declarations.  Each such IL method is a .NET
-interface to the specified Mercury procedure, and should be usable from
-any .NET language.
-
-The type signature of the IL interface to a Mercury procedure is determined as
-follows.  Mercury types are converted to IL types according to the rules in
- at ref{IL data passing conventions}.  Input arguments are passed by value.
-For output arguments, the caller must pass the address in which to store the
-result.  If the Mercury procedure can fail, then its IL interface method
-returns a truth value indicating success or failure.  If the Mercury procedure
-is a Mercury function that cannot fail, and the function result has an output
-mode, then the IL interface method will return the Mercury function result
-value.  Otherwise the function result is appended as an extra argument.
- at c XXX We need to update this for dummy unit types.
-Arguments of type @samp{io.state} or @samp{store.store(_)} are not passed
-at all.  (The reason for this is that these types represent mutable state,
-and in .NET modifications to mutable state are done via side effects, rather
-than argument passing.)
-
-Calling polymorphically typed Mercury procedures from .NET is a little bit more
-difficult than calling ordinary (monomorphically typed) Mercury procedures.
-The simplest method is to just create monomorphic forwarding procedures that
-call the polymorphic procedures, and export them, rather than exporting the
-polymorphic procedures.
-
-If you do export a polymorphically typed Mercury procedure, the compiler
-will prepend one @samp{type_info} argument to the parameter list of
-the IL interface method for each polymorphic type variable in the
-Mercury procedure's type signature.  The caller must arrange to pass
-in appropriate @samp{type_info} values corresponding to the types
-of the other arguments passed.  These @samp{type_info} arguments can
-be obtained using the Mercury @samp{type_of} function in the Mercury
-standard library module @samp{type_desc}.
-
- at node Using pragma foreign_decl for IL
- at subsubsection Using pragma foreign_decl for IL
-
- at samp{pragma foreign_decl} is currently not supported for IL.
- at c XXX
-
- at node Using pragma foreign_code for IL
- at subsubsection Using pragma foreign_code for IL
-
- at samp{pragma foreign_code} is currently not supported for IL.
- at c XXX
-
- at c ----------------------------------------------------------------------------
-
 @node Interfacing with Java
 @subsection Interfacing with Java
 
diff --git a/doc/user_guide.texi b/doc/user_guide.texi
index e50f0f6..e978c96 100644
--- a/doc/user_guide.texi
+++ b/doc/user_guide.texi
@@ -7923,7 +7923,7 @@ It requires @samp{--high-level-code}.
 @samp{mps} is another conservative collector based on Ravenbrook Limited's
 MPS (Memory Pool System) kit.
 @samp{automatic} means the target language provides it.
-This is the case for the IL, Java and Erlang back-ends, which always use
+This is the case for the IL, C#, Java and Erlang back-ends, which always use
 the underlying implementation's garbage collector.
 
 @sp 1
@@ -7967,7 +7967,7 @@ accessible via the @samp{thread} module in the standard library.
 The runtime uses POSIX threads to achieve this, therefore it may also support
 parallel execution of threads.
 
-The Java, IL and Erlang grades support concurrency without this option.
+The Java, C#, IL and Erlang grades support concurrency without this option.
 Parallel execution may also be available depending on the target's runtime. 
 
 @sp 1
@@ -7995,7 +7995,7 @@ attribute.  The default is @samp{no}.
 Use single precision floats so that, on 32-bit machines
 floating point values don't need to be boxed.  Double
 precision floats are used by default.
-This option is not yet supported for the IL or Java back-ends.
+This option is not yet supported for the IL, C# or Java back-ends.
 This option will not be supported for the Erlang back-end.
 
 @c RBMM is undocumented since it is still experimental.
@@ -9373,8 +9373,8 @@ than to @samp{mmc}.
 Enable debugging of the generated target code.
 If the target language is C, this has the same effect as
 @samp{--c-debug} (see below).
-If the target language is IL, this causes the compiler to
-pass @samp{/debug} to the IL assembler.
+If the target language is IL or C#, this causes the compiler to
+pass @samp{/debug} to the IL assembler or C# compiler.
 
 @sp 1
 @item --cc @var{compiler-name}

--------------------------------------------------------------------------
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
--------------------------------------------------------------------------