Eve Application Development

Michael L Brereton - 02 February 2008, http://www.ewesoft.com/

 

Beginners Guide - Contents

>> Next: Starting Your Application

Setting up the Eve SDK

Eve Application Development

Setting up the Eve SDK

Introduction

What's in the SDK

Compiling and Running Eve Applications – Expert

Compiling and Running Eve Applications - Part 1, Quick Start

Compiling and Running Eve Applications - Part 2, Advanced Topics

Configuring Eclipse for Eve Development

 

Introduction

Thank you for downloading and installing the Eve SDK. This document will help you set up your standard Java SDK tools and IDE to be able to easily write, compile, execute and debug Eve applications.

 

By this time you would have already read about Eve, its capabilities and its differences from a standard Java VM. However at this point it is best to briefly mention some important aspects of the Eve platform.

 

o       A Native Eve VM is one that has been written specifically for a particular platform. Native Eve VMs are available for Microsoft PocketPC, Microsoft Smartphone, Microsoft Windows, Linux Desktop and some Linux Mobile systems. On Windows desktop the VM is a single executable (eve.exe) while on Windows mobile systems, the VM consists of a small launcher executable (eve.exe) and the VM itself compiled as a dynamic linked library (eve.dll).

o       Native Desktop Eve VMs contain all classes in the Eve library (the eve.xxx packages) as well as some classes in java.xxx packages. The mobile versions of the Eve VM have some packages removed but these packages are available in the file eve-extended.eve which can be optionally installed with the VM to provide full desktop functionality.

o       Because the native Eve VM does not contain the full standard Java library, it is therefore not a fully functional, standard Java VM. It can be thought of a VM that implements some Java classes, plus an extensive Java compatible library (the eve.xxx packages).

o       An Eve Application or Eve Compatible Library is one that targets the Eve VM. That is, it only uses classes which are in the Eve library, or which are from another Eve Compatible Library.

o       An Eve Application can therefore be run on any native Eve VM, since the classes required by the application will be within the native Eve VM.

o       An Eve Application can also be run on any Java VM with the use of an external JAR or ZIP file which contains the Eve library specially written for a true Java VM. There are two such external library files provided by: eve.jar and JavaEve.zip. The use of these two files and the differences between them are discussed in later sections.

 

It is important to also note that an Eve Application is a true Java application. All classes and methods used by an Eve Application and which are contained within the external Eve library JAR/ZIP files are true Java classes. The Eve VM only runs classes compiled by a standard Java compiler – no extensions to the language itself are used. This is why an Eve Application can be run on any system with a Java VM and can also be converted easily into an Applet without any additional programming.

 

What's in the SDK

The SDK contains within it several directories. These are:

o       classes - which contains JAR/ZIP libraries need to compile and debug Eve Applications.

o       programs - which contains the EveMaker program builder along with its associated support files. This is used to create .eve files from your applications and other distributable file types for your application.

o       include - which contains the eve_eni2.h file used for writing DLLs to interface to both Native Eve VMs and Java VMs to implement native Java methods.

o       docs – which include the API documentation and the basic Programming Guide.

 

Compiling and Running Eve Applications – Expert

This Expert section is intended for developers who are experienced in Java development and in configuring their Integrated Development Environment (IDE), or who have had prior experience using Eve. Other users may wish to go to the following sections for more detailed explanations on compiling and running Eve applications.

 

Compiling Eve Applications - CompileEve.zip

 

The file CompileEve.zip is within the classes directory of the SDK and it is used as the library for compiling Eve applications. When compiling Eve applications, you must instruct your compiler/IDE to:

 

1.            Disregard standard Java libraries - i.e. tell the compiler not to use the standard Java SDK libraries since they will contain common Java classes which are not supported by the Eve VM.

2.            Include the file CompileEve.zip as a class library - i.e. tell the compiler to look within this file for all classes. Of course you would add the project class directory and any other Eve compatible libraries that you may have.

Under IDEs like Eclipse this would mean removing the reference to JRE System Library in the Libraries tab of the Java Build Path of the Project Properties, and adding instead the file CompileEve.zip as an External Jar.

Running/Debugging Eve Applications with a Java VM - JavaEve.zip

 

The file JavaEve.zip is also in the classes directory of the SDK and it is used when you wish to run a Eve application using a standard Java VM (Java 2 or better). The JavaEve.zip file contains:

1.            Debug builds of the Eve class library for Java VMs. This allows a Java VM to execute a Eve application.

2.            Full source code to all the classes in the zip file. This allows you to trace/step into the Eve library itself when debugging your Eve applications.

 

So, in order to use a Java VM to run an Eve application, you must provide JavaEve.zip as an external library (i.e. you must include it in the classpath for the VM). You must note however that you never execute your main runnable Eve class directly - you must always run the class Eve (which is within the JavaEve.zip library) and then provide your main Eve class as an argument. For example, if you wished to run the class tests.HelloWorld you would have to run:

 

