Morphir Rust

Rust-based tooling for the Morphir ecosystem. This project provides a multi-crate workspace including a CLI tool and core libraries for working with Morphir IR (Intermediate Representation).

Overview

Morphir Rust is part of the Morphir ecosystem, which includes:

• finos/morphir - Core Morphir specification
• finos/morphir-elm - Reference implementation (Elm)
• finos/morphir-jvm - JVM implementation
• finos/morphir-scala - Scala implementation
• finos/morphir-dotnet - .NET implementation

Project Structure

This is a Rust workspace containing multiple crates:

• morphir - CLI tool for working with Morphir IR
• morphir-ir - Core IR model definitions and utilities
• morphir-common - Shared utilities (remote sources, caching)

Prerequisites

• Rust (latest stable version recommended)
• Cargo (comes with Rust)

Installation

Using cargo-binstall (Recommended)

The fastest way to install pre-built binaries:

# Install cargo-binstall if you don't have it
cargo install cargo-binstall

# Install morphir
cargo binstall morphir

Using mise

mise install morphir

Building from Source

# Clone the repository
git clone https://github.com/finos/morphir-rust.git
cd morphir-rust

# Build the project
cargo build --release

# Install the CLI tool
cargo install --path crates/morphir

Usage

Getting Help

# Show help
morphir --help

# Show help including experimental commands
morphir --help-all
morphir help --full
morphir help --experimental

# Show version
morphir --version

IR Migration

Convert Morphir IR between format versions (Classic V1-V3 ↔ V4):

# Migrate local file to V4 format
morphir ir migrate --input ./morphir-ir.json --output ./morphir-ir-v4.json

# Migrate from remote URL
morphir ir migrate \
    --input https://lcr-interactive.finos.org/server/morphir-ir.json \
    --output ./lcr-v4.json

# Migrate from GitHub
morphir ir migrate \
    --input github:finos/morphir-examples@main/examples/basic/morphir-ir.json \
    --output ./example-v4.json

# Migrate to Classic format
morphir ir migrate \
    --input ./morphir-ir-v4.json \
    --output ./morphir-ir-classic.json \
    --target-version classic

See IR Migrate Documentation for full details.

JSON Schema Generation

Generate JSON Schema for Morphir IR validation:

# Output to stdout
morphir schema

# Output to file
morphir schema --output ./morphir-ir-schema.json

Tool Management

Manage Morphir tools, distributions, and extensions:

# Tools
morphir tool install <tool-name> [--version <version>]
morphir tool list
morphir tool update <tool-name> [--version <version>]
morphir tool uninstall <tool-name>

# Distributions
morphir dist install <dist-name> [--version <version>]
morphir dist list
morphir dist update <dist-name>
morphir dist uninstall <dist-name>

# Extensions
morphir extension install <extension-name> [--version <version>]
morphir extension list
morphir extension update <extension-name>
morphir extension uninstall <extension-name>

Experimental Commands

The following commands are experimental and hidden by default. Use --help-all to see them:

# Validate Morphir IR (experimental)
morphir validate --input ./morphir-ir.json

# Generate code (experimental)
morphir generate --target rust --input ./morphir-ir.json --output ./output

# Transform IR (experimental)
morphir transform --input ./morphir-ir.json --output ./transformed.json

Documentation Generation

Generate man pages, markdown documentation, and shell completions:

# Install usage CLI (required for doc generation)
mise install usage

# Generate all documentation
mise run docs:generate

# Generate specific types
mise run docs:man          # Man pages
mise run docs:markdown     # Markdown docs
mise run docs:completions  # Shell completions

Development Setup

# Install Rust toolchain (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and navigate to the project
git clone https://github.com/finos/morphir-rust.git
cd morphir-rust

# Build the project
cargo build

# Run tests
cargo test

# Run the CLI
cargo run --bin morphir -- --help

# Format code
cargo fmt

# Check for linting issues
cargo clippy

Mise Tasks

This project uses mise for task automation:

# List available tasks
mise tasks

# Run checks
mise run check:fmt    # Format check
mise run check:lint   # Lint check

# Documentation
mise run docs:generate     # Generate all docs
mise run docs:man          # Man pages only
mise run docs:markdown     # Markdown only
mise run docs:completions  # Shell completions

# Release management
mise run release:check     # Pre-release checks
mise run release:version-bump <version>
mise run release:changelog-validate

Design Principles

This project follows Functional Domain Modeling principles:

• Immutability: Data structures are immutable by default
• Type Safety: Strong typing throughout the codebase
• Composability: Functions and data structures are designed to compose
• Purity: Functions are pure where possible, with clear separation of side effects

Contributing

1. Fork it (https://github.com/finos/morphir-rust/fork)
2. Create your feature branch (git checkout -b feature/fooBar)
3. Read our contribution guidelines and Community Code of Conduct
4. Commit your changes (git commit -am 'Add some fooBar')
5. Push to the branch (git push origin feature/fooBar)
6. Create a new Pull Request

NOTE: Commits and pull requests to FINOS repositories will only be accepted from those contributors with an active, executed Individual Contributor License Agreement (ICLA) with FINOS OR who are covered under an existing and active Corporate Contribution License Agreement (CCLA) executed with FINOS. Commits from individuals not covered under an ICLA or CCLA will be flagged and blocked by the FINOS Clabot tool (or EasyCLA). Please note that some CCLAs require individuals/employees to be explicitly named on the CCLA.

Need an ICLA? Unsure if you are covered under an existing CCLA? Email help@finos.org

License

Copyright 2022 FINOS

Distributed under the Apache License, Version 2.0.

SPDX-License-Identifier: Apache-2.0