MMG(1)

NAME

mmg - MuPAD module generator for creating dynamic modules

SYNOPSIS

mmg [-a {static|unload}] [-j {func|table|link}] [-pseudo]
[-c main=name] [-make] [-g] [-sys] [-v] [-V version]
[-n] [-nog] [-noc] [-nol] [-nor] [-gnu] [-nognu]
[-op path] [-CC compiler] [-LD linker] [-oc ccoption]
[-ol ldoption] [-Ddefinition] [-Iincpath] [-Llibpath]
[-llibname] [file.{a|o|lib|dll} ...] sourcefile.cpp

DESCRIPTION

mmg is called the MuPAD module generator. It analyses module source files written in the C++ programming language and compiles them into a so-called dynamic MuPAD modules. Dynamic modules can be loaded into MuPAD at runtime and are used in the same way as MuPAD library packages. In addition to its options, mmg accepts the name of one C++ source file with the suffix .cpp and a list of object files and library archives which are to be linked to the module. Depending on the specified options, additional C++ code (for module management) is generated and written into the temporary file 'MMGsource.cpp'. This file includes the user's source code and is compiled using a C++ compiler. It is linked to a dynamic module generating an object file 'source.o' and a shared library respectively dynamic link library 'source.mdm'. By default, all output files are placed in the current directory. Usually, for creating module binaries mmg calls the C++ compiler that was used to compile the MuPAD kernel. This is one of the C++ compilers CL (Microsoft Visual C++), g++ (GNU C++ compiler), CC, cxx, xlC and one of the link editors link (Microsoft Visual C++), ld. The compiler and linker used varies for different operating systems and MuPAD releases as well as for different machine types. However, the user can change the compiler with option -gnu respectively -nognu, in order to use respectively not to use the GNU compiler g++, or by re-defining the compiler/linker command using option -CC, -LD respectively. If the GNU C++ compiler g++ is set as default compiler of the module generator, this option has no meaning. Note: Dynamic modules must be compiled to position independent code (PIC). It is always recommended to use the default compiler.

OPTIONS

-a modattr
    Sets the attribute modattr to specify one of the following special treatments for this module:
    static - MuPAD never unloads this module
    unload - MuPAD unloads it as fast as possible

-b, -batch
    Starts mmg in batch mode. On Windows 95/98/NT systems this option suppresses the use of dialog boxes and the request to press the return key to terminate the module generator.

-c main=name
    If the module source code is split into several files, this option is used to compile all source files but the main module source file to object files. Here, 'name' specifies the name of the main source file without its suffix. Object files like this can be linked to a dynamic module later. mmg creates the object file 'source.o' and a temporary file 'MMGsource.cpp', which contains relevant parts of the module management code. This option must not be used to compile the main source file of the module.

-color
    Colors the messages of mmg, which makes it easier to distinguish comments, warnings and errors in a multiple line output. This option is interpreted by the shell script mmg and ignored by the corresponding binary. (Not supported on Windows 95/98/NT.)

-g  Debug option. mmg instructs the C++ compiler to create code which can be debugged with a source code debugger. With this, option -nor is activated automatically.

-gnu, -nognu
    Instructs mmg to use the GNU C++ compiler g++ instead of the mmg default compiler respectively instructs mmg not to use the GNU C++ compiler. (Not supported on Windows 95/98/NT.)

-j resolvingmode
    Selects the address resolving method used by the module to resolve MuPAD kernel objects:
    func - resolver function (debugging/tracing)
    table - resolving table (default)
    link - dynamic loader (undocumented features)
    Using undocumented MuPAD kernel routines requires to set option -j link. (For wizards only. Supported on most UNIX systems.)

-llibraryname
    This is a shortcut for -ol -llibraryname. libraryname is an abbreviation for the library file name liblibraryname.*.

-m memorymodel
    Selects a MuPAD memory model. This option allows to choose one of the following memory models to be used by the created module:
    lean - lean management (default)
    leandebug - lean management (debug version)
    Usually it is not necessary to change the memory model. (For wizards only.)

-make
    Creates a Makefile. This option instructs mmg to generate a Makefile source.mk which can be used to build (compile and link) the specified module.

-n  No operation. Suppresses any kind of code generation. In combination with the option -v it can be used to display the calling sequence of the compiler and linker.

-nog
    Instructs mmg to skip the generation of module management code. If compiling and linking is not suppressed too then it is expected that the file 'MMGsource.cpp', has been generated before and is available in the current directory.

-noc
    Instructs mmg to skip compiling. If linking is not suppressed too, it is expected that the module object files have been compiled before and are available in the current directory.

-nol
    Instructs mmg to skip linking.

-nor
    Instructs mmg not to remove temporary created module code files like 'MMGsource.cpp' and 'MMGsource.o'.

-oc compileroption
    Passes the option compileroption to the compiler. Whitespaces must be quoted.

-ol linkeroption
    Passes the option linkeroption to the linker. Whitespaces must be quoted.

