InfoMagic Source Code 1993 July/THE_SOURCE_CODE_CD_ROM.iso/languages/modula_3/contrib/m3pc/m3/readme

Text File | 1992-12-10 | 12.2 KB | 279 lines

Klagenfurt, Mon Dec  7 16:35:13 MET 1992

Hi,

This file gives a brief description of this (possibly the first) Modula-3
(M3) port to the i386 architecture with MS-DOS. I have used DEC-SRC M3
version 2.09 for the DECstation (DS3100). M3 is available via anonymous
ftp from gatekeeper.dec.com:pub/DEC/Modula-3. Sorry for my bad English
but it's not my native language.

My goal was to bring a bootstrapable M3 version to the PC. PC-M3 has several
restrictions due to the limitations of MS-DOS and the lack of time to
make things perfect (i.e. Threads do not work and there is no m3make
available on PCs, floating point is not correct). The compiler is slow but
it works.

To run PC-M3 you need:
    - a i386 (or upward)
    - MS-DOS 5.0 (it should also work with MS-DOS 3.2)
    - at least 2 MB RAM (I recommend 4 to 8 MB)

M3 V 2.09 produces C code. Therfore a C compiler is needed. The PC C
compilers (i.e. MS-C, Turbo-C) are written for the so called "real mode"
of the 80x86 processors. This mode has several limitations. I have therfore
used the GNU C compiler (gcc). To run gcc it is necessary to have DJ
Delorie's DOS Extender (go32 - it is available together with gcc via
anonymous ftp from barnacle.erc.clarkson.edu:pub/msdos/djgpp, login
name: ftp). Thanks DJ for doing the gcc port to MS-DOS! With go32 it is
possible to use the "protected mode" features of the i386 processor.
For further information about go32 and gcc read the README files in
\djgpp\docs.

A "minimal" version of go32 and gcc comes with PC-M3 so that it is possible
to compile and link M3 programs. I have not included anything because it
would blow up the size of the whole package. If you are interested
in the rest please ftp it from the above mentioned host.


The main parts of PC-M3:
------------------------
1) The driver (m3)
The driver is a program that invokes the M3 compiler (see below), the
C compiler (gcc in our case), does "M3 linking" and builds the final
program.

2) The compiler (m3compiler)
This program is invoked with "system()" from m3 and translates a M3 program
to C code.

3) The library (libm3.a, libm3.ax)
This is the SRC M3 library. It contains a lot of library functions and the
M3 runtime system.


PC-M3 Directories:
------------------
I have tried to preserve the SRC directory structure.

\djgpp                  directory for go32 and gcc (contains subdirs)
\m3                     the M3 main directory
\m3\include\m3          the M3 interfaces
\m3\bin                 the M3 executeables (m3, m3compiler)
\m3\lib\m3              the M3 library, header files, ...
\m3\driver              the M3 driver sources (contains subdirs)
\m3\compiler            the M3 compiler sources (contains subdirs)
\m3\libm3               the M3 library sources (contains subdirs)
\m3\doc                 documentation, copyright info, FAQ, ...
\m3\test                some tests, misc\sn.m3


Using PC-M3:
------------
Before you can use M3 you have to call \djgpp\setenv to setup your
environment. Note: setenv.bat changes your PATH environment variable.
setenv.bat makes just the changes required for go32 and gcc - you
possibly want to include \m3\bin into your PATH.
To compile a M3 program (say "Hello.m3") type:

\m3\bin\m3 -w1 -make -why -o Hello Hello.m3

To execute "Hello" type: go32 Hello
If you want a "Hello.exe" type: aout2exe Hello

For building a program with more than one module I would advise to
use m3 with the -F option. See \m3\driver\DOS386\m3make.bat for an
example.

Do not use names for Interfaces/Modules with more than 8 characters
(otherwise you have to use name maps - see below).

