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