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 übersetzt diese zu sogenannten Dynamischen Modulen. Dynamische Module können 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 Abhängigkeit von den spezifizierten Optionen wird zusätzlicher C++ Code zum Modulmanagement generiert und in die temporäre Datei 'MMGsource.cpp' geschrieben. Diese Datei bindet den Quellcode des Anwenders ein und wird im folgenden unter Verwendung eines C++ Compilers übersetzt. 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 Übersetzen 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 für verschiedene Betriebssysteme und MuPAD Versionen sowie für 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 vollständig neu definiert. Achtung: Dynamische Module müssen zu sogenanntem position independent code (PIC) übersetzt 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 unterdrückt diese Option die Verwendung von Windows Dialogboxen sowie die Aufforderung zur Betätigung der Enter-Taste zur Beendigung des Modulgenerators.

-c main=name
    Wenn der Modul-Quellcode auf mehrere Dateien verteilt ist, dann wird diese Option benötigt, um die Quellateien, ausser der Modul-Hauptdatei, zu Objektcode zu übersetzen. Als Bezeichner name wird dabei der Namen der Modul-Hauptdatei (ohne Dateiendung) angegeben. Die Objektcode Dateien können im folgenden zu einem dynamischen Modul gelinkt werden. mmg erstellt die Objektcode Datei 'source.o' und eine temporäre Datei 'MMGsource.cpp', die wichtige Teile des Codes zum Modulmanagement enthält. Diese Option darf nicht zum Übersetzen der Modul-Hauptdatei verwendet werden.

-color
    Färbt 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 unterstützt 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 unterstützt unter Windows 95/98/NT.)

-j resolvingmode
    Spezifiziert welche Methode der Adressauflösung 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 für Entwickler. Unterstützt auf den meisten UNIX Systemen.)

-llibraryname
    Kurzschreibweise der Option -ol -llibraryname. libraryname ist eine Abkürzung für den Library-Dateinamen liblibraryname.*.

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

-m memorymodel
    Spezifiziert ein Speichermodell für das zu erzeugende Modul. Die Option ermöglicht die Wahl eines der folgenden MuPAD Speichermodelle:
    lean - lean management (Standard)
    leandebug - lean management (debug Version)
    Üblicherweise ist es nicht notwendig das Speichermodel zu ändern. (Nur für Entwickler.)

-n  Diese Option unterdrückt jegliche Art der Codegenerierung. In Kombination mit der Option -v kann sie zum Ausgeben/Prüfen der Compiler und Linker Aufrufsequenzen verwendet werden.

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

-noc
    Weist mmg an, das Übersetzen des erweiterten Modul-Quellcodes zu unterdrücken. Falls das Linken nicht ebenfalls unterdrückt wurde, so erwartet der Modulgenerator dass die Modul Objektdateien zuvor im aktuellen Verzeichnis übersetzt wurden.

-nol
    Weist mmg an, das Linken der Objektcode Dateien zu unterdrücken.

-nor
    Weist mmg an, die temporär erstellten Dateien, zum Beispiel 'MMGsource.cpp' und 'MMGsource.o', nicht automatisch zu löschen.

-oc compileroption
    Übergibt die Option compileroption an den C++ Compiler. Leerzeichen müssen maskiert werden.

-ol linkeroption
    Übergibt die Option linkeroption an den Linker. Leerzeichen müssen maskiert werden.

-op outputdir
    Ändert das Ausgabeverzeichnis für neu erstellte Dateien vom aktuellen Arbeitsverzeichnis zum Verzeichnis outputdir.

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

-sys
    Liefert den MuPAD Systemnamen. MuPAD verwendet diesen Namen für den Zugriff auf betriebssystemabhängige 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 überschreibt die Standardvorgabe sowie die Option -gnu und den Wert der Umgebungsvariable MMG_CC. Zusätzlich zum Namen des Compilers, darf die Zeichenkette compiler auch weitere Compileroptionen enthalten. Siehe auch MMG_CC.

