MQL Clangd

Note: Originally based on MQL Tools by L-I-V. Now an independent project with clangd support and major performance optimizations.

View Changelog for the latest updates and improvements.

---

Table of Contents

• Differences from MQL Tools
• Smart Compile Targets for Header Files
• IntelliSense & Semantic Support
• Quick Setup Guide
• Important Notes
• MetaEditor on macOS / Linux (Wine)
• Auto-Reload EA After Compile (MT5 Service)
• Live Runtime Log
• Trade Report Dashboard
• Run Backtest
• Arrange MT5 Charts
• MQL Debugger (Real-Time Variable Inspection)
• Troubleshooting clangd diagnostics (MQL-specific)
• FAQ: Common Questions
• Preserving Custom Diagnostic Suppressions

---

Differences from MQL Tools

Feature	MQL Tools	MQL Clangd
IntelliSense Engine	Microsoft C++	clangd
Performance	Synchronous I/O	Async I/O
Diagnostics in Problems tab	❌	✅
Document Symbols (Outline, Breadcrumbs)	❌	✅
Compile without opening MetaEditor	❌	✅
Smart Compile Target for Headers	❌	✅
Multi-root / MQL4+MQL5 mixed workspace support	❌	✅
MetaEditor on macOS / Linux via Wine	❌	✅
CPU Architecture Selection (AVX/AVX2/AVX512)	❌	✅
Auto-Reload EA After Compile (MT5 Service)	❌	✅
Live Runtime Log (LiveLog, 3 tail modes)	❌	✅
Trigger Backtest from VS Code	❌	✅
Arrange MT5 Charts (multi-monitor layouts)	❌	✅
MQL Debugger (real-time variable inspection)	❌	✅

---

Smart Compile Targets for Header Files

When editing .mqh header files, the extension now intelligently determines which main .mq4/.mq5 file to compile—without hardcoding filenames in the header itself.

• Automatic Inference: The extension builds a reverse include graph to find which main files include your header.
• Smart Selection:

• If exactly 1 main file includes the header → auto-compiles and remembers the choice
• If multiple main files include it → shows a picker to select which one(s) to compile
• If no main files include it → shows all available main files to pick from

