[m-rev.] For review: Document .jar files in the user guide

[James Goddard]

Estimated hours taken: 1
Branches: main

Document the use of .jar files for the Java grade.

doc/user_guide.texi:
	Include .jar files in the `File naming conventions' section.
	Explain how libraries are built, installed and used in the `Libraries'
	chapter.


Index: user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.380
diff -u -d -r1.380 user_guide.texi
--- user_guide.texi	10 Feb 2004 12:43:32 -0000	1.380
+++ user_guide.texi	18 Feb 2004 06:42:52 -0000
@@ -234,8 +234,8 @@
 by the Mercury compiler. The non-standard extensions are necessary
 to avoid conflicts with system header files.
 @file{.s} files and @file{.pic_s} files are assembly language.
- at file{.java} and @file{.class} files are Java source code
-and Java bytecode respectively.
+ at file{.java}, @file{.class} and @file{.jar} files are Java source code,
+Java bytecode and Java archives respectively.
 @file{.il} files are Intermediate Language (IL) files
 for the .NET Common Language Runtime.
 @c XXX mention .dll and .exe?
@@ -914,6 +914,7 @@
 * Building libraries::
 * Installing libraries::
 * Using libraries::
+* Libraries and the Java grade::
 @end menu
 
 @node Writing libraries
@@ -1164,6 +1165,26 @@
 @example
 EXTRA_LIBRARIES-foo = mylib4foo
 @end example
+
+ at node Libraries and the Java grade
+ at section Libraries and the Java grade
+ at cindex jar files
+ at cindex Java libraries
+
+Libraries are handled a little differently for the Java grade.  Instead of
+compiling object code into a static or shared library, the class files are
+added to a jar (Java ARchive) file of the form @var{library-name}.jar.
+
+To create or install a Java library, simply specify that you want to use the
+java grade, either by setting @samp{GRADE=java} in your Mmakefile, or by
+including @samp{--java} or @samp{--grade java} in your @samp{MCFLAGS}, then
+follow the instructions as above.
+
+Java libraries are installed to the directory
+ at file{@var{prefix}/lib/mercury/lib/java}.  To include them in a program, in
+addition to the instructions above, you will need to include the installed jar
+file in your @samp{CLASSPATH}, which you can set using
+ at samp{--java-classpath @var{jarfile}} in @samp{MCFLAGS}.
 
 @c ----------------------------------------------------------------------------
 
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------