BCPL CINTCODE DISTRIBUTION

This distribution of BCPL is free of charge to individuals for private
use and to academic institutions, but please, if you install the
system send me an e-mail message (to mr@cl.cam.ac.uk) so I can keep a
record of who is interested in it. It is available via my Home Page
(http://www.cl.cam.ac.uk/users/mr).

It provides a machine independent interpretive version of BCPL. The
interpreter in implemented in C, but for many architectures it also
has a version implemented in assembly language which greatly improved
the performance.

This distribution contains versions of the system for Linux, DEC Alpha
machines, Mips R2000/3000 machines, Sun4s, Sun/SPARCs and
386/486/Pentium machines under MSDOS, Windows 95/98/NT/2000, Windows CE2.0
(for the HP 620LX), MAC or OS/2. The implementations for the MAC and
OS/2 have not been tested recently and are out of date. The simplest
installation is for Linux machines. Installation on other machines is
described later.

TIME/ADDRESS DIAGRAMS

A version of the interpreter that can generate a time/address
diagrams in Postscript has been added to the distribution (see
com/raster.b, com/rast2ps.b, sys/rasterp.c and sys/rastlib.c)

PROFILING

Profiling and statistics gathering is available, see com/stats.b

CHANGE LOG

For a log of recent changes look in cintcode/doc/changes.

NATIVE CODE

A BCPL system that generates native is now available in this
distribution.  It currently only provides code generators for the i386
and DEC Alpha architectures.  On these machines it gives a speed up
of about a factor of ten.


PERFORMANCE STATISTICS (Cintcode interpreters)

                            BCPL self           bench         Date
                            compilation                       measured

Cintcode instructions        22244904           6176753       12 Jan 96
executed

66MHz 486 Linux                5.340             1.360        11 Jan 96

120MHz Pentium Linux           2.030             0.550        12 Jan 96

90MHz Pentium Linux            2.770             0.710        31 May 96

90MHz Pentium Linux native     0.75              0.109        19 Aug 96

450MHz Pentium Linux           0.760             0.270         7 Jan 00

450MHz Pentium Linux native    0.09              0.03          7 Jan 00

400MHz Pentium Windows NT      0.881             0.320         7 Dec 99

150MHz DEC Alpha               3.199             0.766        12 Jan 96

DEC R2000/R3000 Mips (10MHz?) 45.750            12.394        12 Jan 96

Sun4m ????                    13.549             3.817        12 Jan 96

Sun4m SPARC 20 Model 514       9.830             2.610        12 Jan 96

75MHz SH3 Windows CE 2.0       7.558             3.517         7 Jan 00

(The CPU times are in seconds)

LINUX INSTALLATION 

This section describes how to install Cintcode BCPL on an IBM PC
running Linux.

1) Choose a directory into which you wish to install BCPL and copy bcpl.tgz
into it. E.g:

        cd <somewhere>
        cp <bcpl.tgz> .
        ls -l

2) Extract the files for the BCPL system, eg

        tar zxvf bcpl.tgz

Some browsers will have already automatically decompressed bcpl.tgz,
so you may have to use the following command instread:

        tar xvf bcpl.tgz

This will create the directories BCPL, BCPL/cintcode, BCPL/bcplprogs
and BCPL/natbcpl and fill them with useful material. The directory
BCPL/bcplprogs contains subdirectories of demonstration programs, and
BCPL/natbcpl contains the native code versions of the system.

3) Change to the cintcode directory an rebuild the system:

        cd BCPL/cintcode
        make clean
        make

Note that the line 'make clean' is a recent recommendation that
eliminates some commonly reported problems.

4) This should have rebuilt and entered the BCPL Cintcode System, but
it will have only installed a few commands (including bcpl and c). To
compile all the other commands type:

        c compall

5) Try out a few commands, eg:

        echo hello
        bcpl com/echo.b to junk
        junk hello
        map pic
        logout   (or CTRL-C)

Try "cinterp -h" to see how to set the Cintcode memory size.

6) Read the documentation in cintcode/doc and any README files you can
find, and possibly try out the demonstration script in
cintcode/doc/notes.

7) In order to use the BCPL Cintcode system from another directory
define the shell variable BCPLPATH to be the absolute file name of the
cintcode directory and add this directory to your PATH.  This can be
done by editing the file BCPL/cintcode/setenv and running the command:

        . sentenv

This will execute commands similar to:

        export CINTCODE=$HOME/BCPL/cintcode
        export BCPLPATH=$CINTCODE
        export PATH=$PATH:$CINTCODE

