Installation instructions

This chapter explains how to install Caml Light on your machine.

The Unix version

Requirements:
Any machine that runs under one of the various flavors of the Unix operating system, and that has a flat, non-segmented, 32-bit or 64-bit address space. 4M of RAM, 2M of free disk space. The graphics library requires X11 release 4 or later.

Installation:
The Unix version is distributed in source format, as a compressed tar file named cl7unix.tar.Z. To extract, move to the directory where you want the source files to reside, transfer cl7unix.tar.Z to that directory, and execute
        zcat cl7unix.tar.Z | tar xBf -
This extracts the source files in the current directory. The file INSTALL contains complete instructions on how to configure, compile and install Caml Light. Read it and follow the instructions.

Troubleshooting:
See the file INSTALL.

The Macintosh version

Requirements:
Any Macintosh with at least 1M of RAM (2M is recommended), running System 6 or 7. About 850K of free space on the disk. The parts of the Caml Light system that support batch compilation currently require the Macintosh Programmer's Workshop (MPW) version 3.2. MPW is Apple's development environment, and it is distributed by APDA, Apple's Programmers and Developers Association. See the file READ ME in the distribution for APDA's address.

Installation:
Create the folder where the Caml Light files will reside. Double-click on the file cl7macbin.sea from the distribution. This displays a file dialog box. Open the folder where the Caml Light files will reside, and click on the Extract button. This will re-create all files from the distribution in the Caml Light folder.

To test the installation, double-click on the application Caml Light. The ``Caml Light output'' window should display something like

        >       Caml Light version 0.7

        #
In the ``Caml Light input'' window, enter 1+2;; and press the Return key. The ``Caml Light output'' window should display:
        >       Caml Light version 0.7

        #1+2;;
        - : int = 3
        #
Select ``Quit'' from the ``File'' menu to return to the Finder.

If you have MPW, you can install the batch compilation tools as follows. The tools and scripts from the tools folder must reside in a place where MPW will find them as commands. There are two ways to achieve this result: either copy the files in the tools folder to the Tools or the Scripts folder in your MPW folder; or keep the files in the tools folder and add the following line to your UserStartup file (assuming Caml Light resides in folder Caml Light on the disk named My HD):

        Set Commands "{Commands},My HD:Caml Light:tools:"
In either case, you now have to edit the camlc script, and replace the string
        Macintosh HD:Caml Light:lib:
(in the first line) with the actual pathname of the lib folder. For example, if you put Caml Light in folder Caml Light on the disk named My HD, the first line of camlc should read:
        Set stdlib "My HD:Caml Light:lib:"

Troubleshooting:

Here is one commonly encountered problem.

Cannot find file stream.zi
(Displayed in the ``Caml Light output'' window, with an alert box telling you that Caml Light has terminated abnormally.) This is an installation error. The folder named lib in the distribution must always be in the same folder as the Caml Light application. It's OK to move the application to another folder; but remember to move the lib directory to the same folder. (To return to the Finder, first select ``Quit'' from the ``File'' menu.)

The PC version

Requirements:
A PC equipped with a 80386, 80486 or Pentium processor, running MS-DOS version 3.3 or later. Older Intel processors (8086, 80286) are no longer supported. 2M of RAM. About 1.2M of free space on the disk. The graphics primitives require a VGA or SuperVGA video card.

Installation:
In the following, we assume that the distribution files resides in drive A:, and that the hard disk on which you are installing Caml Light is drive C:. If this is not the case, replace A: and C: by the appropriate drives.

Create a directory on the hard disk where Caml Light will reside. In the following, we assume that this directory is named C:\caml. If you choose a different directory, replace C:\caml in the following by the appropriate absolute path name. Then, execute the following commands:

        cd C:\caml
        A:pkunzip -d A:cl7pc
(Be careful not to omit the -d option to pkunzip.) This extracts all files in the C:\caml directory.

Select or create a directory where Caml Light will put its temporary files. Many machines already have a C:\tmp directory for that purpose. If it does not exist, create it.

For the remainder of the configuration process, you will have to determine two things:

Now, edit the C:\autoexec.bat file, in order to:

Then, save the autoexec.bat file and restart the machine. To test the installation, execute:
        camlc -v
The camlc command should print something like:
        The Caml Light system for the 80386 PC, version 0.7
          (standard library from C:\caml\lib)
        The Caml Light runtime system, version 0.7
        The Caml Light compiler, version 0.7
        The Caml Light linker, version 0.7
Then, execute:
        caml
The caml command should print something like:
        >       Caml Light version 0.7

        #
In response to the # prompt, type:
        quit();;
This should get you back to the DOS command interpreter.

Troubleshooting:
Here are some commonly encountered problems.

Cannot find the bytecode file or camlrun.exe: No such file
The installation has been performed incorrectly. Double-check the autoexec.bat file for errors in setting the PATH and CAMLLIB variables.

CPU must be a 386 to run this program
Self-explanatory. It's about time you buy a 386 PC or better.

CPU must be in REAL mode (not V86 mode) to run this program
Ah. That's a tricky one. A number of utility programs switch the 80386 processor to a particular mode, called ``Virtual 86'' or ``V86'' mode, that prevents 32-bit protected-mode applications like the 80386 PC version of Caml Light from starting. These programs include:

  • device drivers that provide memory management services
  • device drivers that provide enhanced debugging possibilities, such as tdh386.sys from Turbo Debugger.
The 80386 PC version cannot start when any of these programs is active. To solve the problem, remove the guilty device drivers from your config.sys file.

On the other hand, the 80386 PC version knows how to cohabit with DPMI-compliant or VCPI-compliant environments and memory managers. These include Windows 3, Desqview, and the EMM386, QEMM386 and 386MAX memory managers. In the case of EMM386.EXE from the MS-DOS distribution, EMS must be enabled (do not give it the NOEMS option). If you run the 80386 PC under a VCPI-compliant memory manager, configure the memory manager so that it allocates at least 1M of EMS, and preferably 2M or more.

Caml Light runs slowly and does a lot of disk accesses
When Caml Light cannot allocate the RAM it requires, it starts paging to a disk file, which considerably slows down execution. To avoid this, make sure that at least 1M or memory is available to Caml Light, and preferably 2M. Caml Light uses XMS memory if you are not running under a VCPI-compliant memory manager, and EMS memory if you are running under a VCPI-compliant memory manager. In the latter case, make sure to configure the memory manager so that it can allocate enough EMS.