Vn 3.01 18-April-2020

Ocode BCPL under Windows

This document provides a guide to installing the environment necessary to compile and run Robert Nordier's 'oBCPL' compiler distribution kit under Windows (XP/W7).  This Windows port of  Martin Richards'  'second generation' BCPL compiler produces 32-bit executable programs (.exe files) in the same way as the Windows port of its predecessor, the 'Classic BCPL' compiler.

Disclaimer

This is a 'work in progress'.  While it appears to function correctly, bugs may appear which will hopefully be fixed, and things which presently work may be changed to improve them - See 'Bug Fixes & Changes'

While nothing has been engineered into this kit which is intended to harm your PC or its files I have to state that this is free software.  There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


Dave Cannon
D.Cannon(at)ex.ac.uk



0.    Contents

  1. Tools Required
  2. Why do I Need All This Stuff?
  3. One Step at a Time
    1. The BCPL KIt
    2. The GNU Compiler, Assembler and Loader
      1. GNU Loader Script Files
    3. The GNU 'make' utility
    4. The GNU CoreUtils Package
    5. The GNU util-linux-ng Package - 'getopt'
  4. Compile the Compiler!
  5. And now to BCPL...
  6. Write Your First BCPL Program
  7. Compile and Run it
    1. Other BCPL Programs
    2. Writing Your Own Code - Command-line Input
    3. The BCPL.cmd Script
  8. Notes on the Compiler
  9. Bug Fixes & Changes
  10. Known Bugs
  11. The Current BCPL Compiler...
  12. Acknowledgements

1.    Tools Required


2.    Why do I Need All This Stuff?

The good news is that, if you've already downloaded and installed the 'Classic BCPL' compiler kit, you won't need to repeat the installation of the required GNU c compiler, or the accompanying GNU tools - they're already in place.  You just need the' oBCPL' kit.

The GNU compiler and tools are needed as the first step of the bootstrap process, to convert a machine independent OCODE representation of the BCPL compiler (hence 'oBCPL') to a runnable 32-bit Windows program.  This version of the BCPL compiler itself produces OCODE versions of your BCPL programs, and the same c program is used to convert these to Windows executables.


3.    One Step at a Time

3.1    The oBCPL Kit

First, download the Windows BCPL-0.9.8.zip to a suitable folder on your PC, BCPL perhaps, and expand/unzip it.  This should create a folder called 'BCPL-0.9.8' containing a number of subfolders and files.  This is the oBCPL kit for Windows.

3.2    The GNU Compiler, Assembler and Loader

If you've already installed the Classic BCPL kit for Windows, skip this step, otherwise refer to 'Classic BCPL Under Windows: 3.2 The GNU Compiler, Assembler and Loader'

It is worth emphasising here that If you already have a c compiler, assembler and loader package installed from some other source please BE AWARE that integrating the BCPL kit with your installation will be non-trivial, and you will in all likelihood need to edit ALL the scripts and Makefiles in order that the BCPL build will work.

3.2.1    GNU Loader Script Files

If you've already installed the Classic BCPL kit for Windows, skip this step, otherwise refer to 'Classic BCPL Under Windows: 3.2.1 GNU Loader Script Files'

3.3    The GNU 'make' Utility

If you've already installed the Classic BCPL kit for Windows, skip this step, otherwise refer to 'Classic BCPL Under Windows: 3.3 The GNU 'make' Utility'

3.4    The GNU CoreUtils Package

If you've already installed the Classic BCPL kit for Windows, skip this step, otherwise refer to 'Classic BCPL Under Windows: 3.4 The GNU CoreUtils Package'

3.5    The GNU util-linux-ng Package - 'getopt'

If you've already installed the Classic BCPL kit for Windows, skip this step, otherwise refer to 'Classic BCPL Under Windows: 3.4 The GNU util-linux-ng Package - 'getopt'

4.    Compile the Compiler!

