MQL4/.github/instructions/compilation-verification.instructions.md

# Compilation and Verification Instructions for Agentic AI Coders

## Overview
This document provides step-by-step instructions for AI agents to compile MQL5 code and verify successful compilation through terminal commands. These procedures ensure that code changes are validated before marking tasks complete.

---

## 1. Prerequisites

### Required Information
- **MetaEditor Path:** Location of MetaEditor64.exe on the system
- **Source File Path:** Absolute path to the .mq5 or .mq4 file to compile
- **Project Root:** Workspace root directory

### Common MetaEditor Locations
```powershell
# Standard MetaTrader 5 installation
"C:\Program Files\MetaTrader 5\MetaEditor64.exe"

# Broker-specific installations (examples)
"C:\Program Files\Dukascopy MetaTrader 5\MetaEditor64.exe"
"C:\Program Files\Alpari MetaTrader 5\MetaEditor64.exe"
"C:\Program Files\IC Markets MetaTrader 5\MetaEditor64.exe"

# Standard MetaTrader 4 installation
"C:\Program Files\MetaTrader 4\MetaEditor.exe"
```

### How to Find MetaEditor
```powershell
# Search for MetaEditor installations
Get-ChildItem "C:\Program Files" -Recurse -Filter "MetaEditor*.exe" -ErrorAction SilentlyContinue | Select-Object FullName

# Check if specific broker installation exists
Test-Path "C:\Program Files\Dukascopy MetaTrader 5\MetaEditor64.exe"
```

---

## 2. Compilation Process

### Step 1: Verify Source File Exists
Before attempting compilation, confirm the source file exists:

```powershell
# Check if .mq5 file exists
$sourcePath = "c:\path\to\your\file.mq5"
if (Test-Path $sourcePath) {
    Write-Host "✓ Source file found: $sourcePath"
    Get-Item $sourcePath | Select-Object Name, LastWriteTime, Length
} else {
    Write-Host "✗ ERROR: Source file not found at $sourcePath"
    exit 1
}
```

### Step 2: Execute Compilation
Use MetaEditor's command-line interface to compile:

```powershell
# Basic compilation command
& "C:\Program Files\MetaTrader 5\MetaEditor64.exe" /compile:"c:\path\to\your\file.mq5"

# With /log flag for detailed output (recommended for debugging)
& "C:\Program Files\MetaTrader 5\MetaEditor64.exe" /compile:"c:\path\to\your\file.mq5" /log

# Using Start-Process for better control (waits for completion)
Start-Process -FilePath "C:\Program Files\MetaTrader 5\MetaEditor64.exe" -ArgumentList "/compile:`"c:\path\to\your\file.mq5`"" -Wait -NoNewWindow
```

**Important Notes:**
- Use **escaped quotes** (`\`"`) when using `-ArgumentList` with `Start-Process`
- The `-Wait` flag ensures the command completes before continuing
- The `-NoNewWindow` flag prevents opening a separate window
- Exit Code 0 indicates successful execution (but NOT necessarily successful compilation)

### Step 3: Verify Compilation Success
MetaEditor's exit code doesn't indicate compilation errors. You must verify by checking the compiled file:

```powershell
# Define paths
$sourcePath = "c:\path\to\your\file.mq5"
$compiledPath = $sourcePath -replace '\.mq5$', '.ex5'  # Replace .mq5 with .ex5
# For MQL4: $compiledPath = $sourcePath -replace '\.mq4$', '.ex4'

# Check if compiled file was created/updated
if (Test-Path $compiledPath) {
    $compiledFile = Get-Item $compiledPath
    $sourceFile = Get-Item $sourcePath
    
    # Verify compiled file is newer than or equal to source file
    if ($compiledFile.LastWriteTime -ge $sourceFile.LastWriteTime) {
        Write-Host "✓ Compilation SUCCESSFUL"
        Write-Host "Compiled File: $($compiledFile.Name)"
        Write-Host "Size: $($compiledFile.Length) bytes"
        Write-Host "Timestamp: $($compiledFile.LastWriteTime)"
    } else {
        Write-Host "✗ WARNING: Compiled file is older than source file"
        Write-Host "Source modified: $($sourceFile.LastWriteTime)"
        Write-Host "Compiled: $($compiledFile.LastWriteTime)"
        Write-Host "Compilation may have failed. Check MetaEditor logs."
    }
} else {
    Write-Host "✗ Compilation FAILED - .ex5 file not found"
    Write-Host "Expected at: $compiledPath"
    exit 1
}
```

