Next: , Previous: Running, Up: Top   [Contents][Index]


5 Using Mmake

Mmake, short for “Mercury Make”, is a tool for building Mercury programs. The same functionality is now provided in ‘mmc’ directly by using the ‘--make’ option:

mmc --make main-module

The usage of Mmake is discouraged, not least because it works only when targeting C.

Mmake is built on top of GNU Make. With Mmake, building even a complicated Mercury program consisting of a number of modules is as simple as

mmc -f source-files
mmake main-module.depend
mmake main-module

Mmake only recompiles those files that need to be recompiled, based on automatically generated dependency information. Most of the dependencies are stored in .d files that are automatically recomputed every time you recompile, so they are never out-of-date. A little bit of the dependency information is stored in .dep and .dv files which are more expensive to recompute. The ‘mmake main-module.depend’ command which recreates the main-module.dep and main-module.dv files needs to be repeated only when you either add a module to your program or remove a module from it. There is no danger of getting an inconsistent executable if you forget this step — instead you will get a compile or link error.

The ‘mmc -f’ step above is only required if there are any source files for which the file name does not match the module name. ‘mmc -f’ generates a file named Mercury.modules containing a mapping from module name to source file. The Mercury.modules file must be updated when a source file for which the file name does not match the module name is added to or removed from the directory.

mmake’ allows you to build more than one program in the same directory. Each program must have its own .dep and .dv files, and therefore you must run ‘mmake program.depend’ for each program. The ‘Mercury.modules’ file is used for all programs in the directory.

If there is a file called Mmake or Mmakefile in the current directory, Mmake will include that file in its automatically generated Makefile. The ‘Mmake’ file can override the default values of various variables used by Mmake’s builtin rules, or it can add additional rules, dependencies, and actions.

Mmake’s builtin rules are defined by the file prefix/lib/mercury/mmake/Mmake.rules (where prefix is /usr/local/mercury-version by default, and version is the version number, e.g. ‘0.6’), as well as the rules and variables in the automatically generated .dep and .dv files. These rules define the following targets:

main-module.depend

Creates the files main-module.dep and main-module.dv from main-module.m and the modules it imports. This step must be performed first. It is also required whenever you wish to change the level of inter-module optimization performed (see Overall optimization options).

main-module.all_ints

Ensure that the interface files for main-module and its imported modules are up-to-date. (If the underlying ‘make’ program does not handle transitive dependencies, this step may be necessary before attempting to make main-module or main-module.check; if the underlying ‘make’ is GNU Make, this step should not be necessary.)

main-module.check

Perform semantic checking on main-module and its imported modules. Error messages are placed in .err files.

main-module

Compiles and links main-module using the Mercury compiler. Error messages are placed in .err files.

libmain-module

Builds a library whose top-level module is main-module. This will build a static object library, a shared object library (for platforms that support it), and the necessary interface files. For more information, see Libraries.

libmain-module.install

Builds and installs a library whose top-level module is main-module. This target will build and install a static object library and (for platforms that support it) a shared object library, for the default grade and also for the additional grades specified in the LIBGRADES variable. It will also build and install the necessary interface files. The variable INSTALL specifies the name of the command to use to install each file, by default ‘cp’. The variable INSTALL_MKDIR specifies the command to use to create directories, by default ‘mkdir -p’.

main-module.clean

Removes the automatically generated files that contain the compiled code of the program and the error messages produced by the compiler. Specifically, this will remove all the ‘.c’, ‘.o’, ‘.pic_o’, ‘.prof’, ‘.used’, ‘.mih’, and ‘.err’ files belonging to the named main-module or its imported modules. Use this target whenever you wish to change compilation model (see Compilation model options). This target is also recommended whenever you wish to change the level of inter-module optimization performed (see Overall optimization options) in addition to the mandatory main-module.depend.

main-module.realclean

Removes all the automatically generated files. In addition to the files removed by main-module.clean, this removes the ‘.int’, ‘.int0’, ‘.int2’, ‘.int3’, ‘.opt’, ‘.trans_opt’, ‘.date’, ‘.date0’, ‘.date3’, ‘.optdate’, ‘.trans_opt_date’, ‘.mh’ and ‘.d’ files belonging to one of the modules of the program, and also the various possible executables, libraries and dependency files for the program as a whole — ‘main-module’, ‘libmain-module.a’, ‘libmain-module.so’, ‘libmain-module.dylib’, ‘main-module.init’, ‘main-module.dep’ and ‘main-module.dv’.

