Installation & CLI Reference

Flame provides an all-in-one developer workspace toolchain containing a compiler, an automated code formatter, diagnostics engine, and a Smart ABI plugin system for seamless Rust interop.

---

Installation

Quick Install (Recommended)

Choose your operating system and preferred shell to install Flame and the Blaze toolchain:

Windows (PowerShell)

Run in Windows PowerShell (Standard or Administrator):

powershell

irm https://raw.githubusercontent.com/sohamglx/flame/main/install.ps1 | iex

Or from a local cloned repository:

powershell

.\install.ps1

Linux & macOS (Bash)

Run the universal bash script (Linux, macOS, and Windows via Git Bash / WSL / MSYS):

bash

curl -fsSL https://raw.githubusercontent.com/sohamglx/flame/main/install.sh | bash

Or from a local cloned repository:

bash

bash install.sh

Linux Prerequisites

Native hardware, Bluetooth, and camera capabilities require development headers for dbus, udev, and libclang (used by bindgen for video devices). The installer will attempt to install these automatically, or you can install them manually:

• Debian / Ubuntu / WSL: sudo apt-get update && sudo apt-get install -y build-essential pkg-config libdbus-1-dev libudev-dev libclang-dev clang
• Fedora / RHEL: sudo dnf install -y gcc gcc-c++ pkgconf-pkg-config dbus-devel systemd-devel clang-devel
• Arch Linux: sudo pacman -S --noconfirm base-devel pkgconf dbus systemd-libs clang

What the installer does

The installer automatically builds flame (and flamelang), registers the fmp binary command in your permanent User PATH, and provisions the canonical Blaze/std definition interface directory into your system programs folder (e.g. C:\Program Files\Blaze or ~/.blaze) for instant Go-to-Definition and IDE LSP support.

---

Verifying the Installation

Check that fmp is accessible from your terminal:

bash

fmp --version

To view the complete help menu and all available flags:

bash

fmp --help

---

Project Structure & Manifest

Run fmp init <project_name> to create a new Flame project:

A standard Flame project contains a flame.toml manifest file and source code in src/:

my-flame-app/
├── flame.toml           # Project manifest, native crates & plugins
└── src/
    └── main.fm          # Application entrypoint

Manifest Example (flame.toml)

[package]
name = "my_flame_app"
version = "0.1.0"
entry = "src/main.fm"

[native-dependencies]
uuid = { version = "1.0", features = ["v4"] }
axum = "0.7"

[plugins]
server = "./native"

Just like a normal Cargo.toml, users can configure native crate features and version specifications manually by editing flame.toml.

---

CLI & Toolchain Reference

The fmp cli provides a unified command set for your entire development workflow:

1. Running & Building Applications

⚡ Quick-Run (fmp)

Inside any Flame project directory (where flame.toml is present), simply type fmp and press enter to instantly compile and run your application entry point:

bash

fmp

fmp run

Runs the Flame entry file main.fm:

bash

fmp run

fmp build

Constructs an application-specific native runtime containing only the packages, standard library features, and native plugins imported by your project. It compiles the specialized runtime via Rust/Cargo/LLVM into an executable:

bash

# Debug build in target/dev/ (uses normal filesystem, no VFS)
fmp build

# Release build in target/release/ (uses normal filesystem, no VFS)
fmp build --release

Normal Filesystem Execution

Standard fmp build and fmp build --release execute against the real filesystem and do not use VFS. Unused packages and runtime components are excluded from the binary.

fmp build --exe / fmp build --vfs --release (Single Executable Mode)

When you require a self-contained single executable that bundles all application source files, packages, and .fmi interfaces directly inside the binary, pass --exe or --vfs:

bash

# Self-contained single executable with embedded VFS
fmp build --exe

# Optimized production single executable with embedded VFS
fmp build --exe --release
# or
fmp build --vfs --release

VFS Is an Optional Packaging Mechanism

VFS is used only when explicitly requesting a self-contained single binary (--exe or --vfs). Normal builds operate directly on the real host filesystem.

---

2. Package & Native Plugin Management

