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 *)

---

REPL Plugin Management

Plugins can be installed and loaded directly from the REPL using the /plugin (or :plugin) command. This lets you experiment with plugins interactively without modifying your project.

Installing a Plugin in the REPL

aro> /plugin add git@github.com:arolang/plugin-swift-hello.git
Plugin 'plugin-swift-hello' v1.0.0 installed and loaded (commit: a3f9c21)
  [+] Swift sources ready
Actions: Greet

aro> /plugin add git@github.com:arolang/plugin-rust-csv.git --ref v2.0.0
Plugin 'plugin-rust-csv' v2.0.0 installed and loaded (commit: 7b2e4f1)
  [+] Rust plugin built
Actions: ParseCSV, FormatCSV

Once loaded, the plugin's actions and qualifiers are immediately available:

aro> Greet the <message> with "World".
=> "Hello, World!"

Listing Loaded Plugins

aro> /plugin list
Name              | Version | Handle      | Status
------------------|---------|-------------|-------
plugin-swift-hello | 1.0.0  | Hello       | loaded
plugin-rust-csv    | 2.0.0  | CSV         | loaded

Removing a Plugin

Unload a plugin from the current REPL session:

aro> /plugin remove plugin-swift-hello
Plugin 'plugin-swift-hello' unloaded

Where Are REPL Plugins Stored?

REPL-installed plugins are stored in ~/.aro/repl-plugins/Plugins/. They persist across REPL sessions, so you don't need to reinstall them each time.

Command Prefix

All REPL commands work with both : and / prefixes:

aro> :plugin list    # Works
aro> /plugin list    # Also works

---

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: Services for detailed instructions on creating plugin services.

Related Topics

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