ELD is an ELF linker designed to meet the needs of embedded software projects. It aims to be a drop-in replacement for the GNU linker, with a smaller memory footprint, faster link times and a customizable link behavior.

ELD supports targets Hexagon, ARM, AArch64 and RISCV and is designed for easy addition of more backends.

• Static linking

• Dynamic linking

• Partial linking

• LTO

• Same command-line options as GNU LD.

• Linker scripts. Linker script syntax is same as of GNU LD.

• Highly detailed linker map-files.

  Highly detailed map-files are essential to debug complex image layouts.

• Linker plugins

  Linker plugins allow a user to programmatically customize link behavior for advanced use-cases and complex image layouts.

• Reproduce functionality

  The reproduce functionality creates a tarball that can be used to reproduce the link without any other dependency.

ELD supports building and running tests on Linux, Windows, and macOS (Darwin) utilizing LLVM. macOS is supported as a host (Apple Silicon and Intel); ELD still produces ELF images and does not link Mach-O. On macOS the linker binary is built natively for the host architecture (arm64 or x86_64); universal binaries are not required.

ELD depends on LLVM. You can build ELD either:

• Integrated into an llvm-project build (recommended for running tests), or
• Against an external, prebuilt LLVM installation (faster iteration if you already have an LLVM release).

You will need a recent C++ compiler for building LLVM and ELD.

git clone https://github.com/llvm/llvm-project.git
cd llvm-project/
git clone https://github.com/qualcomm/eld.git
cd ../
cmake -G Ninja \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_INSTALL_PREFIX=../inst \
  -DLLVM_ENABLE_ASSERTIONS:BOOL=ON \
  -DLLVM_ENABLE_PROJECTS='llvm;clang' \
  -DLLVM_EXTERNAL_PROJECTS=eld \
  -DLLVM_EXTERNAL_ELD_SOURCE_DIR=${PWD}/llvm-project/eld \
  -DLLVM_TARGETS_TO_BUILD='ARM;AArch64;RISCV;Hexagon;X86' \
  -DCMAKE_CXX_FLAGS='-stdlib=libc++' \
  -B ./obj \
  -S ./llvm-project/llvm
cmake --build obj # Build the linker
cmake --build obj -- check-eld # Build test artifacts and run the tests

If you already have an installed LLVM/Clang "release" directory (with bin/clang, bin/clang++, bin/llvm-tblgen, and lib/cmake/llvm), you can configure ELD directly against it:

./configure_external_llvm.sh <LLVM_RELEASE_DIR> <ELD_BUILD_DIR>
cd <ELD_BUILD_DIR>
ninja

Notes:

• Tests are disabled by default for external builds;
• To build just the linker: ninja ld.eld

Some (optional) helpful CMake options:

• -DLLVM_USE_SPLIT_DWARF=On

  This option helps save on disk space with debug builds

• -DLLVM_PARALLEL_LINK_JOBS

  Linking LLVM toolchain can be very memory-intensive. To avoid OOM or swap performance repurcussion, it is recommended to restrict parallel link jobs, especially in systems with less than 32 GB of memory.

• -DLLVM_USE_LINKER=lld

  Using LLD instead of GNU LD can signficantly help in reducing link time and memory.

To execute an individual ELD test without running the entire suite, follow the steps below from the build directory ('obj/' here).

• Test configurations are stored under: obj/tools/eld/test/

• Test files reside in the source tree, for example: llvm-project/eld/test/<Subdirectory>/<TestName>.test

Use the following command to run a specific test case:

<path_to_lit_config> <path_to_test_file>

• <path_to_lit_config> : Path to the LIT configuration script
• <path_to_test_file> : Path to the '.test' file you wish to execute

obj/tools/eld/test/llvm-lit-arm-default  llvm-project/eld/test/Common/standalone/AliasSymbolExportDynamic/AliasSymbolExportDynamic.test

This command runs only the AliasSymbolExportDynamic test using the ARM default configuration. Results and diagnostics will be printed to the console.

• -a: Always show detailed output.
• -v: Show detailed output only when a test fails ("on failure" mode).

Some tests actually execute the linked binaries to verify runtime behavior. These tests require a cross-compilation toolchain and an emulator (e.g., QEMU) to be configured.

Configure the project with -DELD_ENABLE_RUN_TESTS=On and set the following environment variables for each target architecture you want to enable run tests on:

The run_test lit feature is enabled when the C compiler, sysroot, and emulator are all configured for a target. The run_cxx_test feature additionally requires the C++ compiler.

For <TARGET>_C_COMPILER, <TARGET>_CXX_COMPILER, and <TARGET>_EMULATOR, you can provide either a full path or just the tool name (which will be resolved via PATH).

# CMake must be configured via -DELD_ENABLE_RUN_TESTS=On
export ELD_AARCH64_C_COMPILER=/usr/bin/aarch64-linux-gnu-gcc
export ELD_AARCH64_CXX_COMPILER=/usr/bin/aarch64-linux-gnu-g++
export ELD_AARCH64_SYSROOT=/usr/aarch64-linux-gnu
export ELD_AARCH64_EMULATOR=qemu-aarch64

After running check-eld, you can print a consolidated result table across all architecture/option configurations using the check-eld-summary target:

cmake --build obj -- check-eld-summary
# or with ninja:
ninja check-eld-summary

This reads the results.json file written by each lit sub-run and prints a table.

If a configuration has not been run yet its row shows (no results). check-eld-summary is independent of check-eld — it only reads result files and always exits successfully.

