# 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, xm`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

`` `xm hello.mod`

at the command prompt. `xm` 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 `xm` 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:

`` xm`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:

`` xm`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

After compilation of `hello` program you can invoke your C compiler. It is necessary to specify the paths to header files and library (use the name of appropriate library from you package). Consult your C compiler manual for syntax of the compiler command line.

       cc hello.c -Ic:\xds\include c:\xds\lib\libxds.lib

Type

       hello

to run your program.

The `xdsuser` script creates the `xcc` script that can be used to compile and link a simple program. Type

       xcc hello.c

If your project contains more than one module, we recommend to write a project file (See Project files) and use appropriate template file (See Template files). The following project file contains all necessary settings:

    % debug ON
    -gendebug+
    -lineno+
    % specify template file
    -template = xds.tem
    % specify a name of a makefile
    -mkfname = tmp
    -mkfext  = mkf
    % force generation of the makefile
    -makefile+
    % call the make
    -link = "make -f %s",mkfname#mkfext;
    % main module of the program
    !module hello.mod

It specifies the template file to use (`xds.tem`), the name of the makefile (`tmp.mkf`) and the make command line.

After successful compilation of the whole project the compiler creates the makefile and then executes the command line, specied by the LINK equation. The `xds.tem` template file defines a template for a makefile. The following invocation

`` `xm` `hello.prj =p`

will compile modules constituting the project (if required) and then execute the make. See Template files for the full description of template files. See also the project files, generated by the `xdsuser` script.

## Debugging a program

XDS allows one to use any standard debugger. However, the postmorten historyfeature of XDS run-time support may be used in may cases instead of debugger. To enable this feature the option GENDEBUG should be set for all modules in the program; the debug mode should also be set for a C compiler and linker.

If your program is compiled in this mode, the run-time system will print a stack of procedure calls (a file name and a line number) on abnormal termination of your program.

##### 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 prints the exception location and a stack of procedure calls. If the option LINENO is ON, all information will be reported in terms of original (Oberon-2/Modula-2) source files:

    #RTS: No exception handler #6: zero or negative divisor.
    test.mod              5
    test.mod             11
    test.mod             15

The exception was raised in line 6 of `test.mod`, the `Div` procedure was called from line 12, while the `Try` procedure was called from line 16 (module body). If the option LINENO is OFF, all information will be reported in terms of generated C files:

    #RTS: No exception handler #6: zero or negative divisor.
    test.c               17
    test.c               27
    test.c               36

See Code generation for additional details.