mirror of https://github.com/logos-messaging/logos-delivery.git synced 2026-07-23 13:03:11 +00:00

feat: generate the C header instead of hand-writing it

The hand-written liblogosdelivery.h / _kernel.h declared the pre-CBOR
string ABI, so they lied about the real one -- a C consumer would link
against signatures that no longer exist. genBindings already produces the
Rust bindings from the Nim source; this adds the C target on the same
footing.

liblogosdeliveryGenBindingsC emits library/c_bindings/: logosdelivery.h
covering the whole surface (messaging, channels and the waku_* kernel
procs in one file), plus the nim_ffi_cbor.h / _prelude.h helpers that
marshal the CBOR payloads. Params ride as CBOR blobs, matching the
library's default ABI and what the Rust crate does internally; the typed
C ABI (abi=c) stays available per-proc for later.

The two hand-written headers are deleted and nix packaging ships the
generated ones. The C examples target the old string ABI and removed
headers, so they no longer compile; each is annotated as awaiting a port
rather than left with a dangling include that pretends to work.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-16 11:33:20 +02:00

3.0 KiB

Raw Blame History

Building liblogosdelivery and Examples

Prerequisites

Nim 2.x compiler
Rust toolchain (for RLN dependencies)
GCC or Clang compiler
Make

Building the Library

Dynamic Library

make liblogosdelivery

This creates build/liblogosdelivery.dylib (macOS) or build/liblogosdelivery.so (Linux).

Static Library

nim liblogosdelivery STATIC=1

This creates build/liblogosdelivery.a.

Building Examples

liblogosdelivery Example

Compile the C example that demonstrates all library features:

# Using Make (recommended)
make liblogosdelivery_example

## Running Examples

```bash
./build/liblogosdelivery_example

The example will:

Create a Logos Messaging node
Register event callbacks for message events
Start the node
Subscribe to a content topic
Send a message
Show message delivery events (sent, propagated, or error)
Unsubscribe and cleanup

Build Artifacts

After building, you'll have:

build/
├── liblogosdelivery.dylib        # Dynamic library (34MB)
├── liblogosdelivery.dylib.dSYM/  # Debug symbols
└── liblogosdelivery_example      # Compiled example (34KB)

Library Headers

The C header is generated from the Nim source by nim-ffi, not hand-written:

nimble liblogosdeliveryGenBindingsC

This emits library/c_bindings/:

logosdelivery.h - the full C API (Messaging, Reliable Channels and the low-level waku_* kernel procs, in one file).
nim_ffi_cbor.h / nim_ffi_prelude.h - request/response payloads cross the boundary as CBOR blobs (the library's default ABI), and these helpers encode and decode them. logosdelivery.h includes them.

Regenerate whenever the {.ffi.} surface changes; the checked-in copy must match the Nim source.

Troubleshooting

Library not found at runtime

If you get "library not found" errors when running the example:

macOS:

export DYLD_LIBRARY_PATH=/path/to/build:$DYLD_LIBRARY_PATH
./build/liblogosdelivery_example

Linux:

export LD_LIBRARY_PATH=/path/to/build:$LD_LIBRARY_PATH
./build/liblogosdelivery_example

Cross-Compilation

For cross-compilation, you need to:

Build the Nim library for the target platform
Use the appropriate cross-compiler
Link against the target platform's liblogosdelivery

Example for Linux from macOS:

# Build library for Linux (requires Docker or cross-compilation setup)
# Then compile with cross-compiler

Integration with Your Project

CMake

find_library(LMAPI_LIBRARY NAMES lmapi PATHS ${PROJECT_SOURCE_DIR}/build)
include_directories(${PROJECT_SOURCE_DIR}/liblogosdelivery)
target_link_libraries(your_target ${LMAPI_LIBRARY})

Makefile

CFLAGS += -I/path/to/liblogosdelivery
LDFLAGS += -L/path/to/build -llmapi -Wl,-rpath,/path/to/build

your_program: your_program.c
	$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)

API Documentation

See:

liblogosdelivery.h - API function declarations
MESSAGE_EVENTS.md - Message event handling guide

3.0 KiB Raw Blame History