Eve Application Development

Michael L Brereton - 30 December 2007, http://www.ewesoft.com/

 

Beginners Guide - Contents

<< Previous: Starting Your Application

>> Next: Laying Out Controls

Using EveMaker

Eve Application Development

Using EveMaker

Creating a .eve File

Creating Executable Targets

Advanced Executable Targets

Developer Tools

Advanced Command Line Options

Edit Install File

 

 

The EveMaker application is written entirely in Eve and is located in the /programs subdirectory of the Eve SDK. Because it is very processing and I/O intensive it will perform significantly better when run using Sun’s Java VM. The RunEveMaker.bat file in the /programs directory can be used to run it with an installed Java VM (you may have to edit the bat file to correctly identify the path of the Java VM). The batch file has the single line:

 

         java -cp ../classes/eve.jar Eve EveMaker.eve

 

The purpose of the EveMaker application is to:

 

1.      Package the classes and resources needed by an application into a .eve file – the normal method of distributing Eve applications in a completely platform independent way. Not only can you specify the starting class but you can also specify a full set of command line arguments for the application.

2.      Produce a native executable file that contains all your programs classes and resources. This effectively combines your application with a stub VM executable to produce a single executable file. For all Windows and Windows Mobile targets, you can additionally specify a Windows icon to be assigned to the executable. Linux executables are not assigned icons.

3.      Provide a number of developer utilities including:

o       Producing a Windows icon from individual images.

o       Extracting individual images from a Windows icon.

o       Producing a PNG image with transparent areas from an individual image.

o       (Advanced)  Producing Eve Native Interface code from native methods in a compiled Java class.

o       (Advanced) Attaching the entire Eve library to a VM executable that was produced by building the VM from source.

 

Creating a .eve File

Here is what the EveMaker application looks like when run.

 

 

The icons at the top are used to switch between the various functions EveMaker (similar to a Tabbed panel). The first tab, as displayed, is used to specify the classes and other files that will make up the application.

 

The Program Name is used as the base name for executables produced, so you should not have any spaces or other characters not allowed on the destination file system. The Starting Class is the class that is used to start the application.

 

The Edit Command Line button is used to edit more advanced command line options (detailed here) and the Single Class File button is a convenience function that lets you select a single class through a file chooser box and EveMaker will then fill out the rest of the information based on that class (you will always have a chance to edit the information afterwards).

 

The Program Directories/Files Entries is where you specify the classes and other files that make up your application. The files specified here are placed in the output .eve file (and executable files if chosen) and will be available to the application at run time.

 

NOTE: File names in .eve files are case sensitive. An application that works when run from individual classes and individual files on an Windows system may stop working when placed in a .eve file because the Windows file system is not case sensitive (the Linux file system is). This will be the most common problem you will have when packaging your application.

 

You use the  button to add a new entry into the list. Each entry specifies:

1.      A Source Path – a directory that holds files for the application.

2.      A File/Mask value – which is a semi-colon separated list of file masks. All files in the directory that match those masks will be placed in the .eve file.

3.      A Path in Eve value – which specifies the virtual directory within the .eve file assigned to those files.

4.      An Include Subdirectories flag – which specifies whether the File/Mask should be applied to the subdirectories of the Source Path as well as the directory itself.

 

You can use the Preview Files button to see what files will be included and what they will be named in the .eve file. Here is what the included files look like for the example above:

 

 

The Eve File Options is where you specify the name of the final output .eve file and other options:

 

1.      Add Command Line – specifies that a command line should be added to the .eve file. This is almost always the case unless you are creating an .eve file that is meant to be a library (a collection of classes for use by other applications).

2.      Use String Pool – a special option that reduces the size of the final .eve file by pooling all the Strings in the .eve file into a single pool instead of individual String pools in each class (the default).

3.      Create Zip File Also – this specifies that a .zip file containing the exact same files as the .eve file should also be created. This can be useful for tracking deployment problems.

4.      Add Install File – this is used by various target platforms to install the application. Currently the following platforms use this file:

o       the Eve VM Launcher uses the Icon specified in the install file to display the link to the application.

o       Qtopia Based devices use all the information to determine how to place the application within the application tabs.

 

The Edit Install File is used to specify the information placed in this file, and this is detailed here.

 

The final section on this screen contains the Create Eve File button which is used to place all the specified files into the output .eve file. The Show Files button will show in a tree structure all the files that will be placed in the .eve file. The Run Eve File button will use the Eve VM to run the created .eve file. You should always use this to test your application before attempting to create executable targets. The Check Dependencies button is used to make sure that there are no classes that are referred to from within the .eve file but which are not present in the final file.

 

