This document describes each of the tools in the SRC Modula-3 distribution and how to use them. Briefly, the tools include a compiler, a linker, a pretty printer, and a line-based profiler. See also chapter~\ref{local} for tools and hints that are local to your installation.

Compiling

m3 parses the command line and invokes the compiler and linker as required. m3 tells the compiler where to seek imported interfaces and where to find the Modula-3 runtime library. Arguments ending in .m3 or .i3 are assumed to name Modula-3 source files to be compiled. Arguments ending in .mo, .io or .o are assumed to name object files, possibly created by other language processors, that are to be linked with the object files created by m3. Arguments ending in .mc, .ic, or .c are assumed to name C source files to be compiled. Arguments ending in .ms, .is, or .s are assumed to name assembly language files to be translated into object files by the assembler. Arguments starting with - specify compiler options. Other arguments are assumed to name library files, and are simply passed along to the linker.

The source for a module named M is normally in a file named M.m3. The source for an interface named I must be in a file named I.i3. The main program is the module that implements the interface Main.

There are options to compile without linking, stop compiling after producing C, emit debugger symbols, generate profiling hooks, retain intermediate files, override search paths, select non-standard executables for the various passes, and pass arguments to individual passes. For the full details, see the m3(1) man page.

In a source file, an occurrence of IMPORT Mumble causes the compiler to seek an interface named Mumble. The compiler will step through a sequence of directories looking for the file Mumble.i3. It will parse the first such file that it finds, which is expected to contain an interface named Mumble. If no file Mumble.i3 exists, or if the parse fails, the compiler will generate an error. The particular sequence of directories to be searched is determined by the options passed to m3. See the m3(1) manual page for full details.

An example

In the file Main.m3:

       MODULE Main;
       IMPORT A;
       BEGIN
         A.DoIt ();
       END Main.

       INTERFACE A;
       PROCEDURE DoIt ();
       END A.

       MODULE A;
       IMPORT Wr, Stdio;

       PROCEDURE DoIt () =
          BEGIN
            Wr.PutText (Stdio.stdout, "Hello world.\n");
            Wr.Close (Stdio.stdout);
          END DoIt;

       BEGIN
       END A.

       m3 -make -why -o hello Main.m3 A.m3 A.i3

m3makefiles

The m3makefile for the example above would be:

       implementation (Main)
       module (A)
       program (hello)

Language restrictions

      TRY
        i := 3;
        P ();
      EXCEPT E:
        j := i;
      END;

      CONST P = T.m;  BEGIN P (...) ...

      CONST X = ARRAY [0..2] OF Proc { T.m, ..};

      CONST X = (T.m = MyProcedure);

      <*EXTERNAL*> INTERFACE OS;
      VAR errno: INTEGER;
      PROCEDURE exit (i: INTEGER);
      END OS.

      INTERFACE OS;
      <*EXTERNAL errno:C *> VAR errno: INTEGER;
      <*EXTERNAL exit:C  *> PROCEDURE Exit (i: INTEGER);
      END OS.

      INTERFACE Xt;
        <*EXTERNAL "_XtCheckSubclassFlag" *>
        PROCEDURE CheckSubclassFlag (...);
        ...

      INTERFACE X;
      <*INLINE*> PROCEDURE P (i: INTEGER);
      <*INLINE*> PROCEDURE Q ();
      END X.

       MODULE M;
       VAR x: Foo <*TRACE MyTrace.FooChanged*>;

       MyTrace.FooChanged ("M.x", x)

       WITH  alias = x DO  INC(alias) END

    VariableDecl = IdList (":" Type & ":=" Expr) V_TRACE.
    Formal       = [Mode] IdList (":" Type & ":=" ConstExpr) V_TRACE.
    ForSt        = FOR Id V_TRACE ":=" Expr TO Expr [BY Expr] DO S END.
    Handler      = QualId {"," QualId} ["(" Id V_TRACE ")"] "=>" S.
    TCase        = Type {"," Type} ["(" Id V_TRACE ")"] "=>" S.
    Binding      = Id V_TRACE "=" Expr.
    V_TRACE      = [ "<*" TRACE  Expr "*>" ].

       BEGIN <* TRACE  INC(cnt); MyTrace(cnt) *>
         i := j;
         j := i;
       END;

      EXCEPTION InternalError;
      <*FATAL InternalError*>

      PROCEDURE X() RAISES {} =
      BEGIN
        ...
        <*FATAL ANY*> BEGIN
           List.Walk (list, proc);
        END;
        ...
      END X;

      PROCEDURE DefaultClose (<*UNUSED*> wr: Wr.T) =
         BEGIN (* do nothing *) END DefaultClose;

      <*LINE number filename *>
      <*LINE number *>

    (gdb) run MyProgram @M3novm

    (gdb) handle 11 noprint pass

    (gdb) call RTHeap__FinishVM()

    (gdb) call RTHeap__NoVM()

    ignore SIGVTALRM
    set $casesense = 1

    (autoload 'modula-3-mode "modula3")
    (setq auto-mode-alist 
         (append '(("\\.ig$" . modula-3-mode)
                   ("\\.mg$" . modula-3-mode)
                   ("\\.i3$" . modula-3-mode)
                   ("\\.m3$" . modula-3-mode))
                   auto-mode-alist))	

    (setq completion-ignored-extensions
       (append '(".mo" ".mx" ".mc" ".io" ".ix") completion-ignored-extensions))

        (visit-tags-table "LIB_USE/FTAGS")