MMG(1)

NAME

mmg - Der MuPAD Modulgenerator erzeugt Dynamische Module

AUFRUF

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

BESCHREIBUNG

mmg ist der MuPAD Modulgenerator. Er analysiert Modul-Quelldateien, geschrieben in der Programmiersprache C/C++, und uebersetzt diese zu sogenannten Dynamischen Modulen. Dynamische Module koennen zur Laufzeit in MuPAD geladen und in der gleichen Weise wie MuPAD Library-Pakete verwendet werden. Neben einer Reihe von optionalen Parametern akzeptiert mmg die Angabe genau einer C++ Modul-Quelldatei source mit der Dateiendung .cpp sowie eine Liste von Objektcode Dateien und Library-Archiven die zum Modul gelinkt werden sollen. In Abhaengigkeit von den spezifizierten Optionen wird zusaetzlicher C++ Code zum Modulmanagement generiert und in die temporaere Datei 'MMGsource.cpp' geschrieben. Diese Datei bindet den Quellcode des Anwenders ein und wird im folgenden unter Verwendung eines C++ Compilers uebersetzt. Die dabei erzeugte Datei 'source.o' wird dann zu einer sogenannten shared library bzw. einer dynamic link library 'source.mdm' gelinkt. Im Standardfall werden alle Ausgabedateien im aktuellen Arbeitsverzeichnis erstellt. Normalerweise verwendet der Modulgenerator zum Uebersetzen der Modul-Quelldateien genau den Compiler, der auch zur Erstellung des MuPAD Kerns eingesetzt wurde, zum Beispiel CL (Microsoft Visual C++), g++ (GNU C++ Compiler), CC, cxx, xlC sowie die Linker link (Microsoft Visual C++), ld. Die verwendeten Compiler und Linker variieren fuer verschiedene Betriebssysteme und MuPAD Versionen sowie fuer verschiedene Hardware Architekturen. Der Anwender kann den verwendeten C++ Compiler jedoch auch selbst spezifizieren. Einerseits mit der Option -gnu (bzw. -nognu) um den GNU Compiler g++, explizit (nicht) zu verwenden oder indem er den Compiler/Linker-Aufruf mit der Option -CC bzw. -LD vollstaendig neu definiert. Achtung: Dynamische Module muessen zu sogenanntem position independent code (PIC) uebersetzt werden. Es ist stets angeraten den im Modulgenerator voreingestellten C++ Compiler zu verwenden.

OPTIONEN

-a modattr
    Setzt eines der folgenden Modulattribute modattr, um eine spezielle Behandlung des dynamischen Moduls durch den MuPAD Kern zu veranlassen:
    static - MuPAD entfernt das Modul nie
    unload - MuPAD entfernt das Modul baldigst

-b, -batch
    Startet mmg im Stapelverarbeitungsmodus. Auf Windows 95/98/NT Systemen unterdrueckt diese Option die Verwendung von Windows Dialogboxen sowie die Aufforderung zur Betaetigung der Enter-Taste zur Beendigung des Modulgenerators.

-c main=name
    Wenn der Modul-Quellcode auf mehrere Dateien verteilt ist, dann wird diese Option benoetigt, um die Quellateien, ausser der Modul-Hauptdatei, zu Objektcode zu uebersetzen. Als Bezeichner name wird dabei der Namen der Modul-Hauptdatei (ohne Dateiendung) angegeben. Die Objektcode Dateien koennen im folgenden zu einem dynamischen Modul gelinkt werden. mmg erstellt die Objektcode Datei 'source.o' und eine temporaere Datei 'MMGsource.cpp', die wichtige Teile des Codes zum Modulmanagement enthaelt. Diese Option darf nicht zum Uebersetzen der Modul-Hauptdatei verwendet werden.

-color
    Faerbt die Ausgabe des Modulgenerators ein. Dies macht es leichter einfache Meldungen, Warnungen und Fehlermeldungen in mehrzeiligen Ausgaben zu unterscheiden. Diese Option wird vom shell script mmg ausgewertet und vom Modulgenerator-Binary ignoriert. (Nicht unterstuetzt unter Windows 95/98/NT.)

-g  Debug Option. mmg weist den C++ Compiler an Code zu erzeugen, der von einem Quellcode Debugger ausgewertet werden kann. Mit dieser Option wird automatisch auch die Option -nor aktiviert.

