libc/docs/header_generation.rst

   1 Generating Public and Internal headers
   2 ======================================
   3
   4 Other libc implementations make use of preprocessor macro tricks to make header
   5 files platform agnostic. When macros aren't suitable, they rely on build
   6 system tricks to pick the right set of files to compile and export. While these
   7 approaches have served them well, parts of their systems have become extremely
   8 complicated making it hard to modify, extend or maintain. To avoid these
   9 problems in llvm-libc, we use a header generation mechanism. The mechanism is
  10 driven by a *header configuration language*.
  11
  12 Header Configuration Language
  13 -----------------------------
  14
  15 Header configuration language consists of few special *commands*. The header
  16 generation mechanism takes an input file, which has an extension of
  17 ``.h.def``, and produces a header file with ``.h`` extension. The header
  18 configuration language commands are listed in the input ``.h.def`` file. While
  19 reading a ``.h.def`` file, the header generation tool does two things:
  20
  21 1. Copy the lines not containing commands as is into the output ``.h`` file.
  22 2. Replace the line on which a command occurs with some other text as directed
  23    by the command. The replacement text can span multiple lines.
  24
  25 Command syntax
  26 ~~~~~~~~~~~~~~
  27
  28 A command should be listed on a line by itself, and should not span more than
  29 one line. The first token to appear on the line is the command name prefixed
  30 with ``%%``. For example, a line with the ``include_file`` command should start
  31 with ``%%include_file``. There can be indentation spaces before the ``%%``
  32 prefix.
  33
  34 Most commands typically take arguments. They are listed as a comma separated
  35 list of named identifiers within parenthesis, similar to the C function call
  36 syntax. Before performing the action corresponding to the command, the header
  37 generator replaces the arguments with concrete values.
  38
  39 Argument Syntax
  40 ~~~~~~~~~~~~~~~
  41
  42 Arguments are named indentifiers but prefixed with ``$`` and enclosed in ``{``
  43 and ``}``. For example, ``${path_to_constants}``.
  44
  45 Comments
  46 ~~~~~~~~
  47
  48 There can be cases wherein one wants to add comments in the .h.def file but
  49 does not want them to be copied into the generated header file. Such comments
  50 can be added by beginning the comment lines with the ``<!>`` prefix. Currently,
  51 comments have to be on lines of their own. That is, they cannot be suffixes like
  52 this:
  53
  54 ```
  55 %%include_file(a/b/c) <!> Path to c in b of a.  !!! WRONG SYNTAX
  56 ```
  57
  58 Available Commands
  59 ------------------
  60
  61 Sub-sections below describe the commands currently available. Under each command
  62 is the description of the arguments to the command, and the action taken by the
  63 header generation tool when processing a command.
  64
  65 ``include_file``
  66 ~~~~~~~~~~~~~~~~
  67
  68 This is a replacement command which should be listed in an input ``.h.def``
  69 file.
  70
  71 Arguments
  72
  73   * **path argument** - An argument representing a path to a file. The file
  74     should have an extension of ``.h.inc``.
  75
  76 Action
  77
  78   This command instructs that the line on which the command appears should be
  79   replaced by the contents of the file whose path is passed as argument to the
  80   command.
  81
  82 ``begin``
  83 ~~~~~~~~~
  84
  85 This is not a replacement command. It is an error to list it in the input
  86 ``.h.def`` file. It is normally listed in the files included by the
  87 ``include_file`` command (the ``.h.inc`` files). A common use of this command it
  88 mark the beginning of what is to be included. This prevents copying items like
  89 license headers into the generated header file.
  90
  91 Arguments
  92
  93   None.
  94
  95 Action
  96
  97   The header generator will only include content starting from the line after the
  98   line on which this command is listed.
  99
 100 ``public_api``
 101 ~~~~~~~~~~~~~~
 102
 103 This is a replacement command which should be listed in an input ``.h.def``
 104 file. The header file generator will replace this command with the public API of
 105 the target platform. See the build system document for more information on the
 106 relevant build rules. Also, see "Mechanics of public_api" to learn the mechanics
 107 of how the header generator replaces this command with the public API.
 108
 109 Arguments
 110
 111   None.
 112
 113 Action
 114
 115   The header generator will replace this command with the public API to be exposed
 116   from the generated header file.