Boxlang 1.x Stable Released
BoxLang : A Modern Dynamic JVM Language
DownloadTrySourceSupport
Edit

BoxLang Version Manager (BVM)

BVM is a simple version manager for BoxLang, similar to jenv or nvm. It allows you to easily install, manage, and switch between different versions of BoxLang.

BoxLang Version Manager

BVM is an advanced version manager for BoxLang, similar to jenv or nvm. It allows you to easily install, manage, and switch between different versions of BoxLang.

🆚 BVM vs Single-Version Installer

Choose BVM if you:

  • 🔄 Work on multiple projects that might need different BoxLang versions

  • 🧪 Want to test your code against different BoxLang releases

  • 🚀 Need to switch between stable and snapshot versions

  • 📦 Want centralized management of BoxLang installations

  • 🛠️ Are a BoxLang developer or advanced user

Choose the single-version installer (install-boxlang.sh) if you:

  • 📌 Only need one BoxLang version system-wide

  • 🎯 Want the simplest possible installation

  • 🏢 Are setting up production servers with a specific BoxLang version

  • ⚡ Want the fastest installation with minimal overhead

Both installers provide identical functionality:

  • ✅ Same BoxLang runtime and MiniServer

  • ✅ Same helper scripts (install-bx-module, install-bx-site, etc.)

  • ✅ Same command-line tools (boxlang, bx, boxlang-miniserver, etc.)

  • ✅ Same installation quality and reliability

The only difference is that BVM adds version management capabilities on top.

📋 Table of Contents

🛠️ Features

  • 📦 Install complete BoxLang environment - runtime, MiniServer, and helper scripts

  • 🔄 Switch between versions easily - change your active BoxLang version with one command

  • 📋 List installed versions - see what's installed locally with bvm list or bvm ls

  • 🌐 List remote versions - see what's available for download with bvm list-remote or bvm ls-remote

  • 🗑️ Clean Removal - remove versions you no longer need with bvm remove, or bvm rm

  • 🔍 Health check - verify your BVM installation with bvm doctor or bvm health

  • 🧹 Cache management - clean up downloaded files with bvm clean

  • 🚀 Execute BoxLang components - run BoxLang, MiniServer through BVM with version management

  • 🔗 Seamless integration - wrapper scripts make all tools available in PATH

  • ⚡ Command aliases - convenient short aliases for all major commands

  • 🛠️ Helper script integration - all BoxLang helper scripts work with active version

  • 🎯 Smart version detection - automatically detects actual version numbers from installations

  • 🆙 Built-in update checker - check for BVM updates and upgrade easily

  • ☕ Automatic Java installation - installs Java 21 JRE if needed with --with-jre option

  • 🗑️ Uninstall BVM - Remove completely BVM, versions, etc.

🚀 Quick Start

📋 Prerequisites

The installer will attempt to install any missing prerequisites automatically, but there are some that will need to be installed manually depending on your platform.

  • bash - Required shell execution environment, especially on Alpine Linux

  • curl - For downloading releases

  • PowerShell 6+ - Required for Windows installations

Alpine Linux : You will need to install bash manually as it is not included by default.

The following are automatically installed for you, but you can install them manually if you prefer.

  • Java 21+ - JRE or JDK

  • unzip - For extracting downloaded files

  • jq - For parsing JSON (BVM only)

Manual Installation

Remember, we do this automatically for you, but if you want to do it manually, here are the commands:

macOS (with Homebrew):

Ubuntu/Debian:

RHEL/CentOS/Fedora:

Alpine Linux:

⬇️ Installation

💻 Basic Usage

📂 What BVM Installs

When you install a BoxLang version with BVM, it downloads and sets up:

Core Components

  • BoxLang Runtime (boxlang, bx) - The main BoxLang interpreter

  • BoxLang MiniServer (boxlang-miniserver, bx-miniserver) - Web application server