-gnu, -nognu
    Weist mmg an den GNU C++ Compiler g++ anstatt des C++ Standardcompilers explizit zu verwenden bzw. explizit nicht zu verwenden. Ist der GNU C++ Compiler als Standardcompiler eingetragen, so ist diese Option wirkungslos. (Nicht unterstuetzt unter Windows 95/98/NT.)

-j resolvingmode
    Spezifiziert welche Methode der Adressaufloesung das Modul zur Adressierung von MuPAD Kernobjekten verwenden soll:
    func - Adressfunktion (debugging/tracing)
    table - Adresstabelle (Standard)
    link - Dynamischer Linker (Entwickler))
    Das Adressieren undokumentierter MuPAD Kernobjekte sowie das Debuggen kann das Setzen der Option -j link erfordern. (Nur fuer Entwickler. Unterstuetzt auf den meisten UNIX Systemen.)

-llibraryname
    Kurzschreibweise der Option -ol -llibraryname. libraryname ist eine Abkuerzung fuer den Library-Dateinamen liblibraryname.*.

-make
    Makefile generieren. Die Option weist den Modulgenerator an ein Makefile source.mk zu generieren, das zum Erstellen (uebersetzen und linken) des angegebenen Moduls verwendet werden kann.

-m memorymodel
    Spezifiziert ein Speichermodell fuer das zu erzeugende Modul. Die Option ermoeglicht die Wahl eines der folgenden MuPAD Speichermodelle:
    lean - lean management (Standard)
    leandebug - lean management (debug Version)
    Ueblicherweise ist es nicht notwendig das Speichermodel zu aendern. (Nur fuer Entwickler.)

-n  Diese Option unterdrueckt jegliche Art der Codegenerierung. In Kombination mit der Option -v kann sie zum Ausgeben/Pruefen der Compiler und Linker Aufrufsequenzen verwendet werden.

-nog
    Weist mmg an, die Generierung des Codes zum Modulmanagement zu unterdruecken. Falls das Uebersetzen und Linken nicht ebenfalls unterdrueckt wurde, so erwartet der Modulgenerator dass die C++ Quelldatei 'MMGsource.cpp', zuvor im aktuellen Arbeitsverzeichnis erstellt wurde.

-noc
    Weist mmg an, das Uebersetzen des erweiterten Modul-Quellcodes zu unterdruecken. Falls das Linken nicht ebenfalls unterdrueckt wurde, so erwartet der Modulgenerator dass die Modul Objektdateien zuvor im aktuellen Verzeichnis uebersetzt wurden.

-nol
    Weist mmg an, das Linken der Objektcode Dateien zu unterdruecken.

-nor
    Weist mmg an, die temporaer erstellten Dateien, zum Beispiel 'MMGsource.cpp' und 'MMGsource.o', nicht automatisch zu loeschen.

-oc compileroption
    Uebergibt die Option compileroption an den C++ Compiler. Leerzeichen muessen maskiert werden.

-ol linkeroption
    Uebergibt die Option linkeroption an den Linker. Leerzeichen muessen maskiert werden.

-op outputdir
    Aendert das Ausgabeverzeichnis fuer neu erstellte Dateien vom aktuellen Arbeitsverzeichnis zum Verzeichnis outputdir.

-pseudo
    Weist mmg an ein Pseudomodul zu erstellen. Dieses kann mit einem C++ Compiler uebersetzt und statisch zum MuPAD Kern gelinkt werden. Der Code des Pseudomoduls wird in der Datei 'psource.cpp' gespeichert. (Nur fuer Entwickler.)

-sys
    Liefert den MuPAD Systemnamen. MuPAD verwendet diesen Namen fuer den Zugriff auf betriebssystemabhaengige Daten. Vergleichen Sie hierzu das MuPAD shell script sysinfo, das auf UNIX Systemen ausgeliefert wird.

-v  Weist mmg an, jeden Schritt der Modulgenerierung mit einer entsprechenden Meldung zu dokumentieren.

