vx-shim

Cross-platform shim executable for the vx universal tool manager.

Overview

vx-shim is a lightweight, cross-platform executable that acts as a proxy to other executables. It's inspired by scoop-better-shimexe but written in Rust for better cross-platform support and modern features.

Features

Cross-Platform: Works on Windows, macOS, and Linux
Fast Execution: Minimal overhead with efficient process management
Signal Handling: Proper Ctrl+C and signal forwarding to child processes
Process Management: Automatic cleanup of child processes
Flexible Configuration: Support for both TOML and legacy Scoop formats
Environment Variables: Support for custom environment variables
Working Directory: Configurable working directory for target executables
Windows Features: Job objects, console hiding, elevation support
Unix Features: Fork/exec with proper signal handling

How It Works

Shim Discovery: Looks for a .shim file with the same name as the executable
Configuration Parsing: Reads the shim configuration (TOML or legacy format)
Process Execution: Executes the target program with proper signal handling
Cleanup: Ensures child processes are cleaned up when the shim exits

Shim Configuration

TOML Format (Recommended)

# Path to the target executable
path = "/usr/bin/git"

# Optional arguments to prepend
args = "status -u"

# Working directory (optional)
working_dir = "/workspace"

# Environment variables (optional)
[env]
GIT_EDITOR = "vim"
PAGER = "less"

# Signal handling configuration (optional)
[signal_handling]
ignore_sigint = true
forward_signals = true
kill_on_exit = true

# Windows-specific options (optional)
hide_console = false
run_as_admin = false

Legacy Scoop Format

path = C:\Program Files\Git\git.exe
args = status -u
working_dir = C:\workspace
env.GIT_EDITOR = vim
env.PAGER = less

Usage

As a Library

use vx_shim::{ShimConfig, Executor};

// Load configuration
let config = ShimConfig::load("my-tool.shim")?;

// Execute with arguments
let executor = Executor::new(config);
let exit_code = executor.execute(&["--version"])?;

As an Executable

# The shim executable looks for a .shim file with the same name
# For example, git.exe looks for git.shim

# Create a shim configuration
echo 'path = "/usr/bin/git"' > git.shim
echo 'args = "status -u"' >> git.shim

# Copy vx-shim to git (or git.exe on Windows)
cp vx-shim git

# Now running ./git will execute: /usr/bin/git status -u [additional args]
./git --short
# Executes: /usr/bin/git status -u --short

Installation

From Crates.io

cargo install vx-shim

From Source

git clone https://github.com/loonghao/vx
cd vx/crates/vx-shim
cargo build --release

Platform-Specific Features

Windows

Job Objects: Automatic cleanup of child processes using Windows job objects
Console Management: Option to hide console windows for GUI applications
Elevation Support: Automatic handling of UAC elevation requests
Signal Handling: Proper handling of Ctrl+C and other console signals

Unix (Linux/macOS)

Fork/Exec: Uses fork/exec for better signal handling
Signal Forwarding: Proper forwarding of signals to child processes
Process Groups: Management of process groups for cleanup
File Permissions: Automatic handling of executable permissions

Advantages over Alternatives

vs. Batch/Shell Scripts

Performance: No shell interpreter overhead
Signal Handling: Proper signal forwarding and cleanup
Cross-Platform: Single binary works everywhere
Error Handling: Better error reporting and handling

vs. scoop-better-shimexe

Cross-Platform: Works on Unix systems, not just Windows
Modern Language: Written in Rust for memory safety and performance
Flexible Configuration: Support for both TOML and legacy formats
Better Testing: Comprehensive test suite and CI

vs. Symlinks

Argument Injection: Can prepend arguments to commands
Environment Control: Can set custom environment variables
Working Directory: Can change working directory
Windows Compatibility: Works on Windows without admin privileges

Development

Building

cargo build

Testing

cargo test

Cross-Platform Testing

# Test on Windows
cargo test --target x86_64-pc-windows-msvc

# Test on Linux
cargo test --target x86_64-unknown-linux-gnu

# Test on macOS
cargo test --target x86_64-apple-darwin

Integration with VX

vx-shim is designed to work seamlessly with the vx tool manager:

Tool Installation: vx creates shim files when installing tools
Version Management: Different tool versions can have different shims
Virtual Environments: Shims can be environment-specific
Path Management: Shims are placed in vx-managed PATH directories

Examples

Simple Command Proxy

# echo.shim
path = "/bin/echo"
args = "Hello from shim:"

./echo world
# Output: Hello from shim: world

Development Tool with Environment

# node.shim
path = "/usr/local/bin/node"
working_dir = "/workspace"

[env]
NODE_ENV = "development"
DEBUG = "*"

Windows GUI Application

# notepad.shim
path = "C:\\Windows\\System32\\notepad.exe"
hide_console = true

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please see the contributing guidelines for more information.

Related Projects

scoop-better-shimexe - Original inspiration (Windows-only)
Scoop - Windows package manager that uses shims
vx - Universal tool manager that uses vx-shim

vx-shim 0.2.3