clean

This makes ‘main-module.clean’ for every main-module for which there is a main-module.dep file in the current directory, as well as deleting the profiling files ‘Prof.CallPair’, ‘Prof.Counts’, ‘Prof.Decl’, ‘Prof.MemWords’ and ‘Prof.MemCells’.

realclean

This makes ‘main-module.realclean’ for every main-module for which there is a main-module.dep file in the current directory, as well as deleting the profiling files as per the ‘clean’ target.

The variables used by the builtin rules (and their default values) are defined in the file prefix/lib/mercury/mmake/Mmake.vars, however these may be overridden by user ‘Mmake’ files. Some of the more useful variables are:

MAIN_TARGET

The name of the default target to create if ‘mmake’ is invoked with any target explicitly named on the command line.

MC

The executable that invokes the Mercury compiler.

GRADEFLAGS and EXTRA_GRADEFLAGS

Compilation model options (see Compilation model options) to pass to the Mercury compiler, linker, and other tools (in particular mmc, mgnuc, ml, and c2init).

MCFLAGS and EXTRA_MCFLAGS

Options to pass to the Mercury compiler. (Note that compilation model options should be specified in GRADEFLAGS, not in MCFLAGS.)

MGNUC

The executable that invokes the C compiler.

MGNUCFLAGS and EXTRA_MGNUCFLAGS

Options to pass to the mgnuc script.

CFLAGS and EXTRA_CFLAGS

Options to pass to the C compiler.

JAVACFLAGS and EXTRA_JAVACFLAGS

Options to pass to the Java compiler (if you are using it).

ML

The executable that invokes the linker.

LINKAGE

Can be set to either ‘shared’ to link with shared libraries, or ‘static’ to always link statically. The default is ‘shared’. This variable only has an effect with ‘mmc --make’.

MERCURY_LINKAGE

Can be set to either ‘shared’ to link with shared Mercury libraries, or ‘static’ to always link with the static versions of Mercury libraries. The default is system dependent. This variable only has an effect with ‘mmc --make’. See Using installed libraries with mmc --make.

MLFLAGS and EXTRA_MLFLAGS

Options to pass to the ml and c2init scripts. (Note that compilation model options should be specified in GRADEFLAGS, not in MLFLAGS.) These variables have no effect with ‘mmc --make’.

LDFLAGS and EXTRA_LDFLAGS

Options to pass to the command used by the ml script to link executables (use ml --print-link-command to find out what command is used, usually the C compiler).

LD_LIBFLAGS and EXTRA_LD_LIBFLAGS

Options to pass to the command used to by the ml script to link shared libraries (use ml --print-shared-lib-link-command to find out what command is used, usually the C compiler or the system linker, depending on the platform).

MLLIBS and EXTRA_MLLIBS

A list of ‘-l’ options specifying libraries used by the program (or library) that you are building. See Using libraries with Mmake. See Using installed libraries with mmc --make.

MLOBJS and EXTRA_MLOBJS

A list of extra object files or archives to link into the program or library that you are building.

C2INITFLAGS and EXTRA_C2INITFLAGS

Options to pass to the linker and the c2init program. C2INITFLAGS and EXTRA_C2INITFLAGS are obsolete synonyms for MLFLAGS and EXTRA_MLFLAGS (ml and c2init take the same set of options). (Note that compilation model options and extra files to be processed by c2init should not be specified in C2INITFLAGS — they should be specified in GRADEFLAGS and C2INITARGS, respectively.)

C2INITARGS and EXTRA_C2INITARGS

Extra files to be processed by c2init. These variables should not be used for specifying flags to c2init (those should be specified in MLFLAGS) since they are also used to derive extra dependency information.

EXTRA_LIBRARIES

A list of extra Mercury libraries to link into any programs or libraries that you are building. Libraries should be specified using their base name; that is, without any ‘lib’ prefix or extension. For example, the library including the files libfoo.a and foo.init would be referred to as just ‘foo’. See Using libraries with Mmake. See Using installed libraries with mmc --make.

EXTRA_LIB_DIRS

A list of extra Mercury library directory hierarchies to search when looking for extra libraries. See Using libraries with Mmake. See Using installed libraries with mmc --make.

INSTALL_PREFIX

The path to the root of the directory hierarchy where the libraries, etc. you are building should be installed. The default is to install in the same location as the Mercury compiler being used to do the install.

INSTALL

The command used to install each file in a library. The command should take a list of files to install and the location to install them. The default command is ‘cp’.