-op outputdir
    Changes the output directory for created files from the current working directory to outputdir.

-pseudo
    Instructs mmg to generate module management code for a pseudo module. This may be compiled with a C++ compiler and can be linked statically with the MuPAD kernel. The name of the output file is 'psource.cpp'. (For wizards only.)

-sys
    Displays the system name. MuPAD uses this name to find system dependent binary files. On UNIX systems also refer to the MuPAD shell script sysinfo.

-v  Verbose. Normally mmg does its work silently. Using this option mmg displays every step of the module generation.

-CC compiler
    Specifies the calling sequence of the C++ compiler. This option overwrites the default value as well as the option -gnu and the value given in the environment variable MMG_CC. In addition to the compiler name, the string compiler may also contain additional compiler options. Also refer to MMG_CC.

-Ddefinition
    C++ preprocessor definition. This option is a shortcut for -oc -Ddefinition.

-Iincludedir
    Adds includedir to the list of directories in which the C++ compiler searches for include files. This is a shortcut for -oc -Iincludedir.

-Llibrarydir
    Adds the librarydir to the list of directories in which the linker (loader) searches for libraries. This is a shortcut for -ol -Llibrarydir.

-LD linker
    Specifies the calling sequence of the linker (loader). This option overwrites the default value as well as the option -gnu and the value given in the environment variable MMG_LD. In addition to the linker name, the string linker may also contain additional linker options. Also refer to MMG_LD.

-V version
    Version information. Includes a user-defined information character string into the created module. The version information of a module is displayed using the MuPAD function info.

ENVIRONMENT

MMG_CC
    Specifies the name (as well as default options) of the C++ compiler to be used by mmg. Refer to option -CC.

MMG_LD
    Specifies name (as well as default options) of the link editor to be used by mmg. Refer to option -LD.

PATH
    mmg requires the insertion of the names of directories which contain the C++ compilers, e.g. CL (Microsoft Visual C++), g++ (GNU C++ Compiler), CC, cxx or xlC, and link editors, e.g. LINK (Microsoft Visual C++), ld, in your path list.

MuPAD_ROOT_PATH
    On UNIX operating systems this environment variable is needed by the module generator to access the MuPAD installation directory. The environment variable is set automatically in the shell script $MuPAD_ROOT_PATH/share/bin/mmg.

MuPAD_PRO_XXX
    On Windows 95/98/NT systems the environment variable MuPAD_PRO_XXX (with XXX specifies the MuPAD release number, e.g. MuPAD_PRO_150) is needed by the module generator to access the MuPAD installation directory. On Windows NT systems it is set automatically when MuPAD is installed. On Windows 95 systems you may need to edit the batch file %MuPAD_PRO_XXX%\modules\bin\mmg.bat and to insert this definition.

NOTE
    If you have to use LD_LIBRARY_PATH, be sure to put the path of your C++ compiler at the head of the path list.

NOTE
    In order to use the command line version of the Microsoft Visual C++ Compiler on Windows 95/98/NT systems it is necessary to define additional environment variables. The easiest way of doing this is to copy the batch file 'Vcvars32.bat' (distributed with the Microsoft Visual C++ Compiler) into the MuPAD directory %MuPAD_PRO_XXX%\modules\bin.

FILES

MMGsource.cpp
    = extended module source code. It consists of the C++ module management code and includes the user-defined C++ source code. This file is compiled to module main object file.
source.o
    = module main object file. It consist of machine code compiled from the module main source file. This file is linked to the dynamic module file.
source.mdm
    = dynamic module file. This file can be loaded in a MuPAD session and is used like a MuPAD library package.
source.mk
    = module Makefile. This file can be created with mmg using option -make.

SEE ALSO
CC(1), cxx(1), xlC(1), g++(1), ld(1), Microsoft Visual C++ Documentation The complete documentation about using, writing and creating dynamic modules with MuPAD 1.4 is given with the book Dynamic Modules -- User's Manual and Programming Guide for MuPAD 1.4, Andreas Sorgatz, October 1998; Springer Verlag, Berlin, Heidelberg, New York; ISBN 3-540-65043-1. This book includes a CDROM with a trial version of MuPAD 1.4.1 for Linux and Solaris operating systems and many programming examples and module applications. The book describes the UNIX version of dynamic modules in MuPAD 1.4.1. However, most of its information is also relevant (and needed) for developing dynamic modules with MuPAD Release 1.5 on UNIX as well as on Windows 95/98/NT operating systems. Latest information about new features are available at the MuPAD web site http://www.mupad.de/PAPER/MODULES/.

DIAGNOSTICS
The diagnostics produced by mmg are intended to be self-explanatory. Occasional obscure messages may be produced by the preprocessor, compiler, assembler, or loader.