fmp install

Resolves and installs all dependencies declared in flame.toml:

bash

fmp install

Flame downloads package repositories from their configured GitHub/registry sources, caches them in .flame/pkg/, and ensures .fmi interface metadata is generated for all packages with native plugins. Developers never manually copy Rust source or Cargo projects into the application.

fmp new <name>

Initializes a new Flame workspace directory with a starter manifest and directory structure:

bash

fmp new my_app

fmp new --plugin <name> / fmp new -p <name>

Scaffolds a native Rust plugin workspace (./native) inside your current project. It creates a starter Cargo.toml, bridge boilerplate code, and automatically registers the plugin in your flame.toml (alias: fmp native init):

bash

fmp new --plugin server
# or shorthand:
fmp new -p server

Note on Naming: The Flame package name (in flame.toml) and the native plugin name (in native/Cargo.toml) must be different. Using the same name causes Cargo workspace naming conflicts and linkage errors.

fmp add <url_or_name>

Downloads and registers external Flame modules or packages into flame.toml:

bash

fmp add https://github.com/example/flame-package

fmp add --native <crate_name> / fmp add -n <crate_name>

Adds a Rust crate as a native dependency under [native-dependencies] in your flame.toml:

bash

fmp add --native uuid
# or shorthand:
fmp add -n uuid

Just like a normal Cargo.toml, users can configure crate features manually by editing flame.toml:

[native-dependencies]
uuid = { version = "1.0", features = ["v4"] }

fmp add --plugin <path_to_plugin> / fmp add -p <path_to_plugin>

Registers an existing local or external native Rust plugin inside your flame.toml manifest. Flame automatically discovers the plugin name from its Cargo.toml, so --name is not required:

bash

fmp add --plugin ./native
# or shorthand:
fmp add -p ./native

---

3. Diagnostics & IDE Integration (check --json)

fmp check <file.fm> [--json] [--line N --col N]

Performs instantaneous syntactic analysis, type inference, and static diagnostics without compiling or linking binaries.

When invoked with --json, it emits structured metadata designed for IDEs and the Language Server Protocol (LSP):

• Precision Hover Metadata: Passing --line N --col N resolves the exact AST symbol under the cursor, returning inferred primitive types, native .fmi struct signatures, and identifying native AOT packages as plugin (e.g. server: plugin).
• Autocomplete & IntelliSense: Extracts methods, parameters, docstrings, and struct layouts from standard libraries (std.*) and native plugins (native.*).
• Real-Time Diagnostics: Emits syntax errors, undefined symbols, and type mismatches with exact line and column numbers.

Example Command & JSON Payload

bash

fmp check automation/src/main.fm --json --line 47 --col 18

{
  "file": "automation/src/main.fm",
  "diagnostics": [],
  "std_modules": ["thread", "process", "fs", "math", "time", "os", "env"],
  "native_modules": ["server"],
  "plugins": [
    {
      "name": "server",
      "source": "./native",
      "version": null,
      "is_local": true
    }
  ],
  "completions": [],
  "hover": {
    "label": "server",
    "documentation": "```flame\nserver: plugin\n```\nInferred type from AST"
  }
}

---

4. Code Formatting

fmp format <file.fm>

Automatically formats your source code to adhere to Flame’s canonical style rules:

bash

# Format a specific file and write changes
fmp format src/main.fm

# Output formatted code to stdout without writing
fmp format src/main.fm --stdout

fmp format --all

Formats all .fm source files across your entire project workspace:

bash

fmp format --all
# or simply:
fmp format

---

5. Native Test Runner

fmp test

Discovers and executes all @Test annotated functions across your project files:

bash

fmp test

---

6. Updating & Toolchain Maintenance

fmp update

Automatically updates your Flame compiler to the latest published release on Cargo (crates.io), synchronizes the fmp binary alias, and keeps your toolchain current:

bash

fmp update

fmp uninstall

Removes the Flame compiler binaries (fmp, flamelang) from your Cargo environment and purges the installed Blaze standard library definition directories:

bash

fmp uninstall