To list individual test names beneath each configuration row, set ELD_SUMMARY_DETAIL=1 (shows all non-PASS codes) or ELD_SUMMARY_DETAIL_CODES (comma-separated list of codes to expand):

# Linux - PASS result codes
ELD_SUMMARY_DETAIL=1 ninja check-eld-summary

# Linux — expand only UNSUPPORTED and XFAIL
ELD_SUMMARY_DETAIL_CODES=UNSUPPORTED,XFAIL ninja check-eld-summary

# Windows (cmake --build)
ELD_SUMMARY_DETAIL=1 cmake --build obj --config Release --target check-eld-summary

The Vim syntax-highlighting files in etc/vim/ have a lit-based test suite that verifies syntax-group assignments for every token class in eld.vim.

Prerequisites

• Vim 9.1 or later in PATH (tests drive Vim in batch mode; Neovim is not supported).
• Python 3 in PATH.
• lit installed (pip install lit).

Running the tests

Each test spawns one Vim process; run the suite serially to avoid resource contention:

cd etc/vim/test
lit -j1 .

Run a single test file:

lit -j1 comments.test

Run with verbose output to see per-check PASS/FAIL lines:

lit -j1 -v .

Use a specific Vim binary:

lit -j1 -D vim=/path/to/vim .

CMake build target

Enable the test suite at configure time with -DELD_VIM_TESTS=ON. This adds a check-eld-vim target that runs the tests with a single worker and a 120-second per-test timeout:

cmake -DELD_VIM_TESTS=ON <other options> <source-dir>
ninja check-eld-vim

First install the prerequisites for building documentation:

• Doxygen (>=1.8.11)
• graphviz
• Sphinx and other python dependencies as specified in 'docs/userguide/requirements.txt'

On an ubuntu machine, the prerequisites can be installed as:

sudo apt install doxygen graphviz
pip3 install -r ${ELDRoot}/docs/userguide/requirements.txt

Finally, to build documentation:

• Configure CMake with the option -DLLVM_ENABLE_SPHINX=On
• Build documentation by building eld-docs target: cmake --build . --target eld-docs
• To also build ELD_UserGuide.pdf, configure with -DELD_ENABLE_PDF_DOCS=ON. PDF generation uses Typst, provided either by the typst executable or the Python package listed in docs/userguide/requirements.txt.

To run DCO checks locally you will need to fiest install nodeJs and npm:

On an ubuntu machine, these can be installed as:

sudo apt install nodejs
sudo apt install npm

You can then install repolinter using:

npm install repolinter

To run the DCO checks locally use the following command:

repolinter lint </path/to/eld>

ELD uses LLVM clang-format style via the repository .clang-format file.

Use the helper script at: etc/bash/eld_clang_format_helpers.sh

To enable the functions in your shell, add this to your ~/.bashrc (or ~/.bash_aliases) and reload:

source </path/to/eld>/etc/bash/eld_clang_format_helpers.sh

For usage, run:

eld_clang_format_check --help

clang-format --version
eld_clang_format_check <base-branch>

eld_clang_format_check prints per-file colored status and returns non-zero on failure.

eld_clang_format_fix <base-branch>

Pull requests run .github/workflows/clang-format-pr.yml, which fails if any changed C/C++ source file is not formatted with clang-format --style=file.

ELD PRs also run clang-tidy-based lint checks via: .github/workflows/cpp-linter-pr.yml

Current behavior:

• Runs on changed C/C++ files in the PR.
• Uses external-LLVM build setup to generate compile_commands.json.
• Runs non-blocking for now (does not fail the PR by default).
• Uploads downloadable logs/artifacts (including detailed diagnostics).

Use the helper script at: etc/bash/eld_cpp_linter_helpers.sh

To enable the functions in your shell:

source </path/to/eld>/etc/bash/eld_cpp_linter_helpers.sh

For usage/help:

eld_cpp_linter_check --help

Common usage:

# Check changed files against base branch
eld_cpp_linter_check --base-branch main --build-directory <build-dir>

# Apply clang-tidy fixes on changed files
eld_cpp_linter_fix --base-branch main --build-directory <build-dir>

# Check or fix a single file
eld_cpp_linter_check --build-directory <build-dir> --file path/to/file.cpp
eld_cpp_linter_fix   --build-directory <build-dir> --file path/to/file.cpp

1. Skip in PR workflow input list (temporary CI-level skip):

git diff --name-only --diff-filter=ACMRT "origin/${BASE_REF}...HEAD" \
  | grep -E '\.(c|cc|cpp|cxx|h|hh|hpp|hxx|inc|def)$' \
  | grep -Ev '^(path/to/file1\.cpp|path/to/legacy/.*)$' \
  > .cpp-linter-files.txt || true

2. Run helpers on a specific file only (local scope control):

eld_cpp_linter_check --build-directory <build-dir> --file path/to/file.cpp

3. Add source-level suppressions where justified:

• // NOLINT(<check-name>)
• // NOLINTBEGIN(<check-name>) / // NOLINTEND(<check-name>)

4. Use repo-level .clang-tidy policy filters, if maintained, for broad path/check tuning.

• Official clang-tidy checks list: https://clang.llvm.org/extra/clang-tidy/checks/list.html
• Checks supported by your installed clang-tidy version:

clang-tidy -list-checks -checks='*'

Live status of workflows building with ELD

Licensed under BSD 3-Clause License