MVX Interpreters
MVX supports multiple interpreters for executing commands, allowing you to choose the best execution environment for your specific needs.
Available Interpreters
1. Native Interpreter (native)
The native interpreter uses the system's default shell (bash on Unix systems, cmd on Windows) to execute commands. This is the recommended interpreter for commands that:
- Use external tools and binaries
- Require complex shell features like pipes, redirects, or advanced scripting
- Need access to system-specific functionality
Example:
{
commands: {
"build": {
description: "Build the project",
script: "go build -o dist/myapp .",
interpreter: "native"
}
}
}
2. MVX Shell Interpreter (mvx-shell)
The mvx-shell interpreter is a cross-platform command interpreter built into MVX. It provides:
- Cross-platform compatibility
- Built-in commands (cd, echo, mkdir, rm, cp)
- Environment variable expansion
- Basic command chaining with
&&,||, and;
Example:
{
commands: {
"setup": {
description: "Setup project directories",
script: "mkdir -p dist && echo 'Directories created'",
interpreter: "mvx-shell"
}
}
}
Interpreter Selection
Automatic Selection
MVX automatically selects the appropriate interpreter based on your script configuration:
- Simple string scripts default to
mvx-shellfor cross-platform compatibility - Platform-specific scripts default to
nativefor system integration
Explicit Selection
You can explicitly specify the interpreter using the interpreter field:
{
commands: {
"format": {
description: "Format code",
script: "go fmt ./...",
interpreter: "native" // Explicitly use native interpreter
},
"clean": {
description: "Clean build artifacts",
script: "rm -rf dist && echo 'Cleaned'",
interpreter: "mvx-shell" // Explicitly use mvx-shell
}
}
}
Environment Variables
Both interpreters support environment variables with different capabilities:
Global Environment Variables
Set in the environment section of your configuration:
{
environment: {
BUILD_MODE: "production",
LOG_LEVEL: "info"
}
}
Command-Specific Environment Variables
Set per command using the environment field:
{
commands: {
"test": {
description: "Run tests",
script: "go test ./...",
interpreter: "native",
environment: {
GO_ENV: "test",
VERBOSE: "true"
}
}
}
}
Variable Expansion
Both interpreters support comprehensive variable expansion with multiple syntax options:
Supported Syntax
- Simple Variables:
$VARIABLE_NAME - Braced Variables:
${VARIABLE_NAME}(useful when followed by other characters)
MVX-Shell Variable Expansion
The mvx-shell interpreter provides comprehensive variable expansion for all commands:
{
commands: {
"setup-project": {
description: "Setup project structure",
script: "mkdir $PROJECT_NAME && cd $PROJECT_NAME && echo 'Created ${PROJECT_NAME}_config.json'",
environment: {
PROJECT_NAME: "myapp"
}
},
"deploy": {
description: "Deploy application",
script: "echo 'Deploying $PROJECT_NAME in $BUILD_MODE mode to ${DEPLOY_ENV}_server'",
environment: {
PROJECT_NAME: "myapp",
BUILD_MODE: "production",
DEPLOY_ENV: "staging"
}
}
}
}
Variable Expansion Features
- Command Names: Variables are expanded in command names
- Arguments: Variables are expanded in all command arguments
- Built-in Commands: All mvx-shell built-in commands support variable expansion
- External Commands: Variables are expanded before executing external commands
- Environment Override: Command-specific environment variables override global ones
Examples
# These all work with variable expansion in mvx-shell:
mkdir $PROJECT_DIR # Create directory with variable name
echo "Hello $USER_NAME" # Print with variable expansion
rm ${TEMP_DIR}/cache # Remove with braced variable syntax
cd $PROJECT_DIR && echo "In project" # Chain commands with variables
PATH Management
MVX automatically manages the PATH environment variable to ensure mvx-managed tools are available:
Tool PATH Integration
When you have tools configured in your .mvx/config.json5:
{
tools: {
go: { version: "1.24.2" },
java: { version: "17", distribution: "zulu" },
maven: { version: "3.9.11" }
}
}
MVX automatically prepends the tool bin directories to PATH:
~/.mvx/tools/go/1.24.2/go/bin~/.mvx/tools/java/17-zulu/bin~/.mvx/tools/maven/3.9.11/bin
Interpreter-Specific PATH Handling
- Native interpreter: Full PATH integration with system shell
- MVX-shell interpreter: Limited PATH support for external commands
For commands that use external tools (like go, mvn, node), it's recommended to use the native interpreter to ensure proper PATH resolution.
Best Practices
When to Use Native Interpreter
Use interpreter: "native" for commands that:
- Execute external tools (
go,mvn,npm, etc.) - Use complex shell features (pipes, redirects, loops)
- Require system-specific functionality
- Need reliable PATH resolution
{
commands: {
"build": {
script: "go build -o dist/app .",
interpreter: "native"
},
"test": {
script: "go test -v ./...",
interpreter: "native"
},
"deps": {
script: "go mod download && go mod tidy",
interpreter: "native"
}
}
}
When to Use MVX-Shell Interpreter
Use interpreter: "mvx-shell" for commands that:
- Use only built-in commands
- Need cross-platform compatibility
- Perform simple file operations
- Don't require external tools
{
commands: {
"clean": {
script: "rm -rf dist && mkdir -p dist",
interpreter: "mvx-shell"
},
"setup": {
script: "mkdir -p src test docs && echo 'Project structure created'",
interpreter: "mvx-shell"
}
}
}
Debugging
Verbose Logging
Enable verbose logging to debug interpreter and PATH issues:
MVX_VERBOSE=true mvx your-command
This will show:
- Environment setup details
- PATH modifications
- Interpreter selection
- Command execution details
Common Issues
-
"executable file not found" errors: Usually indicates PATH issues. Use
interpreter: "native"for external tools. -
Cross-platform compatibility: Use
mvx-shellfor simple commands that need to work across different operating systems. -
Environment variable not found: Check that variables are properly defined in global or command-specific environment sections.
Migration Guide
If you're experiencing PATH issues with existing commands, add interpreter: "native" to commands that use external tools:
// Before (may have PATH issues)
{
"fmt": {
"script": "go fmt ./..."
}
}
// After (fixed)
{
"fmt": {
"script": "go fmt ./...",
"interpreter": "native"
}
}