libc/docs/dev/source_tree_layout.rst

   1 .. _source_tree_layout:
   2
   3 ============================
   4 LLVM-libc Source Tree Layout
   5 ============================
   6
   7 At the top-level, LLVM-libc source tree is organized in to the following
   8 directories::
   9
  10    + libc
  11         - benchmarks
  12         - cmake
  13         - config
  14         - docs
  15         - examples
  16         - fuzzing
  17         - include
  18         - lib
  19         - spec
  20         - src
  21         - startup
  22         - test
  23         - utils
  24
  25 Each of these directories is explained breifly below.
  26
  27 The ``benchmarks`` directory
  28 ----------------------------
  29
  30 The ``benchmarks`` directory contains LLVM-libc's benchmarking utilities. These
  31 are mostly used for the memory functions. This also includes the automemcpy
  32 subdirectory for automatic generation of optimized memory functions.
  33
  34 The ``config`` directory
  35 ------------------------
  36
  37 The ``config`` directory contains the default configurations for the targets
  38 LLVM-libc supports. These are files in the ``config/<platform>/<architecture>/``
  39 subdirectory called ``entrypoints.txt``, ``exclude.txt``, ``headers.txt``,  and
  40 ``config.json``. These tell cmake which entrypoints are available, which
  41 entrypoints to exclude, which headers to generate, and what options to set for
  42 the current target respectively. There are also other platform specific files in
  43 the ``config/<platform>/`` subdirectory.
  44
  45 The ``cmake`` directory
  46 -----------------------
  47
  48 The ``cmake`` directory contains the implementations of LLVM-libc's CMake build
  49 rules.
  50
  51 The ``docs`` directory
  52 ----------------------
  53
  54 The ``docs`` directory contains design docs and also informative documents like
  55 this document on source layout.
  56
  57 The ``fuzzing`` directory
  58 -------------------------
  59
  60 This directory contains fuzzing tests for the various components of LLVM-libc.
  61 The directory structure within this directory mirrors the directory structure
  62 of the top-level ``libc`` directory itself. For more details, see
  63 :doc:`fuzzing`.
  64
  65 The ``include`` directory
  66 -------------------------
  67
  68 The ``include`` directory contains:
  69
  70 1. ``*.h.def`` files - These files are used to construct the generated public
  71    header files.
  72 2. Self contained public header files - These are header files which are
  73    already in the form that get installed when LLVM-libc is installed on a
  74    user's computer. These are mostly in the ``llvm-libc-macros`` and
  75    ``llvm-libc-types`` subdirectories.
  76
  77 The ``lib`` directory
  78 ---------------------
  79
  80 This directory contains a ``CMakeLists.txt`` file listing the targets for the
  81 public libraries ``libc.a``, ``libm.a`` etc.
  82
  83 The ``spec`` directory
  84 ----------------------
  85
  86 This directory contains the specifications for the types, macros, and entrypoint
  87 functions. These definitions come from the various standards and extensions
  88 LLVM-libc supports, and they are used along with the ``*.h.def`` files and the
  89 config files to generate the headers for fullbuild mode.
  90
  91 The ``src`` directory
  92 ---------------------
  93
  94 This directory contains the implementations of the llvm-libc entrypoints. It is
  95 further organized as follows:
  96
  97 1. There is a top-level CMakeLists.txt file.
  98 2. For every public header file provided by llvm-libc, there exists a
  99    corresponding directory in the ``src`` directory. The name of the directory
 100    is same as the base name of the header file. For example, the directory
 101    corresponding to the public ``math.h`` header file is named ``math``. The
 102    implementation standard document explains more about the *header*
 103    directories.
 104
 105 The ``startup`` directory
 106 -------------------------
 107
 108 This directory contains the implementations of the application startup objects
 109 like ``crt1.o`` etc.
 110
 111 The ``test`` directory
 112 ----------------------
 113
 114 This directory contains tests for the various components of LLVM-libc. The
 115 directory structure within this directory mirrors the directory structure of the
 116 toplevel ``libc`` directory itself. A test for, say the ``mmap`` function, lives
 117 in the directory ``test/src/sys/mman/`` as implementation of ``mmap`` lives in
 118 ``src/sys/mman``.
 119
 120 The ``utils`` directory
 121 -----------------------
 122
 123 This directory contains utilities used by other parts of the LLVM-libc system.
 124 See the `README` files in the subdirectories within this directory to learn
 125 about the various utilities.