Guide Package Manager

Package Manager Guide

ARO includes a Git-based package manager for installing and managing plugins.

Installation Commands

Install a Plugin

aro add <git-url>[@ref]

Examples:

# Install from Git URL
aro add git@github.com:arolang/plugin-swift-hello.git

# Install specific version
aro add git@github.com:arolang/plugin-rust-csv.git@v1.0.0

# Install from branch
aro add git@github.com:arolang/plugin-python-markdown.git@main

Remove a Plugin

aro remove <plugin-name>

Example:

aro remove plugin-swift-hello

Plugin Management Commands

List Installed Plugins

aro plugins list

Update All Plugins

aro plugins update

Validate Plugins

Check that all installed plugins are valid and dependencies are satisfied:

aro plugins validate

Export Plugin Sources

Export plugin source URLs to .aro-sources file (useful for version control):

aro plugins export

Restore Plugins

Restore plugins from .aro-sources file:

aro plugins restore

Plugin Directory Structure

Plugins are installed in the Plugins/ directory:

MyApp/
├── main.aro
├── openapi.yaml
└── Plugins/
    ├── plugin-swift-hello/
    │   ├── plugin.yaml
    │   ├── Sources/
    │   └── features/
    └── plugin-rust-csv/
        ├── plugin.yaml
        ├── Cargo.toml
        └── src/

The plugin.yaml Manifest

Every plugin requires a plugin.yaml manifest:

name: my-plugin
version: 1.0.0
description: "Plugin description"
author: "Author Name"
license: MIT
aro-version: ">=0.1.0"

source:
  git: "git@github.com:user/my-plugin.git"
  ref: "main"

provides:
  - type: aro-files
    path: features/
  - type: swift-plugin
    path: Sources/

dependencies:
  other-plugin:
    git: "git@github.com:arolang/other-plugin.git"
    ref: "v1.0.0"

Required Fields

Field	Description
name	Plugin name (lowercase, hyphens allowed)
version	Semantic version (e.g., "1.0.0")
provides	List of components this plugin provides

Provide Types

Type	Description
aro-files	ARO feature set files
swift-plugin	Swift package
rust-plugin	Rust library (FFI)
c-plugin	C/C++ library (FFI)
cpp-plugin	C++ library (FFI)
python-plugin	Python module

Plugin Languages

ARO supports plugins in multiple languages:

ARO Files

Pure ARO feature sets that can be reused:

provides:
  - type: aro-files
    path: features/

Swift Plugins

Native Swift integration with the ARO runtime:

provides:
  - type: swift-plugin
    path: Sources/

build:
  swift:
    minimum-version: "6.2"

Rust Plugins

High-performance plugins via FFI:

provides:
  - type: rust-plugin
    path: src/
    build:
      cargo-target: release
      output: target/release/libplugin.dylib

C/C++ Plugins

System-level plugins via FFI:

provides:
  - type: c-plugin
    path: src/
    build:
      compiler: clang
      flags: ["-O2", "-fPIC", "-shared"]
      output: libplugin.dylib

Python Plugins

Access to Python's ecosystem:

provides:
  - type: python-plugin
    path: src/
    python:
      min-version: "3.9"
      requirements: requirements.txt

Plugin Dependencies

Plugins can depend on other plugins:

dependencies:
  string-helpers:
    git: "git@github.com:arolang/plugin-string-helpers.git"
    ref: "v1.0.0"

Dependencies are automatically resolved and installed in the correct order.

Plugin Lifecycle: Unload and Reload

Plugins can be unloaded and reloaded at runtime without restarting the application. This is useful for hot-reloading during development or swapping plugin implementations dynamically.

Unloading a Plugin

When a plugin is unloaded, all actions and qualifiers it registered are automatically deregistered:

• Dynamic action verbs are removed from ActionRegistry
• Qualifiers are removed from QualifierRegistry
• For C/Rust plugins, the native library handle is closed (dlclose)
• If the plugin was not loaded, unload is a no-op and returns false

Reloading a Plugin

Reloading performs an unload followed by a fresh load from the same directory, picking up any changes to the plugin binary or source files. If the plugin was never loaded, reload throws UnifiedPluginError.notFound.

Action Ownership Tracking

Dynamic plugin actions are tracked by plugin name. When unregisterPlugin is called, only the actions belonging to that plugin are removed — other plugins are not affected:

(* Actions from csv-processor are registered *)
Compute the <result: csv-processor.parse-csv> from the <input>.

(* After unloading csv-processor, the action is removed *)
(* Other plugins remain unaffected *)

---

Example Plugins

The ARO team maintains example plugins:

Plugin	Language	Purpose
plugin-swift-hello	Swift	Greeting actions
plugin-rust-csv	Rust	CSV parsing
plugin-c-hash	C	Hash functions
plugin-python-markdown	Python	Markdown processing

Creating Your Own Plugin

See Guide: Creating Plugins for detailed instructions on creating plugins.

Related Topics

• Guide: Actions
• Guide: Services
• Action Developer Guide