Linux native integration

Linux native · supported

Linux uses the stable native C ABI. Native consumers own consent presentation, callback threading, handle serialization, and application packaging. Prefer a supported higher-level wrapper when your host is Node.js.

Artifact layout

The onboarding archive contains a target-specific directory similar to:

include/p2p_sdk.h
lib/libp2p_sdk.so -> libp2p_sdk.so.1
lib/libp2p_sdk.so.1 -> libp2p_sdk.so.1.0.0
lib/libp2p_sdk.so.1.0.0
lib/pkgconfig/p2p-sdk.pc
lib/cmake/P2PSdk/P2PSdkConfig.cmake

Preserve the SONAME links and package the library in an application-controlled directory.

Link with pkg-config

PKG_CONFIG_PATH="$P2PSDK_ROOT/lib/pkgconfig" \
  cc app.c $(pkg-config --cflags --libs p2p-sdk) \
  -Wl,-rpath,'$ORIGIN/lib' \
  -o app

Link with CMake

find_package(P2PSdk CONFIG REQUIRED)
target_link_libraries(app PRIVATE P2PSdk::p2p_sdk)

Point CMAKE_PREFIX_PATH at the onboarding artifact root. Run the application from its final packaged directory to verify runtime resolution.

Initialize through the C ABI

#include <p2p_sdk.h>
#include <stdbool.h>
#include <stdio.h>

static void on_connect(void* user_data) {
    (void)user_data;
    puts("P2PSDK connected");
}

static void on_disconnect(int reason, void* user_data) {
    (void)user_data;
    fprintf(stderr, "P2PSDK disconnected: %d\n", reason);
}

int main(void) {
    if (sdk_abi_version() != 1) {
        fputs("Unsupported P2PSDK ABI\n", stderr);
        return 1;
    }

    /* Pass true only after the product completes its approved consent flow. */
    void* sdk = sdk_new_with_debug_and_consent(
        "app-integration-key",
        false,
        true
    );

    if (sdk == NULL) {
        const char* message = sdk_last_error_message();
        fprintf(stderr, "P2PSDK init failed: %s\n", message ?: "unknown");
        return 1;
    }

    sdk_set_callbacks(sdk, on_connect, on_disconnect, NULL);

    if (!sdk_connect(sdk)) {
        const char* message = sdk_last_error_message();
        fprintf(stderr, "connect failed: code=%d retryable=%s message=%s\n",
            sdk_last_error_code(),
            sdk_last_error_retryable() ? "yes" : "no",
            message ?: "unknown");
        sdk_free(sdk);
        return 1;
    }

    /* Keep the process and handle alive; online arrives through on_connect. */
    sdk_disconnect(sdk);
    sdk_set_callbacks(sdk, NULL, NULL, NULL);
    sdk_free(sdk);
    return 0;
}

If your C compiler does not support the GNU ?: extension, replace message ?: "unknown" with message ? message : "unknown".

The Linux C ABI does not provide a standard application UI helper. Your approved integration design must collect consent before passing true, or create with a receipt when the onboarding flow requires one. Do not use the legacy sdk_new or sdk_new_with_debug; they remain exported for ABI compatibility but return NULL because consent is required.

Threading and ownership

C callbacks can run on SDK runtime threads. Keep them short, non-blocking, and thread-safe. Marshal into a UI toolkit or language runtime before touching its state.

Serialize calls when multiple application threads can access one handle. Never call sdk_free while another call or callback for that handle is active. Clear callbacks before releasing application callback context.

Error lifetime

sdk_last_error_message() returns thread-local data valid only until another SDK ABI call on that thread changes or clears it. Read and copy it immediately after failure. Prefer structured code, retryability, and disconnect reason accessors.

Linux verification

Compile a clean consumer using the staged header and pkg-config/CMake metadata.
Verify ABI major, SONAME links, rpath, dependencies from ldd, and final package layout.
Wait for the connect callback, interrupt/restore the network, and verify callback thread handling.
Clear callbacks, free exactly once, and run thread sanitization in the host application where practical.