-CC compiler
    Spezifiziert die Aufrufsequenz des C++ Compilers. Diese Option ueberschreibt die Standardvorgabe sowie die Option -gnu und den Wert der Umgebungsvariable MMG_CC. Zusaetzlich zum Namen des Compilers, darf die Zeichenkette compiler auch weitere Compileroptionen enthalten. Siehe auch MMG_CC.

-Ddefinition
    C++ Praeprozessor Definition. Diese Option ist eine Kurzschreibweise der Option -oc -Ddefinition.

-Iincludedir
    Erweitert die Liste der Verzeichnisse in denen der C++ Compiler nach include-Dateien sucht um den Pfad includedir. Diese Option ist eine Kurzschreibweise der Option -oc -Iincludedir.

-Llibrarydir
    Erweitert die Liste der Verzeichnisse in denen der Linker nach Libraries sucht um den Pfad librarydir. Diese Option ist eine Kurzschreibweise der Option -ol -Llibrarydir.

-LD linker
    Spezifiziert die Aufrufsequenz des Linkers. Diese Option ueberschreibt die Standardvorgabe sowie die Option -gnu und den Wert der Umgebungsvariable MMG_LD. Zusaetzlich zum Namen des Linkers, darf die Zeichenkette linker auch weitere Linkeroptionen enthalten. Siehe auch MMG_LD.

-V version
    Versionsinformation. Mit dieser Option wird ein vom Benutzer definierter Informationstext in das Dynamische Modul eingebunden. Dieser wird beim Aufruf der MuPAD Funktion info zusammen mit der Modul-Schnittstellenbeschreibung ausgegeben.

UMGEBUNG

MMG_CC
    Spezifiziert die Aufrufsequenz (ggf. auch Standardoptionen) fuer den C++ Compiler den mmg verwenden soll. Vergleichen Sie hierzu Option -CC.

MMG_LD
    Spezifiziert die Aufrufsequenz (ggf. auch Standardoptionen) fuer den Linker den mmg verwenden soll. Vergleichen Sie hierzu Option -LD.

PATH
    Zum Aufruf des C++ Compilers und Linkers benoetigt mmg die Spezifikation der entsprechenden Zugriffspfade, zum Beispiel zu den Compilern CL (Microsoft Visual C++), g++ (GNU C++ Compiler), CC, cxx oder xlC, und den Linkern LINK (Microsoft Visual C++), ld, in der Pfadvariable.

MuPAD_ROOT_PATH
    Auf UNIX Betriebssystemen wird diese Umgebungsvariable vom Modulgenerator benoetigt um auf das MuPAD Installationsverzeichnis zuzugreifen. Die Umgebungsvariable wird im shell script $MuPAD_ROOT_PATH/share/bin/mmg automatisch gesetzt.

MuPAD_PRO_XXX
    Auf Windows 95/98/NT Systemen wird die Umgebungsvariable MuPAD_PRO_XXX (wobei XXX die MuPAD Versionsnummer spezifiziert, z.B. MuPAD_PRO_150) vom Modulgenerator benoetigt um auf das MuPAD Installationsverzeichnis zuzugreifen. Auf Windows NT Systemen wird sie automatisch mit der Installation von MuPAD Pro global gesetzt. Auf Windows 95 Systemen muss gegebenenfalls die Stapelverarbeitungsdatei %MuPAD_PRO_XXX%\modules\bin\mmg.bat bearbeitet und die Pfaddefinition eingefuegt werden.

HINWEIS
    Wenn Sie die Umgebungsvariable LD_LIBRARY_PATH, einsetzen, stellen Sie sicher, dass der Pfad des C++ Compilers am Anfang der Pfadliste steht.

HINWEIS
    Um die Kommandozeilenversion des Microsoft Visual C++ Compilers unter Windows 95/98/NT zu verwenden, ist es notwendig weitere Umgebungsvariablen zu setzen. Der einfachste Weg dies zu tun, ist die Stapelverarbeitungsdatei 'Vcvars32.bat' (ausgeliefert mit dem Microsoft Visual C++ Compiler) in das MuPAD Verzeichnis %MuPAD_PRO_XXX%\modules\bin zu kopieren.

DATEIEN

MMGsource.cpp
    = Erweiterte Modul-Quellcode Datei. Sie besteht aus dem C++ Code zum Modulmanagenemt und bindet den benutzer-definierten C++ Modul-Quellcode ein. Die Datei wird zu einer Modul Objektcode Datei uebersetzt.
