### Getting started with the `ocs` tool

The compilation of Opal sources is driven by a single, batch-oriented command `ocs`, which is similar to the traditional Unix tool `make`.

For example, we compile the mandatory hello-world program with `ocs` as follows:

        $ cd examples/HelloWorld
        examples/HelloWorld $ ocs
    ->  Generating rules for hello'HelloWorld ...
    ->  Checking Signature of HelloWorld ...
    ->  Compiling Implementation of HelloWorld ...
    ->  Generating  object code for HelloWorld ...
    ->  Generating startup code for hello ...
    ->  Linking hello ...
        examples/HelloWorld $ ./hello
    ->  Hello World!

Like `make`, `ocs` is ``lazy'' and performs only the steps necessary to bring its target up to date. Thus, calling `ocs` again yields:

        examples/HelloWorld $ ocs
    ->  Nothing to be done for `all'.

Only if sources change (reflected by their time stamps) will (partial) recompilation be carried out:

        examples/HelloWorld $ touch HelloWorld.impl
        examples/HelloWorld $ ocs
    ->  Generating rules for hello'HelloWorld ...
    ->  Compiling Implementation of HelloWorld ...
    ->  Generating  object code for HelloWorld ...
    ->  Generating startup code for hello ...
    ->  Linking hello ...

`ocs` places intermediate compilation results in a subdirectory called `OCS`. In order to enforce recompilation, or to recover disk space, simply remove this directory:

        examples/HelloWorld $ rm -rf OCS
        examples/HelloWorld $ ocs
    ->  Generating rules for hello'HelloWorld ...
        ...
    ->  Linking hello ...

> Sometimes `ocs` gets confused by changes on the `SysDefs` file - for example, if structures have been renamed. If the operation of `ocs` fails for such reasons, removing `./OCS` helps.

`ocs` gets its information from a file called `SysDefs` (like `make` from `Makefile`) in the current directory. For the hello-world program, this file has the following contents:

        examples/HelloWorld $ cat SysDefs
    ->  TOPSTRUCT = HelloWorld
    ->  TOPCOM = hello

A `SysDefs` file contains a set of variable definitions in a `make`-like syntax. For hello-world, we only had to define the following variables: `TOPSTRUCT`, the name of the structure which contains the top-level monadic command, and `TOPCOM`, the name of this command.

> Remark: by running `"ocs -top HelloWorld hello"`, a file `SysDefs.HelloWorld-hello` will be created which can be renamed `SysDefs`.

A `SysDefs` file may contain further variable definitions, and `ocs` runs in a variety of modes supporting diverse options. For further documentation, see the `ocs(1)` manual page.

The operation of `ocs` may be further customized by a <emph>project definitions file</emph>. If the environment variable `OCSPROJECT` is defined, it must point to a file which contains the project definitions. See `examples/Customize` for examples of project definitions files.

Last modified: Tue Nov 25 16:04:12 1997