C ABI negotiation

The stable C interface reports ABI major 1, minor 0. Negotiate the major before calling a function table. A null table or a major mismatch is a hard failure; decide whether a minor version is acceptable before using optional capabilities.

Link the C interface

The forwarding headers and compatibility target are part of the installed package:

find_package(TreefallSDK 0.9.0 EXACT REQUIRED CONFIG)

add_executable(c-abi-consumer main.c)
target_compile_features(c-abi-consumer PRIVATE c_std_11)
target_link_libraries(c-abi-consumer PRIVATE Treefall::core)

Configure with the install prefix from Build and install:

cmake -S . -B build \
  -DCMAKE_PREFIX_PATH=/tmp/treefall-sdk-0.9.0-install
cmake --build build

Request ABI 1.0

Include <treefall/abi.h> and <treefall/abi_version.h>, pass the major you compiled against, and inspect every result before calling through the table:

#include <stddef.h>
#include <stdint.h>

#include <treefall/abi.h>
#include <treefall/abi_version.h>

uint32_t got_major = 0;
uint32_t got_minor = 0;
const treefall_session_api_v1* api =
    treefall_session_abi_v1(TREEFALL_ABI_MAJOR, &got_major, &got_minor);

if (api == NULL ||
    got_major != TREEFALL_ABI_MAJOR ||
    got_minor != TREEFALL_ABI_MINOR ||
    TREEFALL_ABI_MAJOR != 1 ||
    TREEFALL_ABI_MINOR != 0) {
  /* Do not call function-table entries. */
  return 1;
}

/* The table is negotiated; check each operation's TREEFALL_STATUS_* result. */
treefall_session_handle session = NULL;
if (api->create(&session) != TREEFALL_STATUS_OK || session == NULL) {
  return 1;
}
api->destroy(session);

treefall_session_abi_v1() always reports the SDK’s got_major and got_minor when those output pointers are non-null. It returns NULL when the requested major is not implemented. ABI status values such as TREEFALL_STATUS_INVALID_ARGUMENT and TREEFALL_STATUS_NOT_FOUND describe individual table calls; they do not replace negotiation.

The exact-minor check above is appropriate for this 1.0 consumer. A consumer that accepts compatible minor additions can use its own policy, but must never call optional fields it has not established are present.

Verify an installed package

The package C smoke requests the ABI major, checks the returned 1.0 values and table pointers, exercises create/destroy and status conversion, and confirms that Treefall and legacy C entry points resolve the same ABI surface:

example.c-abi-smoke · Product 0.9.0

Source revision: b8c8b87540fe585b5c7d5c8f25d193c1a1af93d5

/* SPDX-License-Identifier: MIT */
#include <treefall/abi.h>
#include <treefall/abi_version.h>

#include <stdint.h>
#include <stdio.h>

int main(void) {
  uint32_t got_major = 0;
  uint32_t got_minor = 0;
  const treefall_session_api_v1* api =
      treefall_session_abi_v1(TREEFALL_ABI_MAJOR, &got_major, &got_minor);
  if (api == NULL || !TREEFALL_ABI_EXPECT(got_major) || got_major != 1 || got_minor != 0 ||
      TREEFALL_ABI_MAJOR != 1 || TREEFALL_ABI_MINOR != 0) {
    fputs("Treefall C ABI negotiation failed\n", stderr);
    return 1;
  }
  puts("Treefall C ABI 1.0 available");
  return 0;
}

Treefall C ABI 1.0 available

Source and producer-reported verification

Source-relative path: examples/c-abi-smoke.c
SHA-256: 89d7dd07165b888c72e3de61b91fa90f263601f53fd81878a5de4c02d2008ca6
Producer-reported verification: executed
Environment: os=darwin/arm64; cmake=cmake version 4.1.0; compiler=Apple clang version 21.0.0 (clang-2100.0.123.102)
Command: ./examples-build/c-abi-smoke

If the program exits nonzero, inspect package discovery first, then confirm that the executable links the intended install prefix. Do not call a table after negotiation failed.

The forwarding declarations and version macros are in the ABI header and ABI version header at the documented source revision. The installed C consumer is exercised by the C package example.