Helper Scripts

  • install-bx-module - BoxLang module installer (available in PATH after installation)

  • install-bvm - BVM installer script (available in PATH after installation)

  • Other utility scripts - Various helper tools

💡 Examples

🔒 Security & Reliability

BVM includes several security and reliability enhancements to ensure safe and reliable installations:

SHA-256 Checksum Verification

  • 🔒 Automatic verification - Downloads and verifies SHA-256 checksums for all BoxLang downloads

  • ✅ Cryptographic integrity - Ensures downloaded files haven't been tampered with

  • 🛡️ Security first - Available for BoxLang 1.3.0 and later versions

  • ⚠️ Graceful fallback - Clear warnings for pre-1.3.0 versions without checksums

  • 🔧 Multiple tools - Supports both sha256sum (Linux) and shasum (macOS)

Force Reinstallation

Use the --force flag to reinstall existing versions:

When to use --force:

  • 🔄 Recover from corrupted installations

  • 🆙 Get the latest "latest" or "snapshot" builds

  • 🛠️ Troubleshoot installation issues

  • 🧪 Testing and development scenarios

Command Aliases

BVM provides convenient short aliases for all major commands:

Automatic Snapshot Updates

BVM automatically ensures you have the latest development builds:

BVM now intelligently detects actual version numbers when installing "latest" or "snapshot" versions, providing clear and accurate version tracking.

How Version Detection Works

When you install using aliases like "latest" or "snapshot", BVM:

  1. Downloads the requested version (latest stable or development snapshot)

  2. Inspects the BoxLang JAR file to extract the actual version number

  3. Installs under the detected version (e.g., 1.2.0 or 1.3.0-snapshot)

  4. Creates appropriate symlinks (only for "latest" - points to the actual version)

Benefits

  • 🎯 Clear version tracking - bvm list shows actual version numbers, not generic aliases

  • 📋 Accurate history - see exactly which versions you have installed

  • 🔍 No confusion - distinguish between different snapshot builds

  • 🔗 Smart symlinks - "latest" symlink for convenience, actual versions for clarity

Example

Before (old behavior):

After (new behavior):

📁 Project-Specific Versions (.bvmrc)

BVM supports project-specific version configuration through .bvmrc files, similar to tools like jenv or nvm. This allows different projects to automatically use different BoxLang versions.

How .bvmrc Works

  • 📁 Per-project configuration - Each project can have its own BoxLang version

  • 🔍 Automatic discovery - BVM searches from current directory up to root for .bvmrc

  • 🎯 Simple format - Just the version number on the first line

  • 🚀 Seamless switching - Use bvm use without arguments to activate the project version

Creating .bvmrc Files

Using .bvmrc Files

.bvmrc File Format

The .bvmrc file is simple - just put the version on the first line:

Example Workflow

Directory Hierarchy

BVM searches for .bvmrc files starting from the current directory and walking up the directory tree:

⌨️ Commands

Version Management

  • bvm install <version> - Install a specific BoxLang version

    • bvm install latest - Install latest stable release (detects and installs actual version, e.g., 1.2.0)

    • bvm install snapshot - Install latest development snapshot (detects and installs actual version, e.g., 1.3.0-snapshot)

    • bvm install 1.2.0 - Install specific version

    • bvm install <version> --force - Force reinstall existing version (useful for updates or corruption recovery)

  • bvm use <version> - Switch to a specific BoxLang version

    • Can use actual version numbers (e.g., 1.2.0, 1.3.0-snapshot) or latest symlink

    • bvm use - Use version from .bvmrc file (if present)

  • bvm local <version> - Set local BoxLang version for current directory (creates .bvmrc)

    • bvm local - Show current .bvmrc version

  • bvm current - Show currently active BoxLang version

  • bvm remove <version> - Remove a specific BoxLang version (use actual version number)

    • Aliases: bvm rm <version>

  • bvm uninstall - Completely uninstall BVM and all BoxLang versions

