logos-messaging-nim/library/BUILD.md

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:

1. Create a Logos Messaging node
2. Register event callbacks for message events
3. Start the node
4. Subscribe to a content topic
5. Send a message
6. Show message delivery events (sent, propagated, or error)
7. 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 API is tiered across two headers (one library, two stability promises):

• library/liblogosdelivery.h - stable, supported Messaging / Reliable Channels API. This is the front door for consumers.
• library/liblogosdelivery_kernel.h - advanced, low-level kernel API (waku_*). "Use at your own risk", may change at any time. Including it is a deliberate opt-in; it pulls in liblogosdelivery.h for shared types.

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:

1. Build the Nim library for the target platform
2. Use the appropriate cross-compiler
3. 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