home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / SIMTEL / CPMUG / CPMUG048.ARK / BDS-C.DOC < prev    next >
Text File  |  1984-04-29  |  17KB  |  395 lines
  1.       **********************************************************
  2.       *                               *
  3.       *      The BD Software C Compiler v1.41    10/9/80    *
  4.       *                               *
  5.       *      written by:      Leor Zolman               *
  6.       *              BD Software               *
  7.       *              173 Hampshire st. #2           *
  8.       *              Cambridge, Mass. 02139       *
  9.       *              (617) 492-3038 evenings       *
  10.       *                               *
  11.       **********************************************************
  12.  
  13. This  flier  represents most of the BDS C Handbook that comes with each copy of
  14. the compiler (in  addition to the User's Guide). The BDS C package is available
  15. only from:
  16.  
  17.     Lifeboat Associates        Price: $145 on 8" CP/M disks;
  18.         1651 Third Ave.                 Contact Lifeboat for the
  19.         New York, NY 10028              prices on other formats.
  20.         (212) 860-0300
  21.  
  22. There is NO restriction  on  use  of COM files generated by the BDS C Compiler;
  23. Users are free to place such items on the market without paying any royalty for
  24. use of run-time routines provided with the compiler package.  
  25.  
  26.  
  27. The  main  components  of the BDS C package  are:  four  executable  COM  files
  28. (CC1.COM,  CC2.COM,  CLINK.COM   and  CLIB.COM),  two  standard  library  files
  29. (DEFF.CRL  and  DEFF2.CRL),  and  a  run-time   package   module  (C.CCC).  For
  30. customization  purposes,  sources  are  provided  for C.CCC (CCC.ASM)  and  all
  31. library functions written in assembler (DEFF2.ASM and  DEFF2A.ASM).   There are
  32. also various sample source programs and utility packages included.  
  33.  
  34. A description of each follows:  
  35.  
  36.  
  37. CC1:      The  first  phase  of the compiler: accepts a C source file with  any
  38.           filename and extension  (say,  "foo.c") and produces a temporary file
  39.       containing a symbol table and an encoded form of the source code.  By
  40.       default, CC1 leaves the temporary file in ram and attempts to load in
  41.       the next phase of the compiler (CC2)    from  the  currently  logged in
  42.       disk    (unless  errors  occur);  see the"-a" option below for control
  43.       details.
  44.  
  45.       The file extension".C" is NOT assumed  for  the source file name, so
  46.       saying"foo" when you mean "foo.c" would not work.  
  47.  
  48.       If the source file name is preceded by a disk  designation,  then the
  49.       input is taken from the specified disk, and the output (if no errors)
  50.       is written to that disk.
  51.  
  52.       Following  the  name of the source file on the command line, you  may
  53.       specify a list of options, each"optionally" preceded by a dash.  
  54.  
  55.       The recognized options are:
  56.  
  57.  
  58.       -o      causes  speed-optimization   to   be     performed  instead  of
  59.           space-optimization. I.e., causes the final  generated code to
  60.           be longer but faster.  Will ONLY work if CC2    is  auto-loaded
  61.           by CC1.
  62.  
  63.       -p      causes  the  result  of the preprocessor phase of compilation
  64.           (i.e., the result of #define and #include text substitutions)
  65.           to be written to the CP/M  console output, with lines numbers
  66.           generated. If you type a control-P  before  hitting return on
  67.           the command line, output will also go to the list device.
  68.  
  69.       -e xxxx Specifies an explicit, absolute address for the external data
  70.           area, letting the compiler generate direct loads  and  stores
  71.           (using"lhld"  and "shld") for external variables. Will ONLY
  72.           work if CC2 is auto-loaded by CC1.
  73.  
  74.       -m xxxx Specifies the starting  address of C.CCC package at run-time.
  75.           Normally (under CP/M) this  defaults    to the base of the TPA;
  76.           use -m when generating code for a customized environment. See
  77.           the"CRL Format" section of the User's  Guide  for details on
  78.           customization. Will ONLY work if CC2 is auto-loaded  by  CC1.
  79.  
  80.       -r n      Reserves nK bytes for the symbol table.  Default value for  n
  81.           is  8 (6 for 4200h-based versions.) Minimum symbol table size
  82.           is 5K.
  83.  
  84.       -a x      Causes  CC2.COM to be auto-loaded from disk x, where x may be
  85.         "a", "b",  "c",  etc...or  "z"  to  force  a  .CCI file to be
  86.           written to disk (under control of the "-d" option below.) 
  87.  
  88.           You'd  use  this  option  when the disk on which your  BDS  C
  89.           commands reside is NOT the  currently  logged  disk;    In  the
  90.           absence  of  this  option,  CC1  will auto- load CC2 from the
  91.           currently logged disk.
  92.  
  93.       -d x      Specifies to which disk the .CRL file  output of the compiler
  94.           is  to  be written. The default is the disk  from  which  the
  95.           source was taken. Again, x can be"a", "b", "c", etc.  
  96.  
  97.           If auto-loading  of CC2 is not performed (i.e., if the"-a z"
  98.           option is used), then  this  option  controls  which disk the
  99.           .CCI file output is to be written to. 
  100.  
  101.       -c      Disables the comment-nesting feature; When this is used, then
  102.           the  first"*/"  after  any  "/*" is encountered closes  the
  103.           comment. If"-c" is NOT used, then  each  occurence  of  "/*"
  104.           requires  a  matching "*/"  before  a  comment is considered
  105.           terminated.
  106.         
  107.       On a 2 MHz 8080,  processing    speed  (not  counting  disk waiting) is
  108.       about 15 lines of source/second.  On a 4 MHz Z80, speed  is  about 35
  109.       lines/sec.
  110.  
  111.  
  112. CC2:      This    is the second phase of the compiler. CC2 accepts a".CCI"  file
  113.       as input,  and  writes  out  a".CRL" file if no errors are detected.
  114.       (CRL    is  mnemonic  for  'C  ReLocatable'.)    Normally   CC2.COM   is
  115.       automatically loaded in (by CC1) and operates on the CCI file left in
  116.       memory  by  CC1;  If invoked explicitly, then the .CCI file is loaded
  117.       from disk.
  118.  
  119.       If all goes well, writing out of the CRL file is followed by deletion
  120.       of the"CCI" file (if it exits), and compilation is complete.  
  121.  
  122.       On an 8080, execution  speed    =  about 35 lines/sec.    On a 4 MHz Z80,
  123.       speed is about 90 lines/sec.    
  124.  
  125.  
  126. CLINK:      This program links a"main" function  from  a  given CRL file in with
  127.       C.CCC  (for common system subroutines) and any subordinate  functions
  128.       which "main" may require (from perhaps many CRL files).  Alternately,
  129.       CLINK may  be  used to prepare a code segment which can be swapped in
  130.       at run time by the root module.
  131.  
  132.       A successful linkage    causes    a".COM" file to be generated, at which
  133.       point the 8080 absolute machine  code  file  is  ready to be executed
  134.       (for better or worse) as a transient command by CP/M    (or  swapped in
  135.       by another COM file.) 
  136.  
  137.       The first argument on the command line must be the name of a CRL file
  138.       containing   a"main"  function;  it  may  be  preceded  by  a  disk
  139.       designation, to  state where all .CRL files (except DEFF*.CRL) are to
  140.       be searched for if further disk designators are omitted.
  141.  
  142.       Any other CRL files  to  search  may also be specified on the command
  143.       line (WITHOUT their".CRL" extensions),  causing  them to be searched
  144.       in the order specified.  The default disk to search  will be the same
  145.       disk from which the original CRL file was taken; this  default can be
  146.       overridden  by  specifying  an  explicit  disk  designation  for  any
  147.       appropriate CRL file name needing it. For example,
  148.     
  149.           A>clink c:foo bar a:zot fraz
  150.  
  151.       causes  disk    C  to  be  searched  for the files FOO.CRL, BAR.CRL and
  152.       FRAZ.CRL, and disk A to be searched to find ZOT.CRL. Note that C.CCC,
  153.       DEFF.CRL and DEFF2.CRL are expected to reside on the currently-logged
  154.       disk, unless the -c option is used (see below.)
  155.  
  156.       After  all  given  CRL  files have been  searched  once,  CLINK  will
  157.       automatically search DEFF.CRL and then DEFF2.CRL.
  158.  
  159.       If there are still some unresolved  references,  then  CLINK will ask
  160.       for input from the keyboard to try resolving them. This  situation is
  161.       likely  to arise in the case where a function becomes "needed"  AFTER
  162.       the CRL file    containing  it    has already been searched. When yanking
  163.       functions out of a CRL file, CLINK  will  only  take    those which are
  164.       already known to be needed (due to a prior reference.)  Thus, it will
  165.       save you some pain to order the CRL filenames on the command    line in
  166.       such    a  way    as to minimize undefined backward references. This ONLY
  167.       applies to multiple CRL files; the order of functions within a single
  168.       CRL file makes no difference. 
  169.  
  170.       There are several options which may be specified on the CLINK command
  171.       line. Each option  must  be preceded by a dash (-); the space between
  172.       options and their argument (if needed) is optional.
  173.  
  174.       The presently supported options are:    
  175.  
  176.         -s        Prints out load statistics. 
  177.  
  178.         -d ["args"] Use this to run the code immediately after linking,
  179.                 for debugging  purposes,  instead  of writing a COM
  180.                 file  out  to disk.  If a quoted string  is  given,
  181.                 then that string  is  treated  as a list of command
  182.                 line  arguments  and  is  passed to  the  executing
  183.                 program as if via the CCP.    
  184.  
  185.         -t nnnn     Reserves location nnnn (hex)  and  above  for user;
  186.                 default  is  to  reserve no space. What this really
  187.                 does is to cause the first op in the object file to
  188.                 become
  189.             
  190.                     lxi sp,nnnn
  191.  
  192.                 instead of the usual
  193.             
  194.                     lhld BASE+6
  195.                     sphl
  196.  
  197.  
  198.         -o name     Causes the .COM file generated to
  199.        (or) -o name.    be called"name.COM", "name" or 
  200.        (or) -o name.ext"name.ext" respectively.  If  omitted,  the name of
  201.                 the "main" .CRL file is used by default,  with  the
  202.                 extension".COM".  
  203.  
  204.                 The  name may also have a disk designator to direct
  205.                 the output    to  any  disk  (in  lieu of the special
  206.                 extension code on the"main" CRL  filename).  If  a
  207.                 disk designator ALONE is given (e.g.,"-o b:") then
  208.                 the  output  is  directed  to  the    specified  disk
  209.                 without affecting the filename.
  210.  
  211.  
  212.         -e xxxx     Sets  start  of  data  area  to  address  xxxx,  to
  213.                 maintain  consistency between several separate .COM
  214.                 files  when  chaining  (via  the  library  function
  215.             "exec")  is  used  and  external  data  need  to be
  216.                 shared.    If  the    program  will  be  swapping  in
  217.                 segments, then the value given MUST BE GREATER THAN
  218.                 THE  HIGHEST  ADDRESS THAT WILL EVER BE OCCUPIED BY
  219.                 SWAPPED-IN CODE.    Note  that  the "Stack  space"
  220.                 statistic,    printed  upon completion of linkage  if
  221.             "-s" is given, may be incorrect when this option is
  222.                 used.
  223.  
  224.         -c x        Tells CLINK to obtain the files C.CCC, DEFF.CRL and
  225.                 DEFF2.CRL from disk "x".  By  default,  these files
  226.                 are assumed to reside on the currently logged disk.
  227.  
  228.         -y name     Yanks  in  the  symbol  table file"name.SYM"  from
  229.                 disk, and defines all the  symbols    found  therein.
  230.                 This  is  used when linking an overlay segment,  to
  231.                 pre-define    the  function addresses resident in the
  232.                 root node and accessible by the segment. See the -w
  233.                 option below.
  234.  
  235.         -w        Causes a SID-compatible  symbol  table  file  to be
  236.                 written  to  disk for use either by SID or by CLINK
  237.                 later on when  linking overlay segments (see the -y
  238.                 option above.)
  239.  
  240.         -v        Specifies that the    resultant  COM    file  is  to be
  241.                 swapped in as an overlay segment by another command
  242.                 at run time, so the run-time package (C.CCC) is not
  243.                 linked  into the code. The"-l" (letter ell) option
  244.                 should always  be  used  with"-v". Note that this
  245.                 option  replaces  the awkward"foo.aaS"  scheme  of
  246.                 previous versions.    
  247.  
  248.         -l xxxx     (letter ell) Sets the  starting  (load)  address of
  249.                 the generated code. Normally, this defaults  to the
  250.                 base of the TPA; If used with the"-v" option, this
  251.                 generates  an overlay segment to load in at address
  252.                 xxxx. If the"-v"  option  is  not given, then the
  253.                 run-time package (C.CCC) must have    been previously
  254.                 re-assembled  to  run at location xxxx  (since  the
  255.                 run-time package always  resides at the base of the
  256.                 root segment.) For detailed info on generating code
  257.                 to run at an arbitrary starting  address  and/or to
  258.                 be    ROMable,  see  the"CRL Format" section of  the
  259.                 User's Guide.
  260.  
  261.         -r xxxx     Reserve xxxx bytes (in  HEX) for the internal CLINK
  262.                 forward function reference table.  This table's not
  263.                 being big enough (and my  faulty  tests  for  table
  264.                 overflow)  were  responsible  for  CLINK's previous
  265.                 tendency  to  crash  on  big linkages. While  CLINK
  266.                 won't crash anymore, it may  give  you a"Ref table
  267.                             overflow"  message and quit; if this  happens,  use
  268.                 this option  with  an argument larger than the 600h
  269.                 default for regular  CP/M,    or the 400h default for
  270.                 4200h-based  CP/M  systems, to  enlarge  the  table
  271.                 area. Of course, this  reduces  the space available
  272.                 for linked code...if CLINK gives  you  an"Out  of
  273.                             memory"  message, use the "-r" option to reduce the
  274.                 reserved table  space  and provide more code space.
  275.                 Chances are, though, that  you  won't  be  able  to
  276.                 reduce  the  table space by much before running out
  277.                 of it. Time for overlays... 
  278.  
  279.  
  280. CLIB:      This program    maintains .CRL files, allows transfer of functions from
  281.       one CRL file to another, etc. To invoke CLIB, just type
  282.     
  283.           A>clib
  284.  
  285.       CLIB will print a line such as
  286.     
  287.           Function buffer size = nnnnn
  288.  
  289.       specifying the  largest function size that can be handled. Attempting
  290.       to"transfer" or  "extract" a function larger than this size could be
  291.       destructive.    
  292.  
  293.       Next CLIB will prompt  with a "*". Typing "h" at this point will give
  294.       you a command summary.
  295.  
  296.       Basically, you work CLIB  by opening one to six CRL files (which then
  297.       become associated with"file  numbers"),  diddling  the files to your
  298.       hearts  content,  closing  all  files which you altered,  and  typing
  299.       control-C.
  300.  
  301.       The old version of any CRL file you  change  with  CLIB is renamed to
  302.       name.BRL (for Backup ReLative).
  303.  
  304.       A sample session of CLIB to, say, transfer the functions named"FOO",
  305.     "BAR", and "ZOT" from a CRL file named "DSSR" on disk B: to one named
  306.     "RTS" on disk A: would go as follows:  
  307.         
  308.           A>clib
  309.           BD Sofware C Librarian v1.4
  310.           Function buffer size = xxxxx bytes
  311.           * open 0 b:dssr
  312.           * open 1 rts
  313.           * t 0 1 foo
  314.           * t 0 1 bar
  315.           * t 0 1 zot
  316.           * c 1
  317.           * ^C
  318.         
  319.           A> ...
  320.  
  321.         
  322.       The"open" commands prepare to do work on a .CRL file,  and associate
  323.       each    .CRL  file opened with a digit (0-9).  The"transfer"  commands
  324.       tell CLIB to    transfer  the named function from the first file (named
  325.       by file #) to the second  file  (also  named by number).  The "close"
  326.       command need only be given for files which  have  been altered; since
  327.       DSSR    wasn't written to in the above example, it didn't  need  to  be
  328.       closed, but RTS did need to be closed.
  329.  
  330.  
  331. DEFF.CRL: Contains all compiled functions from STDLIB1.C and  STDLIB2.C.    See
  332.       the  BDS C User's Guide, STDLIB1.C and STDLIB2.C for documentation on
  333.       these functions.
  334.  
  335.  
  336. DEFF2.CRL: Contains  all  library  functions  coded  in  assembly language; the
  337.       sources to all of these functions (except"fp")  are in DEFF2.ASM and
  338.       DEFF2A.ASM.
  339.  
  340.  
  341. C.CCC:      The run-time package, containing code for processing the command line
  342.       (generating argc and argv, for you Unix [1] lovers),    room  for  file
  343.       I/O  buffers,  some  math subroutines, etc.  This run-time package is
  344.       always linked in at the beginning of root segment COM files generated
  345.       by CLINK. The source to C.CCC is CCC.ASM.
  346.  
  347.  
  348. OTHER THINGS YOU GET WITH THE PACKAGE:    
  349.  
  350. STDLIB1.C    Source    for  library  functions  which    are  written  in  C and
  351.         present, in compiled form, within DEFF.CRL.
  352.  
  353. STDLIB2.C    More DEFF.CRL library function sources. 
  354.  
  355. OTHELLO.C    Game  program.    Serves    as  a  good  example of modular coding,
  356.         passing  arrays  as  arguments to functions,  and  the    "qsort"
  357.         library function.
  358.  
  359. RALLY.C     Arcade game, for H19 terminal only  (uses  files  RALLY.MAP and
  360.         R2.MAP).
  361.  
  362. PPONG.C     Polish Pong, for the H19. Very interesting little hack. 
  363.  
  364. TELNET.C    Program  to  let  a  system  be  used as a terminal, optionally
  365.         routing  stuff    from  modem  to  disk  and  vice-  versa.  Nice
  366.         hanshaking and check- summing features. Hairy but useful.
  367.  
  368. CONVERT.C    Converts unprintable characters (for systems  having upper-case
  369.         only  and/or  incomplete  special  symbol  set)  into    special
  370.         2-character  sequences    beginning  with  the character '#'. See
  371.         also CC0T.C
  372.  
  373. CC0T.C        Converts  C  source  files  containing    the  special  sequences
  374.         generated by the CONVERT program back into a form  that  can be
  375.         compiled.
  376.  
  377. FLOAT.DOC,    Bob Mathias's contributed floating
  378. FLOAT.C     point    package  (uses    the"fp"  function  which  resides  in
  379.         DEFF2.CRL.)
  380.  
  381. FLOATSUM.C    Sample program using the floating point package.
  382.  
  383. CMAC.LIB,    Macro package  for  use  with  Digital    Research's"mac" macro
  384.         assembler   to     create  CRL  files  painlessly  from  assembly
  385.         programs.
  386.  
  387. CCC.ASM     Source to the C.CCC run-time package.
  388.  
  389. DEFF2.ASM      Source to the machine-language  library  functions.  Uses the
  390.         CMAC.LIB  macro  package, requiring Digital Research's MAC  for
  391.         assembly.
  392. DEFF2A.ASM      More of the above
  393.  
  394. BDS.LIB     Global header file for FNS.ASM. 
  395.