Clean up the handling of the --java' and --gc' compilation options.

Estimated hours taken: 3
Branches: main

Clean up the handling of the `--java' and `--gc' compilation options.

README.Java:
	Document the `--java' and `--target java' options,
	and use `--java' rather than `--grade java' in the examples.

compiler/handle_options.m:
	Fix a bug where `mmc --java --output-grade-string'
	was printing "java.gc" instead of "java".  It was calling
	set_gc_method to set the gc_method field in the globals structure,
	but it was not setting the corresponding string option in the
	options table, and compute_grade was looking at the string option.
	The fix was to also set the string option.

scripts/parse_grade_options.sh-subr:
	Handle the `--java' and `--java-only' options.

scripts/final_grade_options.sh-subr:
	For the IL and Java back-ends, set the gc_method to automatic.
	For the Java back-end, set highlevel_data to true.

compiler/globals.m:
	Fix an XXX: add a new alternative to the gc_method type,
	"automatic", to distinguish lack of GC ("none") from the
	automatic GC done by Java or the .NET CLR.

compiler/options.m:
doc/user_guide.texi:
	Document the new `--gc automatic' alternative for the `--gc' option.
	Delete the documentation of the deprecated `--gc conservative'
	option (which has been replaced with `--gc boehm').

compiler/compile_target_code.m:
compiler/handle_options.m:
scripts/parse_grade_options.sh-subr:
scripts/final_grade_options.sh-subr:
	Handle the new `--gc automatic' option..

README.Java

@@ -33,8 +33,11 @@ In order to try this system you will need
 
 THE JAVA GRADE
 
-The Mercury compiler currently supports the grade 'java' to target Java
-bytecode.  Support for building and installation of this grade
+The Mercury compiler currently supports the grade `java' to target Java
+bytecode.  The java grade is enabled by using any of the options
+`--grade java', `--target java', or just `--java'.
+
+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 Mercury
@@ -54,7 +57,7 @@ You can now build programs such as hello.m or calculator.m in the samples
 directory.
 	
 	cd samples
-	mmc --make --grade java hello
+	mmc --make --java hello
 
 Now you can run hello
 
@@ -145,7 +148,7 @@ A. By default, javac already generates line number and source file debugging
    setting the JAVACFLAGS variable to include "-g" when invoking mmake,
    e.g.
 
-        mmc --make --grade java --target-debug <progname>
+        mmc --make --java --target-debug <progname>
 
    or
    	

compiler/compile_target_code.m

@@ -460,6 +460,12 @@ compile_c_file(ErrorStream, PIC, C_File, O_File, Succeeded) -->
 	),
 	globals__io_get_gc_method(GC_Method),
 	{
+		GC_Method = automatic,
+		GC_Opt = ""
+	;
+		GC_Method = none,
+		GC_Opt = ""
+	;
 		GC_Method = boehm,
 		GC_Opt = "-DMR_CONSERVATIVE_GC -DMR_BOEHM_GC "
 	;
@@ -468,9 +474,6 @@ compile_c_file(ErrorStream, PIC, C_File, O_File, Succeeded) -->
 	;
 		GC_Method = accurate,
 		GC_Opt = "-DMR_NATIVE_GC "
-	;
-		GC_Method = none,
-		GC_Opt = ""
 	},
 	globals__io_lookup_bool_option(profile_calls, ProfileCalls),
 	{ ProfileCalls = yes ->
@@ -1310,6 +1313,10 @@ get_mercury_std_libs(TargetType, StdLibDir, StdLibs) -->
 	% GC libraries.
 	%
 	(
+		{ GCMethod = automatic },
+		{ StaticGCLibs = "" },
+		{ SharedGCLibs = "" }
+	;
 		{ GCMethod = none },
 		{ StaticGCLibs = "" },
 		{ SharedGCLibs = "" }

compiler/globals.m

@@ -47,17 +47,32 @@
 	.
 
 	% The GC method specifies how we do garbage collection.
-	% This is only relevant for the C and asm back-ends;
-	% when compiling to IL or Java, where the target language
-	% implementation handles garbage collection automatically,
-	% the gc_method is set to `none'.  (XXX Maybe we should
-	% have a different alternative for that case?)
+	% The last four alternatives are for the C and asm back-ends;
+	% the first alternative is for compiling to IL or Java,
+	% where the target language implementation handles garbage
+	% collection automatically.
 	% 
 :- type gc_method
-	--->	none
-	;	boehm
-	;	mps
-	;	accurate.
+	--->	automatic % It is the responsibility of the target language
+			  % that we are compiling to to handle GC.
+
+	;	none	% No garbage collection. 
+			% But memory may be recovered on backtracking,
+			% if the --reclaim-heap-on-*failure options are set.
+
+	;	boehm	% The Boehm et al conservative collector.
+
+	;	mps	% A different conservative collector, based on
+			% Ravenbrook Limited's MPS (Memory Pool System) kit.
+			% Benchmarking indicated that this one performed worse
+			% than the Boehm collector, so we don't really
+			% support this option anymore.
+
+	;	accurate
+			% Our own home-grown copying collector.
+			% See runtime/mercury_accurate_gc.c
+			% and compiler/ml_elim_nested.m.
+	.
 
 	% Returns yes if the GC method is conservative,
 	% i.e. if it is `boehm' or `mps'.
@@ -264,6 +279,7 @@ convert_gc_method("conservative", boehm).
 convert_gc_method("boehm", boehm).
 convert_gc_method("mps", mps).
 convert_gc_method("accurate", accurate).
+convert_gc_method("automatic", automatic).
 
 convert_tags_method("none", none).
 convert_tags_method("low", low).
@@ -278,6 +294,7 @@ gc_is_conservative(boehm) = yes.
 gc_is_conservative(mps) = yes.
 gc_is_conservative(none) = no.
 gc_is_conservative(accurate) = no.
+gc_is_conservative(automatic) = no.
 
 %-----------------------------------------------------------------------------%
 

compiler/handle_options.m

@@ -251,7 +251,7 @@ postprocess_options(ok(OptionTable), Error) -->
                 { Error = yes("Invalid tags option (must be `none', `low' or `high')") }
             )
         ;
-            { Error = yes("Invalid GC option (must be `none', `conservative', `boehm', `mps' or `accurate')") }
+            { Error = yes("Invalid GC option (must be `none', `conservative', `boehm', `mps', `accurate', or `automatic')") }
 	)
     ;
         { Error = yes("Invalid target option (must be `c', `asm', `il', or `java')") }