source.o
    = Modul Objektcode Datei. Sie enthaelt den aus der erweiterten Modul Quellcode Datei uebersetzten Maschinencode. Die Datei wird zu einem dynamischen Modul gelinkt.
source.mdm
    = Dynamisches Modul. Diese Datei kann in einer MuPAD Sitzung geladen und wie ein MuPAD Library-Paket eingesetzt werden.
source.mk
    = Modul Makefile. Die Datei kann mittels der Option -make vom Modulgenerator erstellt werden.

SIEHE AUCH
CC(1), cxx(1), xlC(1), g++(1), ld(1), Microsoft Visual C++ Dokumentation Eine vollstaendige (englische) Dokumentation ueber das Verwenden, Schreiben und Erzeugen von dynamischen Modulen in MuPAD 1.4 ist mit dem folgenden Buch verfuegbar: Dynamic Modules -- User's Manual and Programming Guide for MuPAD 1.4, Andreas Sorgatz, Oktober 1998; Springer Verlag, Berlin, Heidelberg, New York; ISBN 3-540-65043-1. Das Buch enthaelt eine CDROM mit einer "trial version" von MuPAD 1.4.1 fuer Linux und Solaris Betriebssysteme sowie viele Programmierbeispiele und Modulanwendungen. Das Buch beschreibt die UNIX Version der dynamischen Module in MuPAD 1.4.1. Die meisten Informationen sind jedoch ebenfalls relevant (und notwendig) zur Entwicklung von dynamischen Module mit MuPAD Release 1.5 unter UNIX sowie auch unter Windows 95/98/NT Systemen. Aktuelle Informationen und Erweiterungen finden Sie auf dem MuPAD WWW Server http://www.mupad.de/PAPER/MODULES/.

DIAGNOSEN
Die vom Modulgenerator ausgegebenen Fehlermeldungen sollten selbsterklaerend sein. Gelegentliche unklare Warnungen und Fehlermeldungen koennen gegebenenfalls vom C++ Praeprozessor, C++ Compiler, Assembler oder Linker erzeugt werden.

ANMERKUNGEN
mmg generiert zusaetzlichen C++ Quellcode zum Modulmanagement. Dieser wird zusammen mit dem benutzerdefinierten C++ Code uebersetzt und zu einem Modul gelinkt. In seltenen Faellen koennen dabei Namenskonflikte auftreten. In so einem Fall schauen Sie bitte in die Datei 'MMGsource.cpp', die vom Modulgenerator temporaer erzeugt wird, sowie in die MuPAD include-Dateien hinein, die im Verzeichnis $MuPAD_ROOT_PATH/share/mmg/include (UNIX Systeme) bzw. %MuPAD_PRO_150%\modules\include (Windows 95/98/NT) installiert sind. Deklarieren und definieren Sie niemals Objekte mit den Praefixen MC, MD, MF, MT, MV, da diese fuer das MuPAD Application Programming Interface (MAPI) reserviert sind.

BEISPIELE
Der folgende C++ Quellcode stellt ein einfaches aber vollstaendiges Beispiel einer Moduldefinition dar. Er definiert ein dynamisches Modul mit dem Namen 'math' und eine darin enthaltene Modulfunktion 'sin'.
 // math.cpp - Sinus fuer Maschinen-Fließkommanzahlen
 #include <math.h>
 MMG(info="Module: Sinus fuer Maschinen-Fließkommanzahlen")
 MFUNC( sin, MCnop ) // Modulfunktion ::sin
 { MFnargsCheck(1); // Ein Param. erwartet
   MFargCheck(1,DOM_FLOAT); // muss ein float sein
   MTcell arg = MFarg(1); // der erste Parameter
   double val = MFdouble(arg); // Konvertiert in double
   val = sin(val); // Berechnet den Sinus
   MFreturn(MFdouble(val)); // Liefert MuPAD float
 } MFEND Rufen Sie den Modulgenerator zur Erstellung des MuPAD Moduls auf:
 > 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
Laden Sie das dynamische Modul waehrend der MuPAD Sitzung und verwenden Sie es genau wie ein MuPAD Library-Paket:
 >> module(math);
 math
 >> info(math):
 Module: 'math' created on 17.Aug.99 by mmg R-1.5.0
 Module: Sinus fuer Maschinen-Fließkommanzahlen
 -- 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