Note: In the library just the things used by the compiler and driver
are guaranteed to work. I expect that many things in the library will
not work on the PC. I have not tested this - just worked with the
driver and compiler.


Translating the driver, compiler or building the library:
---------------------------------------------------------
PC-M3 comes with executeables for m3, m3compiler and with the build library.
If you change something you want to recompile things. Make sure that you
have copies of the things you change in case something does not work.

To recompile the driver go to \m3\driver\DOS386 and call m3make.bat.
This batch file will build a new driver. To install the driver type
"aout2exe m3" and "copy m3.exe \m3\bin".

To recompile the compiler go to \m3\compiler\DOS386 and call m3make.bat.
This batch file will build a new compiler. To install the compiler type
"aout2exe m3compil" and "copy m3compil.exe \m3\bin".

Note: It is necessary to have the library to rebuild driver and compiler.

To build a new libm3.a go to \m3\libm3\DOS386 and call m3make.bat.
This batch file will build a new libm3.a and libm3.ax. Copy libm3.a and
libm3.ax to \m3\lib\m3. There is a file runtime.c. Compile this file
with "gcc -c runtime.c". Include this file into the library with "ar -r
libm3.a runtime.o" Do not forget to call "ranlib libm3.a". You have now
a new library.

The file runtime.c is a copy of /m3/libm3/Csupport/src/generic/M3Runtime2.c.
This file should be included automatically during the build of the library.
But this currently does not work - I guess it is a problem within m3 in
connection with the name maps - I had not the time to correct this - Sorry.
Therefore it is necessary to insert this file by hand into the library.

Note: All this m3make batch files use a file PGMS with the path and filenames
of the sources. You should change PGMS if you want to add or remove a file.
I would recommend to start a full recompilation of the compiler or the
library over night, because it needs some time.

If you change something in a interface do not forget to update it in
\m3\include\m3 also. Possibly you have to update a NAMES.MAP.


Brief Description of Problems and Changes:
------------------------------------------
You can skip this section if you are not interested in changing things in
PC-M3. I have build a M3 cross compiler on a DECstation. I have installed
go32 and gcc on a PC (my system was a 486 with 16 MB memory). I have build
(several times) a boot-DOS386 (DOS386 is the name of the new target
architecture) for the driver and the compiler on the DECstation. I transfered
the C sources to the PC and compiled with gcc.

- jump buffer

M3 uses setjmp/longjmp. It is necessary to change the jmp_buf.

- problems during linking

I had problems with the following unresolved references during the first link
phase:

_setjmp, _longjmp, scalb, logb, copysign, finite, isnan, sqrt, fp_class_d,
getpwuid, getpwnam, swapRM, get_fpc_csr, set_fpc_csr, sigvec, pipe,
setitimer, execvp, mprotect, select, fcntl

I have solved this problems in a way that it is possible to run the compiler
(all of this functions not needed by the driver or compiler cause a runtime
error). sigvec and fcntl simply return 0. Because there are no signals on a
PC the M3 Threads do not work.

- file name problems

I had problems with the length of the filenames. DOS allows just a 8
character name with a 3 character extension. I have solved this problem
with files called "name maps". With this maps I map a long Unix name to a
short DOS name - the extension is preserved (means just 3 characters are
allowed). The name of the file containing such a map is always "NAMES.MAP".
The structrure of this file is:

number '\n' { long-Unix-name '\n' short-DOS-name '\n' }

Each directory has its own name map. I insert just files into the map (no
subdirectories).

'\n':           newline - each item is seperated by a newline
        (\r\n is also allowed)

number:         the number (represented by ascii characters) is used to
        create a new unique file name; if the file is empty number
        is 0; in the current version number is alway increased if a
        new name is inserted - it is not decremented if a file
        is removed.

long-Unix-name: a Unix file name (i.e. Short.m3, ThisNameIsTooLongForDOS.m3)

