By (and Copyright 2004) Dr. Jeffrey R. Fox (JeffreyRFox@msn.com)
Date: June 9, 2004
I have been bragging to the owner of a Toshiba e740 Pocket PC that I could set up both a Java run-time (JVM) and a usable Java compiler on his system given the time, and the opportunity. This was accepted as a serious offer, and this is the report of my travails.
First let me explain that my braggin’ was based on my experience over two and a half years of work with the Sharp Zaurus 5000D, a Linux based handheld which from the hardware perspective is not far from the norm for ARM based Pocket PCs and the e740 – the only real difference is that part of the case slides out to reveal a small RIM-like keyboard. My thumbs know this keyboard well, and I have written many C++, Java, and Forth programs, as well as innumerable “bash” shell scripts with it.
The software situation on the two handhelds appears very similar on the surface – a GUI with PIM applications and a “document only” viewpoint that does not support user programming or even simple scripting beyond what the spreadsheet application will do. Fortunately, on the Zaurus this is only a veneer over a real, though minimalist, Linux/GNU system, and a “console” application allows one to see a tiny terminal with the Bash shell running. Beyond that is a built-in version of the Insignia Jeode Java VM, a thing functionally equivalent to Sun’s ancient JRE 1.1 runtime. It is possible with this VM to compile java source using the Kopi or Sun’s Javac (1.1) java based compilers on-board the palmtop, or IBM’s open-source Jikes, a Java compiler written in C++, has also been ported over to the Zaurus platform. Using these tools, I have been able to program and test applets, normal AWT and simple Swing applications, servlets, and even do MIDP programming using Java based phone emulators. There are limits – language and library support beyond Java 1.1 requires plenty of research, and servers supporting JSP or enterprise technologies are often starved for run-time memory or other resources – so you can’t do everything Java, but there is enough depth to keep one busy forever. I maintain an ‘on-board program development’ tool support site for the Zaurus at http://foxfrenchtranslations.com/HostedWebSites.htm.
Since I knew that a DOS-like console program was available for Windows CE devices, and that the Insignia Jeode system was available ‘on the CD’ for many of the IPAQ systems and commercially available at low price, and that Sun had developed its own Personal Java Profile system for CE, I should not have too much trouble with coming up with some combination of tools that would compile and run Java. And since the Toshiba was a loaner, I wanted to do it with “free, as in beer” or trial, software.
Well ok, I did succeed to a certain extent and I am going to tell all. But first I think it is necessary to say that writing code with the tip of a plastic stylus is the pits – the little Zaurus keyboard is not lovely until you are without it. And Java is not the language of choice if every letter and digit is in pain – it is a wordy and redundant language free of macros, short-cuts and every other typing convenience. But this article is not directly about the merits of the different hardware platforms, the intrinsic value of Java as a programming language, or of the act of “on-board program development” verses the cross-compiling and emulation systems freely available for these systems. I want to be able to noodle around with the programming language(s) of my choice under the shade of a tree in the park of my choice without any support or reference not available on my handheld, and this report is in aid of others of like mind. I also think that cross-compiling to embedded systems often leads to a failure to properly test and debug embedded applications.
And before I launch into the complicated world of Java, let me say that if you just want to learn, or do, some simple programming on the PPC platform, there are plenty of possibilities. One that is often overlooked is Jscript, the version of the javascript language that is built into Internet Exploder. Javascript and Jscript are not Java in any way – they are Basic-like languages that work within the confines of internet browser web pages. All you have to do is get a text or html editor on-board, and then you can program – here is a sample (jscript.html) that will run in an IE window when you click on its file icon. (There is always an outer coating of HTML around a javascript program – that coating is here everything except the two lines starting with ‘var’, and the result is a web page that knows the date and prints it.
<HTML>
<HEAD><TITLE>Our First Script</TITLE></HEAD>
<BODY><CENTER><H1>Our FIRST working Script</H1></CENTER>
<P>Today is
<SCRIPT Language="JavaScript">
<!-- hide from old browsers
var today = new Date()
document.write(today)
//--></SCRIPT>
</P></BODY></HTML>
You can get jscript documentation on line in html format and read it on your handheld. The ‘visual basic’ scripting language vbscript is also supported by IE, so there are at least two “free” and easy to use languages already on-board.
For C and C++ programmers, there is the Pocket GCC, which is an onboard gcc tool suite utilizing the Pocket Console technology discussed below. A commercial C programming system (mini-IDE), PocketC is available, as well as a freeware subset C compiler with editor based on the Linux standard editor Vi. And there are also versions of Python, Perl, Smalltalk, etc. (see http://www.cegadgets.com/cedevtools.htm).
Traditional compiler technology is command line based, with modern incarnations employing an IDE (Integrated Development Environment) to orchestrate the myriad options, files, libraries and other parameters involved in editing, compiling and building an executable. Some simplified IDEs are available on the handheld platforms and one of apparent interest in the present discussion is jCompiler for PocketPCby KLAWA (available from Handango, trial not available). This $20 product must be coupled with a JVM to work, and the default choice is the Insignia Jeode JVM, now marketed (and perhaps upgraded) by Esmertec (also available at Handango, $50); the developer of jCompiler states his commitment to integrating other JVMs. I did not further investigate this product; it is not clear from the description that an editor is included. I did not find any freeware IDEs that might be used for the project.
This leaves us with the problem of assembling compatible components, with the most important being the JVM and the compiler. I was unable to find a version of IBM’s Jikes java compiler for the PPC platform. If such a thing existed, it would be the technology of choice for the transformation of java source into bytecode (‘class’) files; but would require some reengineering of the original C++ code to comply with the demands of one of the console shell tools discussed below. The other choices known to me are written in java and thus require a JVM to execute. The choices known to me are the familiar Javac from Sun’s JDKs, and Kopi, an open-source offering from Decision Management Systems (DMS). While Javac is the gold standard for Java compiling, it is embedded in the JDK classes.zip file, and its use on a handheld is complicated by the fact that it uses deprecated java classes (in JDK 1.1) that modern JVMs may not support, must be compressed and repacked to reach a usable size, and cannot be distributed by third parties due to licensing issues. I won’t describe what is involved making Javac work any further here; if you are really interested read the java related descriptions on my tools web site. My final choice for compiler technology was the Kopi compiler, version 1.5. This open-source compiler is available from DMS, or from my tools site, and should work with any JVM supporting Personal Java or the newer Personal Profile.
I looked with some care at three Pocket PC JVMs: one from Sun, the J9/Personal Profile JVM from IBM, and a port of the Kaffe clean-room open-source JVM.
The Sun JVM, which I downloaded from java.sun.com several years ago, is no longer available from Sun, and development appears to have stopped. It can still be downloaded from the net (http://cs.nmu.edu/~SeniorProjects/ikruhak/programs/pjavawince-1_1-beta1-arm.zip), but is probably ‘abandonware’ at this point. This is a shame because it is very close to usable in its present state, and I was able to run a number of different types of applications and applets with it. The problems are that it will not interact with any known console program, the documentation is outdated and incorrect for the PPC2002 case, and the error stream can not be captured, so debugging of any problem is near impossible. I will refer to the methods I used to get it running in an appendix.
The Kaffe JVM is also not ideal from the point of view of console I/O – it writes files to the root directory when it has output of this type, but that can’t work for many interactive console-oriented java programs. I am not sure it is really working; it crashed hard on a simple computational program. I ran out of time before I could really test this open-source offering. It forms part of software suite that may greatly appeal to programmers familiar with Linux tools and includes gcc, perl, a simple console shell, and a number of compatible command line tools, some quite exotic. Kaffe is distributed with the 1.4 version of the Kopi compiler; the implication is that this combination will work as a compiler.
So that leaves us with IBM’s Websphere Micro Environment, a commercial but low cost JVM which can be configured in a number of different ways. The essential files are distributed as part of the Websphere Studio Device Developer (WSDD) product, a comprehensive IDE for Windows that provides java device emulation and cross-compilation plus device run-time support. You can obtain a license to use the JVM on a PPC from Handango for $6 per device, but you must obtain the files from a 30 trial download (or the $600 product) of the WSDD. The IBM JVM is known in the industry and internally by the name “j9” and that is how I will refer to it here. To install j9, copy the following files from the wsdd5.0 directory, after installing on your ‘big’ computer, to form the indicated directory structure on your PPC:
\WSDD\bin (from wsdd5.0\ive-2.1\runtimes\pocketpc\arm\ive\bin)
swt-win32-3009.dll
j9foun21.dll
j9vrb21.dll
j9hook21.dll
j9gc21.dll
j9zlib21.dll
j9w.exe
j9vm21.dll
j9thr21.dll
j9prt21.dll
j9dyn21.dll
j9.exe
iverel21.dll
\WSDD\lib\jclFoundation (from wsdd5.0\ive-2.1\runtimes\common\ive\lib\jclFoundation)
classes.zip
ivemsp.jar
rmip.jar
profile.jar
\WSDD\lib\jclPpro (from wsdd5.0\ive-2.1\runtimes\pocketpc\common\ive\lib\jclPpro)
ppro-ui-win.zip
\WSDD\lib\security (from wsdd5.0\ive-2.1\runtimes\common\ive\lib\security)
java.policy
java.security
For the Kopi java compiler, you can get the single file kjc-suite.jar from my Zaurus tools website, or elsewhere. I supply, and test on, version 1.5 of Kopi, and I have not tested newer versions with the following scripts. Transfer the kjc-suite.jar file to your handheld somewhere, say “\Storage Card2\java\kjc-suite.jar”.
Now we need a command console to execute the JVM. The bad news is that Microsoft does not supply or support the DOS-like command console program on the Pocket PC 2002 (PPC’02) operating system to my knowledge (see the discussion at SymbolicTools). The void has been filled by several freeware offerings, but the result of Microsoft’s choice has apparently led to a fracturing of the development of command line tools for the Pocket PC platforms. Support from Microsoft returns in Pocket PC 2003 (look for it in the Windows Mobile Developer PowerToys) but is not backwards compatible by my test (and confirmed by omission in Microsoft’s documentation). There are several third party alternatives, but I boiled down the choice quickly to a combination of the original CMD.exe shell from Microsoft, together with a replacement dynamic link library, console.dll, from Symbolic tools. To install, download PocketConsole, and the version of CMD.exe that works with it. They both install through the ActiveSync agent.
CMD can be immediately tested – execution of CMD.exe should reveal the console window. Help for the command syntax is only available through the “help”, “help cmd”, and the specific “help <command>” at the command prompt. Unrecalcitrant DOS programmers will feel right at home, but beware: the presence of spaces within the path names of many standard directories is a hazard requiring surrounding double quotes, and the PPC2002 does not keep track of a “current directory” so that most references to files will require a full path name.
CMD.exe supports “batch” script files and that is what I used to get the J9 java system working. You need a text editor – you could use PC Word for that but it does not allow you to name files with a “.bat” ending, something we will want. While file renaming, creation and minor editing can be done with the CMD console, this is tedious and requires knowledge of I/O redirection. A replacement “file explorer” that I found useful for moving files around was the freeware version of Abisoft’s CE-FileCommander, which shows all the files (with types), unlike the brain-dead File Explorer; it does not rename files or file types however. For a text editor I used Tillanosoft’s freeware PocketNotpad, which suffers from the standard inability to open files outside the “My Documents” hierarchy but does allow you to name files with the needed extensions like “.java”, “.bat”, etc.
Since compiled java code is often packed into compressed “.jar” and “.zip” files, it is often useful to have a utility that can manipulate this type of file. CnetX’s ezyUnZip is a very polished freeware offering. Lastly it was useful to make registry entry changes on-board. This is black magic for most PPC users, but sometimes necessary. A very useful utility for this is the freeware PHM Registry Editor. (See the author’s registry tweaks database here, for some neat, and sometimes dangerous, PPC tricks.)
So, with these tools in place, we can write, compile, and run java applications. Firstly let’s look at running a sanity check on the j9 JVM. With the text editor, write a file “\My Documents\bat\j9help.bat” containing
set JAVA="\WSDD\bin\j9.exe"
%JAVA% "-jcl:foun" "-help"
To do this with the Tillanosoft notepad, you need to do a “save as…” and specify both the file type (“All Files (*.*)), and the full filename each time you save an edited file, or it will revert to a “.txt” file type. (We need an editor with a more flexible file dialog box.) The first line of the script defines an environmental variable called JAVA and points to the full path to the j9 executable. The second line executes j9 – it resolves to
"\WSDD\bin\j9.exe" "-jcl:foun" "-help"
The “-jcl:foun” flag indicates where j9 should find its primary class libraries (classes.zip, et. al.). Executing, from the console:
"\My Documents\bat\j9help.bat"
This should bring up the j9 console and print the message:
Licensed Materials - Property of IBM
J9 - VM for the Java(TM) platform, Version 2.1
(c) Copyright IBM Corp. 1991, 2003 All Rights Reserved
Target: 20031212b (Windows CE 3.0 build 11171 arm)
IBM is a registered trademark of IBM Corp.
Java and all Java-based marks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc.
Usage: \WSDD\bin\j9.exe [options] classname [args...]
Usage: \WSDD\bin\j9.exe [options] -jxe:<jxeFile> [args...]
[options]
-classpath <path>
-cp <path> set classpath to <path>.
-jxe:<jxeFile> run the named jxe file.
-D<prop>=<val> set the value of a system property.
-debug:<options> enable debug, JDWP standard <options>.
-jcl:<config>[:options]
specify which JCL DLL to use (e.g. cdc, cldc, ...).
-verbose[:class,gc,stack,sizes]
enable verbose output (default=class).
-verify enable class file verification.
-X print help on non-standard options.
Hopefully you got that – if you did not, and do not understand an error message, adding the flag “-verbose” to the final line may help. All these double quotes are not really necessary in these first simple scripts, but will be necessary whenever there are spaces in path names or file names. When a java program ends, or j9 output ends, it adds “(finished)” to the title bar. Always close this window with the File->Close menu. Always return to the command prompt via the Home application Running tab through activation rather than the Start Menu bar, since this preserves your command history, and that can save you a lot of typing (poking?).
Now that we have seen how a batch file runs, let’s write the classical HelloWorld java program to show the whole compilation cycle. First we create the simplest source file (\My Documents\test\Ex1.java):
// example #1
class Ex1
{ public static void main(String a[])
{
System.out.println("Hello, Dogface!");
}
}
Create a new batch file (“\My Documents\bat\kopi.bat”) containing
set JAVA="\WSDD\bin\j9.exe"
set KOPI="\Storage Card2\java\kjc-suite.jar"
set CPATH="-C\WSDD\lib\jclFoundation\classes.zip;\WSDD\lib\jclMax\ppro-ui-win.zip;%1"
set JAVAC=%JAVA% "-jcl:foun" "-cp" %KOPI% "at.dms.kjc.Main"
%JAVAC% %CPATH% "%2"
The second line points to the path of the Kopi compiler. The third line specifies the libraries and directories (containing class files) we will compile against (i.e. resolve symbols seen in our source using these resources) – note that one of these is a variable argument (“%1”) we will be specifying in the command line. The “ppro-ui-win.zip” is a class file containing the AWT library and many of the JDK 1.1 graphics related classes for the benefit of Kopi. The fourth line is just a typing aid, but specifies “at.dms.kjc.Main” the entry point of the compiler that we must use for this operation (the kjc-suite can do other interesting things). The fifth line executes, compiling the file we specify as “%2”, the second argument.
Unfortunately, Kopi can’t handle spaces within pathnames, so both the CPATH variable above, and the file specification must be free of spaces. The easiest thing to do is create a directory “\test” and copy Ex1.java to it. Then we can try to compile via:
"\My Documents\bat\kopi.bat" \test \test\Ex1.java
Note that we don’t have double quotes here around the arguments because they are already in the batch file. When this is executed, the j9 console comes up, but if there are no compile errors it just seems to pause and then appends “(finished)” to the title line. Kopi writes the compiled “.class” file(s) to the root directory, so when you get a clean compile, you will find the result as “\Ex1.class”. Now we can finally run (and debug) our first program.
Let’s create a general purpose execution batch file “\My Documents\bat\java.bat” to run java programs:
set JAVA="\WSDD\bin\j9.exe"
set BOOTP="-Xbootclasspath/a:\WSDD\lib\jclMax\ppro-ui-win.zip"
%JAVA% "-jcl:foun" %BOOTP% "-cp" "%1" "%2"
The second line defines BOOTP to point to the class library that defines the AWT and other higher-level java libraries, this time for the benefit of the JVM. The “%1” and “%2” in this script refer to arguments that we will specify when we execute this batch file – “%1” is the path to the “.class” file(s), “%2” is the name of the class containing a ‘main’ method to start execution. To use this batch file to execute the “\Ex1.class” file, we would use the CMD syntax:
"\My Documents\bat\java.bat" \ Ex1
The two arguments are, here, “\” and “Ex1”. Successful execution should yield a “Hello, Dogface!” message on the j9 console. Remember to use File->Close to exit j9.
If you have gotten this far, congratulations. That was a long haul just for the love of java. It is time for the last hurdle and that is to compile and run an applet, testing that we have a working AWT graphics library along the way. The batch file for applet execution is going to be pretty strange, and involves a lot of fiddling on my part, and there is virtually no documentation that I can find. But here it is – make a file (“\My Documents\bat\applet.bat”) containing:
set JAVA="\WSDD\bin\j9.exe"
set BOOTP="-Xbootclasspath/a:\WSDD\lib\jclMax\ppro-ui-win.zip"
set AVIEW="com.ibm.oti.appletviewer.AppletViewer"
set CPATH=\WSDD\lib\ext
set JHOME="-Djava.home=\WSDD"
%JAVA% %JHOME% "-jcl:foun" %BOOTP% "-cp" %CPATH% %AVIEW% file:///WSDD/lib/ext/%1
The AVIEW variable is the name of the appletviewer class within the j9 class library. The CPATH variable points to a directory, which you must create, that is special to the java security policy (and could be changed, presumably by changing the line that references “...\lib\ext” in the file “\WSDD\lib\security\java.policy”). This is the only place where you can put the class and html files for an applet and get them to execute without messing with the security apparatus. The JHOME variable allows j9 to find an absolute path to itself, and to its security policies. And finally, the “file://….” is a real live URL with the slashes going the other way and everything, and this must point to the html file.
Let’s get an applet to test this out. Here is a trivial one:
// Applet1.java
import java.awt.*;
import java.applet.*;
public class Applet1 extends Applet {
public void init() {
add(new Label("AWT Components"));
add(new Button("Push hard!"));
add(new Button("Bigger Bigger Button"));
add(new Checkbox("delete present life"));
add(new TextField(20));
add(new Label("Check 'Enter' and ^J, ^M"));
add(new TextArea(4, 10));
}
}
Compiling we know how to do:
"\My Documents\bat\kopi.bat" \WSDD\lib\ext \WSDD\lib\ext\Applet1.java
Move the resulting “\Applet1.class” file to the “\WSDD\lib\ext” directory. For each applet, we also need an HTML file to launch it. Create this file (“\My Documents\Personal\Applet1.html”):
<HTML><HEAD>
<TITLE>Applet1</TITLE>
</HEAD>
<BODY>
This is what you see if you use IE -- but it is really an applet.
<APPLET CODE="Applet1.class" WIDTH=240 HEIGHT=150>
</APPLET></BODY></HTML>
Copy the Applet1.html file to the “\WSDD\lib\ext” directory. Execute the applet with the console command:
"\My Documents\bat\applet.bat" Applet1.html
Hopefully you have an applet running at this point. Note that pressing Enter in the text area has no effect, while ctrl-J and ctrl-M produce a new line. Also note the action of the tab and shift-tab keys. And note the window size is always the screen size, despite what was specified in the html file.
It is now time to dip in to some other PPC secrets so that we can save some keystrokes and make some of this less tedious to input. Let’s first correct an install error in CMD that prevents us from clicking on a “.bat” file in File Explorer to execute. Of course, this will work only when the batch file does not take arguments, but when we are working on a project, it might save time to have a compile or execute batch file just for the project, so that we could click our way through some of the steps rather than picktype our way with the command console.
This is where we put the registry editor (PMH Registry Editor) to work. If you execute that and navigate through the top pane hierarchy to “My Device” -> HKEY_CLASSES_ROOT -> batchfiles -> Shell -> Open -> Command and select the entry “Default” in the bottom pane, you will be able to see the command line that the PPC uses when you click on a batch file. The Value data should be changed from {\Windows\cmd.exe /c %1} to {\Windows\cmd.exe /c “%1”} so that you can have spaces in the path to your batch file, which will be substituted into %1 when you click.
You can see that there are lots of things you might do if you know how this works. In the upper pane at “My Device” -> HKEY_CLASSES_ROOT -> .bat is the association between “.bat” and the batchfiles entry. You should now be able to simply click on the “\My Documents\bat\j9help.bat” entry in File Explorer to execute it.
There is also a more powerful way to execute the kinds of command lines with which we have been working. PPC supports “short-cuts”; these are simply text files containing a command line in a special format. For example, if you create a file (“\My Documents\bat\runj9help.lnk) with the text editor containing the sole line:
26#"\WSDD\bin\j9.exe" "-help"
You will get an entry displaying the j9 icon. Clicking will again run j9 with the “-help” option. The syntax of the line is that the prefix digits are the number of characters in the command line after the “#” separator; you must enclose each and every argument in double quotes and leave an interleaving space. You can construct executable icons like this for all sorts of complicated command lines, and that may save you much picktyping effort.
This does not solve the problem of java as one of the most verbose languages ever created. While one may go far by incrementally improving a program from a bare and simple start, getting a start that includes the GUI and event support one needs to implement a simple window and a few buttons will take some real work. If you are a rank beginner, you may consider using a ‘java interpreter’ rather than go through all the fuss of using the compile, edit, test cycle we have been outlining here.
For example, get the BeanShell interpreter (get bsh-2.0b1.jar from BeanShell.org) and for documentation get the BeanShell manual (and this one too). A batch file (“\My Documents\bat\bsh.bat”) should do the trick if it contains:
set JAVA="\WSDD\bin\j9.exe"
set BOOTP="-Xbootclasspath/a:\WSDD\lib\jclMax\ppro-ui-win.zip"
%JAVA% "-jcl:foun" %BOOTP% "-cp" "\Storage Card2\java\bsh-2.0b1.jar" "bsh.Interpreter"
Of course, replace “\Storage Card2\java\bsh-2.0b1.jar” with the path to wherever you put the jar file. Then you can click on the batch file and the BeanShell interpreter should start running in the j9 console window. Now you get to use the input line. Try:
print(Math.sin(0.7));
or
print(“Hello, Sucker!”);
to test (note ending semicolon). Stop BeanShell with “exit();”. BeanShell should take just about any Java 1.1 construct and can interpret script files too. This starts to make programming on the PPC more close to fun.
For documentation on Java, get the html version of Thinking in Java to read on-board. Buy the book to get the ancient AWT section on the CD, or maybe download the oldest version. Or consult paper books of quality. The Websphere Micro Environment is not well documented and what documentation exists is sadly in need of editing and proofing. But one can hope that improves with yet more age. If you pay your $6 they may notice that there is a market.
I mentioned that one might find, for download (albeit surely a license violation on the part of the poster), Sun’s abandoned personal java implementation for Window CE. And, as stated above, it appears to me to work - if you know how. It is packaged as pjavawince-1_1-beta1-arm.zip (versions for other processors where available once, the readme file indicates). There is no apparent console mode, and thus any real debugging and simple console style programming is impossible. To use it, read the README_BIN.txt file enclosed in the zip file, but every time the documented syntax does not work you will need to put more double quotes around arguments. For example, while we can’t usefully run any java that writes to System.out or reads from System.in, we can run applets:
"\Program Files\java\bin\pjava.exe" –classpath "\WSDD\lib\ext" –file "\WSDD\lib\ext\Applet1.html"