.. _porting: ======================================= Bringup on a New OS or Architecture ======================================= .. contents:: Table of Contents :depth: 4 :local: CI builders =========== If you are contributing a port for an operating system or architecture which is not covered by existing CI builders, you will also have to present a plan for testing and contribute a CI builder. See `this guide `_ for information on how to add new builders to the `LLVM buildbot `_. You will either have to extend the existing `Linux script `_ and/or `Windows script `_ or add a new script for your operating system. An OS specific config directory =============================== If you are starting to bring up LLVM's libc on a new operating system, the first step is to add a directory for that OS in the ``libc/config`` directory. Both `Linux `_ and `Windows `_, the two operating systems on which LLVM's libc is being actively developed, have their own config directory. .. note:: Windows development is not as active as the development on Linux. There is a `Darwin `_ config also which is in a similar state as Windows. .. note:: LLVM's libc is being brought up on the `Fuchsia `_ operating system also. However, there is no config directory for Fuchsia as the bring up is being done in the Fuchsia source tree. The api.td file --------------- If the :ref:`fullbuild_mode` is to be supported on the new operating system, then a file named ``api.td`` should be added in its config directory. It is written in the `LLVM tablegen language `_. It lists all the relevant macros and type definitions we want in the public libc header files. See the existing Linux `api.td `_ file as an example to prepare the ``api.td`` file for the new operating system. .. note:: In future, LLVM tablegen will be replaced with a different DSL to list config information. Architecture Subdirectory ========================= There are parts of the libc which are implemented differently for different architectures. The simplest example of this is the ``syscall`` function and its internal implementation - its Linux implementation differs for different architectures. Since a large part of the libc makes use of syscalls (or an equivalent on non-Linux like platforms), it might be simpler and convenient to bring up the libc for one architecture at a time. In such cases, wherein the support surface of LLVM's libc differs for each target architecture, one will have to add a subdirectory (within the config directory os the operating system) for each target architecture, and list the relevant config information separately in those subdirectories. For example, for Linux, the x86_64 and aarch64 configs are in separate directories, named `x86_64 `_ and `aarch64 `_. The libc CMake machinery looks for subdirectories named after the target architecture. The entrypoints.txt file ======================== One of the important pieces of config information is listed in a file named ``entrypoints.txt``. This file lists the targets for the entrypoints (see :ref:`entrypoints`) you want to include in the static archive of the libc (for the :ref:`overlay_mode` and/or the :ref:`fullbuild_mode`.) If you are doing an architecture specific bring up, then an ``entrypoints.txt`` file should be created in the architecture subdirectory for each architecture. Else, having a single ``entrypoints.txt`` in the operating system directory is sufficient. The Linux config has an ``entrypoint.txt`` for each individual target architecture separately: `aarch64 `_, `arm32 `_ and `x86_64 `_. On the other hand, the Windows config has a single ``entrypoints.txt`` `file `_. A typical bring up procedure will normally bring up a small group of entrypoints at a time. The usual practice is to progressively add the targets for those entrypoints to the ``entrypoints.txt`` file as they are being brought up. The same is the case if one is implementing a new entrypoint - the target for the new entrypoint should be added to the relevant ``entrypoints.txt`` file. If the implementation of the new entrypoint supports multiple operating systems and target architectures, then multiple ``entrypoints.txt`` files will have to be updated. The headers.txt file ==================== Another important piece of config information is listed in a file named ``headers.txt``. It lists the targets for the set of public headers that are provided by the libc. This is relevant only if the libc is to be used in the :ref:`fullbuild_mode` on the target operating system and architecture. As with the ``entrypoints.txt`` file, one ``headers.txt`` file should be listed for each individual target architecture if you are doing an architecture specific bring up. The Linux config has ``headers.txt`` file listed separately for the `aarch64 `_ config and the `x86_64 `_ config.