@@ -325,7 +325,7 @@ postprocess_options_2(OptionTable0, Target, GC_Method, TagsMethod0,
 			AutoIntermodOptimization),
 
 	% Generating IL implies:
-	%   - gc_method `none' and no heap reclamation on failure
+	%   - gc_method `automatic' and no heap reclamation on failure
 	%	  Because GC is handled automatically by the .NET CLR
 	%	  implementation.
 	%   - high-level code
@@ -368,7 +368,8 @@ postprocess_options_2(OptionTable0, Target, GC_Method, TagsMethod0,
 	%   	  needed, so ensure that this dead code is removed.
 
 	( { Target = il } ->
-		globals__io_set_gc_method(none),
+		globals__io_set_gc_method(automatic),
+		globals__io_set_option(gc, string("automatic")),
 		globals__io_set_option(reclaim_heap_on_nondet_failure,
 			bool(no)),
 		globals__io_set_option(reclaim_heap_on_semidet_failure,
@@ -415,7 +416,7 @@ postprocess_options_2(OptionTable0, Target, GC_Method, TagsMethod0,
 	),
 
 	% Generating Java implies
-	%   - gc_method `none' and no heap reclamation on failure
+	%   - gc_method `automatic' and no heap reclamation on failure
 	%	  Because GC is handled automatically by the Java
 	%	  implementation.
 	%   - high-level code
@@ -452,7 +453,8 @@ postprocess_options_2(OptionTable0, Target, GC_Method, TagsMethod0,
 	%   	  intermodule optimization pulls in a lot of code which isn't
 	%   	  needed, so ensure that this dead code is removed.
 	( { Target = java } ->
-		globals__io_set_gc_method(none),
+		globals__io_set_gc_method(automatic),
+		globals__io_set_option(gc, string("automatic")),
 		globals__io_set_option(reclaim_heap_on_nondet_failure,
 			bool(no)),
 		globals__io_set_option(reclaim_heap_on_semidet_failure,

compiler/options.m

@@ -3089,20 +3089,22 @@ your program compiled with different options.
 	]),
 	io__write_string("      Miscellaneous optional features\n"),
 	write_tabbed_lines([
-		"--gc {none, conservative, boehm, mps, accurate}",
-		"--garbage-collection {none, conservative, boehm, mps, accurate}",
-		"\t\t\t\t(`.gc' grades use `--gc boehm',",
+		"--gc {none, boehm, mps, accurate, automatic}",
+		"--garbage-collection {none, boehm, mps, accurate, automatic}",
+		"\t\t\t\t(`java' and `il' grades use",
+		"\t\t\t\t\t`--gc automatic',",
+		"\t\t\t\t`.gc' grades use `--gc boehm',",
 		"\t\t\t\t`.mps' grades use `--gc mps',",
 		"\t\t\t\tother grades use `--gc none'.)",
 		"\tSpecify which method of garbage collection to use",
 		"\t(default: boehm).",
-		"\t`conservative' or `boehm' is Hans Boehm et al's conservative",
-		"\tcollector.",
+		"\t`boehm' is Hans Boehm et al's conservative collector.",
 		"\t`accurate' is our own type-accurate copying GC;",
 		"\tit requires `--high-level-code'.",
 		"\t`mps' is a different conservative collector, based on",
 		"\tRavenbrook Limited's MPS (Memory Pool System) kit.",
-		"\tThis option is ignored for the IL and Java back-ends,",
+		"\t`automatic' means the target language provides it.",
+		"\tThis is the case for the IL and Java back-ends,",
 		"\twhich always use the garbage collector of the underlying",
 		"\tIL or Java implementation.",
 		"--use-trail\t\t\t(grade modifier: `.tr')",

doc/user_guide.texi

@@ -5483,18 +5483,20 @@ Record the sizes of terms, using one cell as the unit of memory.
 @end ignore
 
 @sp 1
-@item @code{--gc @{none, conservative, boehm, mps, accurate@}}
-@itemx @code{--garbage-collection @{none, conservative, boehm, mps, accurate@}}
+@item @code{--gc @{none, boehm, mps, accurate, automatic@}}
+@itemx @code{--garbage-collection @{none, boehm, mps, accurate, automatic@}}
 @cindex Garbage collection
 @cindex Conservative garbage collection
 @cindex Boehm (et al) conservative garbage collector
 @cindex MPS conservative garbage collector
 @cindex Memory Pool System conservative garbage collector
 @cindex Accurate garbage collection
+@cindex Automatic garbage collection
 @findex --gc
 @findex --garbage-collection
 Specify which method of garbage collection to use.
-Grades containing @samp{.gc} use @samp{--gc boehm},
+Grades containing @samp{java} or @samp{il} use @samp{--gc automatic},
+grades containing @samp{.gc} use @samp{--gc boehm},
 grades containing @samp{.mps} use @samp{--gc mps},
 other grades use @samp{--gc none}.
 @samp{conservative} or @samp{boehm} is Hans Boehm et al's conservative
@@ -5503,7 +5505,8 @@ garbage collector.
 It requires @samp{--high-level-code}.
 @samp{mps} is another conservative collector based on Ravenbrook Limited's 
 MPS (Memory Pool System) kit.
-This option is ignored by the IL and Java back-ends, which always use
+@samp{automatic} means the target language provides it.
+This is the case for the IL and Java back-ends, which always use
 the underlying IL or Java implementation's garbage collector.
 
 @sp 1

scripts/final_grade_options.sh-subr

@@ -1,5 +1,5 @@
 #---------------------------------------------------------------------------#
-# Copyright (C) 1998-2002 The University of Melbourne.
+# Copyright (C) 1998-2002, 2004 The University of Melbourne.
 # This file may only be copied under the terms of the GNU General
 # Public License - see the file COPYING in the Mercury distribution.
 #---------------------------------------------------------------------------#
@@ -54,6 +54,20 @@ case $target in asm|il|java)
 	highlevel_code=true ;;
 esac
 
+#
+# --target Java implies --high-level-data
+#
+case $target in java)
+	highlevel_data=true ;;
+esac
+
+#
+# --target IL or Java implies --gc automatic
+#
+case $target in il|java)
+	gc_method=automatic ;;
+esac
+
 #
 # --high-level-code disables the use of low-level gcc extensions
 #

scripts/parse_grade_options.sh-subr

@@ -1,5 +1,5 @@
 #---------------------------------------------------------------------------#
-# Copyright (C) 1997-2003 The University of Melbourne.
+# Copyright (C) 1997-2004 The University of Melbourne.
 # This file may only be copied under the terms of the GNU General
 # Public License - see the file COPYING in the Mercury distribution.
 #---------------------------------------------------------------------------#
@@ -40,6 +40,9 @@
 	--il|--IL|--il-only|--IL-only)
 		target=il ;;
 
+	--java|--Java|--java-only|--Java-only)
+		target=java ;;
+
 	--high-level-code|-H)
 		highlevel_code=true ;;
 	--no-high-level-code|-H-)
@@ -73,7 +76,7 @@
 	--gc)
 		shift
 		case "$1" in
-			accurate|conservative|boehm|mps|none)
+			accurate|conservative|boehm|mps|none|automatic)
 				gc_method=$1 ;;
 			*)
 				echo "$0: invalid gc method \`$1'" 1>&2