short-DOS-name: a DOS file name (i.e. Short.m3, 123.m3); if the lenght of a
        Unix name (excluding the extension) is less equal 8 characters
        it is not changed; if the length of the name is greater it is
        mapped to a number; Note: the extension is not changed

To construct such NAMES.MAP files on a Unix system I have written sn.m3. It
reads directories and also subdirs and converts the file names there to short
DOS file names. The Module \m3\libm3\rw\src\NameMap implements the name maps.
m3 consults this maps to find a file.

- file problems

There are different file flags (i.e. for open()) on Unix and DOS systems
(O_RDONLY, O_WRONLY, ... see \m3\libm3\unix\src\DOS386\Unix.i3, Ustat.i3).
Furthermore DOS distinguishes between "text files" and "binary files". The
M3 Rd'ers and Wr'ers use read(), write() and lseek() calls to work on
file streams. The problem is that lseek() on a PC does not know something
about text files but repositioning is done based on values returned by read()
and write(). The last two system calls are able to distinguish between text
and binary files. Reading a file in text mode and positioning with lseek()
based on values returned by read() gives bad results.

Therfore all files are opened in binary mode. To provide text files
transparent filters (DOSTextRd.T, DOSTextWr.T) are used (see their
interfaces for further info).
The Module FileStream is used only for text files - for binary files use the
Module FileIO (see \m3\libm3\rw\src). Note that FileStream knows about name
maps - FileIO does not.

- argument length

The lenght of arguments given to a program from the command line is
restricted by MS-DOS. m3compiler is able to use a argument file.
The arguments in the file must be seperated by newlines. To call m3compiler
with the argument file "arguments" use: m3compiler @arguments


Experiences with go32 and gcc:
------------------------------
go32 and gcc are reliable most of the time. Sometimes I had crashes and it
can happen that your disk is corrupted. It was always possible to correct
this problems with "chkdsk /F".

The M3 driver (m3) uses fork/exec to start the M3 compiler (m3compiler).
There is no working fork/exec available on the PC. Therefore I have used
system() instead. m3 usually calls m3compiler first and should then call gcc.
gcc calls (also with system()) cpp (preprocessor), cc1 (C compiler) and as
(assembler). It seems that there is just one level of calls with system()
possible. That means m3 is able to call gcc but gcc is not able to call cpp -
it simply hangs. I was therefore forced to go around gcc and call the C passes
(cpp, cc1, as) and ld "by hand" directly from m3.

The whole system communicates via files. Therfore I recommend to use a disk
caching program. I have used "smartdrv" - don't make it too big - some people
reported problems with go32. The only option I used with smartdrv was to
enable write behind.

You can interrupt a running program with Ctrl C - but sometimes the machine
reboots if you do so. If your program hangs - i.e. because of a unhandled
exception - try to type Ctrl C (and nothing else). You should return to the
DOS prompt. If you type another key your machine enters Nirvana and will need
a soft or hard reset. The reason for this is that I have not adjusted the M3
runtime system.


Acknowledgements:
-----------------
I had this summer the opportunity to work as a summer intern for DEC-SRC.
Thanks DEC-SRC. My host there was Bill Kalsow. Thanks Bill for your patience
in explaining the M3 compiler to a M3 novice like me. I would also like to
thank Prof. Laszlo Boszormenyi (Universitaet  Klagenfurt,
Universitaetsstrasse 65-67, Institut fuer Informatik, A-9020 Klagenfurt,
AUSTRIA, e-mail: [e-mail]) who has allowed me to work on
this project.

If you have questions you can try to send them to the e-mail address *below*.
Sorry, I do not know wether I will be able to support PC-M3 in the future -
therefore be ready to help yourself. I hope the sysops at the University
will keep my account open.

If you use PC-M3 please send a postcard to my address *below* !!! Thank you!

   - Klaus

Klaus Preschern
10. Oktoberstrasse 4
A-9170  Ferlach
AUSTRIA

e-mail: [e-mail]