diff: library/Mmakefile & termination analysis

Fergus Henderson fjh at cs.mu.OZ.AU
Sun Jan 25 18:37:42 AEDT 1998
Previous message: diff: library/Mmakefile & termination analysis
Next message: diff: library/Mmakefile & termination analysis
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
On 25-Jan-1998, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> On 25-Jan-1998, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> > Estimated hours taken: 0.5
> > 
> > library/Mmakefile:
> > 	When building the library, enable transitive intermodule
> > 	optimization and enable termination analysis, and make sure the
> > 	library `.trans_opt' files get installed.  This is needed to
> > 	enable users to get the full benefits of transitive intermodule
> > 	optimization and termination analysis for programs that make
> > 	use of the standard library.  Without this, termination analysis
> > 	can't infer termination of "hello world".
> 
> You should probably also change the code that generated .dep files
> so that packages generate the .trans_opt files as well.

Initially I thought this was a good suggestion but I have since
discovered that unfortunately it's not quite that simple.
The problem is that to create the `.trans_opt' files, you
*must* compile everything with `--trans-intermod-opt'.
Otherwise, the information about files each `.trans_opt' depends on,
which is stored in the `.d' files, will get overwritten, and then
when you go to create the `.trans_opt' files, you get a warning
saying that you need to remake the dependencies.

Requiring packages to always be compiled with `--trans-intermod-opt'
would be overkill, I think.  It is "distributed cost" -- people who
are not using termination analysis should not have to pay
excessive compilation times when building packages simply because
someone *might* use termination analysis.  If it were just a matter
of creating the `.trans_opt' files, that would be a reasonable cost.
But compiling the whole package with full `--trans-intermod-opt' enabled
is too high a cost, IMHO.  The default should be to not pay this cost;
package builders can explicitly decide to pay it if their users demand it.
I'd rather inconvenience those using termination analysis than those
not using it.

An alternative would be to store trans-opt dependency information some
where other than in `.d', e.g. in `.td' files.  But that would be
YET ANOTHER FILE, which we should probably not do until we have
reorganized things so that all these little files are stored in
subdirectories.

> The documentation for packages would also need updating.

Yes, I'll do that.

Most of the diff below is trivial changes; the relevant fragments
are these two:

@@ -967,13 +968,19 @@
 Note that to use a library, as well as the shared or static object library,
 you also need the interface files.  That's why the
 @samp{libmypackage} target builds @samp{$(mypackage.ints)}.
-Also, if the people using the library are going to use intermodule
-optimization, you need the intermodule optimization interfaces.
+If the people using the library are going to use intermodule
+optimization, you will also need the intermodule optimization interfaces.
 That's why the @samp{libmypackage} target builds @samp{$(mypackage.opts)}.
+If the people using the library are going to use transitive intermodule
+optimization, you will also need the transitive intermodule optimization
+interfaces.  Currently these are @emph{not} built by default; if
+you want to build them, you will need to include @samp{--trans-intermod-opt}
+in your @samp{MCFLAGS} variable.
+
@@ -989,10 +996,12 @@
 
 If you want, once you have built a library, you could then install
 (i.e. copy) the shared object library, the static object library,
-the interface files and the initialization file into a different directory,
-or into several different directories, for that matter --- though it
-is probably easiest for the users of the library if you keep them
-in a single directory.
+the interface files (possibly including the optimization interface
+files and the transitive optimization interface files), and the
+initialization file into a different directory, or into several
+different directories, for that matter --- though it is probably
+easiest for the users of the library if you keep them in a single
+directory.
 Or alternatively, you could package them up into a @samp{tar}, @samp{shar}, or
 @samp{zip} archive and ship them to the people who will use the
 library.

