PROJECT STATUS AS OF APR. 2018
==============================

The compiler builds and runs successfully in MVS3.8 and in linux.  The package consists of the compiler proper (comp), the preprocessor (cpp), yacc, and standard library, as well as two applications (apl11 and ex-1.1).  The compiler is bootstrapped in linux where the build process generates a series of MVS assembler and link jobs.  These jobs are executed in MVS to produce executable modules for comp, yacc, cpp, apl, and ex.

BUILDING
========

Prior to building inspect and change (if necessary) asmjcl.txt.  Also allocate the following datasets:
    HERC01.OBJ   LRECL=80 BLKSIZE=19040 RECFM=FB
    HERC01.LOAD  LRECL=0 BLKSIZE=19069 RECFM=U

In the top level directory, execute the ``build.sh'' script.  The result should be six JCL jobs:
	ex-1.1/jcl.txt
	cpp/jcl.txt
	370/jcl.txt
	lib/jcl.txt
	apl11/jcl.txt
	yacc/jcl.txt
Submit each job (and wait for completion for submitting the next).

After all of the assembler jobs in the previous step are complete, submit the link jobs:
    ex-1.1/linkjcl.txt
    cpp/linkjcl.txt
    370/ulinkjcl.txt
    370/linkjcl.txt
    apl11/linkjcl.txt
    yacc/linkjcl.txt

Verify there were no errors in the jobs; all job steps should have a completion code of zero.  Any exceptions should be investigated and resolved before proceeding.

USAGE
=====

To compile a module you can make a copy of the file ``370/runjcl.txt'' and modify it accordingly for your source and object dataset definitions.  The file ``ulinkjcl.txt'' contiains model JCL you can use for linking the application (search for and change two occurrences of "UTIL"; add additional SYSLIB statements as needed for each object module).

Prior to building source in MVS you must populate the INCLUDE directory (by default this is named HERC01.H in the sample run jcl).  All of the .h files in include and include/sys should be copied to this MVS include data set.

The apl and ex packages are not currently in a sane state.  Each package is complied without error and linked with a stub module (fake.c) that provides dummy replacements for many missing functions in the MVS standard library package.

COMPATIBILITY
=============
The linux and MVS versions of the compiler produce assembler code that's identical regardless of which version is used, with the following caveats:
 - The compilers disagree in some cases about the representation of floating point constants in the source code.  These differences at assembler source level (e.g., "1.0E2" versus "100.0") should not cause differences in the object code.
 - The C preprocessor in linux (actually gcc is used) and the native C preprocessor in MVS (cpp) disagree about adding blank lines to the intermediate file (the output of the preprocessor before it is passed to the compiler).  The easiest workaround for this is to delete blank lines from the intermediate file (via the UTIL application).  If the blank lines aren't deleted the resulting assembler output files will differ.  In this case the differences affect the diagnostic (comment fields) only, and once again should cause no difference in the object code generated.  The blank line deletion is implemented in the tools in this distribution.
 - Yacc is used in a few instances in these projects.  In the case of the portable compiler the yacc program may be run either in linux or in MVS with identical output.  However this is not true in general; as a rule you should use the MVS version of YACC when building. This is because parsers generated by the linux bootstrap build (ASCII) version of yacc may disagree with the MVS (EBCDIC) implementation; specifically, character set differences.
 - NOTE: The version of yacc in this project must be used; the linux native version of yacc is not compatible with this toolset.

PROJECT STATUS AS OF FEB. 2017
==============================
A work in progress, the project is bootstrapped by first building the C
sources under linux to produce a linux executable.  The C source modules
are combined with several C sources and two assembly source modules from 
the PDPCLIB (PDOS) project. These C files are compiled using the linux
executable (named "comp") to 370 assembler language output files.  These
files along with the two PDPCLIB assembler sources are transferred to MVS
and assembled/linked.  The resulting MVS executable is capable of compiling
very simple C source programs although there are several bugs. It is not known 
how many more bugs will need to be fixed before a stable compiler exists.

The original sources of the portable C compiler were from version 7 of the 
early unix distirbutions, and based on the PDP-11 backend.  Any errors
that were introduced are mine and may be due to incomplete or erroneous
understanding of the original intent.  The reader is strongly encouraged to
thoroughly read the paper by S. C. Johnson ("A Tour Through the Portable C
Compiler", 197x).

Note that this version of the compiler has been developed for MVS/370, but
nothing in the work should preclude the addition of VM/370 support.

This project would not have been possible without GCC/370 and PDOS.

ITEMS YOU WILL NEED TO CHANGE BEFORE BUILDING
=============================================
yacc/files - update this path (optional, only if you want to rebuild yacc)
	# define PARSER "/home/mhp/pcc/yacc/yaccpar"
370/makefile - update path setting
	M=/home/mhp/pcc/370



TO BUILD
========

cd 370/
make
./docomp.sh
cd ../lib
./docomp.sh
# check all the .err files for errors/warnings [see note 8]
cd ../370
./asmall.sh
# asmall.sh should produce a file named deck.txt
# you will need to pre-allocate and catalog the SYSPUNCH dataset 
# (HERC01.OBJ) in the JCL [see note 6]
# you must then submit the JCL file [deck.txt] to MVS as a batch job
# next you will need to pre-allocate and catalog the SYSLMOD dataset 
# e.g., HERC01.LOAD [see note 6]
# submit the linker JCL [see note 7]
./lkc.sh

TO RUN
======
# first transfer the test C source file lib/main.e to MVS
# ensure that the [ and ] characters were not mangled in the upload
# then submit the JCL file [runjcl.txt] to MVS as a batch job
# as of this writing the compiler produces most but not all of the output
# and there are discrepancies versus the output of 'comp' run on linux.

NOTES
=====
1. yacc (included) need only be rebuilt if you're rebuilding the cgram.c file.

2. three of the assembly steps should receive a code 4 - all the remaining jobs should receive a code 0.  (total five statements flagged, these will have to be fixed, someday)

3. the cpp preprocessor hasn't been bootstrapped - accordingly 'gcc -E' is used for all preprocessing duties.  Any C file input to the 'comp' executable (executing either on the build host or in MVS/370) must already have the preprocessing fully done for it beforehand (e.g., the files produced by the host build process having a '.e' suffix)

4. the build sh scripts require the "basname" command with support for the '-s' option - this option is fairly new and may not appear in some older distros - beware.

5. any additions herein are released under the same license as the original unix distributions

6. the following files contain MVS host dataset names and jobcard info that you may need to edit: asmjcl.txt lkc.txt runjcl.txt

7. the linker script assumes an MVS reader is listening on localhost port 3505.

8. no errors should be generated in the *.err files; the expected warning counts are 45 stdio.err, 3 stdlib.err, 4 string.err, 1 local2.err