From 9eb506edc2dbeccab58df227c82f751b12ae248b Mon Sep 17 00:00:00 2001 From: Zoltan Somogyi Date: Wed, 30 Jul 2025 03:32:22 +0200 Subject: [PATCH] Move some existing chapters around. --- doc/user_guide.texi | 1234 +++++++++++++++++++++---------------------- 1 file changed, 617 insertions(+), 617 deletions(-) diff --git a/doc/user_guide.texi b/doc/user_guide.texi index 3253cb0cc..eaaa0d9f7 100644 --- a/doc/user_guide.texi +++ b/doc/user_guide.texi @@ -118,11 +118,11 @@ During that time, we advise you to look at @menu * Introduction:: General overview. -* Filenames:: File naming conventions. * Introduction to mmc:: Introduction to compiling Mercury program * Grades:: Mercury grades * Running:: Runninng Mercury programs * Compilation details:: The Mercury compilation process in detail +* Filenames:: File naming conventions. * Using Mmake:: ``Mercury Make'', a tool for building Mercury programs. * Libraries:: Creating and using libraries of Mercury modules. * Debugging:: The Mercury debugger @samp{mdb}. @@ -172,248 +172,6 @@ The second is that targeting C yields the fastest executables. @c ---------------------------------------------------------------------------- -@node Filenames -@chapter File naming conventions -@cindex File extensions -@cindex File names - -Mercury source files must have a name that ends with the @file{.m} extension. -Each other kind of files (documented below) is identified by its own extension. - -For source files, -the part of the filename before the @file{.m} extension can be anything, -It is simplest if it is the full name of the module contained in the file, -because if it isn't, for any module in a program, -then you will need to tell the compiler -to construct a module-name-to-filename map. -You can do this using a command such as @code{mmc -f *.m} -(if all the source files in the program are in the current directory). - -For all the other kinds files mentioned in this chapter, -which are always constructed automatically by the Mercury compiler, -the part of the filename before the suffix -will be the fully qualified name of the module that the file belongs to. - -@findex --use-subdirs -For historical reasons, the default behaviour -is for these files to be created in the current directory. -However, -if you use the @samp{--use-subdirs} option to @samp{mmc} or @samp{mmake}, -all these intermediate files will be created in a @file{Mercury} subdirectory, -where you can happily ignore them. -(With @samp{mmc --make}, @samp{--use-subdirs} is the default.) - -The rest of this chapter lists the extensions -@c *most* of the kinds of files; there are many more now. -@c XXX We should consider -@c - moving the rest of this chapter to a spot close to the end; and/or -@c - adding to it all the other extensions in compiler/file_names.m. -used by the files automatically generated by the Mercury compiler. -It also briefly introduces their roles. -This is just in case you are interested. -You don't actually need to know anything about them; -if you want, you can skip now to the next chapter. - -@node Interface files -@section Interface files - -Files whose names end in -@file{.int}, @file{.int2}, @file{.int0} and @file{.int3} are interface files. -In the order of their usual creation, - -@itemize - -@item -@findex --make-short-interface -@findex --make-short-int -@file{.int3} files are created by invoking @samp{mmc} with the -@samp{--make-short-interface} (or @samp{--make-short-int}) option. -Roughly, they contain basic information about the entities -defined in the interface section of the module, -and exported from the module to all other modules importing this one. -Their purpose is to provide the information needed -for the generation of the other kinds of interface files below. - -@item -@findex --make-private-interface -@findex --make-priv-interface -@file{.int0} files are created by invoking @samp{mmc} with the -@samp{--make-private-interface} (or @samp{--make-priv-int}) option. -They contain a list of the entities -defined in the implementation section of the module -that are available only to its own submodules. -Modules that do not have any submodules won't have @file{.int0} files. - -@item -@findex --make-interface -@findex --make-int -@file{.int} and @file{.int2} are both created, -at the same time, by invoking @samp{mmc} with the -@samp{--make-interface} (or @samp{--make--int}) option. -The difference between them is that e.g.@: -@file{module_a.int} is intended to contain -everything that is needed by another module, such as @samp{module_b}, -that imports @samp{module_a} @emph{directly}, -while @file{module_a.int2} is intended to contain what is needed -by another module, such as @samp{module_c}, -that imports @samp{module_a} @emph{indirectly}. - -@end itemize - -@node Optimization files -@section Optimization files - -Files whose names end in -@file{.opt} and @file{.trans_opt} -are files used for optimization; -these are generated automatically by the compiler. - -@itemize - -@item -@findex --make-transitive-optimization-interface -@findex --make-optimization-interface -@file{.opt} files are used for inter-module optimization, -and are created using the @samp{--make-optimization-interface} -(or @samp{--make-opt-int}) option. - -@item -@findex --make-transitive-optimization-interface -@findex --make-trans-opt -@file{.trans_opt} files -are used for transitive inter-module optimization, -and are created using the @samp{--make-transitive-optimization-interface} -(or @samp{--make-trans-opt}) option. - -@end itemize - -@node Timestamp files -@section Timestamp files - -Since the interface of a module changes less often than its implementation, -the @file{.int}, @file{.int0}, @file{.int2}, @file{.int3}, @file{.opt}, -and @file{.trans_opt} files will often remain unchanged when they are rebuilt. -To avoid unnecessary recompilations of the clients of the module, -the timestamps on these files are updated only if their contents change. -Files with the suffixes @file{.date}, @file{.date0}, @file{.date3}, -@file{.optdate}, and @file{.trans_opt_date} serve as timestamp files: -they each record the last time when the file or files it represents -has last been checked for being up to date. -(@file{.date} files serve as the last-time-this-was-checked timestamp -for both @file{.int} and @file{.int2} files.) - -The Mercury implementation uses these timestamp files -when deciding whether the files they represent need to be rebuilt. - -@node Mmakefile fragment files -@section Mmakefile fragment files - -The @samp{mmake} build tool -gets the information it needs about the program being built -from Makefile fragments automatically generated by the Mercury compiler. -These fragments come from files with the following extensions. - -@itemize -@item -@file{.dep} files are automatically generated Makefile fragments -which contain the rules for an entire program. -@item -@file{.dv} files are automatically generated Makefile fragments -which contain variable definitions for an entire program. -@item -@file{.d} files are automatically generated Makefile fragments -which contain the dependencies for a module. -@end itemize - -@file{.dep} and @file{.dv} files are built -as part of the initial setup of the program, -when @samp{mmc} is invoked with @samp{--generate-dependencies} -(or some related options). -@file{.d} files contain information about a single module, -and they are updated (if needed) by every recompilation of that module. - -@node Files generated when targeting C -@section Files generated when targeting C - -@itemize - -@item -@file{.c} files are C source code. - -@item -@file{.o} files are object code (generated by C compilers other than MSVC). - -@item -@file{.obj} files are object code (generated by MSVC). - -@item -@file{.pic_o} files are object code files -that contain position-independent (PIC) code. - -@c XXX "egrep lpic_o *.m" in the compiler directory yields no hits. -@c c8d718ec57a7517bf8427ca375ee27dc6864b700 in 2016 deleted lpic_o support. -@c @item -@c @file{.lpic_o} files are object code files -@c that can be linked with shared libraries, -@c but don't necessarily contain position-independent code themselves. - -@end itemize - -@file{.mh} and @file{.mih} files are C header files -generated by the Mercury compiler. -Their non-standard extensions are necessary -to avoid conflicts with system header files. - -@itemize -@item -@file{.mh} files contain the declarations of C function versions -of Mercury predicates and/or functions that are exported to C code -by @samp{foreign_export} pragmas written by programmers. -They are intended to be @code{#included} by the user-written C code -that the @samp{foreign_export} pragmas were intended for. -@item -@file{.mih} files are C header files -that are part of the Mercury implementation. -They are intended to be @code{#included} only by C source files -that are generated automatically by the Mercury compiler. -@end itemize - -@node Files generated when targeting Java -@section Files generated when targeting Java - -@itemize -@item @file{.java} files are Java source code, -@item @file{.class} files are Java bytecode, and -@item @file{.jar} files are Java archives. -@end itemize - -@node Files generated when targeting c# -@section Files generated when targeting c# - -@c when we support shared libraries on Windows .dll will also be used for them. -@itemize -@item @file{.cs} files are C# source code, -@item @file{.dll} files are library assemblies, and -@item @file{.exe} files are process assemblies. -@end itemize - -@c When smart recompilation (@pxref{Auxiliary output options}) is enabled, -@c @file{.c_date}, @file{.cs_date} and @file{.java_date} files -@c perform the same function for -@c @file{.c}, @file{.cs} and @file{.java} files respectively -@c as e.g. @file{.date3} files do for @file{.int3} files: -@c when smart recompilation works out -@c that a module does not need to be recompiled, -@c it updates the timestamp of the @emph{timestamp file} for the target file, -@c but leaves the timestamp of the target file itself unchanged. -@c @findex --smart-recompilation - -@c @file{.used} files contain dependency information for smart recompilation -@c (@pxref{Auxiliary output options}). -@c @findex --smart-recompilation - -@c ---------------------------------------------------------------------------- - @node Introduction to mmc @chapter Introduction to compiling Mercury programs @@ -998,6 +756,380 @@ please see ZZZ @c @ref ZZZ TODO +@ignore + +This is the original documentation of the --grade option. +It is saved here to serve as a mine of ideas and text +for a new chapter on grades. + + @item @code{-s @var{grade}} + @itemx @code{--grade @var{grade}} + @findex -s + @findex --grade + Select the compilation model. + The @var{grade} should be a @samp{.} separated list + in which the first element is a @samp{base grade}, + and each following element (if any) is a @samp{grade modifier}. + + @cindex csharp (compilation grade) + @cindex java (compilation grade) + + @cindex hlc (compilation grade) + + @cindex asm_fast (compilation grade) + @cindex none (compilation grade) + @cindex reg (compilation grade) + + The base grade specifies + what target language to compile the Mercury program to, + and if the compiler can do this in several different ways, + selects one of those ways. + The available base grades are the following. + + @c What target language to use (C, C# or Java), + @c for C, whether to generate idiomatic C or assembly-like code, + @c and if the latter, what combination of GNU C extensions to use. + @c The options are + @c which each specify the named language as the target, + @c and @samp{none}, @samp{reg}, and @samp{asm_fast}, + @c which call for assembly-like C code, + @c with @samp{reg} and @samp{asm_fast} both calling for + @c the use of GNU C's extension for storing global variables in registers, + @c and @samp{asm_fast} calling for the use of two GNU C extensions + @c that together allow direct gotos to labels in other functions, + @c even in other modules. + + @table @asis + + @item @samp{hlc} + This base grade calls for generating idiomatic C, + which we call high-level C. + + @item @samp{none}, @samp{reg}, and @samp{asm_fast} + These base grades call for generating assembly-like C code, + which we call low-level C. + @samp{none} calls for generating standard C without using any GNU C extensions. + @samp{reg} and @samp{asm_fast} both call for + the use of GNU C's extension for storing global variables in registers, + while @samp{asm_fast} also calls for the use of two GNU C extensions + that together allow direct gotos to labels in other functions, + even in other modules. + In general, the more GNU C extensions are used, + the faster the program will be, + but some platforms, compilers or compiler versions + do not support specific extensions. + + @item @samp{csharp} + This base grade calls for generating C#. + + @item @samp{java} + This base grade calls for generating Java. + @end table + + The default base grade is system dependent, + but will be either @samp{hlc} or @samp{asm_fast}, + as these are the two fastest. + + @c @cindex asm_jump (compilation grade) + @c @cindex fast (compilation grade) + @c @cindex jump (compilation grade) + + @c @cindex .agc (grade modifier) + @c @cindex .ssdebug (grade modifier) + @cindex .debug (grade modifier) + @cindex .decldebug (grade modifier) + @cindex .gc (grade modifier) + @cindex .memprof (grade modifier) + @cindex .mm (grade modifier) + @cindex .par (grade modifier) + @cindex .prof (grade modifier) + @cindex .profdeep (grade modifier) + @cindex .spf (grade modifier) + @cindex .stseg (grade modifier) + @cindex .threadscope (grade modifier) + @cindex .tr (grade modifier) + + The grade modifiers may be given in any order. + Each grade modifier sets one or more compilation model options. + The available options each belong to a set of mutually exclusive alternatives + governing a single aspect of the compilation model. + The set of aspects and their alternatives are as follows. + Note that not all grade modifiers are applicable to all grades + (most apply only when targeting C), + and not all grade modifiers are compatible with each other. + + @table @asis + @item garbage collection + The default is no garbage collection beyond what the target language provides. + C# and Java have their own builtin garbage collectors, but C does not. + Since garbage collection is essential for all programs + other than those with @emph{very} short runtimes, + base grades that target C + are usually followed by the @samp{.gc} grade modifier, which calls for + the use of the Boehm-Demers-Weiser conservative collector for C. + @c @samp{.agc} + + @item profiling + The default is no profiling. + The grade modifier @samp{.prof} calls for gprof-style profiling; + the grade modifier @samp{.memprof} calls for profiling of memory usage; + while the grade modifier @samp{.profdeep} calls for deep profiling. + See @ref{Profiling} for an explanation + of the differences between these forms of profiling, + all of which are available only when targeting C. + + @item trailing + The default is no trailing. + Applications that need trailing should specify the grade modifier @samp{.tr}. + Trailing is available only when targeting C. + + (A trail is a data structure + that records changes to a mutable data store during normal execution + so that each of those changes can be unwound (undone) + when execution backtracks to the point in time before it was made. + Mercury normally needs a trail + only when executing programs that use constraint solvers. + While the act of posting a constraint in such a program + is a declarative action, + its implementation requires updating a constraint store.) + + @item floating point precision + By default when targeting C, + the Mercury @samp{float} type is implemented + as an IEEE 754 double-precision floating point number, + which occupies 64 bits of space. + On platforms whose word size is 32 bits, + users whose programs do not require double precision + may improve memory consumption and speed + by specifying the grade modifier @samp{.spf} + (short for single-precision float), + which calls for implementing all Mercury floats + as IEEE 754 single-precision floating point numbers. + Note that on 64 bit platforms, using single-precision floats + definitely will @emph{not} improve memory consumption, + and will probably not improve speed. + On the other hand, it may simplify the use of C APIs + that exclusively use single precision floats. + + For target languages other than C, + the Mercury @samp{float} type is always implemented + as a double-precision floating point number, + and the @samp{.spf} modifier is not supported. + + @item stack size + When generating low-level C, + Mercury implements its own stacks (two of them). + The default is to make each stack a fixed size + (usually a relatively large size, + though the size of each stack can be controlled using runtime options). + We make the page(s) at the tops of the stacks inaccessible, + so that a stack overflow, + instead of accessing and overwriting memory effectively randomly, + causes the operating system to send a signal to the program. + If not caught and handled, this signal will abort the program, + minimizing the damage. + + However, for programs for which this is not acceptable, + users can specify the @samp{.stseg} grade component. + This calls for each stack to be composed of + small memory segments chained together in a list. + When there is no room in the current segment for a new stack frame, + we simply allocate a new segment and add it to the list. + This approach has higher overhead, + since calls to, and returns from, procedures must execute more code, + but it avoids imposing any limit on stack size + other than the size of available memory. + + When targeting anything other than low-level C, + the stack is always managed by the implementation of the target language, + so for them, the @samp{.stseg} modifier is neither relevant nor supported. + + @item debugging + The default is to generate executables that do not support debugging. + However, when generating low-level C code, + specifying one of the grade modifiers @samp{.debug} and @samp{.decldebug} + will cause the compiler to generate executables + that can be debugged using the Mercury debugger @samp{mdb}. + The difference between them is that + the declarative debugging aspects of @samp{mdb} + will work only with @samp{.decldebug}. + The price of this is that @samp{.decldebug} results + in significantly larger executable files. + @c @samp{.ssdebug} + + @item threads + The default is whatever thread support is provided by the target language. + When targeting C, + thread support can be enabled by specifying the grade modifier @samp{.par}. + When targeting low-level C, + this also enables the use of the parallel conjunction operator @samp{&}. + Since Mercury implements parallel conjunctions + only in low-level C grades with the @samp{.par} grade modifier, + in every other situation, the compiler silently converts + every occurrence of @samp{&} to a comma, + the usual @emph{sequential} conjunctions operator. + + @item thread profiling + In low-level C grades with the grade modifier @samp{.par}, + users can enable support for ThreadScope-style thread profiling + by also specifying the grade module @samp{.threadscope}. + The default is no support for thread profiling. + Note that form of profiling is experimental, + and it is not currently supported. + + @item minimal model tabling + The default is no support for minimal model evaluation. + When targeting low-level C, users can specify the grade modifier @samp{.mm}, + which enables support for minimal model tabled evaluation of procedures. + The grade component @samp{.mmsc} is a synonym for @samp{.mm}, + standing for minimal model via stack copying, + since the standard implementation works by copying stack segments. + (The synonym exists because Mercury also has + another implementation of minimal model tabling. + This other implementation, which is incomplete + and was only ever useful for experiments, + is based on a completely different implementation technique.) + + @end table + + The default grade is system-dependent; + it is chosen at installation time by @samp{configure}, + the auto-configuration script, + but can be overridden if desired + with the environment variable @env{MERCURY_DEFAULT_GRADE}. + @vindex MERCURY_DEFAULT_GRADE + On any given particular installation, + the Mercury runtime system and Mercury standard library + will be installed in only a subset of the possible grades; + you can find out which grades these are + by invoking the Mercury compiler + with the @samp{--output-stdlib-grades} option. + Attempting to use a grade which has not been installed + will result in an error at link time. + (The error message will typically be something like + @samp{ld: can't find library for -lmercury}.) + + The tables below show the options + that are selected by each base grade and grade modifier; + they are followed by descriptions of those options. + + @table @asis + @item @var{Grade} + @var{Options implied}. + @findex --gcc-global-registers + @findex --no-gcc-global-registers + @findex --gcc-nonlocal-gotos + @findex --no-gcc-nonlocal-gotos + @findex --asm-labels + @findex --no-asm-labels + @findex --high-level-code + @findex --no-high-level-code + @findex --target + @findex --csharp + @findex --java + @findex --gc + @findex --profiling + @findex --memory-profiling + @findex --deep-profiling + @findex --use-trail + @findex --record-term-sizes-as-words + @findex --record-term-sizes-as-cells + @findex --single-prec-float + @findex --stack-segments + + @item @samp{hlc} + @code{--target c --high-level-code}. + + @item @samp{none} + @code{--target c --no-gcc-global-registers --no-gcc-nonlocal-gotos --no-asm-labels}. + + @item @samp{reg} + @code{--target c --gcc-global-registers --no-gcc-nonlocal-gotos --no-asm-labels}. + + @c @item @samp{jump} + @c @code{--target c --no-gcc-global-registers --gcc-nonlocal-gotos --no-asm-labels}. + + @c @item @samp{fast} + @c @code{--target c --gcc-global-registers --gcc-nonlocal-gotos --no-asm-labels}. + + @c @item @samp{asm_jump} + @c @code{--target c --no-gcc-global-registers --gcc-nonlocal-gotos --asm-labels}. + + @item @samp{asm_fast} + @code{--target c --gcc-global-registers --gcc-nonlocal-gotos --asm-labels}. + + @item @samp{csharp} + @code{--target csharp --high-level-code}. + + @item @samp{java} + @code{--target java --high-level-code}. + + @item @samp{.gc} + @code{--gc boehm}. + + @c @item @samp{.agc} + @c @code{--gc accurate}. + + @item @samp{.prof} + @code{--profiling}. + + @item @samp{.memprof} + @code{--memory-profiling}. + + @item @samp{.profdeep} + @code{--deep-profiling}. + + @c The following are undocumented because + @c they are basically useless... documenting + @c them would just confuse people. + @c + @c @item @samp{.profall} + @c @code{--profile-calls --profile-time --profile-memory}. + @c (not recommended because --profile-memory interferes with + @c --profile-time) + @c + @c @item @samp{.proftime} + @c @code{--profile-time}. + @c + @c @item @samp{.profcalls} + @c @code{--profile-calls}. + @c + @item @samp{.tr} + @code{--use-trail}. + + @c @item @samp{.tsw} + @c @code{--record-term-sizes-as-words}. + + @c @item @samp{.tsc} + @c @code{--record-term-sizes-as-cells}. + + @item @samp{.spf} + @code{--single-prec-float} + + @item @samp{.stseg} + @code{--stack-segments} + + @item @samp{.debug} + @code{--debug}. + + @item @samp{.decldebug} + @code{--decl-debug}. + + @c @item @samp{.ssdebug} + @c @code{--ss-debug}. + + @item @samp{.par} + @code{--parallel}. + + @item @samp{.threadscope} + @code{--threadscope}. + + @end table + + @end table + +@end ignore + @c ---------------------------------------------------------------------------- @node Running @@ -1227,6 +1359,248 @@ but this can be overridden with the @samp{--heap-size} option. @c ---------------------------------------------------------------------------- +@node Filenames +@chapter File naming conventions +@cindex File extensions +@cindex File names + +Mercury source files must have a name that ends with the @file{.m} extension. +Each other kind of files (documented below) is identified by its own extension. + +For source files, +the part of the filename before the @file{.m} extension can be anything, +It is simplest if it is the full name of the module contained in the file, +because if it isn't, for any module in a program, +then you will need to tell the compiler +to construct a module-name-to-filename map. +You can do this using a command such as @code{mmc -f *.m} +(if all the source files in the program are in the current directory). + +For all the other kinds files mentioned in this chapter, +which are always constructed automatically by the Mercury compiler, +the part of the filename before the suffix +will be the fully qualified name of the module that the file belongs to. + +@findex --use-subdirs +For historical reasons, the default behaviour +is for these files to be created in the current directory. +However, +if you use the @samp{--use-subdirs} option to @samp{mmc} or @samp{mmake}, +all these intermediate files will be created in a @file{Mercury} subdirectory, +where you can happily ignore them. +(With @samp{mmc --make}, @samp{--use-subdirs} is the default.) + +The rest of this chapter lists the extensions +@c *most* of the kinds of files; there are many more now. +@c XXX We should consider +@c - moving the rest of this chapter to a spot close to the end; and/or +@c - adding to it all the other extensions in compiler/file_names.m. +used by the files automatically generated by the Mercury compiler. +It also briefly introduces their roles. +This is just in case you are interested. +You don't actually need to know anything about them; +if you want, you can skip now to the next chapter. + +@node Interface files +@section Interface files + +Files whose names end in +@file{.int}, @file{.int2}, @file{.int0} and @file{.int3} are interface files. +In the order of their usual creation, + +@itemize + +@item +@findex --make-short-interface +@findex --make-short-int +@file{.int3} files are created by invoking @samp{mmc} with the +@samp{--make-short-interface} (or @samp{--make-short-int}) option. +Roughly, they contain basic information about the entities +defined in the interface section of the module, +and exported from the module to all other modules importing this one. +Their purpose is to provide the information needed +for the generation of the other kinds of interface files below. + +@item +@findex --make-private-interface +@findex --make-priv-interface +@file{.int0} files are created by invoking @samp{mmc} with the +@samp{--make-private-interface} (or @samp{--make-priv-int}) option. +They contain a list of the entities +defined in the implementation section of the module +that are available only to its own submodules. +Modules that do not have any submodules won't have @file{.int0} files. + +@item +@findex --make-interface +@findex --make-int +@file{.int} and @file{.int2} are both created, +at the same time, by invoking @samp{mmc} with the +@samp{--make-interface} (or @samp{--make--int}) option. +The difference between them is that e.g.@: +@file{module_a.int} is intended to contain +everything that is needed by another module, such as @samp{module_b}, +that imports @samp{module_a} @emph{directly}, +while @file{module_a.int2} is intended to contain what is needed +by another module, such as @samp{module_c}, +that imports @samp{module_a} @emph{indirectly}. + +@end itemize + +@node Optimization files +@section Optimization files + +Files whose names end in +@file{.opt} and @file{.trans_opt} +are files used for optimization; +these are generated automatically by the compiler. + +@itemize + +@item +@findex --make-transitive-optimization-interface +@findex --make-optimization-interface +@file{.opt} files are used for inter-module optimization, +and are created using the @samp{--make-optimization-interface} +(or @samp{--make-opt-int}) option. + +@item +@findex --make-transitive-optimization-interface +@findex --make-trans-opt +@file{.trans_opt} files +are used for transitive inter-module optimization, +and are created using the @samp{--make-transitive-optimization-interface} +(or @samp{--make-trans-opt}) option. + +@end itemize + +@node Timestamp files +@section Timestamp files + +Since the interface of a module changes less often than its implementation, +the @file{.int}, @file{.int0}, @file{.int2}, @file{.int3}, @file{.opt}, +and @file{.trans_opt} files will often remain unchanged when they are rebuilt. +To avoid unnecessary recompilations of the clients of the module, +the timestamps on these files are updated only if their contents change. +Files with the suffixes @file{.date}, @file{.date0}, @file{.date3}, +@file{.optdate}, and @file{.trans_opt_date} serve as timestamp files: +they each record the last time when the file or files it represents +has last been checked for being up to date. +(@file{.date} files serve as the last-time-this-was-checked timestamp +for both @file{.int} and @file{.int2} files.) + +The Mercury implementation uses these timestamp files +when deciding whether the files they represent need to be rebuilt. + +@node Mmakefile fragment files +@section Mmakefile fragment files + +The @samp{mmake} build tool +gets the information it needs about the program being built +from Makefile fragments automatically generated by the Mercury compiler. +These fragments come from files with the following extensions. + +@itemize +@item +@file{.dep} files are automatically generated Makefile fragments +which contain the rules for an entire program. +@item +@file{.dv} files are automatically generated Makefile fragments +which contain variable definitions for an entire program. +@item +@file{.d} files are automatically generated Makefile fragments +which contain the dependencies for a module. +@end itemize + +@file{.dep} and @file{.dv} files are built +as part of the initial setup of the program, +when @samp{mmc} is invoked with @samp{--generate-dependencies} +(or some related options). +@file{.d} files contain information about a single module, +and they are updated (if needed) by every recompilation of that module. + +@node Files generated when targeting C +@section Files generated when targeting C + +@itemize + +@item +@file{.c} files are C source code. + +@item +@file{.o} files are object code (generated by C compilers other than MSVC). + +@item +@file{.obj} files are object code (generated by MSVC). + +@item +@file{.pic_o} files are object code files +that contain position-independent (PIC) code. + +@c XXX "egrep lpic_o *.m" in the compiler directory yields no hits. +@c c8d718ec57a7517bf8427ca375ee27dc6864b700 in 2016 deleted lpic_o support. +@c @item +@c @file{.lpic_o} files are object code files +@c that can be linked with shared libraries, +@c but don't necessarily contain position-independent code themselves. + +@end itemize + +@file{.mh} and @file{.mih} files are C header files +generated by the Mercury compiler. +Their non-standard extensions are necessary +to avoid conflicts with system header files. + +@itemize +@item +@file{.mh} files contain the declarations of C function versions +of Mercury predicates and/or functions that are exported to C code +by @samp{foreign_export} pragmas written by programmers. +They are intended to be @code{#included} by the user-written C code +that the @samp{foreign_export} pragmas were intended for. +@item +@file{.mih} files are C header files +that are part of the Mercury implementation. +They are intended to be @code{#included} only by C source files +that are generated automatically by the Mercury compiler. +@end itemize + +@node Files generated when targeting Java +@section Files generated when targeting Java + +@itemize +@item @file{.java} files are Java source code, +@item @file{.class} files are Java bytecode, and +@item @file{.jar} files are Java archives. +@end itemize + +@node Files generated when targeting c# +@section Files generated when targeting c# + +@c when we support shared libraries on Windows .dll will also be used for them. +@itemize +@item @file{.cs} files are C# source code, +@item @file{.dll} files are library assemblies, and +@item @file{.exe} files are process assemblies. +@end itemize + +@c When smart recompilation (@pxref{Auxiliary output options}) is enabled, +@c @file{.c_date}, @file{.cs_date} and @file{.java_date} files +@c perform the same function for +@c @file{.c}, @file{.cs} and @file{.java} files respectively +@c as e.g. @file{.date3} files do for @file{.int3} files: +@c when smart recompilation works out +@c that a module does not need to be recompiled, +@c it updates the timestamp of the @emph{timestamp file} for the target file, +@c but leaves the timestamp of the target file itself unchanged. +@c @findex --smart-recompilation + +@c @file{.used} files contain dependency information for smart recompilation +@c (@pxref{Auxiliary output options}). +@c @findex --smart-recompilation + +@c ---------------------------------------------------------------------------- + @node Using Mmake @chapter Using Mmake @pindex mmake @@ -7191,380 +7565,6 @@ Another work-around that sometimes works is to set the environment variable @c ---------------------------------------------------------------------------- -@ignore - -This is the original documentation of the --grade option. -It is saved here to serve as a mine of ideas and text -for a new chapter on grades. - - @item @code{-s @var{grade}} - @itemx @code{--grade @var{grade}} - @findex -s - @findex --grade - Select the compilation model. - The @var{grade} should be a @samp{.} separated list - in which the first element is a @samp{base grade}, - and each following element (if any) is a @samp{grade modifier}. - - @cindex csharp (compilation grade) - @cindex java (compilation grade) - - @cindex hlc (compilation grade) - - @cindex asm_fast (compilation grade) - @cindex none (compilation grade) - @cindex reg (compilation grade) - - The base grade specifies - what target language to compile the Mercury program to, - and if the compiler can do this in several different ways, - selects one of those ways. - The available base grades are the following. - - @c What target language to use (C, C# or Java), - @c for C, whether to generate idiomatic C or assembly-like code, - @c and if the latter, what combination of GNU C extensions to use. - @c The options are - @c which each specify the named language as the target, - @c and @samp{none}, @samp{reg}, and @samp{asm_fast}, - @c which call for assembly-like C code, - @c with @samp{reg} and @samp{asm_fast} both calling for - @c the use of GNU C's extension for storing global variables in registers, - @c and @samp{asm_fast} calling for the use of two GNU C extensions - @c that together allow direct gotos to labels in other functions, - @c even in other modules. - - @table @asis - - @item @samp{hlc} - This base grade calls for generating idiomatic C, - which we call high-level C. - - @item @samp{none}, @samp{reg}, and @samp{asm_fast} - These base grades call for generating assembly-like C code, - which we call low-level C. - @samp{none} calls for generating standard C without using any GNU C extensions. - @samp{reg} and @samp{asm_fast} both call for - the use of GNU C's extension for storing global variables in registers, - while @samp{asm_fast} also calls for the use of two GNU C extensions - that together allow direct gotos to labels in other functions, - even in other modules. - In general, the more GNU C extensions are used, - the faster the program will be, - but some platforms, compilers or compiler versions - do not support specific extensions. - - @item @samp{csharp} - This base grade calls for generating C#. - - @item @samp{java} - This base grade calls for generating Java. - @end table - - The default base grade is system dependent, - but will be either @samp{hlc} or @samp{asm_fast}, - as these are the two fastest. - - @c @cindex asm_jump (compilation grade) - @c @cindex fast (compilation grade) - @c @cindex jump (compilation grade) - - @c @cindex .agc (grade modifier) - @c @cindex .ssdebug (grade modifier) - @cindex .debug (grade modifier) - @cindex .decldebug (grade modifier) - @cindex .gc (grade modifier) - @cindex .memprof (grade modifier) - @cindex .mm (grade modifier) - @cindex .par (grade modifier) - @cindex .prof (grade modifier) - @cindex .profdeep (grade modifier) - @cindex .spf (grade modifier) - @cindex .stseg (grade modifier) - @cindex .threadscope (grade modifier) - @cindex .tr (grade modifier) - - The grade modifiers may be given in any order. - Each grade modifier sets one or more compilation model options. - The available options each belong to a set of mutually exclusive alternatives - governing a single aspect of the compilation model. - The set of aspects and their alternatives are as follows. - Note that not all grade modifiers are applicable to all grades - (most apply only when targeting C), - and not all grade modifiers are compatible with each other. - - @table @asis - @item garbage collection - The default is no garbage collection beyond what the target language provides. - C# and Java have their own builtin garbage collectors, but C does not. - Since garbage collection is essential for all programs - other than those with @emph{very} short runtimes, - base grades that target C - are usually followed by the @samp{.gc} grade modifier, which calls for - the use of the Boehm-Demers-Weiser conservative collector for C. - @c @samp{.agc} - - @item profiling - The default is no profiling. - The grade modifier @samp{.prof} calls for gprof-style profiling; - the grade modifier @samp{.memprof} calls for profiling of memory usage; - while the grade modifier @samp{.profdeep} calls for deep profiling. - See @ref{Profiling} for an explanation - of the differences between these forms of profiling, - all of which are available only when targeting C. - - @item trailing - The default is no trailing. - Applications that need trailing should specify the grade modifier @samp{.tr}. - Trailing is available only when targeting C. - - (A trail is a data structure - that records changes to a mutable data store during normal execution - so that each of those changes can be unwound (undone) - when execution backtracks to the point in time before it was made. - Mercury normally needs a trail - only when executing programs that use constraint solvers. - While the act of posting a constraint in such a program - is a declarative action, - its implementation requires updating a constraint store.) - - @item floating point precision - By default when targeting C, - the Mercury @samp{float} type is implemented - as an IEEE 754 double-precision floating point number, - which occupies 64 bits of space. - On platforms whose word size is 32 bits, - users whose programs do not require double precision - may improve memory consumption and speed - by specifying the grade modifier @samp{.spf} - (short for single-precision float), - which calls for implementing all Mercury floats - as IEEE 754 single-precision floating point numbers. - Note that on 64 bit platforms, using single-precision floats - definitely will @emph{not} improve memory consumption, - and will probably not improve speed. - On the other hand, it may simplify the use of C APIs - that exclusively use single precision floats. - - For target languages other than C, - the Mercury @samp{float} type is always implemented - as a double-precision floating point number, - and the @samp{.spf} modifier is not supported. - - @item stack size - When generating low-level C, - Mercury implements its own stacks (two of them). - The default is to make each stack a fixed size - (usually a relatively large size, - though the size of each stack can be controlled using runtime options). - We make the page(s) at the tops of the stacks inaccessible, - so that a stack overflow, - instead of accessing and overwriting memory effectively randomly, - causes the operating system to send a signal to the program. - If not caught and handled, this signal will abort the program, - minimizing the damage. - - However, for programs for which this is not acceptable, - users can specify the @samp{.stseg} grade component. - This calls for each stack to be composed of - small memory segments chained together in a list. - When there is no room in the current segment for a new stack frame, - we simply allocate a new segment and add it to the list. - This approach has higher overhead, - since calls to, and returns from, procedures must execute more code, - but it avoids imposing any limit on stack size - other than the size of available memory. - - When targeting anything other than low-level C, - the stack is always managed by the implementation of the target language, - so for them, the @samp{.stseg} modifier is neither relevant nor supported. - - @item debugging - The default is to generate executables that do not support debugging. - However, when generating low-level C code, - specifying one of the grade modifiers @samp{.debug} and @samp{.decldebug} - will cause the compiler to generate executables - that can be debugged using the Mercury debugger @samp{mdb}. - The difference between them is that - the declarative debugging aspects of @samp{mdb} - will work only with @samp{.decldebug}. - The price of this is that @samp{.decldebug} results - in significantly larger executable files. - @c @samp{.ssdebug} - - @item threads - The default is whatever thread support is provided by the target language. - When targeting C, - thread support can be enabled by specifying the grade modifier @samp{.par}. - When targeting low-level C, - this also enables the use of the parallel conjunction operator @samp{&}. - Since Mercury implements parallel conjunctions - only in low-level C grades with the @samp{.par} grade modifier, - in every other situation, the compiler silently converts - every occurrence of @samp{&} to a comma, - the usual @emph{sequential} conjunctions operator. - - @item thread profiling - In low-level C grades with the grade modifier @samp{.par}, - users can enable support for ThreadScope-style thread profiling - by also specifying the grade module @samp{.threadscope}. - The default is no support for thread profiling. - Note that form of profiling is experimental, - and it is not currently supported. - - @item minimal model tabling - The default is no support for minimal model evaluation. - When targeting low-level C, users can specify the grade modifier @samp{.mm}, - which enables support for minimal model tabled evaluation of procedures. - The grade component @samp{.mmsc} is a synonym for @samp{.mm}, - standing for minimal model via stack copying, - since the standard implementation works by copying stack segments. - (The synonym exists because Mercury also has - another implementation of minimal model tabling. - This other implementation, which is incomplete - and was only ever useful for experiments, - is based on a completely different implementation technique.) - - @end table - - The default grade is system-dependent; - it is chosen at installation time by @samp{configure}, - the auto-configuration script, - but can be overridden if desired - with the environment variable @env{MERCURY_DEFAULT_GRADE}. - @vindex MERCURY_DEFAULT_GRADE - On any given particular installation, - the Mercury runtime system and Mercury standard library - will be installed in only a subset of the possible grades; - you can find out which grades these are - by invoking the Mercury compiler - with the @samp{--output-stdlib-grades} option. - Attempting to use a grade which has not been installed - will result in an error at link time. - (The error message will typically be something like - @samp{ld: can't find library for -lmercury}.) - - The tables below show the options - that are selected by each base grade and grade modifier; - they are followed by descriptions of those options. - - @table @asis - @item @var{Grade} - @var{Options implied}. - @findex --gcc-global-registers - @findex --no-gcc-global-registers - @findex --gcc-nonlocal-gotos - @findex --no-gcc-nonlocal-gotos - @findex --asm-labels - @findex --no-asm-labels - @findex --high-level-code - @findex --no-high-level-code - @findex --target - @findex --csharp - @findex --java - @findex --gc - @findex --profiling - @findex --memory-profiling - @findex --deep-profiling - @findex --use-trail - @findex --record-term-sizes-as-words - @findex --record-term-sizes-as-cells - @findex --single-prec-float - @findex --stack-segments - - @item @samp{hlc} - @code{--target c --high-level-code}. - - @item @samp{none} - @code{--target c --no-gcc-global-registers --no-gcc-nonlocal-gotos --no-asm-labels}. - - @item @samp{reg} - @code{--target c --gcc-global-registers --no-gcc-nonlocal-gotos --no-asm-labels}. - - @c @item @samp{jump} - @c @code{--target c --no-gcc-global-registers --gcc-nonlocal-gotos --no-asm-labels}. - - @c @item @samp{fast} - @c @code{--target c --gcc-global-registers --gcc-nonlocal-gotos --no-asm-labels}. - - @c @item @samp{asm_jump} - @c @code{--target c --no-gcc-global-registers --gcc-nonlocal-gotos --asm-labels}. - - @item @samp{asm_fast} - @code{--target c --gcc-global-registers --gcc-nonlocal-gotos --asm-labels}. - - @item @samp{csharp} - @code{--target csharp --high-level-code}. - - @item @samp{java} - @code{--target java --high-level-code}. - - @item @samp{.gc} - @code{--gc boehm}. - - @c @item @samp{.agc} - @c @code{--gc accurate}. - - @item @samp{.prof} - @code{--profiling}. - - @item @samp{.memprof} - @code{--memory-profiling}. - - @item @samp{.profdeep} - @code{--deep-profiling}. - - @c The following are undocumented because - @c they are basically useless... documenting - @c them would just confuse people. - @c - @c @item @samp{.profall} - @c @code{--profile-calls --profile-time --profile-memory}. - @c (not recommended because --profile-memory interferes with - @c --profile-time) - @c - @c @item @samp{.proftime} - @c @code{--profile-time}. - @c - @c @item @samp{.profcalls} - @c @code{--profile-calls}. - @c - @item @samp{.tr} - @code{--use-trail}. - - @c @item @samp{.tsw} - @c @code{--record-term-sizes-as-words}. - - @c @item @samp{.tsc} - @c @code{--record-term-sizes-as-cells}. - - @item @samp{.spf} - @code{--single-prec-float} - - @item @samp{.stseg} - @code{--stack-segments} - - @item @samp{.debug} - @code{--debug}. - - @item @samp{.decldebug} - @code{--decl-debug}. - - @c @item @samp{.ssdebug} - @c @code{--ss-debug}. - - @item @samp{.par} - @code{--parallel}. - - @item @samp{.threadscope} - @code{--threadscope}. - - @end table - - @end table - -@end ignore - @node Invocation @chapter Invocation