# Getting started

In this and following chapters we assume that XDS is properly installed and configured (See Chapter Configuring the compiler); the default file extensions are used.

Your XDS package contains a script file, xc`work`, which may be used to prepare a working directory. For more information, consult your `readme.1st` file from the XDS on-line documentation.

- Using the Modula-2 compiler
- Using the Oberon-2 compiler
- Error reporting
- Building a program
- Debugging a program

## Using the Modula-2 compiler

In the working directory, use a text editor to create a file called hello.mod, containing the following text:

        MODULE hello;

        IMPORT InOut;

        BEGIN
         InOut.WriteString("Hello World");
         InOut.WriteLn;
        END hello.

Type

`` `xc hello.mod`

at the command prompt. `xc` will know that the Modula-2 compiler should be invoked for the source file with the extension .mod. The compiler heading line will appear:

`XDS Modula-2` version`[`code generator`] "hello.mod"`

showing which compiler has been invoked (including its version number), which code generator is being used (in square brackets) and what is its version, and finally the name of the source file `xc` has been asked to compile.

Assuming that you have correctly typed the source file, the compiler will then display something like

`no errors, no warnings, lines 15, time 1.09`

showing the number of errors, the number of source lines and the compilation time.

Note: The XDS compiler reports are user configurable. If the lines similar to the above do not appear, check that the DECOR equation value contains letters `C' (compiler heading) and `R' (report).

## Using the Oberon-2 compiler

In our bilingual system the Modula-2 source code just shown is also perfectly valid as the Oberon-2 code. XDS allows you to use Modula-2 libraries when programming in Oberon-2 (in our case the `InOut` module).

As in Modula-2, this source code in Oberon-2 constitutes a top-level module or program module, but in Oberon-2, there is no syntactic distinction between a top-level module and any other module. The Oberon-2 compiler must be specifically told that this is a top-level module by using the option MAIN.

Copy the source file to the file hello.ob2 and type:

`` xc`hello.ob2 +MAIN`

The same sequence of reports will occur as that of the Modula-2 compiler, but the Oberon-2 compiler will also report whether a new symbol file was generated or not. It is also possible to override the default source file extension using M2 and O2 options:

`` xc`hello.mod +O2 +MAIN`

In this case, the Oberon-2 compiler will be invoked regardless of the file extension.

## Error reporting

If either compiler detects an error in your code, an error description will be displayed. In most cases a copy of the source line will also be shown with a dollar sign `"$"` placed directly before the point at which the error occurred. The format in which XDS reports errors is user configurable (See Error message format specification), by default it includes a file name, a position (line and column numbers) at which the error occurred, an error type indicator, which can be [E]rror, [W]arning or [F]ault, an error number, and an error message.

##### Example

    * [bf.mod 26.03 W310]
    * infinite loop
      $LOOP

## Building a program

To have you program automatically linked, invoke the compiler in the MAKE mode:

`` `xc =m hello.mod`

In this mode, the compiler processes all modules which are imported by the module specified on the command line, compiling them if necessary. Then, if the specified module was a program module, the linker is invoked.

However, if your program consists of several modules, we recommend to write a project file. In the simplest case, it consists of a single line specifying a name of a main module:

`!module hello.mod`

but it may also contain various option settings. The following invocation

`` `xc =p hello.prj`

will compile modules constituting the project (if required) and then execute the linker.

Here is a more complex project file:

    % debug ON
    -gendebug+
    -genhistory+
    -lineno+
    % optimize for Pentium
    -cpu = pentium
    % response file name
    -mkfname = wlink
    -mkfext  = lnk
    % specify an alternate template file
    -template = wlink.tem
    % linker command line
    -link = "wlink @%s",mkfname#mkfext;
    % main module of the program
    !module main.mod
    % additional library
    !module clib3s.lib

After successful compilation of the whole project the compiler creates a linker response file using the specified template file and then executes a command line specified by the LINK equation.

## Debugging a program

XDS compilers generate debug information in the stabs format and allow you to use any debugger compatible with that format (for example, GDB). However, the postmorten historyfeature of XDS run-time support may be used in many cases instead of debugger. To enable this feature, the option LINENO should be set on for all modules in the program and the option GENHISTORY for the main module of the program; the program also has to be linked with debug info included. If your program was built with the above settings, the run-time system dumps the stack of procedure calls on an abnormal termination into a file called `errinfo.$$$`. The HIS utility reads that file and outputs the call stack in terms of procedure names and line numbers using the debug info from your program's executable file.

##### Example

    MODULE test;

    PROCEDURE Div(a,b: INTEGER): INTEGER;
    BEGIN
      RETURN a DIV b
    END Div;

    PROCEDURE Try;
      VAR res: INTEGER;
    BEGIN
      res:=Div(1,0);
    END Try;

    BEGIN
      Try;
    END test.

When this program is running, an exception is raised and the run-time system stores the exception location and a stack of procedure calls in a file `errinfo.$$$` and displays the following message:

    #RTS: unhandled exception #6: zero or negative divisor

    File errinfo.$$$ created.

The `errinfo.$$$` is not human readable. The HIS utility, once invoked, reads it along with the debug information from your program executable and outputs the call stack in a more usable form:

    #RTS: unhandled exception #6: zero or negative divisor
    ------------------------------------------------------------
    Source file                     LINE  OFFSET  PROCEDURE
    ------------------------------------------------------------
    test.mod                           5  00000F  Div
    test.mod                          11  000037  Try
    test.mod                          15  000061  main

The exception was raised in line 5 of `test.mod`, the `Div` procedure was called from line 11, while the `Try` procedure was called from line 15 (module body).

Note: In some cases, the history may be inaccurate. See Postmortem history for further details.