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

java -Xmx1400m -jar Proteus.jar [options...] ll file

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

java -Xmx1400m -Xms1024m -classpath <JDK_HOME>\tools.jar;Proteus.jar com.emt.proteus.process.Proteus [options...] ll file

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

-package <package>

Specifies how much of the Proteus process to execute

Parse the ll file only
-process parse
Build the source files and the program meta data (will empty both the classes and generate folder)
-process generate
Just apply the goto substitution process, to the classes directory
-process goto
Process all aspects of the Proteus chain except building a jar.
-process build
Process all aspects of the Proteus chain including building a jar. This is the default
-process complete

You may specify your own custom launcher using this option.

-main-class fully qualified classname

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.

-disable-single-jar true|false

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

-source-path mysrc1;mysrc2

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

-class-path lib.jar;classFolder

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.

-interpret function1;function2;function3

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

-generate folder

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

-classes folder

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

-force-name true|false

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.

-remove debug;info;warning

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().

-skip-generation unused1;unused2

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...'

-aliases original=newname;...

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

Where the content of 'properties' is similar to the below
package=org.proteus.myapp sourcepath=/home/usr/proteus/myfunctions generated=/home/usr/proteus/generated classes=/home/usr/proteus/classes # These are logging functions remove to speed up execution remove=\ info;\ debug;\ warn;\ # functions are not actually used anywhere but found in ll skip-generation=\ unusedFunction;\ function2;\ warn;\
Advanced - Function resolution

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, is provided