Ewe
Application Development
17 March 2003
Michael L Brereton
Using the Jewel
Program Builder
Ewe File
Directories/Masks Entries
Step 2 – Creating
Additional Targets
Using the Jewel Program Builder
This chapter explains how to use the Jewel
program to create distributable Ewe applications. To do so, we will create a
distributable version of the Solitaire sample application.
As mentioned before creating a distributable
file requires two steps:
- Creating a portable .ewe file containing all the
application classes and resources. This Ewe file can then be executed on
any system with a Ewe VM installed.
- (Optionally) The Ewe file can then be
used to create any of a number of platform dependant executable files.
Jewel is used to accomplish both these
tasks.
First we will ensure that the Solitaire sample is installed correctly in your environment. Open an MSDOS window and cd into the classes subdirectory of your Ewe programming environment. Then run Solitaire by entering: ewe solitaire.Solitaire or jwe solitaire.Solitaire. Once you confirm that Solitaire is working, we can use Jewel to create our distributable files.
Step 1 – Creating a Ewe file
To do this we will run the Jewel program builder. This is located in the programs subdirectory of the Ewe SDK. If you are running a Windows system and have installed the Ewe VM, then you can just double-click the Jewel.ewe file and the application will begin running. Otherwise you may have to use the command line from within the programs directory using:
ewe Jewel.ewe
If you do not have
a native Ewe VM for your platform then you will have to run Jewel using your
Java VM. To do this you must download the ewe.jar archive from the
Ewesoft website or you can use a zip file utility to open JewelData.jar
and extract the ewe.jar archive from the resources directory within
Jewel.jar. Once you have it you can execute Jewel by entering:
java -cp ewe.jar Ewe Jewel.ewe
Once you do this
the Jewel main screen will appear.
Program Specs/Command Line
This section is used to set the name of the program (this is not the same as the name of the .ewe file – it is the name of any special targets that you may produce) and the starting class of the application. Enter the values “Solitaire” and “solitaire.Solitaire” as shown in the screen shot.
You can specify additional command line options using the Edit Command Line button, but we will not be dealing with this now. The command line information is added to the .ewe file that you will create as a special .run entry with the same name as the .ewe file. This is how the VM knows what the starting class will be when it executes the .ewe file.
Output File Specifications
The Output Ewe File is used to
specify the .ewe file that you will create. Enter a file name here or
use the 
button to select a file using a FileChooser
box. The other options for the output file are:
- Add Command Line – this is necessary
if the .ewe file is to be used as an application. If you are
creating a .ewe file to be used as a class library only, then you
can turn off this option.
- Use String Pool – This is a special
type of class compression that pools together all the Strings used in all
the classes that are going into the .ewe file. This can reduce the
size of your .ewe file to about 75% of what it would be without
this option.
- Add Install File – This is used to add a special install file to the .ewe file that is used by the VM on certain systems to allow the application to be natively installed in the OS. Currently this is used only by the Ewe VM on the Sharp Zaurus. The Edit Install File is used along with this option.
Ewe File Directories/Masks Entries
This is what you use to specify the files that are going into your .ewe file and what path they will have once in the .ewe file.
Each entry in this list specifies:
- A Source Directory that contains files that are going into the .ewe file.
You can enter the directory directly or select it using a FileChooser.
- A File/Mask that
specifies which files in the directory will go into the .ewe file.
This can be any standard file mask, such as *.class or S*.class, or it can be a full file name with no * characters at all. You can specify more than one mask by separating them with semi-colons (e.g *.class;*.png).
- A Path in Ewe
that specifies what path the files will have in the .ewe file.
This is very important – getting this value wrong will result in your application being unable to locate resources and classes in your .ewe file.
The Ewe VM requires the standard Java convention that classes within a package be placed in a directory named after that package. For example the solitaire.Solitiare class must be represented by a file named Solitaire.class stored in a directory called solitaire.
After you enter the source Directory for the entry, Jewel will make a list of likely paths that you would use within your .ewe file and place it in the drop down box associated with the Path input box. You would therefore most likely be able to select it easily from this box.
- An Include Subdirectories option that tells Jewel to include subdirectories of the specified directory in the .ewe file, using the same mask specification.
To add an entry into the list, press the 
button and then enter the information for the
entry. You can use the information from the screen shot above.
You can preview the files that each entry will place in the .ewe file by pressing the Preview Files button. This is very useful to ensure that the files are going in the correct place in the .ewe file.
Ewe File Creation
The Create Ewe File button is used to create the final .ewe file. The Show Files button will show all the files that are going into the final .ewe file. The Run Ewe File button will tell the VM to attempt to run the .ewe file using a separate instance of the Ewe VM.
Press the Create Ewe File button now to create Solitaire.ewe. You can then try running it from within Jewel or you can run it from the command line.
Saving Your Program Specs
Use the Save option from the File menu to save your program specifications as a .jnf file. Save this one as Solitaire.jnf in the programs directory.
Step 2 – Creating Additional Targets
Remember that a .ewe file is a fully portable file, able to be executed on any system with a Ewe VM or a Java Virtual machine along with the ewe.jar file. However you can also package your application in a number of different forms for execution on a number of different targets. These include:
Java Targets
- Java Jar Files – for both Java 1.2
VMs and for Java 1.1/PersonalJava VMs.
The jar files produced for these targets contain your application classes and resources and the Ewe libraries for Java. This means that these jar files are fully self-contained and do not require a VM to be present nor the ewe.jar archive.
- Java Applets – for both Java 1.2
and Java 1.1 VMs.
This produces a complete file list needed to deploy your application as a Web Applet. Again, it provides all the files required, including the Ewe libraries for Java.
- Microsoft Jexegen – for use with Microsoft’s Jexegen utility. This utility creates a Windows executable file from a Java application.
Windows CE Targets
Jewel can produce Windows .exe format files for execution on all Windows CE platforms and processors from WinCE 2.11 up to PocketPC. The .exe files produced do not contain the Ewe VM, only your application classes and resources. When they are run, they will invoke the Ewe VM on the target platform (by dynamic linking to the ewe.dll file). Therefore for these .exe files to work the Ewe VM must be installed on the target system.
Since these are Windows executable files they can contain their own Windows icon, and Jewel provides a way of specifying which icon should be assigned to the executable. In fact, Jewel allows you to build up a Windows icon (which contains any number of differently sized bitmaps) from any BMP or PNG images. This will be discussed later.
Windows Desktop Targets
There are two types of Windows Desktop executable files that you can create:
- Dynamic Linked – similar to the
Windows CE executables, in that they do not contain the Ewe VM, but rather
invoke the installed VM on the target computer when run.
- Static Linked – which contains the full version of the Ewe VM. This means that it is fully self-contained and will run on any Windows system, even without the Ewe VM installed. However you will have to include the ewex_registry.dll file when distributing the application.
All of these targets are produced in their own directory within a directory named after your program
name (i.e. a directory called Solitaire in our example). This directory will be placed in the same location as the .jnf file for your project.
Creating a Windows Icon
The Build Icon
button allows you to build a Windows Icon from any number of bitmaps and it
will bring up the Windows Icon Maker screen as shown below.
A Windows Icon
contains a number of differently sized bitmaps, usually containing at least a 16x16
and a 32x32 bitmap. The icon that is selected at any time depends on the
context in which it is displayed. Each
bitmap also has a mask associated with it that tells the system which
areas of the bitmap are to be considered transparent.
The Icon Maker
allows you to load up images from files (BMP or PNG) and then optionally select
a particular color to be made transparent (if a transparent area is not already
defined for the image). This means that you can use any simple editor (like
Paintbrush) to create a bitmap, fill up the transparent areas with a particular
color that is not used anywhere else in the bitmap, and then use the Icon Maker
to create a Windows icon from it.
Use this feature
now to create an Icon for our Solitaire example. In the programs
directory there are two bitmaps: solitaire_exe_icon.bmp and solitaire_exe_iconsmall.bmp.
Load them both into the Icon Maker and then click on the orange area for both.
Then save the Icon as Solitaire.ico in the programs directory.
When you close the Windows Icon Maker it will automatically select this new
icon as the Windows Icon for the Solitaire project.
Creating a Target
To create one of the targets simply check the ones you are interested in and press the Build Targets button. A progress dialog will appear during the creation process. Note that the Java targets take some time to create since it involves the unzipping and re-zipping of a large number of individual Java classes.
Once the targets are created a Solitaire subdirectory will appear in the same directory as the Solitaire.jnf file that you saved. Within this new subdirectory will be a subdirectory for each of the targets that you selected. These targets are ready for distribution or deployment.
Additional Tools
Jewel provides a number of other tools that are useful to the Ewe developer. These include:
- A PNG Icon Maker. This is similar to the Windows Icon
Maker. It takes any bitmap and lets you select a particular color to be
made transparent. You can then save the image as a PNG image and use
it in your Ewe applications.
- A Ewe Native Interface (ENI) Library Builder. This takes
a class that contains native Java methods and produces a template C++ file
that you can use to create dynamic linked libraries (both Windows and
Unix) that implement these native methods. Please note that this
implementation will also work for Sun's Java VM as well.
- A Resource Extractor. This allows you to extract selected Jewel resources and save them as files on your hard-drive.