Getting Started with Library Integration

Getting Started

This guide walks you through integrating the arxo-engine library into your project.

Prerequisites

• Rust: Rust 1.75+ (for arxo-loader) or a C-compatible toolchain (for FFI)
• License: Valid license key or free tier eligibility if required by your deployment
• Basic understanding of your build system and how to load a shared library (for FFI)

Installation

Rust

Add to your Cargo.toml:

[dependencies]
arxo-types = "0.1"  # Config and shared types (MIT)
arxo-loader = "0.1" # Dynamic loader for closed-source engine

The engine library is loaded at runtime from ARCH0_ENGINE_PATH, the same directory as your binary, ~/.cache/arxo/engine/ (by version), or downloaded from the CDN if not found. See arxo-loader for details.

Other Languages (via FFI)

Download the pre-compiled library for your platform:

# Linux (x86_64)
curl -L https://releases.arxo.dev/latest/linux-x86_64/libarxo_engine.so -o libarxo_engine.so

# macOS (ARM64)
curl -L https://releases.arxo.dev/latest/macos-arm64/libarxo_engine.dylib -o libarxo_engine.dylib

# Windows (x86_64)
curl -L https://releases.arxo.dev/latest/windows-x86_64/arxo_engine.dll -o arxo_engine.dll

License Setup

Free Tier (Open Source Projects)

No license key required if:

• Your project is public on GitHub/GitLab with an OSI-approved license
• The engine automatically detects and verifies your project

Trial License

For evaluation, obtain a trial key from the Arxo website or support, then:

export ARCH0_LICENSE_KEY="your-trial-key"

Commercial License

Contact sales@arxo.dev for:

• Team licenses (5+ developers)
• Enterprise features
• Priority support

Set your license key:

# Environment variable (recommended)
export ARCH0_LICENSE_KEY="your-license-key"

# Or in config file
echo "license_key: your-license-key" > ~/.arxo/license.yml

Basic Usage

Rust

Use arxo-loader to load the engine and arxo-types for the Config type. You pass a path, config, and optional license; the result is an AnalysisResult with a single json string. Parse that JSON to get metric results and policy violations.

use arxo_loader::EngineLibrary;
use arxo_types::config::schema::Config;
use std::path::Path;

fn main() -> Result<(), arxo_loader::LoadError> {
    let engine = EngineLibrary::load()?;
    let path = Path::new("./my-project");
    let config = Config {
        source: None,
        data: None,
        architecture: None,
        metrics: None,
        metric_preset: Some("quick".to_string()),
        policy: None,
        report: None,
        run_options: None,
    };

    let result = engine.analyze(path, &config, None)?;
    // result.json is the full result; parse with serde_json to get results and violations
    println!("Result (first 500 chars): {}...", &result.json[..result.json.len().min(500)]);
    Ok(())
}

See Rust API for parsing the result JSON and full config options.

Other languages (FFI)

From C, Go, Zig, or any language with C FFI, load the engine library and call:

• arxo_version() — returns version string (free with arxo_free_string)
• arxo_analyze(path, config_json, license) — returns JSON string or NULL (free with arxo_free_string)
• arxo_free_string(s) — free returned strings

See FFI API for the exact signatures and examples.

Verify Installation

Rust

Run a simple test to verify the engine loads:

use arxo_loader::EngineLibrary;

#[test]
fn test_engine_loads() {
    let engine = EngineLibrary::load().expect("Failed to load engine");
    let version = engine.version();
    println!("Engine version: {}", version);
}

Configuration

The engine is configured via the Config type from arxo-types (Rust) or a JSON string with the same schema (FFI). Common options:

• metric_preset — e.g. "quick", "ci", "full" (replaces explicit metrics list)
• data — language, import_graph (exclude, group_by), call_graph, git_history, etc.
• policy — rules to evaluate (metric, operator, threshold)
• report — format and file
• run_options — disable_cache, incremental, quiet

You can load config from a YAML file and serialize to JSON for FFI, or build Config in Rust and pass it to analyze. See Configuration Reference for the full schema.

Next Steps

• Examples - Common operations and sample integrations
• Configuration - Full config reference
• Rust API and FFI API - API reference
• Troubleshooting - Common issues

Common Issues

Engine Not Found

Error: Failed to load arxo-engine: library not found

Solution: Ensure the engine library is available. The loader looks for it in (in order): ARCH0_ENGINE_PATH, same directory as your binary, ~/.cache/arxo/engine/ (by version), then CDN. Set ARCH0_ENGINE_PATH to the directory containing the library file, or place the library next to your binary.

License Validation Failed

Error: Invalid or expired license

Solution:

1. Verify license key: echo $ARCH0_LICENSE_KEY
2. For open source / free tier, ensure your deployment is eligible per your license terms

Platform Not Supported

Error: No pre-built binary for your platform

Solution: Contact support@arxo.dev for custom builds. Supported platforms:

• Linux: x86_64, ARM64
• macOS: x86_64, ARM64 (Apple Silicon)
• Windows: x86_64

Support

Need help?

• Troubleshooting Guide
• GitHub Discussions
• Discord Community
• Email: support@arxo.dev (enterprise customers)