Information

  • bvm list - List all installed BoxLang versions (shows actual version numbers and symlinks)

    • Alias: bvm ls

    • Example output: 1.2.0, latest → 1.2.0, 1.3.0-snapshot

  • bvm list-remote - List available BoxLang versions for download

    • Alias: bvm ls-remote

  • bvm which - Show path to current BoxLang installation

  • bvm version - Show BVM version

    • Aliases: bvm --version, bvm -v

Execution

  • bvm exec <args> - Execute BoxLang with current version

    • Alias: bvm run <args>

  • bvm miniserver <args> - Start BoxLang MiniServer with current version

    • Aliases: bvm mini-server <args>, bvm ms <args>

Maintenance

  • bvm check-update - Check for BVM updates and optionally upgrade

  • bvm clean - Clean cache and temporary files

  • bvm stats - Show performance and usage statistics

    • Aliases: bvm performance, bvm usage

  • bvm doctor - Check BVM installation health

    • Alias: bvm health

  • bvm help - Show help message

    • Aliases: bvm --help, bvm -h

🔄 Keeping BVM Updated

BVM includes a built-in update checker that helps you stay current with the latest version.

Checking for Updates

Update Process

When you run bvm check-update, BVM will:

  1. Check your current version - reads from local installation

  2. Fetch the latest version - checks the remote repository

  3. Compare versions - determines if an update is available

  4. Show status - displays current vs. latest version information

Interactive Upgrade

If a newer version is available, BVM will:

  • 🆙 Display the available update - shows current and latest version numbers

  • ❓ Prompt for confirmation - asks if you want to upgrade

  • 🚀 Automatically upgrade - downloads and installs the latest version if you confirm

  • ✅ Preserve your installations - keeps all your BoxLang versions intact

Example Update Session

Status Messages

  • 🦾 Up to date: "You have the latest version of BVM!"

  • 🆙 Update available: "A newer version of BVM is available!"

  • 🧑‍💻 Development version: "Your BVM version is newer than the latest release"

🗑️ Uninstalling BoxLang Versions and BVM

BVM provides two different uninstall options depending on your needs.

Removing Individual BoxLang Versions

Use bvm remove (or bvm rm) to remove specific BoxLang versions you no longer need:

Important Notes

  • Cannot remove active version: You cannot remove the currently active BoxLang version

  • Confirmation required: BVM will ask for confirmation before removing a version

  • Use actual version numbers: Use the actual version number (e.g., 1.2.0), not aliases like latest

Example Session

Completely Uninstalling BVM

Use bvm uninstall to completely remove BVM and all installed BoxLang versions:

What Gets Removed

  • 🗑️ All BoxLang versions - every installed version will be deleted

  • 🗑️ BVM home directory - ~/.bvm and all contents

  • 🗑️ Cache files - all downloaded installers and temporary files

  • 🗑️ Version symlinks - latest and other version links

Complete Uninstall Process

Manual Cleanup

After running bvm uninstall, you may need to manually:

  1. Remove shell profile entries - delete BVM-related lines from ~/.bashrc, ~/.zshrc, etc.

  2. Remove from PATH - if you installed BVM system-wide, remove it from your PATH

  3. Restart terminal - open a new terminal session to ensure changes take effect

🔄 Migrating from Single-Version Installer to BVM

If you currently have BoxLang installed via install-boxlang.sh and want to switch to BVM for version management:

1. Uninstall Current BoxLang (Recommended)

2. Install BVM

3. Install Your Preferred BoxLang Version

4. Verify Everything Works

Note: Your BoxLang home directory (~/.boxlang) with modules, settings, and data will be preserved during migration.

This will check your BVM installation and identify any issues.

🤝 Contributing

BVM is part of the BoxLang Quick Installer project. To contribute:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Test thoroughly

  5. Submit a pull request

PreviousBoxLang Quick InstallerNextModules

Last updated

Was this helpful?