home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c120 / 2.ddi / DCPP.DOC < prev    next >
Encoding:
Text File  |  1990-01-12  |  13.2 KB  |  355 lines
  1.     MS-DOS specific implementation information for DECUS C Preprocessor
  2.                 December, 1985
  3.  
  4.     CPP is the DECUS C Preprocessor, as implemented by Martin Minow.
  5. The version in this library has been modified from the net.sources release
  6. to support the Lattice and Microsoft C compilers for MS-DOS.   Modifications
  7. include the ability to search for system header files in the directory
  8. "\INCLUDE", the ability to search one directory specified in the environment
  9. variable "INCLUDE" (See the MS-DOS INCLUDE command for information on
  10. setting environment variables), and the ability to deal with MS-DOS
  11. memory models.
  12.  
  13. To select the memory model, use the '-M<model>' command line switch, where
  14. <model> is one character as specified below.   The following memory models
  15. are supported:
  16.  
  17. Model    Compiler    sizeof (data *)       sizeof (func *)   Predefines
  18.    s     Lattice        2        2         I8086S
  19.      Microsoft                         SPTR
  20.                                  M_I86SM
  21.                                  M_I86
  22.                                  I8086
  23.                                  MSDOS
  24.  
  25.    p     Lattice        2        2         I8086P
  26.                                  SPTR
  27.                                  I8086
  28.                                  MSDOS
  29.  
  30.    d     Lattice        4               4         I8086D
  31.                                  LPTR
  32.                                  I8086
  33.                                  MSDOS
  34.  
  35.    m     Microsoft        2        4         M_I86MM
  36.                                  M_I86
  37.                                  MSDOS
  38.  
  39.    l     Lattice        4        4         I8086L
  40.                                  LPTR
  41.                                  M_I86LM
  42.                                  M_I86
  43.                                  I8086
  44.                                  MSDOS
  45.  
  46.     The preprocessor predefinition SS_NE_DS under Microsoft C is not
  47. supported, and must be supplied by the user via the -D<idname> option if
  48. desired.   Where the memory model implies the compiler, only those symbols
  49. which that compiler normally predefines are predefined.   The S and L models
  50. are the same in the Microsoft and Lattice compilers, and therefore the
  51. symbols for both compilers must be defined.
  52.  
  53. The version of the C Preprocessor we are distributing compiles under the
  54. Microsoft C compiler.   It is likely that the only problems with bringing it
  55. up under Lattice would be the lack of the UNIX library function ctime()
  56. and the #define MACHINE <stuff> line in the MS-DOS definitions.
  57. The ctime() function problem can be fixed by defining OK_DATE to be FALSE.
  58. Alternatively, the user can make their own.   The other definition can
  59. be gotten around by taking out the carriage returns, at the expense of
  60. code readability.   If necessary, some of the names in the MACHINE
  61. definition may be moved to the SYSTEM definition, but this is not really
  62. kosher to purists like ourselves.
  63.  
  64.     DECUS C is a creation of DEC employees who wanted a C compiler on
  65. DEC machines, particularly the PDP-11 class machines.  It is entirely in the
  66. public domain; general permission to use and distribute the software has been
  67. granted, provided that it is distributed free of charge.  No profit-making
  68. schemes allowed!
  69.  
  70. The Lattice C and Microsoft C compiler modifications for MS-DOS are not part
  71. of the DECUS C Preprocessor distribution yet, but we are in the process of
  72. sending them back to the source.
  73.  
  74.         - Ted Lemon and Jym Dyer
  75.             December, 1985
  76.  
  77.  
  78. CPP DOCUMENTATION:
  79.  
  80.  
  81. HEADER:         CUG243;
  82. TITLE:          DECUS C Preprocessor;
  83. DATE:           12/30/85;
  84. VERSION:
  85. DESCRIPTION:   "C Preprocessor implemented by Martin Minow -- Main program";
  86. KEYWORDS:       C preprocessor, C compiler;
  87. SYSTEM:         MS-DOS;
  88. FILENAME:       CPP1.C;
  89. WARNINGS:      ""
  90. AUTHORS:        Ted Lemon and Jym Dyer; 
  91. COMPILERS:      Lattice C V2.00 or Microsoft C V3.00;
  92. REFERENCES:     ;
  93. ENDREF
  94.  
  95.  
  96. title   cpp             C Pre-Processor
  97. index                   C pre-processor
  98.  
  99. synopsis
  100.         
  101.         cpp [-options] [infile [outfile]]
  102.         
  103. description
  104.  
  105.         CPP reads a C source file, expands macros and include
  106.         files, and writes an input file for the C compiler.
  107.         If no file arguments are given, CPP reads from stdin
  108.         and writes to stdout.  If one file argument is given,
  109.         it will define the input file, while two file arguments
  110.         define both input and output files.  The file name "-"
  111.         is a synonym for stdin or stdout as appropriate.
  112.  
  113.         The following options are supported.  Options may
  114.         be given in either case.
  115.  
  116.  
  117.         -C              If set, source-file comments are written
  118.         to the output file.  This allows the output of CPP to be
  119.         used as the input to a program, such as lint, that expects
  120.         commands embedded in specially-formatted comments.
  121.  
  122.         -Dname=value    Define the name as if the programmer wrote
  123.  
  124.             #define name value
  125.  
  126.         at the start of the first file.  If "=value" is not
  127.         given, a value of "1" will be used.
  128.  
  129.         On non-unix systems, all alphabetic text will be forced
  130.         to upper-case.
  131.  
  132.         -E              Always return "success" to the operating
  133.         system, even if errors were detected.  Note that some fatal
  134.         errors, such as a missing #include file, will terminate
  135.         CPP, returning "failure" even if the -E option is given.
  136.  
  137.         -Idirectory     Add this directory to the list of
  138.         directories searched for #include "..." and #include <...>
  139.         commands.  Note that there is no space between the
  140.         "-I" and the directory string.  More than one -I command
  141.         is permitted.  On non-Unix systems "directory" is forced
  142.         to upper-case.
  143.  
  144.         -N              CPP normally predefines some symbols defining
  145.         the target computer and operating system.  If -N is specified,
  146.         no symbols will be predefined.  If -N -N is specified, the
  147.         "always present" symbols, __LINE__, __FILE__, and __DATE__
  148.         are not defined.
  149.  
  150.         -P              CPP normally writes lines of the form
  151.         #line <number> <file.name> to the output file so the compiler
  152.         can print the line number and name of the original source file
  153.         for diagnostic messages.  The -P option will suppress this output.
  154.  
  155.         -Stext          CPP normally assumes that the size of
  156.         the target computer's basic variable types is the same as the size
  157.         of these types of the host computer.  (This can be overridden
  158.         when CPP is compiled, however.)  The -S option allows dynamic
  159.         respecification of these values.  "text" is a string of
  160.         numbers, separated by commas, that specifies correct sizes.
  161.         The sizes must be specified in the exact order:
  162.  
  163.             char short int long float double
  164.  
  165.         If you specify the option as "-S*text", pointers to these
  166.         types will be specified.  -S* takes one additional argument
  167.         for pointer to function (e.g. int (*)())
  168.  
  169.         For example, to specify sizes appropriate for a PDP-11,
  170.         you would write:
  171.  
  172.                c s i l f d func
  173.              -S1,2,2,2,4,8,
  174.             -S*2,2,2,2,2,2,2
  175.  
  176.         Note that all values must be specified.
  177.  
  178.         -Tnumber        Enable (number = 1) or disable
  179.         trigraph recognition.  (If no number is given, the
  180.         default state is reversed.)  If enabled, the sequence
  181.         "??" is a character-escape to allow certain characters
  182.         to be entered on systems where the normal representation
  183.         is used for national letters.  This implementation
  184.         "merely" converts the trigraph to the internal representation,
  185.         and thus is probably incorrect.  A correct implementation
  186.         would seem to require recognition of Ansi escape sequences
  187.         in the input stream.  Someone else can write that routine.
  188.  
  189.         -Uname          Undefine the name as if
  190.  
  191.             #undef name
  192.  
  193.         were given.  On non-Unix systems, "name" will be forced to
  194.         upper-case.
  195.  
  196.         -Xnumber        Enable debugging code.  If no value is
  197.         given, a value of 1 will be used.  (For maintenence of
  198.         CPP only.)
  199.         
  200.  
  201. Pre-Defined Variables
  202.  
  203.         When CPP begins processing, the following variables will
  204.         have been defined (unless the -N option is specified):
  205.         
  206.         Target computer (as appropriate):
  207.         
  208.             pdp11, vax, M68000 m68000 m68k
  209.         
  210.         Target operating system (as appropriate):
  211.         
  212.             rsx, rt11, vms, unix
  213.         
  214.         Target compiler (as appropriate):
  215.         
  216.             decus, vax11c
  217.         
  218.         The implementor may add definitions to this list.
  219.         The default definitions match the definition of the
  220.         host computer, operating system, and C compiler.
  221.         
  222.         The following are always available unless undefined (or
  223.         -N was specified twice):
  224.  
  225.         __FILE__        The input (or #include) file being compiled
  226.         (as a quoted string).
  227.         
  228.         __LINE__        The line number being compiled.
  229.         
  230.         __DATE__        The date and time of compilation as
  231.         a Unix ctime quoted string (the trailing newline is removed).
  232.         Thus,
  233.         
  234.             printf("Bug at line %s,", __LINE__);
  235.             printf(" source file %s", __FILE__);
  236.             printf(" compiled on %s", __DATE__);
  237.         
  238.  
  239. Draft Proposed Ansi Standard Considerations
  240.  
  241.         The current version of the Draft Proposed Standard
  242.         explicitly states that "readers are requested not to specify
  243.         or claim conformance to this draft."  Readers and users
  244.         of Decus CPP should not assume that Decus CPP conforms
  245.         to the standard, or that it will conform to the actual
  246.         C Language Standard.
  247.  
  248.         When CPP is itself compiled, many features of the Draft
  249.         Proposed Standard that are incompatible with existing
  250.         preprocessors may be disabled.  See the comments in CPP's
  251.         source for details.
  252.  
  253.         The latest version of the Draft Proposed Standard (as reflected
  254.         in Decus CPP) is dated November 12, 1984.  A few things from
  255.         later drafts are included.
  256.  
  257.         Comments are removed from the input text.  The comment
  258.         is replaced by a single space character.  The -C option
  259.         preserves comments, writing them to the output file.
  260.  
  261.         The '$' character is considered to be a letter.  This is
  262.         a permitted extension.
  263.  
  264.         The following new features of C are processed by CPP:
  265.  
  266.         #elif expression    (#else #if)
  267.         '\xNNN'             (Hexadecimal constant)
  268.         '\a'                (Ascii BELL)
  269.         '\v'                (Ascii Vertical Tab)
  270.         #if defined NAME    1 if defined, 0 if not
  271.         #if defined (NAME)  1 if defined, 0 if not
  272.         #if sizeof (basic type)
  273.         unary +
  274.         123U, 123LU         Unsigned ints and longs.
  275.         12.3L               Long double numbers
  276.         #token              Stringize token
  277.         token##token        Token concatenation
  278.         #include token      Expands to filename
  279.  
  280.         The proposed national replacement letter fallbacks, using
  281.         "??", have not been implemented.
  282.  
  283.         The Draft Proposed Standard has extended C, adding a constant
  284.         string concatenation operator, where
  285.  
  286.             "foo" "bar"
  287.  
  288.         is regarded as the single string "foobar".  (This does not
  289.         affect CPP's processing but does permit a limited form of
  290.         macro argument substitution into strings as will be discussed.)
  291.  
  292.         The Standard Committee plans to add token concatenation
  293.         to #define command lines.  One suggested implementation
  294.         is as follows:  the sequence "Token1##Token2" is treated
  295.         as if the programmer wrote "Token1Token2".  This could
  296.         be used as follows:
  297.  
  298.             #line 123
  299.             #define ATLINE foo##__LINE__
  300.  
  301.         ATLINE would be defined as foo123.
  302.  
  303.         Note that "Token2" must either have the format of an
  304.         identifier or be a string of digits.  Thus, the string
  305.  
  306.             #define ATLINE foo##1x3
  307.  
  308.         generates two tokens: "foo1" and "x3".
  309.  
  310.         If the tokens T1 and T2 are concatenated into T3,
  311.         this implementation operates as follows:
  312.  
  313.           1. Expand T1 if it is a macro.
  314.           2. Expand T2 if it is a macro.
  315.           3. Join the tokens, forming T3.
  316.           4. Output T3 (without reexpansion).
  317.  
  318.         As implemented here, ## left-associates.  I.e., a##b##c
  319.         is effectively (a##b)##c.  Cpp can be compiled so as
  320.         to re-expand the constructed macro.
  321.  
  322.         A macro formal parameter will be substituted into a string
  323.         or character constant if it is preceded by a single #.
  324.  
  325.             #define VECSIZE 123
  326.             #define vprint(name, size) \
  327.               printf("name" "[" #size "] = {\n")
  328.               ... vprint(vector, VECSIZE);
  329.  
  330.         expands (effectively) to
  331.  
  332.               vprint("vector[123] = {\n");
  333.  
  334.         Note that this will be useful if your C compiler supports
  335.         the new string concatenation operation noted above.
  336.  
  337. error messages
  338.  
  339.         Many.  CPP prints warning or error messages if you try to
  340.         use multiple-byte character constants (non-transportable)
  341.         if you #undef a symbol that was not defined, or if your
  342.         program has potentially nested comments.
  343. author
  344.         Martin Minow
  345. bugs
  346.         The #if expression processor uses signed integers only.
  347.         I.e, #if 0xFFFFu < 0 may be TRUE.
  348.  
  349.         A / at the end of a macro expansion will not introduce
  350.         a comment:
  351.  
  352.             #define foo /
  353.                 foo* this is not a comment */
  354.  
  355.