Proteus Manual

Proteus should be invoked with the java executable found within the bin directory of the installed Java Development Kit. In this case the command line is

This is necessary to obtain an Java Compiler. Alternatively, the jar containing the java compiler can be added to the class path

This option changes the default package to the specified value. The default value is org.proteus

Specifies how much of the Proteus process to execute

You may specify your own custom launcher using this option.

This option disables the generation of a single jar file. The contents of all directories in the -class-path value are included but any jars are not included (including runtime.jar and core.jar) and must be provided within the same folder. This is useful if the jar is large and you wish to wrap invocation within an applet.

This adds additional directories to the compilation path in order to provide additional functionality. These folders are searched for additional content

If you wish to include additional jars in the class path of compilation and generation then use this option to specify a semicolon delimited list of jars or directories

This is a semicolon delimited list of function names where the Proteus will interpret the function rather than generate Java source. The corresponding Java source file is a simple wrapper to the interpreter. Note that the inclusion of * means that all functions that would be generated will be interpreted. Interpreting functions provides a means to deal with large integer types (i128/i96) or files where the generated class file is to big for the JavaVM.

Specifies the location where generated source files will be created. This folder will be emptied prior to generation.The default value is ./generated

Specifies the location where class files program metadata will be created. This folder will be emptied prior to compilation. The default value is ./classes

If true force underlying function name be used for generated classes, otherwise function names are FlineNumber

Remove calls to the specified functions, which are specified as a semicolon delimited list. This is only possible if any return values are unused. Note this is useful to remove calls to logging functions etc.

Do not generate any code or similar for the specified semicolon delimited list of functions.

The use case for this that you have overridden a function using source in the sourcepath folder, but the generated implementation uses this functionality. For example, I have implemented ShowMessageToUser() which called ShowDialog which used a specific GUI library call. Therefore, I do not wish to generate ShowDialog().

Replace the names of the specified classes with the provided alias. This is useful if you have written a function class called 'MyFunction' and wish to use that function in preference to a mangled name e.g. '_ZN8Class...'

Read the options from a 'properties' file (# is comment and \ is a continuation character)

The ll file contains a number of functions, some of which are defined with the ll file itself and others are required from the runtime environment. A key feature of Proteus is that it is possible to provide alternate implementations of any function that is defined or declared in the ll file. In order to use this feature, it is necessary to understand the process of function resolution and what happens if no function can be found.

Any candidate functions are subclasses of com.emt.proteus.runtime.api.ImplementedFunction and implement a static 'call' method, and 2 instance methods

The initial part of the Proteus process, looks for all available functions that may be predefined.

1. it checks the contents of the directories specified in the -source-path option, in order. When it finds a public top level class with a matching name which extends com.emt.proteus.runtime.api.ImplementedFunction
2. it checks the contents of the jars/directories specified in the -class-path option, in order. When it finds a public top level class with a matching name which extends com.emt.proteus.runtime.api.ImplementedFunction
3. it checks the contents of the runtime.jar. When it finds a public top level class with a matching name which extends com.emt.proteus.runtime.api.ImplementedFunction

If a match is found, then that class is used. Otherwise, a stub class is generated that will throw an UnsupportedOperationException() when invoked.

There are 3 benefits of this approach

1. If a function is 'required' for compilation but never actually called, then the code can be generated and executed.
2. It provides a empty class that can be used as a template for writing the required functionality.
3. If the generated code for a function is suboptimal i.e. there is a more efficient 'pure java' way of writing that functionality, then a 'hand-coded' version can override generated function.

A worked example, message.cc is provided