• Persistent Mappings: Your choices are remembered across sessions (configurable storage: workspace-local, global, or shared via .vscode/settings.json).
• Multi-Target Support: Compile multiple main files from a single header in one go.
• Backward Compatible: The old magic comment syntax (//###<path/to/file.mq5>) still works as a fallback.

Commands:

• MQL: Select Compile Target(s) for Header — Manually choose compile targets
• MQL: Reset Compile Target for Current Header — Clear the mapping
• MQL: Reset All Compile Target Mappings — Clear all stored mappings

---

IntelliSense & Semantic Support

This extension now uses clangd to provide state-of-the-art IntelliSense, code completion, and navigation for MQL4/5.

• Why clangd? Faster, more accurate semantic analysis than the default Microsoft C++ engine — especially for complex MQL projects.
• Automatic Configuration: Run "MQL: Create configuration" to set up the correct include paths and compiler flags for your MQL version. clangd restarts automatically to apply the new settings.
• Conflict Prevention: The extension automatically disables the Microsoft C++ IntelliSense engine (keeping the extension installed for other features) to prevent duplicate diagnostics and completions.

Symbol Visibility Inside Headers

clangd parses each translation unit once, top-down — unlike the MetaEditor compiler, which concatenates all sources and resolves names multi-pass. By itself this would make symbols declared in the parent .mq4/.mq5 invisible to its included .mqh files (their bodies appear after the header is included).

To solve this transparently, MQL: Create Configuration scans every entry-point .mq4/.mq5 for top-level function definitions and writes a generated header <workspace>/.mql-auto-forwards/<basename>.auto.mqh containing one forward declaration per function. That file is injected via -include ahead of all sibling headers in compile_commands.json, so every .mqh in the chain transparently sees the parent's API.

#line directives in the generated file keep Go to Definition jumping to the real .mq4/.mq5 source location. Default arguments are stripped from the forwards so MQL5 does not error on "default argument redefined" at compile time.

You can safely add .mql-auto-forwards/ to your .gitignore — it is regenerated by the extension on every configuration refresh and is not consumed by MetaEditor.

Note: Go to Definition relies on clangd honoring #line directives to remap symbol locations. Most clangd versions do; if yours lands inside the generated .auto.mqh file instead of the original .mq4/.mq5, the #line annotation above each declaration shows the real source path and line — click it to jump.

Note: On case-insensitive filesystems (Windows, default macOS), the include resolver canonicalizes paths to actual on-disk casing. An #include <Keys.mqh> directive against a keys.mqh file on disk now resolves correctly — earlier versions emitted a wrong-cased compile_commands.json entry, causing clangd to silently parse the header as a standalone TU.

---

Quick Setup Guide

1. Installation:

   • Install this MQL Clangd extension from the VS Code Marketplace.
   • Note: The clangd extension will be automatically installed as a required dependency.

2. Open your project:

   • Open your MQL project folder (e.g., your MQL5 or MQL4 folder).
   • Pro Tip: Ensure your folder name contains "MQL4" or "MQL5" for automatic version detection.

3. Basic Configuration:

   • Open Settings (Ctrl+,) and search for MQL Clangd.
   • Provide the path to your MetaEditor executable (essential for compilation).

4. Initialize IntelliSense:

   • Press Ctrl+Shift+P and run the command: "MQL: Create configuration".
   • This one-time setup configures clangd to recognize your MQL code and libraries.

5. Bonus: Icons:

   • If you wish, set custom icons for MQL files. Press Ctrl+Shift+P, select "MQL: Add icons to the theme", and choose your preferred MQL-supported theme.

💡 Windows Tip: Open MQL5 from Your Projects Folder

MetaTrader stores MQL files deep inside AppData\Roaming. You can create a junction (like a symlink) so the folder also appears in your usual workspace:

New-Item -ItemType Junction -Path 'C:\Users\<you>\source\MQL5' -Target 'C:\Users\<you>\AppData\Roaming\MetaQuotes\Terminal\<ID>\MQL5'

This creates a zero-cost pointer — no duplication, files exist only once. You can now open C:\Users\<you>\source\MQL5 in VS Code directly.

---

Important Notes

• Multi-root workspaces: Fully supported. Settings are resolved from the active file's folder.

• Settings Merge: MQL flags are merged into your existing clangd.fallbackFlags — never overwritten.

• Compiler Flags: We automatically inject -xc++ and -std=c++17 along with version-specific defines (__MQL4__/__MQL5__) to help clangd understand MQL syntax.

• CPU Architecture (MQL5): mql_tools.Compile.CpuArchitecture lets you compile for AVX/AVX2/AVX512 instruction sets via a temporary .mqproj wrapper. Only affects MQL5; incompatible binaries will fail to load on older CPUs. Market uploads require x64 (default).

• Relative Paths & Portable Mode: Settings like mql_tools.Metaeditor.Metaeditor5Dir and mql_tools.Metaeditor.Include5Dir now support ${workspaceFolder} variable substitution and relative paths. This is perfect for portable MetaTrader installations:

  {
    "mql_tools.Metaeditor.Metaeditor5Dir": "${workspaceFolder}/../MetaEditor64.exe",
    "mql_tools.Metaeditor.Include5Dir": "${workspaceFolder}"
  }
  

• Third-party Libraries: If you use libraries like JAson.mqh and clangd reports "Unknown type" errors, you have two options:

  **Option A** - Add to settings (global, affects all files):
  ```json
  {
      "mql_tools.Clangd.ForcedIncludes": [
          "Include/JAson.mqh"
      ]
  }
  ```
  
  **Option B** - Add conditional include in your code (per-file):
  ```mql5
  #ifdef __clang__
  #include <JAson.mqh>
  #endif
  ```
  

  This include is only seen by clangd and ignored by MetaEditor.

MetaEditor on macOS / Linux (Wine)

On non-Windows platforms you can run MetaEditor through Wine while keeping the same workflow.

1. Install Wine (wine64 or wine) and MetaTrader/MetaEditor inside a Wine prefix.

2. Point the extension to your MetaEditor executable (host path inside the Wine prefix), for example:

   {
     "mql_tools.Metaeditor.Metaeditor5Dir": "${workspaceFolder}/../drive_c/Program Files/MetaTrader 5/MetaEditor64.exe"
   }
   

3. Enable the Wine wrapper and (optionally) configure the Wine binary:

   {
     "mql_tools.Wine.Enabled": true,
     "mql_tools.Wine.Binary": "wine64" // or "wine", or full path like "/usr/local/bin/wine64"
   }
   

When mql_tools.Wine.Enabled is true on macOS/Linux:

• Compile / Check commands run MetaEditor via Wine instead of executing the .exe directly.
• Paths for source files, include directories and logs are automatically converted with winepath -w, so MetaEditor sees them as Z:\\... paths.
• Behaviour on Windows is unchanged (the wrapper is ignored on Windows, or when Wine.Enabled is false).

---

Auto-Reload EA After Compile (MT5 Service)

On Wine/macOS (and any setup where MetaTrader doesn't auto-reload the running EA after compile) you can close the loop with a tiny MT5 Service that watches for flag files written by the post-compile task hook.

A ready-to-use service ships under files/CompileListenerService.mq5. Install it with one command, compile in MetaEditor, then start it from Navigator → Services.

Command Palette: MQL: Install Compile Listener Service — copies CompileListenerService.mq5 directly into your MQL5/Services/ folder (auto-detected from mql_tools.Metaeditor.Include5Dir or inferred from the workspace).

How it works

1. The extension's post-compile task hook (mql_tools.Compile.RunTaskOnSuccess) runs a VS Code task after a successful compile. Configure that task to write a flag file, e.g. MQL5/Files/COMPILEFLAGS/<EA>.flag.
2. CompileListenerService.mq5 polls the COMPILEFLAGS folder once per second. When <EA>.flag appears it:
   • deletes the flag file,
   • finds the chart whose CHART_EXPERT_NAME matches <EA>,
   • calls ChartApplyTemplate(chartId, "<EA>.tpl") — which reloads the EA from the named template.

Service inputs

Input	Default	Purpose
expertNames	"EA_Name_1,EA_Name_2"	Comma-separated EA names to watch (no extension). Whitespace around names is trimmed.
showDebugOutput	true	Print per-chart scan info and "applying template" lines to the Experts log.

Notes

• It is a real MT5 service (#property service + OnStart), so it runs independently of any chart and survives terminal reload.
• For each EA, save a template named <EA>.tpl in MQL5/Profiles/Templates/. The service applies that template on reload.
• Failures from FileDelete and ChartApplyTemplate are always logged with GetLastError() so silent retry loops are easy to spot.

---

Live Runtime Log

Monitor your MQL4/MQL5 terminal logs in real-time directly within VS Code—no need to switch to MetaTrader or open external log files.

Features:

• Real-time log tailing: See log messages as they happen
• Status bar integration: Click the status bar item to toggle log monitoring on/off
• Three tailing modes: Standard journal logs, real-time LiveLog output, or the shared common-folder LiveLog (visible during strategy-tester runs)

Log Modes

Mode	Description	Latency
LiveLog (Real-time)	Tails MQL5/Files/LiveLog.txt (auto-rotate at 10MB → LiveLog_YYYY_MM_DD.txt) - uses PrintLive() with immediate disk flush	Instant
LiveLog (Common/Tester)	Tails %APPDATA%\MetaQuotes\Terminal\Common\Files\LiveLog.txt - shared by the terminal and all strategy-tester agents, so backtests stream in real-time too. Requires #define LIVELOG_COMMON before the include	Instant (incl. tester)
Standard Journal	Tails MQL5/Logs/YYYYMMDD.log - uses standard Print() output	Delayed (MetaTrader buffering)

Why multiple modes? MetaTrader's Print() buffers output, causing delays in VS Code. LiveLog uses a custom library (LiveLog.mqh) that writes directly to disk with immediate flush. The Common/Tester variant writes to the shared common data folder so strategy-tester runs are visible too.

Setting up LiveLog (Real-time) Mode

1. Install the library: Run MQL: Install LiveLog Library from the Command Palette, or start tailing and accept the prompt to install.

2. Include in your EA:

   #include <LiveLog.mqh>
   

3. Use PrintLive() or the level-prefixed log functions:

   PrintLive("Hello, World!");
   PrintFormatLive("Value: %d, Price: %.5f", 42, 1.23456);
   
   // Level-prefixed logging (automatically includes source location for Trade Report):
   LogDebug("Debug message");
   LogInfo("Info message");
   LogWarn("Warning message");
   LogError("Error message");
   LogTrade("SIMULATED BUY MARKET");
   

   The Log*() functions automatically embed {File:Function:Line} tags, enabling click-to-source navigation in the Trade Report (see below).

4. Optional - Redirect all Print() calls automatically: Add #define LIVELOG_REDIRECT before the include to automatically redirect all Print() and PrintFormat() calls:

   #define LIVELOG_REDIRECT
   #include <LiveLog.mqh>
   
   // Now all Print() calls automatically go to LiveLog.txt!
   Print("This will appear in LiveLog.txt");
   PrintFormat("Value: %d", 42);
   

5. Optional - See strategy-tester runs live (common folder): Tester agents run in their own sandbox, so the default LiveLog file is invisible during backtests. Add #define LIVELOG_COMMON before the include to write to the shared common data folder instead, then switch the watcher to LiveLog (Common/Tester) mode:

   #define LIVELOG_COMMON
   #include <LiveLog.mqh>
   
   // Log lands in Common\Files\LiveLog.txt - one real-time file
   // for live charts AND strategy-tester runs
   

6. Optional - Clean session end marker: Call LiveLogClose() from your OnDeinit to write a "Session Ended" marker:

   void OnDeinit(const int reason)
   {
      LiveLogClose();  // Optional - writes "Session Ended" marker
      // ... your other cleanup code ...
   }
   

Commands:

• MQL: Toggle Live Runtime Log — Start/stop log tailing
• MQL: Install LiveLog Library — Deploy LiveLog.mqh to your Include folder
• MQL: Switch Log Tail Mode (Live/Common/Standard) — Switch between real-time, common-folder (tester) and standard modes

Notes:

• The extension automatically detects MQL version from your active file, workspace folder name, or configured settings
• If the data folder path is not configured, the extension will attempt to infer it from your workspace structure
• Only new log entries are shown (historical logs are not dumped on start)
• LiveLog.txt auto-rotates at 10MB (renamed to LiveLog_YYYY_MM_DD.txt) to prevent disk space issues

---

Trade Report Dashboard

Analyze your Strategy Tester results directly in VS Code. The Trade Report parses MT5 tester log files and displays trades, P&L, and log entries in an interactive dashboard.

Command: MQL: Open Trade Report Dashboard

Features:

• Auto-discovers EAs with test runs under MQL5/Experts/
• Shows trade summary: count, net P&L, win rate, gross profit/loss, commissions
• Individual trade table with entry/exit prices, SL, TP, lots, and exit reason
• Filterable log viewer (ALL, TRADE, INFO, WARN, DEBUG, ERROR)
• Click any log line number to jump to that line in the .log file

Source Code Navigation (Click-to-Source)

When using LiveLog Log*() functions, each log entry and trade automatically includes a source location tag. In the Trade Report, these appear as clickable yellow badges that jump straight to the corresponding line in your MQL source code.

Setup: Just use LiveLog's level-prefixed functions — source tags are embedded automatically:

#include <LiveLog.mqh>

void OnTick()
{
    LogInfo("Checking for entry signal");

    if (buySignal)
    {
        LogTrade("SIMULATED BUY MARKET");
        LogInfo("Entry: " + DoubleToString(price, 5) + " | SL: " + DoubleToString(sl, 5) + " | TP: " + DoubleToString(tp, 5) + " | Lots: 0.10");
    }
}

The Trade Report will show:

• Source column in the trades table with clickable entry/exit source links
• Yellow source badges on each log entry (e.g. OnTick:12) that open the file at that line

Note: Source navigation requires LiveLog. Without it, trades and log entries still appear but without clickable source links.

Source Snapshots

Editing your EA after a test run can break {File:Function:Line} links. Source Snapshots solve this by copying all referenced source files into a snapshot/ folder next to the log file on first report open.

Enable it:

// settings.json
"mql_tools.TradeReport.SnapshotSources": true

When a snapshot exists the Trade Report shows two clickable badges per source location:

• Green badge — opens the snapshot (frozen copy from test time, line numbers always match)
• Yellow badge — opens the current (live) file in your workspace

The dashboard also marks runs that have a snapshot with a small snapshot label.

Warning: Enabling this setting increases disk usage because a full copy of every referenced source file is stored per run. If you run many tests the extra space can add up — disable the setting or delete snapshot/ folders you no longer need.

---

Run Backtest

Launch an MT5 Strategy Tester run for your EA directly from VS Code — without touching the MetaTrader UI.

Requires: TradeReportServer running (or auto-started) and a tester.ini file in the EA's folder.

How to use:

1. Open any .mq5, .mq4, or .mqh file belonging to your EA.
2. Press Ctrl+Alt+T, click the ⚗ Run Backtest button in the editor title bar, or run MQL: Run Backtest from the Command Palette.
3. Select the EA (auto-detected from your current file, or pick from a list).
4. Choose the symbol and date range (pre-filled from tester.ini).
5. MT5 launches the Strategy Tester in the background. A progress notification tracks elapsed time.
6. When the test finishes, the Trade Report Dashboard opens automatically with the new results.

Settings:

Setting	Default	Description
mql_tools.Backtest.PromptForParameters	true	Show symbol/date prompts before running. Set false to use tester.ini defaults silently.
mql_tools.Backtest.AutoOpenReport	true	Open the Trade Report Dashboard when the test completes.
mql_tools.Backtest.VisualMode	null	true/false forces Visual=1/Visual=0 in the generated tester.ini (visual chart testing). null keeps the EA's INI value.
mql_tools.Backtest.KeepTerminalOpen	null	true writes ShutdownTerminal=0 so MT5 stays open after the test; false writes ShutdownTerminal=1. null keeps the EA's INI value. An open terminal can block the next launch (one MT5 instance per data folder).
mql_tools.Backtest.MonitorTimeoutMinutes	10	Minutes to monitor a running test before giving up. Only stops the VS Code progress notification — the MT5 test keeps running. Increase for visual mode or long date ranges.
mql_tools.Backtest.AutoStartServer	true	Auto-start TradeReportServer if it isn't already running.
mql_tools.Backtest.ServerDir	empty	Optional path to the TradeReportServer Node.js package folder. When empty, auto-start uses <MQL5 data folder>/Tools/TradeReportServer.
mql_tools.Backtest.ServerPort	3002	Port used by TradeReportServer.
mql_tools.ShowButton.RunBacktest	true	Show/hide the toolbar button on MQL files.

Notes:

• The test runs fully inside MT5 — cancelling the VS Code progress notification only stops monitoring, not the MT5 test itself.
• A tester.ini file must exist in the EA's folder (e.g. Experts/Trading/MyEA/tester.ini) for the server to know the default test configuration.
• mql_tools.Metaeditor.Include5Dir should point to the MQL5 data folder (the folder containing Include, Experts, Logs, etc.). On Linux/Wine this is usually a host path under your Wine prefix, for example /home/<user>/.wine/drive_c/Program Files/<Vendor> MT5 Terminal/MQL5.
• If your terminal does not contain MQL5/Tools/TradeReportServer, set mql_tools.Backtest.ServerDir to the actual TradeReportServer package folder, or set mql_tools.Backtest.AutoStartServer to false and start the server manually on mql_tools.Backtest.ServerPort.

---

Backtest Setup

tester.ini File Location and Format

Each EA requires a tester.ini configuration file in its folder:

MQL5/Experts/<YourEA>/tester.ini

Copy the template from docs/backtest/artifacts/tester.ini.example and adjust values for your EA.

Required fields in the [Tester] section:

Field	Description	Example
Expert	EA name (without .ex5 extension)	MyEA
Symbol	Trading symbol	EURUSD
FromDate	Start date (format: YYYY.MM.DD)	2025.01.01
ToDate	End date (format: YYYY.MM.DD)	2025.01.31
Period	Timeframe (optional, defaults to M1)	M5

Date format: All dates must use the YYYY.MM.DD format (e.g., 2025.01.31).

Example tester.ini:

[Tester]
Expert=MyEA
Symbol=EURUSD
Period=M5
Model=0
ExecutionMode=0
Optimization=0
FromDate=2025.01.01
ToDate=2025.01.31

[Inputs]
RiskPercentage=1.0||1||0.1||10||Y

VS Code Settings for Backtesting

Setting	Description
mql_tools.Backtest.PromptForParameters	If true, prompts for symbol and date before running. If false, uses tester.ini defaults silently.
mql_tools.Backtest.TesterLogDir	Optional path to MT5's tester agent log directory. Only set if auto-detection fails.
mql_tools.Backtest.VisualMode	Force visual mode on (true) or off (false) for every launch. null (default) respects the EA's INI.
mql_tools.Backtest.KeepTerminalOpen	Keep MT5 open after the test (true → ShutdownTerminal=0). null (default) respects the EA's INI.
mql_tools.Terminal.Terminal5Dir	Path to terminal64.exe. Required on all platforms. Auto-detects common locations on Windows.
mql_tools.Metaeditor.Include5Dir	Path to MQL5 data folder (contains Include, Experts, Logs, etc.).

How MT5 Writes the Tester Log

When a backtest runs, MT5's Strategy Tester agent writes logs to a specific directory. The runner finds these logs as follows:

Windows:

%APPDATA%\MetaQuotes\Tester\<terminal-id>\Agent-127.0.0.1-3000\logs

Linux/macOS (Wine):

<Wine_prefix>/drive_c/users/<user>/AppData/Roaming/MetaQuotes/Tester/<terminal-id>/Agent-127.0.0.1-3000/logs

The extension:

1. Auto-detects the log directory based on the terminal identity (derived from Include5Dir)
2. Monitors the latest *.log file for the completion marker (MetaTester 5 stopped)
3. Copies the completed log to the EA's runs/ folder: MQL5/Experts/<YourEA>/runs/<timestamp>.log

If auto-detection fails, set mql_tools.Backtest.TesterLogDir to the full path of the agent logs directory.

Important Notes

• Each Run Backtest command overwrites <MQL5>/tester.ini with your EA's tester.ini plus any parameters chosen for the run. Back up your hand-tuned <MQL5>/tester.ini first if you need to preserve it.
• Backtest logs are stored in MQL5/Experts/<YourEA>/runs/ — each run creates a timestamped .log file.
• The Trade Report Dashboard opens automatically after test completion (controlled by mql_tools.Backtest.AutoOpenReport).

---

Arrange MT5 Charts

Tile your MetaTrader 5 chart windows into saved layouts from VS Code. Charts docked inside the terminal snap into a grid; charts you undock (right-click → uncheck Docked) spread across your other monitors.

Command: MQL: Arrange MT5 Charts — pick a named preset. Or click the Charts button in the status bar for fast switching (toggle with mql_tools.ChartLayout.ShowStatusBarButton).

Define presets in mql_tools.ChartLayout.Presets. Each has a required docked grid and an optional floating grid for undocked charts. Monitors are numbered 1-based (Windows enumeration order).

"mql_tools.ChartLayout.Presets": [
  // All charts docked, tiled 2×4 inside MT5 on monitor 1.
  { "name": "wall",  "docked": { "monitor": 1, "rows": 2, "cols": 4 } },
  // Docked charts on monitor 1; undocked charts side-by-side on monitor 2.
  { "name": "split", "docked":   { "monitor": 1, "rows": 2, "cols": 3 },
                     "floating": { "monitor": 2, "rows": 1, "cols": 2 } }
]

Charts are matched by SYMBOL,TIMEFRAME title, so panels (Market Watch, Navigator) are never touched.

Beyond uniform grids: a docked/floating block can use a CSS grid-template-areas template for spans (one chart wider or taller than the rest), and naming the cells after timeframes (M5, H1, …) places charts by timeframe, bound to the active chart's symbol (others minimized).

"mql_tools.ChartLayout.Presets": [
  // Letters = spans: A wide on top, B tall down the right, C wide on the bottom.
  { "name": "tall-right", "docked": { "monitor": 1, "areas": ["A A B", "C C B"] } },
  // Timeframe names = match by timeframe: M5 wide top, H1 tall right, M15 bottom,
  // all from the active chart's symbol; charts of other symbols are minimized.
  { "name": "scalp",      "docked": { "monitor": 1, "areas": ["M5 M5 H1", "M15 M15 H1"] } }
]

See the full guide for the rules (rectangular regions, empty . cells, timeframe tokens).

⚠️ Windows only (for now) — it moves native MT5 windows via the Win32 API; a no-op on macOS / Linux / Wine.

Full guide: docs/chart-layout.md.

---

MQL Debugger (Real-Time Variable Inspection)

Debug your MetaTrader Expert Advisors and Scripts directly from VS Code. The extension injects telemetry at your breakpoints, compiles an instrumented build, and streams variable states to a live debug dashboard — no MetaEditor debugger needed.

How to use:

1. Open the .mq5, .mq4, or .mqh file you want to debug.
2. Place breakpoints in the editor margin (click to the left of the line numbers) where you want to inspect variables.
3. Click the Start Debugging (bug icon) button in the editor title bar, or press Ctrl+Alt+D, or run MQL: Start Debugging from the Command Palette.
   • Starting from an .mqh file automatically resolves dependencies and asks which main EA to instrument.
4. The extension will automatically:
   • Deploy MqlDebug.mqh to your MetaTrader Include/ folder (always up to date).
   • Instrument all relevant source files (main EA + included headers with breakpoints).
   • Compile a temporary *.mql_dbg_build.ex5 file without touching your original .ex5.
   • Start watching the debug log file.
   • Open the MQL Debug panel in VS Code.
5. In MetaTrader, attach the newly compiled EA/Script to a chart.
6. As the EA executes and hits breakpoints, variables populate and update in real-time in the debug dashboard.
7. When finished, click Stop Session in the notification or run MQL: Stop Debugging.

What variables are automatically watched

At each breakpoint the extension automatically collects variables into two tiers depending on the mql_tools.Debug.DetailLevel setting:

Default mode (always active):

Source	Example
Function parameters	double price, int magic
Local variables declared before the breakpoint	int bar = 0;
Member access expressions used in the function	g_timers.lastTime, this.m_count, a.b.c
Implicit class members referenced near the breakpoint	m_lotSize used inside a class method

Deep Analysis mode (mql_tools.Debug.DetailLevel: deepAnalysis) — additionally:

Source	Example
Global primitive variables referenced within ±15 lines	g_spread, g_signal
input / sinput parameter variables (always, no proximity filter)	InpLotSize, InpMaxOrders
Primitive fields of local class-typed variables	order.lots, order.openPrice

Supported types: int, uint, short, ushort, char, uchar, long, ulong, double, float, string, bool, datetime, color, common ENUM_* types, and arrays of numeric types.

Manual watch annotations

Add a // @watch comment near any breakpoint to explicitly name variables that should be watched, even if the auto-detector would miss them:

// @watch myVar otherVar
SomeFunction();  // ← breakpoint here

Multiple variables can be listed on one line. Annotated variables are always watched first.

Breakpoint conditions

VS Code conditional breakpoints are fully supported. Set a condition in the breakpoint editor and the injected code wraps the telemetry in an if block — the EA only pauses when the condition is true.

Pause / Continue (blocking breakpoints)

Each breakpoint injects a MQL_DBG_PAUSE call that spin-waits until you press Continue or Stop in VS Code. This lets you inspect a frozen state before the EA resumes.

Warning: The EA thread is fully blocked while paused. No OnTick/OnTimer events fire. Use only on demo accounts or in the Strategy Tester. Auto-resumes after 120 seconds as a safety failsafe.

Call stack tracking

Functions containing breakpoints automatically get ENTER/EXIT instrumentation injected, so the debug dashboard shows a live call stack as functions are entered and returned.

Settings

Setting	Default	Description
mql_tools.Debug.DetailLevel	default	default: locals + member access. deepAnalysis: also global primitives, input vars, and class field expansion.
mql_tools.ShowButton.StartDebugging	true	Show/hide the toolbar bug button on MQL files.

Notes:

• Class-typed variables are not serialized directly (would cause compile errors). Only their primitive/enum fields are watched.
• If an injection point is unsafe (e.g. inside a braceless single-line block), the debugger warns and skips that line. Use // @watch or add a statement to create a safe injection point.
• The instrumented build uses .mql_dbg_build in the filename — never commit or deploy these files.

---

Troubleshooting clangd diagnostics (MQL-specific)

If you open built-in examples like MQL5/Experts/Examples/MACD/MACD Sample.mq5 and see a large number of clangd errors, work through the steps below.

1. Make sure the workspace is configured

   • Run MQL: Create configuration (from the Command Palette) once per workspace root.
   • This command:
     • Updates .vscode/settings.json with the required clangd.fallbackFlags.
     • Generates a .clangd file in the workspace to suppress many MQL-specific false positives.

2. Verify include paths

   • The extension adds -I flags for your MQL4/MQL5 root and its Include directory based on your MetaEditor path.
   • If your MetaTrader installation lives in a non-standard location, set the appropriate mql_tools.Metaeditor.* settings (for example Metaeditor5Dir and Include5Dir), then run MQL: Create configuration again.
   • Advanced: you can manually extend clangd.fallbackFlags in .vscode/settings.json with extra -I... or -include... flags; MQL Clangd merges its own flags with your existing ones instead of overwriting them.

3. Add forced includes for framework / library headers

   • For additional frameworks or helper headers that define lots of types or functions used by your project, prefer:
     • mql_tools.Clangd.ForcedIncludes (global, for all MQL projects), or
     • #ifdef __clang__ includes inside specific .mq4/.mq5 files (per-file).
   • This is often enough to fix "unknown type/function" diagnostics without changing how MetaEditor compiles your code.

4. Tuning diagnostics via the generated .clangd file

   • The .clangd file generated by the extension already suppresses many diagnostics that are known to be noisy for MQL (preprocessor directives, array peculiarities, overload resolution differences, and so on).
   • If you still hit a clangd-only warning that is harmless in MQL, you can:
     • Open the .clangd file at the workspace root.
     • Add the diagnostic ID to the Diagnostics: Suppress: list.
   • This gives you fine-grained control over which clangd checks remain active.

   Tip: Intentional assignment in conditions

   If you see "Possible assignment in condition" for intentional code like if(ticket = OrderSend(...)), you can silence it by adding extra parentheses:

   // Warning: assignment in condition
   if (ticket = OrderSend(...)) { }
   
   // No warning: extra parentheses signal intent
   if ((ticket = OrderSend(...))) { }
   

5. Cleaning up old configuration

   • Leftover clangd.fallbackFlags from other extensions (e.g. the original MQL Tools) can cause issues. Remove stale flags from .vscode/settings.json, then re-run MQL: Create configuration.

---

FAQ: Common Questions

How can I make clang-format more relaxed for MQL code?

If clang-format is reformatting your MQL code in ways you don't like, you have several options:

1. Disable formatting entirely for MQL files (recommended for MQL): Add this to your .clangd file:

   ---
   If:
     PathMatch: .*\.(mq4|mq5|mqh)
   Diagnostics:
     # ... your existing suppressions
   Style:
     # Disable clang-format for MQL files
     DisableFormat: true
   

2. Customize clang-format style: Create a .clang-format file in your workspace root with relaxed settings:

   BasedOnStyle: LLVM
   IndentWidth: 3
   ColumnLimit: 0
   AllowShortFunctionsOnASingleLine: All
   AllowShortIfStatementsOnASingleLine: true
   AllowShortLoopsOnASingleLine: true
   BreakBeforeBraces: Attach
   SpaceAfterCStyleCast: false
   

3. Use MetaEditor's formatting instead: Since MetaEditor has its own formatting rules, you might prefer to format MQL code in MetaEditor and disable clang-format in VS Code entirely.

Is it risky to suppress so many diagnostics?

Short answer: For MQL code, it's necessary and safe.

Why we suppress diagnostics:

• MQL is not standard C++. It has different syntax, keywords, and semantics.
• clangd is a C++ language server that doesn't natively understand MQL-specific features like:
  • #property and #import directives
  • input and sinput keywords
  • export modifier
  • Flexible arrays in classes
  • Different type conversion rules
  • Different overload resolution
  • MQL's custom string type

What we suppress:

• False positives: Errors that clangd reports but are valid MQL code
• MQL-specific syntax: Features that don't exist in standard C++
• Type system differences: MQL is more permissive with conversions

What we DON'T suppress:

• Logic errors in your code
• Undefined variables (that aren't MQL built-ins)
• Type mismatches that would also fail in MQL
• Most code completion and IntelliSense features

The trade-off:

• ✅ You get excellent IntelliSense, code completion, and navigation
• ✅ You avoid hundreds of false-positive errors
• ⚠️ You might miss some edge-case C++ errors (but MetaEditor will catch them during compilation)

Best practice: Use both tools together:

• Use VS Code + clangd for editing, navigation, and IntelliSense
• Use MetaEditor for final compilation and testing
• If you see a real error, add it to your .clangd suppressions only if it's a false positive and report an issue to this repository.

Can I add more diagnostic suppressions?

Yes! If you encounter additional false positives:

1. Identify the diagnostic code:

   • Hover over the error in VS Code
   • Look for the diagnostic code in brackets, e.g., [unknown_typename] or [-Wunused-variable]

2. Add it to .clangd: Open the .clangd file in your workspace root and add the code to the Suppress list:

   Diagnostics:
     Suppress:
       # ... existing suppressions
       - your_diagnostic_code_here
   

3. Save and reload: The changes should take effect immediately. If not, reload the VS Code window.

Preserving Custom Diagnostic Suppressions

The .clangd file is generated by the "MQL: Create configuration" command. If you have added custom diagnostic suppressions, you can preserve them when re-running the command.

Configuration option: mql_tools.Clangd.PreserveSuppressions

• prompt (default): Ask whether to merge suppressions each time
• always: Automatically merge existing suppressions
• never: Always overwrite the .clangd file

Merging combines your custom suppressions with the defaults, deduplicating automatically. Set this in your VS Code settings (.vscode/settings.json or global settings):

{
  "mql_tools.Clangd.PreserveSuppressions": "always"
}

If set to "prompt", you'll see a choice dialog when an existing .clangd is found.