OfrontTM 1.2.3 for Windows under BlackBox 1.4
Copyright (c) Software Templ OEG, 1994-2002
What is Ofront?
Ofront is a tool that translates Oberon-2 programs into semantically equivalent C programs. Ofront for Windows is an implementation of Ofront for PCs running under Microsoft Windows 3.1, NT or 95. For Windows 3.1, the 32-bit extension win32s is required. Ofront for Windows is primarily intended as a cross development tool for embedded systems, Unix platforms and the like. Due to the heterogeneous requirements of such systems an extensive module library bundled with Ofront for Windows would not be very helpful. Instead Ofront for Windows allows to reuse libraries written in C or other foreign languages with very little effort and without any run-time overhead. Ofront for Windows also allows to cross-translate to Unix platforms providing much more convenient editing facilities and error handling. Ofront can be configured to translate against the libraries of those platforms (see below). For more detailed information on how Ofront works please refere to the "Ofront - Oberon-2 to C Translator, User Guide". This document focuses on the particular version of Ofront runing under Microsoft Windows.
Differences to previous version
+ Version 1.2.3: path separator changed from blank to semicolon
+ Version 1.2.2: uses BlackBox 1.4 as a host system
+ Version 1.2.1: uses BlackBox 1.3.2 as a host system
+ creates a new header file only if changes to an existing header file in the output directory are detected. This allows automatic make tools to recompile only changed modules.
+ Version 1.2: supports Ofront 1.2 with multidimensional open arrays and ANSII-style prototypes
+ uses BlackBox 1.3 rather than Oberon/F as a host system
+ portable symbol file format allows for cross translation to different target platform, e.g. Unix
+ easier to install due to automatic menu bar extensions in BlackBox 1.3
+ several minor fixes and updates
+ navigation tool included for convenient source code browsing
+ command OpenDocuments has been removed since it is available in Dev->Open File List
+ standard BlackBox error markers are used instead of specific Ofront error markers
BlackBox component builder
Ofront for Windows runs as a subsystem of the BlackBox component builder (version 1.4) provided by Oberon microsystems Inc. of Zurich, Switzerland. It strictly follows the Windows user interface conventions. Everybody familiar with Windows should immediately be able to use the integrated Ofront development environment. Creating documents, editing, printing, etc. are done in the same way as in standard Windows program. New Oberon source files should be generated as Oberon documents, which have the filename extension .odc. In the Windows file manager you may want to associate the filename extension .odc with the command BlackBox.exe. Oberon documents are not just plain ASCII texts but may contain attributes such as fonts, colors and vertical offsets. A multi-level undo-facility and the ability to insert rulers or other objects in the text are provided by the BlackBox text system as well.
Installation
It is assumed that BlackBox component builder 1.4 is installed and operatiopnal on your machine. Installation of Ofront then means to create the Ofront subsystem. For that, simply copy the distribution directory (rooted in a directory named Ofront) into the BlackBox installation directory. Ofront must be available at the same directory level as other subsystems such as Text, Dev or Host. In order to extend the menu bar with the Ofront menu simply restart BlackBox or activate the command Info->Update All Menus from within the running BlackBox process. In order to make the Navigator tool available (see below) you also have to install the Nav subsystem. (Acknowledgement: The Navigator tool has been based on a similar tool provided by Guy Laden.)
The Ofront menu items
The Ofront menu contains all commands that are necessary to use Ofront for Windows. The following explains the available commands.
Tool...
opens a tool dialog for convenient work with a Translate button and allows to specify the translation options and the directory search path. The defaults for these settings are stored in file Ofront\Rsrc\Strings.odc, which is a BlackBox text document that may be freely edited and stored again. The two most important entries in Strings.odc are options and directories, which specify the defaults for the translation options and the directory search path respectively. An entry in Strings.odc consists of a key followed by a TAB character followed by an arbitrary character sequence up to the end of the line. The translation options are identified by single letters and may be specified in any order. The directory search path specifies a list of directory names separated by semicolon characters. The directory names may be absolute or relative to the startup directory. Directory search is used by Ofront for opening symbol files, prefix files, the parameter file and source files when translating or opening a list of modules. In the list of directories, files are searched from left to right. In addition, the left-most element in the search path specifies the destination directory, i.e. the directory in which Ofront puts its output files. If a specified directory does not exist, Ofront asks whether it should create it or abort the command. The directory search path field in the tool window may be edited to specify a different search path. A search path of the form #ofront:xxx signals Ofront to look up the entry xxx in the strings.odc file. This allows to prepare multiple search path's for the various projects that might be worked on.
Translate
translates the module in the current window. The translation options and the search path are taken from the tool window. Under Win 3.1 module names are truncated to the first 8 characters to fit into the DOS 8+3 jacket. Errors are marked directly in the translated text by inserting error markers (exactly as it is done by the BlackBox compiler). Clicking on such an element displays an error message in the bottom status bar. Double clicking an error marker expands the marker so that it shows the full error message at the error position. Translation of a module also writes a log in the Log window. If warnings are encountered, they are written to the log as well.
Translate Module List
translates a list of Oberon modules specified textually by a list of selected module names or qualified identifiers. The directory search path is taken from the tool window, however, the translation options aren't. The default options for translation of a module list are always xatp. The module list may specify additional options using / to mark options followed by one or more option characters. Options specified in front of the module list affect all modules, options specified behind a module affect only this very module.
Example: /s M1 M2 M3 /m
This means that option s is specified for all modules whereas only M3 is translated as a main module. The complete list starting with / and ending with m must be selected. Translation stops after the first erroneous module. The erroneous document will be opened with error markers inserted just as in the case of translating the module inside the current window.
Show Definition
shows the definition of an Oberon module by decoding the module's symbol file. The name of the module to be decoded must be specified by the text selection. Qualified identifiers may be specified as well, however, only complete modules will be decoded.
Locate...
opens a tool dialog that allows to locate the caret of the current text document at the specified line number (Locate Line) or text position (Locate Pos). The latter may be used for locating warnings generated by Ofront. Invalid positions are acknowledged by a beep tone. The command Next Error locates the caret at the next error marker starting from the current caret position (cf. Dev->Next Error).
Navigator
opens a tool dialog that allows quick navigation in the source code of the active document (the original idea and implementation is due to Guy Laden). The navigator scans the source code and shows a list of procedures that can be clicked on. Clicking on a procedure name moves the text to the beginning of the specified procedure. The procedure list can be filtered according to two criteria:
(1) a name pattern specified in the top most text field. The character * is used as a wildcard character that replaces any number (including zero) of arbitrary characters. A terminating wildcard character is implicitly appended to the search pattern. Therefore typing the first letter of a procedure name restricts the procedure list to those procedures that start with the specified letter. Specifying further characters will trim the list more and more.
(2) a group selected in the middle part of the dialog:
<all> all procedures.
*Guard* all procedures that match with the pattern *Guard*. This name pattern is often used to guard something.
*Notif* all procedures that match with the pattern *Notif*. This name pattern is often used to notifysomebody about something.
-.STATIC.- all static procedures, i.e. <all> without type-bound procedures.
Type name all procedures bound to this type.
Parameterizing the translation process
Without special provisons Ofront for Windows issues a warning before translating a module. This warning occurs if the parameter file Ofront.par is not found, i.e. if it is not in the directory search path. In this case Ofront does not know vital properties of the target platform and C compiler and assumes standard values which work in many cases but not all! For serious work you should always provide a parameter file Ofront.par. For example, when translating for a Unix platform X, you should use the Ofront.par file that comes with Ofront for platform X (lookup the directory named X\V4). More details about creating your own parameter file are contained in the Ofront User Guide.
Cross translation
Ofront for Windows allows to cross translate Oberon-2 programs e.g. for Unix platforms. To do so, it suffices to make the Ofront libraries of those platforms available to Ofront for Windows. This can be done by copying or linking the directory that contains the library (e.g aix\V4) to your Windows environment and specifying the path under which this directory is available in the Ofront directory path in the Tool window. The text field 'directories' contains a semicolon separated list of directories which will be used by Ofront to look up files for the translation process. Please check that you do not merge libraries for different target platforms in the directory search path. Otherwise the generated C code might not function properly.
Example: in order to use directory C:\temp as destination directory and the Oberon V4 library for AIX, which is assumed to be available under G:\AIX\V4 specify in field directories:
C:\temp;G:\AIX\V4
Text Import/Export Filters
For more conveniently accessing ascii texts or other external text formats the BlackBox import/export filters may be configured in module Config. (Code\Config.ocf). Please refere to the documentation of module Converters for more details on installing import/export filters.
The Ofront run-time system sources
For providing a runtime environment for a new platform (such as an embedded system or a particular combination of PC memory model and C compiler) the Ofront runtime module sources are required. Please contact the author (see address below) should you need these sources.
Further documentation
For more information about Ofront in general and the various Ofront Unix versions please consult the "Ofront - Oberon-2 to C Translator, User Guide".
Contact
If you encounter any problems with Ofront for Windows please contact
Dr. Josef Templ
Software Templ OEG
Voeststr. 33
4060 Linz, AUSTRIA
fon [0 [043] 732] 676081
fax [0 [043] 732] 676082
GSM: 0 [043] 664 3841348
e-mail: Josef.Templ@aon.at
http://members.aon.at/software-templ/index.html