libc/docs/mechanics_of_public_api.rst

   1 The mechanics of the ``public_api`` command
   2 ===========================================
   3
   4 The build system, in combination with the header generation mechanism,
   5 facilitates the fine grained ability to pick and choose the public API one wants
   6 to expose on their platform. The public header files are always generated from
   7 the corresponding ``.h.def`` files. A header generation command ``%%public_api``
   8 is listed in these files. In the generated header file, the header generator
   9 replaces this command with the public API relevant for the target platform.
  10
  11 Under the hood
  12 --------------
  13
  14 When the header generator sees the ``%%public_api`` command, it looks up the
  15 API config file for the platform in the path ``config/<platform>/api.td``.
  16 The API config file lists two kinds of items:
  17
  18 1. The list of standards from which the public entities available on the platform
  19    are derived from.
  20 2. For each header file exposed on the platfrom, the list of public members
  21    provided in that header file.
  22
  23 Note that, the header generator only learns the names of the public entities
  24 from the header config file (the 2nd item from above.) The exact manner in which
  25 the entities are to be declared is got from the standards (the 1st item from
  26 above.)
  27
  28 See the ground truth document for more information on how the standards are
  29 formally listed in LLVM libc using LLVM table-gen files.