EveSDK\classes>java -cp JavaEve.zip;./ Eve tests.HelloWorld

 

Note the Java VM will actually execute the class Eve (contained in JavaEve.zip). The Eve class will setup the Eve library, then load the class specified as the argument to Eve (tests.HelloWorld) and then pass execution on to that class, including any further arguments provided.

 

Any special Eve VM Command Line Switches (e.g. "/p" to simulate a PocketPC, or "/s" to simulate a Smartphone) must be placed between Eve and the target class name. e.g.:

 

EveSDK\classes>java -cp JavaEve.zip;./ Eve /s tests.HelloWorld

 

Therefore to configure your IDE to execute/debug a Eve Application you must:

1.            Include the file JavaEve.zip in the classpath of the Java VM you are using. Under Eclipse this means adding it in as an External Jar.

2.            Always specify the target class as Eve (with no package specifiers).

3.            Provide the actual target class you wish to execute as an argument to Eve using full dot notation.

Compiling and Running Eve Applications - Part 1, Quick Start

The classes directory within the SDK is the location for the important SDK library files and for the example Java packages. Within this directory you will find two ZIP files JavaEve.zip and CompileEve.zip, and two subdirectories containing sample Eve classes, solitaire and tests. We will now try to compile and run the HelloWorld.java file located in the tests directory. The examples given show how to do this from the command line, but doing this from an IDE is discussed later.

 

Java Class Organizations

 

Remember that under Java, classes are organized into packages and sub-packages and that these packages are represented on the file system as directories (folders). The full class name is written in dot notation like: eve.net.Link. So the Java source file for this class would be expected to be a file called Link.java in a directory called net which itself would be in a directory called eve.

 

The file HelloWorld.java is in a directory called tests (within the classes directory) because the HelloWorld class has been placed in the tests package. This is indicated by the first line of code in HelloWorld.java: package tests;

 

The JavaEve.zip Library

 

The zip file JavaEve.zip contains all the class files needed to both compile and run a Eve application on a Java VM that is at least Java 2 compliant. It contains all the classes in the Eve library as documented in the Eve API, plus some classes and packages that support the Eve library when running on a Java VM. These additional classes exist in the library but they are not part of the public Eve API and so you should not directly use them in your applications.

Compiling using JavaEve.zip

 

We will now attempt to compile the tests/HelloWorld.java file using the JDK installed on your system. To do so the current working directory for the command line should be the classes directory of the SDK. Then you use the command:

 

EveSDK\classes><path_to_javac>/javac -classpath JavaEve.zip;./ tests/HelloWorld.java

 

The part that reads: -classpath JavaEve.zip;./ tells the compiler to look both in JavaEve.zip and in the current directory to find classes during compilation.

 

If this compilation was successful there will be no messages generated by the compiler and a file called HelloWorld.class will be created within the tests directory.

 

Running using a Eve VM

 

If there is a native Eve VM available for your platform you can run the class files like this:

 

EveSDK\classes><path_to_eve>/eve tests.HelloWorld

 

Note the notation for the class - tests.HelloWorld. When we were compiling we specified a file name for the compiler to work on. Here we are specifying a class name - so we provide the full package name and the class name, but we do not put a .class at the end. Note that we do not need to specify a class path, since the Eve VM will look in the current directory by default for classes. Since the class name is tests.HelloWorld the VM will look automatically for a HelloWorld.class file within a tests directory in the current directory. On my system the command line would be:

EveSDK\classes>c:\"program files"\eve\eve tests.HelloWorld

 

If you get a java/lang/NoClassDefFoundError this indicates that you are probably within the wrong directory - ensure that you are in the classes directory of the SDK.

 

Note that there are some special Eve VM Command Line Switches that can be used to alter the runtime behavior of the VM. These include:

/p or /p5 or /p6 - to simulate a Microsoft PocketPC version 2003 or Mobile 5 or Mobile 6 (all windows will appear at the top left of the desktop in this mode - do not move them from there.)

/s or /s5 or /s6 - to simulate a Microsoft SmartPhone version 2003 or Mobile 5 or Mobile 6 (all windows will appear at the top left of the desktop in this mode - do not move them from there.)

/w <width> - to specify a specific device screen width in pixels.

/h <height> - to specify a specific device screen height in pixels.

/n - to specify a system where multiple windows are not allowed (you should specify a screen width and height with this option).

/r - to specify that the VM should consider itself running on a mobile system.

 

These switches must be placed immediately before the name of the class to execute. For example try this:

 

EveSDK\classes>c:\"program files"\eve\eve /s tests.HelloWorld

 

Running using a Java VM

 

To run a Eve application with the Java VM you run the command line:

 

EveSDK\classes>java -cp JavaEve.zip;<extra_class_paths> Eve <package_and_class>

 

Please note the Eve that is before the full class name that you wish to run. So we would run HelloWorld by doing this:

 

