This guide walks plugin developers through building plugins for LogViewer using the official SDK.
Quick Start (5 Minutes)
1. Install LogViewer SDK
# Download or clone LogViewer
git clone https://github.com/yourname/LogViewer.git
cd LogViewer
# Build and install SDK
cmake -S . -B build -DBUILD_SDK=ON
cmake --install build --prefix ~/LogViewer_install
2. Build the Example Plugin
# Clone or navigate to the BasicPlugin example
cd examples/BasicPlugin
# Configure and build
cmake -S . -B build \
-DCMAKE_PREFIX_PATH=~/LogViewer_install/sdk/lib/cmake
cmake --build build
3. Run Your Plugin
Copy to LogViewer's plugin directory and restart LogViewer:
# Linux
mkdir -p ~/.local/share/LogViewer/plugins
cp build/libbasic_example.so ~/.local/share/LogViewer/plugins/
cp build/config.json ~/.local/share/LogViewer/plugins/
# Windows
mkdir %APPDATA%\LogViewer\plugins
copy build\basic_example.dll %APPDATA%\LogViewer\plugins\
copy build\config.json %APPDATA%\LogViewer\plugins\
Restart LogViewer, and you should see the Basic Example plugin loaded.
Detailed Guide
What is the LogViewer Plugin SDK?
The SDK provides:
- C-ABI Plugin Interface (
PluginC.h)
- Cross-platform, stable ABI (no C++ version mismatch issues)
- Supports all compilers and platforms
- Header-Only Plugin API Library
LogViewer::plugin_api CMake target
- Pure headers, zero runtime dependency
- Automatically includes all required dependencies via
find_package(LogViewer CONFIG)
- CMake Integration
LogViewerConfig.cmake handles all dependency discovery
- Plugin developers only need one
find_package() call
- Example and Documentation
- Basic Example plugin in
examples/BasicPlugin/
- Complete API headers with inline documentation
SDK Installation
Build from Source
git clone <logviewer-repo>
cd LogViewer
# With SDK support
cmake -S . -B build \
-DCMAKE_BUILD_TYPE=Release \
-DBUILD_SDK=ON
# Optional: limit builds to SDK only
cmake --build build --target install
# Install to custom location
cmake --install build --prefix ~/LogViewer_install
The SDK is installed to: ~/LogViewer_install/sdk/
SDK Contents
sdk/
├── include/ # Plugin API headers
│ ├── PluginC.h # Main plugin interface
│ ├── PluginEventsC.h # Event container access
│ ├── PluginHostUiC.h # Host UI callback hooks
│ ├── PluginLoggerC.h # Logger interface
│ ├── PluginTypesC.h # Common types
│ ├── PluginAIProviderC.h # AI provider interface (optional)
│ └── PluginKeyEncryptionC.h # Encryption interface (optional)
│
└── lib/cmake/
├── LogViewerConfig.cmake # Main config file
├── LogViewerPluginTargets.cmake # Target definitions
├── LogViewerPluginPackaging.cmake # ZIP packaging helpers
└── LogViewerConfigVersion.cmake # Version info
Creating Your First Plugin
Step 1: Minimal Plugin Structure
MyPlugin/
├── CMakeLists.txt
├── src/
│ └── MyPlugin.cpp
├── config.json.in
└── README.md
Step 2: Implement BasicPlugin.cpp
Minimum required exports:
#include <PluginC.h>
#include <cstdlib>
extern "C" {
return malloc(256);
}
free(h);
}
const char* Plugin_GetApiVersion(PluginHandle h) {
return LOGVIEWER_PLUGIN_API_VERSION;
}
const char*
json = R
"({"name":"MyPlugin","version":"1.0"})";
size_t len = strlen(
json);
char* copy = (char*)malloc(len + 1);
return copy;
}
bool Plugin_Initialize(PluginHandle h) {
return true;
}
void Plugin_Shutdown(PluginHandle h) {}
return strdup("No error");
}
}
EXPORT_PLUGIN_SYMBOL const char * Plugin_GetMetadataJson(PluginHandle pluginHandle)
Definition AIProviderPlugin.cpp:491
EXPORT_PLUGIN_SYMBOL PluginHandle Plugin_Create()
Definition AIProviderPlugin.cpp:350
EXPORT_PLUGIN_SYMBOL const char * Plugin_GetLastError(PluginHandle pluginHandle)
Definition AIProviderPlugin.cpp:515
EXPORT_PLUGIN_SYMBOL void Plugin_Destroy(PluginHandle h)
Definition AIProviderPlugin.cpp:365
EXPORT_PLUGIN_SYMBOL void Plugin_SetLoggerCallback(PluginHandle h, PluginLogFn logFn)
Definition AIProviderPlugin.cpp:358
nlohmann::json json
Definition FilterSerializer.cpp:9
#define EXPORT_PLUGIN_SYMBOL
Definition IPlugin.hpp:65
Step 3: CMakeLists.txt
cmake_minimum_required(VERSION 3.22)
project(MyPlugin)
# Find SDK - automatically provides Qt6, Threads, and optional libs
find_package(LogViewer CONFIG REQUIRED)
# Create plugin library
add_library(my_plugin MODULE src/MyPlugin.cpp)
# Link against plugin API
target_link_libraries(my_plugin PRIVATE LogViewer::plugin_api)
# Configure output
set_target_properties(my_plugin PROPERTIES PREFIX "")
# Generate config.json
configure_file(config.json.in config.json @ONLY)
Step 4: config.json.in
{
"id": "my_plugin",
"name": "My Plugin",
"version": "1.0.0",
"entry": "my_plugin.dll",
"api_version": "1.0.0",
"description": "My awesome plugin",
"capabilities": []
}
Step 5: Build
cmake -S . -B build \
-DCMAKE_PREFIX_PATH=/path/to/LogViewer_install/sdk/lib/cmake
cmake --build build
Understanding the Plugin Lifecycle
┌─────────────────────────────────────────┐
│ Host Application (LogViewer) │
└─────────────────────────────────────────┘
↓
Plugin_Create() [allocate state]
↓
Plugin_SetLoggerCallback [receive logger]
↓
Plugin_Initialize() [setup, return true/false]
↓
[Plugin active - can process events, create UI, etc.]
↓
Plugin_Shutdown() [cleanup, release resources]
↓
Plugin_Destroy() [deallocate state]
Important: Always use malloc() for any data returned to the host—the host will call free().
Using the Logger
In your plugin:
static PluginLogFn g_logger = nullptr;
g_logger = log;
}
void my_function() {
if (g_logger) {
g_logger(0, "Debug message");
g_logger(1, "Info message");
g_logger(2, "Warning message");
g_logger(3, "Error message");
}
}
Creating UI Panels
Implement any of these optional exports:
return panel;
}
void Plugin_DestroyLeftPanel(PluginHandle h, void* widget) {
}
EXPORT_PLUGIN_SYMBOL void * Plugin_CreateLeftPanel(PluginHandle pluginHandle, void *parentWidget, const char *)
Definition AIProviderPlugin.cpp:455
The host manages widget lifetimes but may call the Destroy function if provided.
Accessing Events
Use the Events Container API:
#include <PluginEventsC.h>
bool my_plugin_init(PluginHandle h) {
return true;
}
void analyze_events() {
int count = PluginEvents_GetSize();
for (int i = 0; i < count; ++i) {
char*
json = PluginEvents_GetEventJson(i);
PluginApi_FreeString(
json);
}
}
Dependencies
Automatically available after find_package(LogViewer CONFIG REQUIRED):
Always included:
- Qt6 (Core, Widgets)
- Threads
Available if built:
- nlohmann_json (header-only JSON)
- fmt (modern string formatting)
- CURL (HTTP client)
- spdlog (fast logging)
- LibArchive (archive handling)
- EXPAT (XML parsing)
Use them in your plugin:
find_package(nlohmann_json REQUIRED)
find_package(fmt REQUIRED)
target_link_libraries(my_plugin
PRIVATE
LogViewer::plugin_api
nlohmann_json::nlohmann_json
fmt::fmt
)
Platform Considerations
Windows (MinGW)
- Use forward slashes in paths:
C:/msys64/mingw64/
- Plugin extension:
.dll
- Set
CMAKE_PREFIX_PATH with forward slashes
Linux
- Plugin extension:
.so
- May need to link Qt plugins for GUI plugins
- Use standard CMake conventions
macOS
- Plugin extension:
.dylib
- Qt6 typically installed via Homebrew
- Code signing may be required for distribution
Distribution
Package plugins as ZIP archives:
my_plugin.zip
├── my_plugin.dll
├── config.json
└── lib/
├── Qt6Widgets.dll
├── Qt6Core.dll
└── ... (runtime dependencies)
Use LogViewerPluginPackaging.cmake for automated packaging:
include(LogViewerPluginPackaging)
# Bundles your plugin with dependencies into a ZIP
Debugging
View Plugin Loads
LogViewer logs plugin loads to:
- Windows:
APPDATA%/LogViewer/logs/
- Linux:
~/.local/share/LogViewer/logs/
- macOS:
~/Library/Logs/LogViewer/
Check logs if your plugin fails to load.
Missing config.json
Ensure config.json is in the same directory as your plugin binary with:
- Correct
entry field matching the binary name
- Valid JSON syntax
- Required fields:
id, name, version, entry, api_version
Symbol Visibility
Use EXPORT_PLUGIN_SYMBOL for all exported functions:
Best Practices
- Always use
malloc() for returned strings char* get_string() {
char* s = (char*)malloc(256);
strcpy(s, "data");
return s;
}
- Store state in opaque handles
struct MyState { ... };
return (PluginHandle)new MyState();
- Check callbacks before using them
if (g_logger) g_logger(0, "message");
- Implement proper error handling
bool Plugin_Initialize(PluginHandle h) {
if () {
last_error = "Reason for failure";
return false;
}
return true;
}
- Document your API in JSON
{
"name": "My Plugin",
"capabilities": [
"ui_panel_right",
"event_analysis"
],
"settings": {
"api_key": "string"
}
}
Examples
See examples/BasicPlugin/ for a complete working example with detailed comments.
API Reference
Core Functions
| Function | Purpose |
Plugin_Create() | Allocate plugin instance |
Plugin_Destroy(h) | Deallocate plugin instance |
Plugin_GetApiVersion(h) | Report SDK version |
Plugin_GetMetadataJson(h) | Return metadata JSON |
Plugin_Initialize(h) | Initialize after creation |
Plugin_Shutdown(h) | Cleanup before destroy |
Plugin_GetLastError(h) | Get last error message |
Plugin_SetLoggerCallback(h, fn) | Receive logger function |
Optional UI Functions
| Function | Purpose |
Plugin_CreateLeftPanel(h, parent, json) | Create left panel widget |
Plugin_CreateRightPanel(h, parent, json) | Create right panel widget |
Plugin_CreateBottomPanel(h, parent, json) | Create bottom panel widget |
Plugin_CreateMainPanel(h, parent, json) | Create main panel widget |
See PluginC.h for complete documentation.
Next Steps
- Build the BasicPlugin example
- Modify it to add your own functionality
- Create a UI panel using Qt6
- Access log events via the Events API
- Package and distribute your plugin
Support
- Documentation: See
docs/ directory
- Example:
examples/BasicPlugin/
- Headers:
src/plugin_api/
- Issues: File issues on the repository
License
Plugins built with this SDK are governed by the LogViewer license. See LICENSE file.