home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource4 / 222_01 / cc.doc < prev    next >
Encoding:
Text File  |  1979-12-31  |  17.4 KB  |  461 lines
  1.  
  2.             S m a l l  -   C     D o c u m e n t a t i o n
  3.  
  4.  
  5.                   V e r s i o n     2.70     10/30/86
  6.  
  7.                              by
  8.  
  9.                       F. A. Scacchitti
  10.                       25 Glenview Lane
  11.                       Rochester, NY 14609
  12.                       (716) 482 - 7159
  13.  
  14.  
  15. This  document  is intended to supplement J.  E.  Hendrix's  "The 
  16. Small  C Handbook" and will only discuss the differences  between 
  17. this version of Small C and that described in the Manual.  It  is 
  18. recommended  the  user  purchase  Hendrix's  manual  for  a  more 
  19. complete treatment of Small C.
  20.  
  21. For information regarding the contents and structure of the Small 
  22. C library, refer to the file CLIB.DOC and Hendrix's Manual.
  23.  
  24. This  compiler was originally Version 2.1 as obtained from  J.  E 
  25. Hendrix.  It  includes all of his newsletter  fixes/enhancements. 
  26. Refer  to the file CC.DEF for a complete chronological history of 
  27. changes and details regarding modules or functions changed.  Also 
  28. it  is  assumed the user is somewhat familiar  with  the  M80/L80 
  29. software.  The  compiler  produces  an output  file  of  assembly 
  30. language pneumonics which must be assembled and linked.
  31.  
  32. This  compiler  is  a superset of J.  E.  Hendrix's  Version  2.1 
  33. compiler,  yet  still a subset of C as described by Kernigan  and 
  34. Ritchie in "The C Programming Manual". The following enhancements 
  35. have been installed:
  36.  
  37.    2.1 --> 2.2
  38.  
  39.        * - CP/M runtime package and I/O library to optimize  size 
  40.            and speed
  41.        * - Global initialization option -i
  42.        * - No boot option -n
  43.        * - external static Type Specifiers
  44.        * - Conditional operator {expr1 ? expr2 : expr3}
  45.  
  46.  
  47.    2.2 --> 2.3
  48.  
  49.        * - added multiple levels of indirection
  50.            eg. **char c; ***int ident;  ****var = **c;
  51.  
  52.  
  53.    2.3 --> 2.4
  54.  
  55.        * - improved multiple levels of indirection to ensure 
  56.            appropriate element is stored or retrieved
  57.  
  58.  
  59.    2.4 --> 2.5
  60.  
  61.        * - added arrays of pointers
  62.            eg. char *argv[]; int **i[20]; *i[2] = 22;
  63.        * - added hex and octal constants
  64.            eg. 0x1a, 0XFA, 03777, 00017
  65.  
  66.  
  67.    2.5 --> 2.6
  68.  
  69.        * - added global multidimensional arrays
  70.            eg. char arc[5][5]; int i[3][4][5]; var=i[2][0][3];
  71.  
  72.  
  73.    2.6 --> 2.7 (Released 10/86 for public consumption)
  74.  
  75.        * - added nested includes
  76.        * - new runtime library (rdrtl.rel) for compiler and/or
  77.            redirected output
  78.        * - new i/o library (clib.rel)
  79.  
  80.  
  81. Planned   2.7 --> 2.8 (In final stages)
  82.  
  83.        * - install floating point (float and double)
  84.            (only for Z80 microprocessors)
  85.        * - allow function definition syntax
  86.        * - add compiler error tracker/counter
  87.  
  88.  
  89. Planned   2.8 --> 2.9 (schemes developed)
  90.  
  91.        * - add typedefs, sizeof, unsigned integers
  92.  
  93.  
  94. Planned   2.9 --> 3.0 (matter of parsing) (2nd quarter '87)
  95.  
  96.        * - allow auto, register, short declarations
  97.            (This will be a release version and the final one
  98.             for CP/M)
  99.  
  100.  
  101. Planned   CP/M 3.0 --> MSDOS 3.0 (3rd quarter '87)
  102.  
  103.        * - using J. E. MSDOS version upgrade to my version 3.0
  104.            (will contain floating point, if I can obtain a good 
  105.             package for MSDOS)
  106.  
  107.  
  108. Planned   MSDOS 3.0 --> MSDOS 4.0 (not started) (4th quarter '87)
  109.  
  110.        * - add longs, unions and structures
  111.  
  112. This  is  an  aggressive schedule (slips are  possible),  but  at 
  113. completion  should be a full implementation of C.  If anyone  has 
  114. any  suggestions or has already accomplished that  which  remains 
  115. undone here, don't hesitate to contact me. I have no qualms about 
  116. collaborating to finish the job or optimize compiler operation.
  117.  
  118.  
  119.  
  120. FEATURES and ENHANCEMENTS
  121.  
  122.  
  123. * - Global initialization option -i
  124.  
  125. This  feature decreases compilation time,  especially when  large 
  126. arrays are declared globally.  Most versions of the compiler  (at 
  127. least  the  ones I've seen),  by default,  initialize all  global 
  128. variables to zero by generating either DB 0 or DW 0.  Arrays  are 
  129. initialized via DB 0, 0, 0, 0, 0, 0, . . . . . . . . . .
  130. This  adds significantly to compile time if the user has declared 
  131. large  global  arrays.  The  compiler  now issues  a  DS  n  thus 
  132. allocating n bytes of uninitialized memory.  If the -i switch  is 
  133. used,  memory  will  be  initialized to zeroes as  before.  As  a 
  134. furthur  example, the Eratosthenes Prime Number  Sieve  takes  80 
  135. seconds to compile when the -i switch is used but only 17 seconds 
  136. if  it isn't.  An additional 55 seconds is required with each for 
  137. assembly and linking.
  138.  
  139.  
  140. * - No boot option -n
  141.  
  142. This  feature allows rapid return to the CP/M prompt  on  program 
  143. completion  at a cost of 800h bytes of code space.  It is used in 
  144. conjunction with the runtime package in the C library (CLIB.REL). 
  145. If  the the -n switch is used and the program contains  a  main() 
  146. function,  DB ZZZCCP 1 will be generated by the compiler prior to 
  147. the  END statement.  If it isn't specified the compiler generates 
  148. DB  ZZZCCP  0.  The global variable ZZZCCP determines  where  the 
  149. stack should be placed and the return path to CP/M.  In short, if 
  150. the -n option is used the stack is placed at the base of the  CCP 
  151. and the program returns to CP/M via a return instruction.  If the 
  152. -n  option isn't specified the stack is placed at the base of the 
  153. BDOS and return is performed via a warm boot.  Refer to  CLIB.DOC 
  154. and  ULINK.MAC  for details regarding operation of this  feature. 
  155. This feature is NOT recommended for use with programs  performing 
  156. disk i/o, but was intended primarily for non-disk utilities.
  157.  
  158.  
  159. * - external static Type Specifiers
  160.  
  161. Global  variables  are more rapidly accessed (both  fetching  and 
  162. storing)  and require less code to access than  local  variables. 
  163. Refer   to  Chapter  19  of  Hendrix's  manual  for  a   complete 
  164. explanation.  Most Small C compilers make all global declarations 
  165. public.  This  obviously  presents a problem (especially for  the 
  166. variables c and i) in taking full advantage of this feature.  The 
  167. static type specifier implies that the variable should be  memory 
  168. resident, yet known only to the module it is compiled in. This is 
  169. accomplished  simply  by  generating  a single  colon  for  types 
  170. specified as static and the original double colon for those  that 
  171. are  not.  This  results in variables that are local only to  the 
  172. file  in which they are compiled.  It is ideal for  non-recursive 
  173. library functions.
  174.  
  175.  
  176. * - Conditional operator {expr1 ? expr2 : expr3}
  177.  
  178. This  is just another enhancement to bring Small C closer to  Big 
  179. C.  This  operator  is described quite thoroughly in  Kernigan  & 
  180. Ritchie's  "The  C Programming Language" and works as  specified. 
  181. The  user  should  try the examples in  thier  manual.  The  code 
  182. generated  by this operator is almost exactly the same as an  if-
  183. else statement, however if does lead to more succinct and elegant 
  184. code  at the source level and can be used inside statements where 
  185. if - else fears to tread.
  186.  
  187.  
  188. * - added multiple levels of indirection
  189.  
  190. This was always a sore spot with me.  Now your program can use  a 
  191. standard  argc,  argv syntax.  (int argc;  char **argv;) It  also 
  192. generates  more  efficient  and  shorter  code  since  additional 
  193. argument  assignments  aren't necessary when  accessing  extended 
  194. levels of a pointer. 
  195.  
  196.  
  197. * - added arrays of pointers
  198.  
  199. One more step toward standardization with full C.  The programmer 
  200. may use char **argv;  or char *argv[];  and/or retrieve/store  as 
  201. specified by K & R.
  202.  
  203.  
  204. * - added hex and octal constants
  205.  
  206. Works as described by K & R. NO longer any need for that decimal-
  207. hexadecimal-octal calculator on the shelf. (Well at least not for 
  208. figuring contants and addresses for your small c program.)
  209.  
  210.  
  211. * - added global multidimensional arrays
  212.  
  213. Some  programs almost demand this capability.  However,  there is 
  214. some overhead involved in using multi-dimmed arrays and the  code 
  215. generated  can  be  larger than if  multiple  single  dimensioned 
  216. arrays are used. The generated code calculates the offset for the 
  217. particular  element  be  accessed.  The user must decide  if  the 
  218. overhead is worth allowing the compiler to do the book keeping.
  219.  
  220.  
  221. * - added nested includes
  222.  
  223. Simple enough to add as long as the file structure permits.  This 
  224. particlar implementation allows nesting six deep.
  225.  
  226.  
  227. * - new runtime library (rdrtl.rel)
  228.  
  229. The Runtime Module used with this compiler was originally written 
  230. in C and contained assembly language enhancements.(I think !) The 
  231. present  module  RDRTL.MAC  contains  most of  the  i/o  routines 
  232. required by the compiler and is structured around the 8 - 1k file 
  233. buffers. Ouput redirection (via > and >>), argv/argc handling and 
  234. special  abort features are included.  The resultant size of  the 
  235. compiler  after linking  CCRTL.REL,  CC1.REL,  CC2.REL,  CC3.REL, 
  236. CC4.REL,  and  searching  CLIB.REL  to pick up  a  few  necessary 
  237. function is < 31K.  Smaller than most (Version 2.7).  This module 
  238. can   be  used  with  the  compiler  or  any  program   requiring 
  239. redirectable  output.  It should must always be linked in  first,  
  240. before  searching the clib module.  Failing to do so will provide 
  241. unpredictable results. 
  242.  
  243.  
  244. * - new i/o library (clib.rel)
  245.  
  246. Installed { exp1 ?  exp2 :  exp3 } operator and external  statics 
  247. where appropriate. Library size was reduced from 26k to 24k. Also 
  248. fixed all known bugs and corrected non-standard operations.
  249.  
  250.  
  251. ** - installing floating point (float and double)
  252.  
  253. In the works.  I'm working with the same package installed by Dr. 
  254. James  VanZandt and using his Small-C Version 1.2  implementation 
  255. as  a guideline.  It requires a Z80 processor or another floating 
  256. point package.  The code generated is generic and could work with 
  257. many float packages, the one I'm using is a 6 bit implementation.
  258.  
  259.  
  260. ** - allow function definition syntax
  261.  
  262. Syntax  such  as  "FILE *fd *fopen();" during  global  and  local 
  263. declaration  or  "int func(var1)char var1;" to define a  function 
  264. will  cause erroneous multi-define errors.  This problem will  be 
  265. cleared up and said syntax is now allowed.
  266.  
  267. ** - add compiler error tracker/counter
  268.  
  269. At  completion of compiling the compiler will reports the  number 
  270. of  errors that occurred.  This could be extended to evalute  the 
  271. results  and determine whether processing  should  continue.  ie. 
  272. assembly, linking, optimization . . .
  273.  
  274.  
  275. ** - add typedefs, sizeof, unsigned integers
  276.  
  277. typedefs  are  a little tricky but ca be accomplished by using  a 
  278. convoluted version of the #define code. Don't worry they are true 
  279. type definitions.
  280.  
  281. sizeof will be almost a duplicate copy of the method employed  by 
  282. J. E. Hendrix in his MSDOS Version 2.1.
  283.  
  284. unsigned  integers require adding a byte to the symbol table  for 
  285. furthur variable definition. Most of the routines were already in 
  286. place, just not employed.
  287.  
  288. ** - allow auto, register, short declarations
  289.  
  290. This  was just a matter of adding the appropriate syntax to allow 
  291. parsing these keywords and verifying proper usage.  Both auto and 
  292. register must be locals while short must define an integer.
  293.  
  294. *  fully implemented
  295.  
  296. **  At some interim stage, alpha test, beta test, debug, or under
  297.     development.
  298.  
  299.  
  300.  
  301. USING THE COMPILER
  302.  
  303. The  major differences between using this compiler and  Hendrix's 
  304. are  (1) this compiler does not create a default output file  and 
  305. (2)  his  runtime package includes redirectable input and  output 
  306. (and  the  resultant  code size overhead). If no  output file  is 
  307. specified,  the  output  will go to the console where it  may  be 
  308. stopped and started via Control S and Control Q. If the output is 
  309. suspended  by  Control  S,  Control C may be used  to  abort  the 
  310. compile.  The  compiler is invoked by running the program  cc.com 
  311. followed by the desired options (in the runstring). Some examples 
  312. follow:
  313.  
  314. cc
  315.      compile console input to console output
  316.  
  317. cc test.c
  318.      compile test.c direct output to console
  319.  
  320. cc test.c -p -a -l2
  321.      compile test.c direct output and source to console
  322.                        pause on errors and sound bell
  323.  
  324. cc test.c >test.mac
  325.      compile test.c direct output to file test.mac
  326.  
  327. cc test.c >test.mac -p -a 
  328.      compile test.c direct output to the file test.mac
  329.                       pause on errors and sound bell
  330.  
  331. cc test.c new.c >test.mac -l2 -i
  332.      compile test.c and new.c direct output to test.mac
  333.                       display source on screen
  334.                       initialize global variables to zero
  335.  
  336. cc test.c >test.mac -o -n -l1
  337.      compile test.c direct output to test.mac
  338.                       optimize for size over speed
  339.                       generate no boot flag
  340.                       insert source in output file as comments
  341.  
  342. cc test.c >test.mac -a -p -l2
  343.      compile test.c direct output to test.mac
  344.                       display source on screen
  345.                       pause on errors and sound bell
  346.  
  347. cc test.c >test.mac -o -n -l1 -p -a -i
  348.      compile test.c direct output to test.mac
  349.                       optimize for size over speed
  350.                       generate no boot flag
  351.                       insert source in output file as comments
  352.                       pause on errors and sound bell
  353.                       initialize global variables to zero
  354.  
  355.  
  356. COMPILER OPTIONS (SWITCHES)
  357.  
  358.  
  359.      -a   sound alarm(bell) on errors
  360.      -i   initialize global variables to zero
  361.      -l1  insert as comments in output file *
  362.      -l2  display source on screen as compile progresses *
  363.      -n   set noboot flag
  364.      -o   optimize for size over speed
  365.      -p   pause on errors
  366.  
  367.  
  368. * only one of these may be specified
  369.  
  370.  
  371.  
  372. COMPILING THE COMPILER
  373.  
  374. Compiling the compiler is no different then compiling any other c 
  375. program.  What is different than normal is the linking procedure. 
  376. The file RDRTL.REL (ReDirectable Run Time Library) must be linked 
  377. first  to ensure that module satisfies its entry points prior  to 
  378. searching CLIB.REL.
  379.  
  380. The submit file CCCC.SUB provides an example of proper compiling, 
  381. assembling and linking of of this compiler. It's the one I use.
  382.  
  383.  
  384.  
  385. SETTING UP A COMPILER DISK
  386.  
  387. Four submit files are included with the source,  CCM.SUB, CCR.SUB 
  388. CCC.SUB  and  RCC.SUB.   These  files  will  produce  m80  source 
  389. files(.mac), l80 source files(.rel) and a final object file(.com) 
  390. without or with redirectable output,  respectively.  The user  is 
  391. encouraged  to  examine and/or modify these files to meet his  or 
  392. her own particular needs.
  393.  
  394.  
  395. 1    Obtain a print out of this file (CC.DOC)
  396.  
  397. 2     Initialize two disks.  One at the same capacity of  this 
  398.         disk  (the  working disk) and the other  at  the  maximum 
  399.         capacity of your system (the C disk).
  400.  
  401. 3     Copy the original disk to the working disk and store the 
  402.         original away for safe keeping.
  403.  
  404. 4       Sysgen your C disk, then install PIP (or SWEEP), M80, L80,
  405.         STAT, SUBMIT, and your current Editor.
  406.  
  407. 5       Place this disk in Drive A and Warm Boot then PIP or SWEEP
  408.         the follow files from the working disk to the C disk.
  409.  
  410.          STDIO.H          Header File
  411.          CC.COM              Small C Compiler
  412.          CC.DOC           This file
  413.          CLIB.REL         C I/O Library
  414.          RDRTL.REL        Redirectable Output Library
  415.          CCM.SUB          Submit file to produce .MAC file
  416.          CCR.SUB          Submit file to produce .REL file
  417.          CCC.SUB          Submit file to produce .COM file
  418.          RCC.SUB          Submit file to produce .COM file
  419.                           but links in the redirect lib first
  420.  
  421.         You now have a working C Compiler Disk. Type in and enter
  422.         <STAT *.* $R/O> to prevent inadvertent erasures.
  423.  
  424. 6       PIP or SWEEP one or more of the C source files to the
  425.         C disk.
  426.  
  427.          FA.C       File Append Prog.
  428.          FB.C       File Copy Prog. (Binary or Ascii)
  429.          FC.C       File Copy Prog. (Ascii)
  430.          FM.C       File Mod Prog.
  431.          CAT.C      File Concatenate Prog.
  432.          FFD.C      Formfeed Prog.
  433.          HELLO.C    You gotta know this one.
  434.          ARGS.C     Example Argument Passing Prog.
  435.          ERATOS.C   Eratos Prime Number Sieve Prog.
  436.          TIME.C     Xerox 820 Time Set/Display Prog.
  437.          UW.C       File Un-Wordstar Prog.
  438.          WC.C       Word Count Prog. (use -i switch)
  439.  
  440. 7       Type in and enter <SUBMIT CCC ERATOS> (or any source file)
  441.  
  442.         The Eratos Benchmark will compile before your very eyes.
  443.         After the CP/M prompt returns, Type in and enter "ERATOS".
  444.         Neat huh ?
  445.  
  446. 8       Have at it. Review the doc files supplied as well as the
  447.         manual written by J. E. Hendrix.
  448.  
  449. 9       This Version of the C Compiler is offered free of charge
  450.         for non commercial use. However, donations are accepted 
  451.         and will be divided to compensate this author as well as
  452.         the original to furthur the development of this compiler.
  453.         If there are any questions or problems regarding the use
  454.         of this version, please contact me. Address comments,
  455.         criticism, or suggestions to
  456.  
  457.                         Fred A. Scacchitti
  458.                         25 Glenview Lane
  459.                         Rochester, NY
  460.                         14609
  461.