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

# 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

# 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:

# 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:

# 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 -ArgumentListwithStart-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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

& "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

Get-Item "c:\path\to\file.ex5" | Select-Object Name, LastWriteTime, Length

Compare Source vs Compiled

$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:

# 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+