Self-Contained Virtual Environment Support #137

New Issue

john · 2025-11-27T02:53:09Z

john commented

2025-11-27 02:53:09 +00:00

Summary

McRogueFace now supports self-contained virtual environments for pip-installed packages. Games can ship as a single directory that automatically bootstraps pip and installs dependencies on first run.

Implementation

C++ Changes (`src/McRFPy_API.cpp`)

Set sys.executable: Both init_python() and init_python_with_config() now set pyconfig.executable to the McRogueFace binary path. This enables subprocess.run([sys.executable, ...]) to work.
Sibling venv detection: On startup, checks for ./venv/ directory alongside the executable. If found, prepends the platform-appropriate site-packages path:
- Linux: venv/lib/python3.14/site-packages
- Windows: venv/Lib/site-packages

Python Reference Implementation (`src/scripts/mcrf_venv.py`)

New module providing:

import mcrf_venv

# Check/create venv
mcrf_venv.venv_exists()  # -> bool
mcrf_venv.create_venv()  # Creates directory structure

# Pip management
mcrf_venv.pip_available()  # -> bool
mcrf_venv.bootstrap_pip()  # Extracts pip from ensurepip wheel
mcrf_venv.pip_install("numpy", "requests")  # Install packages
mcrf_venv.install_requirements("requirements.txt")

# High-level convenience
mcrf_venv.ensure_environment("requirements.txt")  # One-liner setup

# Utilities
mcrf_venv.list_installed()  # -> [(name, version), ...]

Usage

Simple Setup (game.py)

import mcrf_venv

# Bootstrap on first run, install dependencies
if not mcrf_venv.venv_exists():
    mcrf_venv.create_venv()
    mcrf_venv.pip_install("numpy", "pygame-ce")

# Now safe to import
import numpy
import mcrfpy

With requirements.txt

import mcrf_venv
mcrf_venv.ensure_environment("requirements.txt")

import numpy  # Installed from requirements.txt

Distribution Structure

my_game/
├── mcrogueface           # Executable
├── lib/Python/           # Bundled runtime (read-only)
├── venv/                 # Created on first run
│   └── lib/python3.14/site-packages/
│       ├── pip/          # Bootstrapped from ensurepip
│       ├── numpy/        # User-installed
│       └── ...
├── scripts/
│   ├── game.py
│   └── mcrf_venv.py
├── requirements.txt      # Optional
└── assets/

Notes

Pip is bootstrapped from ensurepip/_bundled/pip-*.whl (already bundled)
No system Python required - McRogueFace IS the Python interpreter
Venv packages take priority over bundled stdlib (prepended to sys.path)
Cross-platform: handles Linux and Windows path conventions

Partially addresses #70 (Package mcrfpy without embedded interpreter)
Enables third-party package usage without full pip distribution

## Summary McRogueFace now supports self-contained virtual environments for pip-installed packages. Games can ship as a single directory that automatically bootstraps pip and installs dependencies on first run. ## Implementation ### C++ Changes (`src/McRFPy_API.cpp`) 1. **Set `sys.executable`**: Both `init_python()` and `init_python_with_config()` now set `pyconfig.executable` to the McRogueFace binary path. This enables `subprocess.run([sys.executable, ...])` to work. 2. **Sibling venv detection**: On startup, checks for `./venv/` directory alongside the executable. If found, prepends the platform-appropriate site-packages path: - Linux: `venv/lib/python3.14/site-packages` - Windows: `venv/Lib/site-packages` ### Python Reference Implementation (`src/scripts/mcrf_venv.py`) New module providing: ```python import mcrf_venv # Check/create venv mcrf_venv.venv_exists() # -> bool mcrf_venv.create_venv() # Creates directory structure # Pip management mcrf_venv.pip_available() # -> bool mcrf_venv.bootstrap_pip() # Extracts pip from ensurepip wheel mcrf_venv.pip_install("numpy", "requests") # Install packages mcrf_venv.install_requirements("requirements.txt") # High-level convenience mcrf_venv.ensure_environment("requirements.txt") # One-liner setup # Utilities mcrf_venv.list_installed() # -> [(name, version), ...] ``` ## Usage ### Simple Setup (game.py) ```python import mcrf_venv # Bootstrap on first run, install dependencies if not mcrf_venv.venv_exists(): mcrf_venv.create_venv() mcrf_venv.pip_install("numpy", "pygame-ce") # Now safe to import import numpy import mcrfpy ``` ### With requirements.txt ```python import mcrf_venv mcrf_venv.ensure_environment("requirements.txt") import numpy # Installed from requirements.txt ``` ## Distribution Structure ``` my_game/ ├── mcrogueface # Executable ├── lib/Python/ # Bundled runtime (read-only) ├── venv/ # Created on first run │ └── lib/python3.14/site-packages/ │ ├── pip/ # Bootstrapped from ensurepip │ ├── numpy/ # User-installed │ └── ... ├── scripts/ │ ├── game.py │ └── mcrf_venv.py ├── requirements.txt # Optional └── assets/ ``` ## Notes - Pip is bootstrapped from `ensurepip/_bundled/pip-*.whl` (already bundled) - No system Python required - McRogueFace IS the Python interpreter - Venv packages take priority over bundled stdlib (prepended to sys.path) - Cross-platform: handles Linux and Windows path conventions ## Related - Partially addresses #70 (Package mcrfpy without embedded interpreter) - Enables third-party package usage without full pip distribution

john added the

Minor Feature

system:python-binding

priority:tier2-foundation

labels 2025-11-27 02:53:45 +00:00

john referenced this issue from a commit

2025-11-27 03:01:15 +00:00

feat: Add self-contained venv support for pip packages (closes #137)

john closed this issue

2025-11-27 03:01:15 +00:00

Sign in to join this conversation.