A Native-Code version of Hevea

Philip A. Viton

May 19, 2002

1 Introduction

This note announces the availability of an experimental Microsoft Windows native-code port of Hevea/Hacha/Esponja-1.06, one which does not require the Objective Caml bytecode virtual machine ocamlrun. I've wanted to try this for a long time, and when I finally got a-hold of the Microsoft Visual C++ package, I immediately went to work.

Warning: I have given this very limited testing --- actually, next to none --- so until people have more experience with it, this new port should be considered highly experimental. As noted below, I make it easy to run the new version side-by-side with the older (bytecode) version; and this is the way I think you should proceed. But if you're got a wild streak in you and want to throw caution to the winds, you can opt for the native-code version alone.

Why should you be interested in the native-code version? In a word --- speed. I tested the two versions on a fairly large (600K) .tex file, and this is what I found:

: Bytecode Hevea: 28 seconds
: Native-code Hevea: 6 seconds

Tested on a 500Mhz system running Windows NT4. Your mileage may differ; but it seems clear that there is a significant speed-up, enough to make Hevea usable for a real-time generator of HTML on a web site. On the other hand, the speed-up is presumably less visible on smaller source files, and also with faster computers --- these days 500Mhz is slow by a factor of 3 or 4 --- so you be the judge.

2 Obtaining Native-Code Hevea

I provide three ways you can get this (a copy of these notes in included in HTML format in the two new distributions):

For the utterly reckless: If you are already using the bytecode version, which must be Hevea version 1.06, you can simply replace hevea.exe and hacha.exe by the new native-code executables. (You can also delete ocamlrun.exe). This is the simplest method, but if something goes wrong with the new version, you're out of luck until you re-retrieve the bytecode executables.

You can get the new executables from here : heveaxA.zip
For the more cautious: The second way to try out the native-code version is to run it alongside the bytecode version, which we assume you have already set up as version 1.06. In this version, the executables are heveax.exe and hachax.exe, and I provide a new set of batch files, which differ from the ones you're now using only in that their names have an ``x'' appended to the name (so, for example, if you now use hhtml.bat to run the bytecode version of Hevea, you'd use hhtmlx.bat for the native-code version), and call heveax rather than hevea. This means that if something goes wrong, you can just run the ``other'' batch file.

You can get the native-code executables and supporting batch files from here: heveaxB.zip. The bytecode version of Hevea 1.06 is available here as winport.zip.

To install the new support:
- If you've not already installed the bytecode version 1.06, do that first. Instructions are included in the zip file, or may be read online here.
- Unzip the archive to the same directory where you have installed the bytecode version, typically c:\hevea.
- If you are using Scientific Word, Scientific WorkPlace, or Scientific Notebook then also unzip swpx.zip. Otherwise you can delete swpx.zip.
- If Hevea is installed to c:\hevea then move the new batch files to some folder in your path.
- If Hevea is installed to a folder (directory) other than c:\hevea you must first edit each of the new batch files and change the line set heveadir=c:\hevea to point to wherever Hevea is located. Then move them to some directory in your path.
If you're new to Hevea If you've not tried Hevea before, then you should first install the bytecode version (see winport.html for details and instructions); I then recommend that you install the ``cautious'' version of the native-code support; but of course you don't have to take my advice here.
The TeXConverter If you use Steve Mayer's excellent TeXConverter as a front end to Hevea, you should upgrade: Steve has very kindly written some code to accommodate the native-code version of Hevea. If your Hevea directory contains only hevea.exe (whichever version it actually is), then it will be used automatically. On the other hand, if the TeXConverter sees both hevea.exe and heveax.exe, you will see a radio button allowing you to select which you'd like to use (this will facilitate debugging, since if something goes wrong with the native-code version, you can immediately try the other).

The latest TeXConverter also allows you to run the new Esponja utility, as part of your Hevea run.

Here is a link to the TeXConverter website

3 Reporting Errors

I'm very interested to know if anyone has any problems with the native-code port, so please let me know if anything goes wrong. It would be most helpful if you would check that the bytecode version runs without error in cases where the native-code version fails; but if you've over-written the bytecode executables, send me the source file with a brief description of the problem.

4 Concluding Remarks

Remember, this native code version is explicitly tagged as highly experimental (at least until we get more experience with it).
Good luck!

This document was translated from L^AT_EX by H^EV^EA.