Open Manual

Linking

Note: Use ny for applications; use this API to link existing objects.

The Nyr C API links object files and static archives through an in-process ELF linker or external LLVM tools. Source compilation and the compiler driver's application-link path are separate.

Contents

Declarations are in <nyr/nyr.h>; dispatch and ELF linking are implemented in linker.c.

nyr_link(request, err, err_len) accepts a nyr_link_request_t:

FieldMeaning
input_paths, input_countNonempty array of object or archive paths. Runtime and library files can be supplied as inputs.
output_pathRequired output file path.
target_tripleExplicit target triple, or NULL for the host default.
entry_symbolOptional executable entry symbol; its calling convention depends on the selected path.
kindNYR_LINK_EXECUTABLE, NYR_LINK_SHARED_LIBRARY, or NYR_LINK_STATIC_ARCHIVE.

The call returns true on success and clears a supplied nonempty error buffer. On failure it returns false and writes a diagnostic when a buffer is available. Paths and request storage remain caller-owned for the call.

Path selection

RequestImplementation
Linux x86-64 or AArch64 host, executable, target_triple == NULL, and an entry symbolIn-process ELF linker.
Static archive outputllvm-ar rcs.
Wasm executablewasm-ld; uses --no-entry when no entry is supplied.
Other executable or shared-library outputclang -fuse-ld=lld, with target and output-kind options.
Wasm shared libraryRejected.

An explicit target triple selects the external path even if it names the host. The API launches tools directly, without a shell. NYR_LINK_CLANG, NYR_LINK_WASM_LD, and NYR_LINK_AR override their executable paths. Cross-target links still require compatible tools, input objects, and any necessary target runtime or sysroot.

For external executable links, entry_symbol names the platform entry rather than a C main function. Mach-O requests add the platform's leading underscore. An explicit entry or shared-library request omits normal startup libraries through -nostdlib; callers supply required libraries as inputs. The request structure has no general-purpose linker-argument or library-search-path field.

In-process ELF executables

nyr_link_elf64_executable links one ELF64 x86-64 or AArch64 relocatable object. nyr_link_elf64_executable_objects accepts several objects and static archives for one of those architectures. These entry points are available on Linux x86-64 and AArch64 hosts and do not start an external linker. The output architecture follows the input objects, so an x86-64 host can produce a static AArch64 executable without a cross-linker.

The entry function takes no arguments and returns an i64. The linker adds a startup stub that calls it and uses the low byte of its result as the process exit status. This is not the platform's raw process-entry convention.

The linker resolves global and weak definitions across selected inputs and lazily extracts archive members needed by unresolved strong references. It parses selected members from the loaded archive buffer, without temporary object files. Duplicate strong definitions, unresolved strong symbols, unsupported relocations, writable executable sections, and unsupported object formats are errors.

This path supports the x86-64 and AArch64 relocation subsets emitted by Nytrix's object writers. It produces a static executable. It does not provide shared-library loading, ordinary C startup, or the compiler driver's full runtime and link options. Use the external request path or the compiler driver when those are needed.

Request example

This C fragment requires an existing ELF64 x86-64 object defining int64_t answer(void). Run the resulting executable on Linux x86-64:

#include <nyr/nyr.h>

const char *inputs[] = {"answer.o"};
nyr_link_request_t request = {
    .input_paths = inputs,
    .input_count = 1,
    .output_path = "answer",
    .target_triple = NULL,
    .entry_symbol = "answer",
    .kind = NYR_LINK_EXECUTABLE,
};
char error[256] = {0};
bool linked = nyr_link(&request, error, sizeof(error));

Coverage

The public API acceptance program executes linked outputs and checks multiple objects, archive extraction, strong/weak resolution, duplicate definitions, and unresolved-symbol errors. It also checks AArch64 ELF output and runs that executable under qemu-aarch64 when the emulator is installed. Run it after building the acceptance target:

cmake --build build/release --target nyr-backend-ir-acceptance
build/release/nyr-backend-ir-acceptance

Object emission and linking have separate capability boundaries. A target's object writer being available does not establish that the corresponding external linker, startup objects, or runtime libraries are installed.