Repository navigation
Debugging HashLink
The HashLink debugger debugs programs compiled to HashLink bytecode (.hl files) and running on the HashLink
virtual machine. The debugger itself ships with the plugin; you only need a HashLink runtime. For the workflow all
debuggers share, see Debugging Overview.
- Haxe 4.1 or later. Haxe 4.3 or later gives the best results; see Older Haxe versions.
- HashLink 1.13 or later. The debugger runs on the same HashLink runtime as your program.
HashLink release binaries are published for Windows on the HashLink releases page. For Linux and macOS, use the nightly build from the same page or build HashLink from source.
The plugin looks for the HashLink executable (hl) in this order:
- The Use custom HashLink binary: field of the run configuration, when you turn it on.
- The HashLink executable: field under Runtime Overrides in Settings | Build, Execution, Deployment | Build Tools | Haxe, when it is set. The path must exist; nothing else is tried then.
- The HashLink executable: field in the Runtimes section of the Haxe SDK's settings. See Installation for where the SDK settings are.
- The environment variables
HASHLINK_BIN,HASHLINKandHASHLINKPATH. Each may point at the executable or at the folder that contains it. - Your
PATH.
The debugger works with HashLink bytecode only. Compile with -hl and a file name ending in .hl:
-cp src
-main Main
-hl bin/main.hlHL/C output (-hl with a .c file name) is compiled to a native program and cannot be debugged with this debugger.
A debug build also needs -debug. When you debug through a configuration with a Run Haxe action step, the plugin
adds -debug for you, so you don't need it in the build file. See
Debug builds are made for you.
For Lime and OpenFL projects, use the hl target. Lime packages the bytecode as hlboot.dat, next to a copy of the
HashLink runtime named after your application. The run configuration created from Build & run points at both.
The easiest way is the Haxe tool window: right-click the build file's Build & run entry and choose Debug. This creates a HashLink Application configuration that builds the file before every launch.
To create one by hand, use Run | Edit Configurations…, click +, open the Haxe group and choose HashLink Application. Add a Run Haxe action step under Before launch if the configuration should build first; see The Run Haxe action before-launch step.
| Field | What it does |
|---|---|
| Module: | The module the program belongs to. Its Haxe SDK supplies the HashLink path unless the project overrides it, and relative paths are resolved against its folder. |
| Compiled HashLink binary (.hl / hlboot.dat): | The bytecode to run. A relative path is resolved against the module's folder. |
| Working directory: | The folder the program runs in. Empty means the folder of the binary. |
| Use custom HashLink binary: | Runs the program with this HashLink executable instead of the one found automatically. Lime and OpenFL builds use it for the runtime copy Lime packages with your application. |
The configuration has no field for program arguments.
- Line breakpoints, with conditions. A breakpoint on a line without code is shown as invalid, with the message no executable code at this line (stale build?).
- Stepping: Step Over, Step Into, Step Out, Run to Cursor and Pause. Smart Step Into lists the calls on the current line that the debugger can enter.
- Threads: when the program stops, every thread stops. Select any thread in the Frames view to see its stack and variables. You cannot suspend or resume a single thread.
-
Variables: locals and arguments,
thisand a Statics group with the static fields of the current class. Objects, arrays, maps, enums, anonymous structures, closures andDynamicvalues can be expanded; a closure lists the variables it captured. Long arrays and maps show their first 512 entries. - Registers: a Registers tab in the Debug tool window shows the raw HashLink registers of the selected frame, and the CPU registers of the top frame.
-
Evaluate Expression, watches and hover: full Haxe expressions with operators, field access, array and map
indexing (
map[key]), the ternary operator,is, calls to functions and methods, string literals andnew. Names are looked up in this order: local variables, fields ofthis, static fields of the current class, then class names. -
Set Value, in any frame. You can also assign in Evaluate Expression, for example
count = count * 2orname = "test". - Exception breakpoints: caught, uncaught, critical errors (null access, out of bounds, invalid casts and other errors the HashLink runtime raises) and single classes. See Exception breakpoints.
- Program output appears in the console. Stop ends the program.

A HashLink session: the thread selector (1), the frames of the selected thread (2), the Statics group (3) and the Registers tab (4)
Graphical programs, such as games built with Heaps or SDL, open their window as usual while you debug them.
-
Step Into does not enter every call. Calls that are dispatched at run time are stepped over: calls through an
interface, calls to a method that a subclass overrides, calls to
dynamicmethods and calls through a function value (a closure). Set a breakpoint in the function you want to reach instead. -
Creating values in Evaluate depends on your program.
new MyClass(...)works only for classes your program creates somewhere itself; for other classes the debugger reports it as unavailable. -
Calls in Evaluate take few arguments. On 64-bit HashLink, a call can pass at most four arguments on Windows.
On Linux the limit is six arguments, plus up to eight
Floatarguments. For a method call, the object counts as one of them. A call that throws an exception it does not catch fails. - Changing an argument may not affect the current line. When you change a function argument with Set Value, code later in the function sees the new value, but the current line may still use the old one. The console shows a note when this can happen. To be sure, change the value in the calling function before the call.
-
The compiler can optimize code away, even in debug builds. A
switchon a known value keeps only the matching branch, so a breakpoint on itsswitchorcaseline is shown as invalid. A loop over a constant range such asfor (i in 0...3)may be unrolled, so a breakpoint in it stops less often than expected. A local variable whose value the compiler can fold into the code that uses it, for example one that is only read in anifcondition, may not exist in the compiled program and then does not appear in Variables. See Code the compiler optimized away.
With programs compiled by Haxe 4.1 or 4.2, some details are less precise:
- When the program stops on
throw "message", the stop may show a wrapper class name instead of the message. - The native stack trace stored in an exception shows raw addresses instead of source locations.
- Stepping over a
throwthat acatchhandles may not stop in thecatchblock.
- Windows: works with 64-bit and 32-bit HashLink.
-
Linux: works with the HashLink nightly build. Note two points:
- The debugger attaches to your program from a separate process. Some distributions, such as Ubuntu, only let a
process debug processes it started itself, so attaching fails. Allow it with
sudo sysctl kernel.yama.ptrace_scope=0; the setting lasts until the next reboot. - Multi-threaded programs: HashLink on Linux attaches the debugger to the main thread only. If a breakpoint is hit on any other thread, the program is killed. Single-threaded programs are not affected.
- The debugger attaches to your program from a separate process. Some distributions, such as Ubuntu, only let a
process debug processes it started itself, so attaching fails. Allow it with
- macOS: not tested yet.
Getting started
Working with projects
- The Haxe Tool Window
- Build Files
- Targets and Sections
- Resolve Context
- Libraries and Haxelib
- Defines and Custom Targets
- Building and Running
- Run Configurations
- Tools
- Compilation Server
Debugging
Testing
Profiling
Editing code
- Code Completion
- Diagnostics and Inspections
- Refactoring and Navigation
- Formatting and Code Style
- Conditional Compilation
- Editor Extras
Reference