-
Notifications
You must be signed in to change notification settings - Fork 4
MiniTutorial
To check for proper installation at your site, run
You should see output marked by `->` as above. (The installation directory `/opt/ocs-2.4b` may differ at your site.)
If the command `ocs` is not found, you must extend your search path by `/opt/ocs-2.4b/bin`. If `ocs info` still doesn't work, check the installation at your site (see [raw-attachment:wiki:Documentation:install.pdf]).
To run the examples discussed in this tutorial, you should copy the directory `/opt/ocs-2.4b/examples` to your home directory:
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:
Like `make`, `ocs` is "lazy" and performs only the steps necessary to bring its target up to date. Thus, calling `ocs` again yields:
Only if sources change (reflected by their time stamps) will (partial) recompilation be carried out:
`ocs` places intermediate compilation results in a subdirectory called `OCS`. In order to enforce recompilation, or to recover disk space, simply remove this directory:
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:
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 to `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 project definitions file. If the environment variable `OCSPROJECT` is defined, it must point to a file which contains the project definitions.
The Opal compilation system comes with a set of non-basic libraries which support additional functionality and provide an interface to other software packages such as !Tcl/Tk.
An example for accessing these libraries can be found in `examples/Graphics/Queens`. This is an animated version of the 8-queens problem based on Opal's window library, which is in turn based on !Tcl/Tk. Compile with `ocs` and execute:
If `./queens` fails because of missing shared libraries, use `ldd` queens to check for these libraries in detail. Depending on the operation system, you may have to use `ldconfig` or set `LD_LIBRARY_PATH` to solve the problem. In general, the Opal libraries are prelinked to contain a run-path pointing to "standard" locations (e.g. `/usr/openwin/lib` for the X11 library under Solaris).
The `SysDefs` file for this example shows how Opal's window library is included:
The variable `OPAL_LIBS` consists of a sequence of references to predefined variables describing library packages. In version 2.3n, the following libraries are supported:
* `$(OPAL_WIN)` - the windows library for GUI programming * `$(OPAL_TK)` - the Tk library * `$(OPAL_TCL)` - the Tcl library for integrating Tcl interpreters into Opal programs * `$(OPAL_READLINE)` - the GNU readline command-line editing tool * `$(OPAL_PARSERLIGHT)` - a library for combinator parsing * `$(OPAL_BASE)` - the Opal standard library (Bibliotheca Opalica) comprising a large collection of types and functions
Documentation of the libraries is available online: Bibliotheca Opalica Reference
Any number of Opal structures may be grouped together in a so-called subsystem and referred to as a custom library. (By convention, a subsystem corresponds to a physical directory.)
Consider a situation where you have written a number of related Opal structures dealing with that special `foo` data type you use every day. Suppose these structures are called `Foo1`, `Foo2` and `Foo3`. You might want to put these structures in a subsystem `foo` so you have them at hand for consistent refinement as well as easy access. You can do so by following these steps:
1. Create a suitable subdirectory `foo`. This might be somewhere in your home directory - if your subsystem is private - or some other place, if you want to share your code with others.
2. Assume (after copying) that the six files (`Foo1.sign` through `Foo3.impl`) reside in the (newly created) `foo` directory.
3. Create a file `SysDefs` with the following contents (the example below uses cat, whose input is terminated by ^D):
{{{
$ cd foo foo $ cat > SysDefs SYSKIND=sub NODENAME=foo STRUCTS=Foo1 Foo2 Foo3 ^D foo $
}}} Note that it is important that the value assigned to `NODENAME` is equal to the base name of the current directory.
If you run `ocs` in the `foo` directory, a library will be created (provided the Opal sources are context-correct). This results in (a) new file(s) `libfoo.*` within the subdirectory `foo/OCS`.
Remark: by running `ocs -sub foo Foo1,Foo2,Foo3` a file `SysDefs.foo` will be created which can be renamed `SysDefs`.
Let us assume that you intend to write a program (or a more complex subsystem) based on two libraries `foo` and `bar` (which have been created as above). Simply add the line(s)
to the corresponding `SysDefs` file.
If you have a whole hierarchy of libraries, these must be listed in a top-down manner. Finally, the standard libraries must be supplied by `$(GENSTDSYS)`.
Remark: inclusion of libraries can also be done via `ocs` command-line options, e.g. `ocs -top HelloWorld hello -s path-to-foo/foo -s path-to-bar/bar`.
The `oasys` tool is an alternative to the `ocs` command. It provides particularly useful functionality for interactive program development. Its interpreter-debugger allows to expressions to be evaluated "on the fly" or the execution of functions to be monitored.
In contrast to `ocs`, `oasys` is not batch-oriented, but has its own command line interpreter (which is effectively a Tcl interpreter). The most important commands have one-letter abbreviations; some of these are:
* `a STRUCTURE`: add `STRUCTURE` (and its dependent structures) to the set of known structures * `f UNIT`: define `UNIT` (a structure's signature or implementation part) as focus (context) for the evaluation of expressions * `e EXPR`: evaluate `EXPR` * `h CMD`: give help on `oasys` command `CMD` * `i`: print a short introduction to oasys commands * `q`: quit oasys
For demonstration we use the structure `Rational`:
Firstly, we have to add the structure `Rational` to the set of known structures:
Secondly, we choose one of the loaded units as the focus, that is, the context for the evaluation of expressions. The signature part imports integers to allow basic evaluations:
The prompt changes and indicates the current focus. Now we can evaluate Opal expressions. Before every evaluation, the structures are checked and recompiled, if necessary:
Subsequent evaluations are quicker:
Spaces or quotes may require expressions to be enclosed in curly brackets:
Errors in the evaluated expression are reported at line 0:
For further documentation of the following topics we refer to the [raw-attachment:wiki:Documentation:OasysManual.pdf].
* Executing monadic expressions * Linking executable programs * Customizing `oasys` (see also `examples/Integrator`) * Handling structures in multiple directories
The Opal compilation system contains support for generating documentation in either HTML or DVI format from the source code. The full documentation gives details for the operation of the documentation system DOSFOP. This document gives a short introduction into the usage of the documentation system.
Documentation is included in the form of special comments. Every comment which starts with a percent ("%") sign is treated as a comment. Source code is written in Texinfo (the same language which is used for the documentation of many GNU tools, e.g. `emacs`, `gcc`, ...). The most important Texinfo commands are:
* `@@`, `@{`, `@}` The only special characters are `@` (at sign), `{` and `}` (curly braces) which must be preceded by `@` (at sign). All other characters are included literally.
* `@code{text}` is used for references to identifiers from the source code.
* `@emph{text}` is used to emphasize text.
* `@ref{@Overview{structure name}}` inserts a (hyper-)link to the documentation of structure name.
The `ocs` command knows several targets for generating documentation. Some preparation is necessary, though:
* If you have used the `ocs -top` or `ocs -sub` command, create a link from the generated `SysDefs` file to a file just named `SysDefs`. * Define an environment variable `PROJECTROOT` which contains the absolute path to the directory where the Opal sources are located.
Then use one of
* `ocs doc` to generate HTML documentation * `ocs dvi` to generate DVI documentation
The result is placed in `doc/out.html` or `doc/out.dvi`.
If you use `bash`, type
If you use `csh` or `tcsh`, type