home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / languages / headergen / Doc next >
Text File  |  1995-06-23  |  10KB  |  240 lines
  1.  
  2.     HeaderGen 1.00
  3.  
  4.     Documentation
  5. ____________________________________________________________________________________
  6.  
  7.  
  8. HeaderGen is a coding tool for use with Acorn ANSI C and ObjAsm.
  9.  
  10. HeaderGen is (c) Frank Föhl. This version is PD and may be copied freely, as long as
  11. all files are included and unaltered.
  12.  
  13.  
  14.  
  15.  • Purpose:
  16.  
  17. Generate header files of C and Assembler source files, and convert Assembler sources
  18. to C headers as well as C headers to Assembler headers.
  19.  
  20.  
  21.  • Syntax:
  22.  
  23. HeaderGen -CtoC     [keyword args]  <C source>   <C header>
  24. HeaderGen -ASMtoASM [keyword args]  <ASM source> <ASM header>
  25. HeaderGen -ASMtoC   [keyword args]  <ASM source> <C header>
  26. HeaderGen -CtoASM   [keyword args]  <C header>   <ASM header>
  27.  
  28. Keyword options:
  29.  
  30. -ExtIdent <string>   Use <string> to identify external labels (with -ASMtoASM,-ASMtoC)
  31.                      or to identify external functions/variables (with -CtoC, -CtoASM)
  32. -I <dir>[,<dir>...]  Include <dir>s on the include file search path (with -CtoASM)
  33. -typedef             Declare 'typedef' structures explicitly (with -CtoASM)
  34.  
  35.  
  36.  
  37.  • Limitations
  38.  
  39. Parsing of C source files is not perfect (I haven't bothered to look up the syntax
  40. diagrams), but I think it's now fairly sufficient. If anything goes wrong with
  41. parsing C sources you will get errors or warnings from HeaderGen, as usual.
  42.  
  43. Bitfields are not supported.
  44.  
  45. HeaderGen has no C++ support.
  46.  
  47. Most preprocessor statements are ignored, only the #include's and #define's are
  48. recognized with the -CtoASM action (see below), the #define's only to a limited
  49. degree.
  50.  
  51. HeaderGen -CtoASM parses all Clib and RISC_OSlib headers fine (provided there's no
  52. C++ stuff contained), with the exceptions 'signal.h', 'kernel.h' and 'colourpick.h',
  53. which is mainly because a *very* odd syntax was used. :-)
  54.  
  55. The length of the words and syntax structures scanned in the input files is limited to
  56. 2048 characters, so there might be problems with very long character strings for
  57. example. You'll get a 'word overflow' error if this should occur. Identifiers are
  58. truncated to 256 characters.
  59.  
  60.  
  61.  • How to use HeaderGen
  62.  
  63. All four actions have in common that the generated code is appended to the target
  64. file immediately after the first occurrence of the sequence '/* Auto */' (in C files)
  65. or '; Auto' (in ASM files), deleting everything following it. If the sequence is not
  66. found in the file, then it will be appended along with the generated code. The header
  67. file is generated if it isn't already there.
  68.  
  69. The makefile skeleton shows how HeaderGen can be effectively incorporated into
  70. makefiles.
  71.  
  72. In the following section the four actions are described in detail.
  73.  
  74.  
  75.  HeaderGen -CtoC
  76. =================
  77.  
  78.  generates prototypes of external functions and variables and appends them to the
  79. named C header.
  80.  
  81. Functions and global variables are considered to be external if they contain the
  82. 'ExtIdent' string (see keyword options). This is to allow for global objects that are
  83. only visible within the program module where they are defined. The default ExtIdent
  84. string is the empty string, which will match any symbol. If you wish to use this
  85. feature, then I'd recommend using the name of the program module as ExtIdent string,
  86. as shown in the sample makefile. You can then use this string as a prefix of your
  87. external symbols.
  88.  
  89.  • One little problem with -CtoC
  90.  
  91. If you declare a (comma-separated) list of global variables of the same type, the
  92. ExtIdent string will only be checked against the first variable name. According to
  93. the result, the whole list is either 'extern'ed or not. If this causes inconvenience,
  94. split the list up into single <type> <var> declarations.
  95.  
  96.  
  97.  HeaderGen -ASMtoASM
  98. =====================
  99.  
  100. appends all external labels defined in the ASM source to the ASM header, each preceded
  101. by an IMPORT/EXPORT directive. The directive is implemented as an Asm variable which
  102. is defined at the beginning of the header. This variable expands to 'EXPORT' if the
  103. Asm variable __<file>_s has already been defined, to 'IMPORT' otherwise, where <file>
  104. is the name of the program module. You need to write a 'GBLA __file_s' in every source
  105. file, before it 'GET's its own header, for the header to 'know' whether it is supposed
  106. to IMPORT or to EXPORT the external labels. They are EXPORTed when the header is
  107. included from its own source file, IMPORTed otherwise.
  108.  
  109. Consequently, you don't need to worry about importing or exporting externals, just
  110. sign your external labels as external, include the ASM header into its own source file
  111. and into any source file where the externals shall be visible, and everything's ok.
  112.  
  113. Labels found in the source file are considered to be external if they contain the
  114. ExtIdent string.
  115.  
  116. If additional 'EXPORT <label>' statements are present in the Asm source, then the
  117. corresponding 'IMPORT's will be appended to the header, regardless of the ExtIdent
  118. string, so even if you don't wish to use an external identifier string, you can still
  119. use -ASMtoASM.
  120.  
  121. $-prefixed symbols and lines with Asm directives are ignored by this operation.
  122.  
  123.  
  124.  HeaderGen -ASMtoC
  125. ===================
  126.  
  127.  appends all external labels to the C header, preceded by 'extern'. A label is
  128. considered to be external, either if it contains the ExtIdent string or if it is
  129. explicitly EXPORTed.
  130.  
  131. If there's a comment of the form '; (<type>)' following the label, then <type> is
  132. considered to be the type of the object at the label's address. The default type
  133. is 'int'. If a comment of the form '; (<type>) (<arg0>,,,<argN>)' is found, then the
  134. label is converted to a function prototype with the given type and argument list, eg:
  135.  
  136.            this                    is converted to           this
  137. -------------------------------------------|------------------------------------------
  138. counter    DCD 0 ; (int)                   |     extern int counter;
  139.                                            |
  140. DotPlot          ; (void) (int x,int y)    |     extern void DotPlot(int x,int y);
  141.                                            |
  142.            EXPORT DrawLine ; (void) (void) |     extern void DrawLine(void);
  143.                                            |
  144.  
  145. Note that when 'EXPORT' is used, the (type) and (arg list) comments must follow the
  146. 'EXPORT' statement, and NOT be in the label definition line.
  147.  
  148. Storage areas, data structures and ASM directives are ignored. If you want to declare
  149. constants, or lay out data structures, then do it in a C header (that's the point of
  150. the entire program, BTW ;-)
  151.  
  152.  
  153.  HeaderGen -CtoASM
  154. ===================
  155.  
  156. This is the most complex action. It is used to convert all 'typedef', 'struct',
  157. 'union' and 'enum' definitions and (to a limited degree) macro definitions within a
  158. C header into appropriate ASM code. It also IMPORTs all functions and variables that
  159. are signed as external in the C header.
  160.  
  161. The program recognizes enum/struct/union templates as well as typedefs. The templates
  162. are referred to in the ASM code with the prefixes 'struct_' or 'union_' or 'enum_'
  163. to avoid ambiguity. Normally only the *non-anonymous* *templates* are converted
  164. to an explicit Asm structure, so if you define a structured type with 'typedef'
  165. plus an anonymous template, eg.
  166.  
  167.     typedef struct { int a,b; } dummy;
  168.  
  169. then only the size of the type 'dummy' will be declared in the Asm header, unless you
  170. add some template identifier, eg.
  171.  
  172.     typedef struct dummy { int a,b; } dummy;
  173.  
  174. In this case HeaderGen will also declare offsets to the two structure members a and b.
  175. However, you can change this to taste by calling HeaderGen with the option '-typedef',
  176. which means HeaderGen will explicitly lay out both template structures and typedef
  177. structures. However, this may cause a bit of an overhead.
  178.  
  179. Structure members are aligned correctly, ie char's are byte-aligned, short int's
  180. are half-word-aligned and all the rest is word-aligned. Alignment gaps are inserted
  181. into the ASM structure code as appropriate.
  182.  
  183. The members of enumerated data types may optionally have an expression assigned,
  184. which may contain hex and decimal integers and the operators + - * / % << >>.
  185.  
  186. Union members are not converted (as their offsets are all zero, if I've got it right).
  187. Thus the size of a union is declared as the maximum