[m-dev.] for review: introduce the trace and browser directories

[Zoltan Somogyi]

> One more point: I think you need to modify scripts/Mmake.rules 
> or scripts/Mmake.vars.in to ensure that Mmake passes the GRADEFLAGS
> to c2init.

Actually, modules.m.

> > {runtime,trace}/mercury_trace.[ch]:
> > {runtime,trace}/mercury_trace_external.[ch]:
> > {runtime,trace}/mercury_trace_internal.[ch]:
> > 	Move these files to from the runtime to the trace directory.
> 
> s/to from/from/

Done.

> > +++ Mmake.common.in	1998/09/24 11:55:42
> > @@ -164,9 +164,23 @@
> > +
> > +# The names of the various libraries.
> > +# The archives and shared object objects have a "lib" prefix and a ".a" o
       r
> > +# ".so" suffix around these names; the initialization files have just a
> > +# ".init" suffix.
> 
> s/".so"/".so" (or ".dll")/

Done.

> s/Se/See/

Done.

> > Index: runtime/mercury_trace_base.c
> ...
> > +void
> > +MR_trace_fake(const MR_Stack_Layout_Label *layout, MR_trace_port port,
> > +	Word seqno, Word depth, const char * path, int max_mr_num)
> > +{
> > +	fatal_error("This executable is not set up for debugging.\n"
> > +		"Rebuild the <main>_init.c file, "
> > +		"and give the -t flag to c2init.\n");
> > +}
> 
> The second sentence of that error message is likely to mystify many
> users, I think.  Typically users will just use `mmc' or `mmake' and so
> they may not be even aware of the `c2init' script.  In addition, the
> `<main>_init.c' file may be hidden away in the `Mercury/cs'
> subdirectory.  Thus it may be very difficult for users to figure out
> what they need to do.

If people use mmc, I have made the compiler pass -t to c2init, so the problem
does not arise. If they use debug grade, the problem does not arise. Users
should see that message only if they are using a non-debug grade and separate
compilation. Under those circumstances, requiring users to know about c2init
is not too much to ask, I think.

> Ideally I think the second sentence should be replaced by
> something like "See the <blah> section of the Debugging chapter
> of the Mercury User's Guide for details on how to build programs
> with debugging enabled.", with the relevant section explaining
> in a bit more detail how to do it.
> 
> For the moment you should at very least add an XXX.
> And perhaps change the message to "For details on how to build programs
> with debugging enabled, send email to <mercury at cs.mu.oz.au>." ;-)

Since I don't want to refer people to a chapter that does not exist, I have
just put the XXX about it there.

> > +	trace_func = need_tracing ? "MR_trace_real" : "MR_trace_fake";
> 
> I think some additional parentheses would make the code more readable here:
> 
> 	trace_func = (need_tracing ? "MR_trace_real" : "MR_trace_fake");

Done, even though I don't think it improves readability at all.

The other diffs follow.

Zoltan.

--- Log	Mon Sep 28 19:02:14 1998
+++ /mnt/munkora/home/staff/zs/tmp/Log	Mon Sep 28 17:08:14 1998
@@ -11,32 +11,20 @@
 
 After this change, the linking order becomes:
 
-	the object of the auto-generated init file
-	program object files
+	program object files, and the object of the auto-generated init file
 	trace library (libmer_trace.a)
 	browser library (libmer_browser.a)
 	standard library (libmer_std.a)
 	runtime library (libmer_rt.a)
 	Boehm collector (libgc.a)
 
