Reid Kleckner
821afb2ed8
Tracking issue: https://github.com/llvm/llvm-project/issues/201242 Migration guide docs: https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines RFC: https://discourse.llvm.org/t/rfc-make-myst-markdown-the-llvm-docs-format-rip-rest/90840 This was prepared with rst2myst plus LLM-assisted cleanup. I paged through all the generated HTML looking for migration artifacts, and all of the differences I could find appear to be formatting error corrections. Please spot check my work and approve if it looks good.
60 lines
2.1 KiB
Markdown
60 lines
2.1 KiB
Markdown
(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.
|