EveSDK\classes>java -cp JavaEve.zip;./ Eve tests.HelloWorld

 

Please not that the Java VM does not run the class you specified directly. In fact the Java VM is directed to run the class called Eve (which is within the JavaEve.zip file). This class then starts up the Eve library and then locates, loads and runs the target class file (e.g. tests.HelloWorld).

 

Note that the Eve VM command line switches described above also work here. You specify the switches between the Eve and the target class name. e.g.:

 

EveSDK\classes>java -cp JavaEve.zip;./ Eve /s tests.HelloWorld

 

Why would you want to run your application using a Java VM when you intend to run on an Eve VM? The most important reason to do this during application development is to take advantage of the debugging features afforded by a true Java VM. A true Java VM allows you to step through your code line by line if needed and also allows you to view the values of fields and variables as you step through the application. These features are currently not provided by an Eve VM.

 

What is the eve.jar file? In the classes directory you will also find the file: eve.jar. eve.jar can also be used to compile and run Eve programs, however unlike JavaEve.zip the eve.jar file does not contain any source code and the class files may not have debugging information in them. Therefore when you are debugging your Eve application you will not be able to trace into the classes in the Eve library. However eve.jar is much smaller than JavaEve.zip and so when you are distributing your application, you may wish to include eve.jar instead of JavaEve.zip.

 

Compiling and Running Eve Applications - Part 2, Advanced Topics

Problems compiling with JavaEve.zip

 

When you tell your compiler to use JavaEve.zip during the compiling of your applications, it will look for classes that are in JavaEve.zip and, by default, classes which are in the standard JDK. This is necessary because JavaEve.zip does not contain the java.xxx classes which are part of the Eve library. When the compiler comes across java.xxx classes it will use the classes from the standard JDK library. While this is normally OK to do, there are two potential problems with doing this.

 

1.            The standard JDK library will contain a number of other class files which are not supported by a native Eve VM. So it will be possible for you to refer to classes like java.awt.Color in your Eve application, which will compile correctly but which will generate a “class not found” run-time error when run on a native Eve VM.

2.            Not all of the methods in the java.xxx packages are implemented by the Eve VM.

 

Compiling using CompileEve.zip

 

To ensure that the compiler only allows the compiling of classes and methods which actually are supported by the native Eve VMs, you should tell the compiler to look in the file CompileEve.zip which also exists in the classes directory along with JavaEve.zip. This zip file contains only the classes that are actually supported by a native Eve VM.

 

When running your applications under Java, you should continue to use JavaEve.zip so that you can use the debug features of your IDE.

 

Configuring Eclipse for Eve Development

 

Eclipse is the recommended IDE for Eve developers. It is extremely powerful and has an extensive number of tools for Java developers.

 

Configuring Compiling (Build) using CompileEve.zip

 

The image below shows the modification of an Eclipse Project telling the compiler to use CompileEve.zip as the source for classes during build. Note that originally the Libraries tab contained an entry for JRE System Library which was removed before the Add External JARs button was pressed to add in CompileEve.zip.

 

 

Configuring Running/Debugging using a Java VM and JavaEve.zip

 

The image below shows the creation of a Run entry for an Eve application. Note that the Main Class is set to be Eve.

 

 

Next we set the actual target class we wish to run in the Arguments tab. For this example the target class is evesamples.ui.GridControl and I have specified the /p5 Eve command line switch which tells the Eve Library to simulate a PocketPC Mobile 5.

 

 

Last in the Classpath tab we have to include the JavaEve.zip file and exclude the CompileEve.zip file. The image below shows how the Classpath tab should look when correctly configured.

 

 

Note that when this Run entry was first created for this project, the CompileEve.zip file was included in the classpath - as a dependancy of the project under the UserEntries section. The IDE automatically includes all libraries used for compiling into the classpath used for running. Under most Java circumstances this is the right thing to do, but for our purposes, we need to remove CompileEve.zip. However there was no way to remove the CompileEve.zip entry alone - the entire project under User Entries had to be removed and then the Add Projects button was used to add the project back into the User Entries. This time, when the project was added, CompileEve.zip was not included, and this is what we want.

 

After that the Add External JARs button was used to add JavaEve.zip under User Entries.

 

Once this was done, the Run or Debug button could be used to execute the application using the Java VM.

 

Configuring Running using the native Eve VM.

 

To run a Eve application in Eclipse using the native Eve VM, you must configure an External Tool. To do this you select Run >External Tools >External Tools... from the main menu. Then select Program in the Configurations section and press New. You must give the entry a unique name and then locate the Eve VM by pressing Browse File System in the Location directory. The Working Directory should be set to be the directory where the application classes will be found. This may be set correctly by default, but if not use Browse Workspace or Browse File System to select the correct directory. The Arguments section should be set to the target class, with any VM command line switches placed before it as normal.

 

Once this has been configured then the external tool will execute the native Eve VM and it should run the target application.