-To avoid circularities, libraries cannot contain direct calls to
-any routines that are defined in libraries (or object files) that
-occur earlier in the above list.  Any such calls must be made into
-indirect calls via function pointers.
-
-In particular, there was a circularity caused by the library calling
-MR_trace() which invokes the tracer which in turn invokes the
-library.  This circularity was broken by having MR_trace(),
-which is defined in the runtime, call the tracer indirectly via
-a global variable named MR_trace_func_ptr.  This global variable
-is initialized by the auto-generated *_init.c file.
-
-To avoid linking in the tracer even when it is not being used,
-this global variable is only set to point to MR_trace_real()
-if you're using a debugging grade or if c2init was invoked
-with the `-t' flag.  Otherwise it is set to MR_trace_fake()
-which just prints an error message telling the user to
-rebuild the executable with debugging enabled.
+In case the program does not contain calls to the tracer but the standard
+library does, which can happen if the library is compiled with tracing in a
+non-debug grade, the above structure allows circularities. To avoid them,
+MR_trace, which is in the runtime, calls either a dummy tracer in the runtime
+or a real tracer in the trace directory, depending on the value assigned to
+a new global variable by the automatically generated init file. This is
+controlled by a new option to mkinit/c2init.
 
 Makefile.DLLs:
 	Reserve random locations for the two new libraries. Whether they work
@@ -100,7 +88,7 @@
 {runtime,trace}/mercury_trace.[ch]:
 {runtime,trace}/mercury_trace_external.[ch]:
 {runtime,trace}/mercury_trace_internal.[ch]:
-	Move these files from the runtime to the trace directory.
+	Move these files to from the runtime to the trace directory.
 
 	The only changes are the removal from mercury_trace.h of declarations
 	added to runtime/mercury_trace_base.h, and the change from MR_trace
--- browser/Mmakefile.was	Mon Sep 28 19:13:27 1998
+++ browser/Mmakefile	Mon Sep 28 19:13:29 1998
@@ -155,6 +155,11 @@
 		echo "INIT mercury__`basename $$file .m`__init"; \
 	done > $(BROWSER_LIB_NAME).init
 
+# Ensure we recompile browser_library__version if VERSION is changed.
+$(os_subdir)browser_library.o \
+$(os_subdir)browser_library.pic_o \
+        : $(RUNTIME_DIR)/mercury_conf.h
+
 #-----------------------------------------------------------------------------#
 
 realclean:
--- trace/Mmakefile.was	Mon Sep 28 19:16:49 1998
+++ trace/Mmakefile	Mon Sep 28 19:16:54 1998
@@ -61,16 +61,16 @@
 DLL_CFLAGS	= -Dlib$(TRACE_LIB_NAME)_DEFINE_DLL
 
 # the following header files are created automatically by Makefile.DLLs
-LIBMER_DLL_H	 = lib$(TRACE_LIB_NAME)_dll.h
-LIBMER_GLOBALS_H = lib$(TRACE_LIB_NAME)_globals.h
+LIB_DLL_H	 = lib$(TRACE_LIB_NAME)_dll.h
+LIB_GLOBALS_H = lib$(TRACE_LIB_NAME)_globals.h
 
 include $(MERCURY_DIR)/Makefile.DLLs
 
 else
 
 DLL_CFLAGS =
-LIBMER_DLL_H =
-LIBMER_GLOBALS_H =
+LIB_DLL_H =
+LIB_GLOBALS_H =
 DLL_DEF_LIB =
 
 endif
@@ -83,7 +83,7 @@
 
 .PHONY: trace
 trace: lib$(TRACE_LIB_NAME).a lib$(TRACE_LIB_NAME).$(EXT_FOR_SHARED_LIB)
-trace: $(LIBMER_DLL_H) $(LIBMER_GLOBALS_H)
+trace: $(LIB_DLL_H) $(LIB_GLOBALS_H)
 
 lib$(TRACE_LIB_NAME)$(DLL_DEF_LIB).a: $(OBJS)
 	rm -f lib$(TRACE_LIB_NAME)$(DLL_DEF_LIB).a
@@ -119,8 +119,8 @@
 install: install_headers install_lib
 
 .PHONY: install_headers
-install_headers: $(HDRS) $(LIBMER_GLOBALS_H)
-	cp `vpath_find $(HDRS) $(LIBMER_GLOBALS_H)` $(INSTALL_INC_DIR)
+install_headers: $(HDRS) $(LIB_GLOBALS_H)
+	cp `vpath_find $(HDRS) $(LIB_GLOBALS_H)` $(INSTALL_INC_DIR)
 
 .PHONY: install_lib
 install_lib: lib$(TRACE_LIB_NAME).a lib$(TRACE_LIB_NAME).$(EXT_FOR_SHARED_LIB)
--- runtime/mercury_trace_base.c.was	Mon Sep 28 19:24:52 1998
+++ runtime/mercury_trace_base.c	Mon Sep 28 19:28:37 1998
@@ -103,7 +103,11 @@
 {
 	fatal_error("This executable is not set up for debugging.\n"
 		"Rebuild the <main>_init.c file, "
-		"and give the -t flag to c2init.\n");
+		"and give the -t flag to c2init when you do so.\n"
+		"If you are using mmake, you can do this by including "
+		"-t in C2INIT_FLAGS.\n");
+	/* XXX refer to the debugging chapter in the reference manual */
+	/* when it is written */
 }
 
 void
Index: compiler/modules.m
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/modules.m,v
retrieving revision 1.86
diff -u -u -r1.86 modules.m
--- modules.m	1998/09/24 18:44:33	1.86
+++ modules.m	1998/09/28 09:10:29
@@ -2424,7 +2424,7 @@
 
 	io__write_strings(DepStream, [
 		InitCFileName, " : ", DepFileName, "\n",
-		"\t$(C2INIT) $(ALL_C2INITFLAGS) $(", MakeVarName, ".cs) > ",
+		"\t$(C2INIT) $(ALL_GRADEFLAGS) $(ALL_C2INITFLAGS) $(", MakeVarName, ".cs) > ",
 			InitCFileName, "\n\n"
 	]),
 
Index: compiler/mercury_compile.m
===================================================================
RCS file: /home/mercury1/repository/mercury/compiler/mercury_compile.m,v
retrieving revision 1.106
diff -u -u -r1.106 mercury_compile.m
--- mercury_compile.m	1998/09/10 06:51:23	1.106
+++ mercury_compile.m	1998/09/28 09:15:32
@@ -2370,7 +2370,7 @@
 	    join_module_list(Modules, ".m", ["> ", InitCFileName], MkInitCmd0),
 	    globals__io_get_trace_level(TraceLevel),
 	    { trace_level_trace_interface(TraceLevel, yes) ->
-		CmdPrefix = "c2init -i "
+		CmdPrefix = "c2init -t "
 	    ;
 		CmdPrefix = "c2init "
 	    },