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
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.
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.
3.1 The oBCPL KitFirst, 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 LoaderIf 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'
3.2.1 GNU Loader Script FilesIf 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' UtilityIf 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 PackageIf 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'
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).
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.cmdIf 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...you should see something like the following on a Windows 7 system:
BCPL environment established as:
BCPLenv=Vn 1.02 20-Oct-2015
GnuWin=C:\Program Files (x86)\CodeBlocks\MinGW
makealland 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
________ util _________
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.
cd ..\utiland 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 1061252and if you then type:
TREE SIZE 6814
PHASE 1 COMPLETE
bcplxref bcplxref.byou should see:
BCPL cross referencer...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.
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
BYTESPERWORD 64M1 629
WRITEF 41G1 426 565 587 609 657 660 664 673
WRITES 31G1 561 562 563 564 595 634 643 654
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
7.1 Other BCPL ProgramsThe ...\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) BEWhen executed as:
FOR pct = 0 TO argc-1 DO
WRITEF("argv!%n=%n (%s)*N", pct, argv!pct, argv!pct)
testb this is a testthe program will output (amongst other things)...
Test command line args and dynamic vectors...
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 ScriptAs noted above, the most usual use for the BCPL.cmd script is 'bcpl myprog.b' to create 'myprog.exe', but typing...
bcplwithout arguments will list additional features - these are currently:
Usage: ..\src\bcpl.cmd [-Options] [-o output] fileIf 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.
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
respectively, then recompile the compiler.
blib.b blib_orig.ocd -> blib.ocd
libhdr_orig -> libhdr
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...
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
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:
22-August-2013: None yet identified