home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / prog / c / pdc.lzh / File9 < prev    next >
Text File  |  1991-08-04  |  6KB  |  158 lines
  1. cc.doc    [latest change - 16Jul88 by Jal]
  2.  
  3. ABSTRACT
  4.  
  5.     cc is a smart front end that recognises the type of file from
  6. the suffix, and will invoke the necessary programs for you to produce an
  7. executable module.  With cc you can in one command preprocess the source
  8. code, compile the result to assembler, assemble and link the resulting
  9. object module with the pdc library and Amiga.lib.
  10.  
  11.  
  12. SYNOPSIS
  13.  
  14.     cc is a unix-like cc command that makes the usual compile,
  15. assemble and link stages a little friendlier.  For example, a runnable
  16. version of the "hello world" program called hello, whose source code is in
  17. a file called hello.c as shown below:
  18.  
  19.     /*hello.c*/
  20.     main()
  21.     {
  22.           printf("Hello World!\n");
  23.     }
  24.  
  25. could be made by typing the following at the CLI prompt:
  26.  
  27.  
  28.     1> cc hello.c
  29.  
  30. cc would automatically perform the following for you.
  31.  
  32.     o invoke the macro preprocessor Cpp on the file "hello.c".
  33.     o invoke the PDC C compiler on the preprocessed code.
  34.     o invoke the A68k assembler on the source code put out by PDC.
  35.     o invoke Blink to link the output of A68k with PDCStartup.obj
  36.       using Blink's option LIB PDC.lib ami.lib.
  37.     o The executable program will be called hello, and any
  38.       intermediate files will be deleted by cc.
  39.  
  40. COMMAND LINE OPTIONS:
  41.  
  42.     cc supports several command line options which can modify cc's
  43. behaviour,  change where certain files are searched for,  and define where
  44. temporary files are kept during compilation.  Options come in two flavours,
  45. switches and as parameters that take arguments.
  46.  
  47.   Switches appear by themselves on the line preceded by a minus sign.  "-S",
  48. and "-c" are two valid switch options.  It should be noted that upper and
  49. lower case letters are distinct.  "-O" and "-o" for example could represent
  50. different switch options. 
  51.  
  52.   Argument types are followed by an additional value optionally separated
  53. by a space.  For example, "-Idf0:include"  and "-I df0:include" are both
  54. valid argument options.  Here is the current list of options:
  55.  
  56.  
  57.     -S    "cc -S test.c" will invoke Cpp and the PDC compiler
  58.     -A    and leave the resulting assembler source in a file
  59.     -a    called  "test.s".
  60.  
  61.     -c    "cc -c test.c" or "cc -c test.a" will product an
  62.         object file test.o.  cc recognizes the first form as a
  63.         c program and will compile and assemble test.c.  The
  64.         second form is recognized an assembler program, and the
  65.         compile stage will be skipped.
  66.  
  67.     -V    will print out the command line passed to all programs
  68.         just before they are invoked.
  69.  
  70.     -D    used to define a macro variable just as though it had
  71.         been included in the source file.  For example, the
  72.         option "-D DEBUG=1" is identical to including the 
  73.         statement #define DEBUG 1 in your C source code.
  74.  
  75.         There are three macro variables that are predefined for
  76.         you -  "amiga", "m68000", and "pdc".  Although these are
  77.         defined as lower case in cc, there seems to be a bug in
  78.         the cpp preprocessor which changes the names to upper case.
  79.         These variables are useful for writing compiler-specific
  80.         code in your programs.
  81.  
  82.         There can be a maximum of 32 "-D var=1" defines. 
  83.  
  84.     -I    used to define additional directories where Cpp should
  85.         look for files you have #included.  For example,
  86.         "-I df0:include" would add the directory include on
  87.         drive df0: as one source to look for the standard I/O
  88.         header file "stdio.h".  Additional -I <file> options
  89.         can be specified as required to a maximum of 16.
  90.  
  91.         By default, "ram:include", and "PDC:include" will also
  92.         be searched in the order shown for any included files
  93.         not found in the specified libraries.
  94.  
  95.  
  96.     -l    defines additional libraries where Blink should look for
  97.         library modules to include in the link list.  If "-lc"
  98.         were specified, cc would look for a module ram:lib/c.lib,
  99.         and pdc.lib to link with the object code.  Note that the
  100.         .lib extension is tacked on to the name for you and you
  101.         should not include it on the command line.
  102.  
  103.         There are a maximum 16 libraries that can be specified on
  104.         one line. The libraries "-l pdc" and "-l Ami" have been
  105.         predefined for you.
  106.  
  107.     -o    use "-o name" to define the name of the resulting exec-
  108.         utable filename.  By default,  the name will be the first
  109.         module you specify on the command line, minus the suffix
  110.         if you do not over-ride it with this option.  For example,
  111.         cc hello.c would result in a runnable program called hello.
  112.  
  113.     -q    by default intermediate files will be kept in ram.  Use
  114.         the "-q ram:" option to over-ride this.
  115.  
  116.  
  117. DEFAULTS:
  118.  
  119. The following extensions have special meaning to cc:
  120.  
  121.     .c    A c source code file like hello.c above.
  122.     .s    An assembler source code file.
  123.     .a        "         ".
  124.     .o    An object file, the output of an assembler.
  125.  
  126.  
  127. cc will search in order, the current directory, ram:, and PDC:
  128. for several modules that it needs for execution, as well as for include
  129. libraries and object modules for the linker.  Here is a summary of where it
  130. expects to find things:
  131.  
  132. A68k, Cpp, PDC, and Blink:
  133.  
  134.     If not found in the current directory,     cc will search ram:c,
  135.     and PDC:c for these  modules.  If not found there, the  manx
  136.     version  of  cc will  search  any  paths  given by the AmigaDos path
  137.     command, and finally the "C:" directory.  The version compiled under
  138.     lattice however will only search the "C:" directory if the  required
  139.     program is not found by the above search.
  140.  
  141. Object Modules:
  142.  
  143.     cc generates the command:
  144.  
  145.      "Blink  PDCStartup.obj module.o  LIB PDC.lib Ami.lib".
  146.  
  147.     Both the modules  PDCStartup.obj, PDC.lib  and  Ami.lib  should
  148.     either be in the current directory, or in a directory called ram:lib,
  149.     or PDC:lib.
  150.  
  151.  
  152. Bugs (sigh):
  153.  
  154.     The only serious bug at this time is the inability to stop the
  155.     compile, assemble or link if an error is detected in a previous
  156.     stage.  I need to spend a little more time understanding Manx's
  157.     fexecv() function to trace this one down.
  158.