Debugging

Unfortunately, IDEA Community Edition currently will not start an IDE-based debugging session.  For that, IDEA Ultimate is required. (EAP is free and may work, though it’s technically unsupported.)  

Command-line debugging for C++ projects is always available because that is a feature of the Haxe language itself.

Debugging JavaScript Targets

*We need someone who has done this to fill in this section.*

JavaScript debugging is not supported within IDEA itself.  However, the Haxe compiler does create source maps that browser debuggers can use for source level debugging.

Debugging Flash Targets

(Note: The plugin team does not use these targets regularly.  Accordingly, these instructions need review and clarification by a regular user.  Please let us know of deficiencies.)

Flash targets require a Flash player or AIR player to be installed.  IDEA can use either.  See Adobe’s Getting Started page, to get an appropriate environment set up.

The Flex plugin must be installed within IDEA.  It is shipped with IDEA by default, but you have to visit the Settings to enable it.  (File->Settings->Plugins; make sure that Flex is enabled.)

Start a debugging session via the normal means (Run menu, Ladybug icons, Shift-F9 key, etc.).  The plugin will launch FlashPlayer/AIR debugger, create a connection to it, and then immediately launch the .SWF file from the compilation.  If it’s an OpenFL project, lime will be used to launch the app.  For other project types, the .SWF is launched as if it were a command.  Therefore, you must have your OS environment set up to run the associated viewer.  (For Windows, this would be “ASSOC .swf-ShockwaveFlash.ShockwaveFlash”)

There is an excellent YouTube Video by Jason Sturges on how to set up Flash Debugging for Mac OS.  (It’s roughly the same process for other platforms.)

Debugging C++ Targets

See the hxcpp-debugger project for more information.

C++ projects can be debugged in source mode directly in IDEA.  To do so, you must include the hxcpp library in your project and start the debugger in your code.

The hxcpp debugger functionality conforms to the Haxe v3.0 debugger. In order to use this, you must:

  • Install the *VERSION 1.1* debugger haxelib from https://github.com/HaxeFoundation/hxcpp-debugger/tree/protocol_v1.1.  The hxcpp-debugger that is installed via ‘haxelib install’ is generally not the latest or best working version. (The Haxe Foundation maintainers do not release regular updates for it). Instead, get the current sources locally: Install git and clone the repository from http://github.com/HaxeFoundation/hxcpp-debugger and install via
    haxelib git hxcpp-debugger <your_local_clone> protocol_v1.1
    

    Then, you’ll have the version that matches the plugin. Whenever you need to update the debugger to the latest sources, do a ‘git pull’ and then rebuild your app.

  • Re-build your project using this newest debugger haxelib.
  • Configure your haxe program to start the debugger when the following command line option is provided:
          -start_debugger
    

    If you expect to do remote debugging, you’ll also have to support:

          -debugger_host=[host]:[port]
    

    Most likely you’ll just want to add the following in your main() when

    -start_debugger

    is set:

          new debugger.HaxeRemote(true, host, port);
    

    Generally speaking, the build/debug configuration (Run->Edit Configurations)
    is set up to use port 6972, so you can probably cheat and use:

          new debugger.HaxeRemote(true, "localhost", 6972);
    

    However, the line has to match your debug settings. Fortunately, they are passed to your program on the command line. Notice the

    -start_debugger -debugger_host=localhost:6972

    passed to haxelib:

          C:/HaxeToolkit/haxe/haxelib.exe run lime run C:/temp/issue349/openfl_cpp_debug/openfl_cpp_debug/project.xml
          windows -verbose -Ddebug -debug -args -start_debugger -debugger_host=localhost:6972
    

 

Your program should now:

  1. Look for the
    -start_debugger

    parameter before doing anything. It won’t be there if the program is being started via the “Run” command from IDEA.

  2. Parse the
    -debugger_host=

    parameter. If it exists, then a remote controller (e.g. IDEA) will be trying to connect on that port.
    If it doesn’t exist, then the user (you) probably want to start the command line debugger:

    new debugger.Local(true);

Here’s a snippet you can use: (Thanks to @isBatak)

#if (debug && cpp)
  var startDebugger:Bool = false;
  var debuggerHost:String = "";
  var argStartDebugger:String = "-start_debugger";
  var pDebuggerHost:EReg = ~/-debugger_host=(.+)/;
  for (arg in Sys.args()) {
    if(arg == argStartDebugger){
      startDebugger = true;
    }
    else if(pDebuggerHost.match(arg)){
      debuggerHost = pDebuggerHost.matched(1);
    }
  }

  if(startDebugger){
    if(debuggerHost != "") {
      var args:Array<String> = debuggerHost.split(":");
      new debugger.HaxeRemote(true, args[0], Std.parseInt(args[1]));
    }
    else {
      new debugger.Local(true);
    }
  }
#end