---

## 3. Complete Verification Workflow

### Full Verification Script
This comprehensive script handles the entire verification process:

```powershell
# Configuration
$metaEditorPath = "C:\Program Files\Dukascopy MetaTrader 5\MetaEditor64.exe"
$sourcePath = "c:\Users\krsna\Desktop\Data-Fx\MLQ5\forge.mql5.io\MQL5\Experts\_Thivyam\MultiTimeframeZone\MultiTimeframeZoneEA.mq5"

# Step 1: Verify MetaEditor exists
Write-Host "=== Step 1: Verifying MetaEditor ===" -ForegroundColor Cyan
if (!(Test-Path $metaEditorPath)) {
    Write-Host "✗ ERROR: MetaEditor not found at: $metaEditorPath" -ForegroundColor Red
    exit 1
}
Write-Host "✓ MetaEditor found" -ForegroundColor Green

# Step 2: Verify source file exists
Write-Host "`n=== Step 2: Verifying Source File ===" -ForegroundColor Cyan
if (!(Test-Path $sourcePath)) {
    Write-Host "✗ ERROR: Source file not found at: $sourcePath" -ForegroundColor Red
    exit 1
}
$sourceFile = Get-Item $sourcePath
Write-Host "✓ Source file found: $($sourceFile.Name)" -ForegroundColor Green
Write-Host "  Last modified: $($sourceFile.LastWriteTime)"
Write-Host "  Size: $($sourceFile.Length) bytes"

# Step 3: Compile
Write-Host "`n=== Step 3: Compiling ===" -ForegroundColor Cyan
Write-Host "Executing: MetaEditor64.exe /compile:`"$sourcePath`""
$compileStart = Get-Date
Start-Process -FilePath $metaEditorPath -ArgumentList "/compile:`"$sourcePath`"" -Wait -NoNewWindow
$compileEnd = Get-Date
$compileDuration = ($compileEnd - $compileStart).TotalSeconds
Write-Host "Compilation completed in $([math]::Round($compileDuration, 2)) seconds"

# Step 4: Verify output
Write-Host "`n=== Step 4: Verifying Output ===" -ForegroundColor Cyan
$compiledPath = $sourcePath -replace '\.mq5$', '.ex5'
if (Test-Path $compiledPath) {
    $compiledFile = Get-Item $compiledPath
    
    # Check if compiled file is fresh
    if ($compiledFile.LastWriteTime -ge $compileStart) {
        Write-Host "✓ Compilation SUCCESSFUL!" -ForegroundColor Green
        Write-Host "  Output file: $($compiledFile.Name)"
        Write-Host "  Size: $($compiledFile.Length) bytes"
        Write-Host "  Timestamp: $($compiledFile.LastWriteTime)"
        Write-Host "`n✓✓✓ ALL CHECKS PASSED ✓✓✓" -ForegroundColor Green
        exit 0
    } else {
        Write-Host "⚠ WARNING: Compiled file exists but wasn't updated" -ForegroundColor Yellow
        Write-Host "  File timestamp: $($compiledFile.LastWriteTime)"
        Write-Host "  Compile started: $compileStart"
        Write-Host "  This suggests compilation errors occurred."
        Write-Host "`n✗ VERIFICATION FAILED" -ForegroundColor Red
        exit 1
    }
} else {
    Write-Host "✗ Compilation FAILED - Output file not created" -ForegroundColor Red
    Write-Host "  Expected at: $compiledPath"
    Write-Host "  Check for syntax errors in the source code."
    Write-Host "`n✗ VERIFICATION FAILED" -ForegroundColor Red
    exit 1
}
```

### How to Use the Script
1. **Update Configuration:** Replace `$metaEditorPath` and `$sourcePath` with actual values
2. **Run in Terminal:** Execute the entire script in PowerShell
3. **Interpret Results:**
   - Exit Code 0 = Success
   - Exit Code 1 = Failure (source file issues, compilation errors, or verification failed)

---

## 4. Checking Compilation Errors

### Method 1: Check MetaEditor Log Files
MetaEditor creates log files that contain compilation output:

```powershell
# Common log file locations
$logLocations = @(
    "$env:APPDATA\MetaQuotes\Terminal\*\logs\*.log",
    "$env:APPDATA\MetaQuotes\MetaEditor\logs\*.log",
    "C:\Program Files\MetaTrader 5\logs\*.log"
)