VERFUeGBARKEIT
Derzeit werden Dynamische Module fuer die folgenden MuPAD Versionen unterstuetzt:

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 Eine Portierung fuer den Apple Macintosh (PowerPC) System 7.x (und spaetere) wird bald verfuegbar sein.

BESCHRAENKUNGEN
Die Laenge der Zeichenketten fuer Optionen des Modulgenerators sind auf 2000 Zeichen beschraenkt. Die Anzahl der Modulfunktionen in einem Modul ist auf 512 beschraenkt.

BEKANNTE PROBLEME
Problem:
    MuPAD stuertzt beim Ausladen eines Moduls oder beim Beenden einer Sitzung ab.
Loesung:
    Weisen Sie mmg an den GNU C++ Compiler zu verwenden (Option -gnu). Verwenden Sie die Option -a static um das automatische Ausladen des Moduls zu verhindern.
Problem:
    Ein dynamisches Modul kann von MuPAD nicht geladen oder initialisiert werden.
Loesung:
    Pruefen Sie, ob alle benoetigten Libraries korrekt gelinkt wurden. Wenn Sie shared libraries bzw. dynamic link libraries verwenden, pruefen Sie, ob MuPAD diese finden kann. Gegebenfalls erweitern Sie die entsprechenden Suchpfade oder kopieren Sie die Libraries in das aktuelle Verzeichnis bzw. das MuPAD Binary-Verzeichnis. Versuchen Sie das Modul mit einem alternativen C++ Compiler neu zu erstellen. Auf einigen Betriebssystemen verwenden unterschiedliche C++ Compiler verschiedene Formate fuer interne Symbolnamen, so dass ein korrektes Linken zwischen verschieden erzeugten Objektcode Dateien gegebenenfalls nicht moeglich ist.
Problem:
    Der MuPAD Kern stuerzt beim Aufruf einer Modulfunktion mit einer Fehlermeldung "relocation error" oder "symbol not found" oder aehnliches ab.
Loesung:
    Pruefen Sie, ob alle benoetigten Libraries korrekt gelinkt wurden. Wenn Sie shared libraries bzw. dynamic link libraries verwenden, pruefen Sie, ob MuPAD diese finden kann. Gegebenenfalls erweitern Sie die entsprechenden Suchpfade oder kopieren Sie die Libraries in das aktuelle Verzeichnis bzw. das MuPAD Binary-Verzeichnis. Versuchen Sie das Modul mit einem alternativen C++ Compiler neu zu erstellen. Auf einigen Betriebssystemen verwenden unterschiedliche C++ Compiler verschiedene Formate fuer interne Symbolnamen, so dass ein korrektes Linken zwischen verschieden erzeugten Objektcode Dateien gegebenenfalls nicht moeglich ist.
Entwickler:
    Setzen Sie zu Testzwecken die Option -j link. Vergleichen Sie hierzu Option -j.
Problem:
    Die Verwendung von Streams, Templates oder C++ Exceptions in dynamischen Modulen fuehrt zu Fehlermeldungen wie "unresolved symbols" oder zu einem schwerwiegenden MuPAD Fehlers.
Loesung:
    Weisen Sie den Modulgenerator an eine alternativen C++ Compiler/Linker zu verwenden. Setzen Sie die Option -gnu zur Verwendung des GNU C++ Compilers. Vermeiden Sie die Verwendung der genannten C++ Erweiterungen. Verwenden Sie zur Ausgabe ausschließlich die MAPI Funktionen MFout(MTcell), MFputs(const char*) und MFprintf(const char*, ...).
Problem:
    Der C++ Compiler liefert Warnungen wie "cannot inline function" oder "statement is unreachable".
Loesung:
    Ignorieren Sie die Warnungen oder suchen Sie eine Compileroption um diese Warnungen zu unterdruecken. Ihr C++ Compiler ist leider nicht ganz so schlau wie andere Compiler.

TECHNISCHE UNTERSTUETZUNG
Fuer eine weitere technische Unterstuetzung senden Sie bitte eine ausfuehrliche Problembeschreibung per Email an <bugs@mupad.de>.