In your Command Prompt window, go to the location that your BCPL compiler source files were unzipped to (this is "C:\Users\Dave\Apps\BCPL\BCPL-0.9.8" on my system, but only the bold part is likely to be replicated on your system).

So, type:

cd  C:[...]\BCPL\BCPL-0.9.8

In this folder you'll see a selection of folders and files, these being the parts of the BCPL compiler, and crucially two DOS command files to build the compilers themselves:

BCPLenv.cmd
Makeall.cmd
If you need to change the contents of either of these files - or anything else in this package - you'll need a competent editor.  My preference is the Notepad++ editor, which - if you're interested - you'll find if you search the web...

BCPLenv is a simple command file to establish the environment necessary to build and run the BCPL compilers and programs in this package.  You MUST execute it from the directory you find it in - DO NOT move it anywhere else!  When you type...
BCPLenv
...you should see something like the following on a Windows 7 system:

        BCPL environment established as:

BCPLdir=BCPL-0.9.8
BCPLenv=Vn 1.02 20-Oct-2015
BCPLocd=C:\Users\Dave\Apps\BCPL\BCPL-0.9.8
BCPLroot=C:\Users\Dave\Apps\BCPL\BCPLkit
GnuWin=C:\Program Files (x86)\CodeBlocks\MinGW
minGWVn=4.7.1

Now you can build the BCPL compiler, and various BCPL programs which form the BCPL OCODE distribution package.

Type
makeall
and you should see the following output scroll up your Command Prompt window:
        ________ src _________
gcc  -c cg.c
gcc  -c oc.c
gcc  -o cg cg.o oc.o
gcc  -c op.c
gcc  -c pt.c
gcc  -o op op.o pt.o
as  -o su.o su.s
cg < st.ocd | op > st.s
as  -o st.o st.s
cg < blib.ocd | op > blib.s
as  -o blib.o blib.s
as  -o global.o global.s
as  -o rtc.o rtc.s
ld --allow-multiple-definition -Bdynamic "-TC:\Program Files (x86)\CodeBlocks\Mi
nGW\mingw32\lib\ldscripts\i386pe_mgw.x" "C:\Program Files (x86)\CodeBlocks\MinGW
\lib\crt2.o" "C:\Program Files (x86)\CodeBlocks\MinGW\lib\gcc\mingw32\4.7.1\crtb
egin.o" -o st.exe su.o st.o blib.o global.o rtc.o -lmingw32 -lmoldname -lmingwex
 -lmsvcrt -luser32 -lkernel32 -ladvapi32 -lshell32 "C:\Program Files (x86)\CodeB
locks\MinGW\lib\gcc\mingw32\4.7.1\crtend.o"

        ________ util _________
..\src\bcpl  bcplxref.b
..\src\bcpl  cmpltest_x.b
..\src\bcpl  cmpltest.b
..\src\bcpl  procode.b
..\src\bcpl  mlisp.b
..\src\bcpl  xref.b
..\src\bcpl  gpm.b

If you did, you now have an oBCPL compiler, running under Windows!   If you saw an error message, typically from 'make', you'll need to check at what point the build failed, and attempt to correct the problem.  It will probably be a broken path to one of the components.  If all else fails, feel free to contact me with as full a trace as possible of what happened - I'll try to help, if I can.


5.    And now to BCPL...

So, how to use the compiler?  If you take a look in your ...\src folder you'll see you now have a set of (32-bit) executable programs of various sizes:
37,288
cg.exe
31,409
op.exe
138,980
st.exe

These make up the oBCPL compiler - st.exe is the syntax analyser and translator, producing OCODE, cg.exe is the code generator, producing an assembler source file (optionally fed through the op.exe code optimiser) which is input to the GNU 'as' program to create Windows-compatible executables.  There's a DOS command file, bcpl.cmd, in the ...\src folder to make it easier to use these.


6.    Write Your First BCPL Program

