Installing and Launching Sheets

For these instructions, we assume you're running Microsoft Windows '95 or NT 4.0, and are using some version of Sun's JDK 1.1. If not, adjust instructions accordingly.

Installation

Sheets is a Java application (not an applet). To install it, first unpack the distribution file using your favorite ZIP tool. (We assume that you unpack it into C:\sheets. If not, interpret the installation instructions and adjust any hardwired links accordingly.)

After unpacking the distribution, you should edit sheets.bat to specify the locations of the relevant files and libraries. You will wish to add C:\sheets to your PATH variable so that you can execute sheets.bat. You should also make sure that your PATH includes your Java installation (i.e. jdk1.1.7\bin) and your CLASSPATH variable includes the standard Java class libraries (i.e. jdk1.1.7\lib\classes.zip).

Note for Windows95 users: because sheets.bat sets a number of different environment variables, you may find that you are getting "memory exhausted" messages. If so, you should adjust your "ms-dos prompt properties" so that "memory/initial environment" is higher. (It's probably easiest to simply set it to the maximum value of 4096.)

You will probably wish to create a prototype database file containing summaries of the standard Java libraries. The easiest method is to download prebuilt summaries for JDK1.1.7, JDK1.1.7 plus Swing1.1beta3, or JDK1.2beta4. You can then simply unpack the appropriate ZIP file in your sheets directory.

Execution

If you are running under Windows, you will typically execute Sheets from the cmd prompt.  The sheets.bat script which is located in the sheets home directory (i.e. c:\sheets) is the best way to run Sheets.  In day-to-day usage, you will simply need to type: 
    sheets [database.sdb]
You may explicitly specify a database, or you may accept the default, which is sheets.sdb. (The extension "sdb" stands for Sheets data base.)

If you are working under some other OS, you will (currently) have to build your own script to start Sheets.  Basically, this script should invoke the Java interpreter on the gwydion.sheets.Sheets class. If you are using the Sun or Symantec virtual machine, we recommend the following command line: 

    java  -mx64m -classpath %CLASSPATH% gwydion.sheets.Sheets ....
The -mx64m option sets the maximum heap size of the virtual machine to 64 megabytes; the default setting of 16 megabytes is far too small. (Note that this is the maximum heap size we're changing, so it's ok to specify this even if you are running on a machine without much memory) The -classpath option sets the classpath to the value of the CLASSPATH environment variable. In theory this is redundant, but in practice many Java compilers and virtual machines seem to ignore the CLASSPATH variable.

Customization

You can customize Sheets by creating a file named .sheetsrc. At startup time, Sheets will look for this file in the current directory, and then in your home directory -- which the VM may take from your HOME environment variable.  If not, or if you choose not to place a .sheetsrc there, Sheets will also look in the sheets home directory (i.e. C:\sheets).

In a .sheetsrc file, any line that begins with a pound sign (#) is considered a comment. .sheetsrc files are
case sensitive. Mainly what you do in .sheetsrc is bind commands to keys and set variables. Sheets variables are used both for system configuration such as file locations and for user preferences. Documentation on commands is here and variable documentation is here.

The distribution contains several "typical" sheetsrc files. default.sheetsrc is a nice neutral starting point, while nkramer.sheetsrc and rgs.sheetsrc represent the more idiosyncratic preferences of several Sheets developers. The former follows a minimilast Win32 style, while the latter reflects more of an Emacs flavor.

Which Java?

Sheets has been tested with a variety of Java implementations, and the results don't say much for Java's portability: All virtual machines are quite buggy, and no two VMs implement the same set of bugs. Sheets currently requires Java 1.1. We primarily use Sun's JDK1.1.7. There are known to be a few problems with JDK1.1.3 and Microsoft Java SDK 2.0, but both are usable.  The current version of Sheets does not work under the JDK1.2 betas.

For compilers, we prefer the Microsoft SDK3.1 compiler, JVC. It's many times faster than the other compilers we've tried. However, all compilers should be able to compile Sheets.