(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. If the
  function reads or sets `errno`, include both `libc.src.__support.libc_errno`
  and `libc.src.errno.errno` in `DEPENDS` (see {ref}`setting_errno`).

### 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. For functions
  setting `errno`, use `ErrnoCheckingTest` and `ErrnoSetterMatcher`
  (see {ref}`setting_errno`).
- Update the `CMakeLists.txt` in the test directory (`libc/test/src/<header>/CMakeLists.txt`) to include the new test target.