[m-rev.] For review: README files for Java/DotNet

[James Goddard]

Estimated hours taken: 4
Branches: main

README.Java:
	A helpful guide to installing and using the Java grade, modelled on
	README.DotNet.

Estimated hours taken: 0.1
Branches: main

README.DotNet:
	Added a pointer to the Foreign Language Interface section of the
	Mercury Language Reference.


Index: README.Java
===================================================================
RCS file: README.Java
diff -N README.Java
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ README.Java	27 Jan 2004 07:15:02 -0000
@@ -0,0 +1,151 @@
+-----------------------------------------------------------------------------
+
+INTRODUCTION
+
+This release of Mercury contains a port to Sun Microsystems' Java 2 Platform,
+Standard Edition (J2SE).
+The Mercury compiler will generate Java source code that can be assembled into
+Java bytecode suitable for running in the J2SE runtime system.
+
+The port is mostly complete, but some parts of the Mercury standard
+library are not yet implemented (for a full list see the FAQ below).
+
+The port is currently targeted at J2SE version 1.2 or higher, but we recommend
+version 1.4 for optimal performance and access to features.
+
+PREREQUISITES
+
+In order to try this system you will need 
+
+	- The J2SE SDK, which can be downloaded for free from
+		<http://java.sun.com/downloads/index.html>
+
+	  OR any other compatible Java implementation.
+
+	- The Mercury distribution -- installed as usual.  You can install
+	  from either the source or binary distribution.
+
+	  If you're reading this file from somewhere other than the
+	  Mercury distribution, try the Mercury homepage at
+	  	<http://www.cs.mu.oz.au/mercury/>
+
+-----------------------------------------------------------------------------
+
+THE JAVA GRADE
+
+The Mercury compiler currently supports the grade 'java' to target Java
+bytecode.  Support for building and installation of this grade
+is still somewhat rudimentary.
+
+To run a Mercury program using the java grade, you need to build the
+library and runtime in the java grade, using the Mercury source distribution.
+
+You will also need to set the environment variable CLASSPATH to include the
+mercury standard and runtime libraries for java, as well as the current
+directory.  You should use a command of the form:
+
+	CLASSPATH=<prefix>/mer_std.jar:<prefix>/mer_std.runtime.jar:. ; \
+	export CLASSPATH
+
+Where <prefix> is the location of the installed jar files, which will probably
+be /usr/local/mercury/lib/mercury/lib/java or something similar.
+
+You can now build programs such as hello.m or calculator.m in the samples
+directory.
+	
+	cd samples
+	mmc --make --grade java hello
+
+Now you can run hello
+
+	./hello
+
+-----------------------------------------------------------------------------
+
+USING JAVA
+
+The Mercury standard library has not been fully ported to Java yet.
+The use of unimplemented procedures will result in a run-time error,
+with a message such as "Sorry, not implemented: foreign code for this
+function", and a stack trace.
+
+If you find missing functionality, you can interface to Java using Mercury's
+foreign language interface.
+
+For example:
+
+:- pred to_string(T::in, string::out) is det.
+:- pragma foreign_proc("Java", to_string(T::in, Str::out), [],
+"
+        Str = T.toString();
+").
+
+The implementation will include this Java code in the module's .java file, and
+you can then call the predicate to_string exactly the same as if it were
+implemented using pure mercury code.
+
+For more information about the foreign language interface, refer to the Mercury
+Language Reference Manual, which you can find at:
+	<http://www.cs.mu.oz.au/mercury/information/documentation.html>
+
+-----------------------------------------------------------------------------
+
+RESOURCES
+
+You might find the following pages useful:
+
+	<http://www.cs.mu.oz.au/research/mercury/java.html>
+
+	<http://java.sun.com/reference/api/index.html>
+
+	<http://www.cs.mu.oz.au/mercury/information/documentation.html>
+
+-----------------------------------------------------------------------------
+
+FREQUENTLY ASKED QUESTIONS (FAQS)
+
+Q. What are the advantages of using the Java back-end?
+
+A. The main advantages are easy access to the wide range of libraries available
+   for the J2SE platform, including web applet development, and the portability
+   you get from using Java bytecode.
+
+
+Q. What version of Java should I be using?
+
+A. Java 2 Platform Standard Edition, version 1.2 or greater.  Note that some
+   features require version 1.4 or greater, however.
+
+
+Q. Which features?
+
+A. When using a Java version earlier than 1.4, there are limitations on treating
+   stdin and stdout as binary files with respect to seeking.  See the
+   documentation for io.m in the standard library for more details.
+
+
+Q. What features are not yet implemented?
+
+A. The following standard library modules are completely unimplemented:
+
+	benchmarking
+	construct
+	deconstruct
+	store
+	type_desc
+
+   In addition, the following individual procedures from other modules
+   are still not yet implemented:
+
+	private_builtin.instance_constraint_from_typeclass_info/3
+	private_builtin.superclass_from_typeclass_info/3
+	private_builtin.type_info_from_typeclass_info/3
+	private_builtin.unconstrained_type_info_from_typeclass_info/3
+	term_size_prof_builtin.measure_size/2
+	term_size_prof_builtin.measure_size_acc/3
+	term_size_prof_builtin.increment_size/2
+   	time.clocks_per_sec/0
+	time.c_clock/3
+	time.c_times/7
+
+-----------------------------------------------------------------------------
Index: README.DotNet
===================================================================
RCS file: /home/mercury1/repository/mercury/README.DotNet,v
retrieving revision 1.11
diff -u -d -r1.11 README.DotNet
--- README.DotNet	27 Feb 2003 09:21:07 -0000	1.11
+++ README.DotNet	23 Jan 2004 00:37:37 -0000
@@ -131,6 +131,10 @@
         Str = T.ToString();
 }").
 
+For more information about the foreign language interface, refer to the Mercury
+Language Reference Manual, which you can find at:
+	<http://www.cs.mu.oz.au/mercury/information/documentation.html>
+
 The implementation will put this C# in a separate file, which will be
 compiled with Microsoft's C# compiler.  Mmake will automatically
 generate dependencies for this file and invoke the C# compiler with the
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------