================================================================================ Turbo Modula-2 V1.3 (6/Dec/94) Turbo Modula-2 (c) Copyright 1994 by Amritpal Mann, All Rights Reserved Email: Turbo@econet.demon.co.uk ================================================================================ This is a freely distributable Modula-2 development system. The version of Modula supported is as described in Niklaus Wirth's book: Programming in Modula-2, 4th edition (Springer-Verlag) Turbo Modula-2 consists of: A compiler(M2C), a link utility(M2L), an error lister(M2E), and a program builder(M2B). Interface modules for V40 of the AmigaOS & corresponding linker library, ANSI C standard library definitions as well as those from PIM. The compiler reads source code in a single pass which means fast compilation. Internally however it performs several passes over each procedures statement sequence in order to generate fast and compact code. Typically, generated code is 25% smaller & 75% faster than the commercial Amiga Modula-2 compiler used for the initial bootstraps. Turbo does not have its own linker, instead it requires a 'C' compiler front-end to link generated code. The unregistered freeware version of Matt Dillon's excellent C system, DICE, has been included and contains 2 necessary programs, DCC & DLINK, as well as vital startup code(c.o) and support libraries(c.lib,auto.lib,x.o) Note that Turbo does NOT produce 'C' as intermediate output, it just uses DCC to link and add startup code the machine code it generates. You do not need to know how to use DICE in order to generate M2 executables, M2L calls DCC for you, all you need do is extract DICE (see below). The reason for using DICE instead of say BLINK, are that DICE has excellent support for generating residentable programs, also the standard C library supplied with DICE becomes automatically available and finally (for those of us who have slow(er) amigas) DLINK runs fast! The unregistered freeware version of DICE may only be distributed complete & unmodified. This also applies to Turbo Modula-2. The minimum required setup in order to use Turbo is 1MB of memory, 1.3 workbench and 2 disk drives. However I recommend that you should have at least 1MB of available(free) memory and a hard disk. When runnning under OS 1.3 make sure NEWCLI, ENDCLI and RUN are in youre path, even better make them resident. To use M2B you really need a real-time clock or otherwise set the time at bootup or instead use M2C & M2L directly. If you dont have a RTC you can use a software hack: examples/src/IncTime.mod Dice Extraction =============== The file dice/dice.lha contains the DICE system.In order to save your hard disk space, the dice/M2EXTRACT script will extract the files that we are interested in: >cd dice >execute M2EXTRACT You can of course extract the entire archive if you prefer. If you already have DICE installed on your system, and are therefore not extracting it again, you should delete the appropriate lines in the s/startup script. Installation ============ Add the following lines to your s:user-startup (startup-sequence under 1.3): >assign MODULA: ; = directory where you unarchived Turbo >execute MODULA:s/startup Assignments =========== MODULA: is expected to be assigned to the root directory of the unarchived system. MLIB: should be assigned to MODULA:mlib s/startup will make the above assignments for you. Directory Organisation ====================== docs/ M2OPTS Default M2OPTS file (see below). examples/ Some example programs amiga/ 20000 lines of definition modules for V40 of the AmigaOS, these files were hand translated from Commodores header files. ansi-c/ Definition for the Ansi-C library that comes with DICE. m2lib Definitions for some of the functions in M2.lib. Also contains source for m2_main.o. m2/ Definition for some modula-2 (PIM4) library modules. sym/ Symbol files for above definition modules. obj/ Compiled object modules, for the implementation modules in above directories mlib/ Modula-2 support code (m2.lib & m2_main.o). MLIB: is assigned to this. bin/ Residentable executables for M2B, M2C, M2E, M2F, M2L & M2S. All these programs were developed completely from scracth by the Author, the initial M2C bootstrap was done using M2AmigaV3.3 These programs are only runable from the cli/shell. dice/ DICE system. If you want to redistribute DICE then you must include all the files in the dice.lha archive. s/ Contains startup and object file caching scripts. Filename extensions =================== *.err Binary error file generated by M2C & M2B, used by M2E. *.mod Program/implementation module (ascii text). *.def Definition module (ascii text). *.o Standard Amiga object file, generated by M2C from a *.mod file. *.sym Symbol file generated by M2C from a *.def file. *.lib Linker Library. A concatenation of *.o files. *.lnk Linker object file list(ascii), written to the T: directory by M2L, read by DCC. *.cmp Compiler input file list(ascii), written to the T: directory by M2B, read by DCC. Error Lister (M2E) ================== If M2B or M2C encounter errors while processing a source file, then a binary error file will be generated. Use M2E to view the errors encoded in this file. usage: m2e modulename M2B and M2C will automatically invoke M2E. Program Builder (M2B) ===================== M2B will take care of compilation and linking for you.It checks file timestamps to see which files need to be (re)compiled/(re)linked. M2B is like MAKE, but instead of using a makefile it scans import lists. usage: m2b [-f][-v][-t] [compile/link options] filename [DCC options & args] -f: Force all time comparisons to fail(all modules will be (re)compiled). -v: Write out the name of each file as it is read. -t: Don't actually call M2C & M2L just print the commands that would have been executed. example: /-------- -s passed to DCC >m2b -v -p -b -q foo.mod -s ^--^--^------------------ -p -b -q are compiler(M2C) options -q is also an M2L option. Assuming that foo.o is older than foo.mod and foo.mod does not import any other module then M2B will call M2C & M2L as m2c -p -b -q foo.mod m2l -q foo.o -s (but only if m2c did not fail) You may find the TOUCH program (in dice/bin/) useful when using M2B. Compiler (M2C) ============== usage: m2c [-D][-C][-b][-p][-w][-q][-l] {-Mdir} {[@]filename} filename: File to be compiled If a filename does not end in .mod or .def, then it is assumed to be a .mod and .mod is appended. @filename: Filename is an ascii text file that contains a list of filenames to be compiled (this list is normally created and passed to M2C by M2B). -D: Use large data model (default is small data model). If your program declares more than 64K of global variables then you must enable this option for each constituent module (except library modules that were compiled small data & -l), otherwise linking will fail. By allocating large data structures on the heap you can easily avoid the need to use this option. Using the small data & code models will make your program more compact. Compiling all modules small data will also allow a program to be made fully resident (DCC option -r). -C: Use large code model (default is small). If a module compiles to about 32000 bytes or more, then you may need to enable this option (depending on whether linking fails). If a module compiles to more than 32767 bytes then you definitely need to enable this option. The maximum code size using large code is 48K(per module). -b: Enable array bounds checking. -p: Enable pointer checking. The compiler will insert code to check that all pointer accesses are within a specific range. At the moment the bounds are fixed to 1K..16M. If you're Amiga has valid memory outside this range (and you're program might access it) then you cannot use this option. Programmers who do not have a MMU,and so can't use the enforcer program, will find this option very useful. For best results use pointer checking in conjunction with commodores MUNGWALL program, although it can still trap a lot of bugs without mungwall. Depending on programming style (access procedures or open structures), pointer checking may or may not massively increase the size of a program It does not slow down a program by as much as you may expect. Pointer checking should only be used during program development. -w: Disable compiler warnings. -q: Shut the f*ck up. -l: (equivalent to the DICE option -S) Name BSS(global variable space) section libbss instead of just 'bss'. Use this option to compile re-usable modules that do not have much BSS. This will enable you to use small code library modules with (large code) program modules that declare a lot of BSS.This option avoids the need to have two different versions (one small & one large) of said modules. -M: Add dir to the symbol file directory search path. If a dir/sym/ subdirectory exists, it will be added instead. It is possible to set/clear some of these options inside a source text by using comments, see extensions.doc. If a Modula-2 run-time error occurs (illegal case index, halt called, array/pointer checking etc) the run time support code (in M2.lib) will display a requester with the first 4 letters of the module name and (full) line number of where the error occurred. Ľou can use DICE DOBJ to view the machine code generated by the compiler. As yet the compiler does not perform range and overflow checking. Automatic stack checking is also not implemented, instead it can be done manually see M2Lib.def. One pass compilation -------------------- The compiler operates in a single pass, this means that you must declare variables & procedures before you use them.The compiler provides the FORWARD keyword in order to allow early declarations for procedures that are implemented later. PROCEDURE f( ) ; FORWARD ; (* implementation must be in the same scope *) PROCEDURE g( ) ; BEGIN f( ) ; END g ; PROCEDURE f( ) ; (* alternatively we could nest f( ) inside g( ) *) BEGIN g( ) END f ; If a procedure is declared in a definition module then a forward declaration in the corresponding implementation module is never required. Type sizes & extremal values ---------------------------- size (bytes) range ============ ===== SHORTCARD 1 0 .. 255 CARDINAL 2 0 .. 65535 SHORTINT 1 -128 .. 127 INTEGER 2 -32768 .. 32767 LONGINT 4 -(2^31) .. (2^31)-1 SHORTREAL 4 Motorola FFP REAL 4 IEEE single precision LONGREAL 8 IEEE double precision There is also a LONGCARD datatype which is declared as a LONGINT[0..MAX(LONGINT)]. Compiler Restrictions --------------------- As already mentioned the compiler can only generate object files up to 48K (any bigger than 32000 (I DO NOT mean 32767!) bytes should be compiled large code, linking will fail if you do not). Sets sizes are restricted to 32 bits. Structured types (arrays and record) can not be returned from functions. At somestage I may remove the above 2 restrictions. Module names must be less than 30 characters (AmigaDos restriction) All other identifiers and string literals must be less than 200 chars long. Caching (M2S & M2B) =================== The compiler automatically caches symbol files. If youre system does not have much memory, then you will need to flush the cache on a regular basis, or 'setenv M2SYMCACHE=OFF' To list the cached symbol files use M2S To flush the symbol cache use M2F Linker frontend (M2L) ===================== M2L calls DCC (which in turn calls DLINK) to link the object modules generated by the compiler into an executable file. M2L is itself normally called by M2B (M2B->M2L->DCC->DLINK). Usage: m2l [-q] {-Mdir} module[.o] [DCC options & args] -q : Quiet, don't print the path of each file as it is read. -Mdir : Add directory dir to the object file search path. If a dir/obj/ subdirectory exists, it will be added instead. module: Program (root) module name. This object module must be in a local directory Anything on the command line that follows the module name is passed to DCC. example: m2l -q foo -s -r ^--^-- passed to dcc. This will invoke DCC: dcc -Lmlib: @t:foo.lnk -s -r -ofoo Where t:foo.lnk (intermediate file generated by M2L) will contain: m2_main.o foo.o m2.lib m2_main.o m2.lib are normally in directory mlib: (modula:mlib) See DICE/DOC/DLINK.DOC for further information on linking.(You may have to extract this file) M2OPTS ====== An optional ascii text file named M2OPTS in the MODULA: directory can specify M2C and M2L command line options. M2L filters M2OPTS looking for -q & -M's ignoring all other options. Options in M2OPTS are scanned before command line options. An M2OPTS text in the current directory will override the one in MODULA:. Debugging ========= Ideally Turbo should include a source level debugger. The DCC options '-s' dumps symbols into final executable so you can atleast use a low level debugger (eg Devpac Monam), this does however require knowledge of M68000 assembler. I've just started work on a source level debugger. This may be available in the next release (V1.4). Bug Reports =========== As the library modules are so large they are likely to contain a few mistakes.The structure sizes and constant values have been automatically verified with those in the commodore header files, however is not easily possible to mechanically check the types of all parameters and fields. Rare mistakes like *mi : Menu* instead of *mi : MenuItem* should be detected during compilation: when youre program tries to instantiate the parameter/field. The code called for DIV & MOD are the M68000 versions, which differ from those defined in the Modula standard.The difference is only important when dealing with negative numbers. M2B sometimes get confused when implemention modules contain cyclic importing (bad style anyway). This noramlly results in version mismatches at compile time. Simply invoking M2B again with same command like normally works around the problem. This works because some of the files will have been successfully compiled, so the during the second pass M2B sees things differently. If youre program does not contain any cycles then M2B should work perfectly. The executables have not been tested under the enforcer program, so may cause hits.I have used the pointer checking option (described above) so I would be suprised if any occur?? Please report any bugs/comments/suggestions/spelling errors/job offers, [ive been unemployed since graduating :-(], to Turbo@econet.demon.co.uk.