Michael L Brereton - 30 December 2007, http://www.ewesoft.com/
<<
Previous: Starting Your Application
>>
Next: Laying Out Controls
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.
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.
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.
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.
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.
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”
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.