1.. _porting: 2 3======================================= 4Bringup on a New OS or Architecture 5======================================= 6 7.. contents:: Table of Contents 8 :depth: 4 9 :local: 10 11CI builders 12=========== 13 14If you are contributing a port for an operating system or architecture which 15is not covered by existing CI builders, you will also have to present a plan 16for testing and contribute a CI builder. See 17`this guide <https://llvm.org/docs/HowToAddABuilder.html>`_ for information 18on how to add new builders to the 19`LLVM buildbot <https://lab.llvm.org/buildbot>`_. 20You will either have to extend the existing 21`Linux script <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-linux.py>`_ 22and/or 23`Windows script <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-windows.py>`_ 24or add a new script for your operating system. 25 26An OS specific config directory 27=============================== 28 29If you are starting to bring up LLVM's libc on a new operating system, the first 30step is to add a directory for that OS in the ``libc/config`` directory. Both 31`Linux <https://github.com/llvm/llvm-project/tree/main/libc/config/linux>`_ and 32`Windows <https://github.com/llvm/llvm-project/tree/main/libc/config/windows>`_, 33the two operating systems on which LLVM's libc is being actively developed, 34have their own config directory. 35 36.. note:: Windows development is not as active as the development on Linux. 37 There is a 38 `Darwin <https://github.com/llvm/llvm-project/tree/main/libc/config/darwin>`_ 39 config also which is in a similar state as Windows. 40 41.. note:: LLVM's libc is being brought up on the 42 `Fuchsia <https://fuchsia.dev/>`_ operating system also. However, there is no 43 config directory for Fuchsia as the bring up is being done in the Fuchsia 44 source tree. 45 46Architecture Subdirectory 47========================= 48 49There are parts of the libc which are implemented differently for different 50architectures. The simplest example of this is the ``syscall`` function and 51its internal implementation - its Linux implementation differs for different 52architectures. Since a large part of the libc makes use of syscalls (or an 53equivalent on non-Linux like platforms), it might be simpler and convenient to 54bring up the libc for one architecture at a time. In such cases, wherein the 55support surface of LLVM's libc differs for each target architecture, one will 56have to add a subdirectory (within the config directory os the operating 57system) for each target architecture, and list the relevant config information 58separately in those subdirectories. For example, for Linux, the x86_64 and 59aarch64 configs are in separate directories, named 60`x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_ 61and `aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_. 62The libc CMake machinery looks for subdirectories named after the target 63architecture. 64 65The entrypoints.txt file 66======================== 67 68One of the important pieces of config information is listed in a file named 69``entrypoints.txt``. This file lists the targets for the entrypoints (see 70:ref:`entrypoints`) you want to include in the static archive of the libc (for 71the :ref:`overlay_mode` and/or the :ref:`full_host_build`.) If you are doing an 72architecture specific bring up, then an ``entrypoints.txt`` file should be 73created in the architecture subdirectory for each architecture. Else, having a 74single ``entrypoints.txt`` in the operating system directory is sufficient. 75 76The Linux config has an ``entrypoint.txt`` for each individual target 77architecture separately: `aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_, 78`arm32 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/arm>`_ and 79`x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_. On the 80other hand, the Windows config has a single ``entrypoints.txt`` 81`file <https://github.com/llvm/llvm-project/tree/main/libc/config/windows/entrypoints.txt>`_. 82 83A typical bring up procedure will normally bring up a small group of entrypoints 84at a time. The usual practice is to progressively add the targets for those 85entrypoints to the ``entrypoints.txt`` file as they are being brought up. The 86same is the case if one is implementing a new entrypoint - the target for the 87new entrypoint should be added to the relevant ``entrypoints.txt`` file. If 88the implementation of the new entrypoint supports multiple operating systems and 89target architectures, then multiple ``entrypoints.txt`` files will have to be 90updated. 91 92The headers.txt file 93==================== 94 95Another important piece of config information is listed in a file named 96``headers.txt``. It lists the targets for the set of public headers that are 97provided by the libc. This is relevant only if the libc is to be used in the 98:ref:`full_host_build` on the target operating system and architecture. As with 99the ``entrypoints.txt`` file, one ``headers.txt`` file should be listed for 100each individual target architecture if you are doing an architecture specific 101bring up. The Linux config has ``headers.txt`` file listed separately for the 102`aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64>`_ 103config and the 104`x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_ 105config. 106