# Find recent logs
foreach ($location in $logLocations) {
    Get-ChildItem $location -ErrorAction SilentlyContinue | 
        Where-Object { $_.LastWriteTime -gt (Get-Date).AddMinutes(-5) } |
        Select-Object FullName, LastWriteTime
}
```

### Method 2: Use VS Code Error Detection
If working in VS Code with MQL5 extension:

```powershell
# The get_errors tool can detect compilation errors
# This is IDE-specific and may show IntelliSense errors
# Always prioritize MetaEditor compilation results
```

### Method 3: Parse Compilation Output
For automated workflows, capture and parse output:

```powershell
# Create a temporary output file
$outputFile = "$env:TEMP\mql_compile_output.txt"

# Redirect compilation output
$process = Start-Process -FilePath $metaEditorPath `
    -ArgumentList "/compile:`"$sourcePath`"", "/log" `
    -Wait -NoNewWindow -PassThru -RedirectStandardOutput $outputFile

# Check output for errors
$output = Get-Content $outputFile -ErrorAction SilentlyContinue
if ($output -match "(\d+)\s+error") {
    $errorCount = $matches[1]
    Write-Host "✗ Compilation failed with $errorCount error(s)" -ForegroundColor Red
} else {
    Write-Host "✓ No errors detected in output" -ForegroundColor Green
}

# Cleanup
Remove-Item $outputFile -ErrorAction SilentlyContinue
```

---

## 5. Common Issues and Solutions

### Issue 1: "File not found" error
**Cause:** Incorrect path or special characters  
**Solution:**
```powershell
# Use absolute paths, not relative
# Correct
$path = "c:\Users\krsna\Desktop\Data-Fx\MLQ5\forge.mql5.io\MQL5\Experts\_Thivyam\MultiTimeframeZone\MultiTimeframeZoneEA.mq5"

# Incorrect
$path = ".\MQL5\Experts\_Thivyam\MultiTimeframeZone\MultiTimeframeZoneEA.mq5"
```

### Issue 2: Exit Code 0 but no .ex5 file
**Cause:** Compilation errors (MetaEditor returns 0 even with errors)  
**Solution:** Always verify .ex5 file creation/update timestamp

### Issue 3: Permission denied
**Cause:** MetaEditor or file locked by another process  
**Solution:**
```powershell
# Check if file is locked
$file = "c:\path\to\file.ex5"
try {
    $stream = [System.IO.File]::Open($file, 'Open', 'ReadWrite', 'None')
    $stream.Close()
    Write-Host "✓ File is not locked"
} catch {
    Write-Host "✗ File is locked by another process"
}
```

### Issue 4: Wrong MetaEditor version
**Cause:** Using MetaEditor.exe (32-bit) instead of MetaEditor64.exe  
**Solution:** Always use MetaEditor64.exe for 64-bit systems

---

## 6. Integration with Agentic AI Workflows

### When to Compile
AI agents should compile after:
- ✅ Making any code changes to .mq5/.mq4 files
- ✅ Modifying include files (.mqh) used by the EA/indicator
- ✅ Completing a debugging session
- ✅ Before marking a task as complete

### Workflow Integration
```
1. Make code changes
2. Save files
3. Run compilation verification script
4. IF compilation succeeds:
   - Mark task as complete
   - Report success to user
5. ELSE IF compilation fails:
   - Read error output
   - Fix errors
   - GOTO step 2
