| .. _implementing_a_function: | |
| =========================== | |
| Implementing a New Function | |
| =========================== | |
| This guide provides a step-by-step walkthrough for adding a new function to LLVM-libc. | |
| Overview | |
| ======== | |
| Adding a new function involves several steps, from updating the public specification to implementing and testing the code. Below is the standard checklist for contributors. | |
| Step-by-Step Checklist | |
| ====================== | |
| 1. Header Entry | |
| --------------- | |
| Update the standard YAML file that describes the public header to ensure the function is included in the generated public header. | |
| * **File**: ``libc/include/<header>.yaml`` (or ``libc/include/sys/<header>.yaml`` for system headers) | |
| * Add the new function to the ``functions`` list. | |
| * Specify its name, return type, and arguments. | |
| * List the standards it complies with (e.g., ``stdc``, ``POSIX``). | |
| 2. Header Declaration | |
| --------------------- | |
| Declare the function in the internal implementation header file. This file is used by other internal code. | |
| * **File**: ``libc/src/<header>/<func>.h`` | |
| * Follow the structure defined in :ref:`implementation_standard`. | |
| * Ensure the declaration is inside the ``LIBC_NAMESPACE_DECL`` namespace. | |
| 3. Implementation | |
| ----------------- | |
| Write the actual code for the function. | |
| * **File**: ``libc/src/<header>/<func>.cpp`` (or ``libc/src/<header>/<os>/<func>.cpp`` for platform-specific implementations) | |
| * Use the ``LLVM_LIBC_FUNCTION`` macro. | |
| * Refer to :ref:`code_style` for naming and layout conventions. | |
| 4. CMake Rule | |
| ------------- | |
| Add a CMake target for the new function so it can be compiled. | |
| * **File**: ``libc/src/<header>/CMakeLists.txt`` | |
| * Add an ``add_entrypoint_object`` rule for the new file. | |
| * List all internal dependencies correctly to ensure proper build order. | |
| 5. Platform Registration | |
| ------------------------ | |
| Register the new entrypoint for the target platforms to include it in the build. | |
| * **File**: ``libc/config/<os>/<arch>/entrypoints.txt`` | |
| * Add the new function to the list of active entrypoints. | |
| 6. Testing | |
| ---------- | |
| Create tests to verify the implementation. | |
| * **File**: ``libc/test/src/<header>/<func>_test.cpp`` | |
| * Add corresponding tests using the internal testing framework. | |
| * Update the ``CMakeLists.txt`` in the test directory (``libc/test/src/<header>/CMakeLists.txt``) to include the new test target. |