Make sure that you save your project information with the File->Save menu option. The project is saved as a .enf file at whatever location you choose.

Creating Executable Targets

You should only attempt this once you have confirmed that you can create a working .eve file that is correct and contains all the resources needed by your application. The screen shot below shows the EveMaker tab that is used to create executable targets.

 

 

Here are some important things to note about the executable targets.

 

o       On Windows or Linux desktop systems, the executable produced contains the native VM, the Eve class library and your application classes and resources. No other executables or shared libraries are necessary and the Eve VM does not need to be installed on the computer that will be running the application.

o       On Windows Mobile systems (and soon for Linux mobile systems), the standard Eve VM is a small launcher (eve.exe) and a dynamic linked library (eve.dll) which contains the actual VM. Mobile targets created by EveMaker (like PocketPC or Smartphone) do not contain the Eve library or the VM. Mobile targets contain only your application combined with a simple launcher that will load the eve.dll library at runtime. They are therefore much smaller executables but they require that either the VM be installed on the target device or that you distribute the eve.dll along with the created target. As long as the eve.dll is in the same location as your created target at runtime it will successfully find and load the dll.

o       The Jar target is a single .jar file containing your application, the Eve library and the command line and can therefore be executed directly using an installed Java 2 (or better) VM. The .jar file also contains the Java support libraries java_eve.dll and libjava_eve.so (for Linux desktops).

o       The Exe-Jar Launcher target is a special Windows executable that is similar to the standard Windows executable target but at runtime, if the program detects that Suns Java VM (version 2 or better) is installed on the system it will dynamically create a .jar file for your application and then run the application using the Java VM. If a Java VM is not found, the native Eve VM embedded in the executable will be used instead.

o       The Applet target is used to create a small HTML page containing an <APPLET> tag for your application. The application classes are placed in a .jar file while the resources (images and non-class files) are either placed in appropriate directories or are placed in a single _resources.zip file depending on the option chosen in Applet Options.

 

There are a few Target Options available.

 

o       Windows Program Icon: You use this to assign an icon to Windows and Windows Mobile based targets. You can use the default, use an existing icon or create your own from any number of individual images.

o       Which Eve classes to put in the target? You can choose to place the entire Eve library into the executable or you can choose to place only classes referenced by your application. The second option produces smaller executables but you must be sure that you do not reference essential classes through Class.forName() method calls, since these will not be included in the list of referenced classes.

o       Compress classes in the target? Normally classes are not compressed in the target (the .eve file is not compressed) but you can choose to compress (zip) them either for desktop targets or all targets. It is not normally recommended that you compress classes for mobile targets since extra time is taken to unzip the classes at runtime and extra memory is taken to hold the uncompressed class bytes.

o       Applet Options – Display: The Applet may be displayed completely embedded within the web page (in which case the application will not popup any extra frames at runtime) or it may be displayed in a single external frame or it may be displayed as a regular application, displaying as many frames as it needs. For the first two options you must supply the Width and Height for the Applet or Frame. The third option does not require width/height specifications since each displayed Form determines its own size.

o       Applet Options – Place Resources in Zip File: Normally non-class resources are placed in directories along with the HTML file and the web server will provide the resources individually as needed. However you can specify that all resources be placed in a separate zip file that will be named _resources.zip and which will be downloaded only once when the Applet is loaded. This has the advantage of only a single file access at runtime but will have the disadvantage of a longer start time while this is loaded.

o       Always Check Class Tree: This will do a class dependency check when generating targets to ensure that no classes required by the application are missing.

o       Place Classes in External Zip: This will produce the executable but the classes are placed in an external zip file called eve-classes.zip instead of being placed within the target itself. This is useful for troubleshooting your target if it is not working as expected.

o       Create Targets in Program Info Directory: If this is checked the targets are placed in the same directory as the .enf file that specifies the current project. Each target is placed in a directory named for the target (e.g. “Exe” or “Jar” or “Applet”) and the Program Name specified in the previous section is used as the name of the executable (or .jar or .html) itself. If this in unchecked the targets are created in the same directory as the output .eve file created in the previous section.

 

Once you have selected the targets and the options you want, press the Build Targets button to create the targets. Any errors will be reported in a dialog box. On success the various targets are placed in the destination folders and are immediately ready for running or distribution.

Advanced Executable Targets

