Installation Guide

Gram is a 100% pure-Python framework with zero external C or third-party runtime dependencies (requiring Python 3.10+).

Because Gram does not rely on PyPI packaging metadata (pyproject.toml / setup.py), it is designed to be installed and isolated via VNMA (Vendor Manager) or consumed directly via Git and PYTHONPATH.

1. Installing with VNMA (Recommended)

VNMA vendors dependencies directly into a local vendor/ directory inside your project, providing hermetic sys.path isolation, lockfile reproducibility (vnma.lock), and automatic IDE path configuration for VS Code and PyCharm without duplicating full Python virtual environments.

[!NOTE] Gram includes a native vnma_config.toml at the root of its repository (name = "gram-framework2.0.0b2", packname = "gram", modules = ["gram"]). When installed or linked via VNMA, you can import gram directly (import gram or from gram import lexer, parser, combinators) from any module in your project.

Any questions, CLI usage details, or troubleshooting regarding VNMA itself belong to the official VNMA documentation: https://github.com/GrandKenzy/vnma.

A. Configuring vnma.toml in Your Project

In your project's root vnma.toml, declare Gram under [dependencies]. You can install Gram from a remote GitHub branch, pin it to an immutable Git release tag (such as v2.0.0b2), or link a local clone for real-time editable development:

[project]
name = "my-compiler"
version = "0.1.0"

[dependencies]

# Option 1: From GitHub (pinned to the v2.0.0b2 beta tag - recommended for reproducible builds)
gram-framework = { git = "https://github.com/GrandKenzy/Gram.git", tag = "v2.0.0b2" }

# Option 2: From GitHub (tracking the main branch)
# gramv2.0.0b = { git = "https://github.com/GrandKenzy/Gram.git", branch = "main" }

# Option 3: From a local directory (requires cloning Gram locally; reflects changes in real time)
# gram = { path = "~/Desktop/Gram", editable = true }

[dev-dependencies]

[tool.vnma]
vendor_dir = "vendor"
ide_integration = ["vscode", "pycharm"]

B. Installing and Running via VNMA CLI

Once vnma.toml is configured, run:

# Resolve and vendor dependencies into ./vendor and generate vnma.lock:
vnma install

Or use vnma CLI commands directly:

# Install directly from the GitHub repository (main branch or v2.0.0b2 tag):
vnma install git+https://github.com/GrandKenzy/Gram.git@v2.0.0b2

# Or create a zero-copy live development link to a local Gram clone:
vnma link "~/Desktop/Gram"

Execute your compiler or script inside the isolated VNMA runtime:

vnma run main.py

2. Installing via Git and Release Tags (Manual)

If you are not using VNMA, you can clone the repository directly from GitHub and check out a specific release tag.

A. Clone the Repository and Checkout a Tag

# Clone the repository:
git clone https://github.com/GrandKenzy/Gram.git
cd Gram

# List available release tags:
git tag -l

# Checkout the v2.0.0b2 beta release tag:
git checkout v2.0.0b2

Alternatively, clone the v2.0.0b2 tag directly in a single step:

git clone --branch v2.0.0b2 --depth 1 https://github.com/GrandKenzy/Gram.git

B. Expose gram on PYTHONPATH

Add the cloned Gram directory to your PYTHONPATH before running your Python scripts:

PowerShell (Windows):

$env:PYTHONPATH = "C:\path\to\Gram"
python -m gram

Bash (Linux / macOS):

export PYTHONPATH="/path/to/Gram"
python3 -m gram

C. Verify the Installation

Running python -m gram (or checking gram.version() in Python) prints the installed version:

Gram Framework v2.0.0b2

import gram

print(gram.__version__)       # "2.0.0b2"
print(gram.__version_info__)  # (2, 0, 0, 'beta', 2)