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 one 2400 1200 foot magtape at 800 or 1600 bpi. This will contain source files only. Suggestions for improvements are welcome. It is pos- sible that binary distributions will be made for RT11 and P/OS, written on diskettes appropriate to the particular operating system. The master source tape (DOS FLX) was generated on a VAX/VMS sys- tem. All files contain readable Ascii text. All executable im- ages 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 Minow, Robert B. Denny, Clifford Geshke, and several others. The run-time libraries for RSX-11M and RT-11 were written by C Compiler and Library Page A-2 Getting on the Air with Decus C 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 Martin Minow, 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 col- lection 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 im- plementor on RSTS/E will have to edit command files to define the proper accounts. The GETCMD and BUILD programs may be use- ful in this regard. [5,1] Command procedures, documentation source, etc. [5,2] Portable math library [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. Each account contains a file named README.nnn describing the contents of the account. For example, the README file in ac- count [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 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 C Compiler and Library Page A-3 Getting on the Air with Decus C 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 fol- low 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 invo- cation. 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 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 C Compiler and Library Page A-4 Getting on the Air with Decus C 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. You should expect to have to edit the command files to suit your system's conventions. 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 mess- ing 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] [.pml] Portable Math Library On the previous Decus distribution, this account con- tained the documentation. As the kit size has grown, this is no longer the case and a portable math library has been stored here. Except to verify that it com- piles, it has not been extensively tested. [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 condi- tionally compiled for RSX or RT-11 flavor I/O support. It is not particularily efficient. C Compiler and Library Page A-5 Getting on the Air with Decus C 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 generate code for either RSX-11M or RT-11 operating sys- tem 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 pro- cedure, 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 C Compiler and Library Page A-6 Getting on the Air with Decus C are written in C. They are not as well documented (or written) as they might be. There is also a RSTS/E specific partial replacement for the standard I/O library stored as an archive that might be of interest to RSTS/E users. [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 RSTS/E emu- lation mode. This library will not assemble on RSTS/E V7.0 as the distributed system macro library lacks cer- tain executive service macros. The library has been used for software that runs on VMS compatibility mode and on P/OS. [6,1] [.tools] Software Tools C tools. See [.tools]readme.601 for details. The fol- lowing 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 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 C Compiler and Library Page A-7 Getting on the Air with Decus C these files haven't been touched in years. Some of these are used very often but are not felt to be suffi- ciently interesting to be in the tools directory. You might note the following: cookie Fortune cookie builder and printer. phbook Phone book searcher -- quite simple. Includes a soundex search algorithm that might be of interest. focal For friends of the PDP-8, runs on vax native and Unix; not tested on Decus C. flx, vaxflx Reads and writes "dos" magtapes on ran- dom operating systems. [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 ac- count 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 pro- duct. This library predated the released version of Vax-11 C and may contain modules that have been super- seded 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 in- stall this library, you are asking for trouble. A.5 Installation Overview ____________ ________ 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 documenta- tion files, NEWS.DOC, CC.DOC and WIZARD.DOC, RSX.MAC, RT11.MAC, RT11.EIS, and the command files for your operating system. WIZARD.DOC may be built from WIZARD.RNO, stored in account [5,1]. WARNING The RT11.MAC and RSX.MAC command files, as distri- buted, 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 com- piler 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 re- quire 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 parti- tion. 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 logi- cals, and to create files in other accounts. No C program re- quires <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 V3.1 or later. If you are running on an earlier release, you will have to edit the command files, replacing account assignments as needed. Compa- tibility mode support is required. 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 vari- ous 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 run- ning 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] [.pml] Portable math library [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. The VRKIT command procedure copies all other files to the disk. Be- cause of the many rewinds, this command requires several hours to complete. 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 ac- count, 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 writ- ten to logical BIN: which should be defined before starting the build process. (Edit vbuild.com if BIN: is not defined in your C Compiler and Library Page A-12 Getting on the Air with Decus C 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 "na- tive" 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. Except for "RT11.MAC", "RT11.EIS", and "RSX.MAC" (which are everywhere identical), there are no known conflicts among com- piler 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. In- stead, you should copy the necessary files to diskette as follows: o Build an RT-11 system containing file transfer utili- ties, 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 C Compiler and Library Page A-13 Getting on the Air with Decus C 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 pro- grams. 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. 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 pro- grams, you will need to understand and modify Macro and C source code. The authors would appreciate your communicating correc- tions to errors you have discovered. The Decus "Structured Languages Special Interest Group" is the primary focus for com- munication among users of Decus C.