Ewe Application Development

24 March 2003

Michael L Brereton

http://www.ewesoft.com/

Ewe Application Development 1

Writing Ewe Programs. 1

The Ewe Software Development Kit (SDK) 1

Setting up your Development Tools. 2

Setting up your Compiler. 2

Testing the Compiler. 2

Running your Programs. 2

Command Line Options. 3

Writing Ewe Programs

The Ewe virtual machine executes Java byte-code (i.e. Java programs that have been compiled into “.class”) files. Therefore you write Ewe programs in the same way that you write Java programs, by using an Editor or Integrated Development Environment (IDE) to write source “.java” programs, and then using a Java Compiler to compile them into “.class” files.

Ewe programs are different to Java programs in a few respects, but it is important to remember that Ewe programs can be executed by any Java VM as well as the Ewe VM. This makes your Ewe applications more portable than any other Java applications since Ewe VMs exist for platforms for which there are no feasible Java VMs (e.g. the Casio BE-300 devices, the upcoming Simputer PDA, and more to come).

The differences between Ewe and Java are:

The class library is different. Ewe does not use any of the classes in the standard “java.” packages, except for a selected number in the java.lang package. You should only use classes and methods specified in the Ewe API or classes provided in packages by third-party developers (or your own classes, of course). Many of the ewe packages are similar to the java packages so you will find porting your code to be fairly simple.
The threading model is different. Ewe uses a slightly different threading model to Java – it has the same features and functionality as Java (i.e. synchronization with lock objects that can be waited on and notified) but it is provided using a different mechanism and API. This is explained in a later chapter. The important thing to remember when programming is that you do not use the synchronized keyword, the wait() or notify() methods, and the Thread class. Instead you use an mThread class (for the thread itself) and Lock classes (for locking wait and notify methods).
Ewe programs start a little differently. Ewe provides many more options for starting your application, including via a static main() method.

The Ewe Software Development Kit (SDK)

This is available for free from the Ewesoft website and allows you develop Ewe programs on virtually any platform – including some mobile platforms. Even if there is no Ewe VM available for your development platform (e.g. Mac OS) as long as you have a Java 1.1 (or better) runtime environment or SDK, then you can compile and run your Ewe projects.

The Ewe SDK comprises the following components – all of which are platform independent:

The Ewe Class Library - Ewe-Classes.zip. This is used by your compiler when compiling your Ewe applications. If you do not have a Java compiler you can download one of the Jikes Java compilers from the Ewesoft website.
The Jewel Program Builder – Jewel.ewe and JewelData.jar. These two comprise the Jewel Program Builder. This application is used to package your class files into a single distributable .ewe file. It is also used to convert your application into platform specific executable files (e.g. Windows and WinCE .exe files) or Java .jar files or web Java applets.

Not included in the SDK, but available as a separate download:

A Ewe VM – which you will need to run your Ewe programs and to run the Jewel Program Builder. You should download and install the VM appropriate for your system from Ewesoft.com.

You can always use a Java VM to execute your Ewe programs. To do this you should use the Extract Resources tool under the Developer Tools tab of Jewel to extract the ewe.jar file. If you do not have a Ewe VM (and so cannot run Jewel) and still want to get ewe.jar you can extract it manually from the JewelData.jar file in a directory called resources. JewelData.jar can be treated as an ordinary ZIP file. You can also download ewe.jar directly from the Downloads page at Ewesoft.com.

You can use ewe.jar with a standard Java VM to execute Ewe applications. This gives you the advanced debugging features of a Java VM. Instructions for using ewe.jar with your Java VM are given here.
A Java Compiler – which you will need to compile your Ewe programs. If you have a standard JDK or Java 1.1 compiler, then this will work fine. Otherwise, you can download one of the Jikes compilers from the Ewesoft website. These are available for Windows desktop and for Linux desktop and certain mobile Linux platforms.

The Ewe API and Ewe Application Development guide – The API is the list of all Ewe classes and methods in HTML format, and the Ewe Application Development guide is this very document.

Setting up your Development Tools

The Ewe SDK is a single zip file containing various files within subdirectories. You should unzip the SDK into a development directory of your choice on your hard drive (e.g. C:\ewe or /usr/ewe).

Once all the files are extracted from the SDK zip file you will find the Jewel application in the programs subdirectory and the Ewe-Classes.zip library in the classes subdirectory.

Setting up your Compiler

You must tell your compiler to look in the Ewe-Classes.zip file when it is compiling your Ewe applications. With Sun’s JDK you would include <ewe_directory>/classes/Ewe-Classes.zip in the –classpath option for the javac compiler. e.g.

javac -classpath c:/ewe/classes/Ewe-Classes.zip MyClass.java

With the Jikes compiler you must do the same:

jikes -classpath c:/ewe/classes/Ewe-Classes.zip MyClass.java

Testing the Compiler

Within the classes directory of the SDK there is a tests subdirectory with a HelloWorld.java file. Try to compile this using the command line or your IDE.

Running your Programs

To do this you can use the Ewe VM like this:

ewe mypackage.MyClass

In order for this to work you will have to have the Ewe VM directory in the standard command path, otherwise you will have to specify the full path to the VM.

If you want to use a Java VM to run your Ewe program, then use the following command line:

(Windows version) java -cp ewe.jar;./ Ewe mypackage.MyClass

(Unix version) java -cp ewe.jar:./ Ewe mypackage.MyClass

Command Line Options

There are a number of command line options that you can use when running Ewe programs. These are generally used to see how your application will work on different mobile systems. The switches include:

/w <screen_width_in_pixels> = Limit the screen width.

/h <screen_height_in_pixels> = Limit the screen height.

/r = Simulate a mobile device.

/p = Simulate a pen-based device (e.g. a PDA).

/z = Simulate a monochrome (black & white) system.

/n = Simulate a system that does not support multiple native windows.

/m = Simulate a low memory device.

/o = Rotate the screen by 90 degrees clockwise.

/O = Rotate the screen by 90 degrees anti-clockwise.

/l <locale> = Set the default Locale.

/d <directory> = Specify a specific “program directory”.

/cp <directories> = Specify a ClassPath.

/- = Force the end of VM arguments, all following arguments to be passed to the application.

The format for the command line is:

ewe [vm_options] [run_class] [ewe_files] [/-] [application_arguments]

Examples:

ewe /w 240 /h 320 ewe.ui.Welcome
or
ewe /o ewesoft.gaming.jigsaw.JigsawPuzzle EwesoftGames.ewe

ewe /p eweDemo.ewe

While interpreting the arguments, should the VM come across a .ewe file before the runtime class name has been specified (as in the third example above) then it will search that .ewe file looking for a command line stored within it. If found then that command line will provide the starting class.

The /- option is only necessary if the first application_argument happens to be a file with a .ewe extension. Without the /- the VM will interpret that application_argument as being a .ewe file which contains application classes and not as an argument for the application. For example the command line:

ewe ewesoft.apps.HexView EweConfig.ewe

The EweConfig.ewe file is meant to be viewed by the HexView application, but the VM interprets EweConfig.ewe as a .ewe library containing application classes. The HexView application then receives no program arguments. In this case we will have to use /- as follows:

ewe ewesoft.apps.HexView /- EweConfig.ewe

Now the VM sees the /- and then passes all following arguments to the application.