This feature lets you build executable targets for your porgram with a higher degree of control than the previous screen. You specify options for each target individually instead of having options applied to all targets. Here is what this screen looks like:

 

 

For each entry you can specify an individual Executable Stub on your system that has been compiled and converted to a an appropriate stub – or you can choose one of the already available stubs supplied with the SDK. The one shown in the example is the Linux x86 command line version. You must also provide a unique Directory Name that will contain the created executable. The following options are applied to the target creation:

 

o       Always Append: There are two methods for attaching your application classes to executable stubs. The normal method for Windows executables involves inserting the application classes as standard Win32 resources. This allows for the inclusion of a program icon. The normal method for Linux executables is to append the classes to the end of the executable. This append method also works on Windows executables (but the resource method does not work on Linux executables) but the append method does not allow for the inclusion of a program icon. If you choose this Always Append option, then the application classes and resources will be appended to the executable even if it is a Windows executable.

o       Is Command Line Version: This option should be used if you know that the executable stub was a command line only build of the VM. This tells the system to use the command line only classes to build the target executable. All the eve.fx and eve.ui packages are not included.

o       Is Java Hybrid: This option is used to generate a Jar Launcher as described in the previous section. Note that this will only work on Windows desktop executables at this time.

o       External Resources: This option is used to indicate that the application classes and resources should be placed in an external file called eve-classes.zip. This is only useful for troubleshooting your application.

o       Zip Resources: This option indicates that the application classes and resources should be compressed when being placed in the target executable. This makes the executable smaller but will result in longer startup times and will use more memory.

o       Referenced Classes Only: This option indicates that only classes referenced by your application classes should be placed in the application instead of the entire Eve library.

The Build Target button will build all the targets specified. Any errors will be reported in a dialog box.

Developer Tools

There are a number of Developer Tools provided by EveMaker. These are described below:

 

o       Windows Icon Maker – This allows you to create a Windows Icon from a number of other standard images of various sizes. There must be at least one image within the icon but there is no upper limit on the number of images that can be in the icon. It is recommended that it contain images of sizes 16x16, 32x32 and 48x48 (and 12x12 and 64x64 if possible).

 

o       Windows Icon Extractor – This allows you to select an individual icon from a Windows Icon and then save that image as a single PNG image.

 

o       PNG Icon Maker – This allows you to create a PNG image with transparent areas from a BMP image or other image by selecting an individual color within the image to be transparent.

 

o       ENI DLL Maker – This allows you to generate C++ code necessary for creating ENI (Eve Native Interface) code to implement native Java methods in a class. The generated C++ code, when compiled, produces a DLL that is compatible with the Eve VM and with Sun’s Java VM. The generated code is also compatible with both Windows and Linux. The code produced is a simple skeleton and you must provide the functionality by implementing the provided functions using the Eve ENI specifications. This is explained in a separate programmers guide.

 

o       Eve VM Maker – This takes an Eve VM compiled from source code and produces a stub executable for use in producing application targets and it combines the compiled VM with the Eve library to produce a stand-alone Eve VM. Note that for Windows executables, you should include at least one resource in the executable (you can add an icon, for example). This resource is stripped out when making the stub. Note that if the VM you compile ends with “_stub” or “_stub.exe” it is assumed to already be a stub and no new stub will be created.

Advanced Command Line Options

Here is what the Advanced Command Line options looks like:

 

 

The Eve Files is used to specify extra .eve files which will be used as class libraries at run time. Extra Commands are placed after the start class and VM Options are placed before the start class. You can specify the Width and Height of the application (when simulating a mobile device with /p, /p5 or /p6 or /s, /s5 or /s6. You can also specify a default locale for the application using a two character locale specifier (e.g. us).

 

The example above will generate a final command line that looks like this:

 

/p5 /w 320 /h 240 evesamples.jigsaw.JigsawPuzzle “c:\My Pictures\GoodPicture.jpg”

 

Edit Install File

This is used to edit the data placed in the Install File which may optionally be placed in the .eve file. Here is an example:

 

 

o       Program Title specifies the name to be displayed with the Icon for the application when installed in the Eve VM launcher or on the Qtopia device.

 

o       Install Location specifies the location the .eve file will be placed on a Qtopia device.

 

o       Arguments and VM Options specify extra arguments and VM Options to be used with the application (these are not normally used).

 

o       Category specifies which Qtopia category the application should be placed in.

 

o       Program Icon specifies the name of a PNG icon within the .eve file that should be used to represent the application in the VM Launcher or on the Qtopia device.