Translating

Translation from Object Icon source files to intermediate .u files is done by the program oit.

Input source files should have the suffix .icn (but see the -A option below). To translate one or more files, invoke oit as follows :-

oit -c file1.icn file2.icn ...

This will produce file1.u, file2.u etc.

Linking

The oit program is also used to link .u files together to form an executable file that can be run :-

oit -o prog file1.u file2.u ...

You can also go directly from the source file to the executable if you wish. In this case the intermediate .u files are deleted. For example :-

oit myprog.icn

Translates and links myprog.icn into an executable myprog.

Command line options

oit accepts the following command-line options :-

• -n Only translate a .icn to a .u file if it is out-of-date.
• -B Bundle the oix executable in the output.
• -M Add an empty main procedure if it is missing.
• -m Preprocess using m4.
• -Z Use zlib compression on the icode file.
• -W Exit with an error status if there were warnings.
• -c Stop after producing ucode files.
• -f Enable full string invocation by preserving unreferenced globals and methods during linking (equivalent to invocable all in a source file).
• -g Enable full string method invocation by preserving unreferenced methods during linking (equivalent to invocable methods in a source file).
• -o file Write the executable program to the specified file.
• -s Suppress informative messages during translation and linking (equivalent to -v 0)
• -O i Optimization level during linking. 1 means do optimizations, 0 means don’t (default is 1).
• -v i Set verbosity level of informative messages to i.
• -l i Configure the amount of source location info to store in the icode. 0 means none, 1 means store location info for procedure call and stack tracebacks (the default, 1, adds about 10% more space compared to option 0) and 2 means additionally store location info of all symbols (costs another 5% of space).
• -L During linking, output a .ux file giving information about the icode file. This is only useful if you are interested in the virtual machine instructions used by oix.
• -I During code generation, output a dump of the intermediate code, both in its raw and optimized state. This is only useful if you are interested in the internals of oit.
• -D k[=v] Define or clear a preprocessor symbol.
• -E Direct the results of preprocessing to standard output and inhibit further processing.
• -b i Base option in icode file; 0 means zero base.
• -A Treat files other than .icn or .u files as source files.
• -V Announce version and configuration information on standard error.

Invocable options

oit will try to remove unused parts of a program before generating an output file. This obviously reduces the output file’s size, and also helps improve the resulting program’s startup time and memory usage.

By default, oit will remove unused globals (procedures, records and classes), as well as unused methods. The latter are determined simply by checking whether a method’s name is referenced via a field name anywhere in the program. Globals are removed completely from the resulting program; removed methods are replaced by a stub method which, if it is somehow invoked, raises a runtime error.

Sometimes it is desirable to override this default behaviour because occasionally a global symbol or method may still be used, even if it is not explicitly referenced anywhere in a program. For example :-

• a program might be written in order to be loaded by another program, which would then use its procedures and classes. But these may not be referenced by the program itself.
• a program may use functions like lang.Prog.get_global() and lang.Class.get() to look up global symbols or methods by string name. These won’t be detected as references.
• a program may use lang.decode to decode a string previously encoded with lang.encode, but a symbol in the encoded string is not otherwise referenced in the program.

To deal with these sort of situations the invocable declaration can be used to change the default behaviour just described.

• invocable all - don’t remove any unused globals or methods at all.
• invocable methods - remove unused globals, but don’t remove any unused methods from within the remaining classes.
• invocable g, where g is some global name - don’t remove this global and, if it is a class, don’t remove any of its methods (including inherited ones).
• invocable .f, where f is some field name - don’t remove any methods with this name in any (referenced) classes.

Two command line options to oit are also provided. -f is equivalent to using invocable all, whilst -g is equivalent to invocable methods.

Running

The runtime system is contained in the program oix. It is not normally necessary to run that directly because the executable built by oit invokes it automatically.

oix can be invoked by oit by appending -x to the command line (followed by any desired runtime arguments). For example

oit myprog.icn -x

translates, links and runs myprog.icn. The executable file myprog is not deleted after completion (unlike the intermediate .u file).

Runtime environment variables

Several environment variables affect the behaviour of the interpreter, as shown in the following table.