APPENDIX A IMPLEMENTATION A.1 Overview ________ This document describes the Decus C distribution and discusses its implementation on RSTS/E, RSX-11M, RT-11, and VAX/VMS. A.2 Distribution ____________ NOTE The following is in a state of change. The most likely strategy is to have several kits: 1. VMS backup format at 1600 bpi built on a VMS V3.2 system. This will contain both source and compiled images. 2. DOS (FLX) format (source only) on two 1200 foot magtapes at 800 or 1600 bpi. This will contain source files only. 3. RT11 RL02 disk containing a built system and sources stored in "archive" format. 4. RT11 RX01 disk containing built images only -- no sources. Suggestions for improvements are welcome. The master source tape (DOS FLX) was generated on a VAX/VMS system. All files contain readable Ascii text. All executable images were generated by supplied command files. The compiler and run-time library, accounts [5,1] through [5,7], comprise a compiler and run-time system for the C language. The compiler was written by David G. Conroy, and modified by Martin C Compiler and Library Page A-2 Getting on the Air with Decus C Minow, Robert B. Denny, Clifford Geshke, and several others. The run-time libraries for RSX-11M and RT-11 were written by Martin Minow with help from many friends. In addition, there are several executive interface libraries: one for RSX-11M by Robert B. Denny, one for RSTS/E by Jim Burrows, and one for Vax/VMS (for interface with Vax-11 C) by Martin Minow. There is also a portable math library by Fred Fish. The program library, accounts [6,1] through [6,7], offers a collection of tools, games, and other programs, mostly written in C. They are not needed for installation of the compiler (although several programs in the tools account, such as KWIK, are used to build the documentation.) In general, you should be aware that only the tools in [6,1] are tested. The distribution account numbers were originally chosen so as to be identical under RSX-11M (octal) and RSTS/E (decimal). If the C language system is not stored in the above accounts, the implementor on RSTS/E will have to edit command files to define the proper accounts. The GETCMD and BUILD programs may be useful in this regard. [5,1] Command procedures, documentation source, etc. [5,2] Documentation. [5,3] Compiler and assembler source. [5,4] Common (non-I/O) library source. [5,5] I/O library source and command files. [5,6] Native RSTS/E interface library. [5,7] Native RSX-11M interface library. [6,1] "Software tools." [6,2] Miscellaneous programs -- games and stuff. [6,3] Cross-assemblers for several micro-computers. [6,4] Lexical analyser generator. [6,5] Pieces of a standard library in C [6,6] Useful subroutines in C. [6,7] Vax/VMS interface library. The two-tape distribution contains accounts [5,*] on one (full) tape and accounts [6,*] on the second (2/3 full) tape. Each account contains a file named README.nnn describing the contents of the account. For example, the README file in account [5,1] is named README.501. A.3 Command File Conventions _______ ____ ___________ Command files used to build the C compiler and run-time library follow the following standard: V????? VAX/VMS indirect command file C Compiler and Library Page A-3 Getting on the Air with Decus C X????? RSX-11M file for the RSTS/E RSX emulator R????? RT-11 file for the RSTS/E RT-11 emulator M????? RSX-11M indirect command file T????? RT-11 indirect command file .CMD RSTS/E indirect command files, RSX-11M indirect command files, and indirect command files for MAC.TSK and MACRO.SAV. .COM RT-11 or VMS indirect command files .TKB Task-builder indirect command files .ODL Task-builder overlay descriptor commands .EIS [RT11.EIS only] hardware EIS configuration Command files used to build tools and C-language libraries follow the following convention: VN???? Use the native Vax-11C compiler only. VX???? Use Decus-C (RSX compatibilitye) on Vax/VMS. VB???? Use either, selecting the compiler at command invocation. RX???? RSTS/E RSX-11M emulation mode. RT???? RSTS/E RT-11 emulation mode. M???? RSX-11M native. T???? RT-11 native. A.4 Distribution Contents in Detail ____________ ________ __ ______ [5,1] [.command] Command Files and Documentation This account contains documentation source files (.rno), kit building command files, and a few things that didn't fit anywhere else. This includes a number of special-purpose command files used to develop the C language system (such as FORK.COM, BATCH.COM, and TOOL.COM) which may serve as models for your own needs. It also contains the source for CRUN.BAS, used on RSTS/E systems to pass arguments to C programs and source for C Compiler and Library Page A-4 Getting on the Air with Decus C CCN, used to compile and assembler C programs on native RSX-11M. A full build of the Decus C system may be effected by executing RBUILD.CMD on RSTS/E (requires privileges) or VBUILD.COM on VAX/VMS. Either command requires about two hours to complete. At least 2000 free blocks of disk space is necessary on the default (public) disk. Note that the build will abort if the RSX LBR or TKB programs cannot obtain sufficient contiguous disk space. The RGTDOC.CMD or VGTDOC.COM command files build a new documentation kit. To build the documentation, proceed as follows: 1. Build the compiler and libraries. 2. Build the tools. 4. Use GETRNO to create library runoff files -- see VGTDOC.COM or RGTDOC.CMD. 5. Use RNO.TSK to build documentation on RSX-11M or RSTS/E, or use RUNOFF to built the library on VMS V2.0. 6. If on RSTS/E or VMS, execute FIXDOC to repair .DOC files after RNO.TSK or RUNOFF.EXE has finished messing them up. (See the gory details in RGTDOC.CMD and VGTDOC.CMD.) The GETCMD.C and BUILD.C programs were used to build command files for compilation and network file transfer. See the tool documentation or examine some command files for more information. Run-time library command files were built using the RLBCMD.CMD (RSTS/E) or VLBCMD.COM (VMS) command files. Tool command files were built using the BTOOLS.COM or RTOOLS.CMD command files. [5,2] RSTS/E only On some distributions (but not the Decus submission), this account contains the running system for RSTS/E and save images for RT-11. It is never needed on VMS. Any file residing in this account has been generated from source stored in other accounts. The VMS kit read/write command procedures reference account [5,2] only to copy documentation to and from magtape. Note that CC.DOC, AS.DOC, CBUGS.DOC, CLIB.DOC, and WIZARD.DOC are in this account on all distribution kits. C Compiler and Library Page A-5 Getting on the Air with Decus C This account is the only one that may contain binary files. Consequently, the RSX-11M interface library, CX.OLB, is stored here. It is needed only on native RSX-11M systems. RSX-11M users should be warned that CX.OLB was generated on a VAX/VMS system. CX.OLB is built from a command file in [5,7]. Note that some subroutines will not assemble on RSTS/E or early versions of RSX-11M as the associated macros are not present in the system macro library. [5,3] [.comp] Compiler source This account contains the source and build files for the compiler (CC????.MAC), assembler (AS????.MAC), and the compiler support library (L?????.MAC). The support library is a stripped-down variant of a very early version of the standard library, which is conditionally compiled for RSX or RT-11 flavor I/O support. It is not particularily efficient. To build the compiler, edit RSX.MAC and RT11.MAC to suit your particular hardware needs and execute the CC build command file: @ VMAKCC.COM On VMS ATPK XMAKCC.CMD On RSTS/E RSX mode ATPK RMAKCC.CMD On RSTS/E RT-11 mode @ MMAKCC.CMD On RSX native mode @ TMAKCC.COM On RT-11 native mode Then, build the assembler: @ VMAKAS.COM On VMS ATPK XMAKAS.CMD On RSTS/E RSX mode ATPK RMAKAS.CMD On RSTS/E RT-11 mode @ MMAKAS.CMD On RSX native mode @ TMAKAS.COM On RT-11 native mode [5,4] [.otscom] Common Library This account contains the "common" run-time library source. These files have no I/O or operating-system dependencies. (Note that a few reference library routines to print error messages.) Several modules are called by direct code generation sequences (e.g., the EIS support routines). Command files are stored in [-.OTSIO] ([5,5]). [5,5] [.otsio] I/O library This account contains I/O dependent run-time library source files. These files conditionally compile to C Compiler and Library Page A-6 Getting on the Air with Decus C generate code for either RSX-11M or RT-11 operating system support. You should be warned that several modules contain essentially two totally distinct subroutines. Internally-called routines are in IO????.MAC. INIT.MAC contains the run-time startup program, which is very system dependent. It also contains some code which is specific to particular operating system releases. To build a library, invoke the appropriate command procedure, using the format described above: @ VMAKLB.COM On VMS ATPK XMAKLB.CMD On RSTS/E RSX mode ATPK RMAKLB.CMD On RSTS/E RT-11 mode @ MMAKLB.CMD On RSX native mode @ TMAKLB.COM On RT-11 native mode [5,6] [.rstslb] RSTS/E Interface Library RSTS/E operating-system dependent subroutines allowing access to RSTS/E executive services by C programs. Many are written in C. They are not as well documented (or written) as they might be. [5,7] [.rsxlib] RSX-11/M Interface Library An interface library to the RSX-11M executive. It is not known what parts of this library work on VMS or RSTS/E emulation modes. This library will not assemble on RSTS/E V7.0 as the distributed system macro library lacks certain executive service macros. [6,1] [.tools] Software Tools C tools. See [.tools]readme.601 for details. The following command files are provided: V?TOOL.COM Vax/VMS: VNTOOL uses the native compiler VAX-11C; VXTOOL uses Decus C; and VBTOOL allows selection of either. R?TOOL.CMD RSTS/E: RXTOOL uses RSX emulation mode, while RTTOOL uses RT11 emulation mode. TTOOL.COM Native RT11. MTOOL.CMD Native RSX-11M. The command files were built by executing BUILD.C for all tools. It is highly recommended that, when you need to recompile a tool, you build the command file using BUILD. For example, to build a command file for GREP on C Compiler and Library Page A-7 Getting on the Air with Decus C your current operating system, you need only execute: build grep.c >grep.cmd On VMS, the TOOL.COM command file may be used to build a tool by running BUILD to create a command file which is then executed. Note that the RSTS and VMS commands refer to logical devices (BIN:) that, on VMS, are defined externally to the build process. [6,2] [.misc] Toys and Other Stuff Toys, half baked ideas, and other stuff. See [.misc]readme.602 for details. Command files are provided to build COOKIE on RSTS/E and VMS. Some of these files haven't been touched in years. [6,3] [.cross] Cross Assemblers A variety of cross assemblers. See [.cross]readme.603 for details. This account also contains a copy of the 8080 C compiler printed in Dr. Dobbs Journal, March 1980. Again, little recent debugging. Files in this account are stored in archives. To build a cross assembler, you should first extract the relevant files. These have not been extensively tested. [6,4] [.lex] Lexical Analyser A lexical-analyser generator written by Charles Forsyth. The standard build command files will create compiler command files. [6,5] [.libc] Library in C The first pieces of a "standard" library, implemented in C. Currently, the str??? and is??? routines, a few floating-point routines, and some pieces of printf are present. It is hoped that this account will eventually replace [.OTSCOM] and most of [.OTSIO] in the future. Note that, in the first Decus C distribution, this account contained a machine-independent microcomputer cross assembler. Those routines are now stored in the "cross assembler" directory in an archive). [6,6] [.useful] Useful subroutines A library of useful subroutines written in C. [6,7] [.vaxlib] VAX/VMS Interface Routines C Compiler and Library Page A-8 Getting on the Air with Decus C Interface routines for use with Decus C programs which are being transported to the native VMS C program product. This library predated the released version of Vax-11 C and may contain modules that have been superseded by the distributed Vax-11 C run-time library. Decus C tools must be linked together with this library in order to access routines, such as fwild(), that are not present in the Vax-11 C library. Note especially that the fact that a routine exists in this library (or that a tool compiles under Vax-11 C) does not imply that the tool or routine has been tested. If you blindly install this library, you are asking for trouble. A.5 Installation Overview ____________ ________ NOTE WARNING If you already have Decus C, please backup all files and zero all accounts before copying this distribution to disk. Several files that were on the previous Decus distribution are not on this tape. If you are installing C for the first time, you should print all "README.???" files, the compiler and library/support documentation files, NEWS.DOC, CC.DOC and WIZARD.DOC (in [5,2]), RSX.MAC, RT11.MAC, RT11.EIS, and the command files for your operating system. NOTE WARNING The RT11.MAC and RSX.MAC command files, as distributed, assume the existance of the SXT instruction. This instruction is not present on some early models of the PDP-11. If C programs or libraries are to run on a PDP-11/20, PDP-11/04, PDP-11/05, or on a PDP-11/40 without EIS, the macro header files must be edited to define C$$SXT = 0 before building the compiler or library. Beware, non-SXT compilation hasn't been tested for quite a while. If your system does not have EIS, you can make "no EIS" standard by editing RSX.MAC and RT11.MAC to set symbol C$$EIS to zero. The native RSX build command file inquires whether SXT and EIS defaults must be set. C Compiler and Library Page A-9 Getting on the Air with Decus C A.5.1 Installation on RSTS/E ____________ __ ______ This installation procedure presupposes RSTS/E V7.1 or later. If you are running on a V6 release, you will have to edit the command files, converting them to batch control files. You may also need to edit SUPORT.MAC, INIT.MAC, FWILD.MAC, and SBREAK.MAC in the run-time library as these routines presuppose executive services that were added with the V7.0 release. Decus C does not require "large files" or other optional RSTS/E features. While the C compiler and run-time libraries generally do not require privileges, you will need privileges to perform a few installation-support functions: Creating accounts. Copying files to a specific account. Installing CCL's and system-wide logicals. Create the various accounts, [5,1] through [5,8] and [6,1] through [6,7]. The accounts may be created on a private disk. Then, copy the distribution tape to these accounts: PIP disk:[*,*]<40>=tape:[*,*] File CX.OLB may be in some distributions. It is not needed for RSTS/E systems and should be deleted. The system manager should add the following commands to your system startup command file (before executing RBUILD): RUN $UTILTY ADD LOGICAL disk:[account] C ! define C logical CCL XCC-=C:CC.TSK;0 ! RSX CC compiler CCL XAS-=C:AS.TSK;0 ! RSX AS assembler CCL CC-=C:CC.SAV;8220 ! RT-11 CC compiler CCL AS-=C:CC.SAV;8220 ! RT-11 AS assembler CCL CRUN-=C:CRUN.*;30000 ! Turn CCL to chain call EXIT where "disk:[account]" is specified to suit your installation's needs. It need not be [1,2]. NOTE C programs will not compile if you haven't added C: as a logical device as they use this logical to locate system-wide header files. C Compiler and Library Page A-10 Getting on the Air with Decus C The CCL's install CC.SAV and AS.SAV to run in a 28 K-word partition. The parameter value is constructed as "8192+K" where K is the number of K-words the software is to run in. Note that these programs do not dynamically expand memory on RSTS/E. The "tools" build command files also make reference to system-wide logical PUB:. This may be assigned to [1,2] or some other "public library" account. If you do not wish to edit these files, you should add PUB: as a "system-wide logical." Make sure protection codes are set properly in the files in C:. You may also want to add CC.HLP and [6,1]CTOOLS.HLP to the help facility. Their format is compatible with the VMS help facility and must be edited for use on RSTS/E. Installing the entire system using the [5,1]RBUILD.CMD control file requires about two hours on a lightly-loaded 11/70 system. Note that RSTS/E system installation requires system manager privileges in order to install CCL commands, system wide logicals, and to create files in other accounts. No C program requires <232> privileges for its operation. If your system manager installs the RSTS/E feature patch to permit cross-account file creates within the same project and gives you a [5,0] and [6,0] account, it is possible to build Decus C without privileges. The RBUILD command file cannot be run directly, however. A.5.2 Installation on VMS ____________ __ ___ This installation procedure presupposes VMS V2.0 or later. If you are running on an earlier release, you will have to edit the command files, replacing account assignments as needed. If you are running on VMS V3.0 or later, you can restore the system from magtape (VAX BACKUP format). If your Decus C distribution was in FLX format, create the various accounts and copy account [5,1] from the magtape to account [.command]: $ create/dir disk:[decusc] $ set default disk:[decusc] The VMS V2.0 file system supports relative directory access as follows: [-.subdirectory] means "move to the parent of the current directory and then down to the indicated subdirectory." This is analogous to the Unix C Compiler and Library Page A-11 Getting on the Air with Decus C syntax ../subdirectory This is not supported in earlier releases of VMS. If not running under VMS V2.0 or later, you will have to edit .COM files accordingly. In any case, create the following sub-directories ([P,Pn] shows the correspondance between the tape directory and disk subdirectory): [5,1] [.command] Command files and documentation [5,2] [] .DOC files [5,3] [.comp] Compiler source [5,4] [.otscom] Common (no i/o) run-time library [5,5] [.otsio] I/O run-time library [5,6] [.rstslb] RSTS/E library [5,7] [.rsxlib] RSX-11/M library [6,1] [.tools] C source for useful programs [6,2] [.misc] Various junk [6,3] [.cross] Cross-assemblers [6,4] [.lex] Lexical analyser [6,5] [.cfloat] Floating point library [6,6] [.useful] Useful subroutines [6,7] [.vaxlib] Vax native library Set [.command] as your current default and copy [5,1]VRKIT.COM from the magtape to this account: $ set default [.command] $ mount/foreign mta0: $ mcr flx sy:=mt0:[5,1]vrkit.com/do Now, edit file VRKIT.COM to suit your needs and execute it. (If your distribution is on 1200 foot magtapes, you should copy VRKIT1.COM, execute it, then mount the second magtape on MTA0: and execute (after eventual editing) VRKIT2.COM. The VRKIT command procedure copies all other files to the disk. Because of the many rewinds, this command requires several hours to complete. An alternate distribution for VMS systems only uses the MCR RMSBCK utility to write each subdirectory in a "container" file. The distribution tape is labelled "C" and contains the following files: README.NOW A short file explaining the process KIT.DOC This document BCK.COM The backup command file used RST.COM A model restore command file FILEnn.BCK Container files To generate a C system from the backup tape, you must first copy RST.COM to disk, edit it to set correct disk and directory C Compiler and Library Page A-12 Getting on the Air with Decus C designations, then execute it as an indirect command file. After reading the kit, install the system using the VBUILD.COM command procedure. One simple way to do this is by typing the following sequence: $ set default [.command] $ @batch vbuild ! or submit vbuild This builds a temporary batch control file in your login account, submits it to batch, and sends you mail when the process completes. Batch.com requires some cooperation from your login.com file. The compiler, assembler, and run-time library are written to the parent of [.command] (generally [decusc]). The tools are written to logical BIN: which should be defined before starting the build process. (Edit vbuild.com if BIN: is not defined in your login.com file.) [.command]CCHLP.COM is a command file that adds DECUSC.HLP to the system (VMS V2.0) help library. It requires write-access to the help library. It may not be compatible with later help file conventions, nor has it been tested on later releases of VMS. Installation of VBUILD on an unloaded Vax-11/782 running VMS V3.0 takes about 90 minutes. A.5.3 Installation on RSX-11M ____________ __ _______ There are command files of the format M?????.CMD. They should require no editing for RSX-11M V3.2. Execute them using the "@" system command, answering the questions as needed. Several routines in the RSX interface library are specific to the V3.2 release and will not assemble on previous releases (or on RSX-11M emulated on RSTS/E). A.5.4 Installation on RT-11 ____________ __ _____ An easy way to build an RT-11 system is to first built a RSTS/E system. Then, use ATPK to execute RTKIT.CMD (after editing) to copy files to an RT-11 format disk. To run the compiler, define logical device C: to refer to the disk containing the "#include <>" files and libraries and off you go. Command procedures of the format T?????.COM are present for "native" RT-11. They are not optimized to minimize disk storage usage. Decus C has been built on 2 RK05 RT11 systems, using one RK05 for system and one for source files. C Compiler and Library Page A-13 Getting on the Air with Decus C Except for "RT11.MAC", "RT11.EIS", and "RSX.MAC" (which are everywhere identical), there are no known conflicts among compiler and library file names. However, given the size of the C distribution, it would be prudent to use separate disks for the various components of the distribution. The C system runs on diskette-based systems, such as the PDT-150. (and even on a VT103 with two TU58's!) No command files are present to build the system on diskette systems. Instead, you should copy the necessary files to diskette as follows: o Build an RT-11 system containing file transfer utilities, editors, LINK.SAV, and LIBR.SAV. o Copy CC.SAV, AS.SAV, and STDIO.H to this disk (there will be only a few free blocks left). This diskette will be defined as the C: logical device. o Initialize a second diskette and copy CLIB.OBJ and SUPORT.OBJ to it. Your C programs should be created on the second disk. There will be slightly more than 300 blocks free after creating CLIB.OBJ and SUPORT.OBJ. Note that, if you omit some of the file transfer utilities, CLIB.OBJ and SUPORT.OBJ may be stored on the system disk, freeing the second diskette for your C programs. You should attempt to keep C program files quite short, using the linker/librarian to build larger entities. For example, the MAZE.C program (in [6,2]) needs over 200 blocks of temporary disk storage for compilation. This is unsatisfactory in many situations. The C language system has not been tested on HT-11. Several of the library routines use RT-11 Version 3 monitor calls that are not supported on HT-11. However, it should not be too difficult to "fix" the library as needed. While all tools have been compiled using Vax-11 C, only a few have been tested in "native C." Note also that there are a few incompatiblities between Decus C and "standard" C, and several incompatibilities between the Decus run-time library and Unix-style standard libraries. C Compiler and Library Page A-14 Getting on the Air with Decus C A.5.5 Supporting Decus C __________ _____ _ Decus C is distributed in source format. All files are in the public-domain. WIZARD.DOC contains information on compiler data formats and library internal information. This software is made available without any support whatsoever. To support the Decus C language, run-time library, or C programs, you will need to understand and modify Macro and C source code. The authors would appreciate your communicating bug reports (with fixes!) and suggestions. The Decus "Structured Languages Special Interest Group" is the primary focus for communication among users of Decus C.