-Ddefinition
    C++ Präprozessor 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 überschreibt die Standardvorgabe sowie die Option -gnu und den Wert der Umgebungsvariable MMG_LD. Zusätzlich 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) für den C++ Compiler den mmg verwenden soll. Vergleichen Sie hierzu Option -CC.

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

PATH
    Zum Aufruf des C++ Compilers und Linkers benötigt 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 benötigt 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 benötigt 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 eingefügt 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 übersetzt.
source.o
    = Modul Objektcode Datei. Sie enthält den aus der erweiterten Modul Quellcode Datei übersetzten 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 vollständige (englische) Dokumentation über das Verwenden, Schreiben und Erzeugen von dynamischen Modulen in MuPAD 1.4 ist mit dem folgenden Buch verfügbar: 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 enthält eine CDROM mit einer "trial version" von MuPAD 1.4.1 für 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 selbsterklärend sein. Gelegentliche unklare Warnungen und Fehlermeldungen können gegebenenfalls vom C++ Präprozessor, C++ Compiler, Assembler oder Linker erzeugt werden.

ANMERKUNGEN
mmg generiert zusätzlichen C++ Quellcode zum Modulmanagement. Dieser wird zusammen mit dem benutzerdefinierten C++ Code übersetzt und zu einem Modul gelinkt. In seltenen Fällen können dabei Namenskonflikte auftreten. In so einem Fall schauen Sie bitte in die Datei 'MMGsource.cpp', die vom Modulgenerator temporär 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 Präfixen MC, MD, MF, MT, MV, da diese für das MuPAD Application Programming Interface (MAPI) reserviert sind.

BEISPIELE
Der folgende C++ Quellcode stellt ein einfaches aber vollständiges Beispiel einer Moduldefinition dar. Er definiert ein dynamisches Modul mit dem Namen 'math' und eine darin enthaltene Modulfunktion 'sin'.
 // math.cpp - Sinus für Maschinen-Fließkommanzahlen
 #include <math.h>
 MMG(info="Module: Sinus für 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 während 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 für 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

VERFÜGBARKEIT
Derzeit werden Dynamische Module für die folgenden MuPAD Versionen unterstützt:

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 für den Apple Macintosh (PowerPC) System 7.x (und spätere) wird bald verfügbar sein.

BESCHRÄNKUNGEN
Die Länge der Zeichenketten für Optionen des Modulgenerators sind auf 2000 Zeichen beschränkt. Die Anzahl der Modulfunktionen in einem Modul ist auf 512 beschränkt.

BEKANNTE PROBLEME
Problem:
    MuPAD stürtzt beim Ausladen eines Moduls oder beim Beenden einer Sitzung ab.
Lösung:
    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.
Lösung:
    Prüfen Sie, ob alle benötigten Libraries korrekt gelinkt wurden. Wenn Sie shared libraries bzw. dynamic link libraries verwenden, prüfen 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 für interne Symbolnamen, so dass ein korrektes Linken zwischen verschieden erzeugten Objektcode Dateien gegebenenfalls nicht möglich ist.
Problem:
    Der MuPAD Kern stürzt beim Aufruf einer Modulfunktion mit einer Fehlermeldung "relocation error" oder "symbol not found" oder ähnliches ab.
Lösung:
    Prüfen Sie, ob alle benötigten Libraries korrekt gelinkt wurden. Wenn Sie shared libraries bzw. dynamic link libraries verwenden, prüfen 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 für interne Symbolnamen, so dass ein korrektes Linken zwischen verschieden erzeugten Objektcode Dateien gegebenenfalls nicht möglich 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 führt zu Fehlermeldungen wie "unresolved symbols" oder zu einem schwerwiegenden MuPAD Fehlers.
Lösung:
    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".
Lösung:
    Ignorieren Sie die Warnungen oder suchen Sie eine Compileroption um diese Warnungen zu unterdrücken. Ihr C++ Compiler ist leider nicht ganz so schlau wie andere Compiler.

TECHNISCHE UNTERSTÜTZUNG
Für eine weitere technische Unterstützung senden Sie bitte eine ausführliche Problembeschreibung per Email an <bugs@mupad.de>.