The shell variable BCPLPATH is used when loading Cintcode object
modules, reading BCPL header files and command-command files used by
the c command.

8) To compile and run a demo program such as bcplprogs/demos/queens.b:

        cd ../bcplprogs/demos
        cinterp
        c b queens
        queens

9) To construct a time/address graph, ensure that rasterp has been
made, by:

        cd $BCPLPATH
        make rasterp

Then change directory to the one containing the test program, and
enter rasterp, eg:

        cd ../bcplprogs/sort
        rasterp

Compile the test program if necessary, eg:

        c b sortdemo

Open a raster file (eg RASTER), run the test, and close the raster
file:

       raster count 1000 scale 12 to RASTER   
       sortdemo
       raster

This will generate a relatively compact file using run length encoding

    K1000 S12          1000 instruction per raster line, 12 bytes per pixel
    W10B3W1345B1N      10 white 3 black 1345 white 1 black newline
    W13B3W12B2N        etc
    ...

Get out of rasterp and enter cinterp (since it runs faster), convert
the raster file to postscript and view the result:

       logout
       cinterp
       rast2ps m 110000 f 12000000 to /tmp/RASTER.ps
       logout
       ghostview /tmp/RASTER.ps

10) To gather and analyse execution counts, type, for instance, the
following:

    cinterp                     Enter the cintcode system
    preload sortdemo            Preload the program to study
    stats                       Enable stats gathering on next command
    sortdemo                    Execute the command to study
 
    interpreter                 Select the fast interpreter (cintasm)
                                stats automatically selects the slow one

    stats to STATS              Send instruction frequencies to file
                                or
    stats profile to PROFILE    Send detailed profile info to file
                                or
    stats analysis to ANALYSIS  Generate statistical analysis to file


Installation on other unix machines

Carry out steps 1 to 2 above.  In the directory BCPL/cintcode/sys you
will find directories for different architectures, e.g. ALPHA, MIPS,
SUN4, SPARC, MSDOS, MAC, OS2, BC4, Win32, CYGWIN32 and shWinCE. These
contain files that are architecture (or compiler) dependent, typically
including cintasm.s (or cintasm.asm).  For some old versions of Linux,
it is necessary to change _dosys to dosys (or vice-versa) in the file
sys/LINUX/cintasm.s.

Edit Makefile (typically by adding and removing comment
symbols) as necessary for your system/machine and then execute 
make in the cintcode directory, e.g:

       make

Variants of the above should work for the other architectures
running Unix.


Installation on machines running Windows 95/98/NT/2000/XP

The files cinterp.exe and rasterp.exe are included in the standard
distribution and should work under these operating systems just by
typing the command:

    cinterp

I recommend using the GNU development tools and utilities for Windows
95/98/NT/2000/XP that are available from

        http://sources.redhat.com/cygwin/download.html.

I would recommend clicking on the "Install Cygwin Now!" link.
I am currently using the Cygwin DLL 1.3.3 release.

Edit the cintcode/Makefile to comment out the LINUX version

    #CC = gcc -O9 -DforLINUX
    #SYSM = ../cintcode/sys/LINUX
    #CINTASM = cintasm.o
    #ENDER = LITENDER

and enable the CYGWIN32 version

    CC = gcc -O9 -DforCYGWIN32
    CINTASM = cintasm.o
    SYSM = ../cintcode/sys/CYGWIN32
    ENDER = LITENDER

Then type:

    make

This should recompile the system and create the executable cinterp.exe.

REMEMBER to include the cintcode directory in your PATH and BCPLPATH
environment variables, so that the cintcode system can be run in any
directory.

Careful inspection of the Makefile and directories in cintcode/sys will
show that versions also exist that use Microsoft C++ 5.0 and Borland C
4.0, but these are now out of date and are not recommended.


INSTALLATION FOR THE MAC OR OS/2

These are non-unix systems and so you have to invent the appropriate
sequence of operations to construct the system.  Under OS/2 and I used
IBM's CSET/2 for the C programs and Borland's TASM as the assembly
language.

The MAC and OS/2 versions are now out of date.

INSTALLATION FOR WINDOWS CE 2.0 (Tested on an HP 620LX)

See the file cintcode/sys/shWinCE/README.


Good luck!


Martin Richards
     (mr@cl.cam.ac.uk, http://www.cl.cam.ac.uk/users/mr)
University Computer Laboratory
New Museums Site                  
Pembroke Street
Cambridge
UK                                                   16 February 2004



