The core runtime library for the Logos modular application platform. Provides liblogos_core (a C-API shared library) and logos_host (the module subprocess host binary).

logos-liblogos is a library. It is consumed by two frontends:

logos-basecamp — the desktop GUI application shell
logos-logoscore-cli — the headless CLI runtime (logoscore)

How to Build

The project uses a Nix flake for reproducible builds with a modular structure:

Build Complete Library (Binaries + Libraries + Headers)

# Build everything (default)
nix build

# Or explicitly
nix build '.#logos-liblogos'
nix build '.#default'

The result will include:

/bin/ - Host binary (logos_host)
/lib/ - Core library (liblogos_core)
/include/ - Headers (logos_core.h, interface.h)

Build Individual Components

# Build only the binaries (outputs to /bin)
nix build '.#logos-liblogos-bin'

# Build only the libraries (outputs to /lib)
nix build '.#logos-liblogos-lib'

# Build only the headers (outputs to /include)
nix build '.#logos-liblogos-include'

# Build and run tests
nix build '.#logos-liblogos-tests'

# Build portable variant (selects portable LGX variants instead of dev)
nix build '.#portable'

Running Tests

# Build and run tests (tests run automatically during build)
nix build '.#logos-liblogos-tests'

# To run tests manually after building:
./result/bin/logos_core_tests

# Run specific tests
./result/bin/logos_core_tests --gtest_filter=AppLifecycleTest.*

# List all available tests
./result/bin/logos_core_tests --gtest_list_tests

Development Shell

# Enter development shell with all dependencies
nix develop

Note: In zsh, you need to quote targets with # to prevent glob expansion.

If you don't have flakes enabled globally, add experimental flags:

nix build '.#logos-liblogos' --extra-experimental-features 'nix-command flakes'

The compiled artifacts can be found at result/

Modular Architecture

The nix build system is organized into modular files in the /nix directory:

nix/default.nix - Common configuration (dependencies, flags, metadata)
nix/build.nix - Shared build that compiles everything once
nix/bin.nix - Extracts binaries (logos_host, includes libraries for runtime linking)
nix/lib.nix - Extracts libraries only
nix/include.nix - Header installation
nix/tests.nix - Test suite build and execution

Note: The logos-liblogos-bin package includes both the logos_host binary and its required libraries to ensure proper runtime linking.

Local Development

To use a local logos-cpp-sdk repo:

nix build --override-input logos-cpp-sdk path:../logos-cpp-sdk

Library API

logos-liblogos exposes a C API via logos_core.h:

// Lifecycle
void logos_core_init(int argc, char *argv[]);
void logos_core_start();
int  logos_core_exec();
void logos_core_cleanup();

// Plugin directory management
void logos_core_set_plugins_dir(const char* dir);
void logos_core_add_plugins_dir(const char* dir);

// Plugin management
int  logos_core_load_plugin(const char* name);
int  logos_core_load_plugin_with_dependencies(const char* name);
int  logos_core_unload_plugin(const char* name);
char* logos_core_process_plugin(const char* path);
void logos_core_refresh_plugins();

// Plugin queries
char** logos_core_get_loaded_plugins();
char** logos_core_get_known_plugins();

// Module stats and tokens
char* logos_core_get_module_stats();
char* logos_core_get_token(const char* key);

// Event loop integration
void logos_core_process_events();

See src/logos_core/logos_core.h for the full API.

Dev vs Portable Builds

The library supports two build modes controlled by the LOGOS_PORTABLE_BUILD CMake flag:

Dev build (default): Plugin loading looks for LGX variants with -dev suffix (e.g., linux-amd64-dev). Used in Nix/development environments.
Portable build (-DLOGOS_PORTABLE_BUILD=ON): Looks for portable variants without suffix (e.g., linux-amd64). Used in self-contained distributed applications.

Build the portable variant with nix build '.#portable'.

Supported Platforms

macOS (aarch64-darwin, x86_64-darwin)
Linux (aarch64-linux, x86_64-linux)