doc/user_guide.texi:
	Document that library builders need to include `--trans-intermod-opt'
	in their MCFLAGS if they want to build transitive optimization
	interfaces.
	Various other minor corrections to the trans-opt documentation.
	ALso make sure that full stops are followed by two spaces.

Index: user_guide.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/user_guide.texi,v
retrieving revision 1.114
diff -u -u -r1.114 user_guide.texi
--- user_guide.texi	1998/01/23 17:09:46	1.114
+++ user_guide.texi	1998/01/25 07:31:20
@@ -138,15 +138,16 @@
 (or @samp{--make-opt-int}) option.
 Files ending in @file{.trans_opt} are interface files used in
 transitive inter-module optimization, and are created using the
- at samp{--make-transitive-optimization-interface} option.
+ at samp{--make-transitive-optimization-interface}
+(or @samp{--make-trans-opt-int}) option.
 
 Since the interface of a module changes less often than its implementation,
-the @file{.int}, @file{.int2}, @file{.int3}, and @file{.opt}
+the @file{.int}, @file{.int2}, @file{.int3}, @file{.opt}, and @file{.trans_opt}
 files will remain unchanged on many compilations.
 To avoid unnecessary recompilations of the clients of the module,
 the timestamps on the these files are updated only if their contents change.
- at file{.date}, @file{.date3} and @file{.optdate} files associated with the
-module are used as date stamps;
+ at file{.date}, @file{.date3}, @file{.optdate}, and @file{.trans_opt_date}
+files associated with the module are used as date stamps;
 they are used when deciding whether the interface files need to be regenerated.
 
 Files ending in @file{.d} are automatically-generated Makefile fragments
@@ -459,7 +460,7 @@
 @end example
 
 By default, @samp{msc} compiles files to machine code using
-SICStus Prolog's @samp{fastcode} mode. If space is more important
+SICStus Prolog's @samp{fastcode} mode.  If space is more important
 than speed, you can use the @samp{--mode compactcode} option,
 which instructs @code{msc} to use SICStus Prolog's @samp{compactcode}
 mode, which compiles files to a bytecode format.
@@ -808,7 +809,7 @@
 In addition to the files removed by @var{main-module}.clean, this
 removes the @samp{.date}, @samp{.int}, @samp{.int2}, @samp{.int3},
 @samp{.opt}, @samp{.optdate}, @samp{.date3},
- at samp{.trans_opt}, @samp{.trans_optdate},
+ at samp{.trans_opt}, @samp{.trans_opt_date},
 @samp{.d}, and @samp{.dep} belonging to one of the modules of the program,
 and also the various possible executables for the program ---
 @samp{@var{main-module}},
@@ -833,7 +834,7 @@
 
 The variables used by the builtin rules (and their default values) are
 defined in the file @file{@var{prefix}/lib/mercury/mmake/Mmake.vars}, however
-these may be overridden by user @samp{Mmake} files. Some of the more
+these may be overridden by user @samp{Mmake} files.  Some of the more
 useful variables are:
 
 @table @code
@@ -867,9 +868,9 @@
 
 If you wish to temporarily change the flags passed to an executable,
 rather than setting the various @samp{FLAGS} variables directly, one can
-supply a @samp{EXTRA_} variable. When defining a @samp{FLAGS} option
+supply a @samp{EXTRA_} variable.  When defining a @samp{FLAGS} option
 directly (in your own @samp{Mmake} file), it is recommended you include
-the @samp{EXTRA_} version at the end. This is particularly intended for
+the @samp{EXTRA_} version at the end.  This is particularly intended for
 use where a shell script needs to call mmake and add an extra parameter,
 without interfering with the flag settings in the @samp{Mmake} file.
 
@@ -886,7 +887,7 @@
 @chapter Libraries
 
 Often you will want to use a particular set of Mercury modules
-in more than one program. The Mercury implementation
+in more than one program.  The Mercury implementation
 includes support for developing libraries, i.e. sets of Mercury modules
 intended for reuse.  It allows separate compilation of libraries
 and, on many platforms, it supports shared object libraries.
@@ -967,13 +968,19 @@
 Note that to use a library, as well as the shared or static object library,
 you also need the interface files.  That's why the
 @samp{libmypackage} target builds @samp{$(mypackage.ints)}.
-Also, if the people using the library are going to use intermodule
-optimization, you need the intermodule optimization interfaces.
+If the people using the library are going to use intermodule
+optimization, you will also need the intermodule optimization interfaces.
 That's why the @samp{libmypackage} target builds @samp{$(mypackage.opts)}.
+If the people using the library are going to use transitive intermodule
+optimization, you will also need the transitive intermodule optimization
+interfaces.  Currently these are @emph{not} built by default; if
+you want to build them, you will need to include @samp{--trans-intermod-opt}
+in your @samp{MCFLAGS} variable.
+
 In addition, with certain compilation grades, programs will need to
 execute some startup code to initialize the library; the
 @samp{mypackage.init} file contains information about initialization
-code for the library.
+code for the library.  The @samp{libmypackage} target will build this file.
 
 On some platforms, shared objects must be created using position independent
 code (PIC), which requires passing some special options to the C compiler.
@@ -989,10 +996,12 @@
 
 If you want, once you have built a library, you could then install
 (i.e. copy) the shared object library, the static object library,
-the interface files and the initialization file into a different directory,
-or into several different directories, for that matter --- though it
-is probably easiest for the users of the library if you keep them
-in a single directory.
+the interface files (possibly including the optimization interface
+files and the transitive optimization interface files), and the
+initialization file into a different directory, or into several
+different directories, for that matter --- though it is probably
+easiest for the users of the library if you keep them in a single
+directory.
 Or alternatively, you could package them up into a @samp{tar}, @samp{shar}, or
 @samp{zip} archive and ship them to the people who will use the
 library.
@@ -1577,16 +1586,17 @@
 @item --make-trans-opt
 @itemx --make-transitive-optimization-interface
 Write the @file{@var{module}.trans_opt} file.  This file is used to store
-information used for inter-module optimization. The information is read
-in when the compiler is invoked with the @samp{--transitive-optimization}
-option.  The file is called ``transitive'' because a
- at file{@var{module}.trans_opt} file may depend on other
+information used for inter-module optimization.  The information is read 
+in when the compiler is invoked with the
+ at samp{--transitive-intermodule-optimization} option. 
+The file is called ``transitive'' because a 
+ at file{@var{module}.trans_opt} file may depend on other 
 @file{@var{module}.trans_opt} files.
 
 @sp 1
 @item -G
 @itemx --convert-to-goedel
-Convert the Mercury code to Goedel. Output to file @file{@var{module}.loc}.
+Convert the Mercury code to Goedel.  Output to file @file{@var{module}.loc}.
 The translation is not perfect; some Mercury constructs cannot be easily
 translated into Goedel.
 
@@ -1594,7 +1604,7 @@
 @item -P
 @itemx --pretty-print
 @itemx --convert-to-mercury
-Convert to Mercury. Output to file @file{@var{module}.ugly}.
+Convert to Mercury.  Output to file @file{@var{module}.ugly}.
 This option acts as a Mercury ugly-printer.
 (It would be a pretty-printer, except that comments are stripped
 and nested if-then-elses are indented too much --- so the result
@@ -1651,7 +1661,7 @@
 by an experimental debugger.
 
 @item --generate-prolog
-Convert the program to Prolog. Output to file @file{@var{module}.pl}
+Convert the program to Prolog.  Output to file @file{@var{module}.pl}
 or @file{@var{module}.nl} (depending the the dialect).
 
 @item --prolog-dialect @var{dialect}
@@ -1803,7 +1813,7 @@
 @sp 1
 @item --termination-norm @var{norm}
 The norm defines how termination analysis measures the size
-of a memory cell. The @samp{simple} norm says that size is always one.
+of a memory cell.  The @samp{simple} norm says that size is always one.
 The @samp{total} norm says that it is the number of words in the cell.
 The @samp{num-data-elems} norm says that it is the number of words in
 the cell that contain something other than pointers to cells of
@@ -1842,7 +1852,7 @@
 @table @asis
 @item @code{-s @var{grade}}
 @itemx @code{--grade @var{grade}}
-Select the compilation model. The @var{grade} should be a base
+Select the compilation model.  The @var{grade} should be a base
 grade with zero or more grade modifiers appended.
 The base grades are @samp{none}, @samp{reg}, @samp{jump}, @samp{asm_jump},
 @samp{fast}, and @samp{asm_fast}.
@@ -2036,7 +2046,7 @@
 This option will generate smaller executables, but will not allow the
 use of code that uses the layout information (e.g. @samp{functor},
 @samp{arg}). Using such code will result in undefined behaviour at
-runtime. The C code also needs to be compiled with
+runtime.  The C code also needs to be compiled with
 @samp{-DNO_TYPE_LAYOUT}.
 
 @sp 1
@@ -2192,7 +2202,7 @@
 different to the @file{@var{module}.opt} as @file{@var{module}.trans_opt}
 files may depend on other @file{@var{module}.trans_opt} files.
 @file{@var{module}.opt} files may only depend on the
- at file{@var{module}.m} file.
+ at file{@var{module}.m} file.  
 
 @sp 1
 @item --split-c-files
@@ -2242,7 +2252,7 @@
 
 @item --intermod-inline-simple-threshold @var{threshold}
 Similar to --inline-simple-threshold, except used to determine which
-predicates should be included in @samp{.opt} files. Note that changing this
+predicates should be included in @samp{.opt} files.  Note that changing this
 between writing the @samp{.opt} file and compiling to C may cause link errors,
 and too high a value may result in reduced performance.
 
@@ -2272,7 +2282,7 @@
 
 @sp 1
 @item --optimize-unused-args
-Remove unused predicate arguments. The compiler will
+Remove unused predicate arguments.  The compiler will
 generate more efficient code for polymorphic predicates.
 
 @sp 1
-- 
Fergus Henderson <fjh at cs.mu.oz.au>   |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>   |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3         |     -- the last words of T. S. Garp.
Previous message: diff: library/Mmakefile & termination analysis
Next message: diff: library/Mmakefile & termination analysis
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the developers mailing list