App::MoarVM::Debug

The interactive MoarVM debugger installs a script called raku-remote-debug that allows a developer to start a Raku program in debugger mode, while in another window allows the developer to step through the program and perform various types of introspection.

Starting in debugger mode

$ raku-remote-debug your-program.raku arg1 arg2

Starting a program in debugger mode is as simple as replacing raku by raku-remote-debug on the command line. That's it.

When it is started this way, it will show a text on STDERR such as:

Running with debugging enabled at localhost port 27434

Your program will not actually execute until you have entered the resume command in the debugger.

Starting the debugger

$ raku-remote-debug

To start the debugger, call raku-remote-debug without any arguments. It will show you a text such as:

Welcome to the MoarVM Remote Debugger

Connecting to MoarVM remote on localhost port 27434
success!
>

You would typically then set breakpoints or do some introspection. And then start the program by typing "resume" to lift the suspension of all threads in the program.

Type "help" in the debugger's CLI to see what commands are available to you.

Limitations

The debugger uses a single port to communicate between your program and the debugger. By default this is port 27434.

This means that on any given computer, only one program can be debugged this way, and only one debugger can run at the same time.

Should you need to have more debuggers running at the same time, or for some reason you need to use another port, you can set the environment variable MVM_DEBUG_PORT to the port you'd like to use.

To start your program:

$ MVM_DEBUG_PORT=4242 raku-remote-debug your-program.raku arg1 arg2

To start the debugger:

$ MVM_DEBUG_PORT=4242 raku-remote-debug

Some hints

(Optional) Write assume thread 1 to assume tracking of first (main) thread
Set a breakpoint
breakpoint "my-script.raku" 1234 1 1

The string is the filename and 1234 is the line number (1 1 is the secret ingredient). Ensure the line number doesn't point to an empty line.

Type resume to run your script.
The breakpoint will trigger, you can type all lexicals to view all lexicals. The numbers shown next to them in bold are "handle" numbers.
Find the object you want to dump and type metadata 1234 (1234 is the handle number).

If the features includes attributes, you can enter attributes 1234 for this object to get information about the object's attributes.

If the features includes positional, you can enter positionals 1234 to get information about the positional elements of the object.

If the features includes associative, you can enter associatives 1234 to get information about the associative elements (keys and values) of the object.

The metadata command is only needed if you don't know which of these commands is useful for any given type.

Type help to see all of the available commands.

Known Issues

The only stepping mode currently available is Step Into.

Backtraces will show incorrect line numbers.

AUTHOR

Timo Paulssen

Source can be located at: https://github.com/raku-community-modules/App-MoarVM-Debug . Comments and Pull Requests are welcome.

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.