.TL
\f(HBCLE - PTOC Version 1.01.  Release Notes\fR
.AU "Dieter Konnerth"
.AF "/dev Software M\(u:nchen"
.MT 4

.H 1 "Allgemeines"

Der vorliegende Pascal nach C Konverter basiert auf dem CLE
Pascal Compiler. Er akzeptiert bis auf einige Ausnahmen
den vollen Sprachumfang des CLE Pascal Compilers.
Der erzeugte C Code hat nur Mindestanforderungen an den 
nachfolgenden C Compiler, er ben\(u:tzt nichts was \(u:ber
die C-Definition in K&R hinausgeht.
.P
Der erzeugte C-Code mu\(ss erst mit dem C-Preprozessor expandiert,
dann compiliert und zuletzt mit der Pascal Library (libpc.a) und
der C Library der Zielmaschine gebunden werden. 


.H 2 "Einschr\(a:nkungen des Pascal Sprachumfanges"
.P
Nicht implementiert ist:
.P
 - nicht lokales \fBgoto\fR
 
.H 1 "Installation"
Die vorliegende bin\(a:r Version ist auf 386 Systemen mit System V.3
und seinen Derivaten lauff\(a:hig.

Auf der Diskette ist folgender \fBcpio\fR Baum (mit relativen Pfaden):
.in 4
.TS
l l.
usr/bin/ptoc	Treiberprogramm 
usr/lib/pgenc	eigentlicher \(U:bersetzer
usr/include/ptoc.h	Include File, auf Zielsystem installieren
libpc.src/Makefile	Makefile f\(u:r Pascal Library
libpc.src/*.[ch]	Pascal Library Quellen
libpc.src/libpc.a	Pascal Library Binaries f\(u:r 386
libpc.src/libpc_p.a	- " -  mit profiling
.TE
.in -4
Die Dateien \fIptoc\fR und \fIpgenc\fR stellen den eigentlichen 
Pascal nach C \(U:bersetzer dar. Diese m\(u:ssen auf dem 
Entwicklungssystem unter \fI/usr/bin\fR bzw. \fI/usr/lib\fR installiert werden.

Die Pascal Library mu\(ss, nach entsprechender Anpassung f\(u:r das Zielsystem,
mit dem C-Compiler des Zielsystems an geeigneter Stelle zB. \fI/lib\fR auf dem 
C - Entwicklungssystem installiert werden (Im allgemeinen Fall kann die
Generierung von C-Code und die \(U:bersetzung des C-Codes auf verschiedenen
Maschinen laufen.)

Die 'include' Datei \fIptoc.h\fR mu\(ss, ebenfalls auf dem 
C - Entwicklungssystem  unter \fI/usr/include\fR installiert werden.

.H 1 "Aufruf, Anwendung"
.P
Aufrufsyntax:

	\fBptoc [optionen] files ...\fR

Die Optionen sind die gleichen wie f\(u:r \fBpascal(CLE)\fR,
allerdings werden nur die den Preprozessor und das Frontend betreffenden
Optionen ausgewertet. Die Ausgabe ist ein File mit \fI.c\fR als Suffix.
.P
Beispiel.:

.S 12
.ft CW
    ptoc -e -qn test.p
    cc -o test test.c -lpc
.S 10
.ft

Range Check (-C) und globale Optimierung (-O) werden unterst\(u:tzt, 
nicht jedoch Register Optimierung.
.P
Zwei zus\(a:tzliche Optionen sind speziell f\(u:r \(fIptoc\fR
dazugekommen:
.VL 8 4
.LI -Xx
Static Link Option, schaltet die Unterst\(u:tzung f\(u:r geschachtelte 
Prozeduren ein. Ohne diese Option sind geschachtelte Prozedurdeklarationen 
mit Zugriff auf Variablen der umgebenden Prozeduren verboten.
Die \fIstatic link option\fR f\(u:hrt zu einem leichten Effizienzverlust,
falls keine geschachtelten Prozeduren verwendet werden.
.LI -Xc
Diese Option erzwingt, da\(ss symbolische Konstanten des Pascalprogramm
im generierten C Programm durch ihren Wert ersetzt werden. Dies kann
n\(o:tig werden, wenn der verwendete Ziel C Compiler Schwierigkeiten
mit Symboltabellen\(u:berlauf macht. 


.H 1 "Probleme, Hinweise"
.H 2 "Generierte Namen."
.P
Es gibt mehrere Situationen in denen \fIptoc\fR neue Namen
generieren mu\(ss. Dabei wird ein Algorithmus verwendet
der verhindert da\(ss es zu Namenskonflikten kommt.
Allerdings kann nicht ausgeschlossen werden da\(ss es zu Konflikten
mit Namen aus anderen, getrennt \(u:bersetzten Modulen kommt.
Bei der Generierung von Namen werden folgende Konventionen
verwendet:
.P
.BL
.LI
Generierte Namen: Vollst\(a:ndig selbstgenerierte Namen beginnen 
immer mit dem String \fBptoc_\fR. Darauf folgt ein die Art des Namens 
beschreibender String (zB. \fBVar\fR f\(u:r Variable, \fBTyp\fR f\(u:r Typ, 
usw.) gefolgt von einer eindeutigen Zahl.
.LI
Spezielle generierte Namen sind:
.TS
l l.
_ptoc_LOCAL	: Variablenname eines Procedure Frames
_ptoc_LINK	: Parameter, Statischer Vorganger
<proc>_ssl	: Parameter, Statischer Vorg\(a:nger eines Prozedur Parameters
_ptoc_FRAME_<proc>	: Typname eines Procedure Frames
_ptoc_TEMPSTRUCT	: Tempor\(a:rer structur Name.
_ptoc_ASSIGN	: Makro, definiert in ptoc.h
_ptoc_MOVE	: Makro, definiert in ptoc.h
_ptoc_MEMCMP	: Makro, definiert in ptoc.h
_ptoc_CONST	: Makro, definiert in ptoc.h
.TE
.LI
Globale Namen: Namen die in der Pascal Quelle lokal definiert sind, aber in
dem C Code global sein m\(u:ssen, werden durch Anh\(a:ngen des
Funktionsnamens und eventuell einer Zahl, eindeutig gemacht.
Dies betrifft die Namen von lokalen Prozeduren/Funktionen,
sowie Typnamen und Namen der Elemente von Aufz\(a:hlungstypen.
.LI
C Keywords: Kommen in der Pascal Quelle C Keywords als Namen 
vor so wird \fB_\fR angeh\(a:ngt. Wird dadurch ein schon existierender
Name generiert werden weitere Unterstriche angeh\(a:ngt bis der Name
eindeutig ist.
.LI
Typenamen: Typen werden generell global definiert, und erhalten den
Prefix \fBt_\fR und eventuell eine Zahl als Suffix. 
Dies ist n\(o:tig
da sich beim Test mit mehreren C-Compilern herausgestellt hat,
da\(ss Namenskonflikten zwischen Typnamen und sonstigen Namen,
sowie lokale Typnamen Probleme bereiten.
.LI
Level 0 Namen: 
Die vordefinierten globalen Namen \fItrue, false, minchar, maxchar,
minint, maxint\fR erhalten den Prefix \fBl0_\fR und eventuell eine
Zahl als Suffix. Dies ist n\(o:tig da diese Namen in Pascal durch
globale (Level 1) Definitionen \f(u:berschattet werden k\(o:nnen, 
es in C aber keine Unterscheidung zwischen Level 0 und 1 Namen gibt.

\fBAchtung:\fR Die Level 0 Namen \fIinput, output, _err, _argc, _argv, _envp\fR
k\(o:nnen nicht durch Prefixe bzw. Suffixe eindeutig gemacht werden,
da es externe Variablennamen sind, die in der Pascal Library und auch in
beliebigen Modulen vorkommen, der Algorithmus der einen Namen eindeutig
macht aber nur innerhalb eines Moduls arbeiten kann. Dies ergibt eine
Einschr\(a:nkung: Die oben aufgez\(a:hlten Namen d\(u:rfen nicht auf Level 1
(d.h. global) redefiniert werden.
.LI
Vordefinierte Preprozessor Namen: Falls Namen die im C Preprozessor 
vordefiniert sind wie \fIunix, i386, ...\fR in der Pascal Quelle verwendet 
werden,  f\(u:hrt dies zu Fehlern, da der C Code durch den Preprozessor 
mu\(ss, auch wenn der Pascal Code nicht mit dem Preprozessor bearbeitet
wurde.
.LE

.H 2 "Datentypen, Packen von Strukturen"
.P
Die Pascal Datentypen werden auf die entprechenden C Typen  abgebildet.
.in 4
.TS
l l.
integer	-> int  oder unsigned
char	-> unsigned char
enum	-> enum
real	-> float
double	-> double
.TE
.in -4
Subrange Typen und Set Typen werden wie beim CLE Pascal Compiler
von der \fI-q\fR Option gesteuert:

mit -q
.in 4
.TS
l l.
subrange	-> char, short oder int je nach Range
set	-> char [1], char [2 x n], n=1,2,... je nach Grundmenge
.TE
.in -4
ohne -q
.in 4
.TS
l l.
subrange	-> int
set	-> char [4 x n], n=1,2,... je nach Grundmenge
.TE
.in -4
Das packen von \fIstructure\fR und \fIarray\fR Typen wird dem C-Compiler 
\(u:berlassen.

.H 1 "Die Pascal Library"
.P
Zur Verwendung des Pascal nach C \(U:bersetzers mu\(ss als erstes
die Pascal Library f\(u:r das Zielsystem portiert werden.
Die Pascal Library ist in C geschrieben. 
Sie st\(u:tzt sich auf die C-Library
bzw. auf UNIX System Calls. Einige Module enthalten
Maschinenabh\(a:ngigkeiten. Dabei handelt es sich im wesentlichen 
um  Abh\(a:ngigkeit von der ByteOrder der Zielmaschine sowie um einige 'asm'
Anweisungen. Diese Stellen m\(u:ssen f\(u:r jede Zielmaschine angepa\(sst werden.
Die Stellen erkennt man an '#ifdef iAPX386' ...
Die wichtigsten sind in whoami.h und PCSTART.c.
Die vorliegende Version unterst\(u:zt i386, 68k und Pyramid Systeme .

.H 1 "Portierung von PTOC"

Die vorliegende Version ist auf 386 PC's unter UNIX System V und seinen 
Derivaten lauff\(a:hig. Der Compiler ist in C und Pascal geschrieben.

Die Portierung auf andere Systeme ist m\(o:glich, auch wenn f\(u:r
das Zielsystem kein Pascal Compiler existiert.

Daf\(u:r sind folgende Schritte n\(o:tig:

.BL
.LI
Portierung der Pascal Library f\(u:r das Zielsystem.
.LI
Generierung und Test der Pascal Library.
.LI
Generierung der C-Files aus den in Pascal geschriebenen Modulen
des \fIptoc\fR Compilers. Dies geschieht auf einem 386 System
und wird von dem Makefile unterst\(u:tzt:

.S 12
.ft CW
    cd pcomp
    make cfiles
.ft
.S 10

.LI
Kopieren des gesamten Source Baumes auf die Zielmaschine
.LI
Generieren des Compilers.

.S 12
.ft CW
    cd pcomp
    make xpgenc
.ft
.S 10

.LE
Der 'Pascal nach C' Konverter selber enth\(a:lt keine Abh\(a:ngigkeiten
vom System dem er l\(a:uft. Im Treiberprogramm,
in der Datei \fIptoc/wait.h\fR.  gibt es eine Abh\(a:ngigkeit 
vom Betriebssystem (System V oder Berkeley),
die \(u:ber die 'Makevariable' HOST in \fIptoc/Makefile\fR 
einzustellen ist.

.H 2 "Der Source Baum"

Der Source Baum hat folgende Subdirectories:

.VL 12 0
.LI DIST	
Unter diesem Baum werden die Binaries abgelegt.
.LI doc
Dokumentation, diese Zeilen. Auszudrucken mit

	tbl Notes | troff -mm ...
.LI common
Allen Sprachen und Codegeneratoren gemeinsame CLE Module.
.LI gram
Einige include files die eigentlich zum CLE Codegenerator
geh\(o:ren, hier aber trotzdem gebraucht werden.
.LI include
Enth\(a:lt nur ptoc.h (siehe oben).
.LI libpc
Die Pascal Library mit Makefiles
.LI optimizer
Die Module des globalen CLE Optimierers 
.LI pascl
Pascal Semantik Module
.LI pgram
Pascal Gramatik Module
.LI ptoc
Treiber (ptoc) mit Makefile
.LI pcomp
Generierungsdirectory, Makefiles
.LI tools
Einige Hilfstools die zur Generierung des Compilers verwendet
werden:
.TS
l l.
eyacc:	Erweiterte yacc Version
mkvers:	Rudiment\(a:re Versionskontrolle
makedepend:	Generierungstools f\(u:r Makefiles
install:	Installscript
tws:	Yacc Preprocessor, nur bei C Compiler verwendet
.TE
.LE

Generierung des Compiler bei installiertem CLE Pascal
Compiler:

.S 12
.ft CW
    make install ROOT=`pwd`/DIST
.S 10
.ft R

erzeugt den Compiler und legt die Objekte unter DIST.

In dem Unterverzeichnis \fIpcomp\fR bedeuten:
.in 4
.TS
l l.
make mkpgenc	: erzeugt den Compiler
make cfiles	: erzeugt C Files aus den Pascal Files
make xmkpgenc	: erzeugt den Compiler aus den C Zwischenfiles
make clean	: saubermachen
make pgenc.mk	: erzeugt Makefile
make xpgenc.mk	: erzeugt Makefile
.TE
.in -4