NOTES
mmg generates additional C++ code for module management. This is compiled and linked together with the user's source code. In case of trouble, e.g. naming conflicts, check your source code for names that are also used in the file 'MMGsource.cpp', temporary created by mmg, or in any of the MuPAD header files installed in the directory $MuPAD_ROOT_PATH/share/mmg/include (UNIX) respectively in %MuPAD_PRO_150%\modules\include (Windows 95/98/NT). Never declare or define objects with a prefix MC, MD, MF, MT, MV because they are reserved for the MuPAD Application Programming Interface (MAPI).

EXAMPLES
The following source code is a simple and but complete example of a module definition. It defines a dynamic module called 'math' with a module function 'sin'.
 // math.cpp - Sin for machine floating point numbers
 #include <math.h>
 MMG(info="Module: Using machine floating point numbers")
 MFUNC( sin, MCnop ) // function ::sin
 { MFnargsCheck(1); // one param. expected
   MFargCheck(1,DOM_FLOAT); // it must be a float
   MTcell arg = MFarg(1); // get first parameter
   double val = MFdouble(arg); // convert to double
   val = sin(val); // compute sin of val
   MFreturn(MFdouble(val)); // return MuPAD float
 } MFEND Call mmg to create a dynamic MuPAD module:
 > mmg math.cpp
 MMG -- MuPAD-Module-Generator -- V-1.5.0 Aug.99
 Mesg.: Scanning source file ...
 Mesg.: 1 function(s) and 1 option(s) found in 15 lines
 Mesg.: Creating extended module code ...
 Mesg.: Compiling extended module code ...
 [...]
 Mesg.: Linking dynamic module ...
 [...]
 Mesg.: Ok
Load the dynamic module within a MuPAD session and use it:
 >> module(math);
 math
 >> info(math):
 Module: 'math' created on 17.Aug.99 by mmg R-1.5.0
 Module: Using machine floating point numbers
 -- Interface:
 Interface:
 math::doc, math::sin
 >> math::sin();
 Error: Wrong number of arguments [math::sin]
 >> math::sin(1);
 Error: Invalid argument [math::sin]
 >> math::sin(1.0);
 0.8414709848
 >> % -sin(1.0);
 -0.000000000000000001843143691

AVAILABILITY
So far the use of dynamic modules can supported for the following MuPAD versions:

DECalpha:
    Linux/ELF 2.0
DECalpha:
    OSF1 V3.x
HP: HP-UX Rel. 9.x, 10.x
IBM(RS6000):
    AIX 4.x
PC/AT:
    FreeBSD 2.0, NetBSD 1.2, OpenBSD 2.0
PC/AT:
    Linux/ELF 2.x
PC/AT:
    Windows 95/98/NT
PC/AT:
    Solaris 2.x
SGI(Indigo):
    IRIX 5.x, IRIX 6.x
Sun(SPARC):
    SunOS 4.x, Solaris 2.x Ports for Apple Macintosh (PowerPC) System 7.x and later will be available soon.

RESTRICTIONS
The length of option strings is limited to 2000 characters. The number of module functions is limited to 512 per module.

KNOWN PROBLEMS
Problem:
    MuPAD dies when unloading a module or when quitting the session.
Solution:
    Instruct mmg to use the GNU C++ compiler by setting the option -gnu and/or set option -a static to declare this module as unloadable.
Problem:
    A dynamic module cannot be loaded or initialized by MuPAD.
Solution:
    Check if all libraries needed by the module are linked correctly. If you are using shared libraries respectively dynamic link libraries check if these can be found by MuPAD. If not, extend the corresponding search paths or copy the libraries into the current working directory respectively into the MuPAD bin-directory. Try to re-generate the module using an alternative C++ compiler. On some operating systems different compilers use a slightly different linking format, so that a correct linking of object code compiled by different C++ compilers may not be possible.
Problem:
    The kernel dies when executing a module function with an error message like "relocation error" or "symbol not found".
Solution:
    Check if all libraries needed by the module are linked correctly. If you are using shared libraries respectively dynamic link libraries check if these can be found by MuPAD. If not, extend the corresponding search paths or copy the libraries into the current working directory respectively into the MuPAD bin-directory. Try to re-generate the module using an alternative C++ compiler. On some operating systems different compilers use a slightly different linking format, so that a correct linking of object code compiled by different C++ compilers may not be possible.
Wizards:
    Try option -j link. Refer to option -j.
Problem:
    Using streams, templates or C++ exceptions in a dynamic module, there are unresolved symbols or the MuPAD kernel reports a fatal error.
Solution:
    Instruct mmg to use an alternative C++ compiler/linker. Use the option -gnu for the GNU C++ compiler. Avoid these features and use the MAPI routines MFout(MTcell), MFputs(const char*) and MFprintf(const char*, ...) for displaying output only.
Problem:
    The C++ compiler reports warnings like "cannot inline function" and "statement is unreachable".
Solution:
    Ignore them or look for an option to suppress these kind of warnings. Your compiler is not as smart as other ones.

TECHNICAL SUPPORT
For getting further technical support please send a detailed problem report via email to <bugs@mupad.de>.