This part's even easier - the 'util' directory contains a set of BCPL programs as examples of the language.  Compile or amend these at your leisure.

7.    Compile and Run it

A copy of bcplxref.b is in the 'C:[...]\BCPL\BCPL-0.9.8\util' directory, so, assuming your Command Prompt window is still in the '...\src' directory, type:
cd ..\util
and then type:
..\src\bcpl bcplxref.b
(the '..\src\'... part is needed because the Windows script, 'bcpl.cmd' is not in the Windows 'path' Environment Variable - but you know how to fix that...)  This should output the following...
BCPL 1061252
OPTIONS  L9500

TREE SIZE 6814

PHASE 1 COMPLETE
and if you then type:
bcplxref bcplxref.b
you should see:
BCPL cross referencer

Work space: 30000
File 1 is "LIBHDR"

  a           593V   594    594    594
  addref       48G   483P   553
  ARGC         53G1  624V   639    642
  arglst      624V   639
  ARGV         54G1  626V   639    647    647    662    664    670    671
              673
  BYTESPERWORD        64M1  629
...
  WRITEF       41G1  426    565    587    609    657    660    664    673
  WRITES       31G1  561    562    563    564    595    634    643    654
              658
  wrnameinfo          51G   570    574P
  wspacesize          31M   631    660    679
  x           478V   480
  xref         49G   489P   679
  y           478V   480

* - never used

Key to references in <lineno><type><fileno>
 V - variable
 p - procedure
 L - label
 G - global
 M - manifest
 S - static
 F - FOR loop variable

Space used 3219
...scroll up your screen.  The BCPL cross-referencer is a handy program to list the occurrence and usage of the variables and library routines in your BCPL programs.

7.1    Other BCPL Programs

The ...\util folder contains a number of more interesting programs written in BCPL, all of which should compile and run under Windows, including:
bcplxref.b a BCPL source code cross-referencing program  (see above)
cmpltest.b to run checks on the compiler output
cmpltest_x.b to run more checks on the compiler output
gpm.b an implementation of Christopher Strachey's GPM macro language parser.  Some usage guidance is offered in the file: gpm_readme.txt
mlisp.b A C Norman's mini-lisp implementation (after compilation, try mlisp mlispdemo.l)
procode.b convert the ...ocd OCODE files output by this compiler to a more readable text form  (Try ..\src\bcpl -c procode.b & procode procode.ocd procode.txt & procode.txt)
testb.b a test program which reads and lists items on its command line, and ends by calling MAPSTORE() to output the Global vector, the file table, and the BCPL stack
xref.b an earlier version of the BCPL source code cross-referencer (after compiling it, try xref < xref.b)

The included Makefile will compile all of the above - the usual caveats apply regarding your system and your installation.

7.2    Writing Your Own Code - Command-line Input

BCPL was designed to be portable, so its reliance on the host Operating System services are minimal, being limited to twelve i/o requests and half a dozen system services (eg STOP).  These are all fairly straightforward to implement.  One facility which is undefined and therefore different on almost every BCPL port is how command-line arguments are passed through to the user's program.

The Windows BCPL port is built over the GNU c runtime API, and it seemed natural to pass c's concept of argv and argc through to the user's program - this is a fairly light touch approach where command-line arguments are separated by spaces, and each item on the argument list is passed by address to the BCPL START routine, with the number of arguments passed in argc.  The program 'testb.b' offers an example of its use:

LET start(argv, argc) BE
$(
...
FOR pct = 0 TO argc-1 DO
        WRITEF("argv!%n=%n (%s)*N", pct, argv!pct, argv!pct)
...
$)
When executed as:
testb this is a test
the program will output (amongst other things)...
Test command line args and dynamic vectors...
argv=2737088, argc=4

argv!0=2737096 (this)
argv!1=2737100 (is)
argv!2=2737104 (a)
argv!3=2737138 (test)
...

Note that every argument offered is passed through to the program as a (BCPL) text string - numbers are NOT converted to their value.  Equally, spaces are the only recognised delimiter between arguments, so if you wish to perform your own argument parsing, you could use a non-space delimiter, for example comma (so: myprog arg1,arg2,longarg3) or you could enclose the whole set of arguments in quotes, eg myprog "arg1 arg2 longarg3".  In either case you will receive just one argument string.

Alternatively, blib.b, (the BCPL run-time library) offers a simple version of RDARGS() which will convert numeric arguments to their value and leave other arguments as BCPL strings - see blib.b for details.

7.3    The BCPL.cmd Script

As noted above, the most usual use for the BCPL.cmd script is 'bcpl myprog.b' to create 'myprog.exe', but typing...
bcpl
without arguments will list additional features - these are currently:
Usage:  ..\src\bcpl.cmd [-Options] [-o output] file
        where   file is a BCPL source program to be compiled
                [-o output] (optional) specifies the compiled program name
                [-Options] may be any of:
                [-O] (optional) suppresses the code optimiser
                [-c] (optional) preserve OCODE output as 'file.ocd'
                [-l] (optional) preserve the 'file.o' object file for ld
                [-S] (optional) preserve the 'file.asm' assembler file

        ..\src\bcpl.cmd Vn 2.03 20-Aug-2014
If you're interested in the various intermediate stages of the creation of your executable, or you wish to optimise its code, there's an option to do it.

8.    Notes on the Compiler

This distribution package, BCPL-0.9.8.zip, is Robert Nordier's oBCPL kit, with a few modifications, largely to add some extended i/o and diagnostic capabilities to the BCPL library module, blib.b, and to the library header file, libhdr.

If you prefer to experience oBCPL without these embellishments, go to the ...\src directory and rename
from...
...to
blib_orig.b ->
 blib.b
blib_orig.ocd -> blib.ocd
libhdr_orig -> libhdr

respectively, then recompile the compiler.


9.    Bug Fixes & Changes

NB:  These changes/fixes are NOT included in the .._orig.x files (see 'Notes on the Compiler', above), except where noted.

30-October-2015: Introduction of BCPLenv script, to establish the environment for the makefiles, compiler and programs
22-June-2014:
 GLOBAL space extended to 999 entries - 'cmpltest_x' now works...
31-December-2013:
 tm := time() support added to rtc.S (tm is the c tm struct) and timeofday(), date() added to blib.b
18-November-2013:
 stream := findfile("filename", "mode") added to rtc.S, where "mode" may take any of the modes permitted by the c library 'fopen()' call
26-October-2013: A tidy-up release:
  • ENDSTREAM(streamno), to close the nominated input or output stream, added to blib.b and LIBHDR files
5-October-2013:
 Code added to blib.b to support a limited version of rdargs(), handling command-line parameters, and trap(), which catches attempts to call undefined GLOBALs
22-August-2013:
 Initial version

10.    Known Bugs

...as of:
 Issue
22-August-2013: None yet identified

11.    The Current BCPL Compiler...

BCPL has moved on from the version presented here as 'oBCPL'.  Martin Richards' web pages detail its current incarnation.

Three versions of the BCPL compiler, postdating the version presented in this oBCPL kit, are available in the Windows Classic BCPLkit.zip.  Please note that, due to slightly different stack usage, modules created and used by this version of the compiler are not interchangeable with those for the Classic BCPL compiler and its descendants.  Compare the reclaim() routine in the versions of mlisp.b for detail.


12.    Acknowledgements

I'm indebted to Martin Richards, for conceiving and creating BCPL, including his much updated and extended versions, and to Robert Nordier for his work in making available both the Classic BCPL porting kit and this oBCPL kit in a way that enthused me to try a Windows version.  The vast content of this port is due to their effort, and remains their copyright.


Dave Cannon
April 2020