INSTALL_MKDIR

The command used to create each directory in the directory hierarchy where the libraries are to be installed. The default command is ‘mkdir -p’.

LIBGRADES

A list of additional grades which should be built when installing libraries. The default is to install the Mercury compiler’s default set of grades. Note that this may not be the set of grades in which the standard libraries were actually installed. Note also that any GRADEFLAGS settings will also be applied when the library is built in each of the listed grades, so you may not get what you expect if those options are not subsumed by each of the grades listed.

LIB_LINKAGES

A list of linkage styles (‘shared’ or ‘static’) for which libraries should be built and installed. The default is to install libraries for both static and shared linking. This variable only has an effect with ‘mmc --make’.

Other variables also exist — see prefix/lib/mercury/mmake/Mmake.vars for a complete list.

If you wish to temporarily change the flags passed to an executable, rather than setting the various ‘FLAGS’ variables directly, you can set an ‘EXTRA_’ variable. 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 ‘Mmakefile’.

For each of the variables for which there is version with an ‘EXTRA_’ prefix, there is also a version with an ‘ALL_’ prefix that is defined to include both the ordinary and the ‘EXTRA_’ version. If you wish to use the values any of these variables in your Mmakefile (as opposed to setting the values), then you should use the ‘ALL_’ version.

It is also possible to override these variables on a per-file basis. For example, if you have a module called say bad_style.m which triggers lots of compiler warnings, and you want to disable the warnings just for that file, but keep them for all the other modules, then you can override MCFLAGS just for that file. This is done by setting the variable ‘MCFLAGS-bad_style’, as shown here:

MCFLAGS-bad_style = --inhibit-warnings

Mmake has a few options, including ‘--use-subdirs’, ‘--use-mmc-make’, ‘--save-makefile’, ‘--verbose’, and ‘--no-warn-undefined-vars’. For details about these options, see the man page or type ‘mmake --help’.

Finally, since Mmake is built on top of GNU Make, you can also make use of the features and options supported by the underlying Make. In particular, GNU Make has support for running jobs in parallel, which is very useful if you have a machine with more than one CPU.

As an alternative to Mmake, the Mercury compiler now contains a significant part of the functionality of Mmake, using ‘mmc’’s ‘--make’ option.

The advantages of the ‘mmc --make’ over Mmake are that there is no ‘mmake depend’ step and the dependencies are more accurate.

Note that ‘--use-subdirs’ is automatically enabled if you specify ‘mmc --make’.

The Mmake variables above can be used by ‘mmc --make’ if they are set in a file called Mercury.options. The Mercury.options file has the same syntax as an Mmakefile, but only variable assignments and ‘include’ directives are allowed. All variables in Mercury.options are treated as if they are assigned using ‘:=’. Variables may also be set in the environment, overriding settings in options files.

mmc --make’ can be used in conjunction with Mmake. This is useful for projects which include source code written in languages other than Mercury. The ‘--use-mmc-make’ Mmake option disables Mmake’s Mercury-specific rules. Mmake will then process source files written in other languages, but all Mercury compilation will be done by ‘mmc --make’. The following variables can be set in the Mmakefile to control the use of ‘mmc --make’.

MERCURY_MAIN_MODULES

The top-level modules of the programs or libraries being built in the directory. This must be set to tell Mmake to use ‘mmc --make’ to rebuild the targets for the main modules even if those files already exist.

MC_BUILD_FILES

Other files which should be built with ‘mmc --make’. This should only be necessary for header files generated by the Mercury compiler which are included by the user’s C source files.

MC_MAKE_FLAGS and EXTRA_MC_MAKE_FLAGS

Options to pass to the Mercury compiler only when using ‘mmc --make’.

The following variables can also appear in options files but are only supported by ‘mmc --make.

GCC_FLAGS

Options to pass to the C compiler, but only if the C compiler is GCC. If the C compiler is not GCC then this variable is ignored. These options will be passed after any options given by the ‘CFLAGS’ variable.

CLANG_FLAGS

Options to pass to the C compiler, but only if the C compiler is clang. If the C compiler is not clang then this variable is ignored. These options will be passed after any options given by the ‘CFLAGS’ variable.

MSVC_FLAGS

Options to pass to the C compiler, but only if the C compiler is Microsoft Visual C. If the C compiler is not Visual C then this variable is ignored. These options will be passed after any options given by the ‘CFLAGS’ variable.


Next: , Previous: Running, Up: Top   [Contents][Index]