```

### Reporting Results
AI agents should report:
- ✅ Compilation status (success/failure)
- ✅ Output file size and timestamp
- ✅ Compilation duration
- ✅ Error count and descriptions (if any)

Example success report:
```
✓ Compilation SUCCESSFUL!
  - File: MultiTimeframeZoneEA.ex5
  - Size: 62,588 bytes
  - Compiled at: 2025-11-03 06:55:01 AM
  - Duration: 2.3 seconds
  - Result: 0 errors, 0 warnings
```

Example failure report:
```
✗ Compilation FAILED
  - Expected output: MultiTimeframeZoneEA.ex5
  - Status: File not created
  - Errors detected: 2 errors, 0 warnings
  - Most recent error: 'undeclared identifier' at line 58
  - Action needed: Fix syntax errors and recompile
```

---

## 7. Best Practices

### DO:
- ✅ Always use absolute paths
- ✅ Verify .ex5 file timestamp is recent
- ✅ Check file size is reasonable (>10KB for typical EAs)
- ✅ Wait for compilation to complete (use `-Wait` flag)
- ✅ Report compilation results clearly to user

### DON'T:
- ❌ Rely solely on exit codes
- ❌ Use relative paths
- ❌ Skip verification steps
- ❌ Assume compilation succeeded without checking output
- ❌ Continue with other tasks if compilation fails

---

## 8. Quick Reference Commands

### Single-Line Compilation Check
```powershell
& "C:\Program Files\MetaTrader 5\MetaEditor64.exe" /compile:"c:\path\to\file.mq5"; if (Test-Path "c:\path\to\file.ex5") { Write-Host "✓ Success" } else { Write-Host "✗ Failed" }
```

### Check Last Compilation Time
```powershell
Get-Item "c:\path\to\file.ex5" | Select-Object Name, LastWriteTime, Length
```

### Compare Source vs Compiled
```powershell
$src = Get-Item "c:\path\to\file.mq5"; $comp = Get-Item "c:\path\to\file.ex5"; if ($comp.LastWriteTime -gt $src.LastWriteTime) { "✓ Compiled is newer" } else { "✗ Source is newer - recompile needed" }
```

---

## 9. Example: Real-World Compilation Verification

This is the exact sequence used to verify the MultiTimeframeZone EA compilation:

```powershell
# 1. Initial compilation attempt
Start-Process -FilePath "C:\Program Files\Dukascopy MetaTrader 5\MetaEditor64.exe" `
    -ArgumentList "/compile:`"c:\Users\krsna\Desktop\Data-Fx\MLQ5\forge.mql5.io\mql5\Experts\_Thivyam\MultiTimeframeZone\MultiTimeframeZoneEA.mq5`"" `
    -Wait -NoNewWindow

# 2. Verification
if (Test-Path "c:\Users\krsna\Desktop\Data-Fx\MLQ5\forge.mql5.io\mql5\Experts\_Thivyam\MultiTimeframeZone\MultiTimeframeZoneEA.ex5") {
    Get-Item "c:\Users\krsna\Desktop\Data-Fx\MLQ5\forge.mql5.io\mql5\Experts\_Thivyam\MultiTimeframeZone\MultiTimeframeZoneEA.ex5" | 
        Select-Object Name, LastWriteTime, Length
} else {
    Write-Host "Compilation failed - .ex5 not found"
}

# Output from successful compilation:
# Name                     LastWriteTime        Length
# ----                     -------------        ------
# MultiTimeframeZoneEA.ex5 11/3/2025 6:55:01 AM  62588
```

---

## 10. Troubleshooting Checklist

When compilation fails, check:

- [ ] Source file path is correct and file exists
- [ ] MetaEditor path is correct for your installation
- [ ] No syntax errors in the code (check line numbers in errors)
- [ ] All include files (.mqh) exist and are accessible
- [ ] No circular dependencies in include files
- [ ] File permissions allow reading source and writing compiled output
- [ ] Sufficient disk space for compilation
- [ ] No other process has locked the files
- [ ] MetaTrader terminal is not running with the same files open
- [ ] Proper escape sequences used in PowerShell commands

---

**Document Version:** 1.0  
**Last Updated:** November 3, 2025  
**Validated On:** Windows 10/11 with PowerShell 5.1+  
**Compatible With:** MetaTrader 5 Build 3960+, MetaTrader 4 Build 1380+