How to use ChakraCore Debug API

[lemmel]

Hi.

Once the JsDiagStartDebugging call is done with a certain callback, and a call to JSRun is in the process of the provided code, the provided callback is called with the event JsDiagDebugEventSourceCompile.
That's ok.
But the code provided to JSRun is always runned before taking into account any call to JsDiagSetBreakpoint, or JsDiagRequestAsyncBreak, even if these functions are called inside the callback, or called before JSRun.

And so I always end with the JsErrorDiagNotAtBreak error code.
Furthermore with more complex code, any "echo" in the JS code is done (and visible in the console) when the call to JSRun is completed. So anything done after the JSRun completion seems to be useless as the JS code will be executed.

Can you tell how to start the debugging and stop at the first line ?

P.S.: You can find below, one of my many attempts to get it right.

#include <cstdio>
#include <cstring>
#include <cstdlib>
#include "ChakraCore.h"
#define EXCEPTION_MAX_LENGTH 255

class ErrorCode
{
  bool withException;
  JsErrorCode errCode;
public:
  explicit ErrorCode(bool withException = true):withException(withException), errCode(JsNoError){}
  explicit ErrorCode(JsErrorCode errCode, bool withException = true):withException(withException)
  {
    (*this) = errCode;
  }
  ErrorCode(const ErrorCode& errorCode)
    :withException(errorCode.withException), errCode(errorCode.errorCode())
  {}
  operator bool() const
  {
    return errCode == JsNoError;
  }
  JsErrorCode errorCode() const{return errCode;}
  ErrorCode& operator()(JsErrorCode errorCode, const char* errorMessage) noexcept (false)
  {
    this->errCode = errorCode;
    if (errorCode == JsNoError)
      return *this;
    char buffer [EXCEPTION_MAX_LENGTH + 1];
    size_t actualLength;
    JsErrorCode error;

    JsValueRef exception;
    if ((error = JsGetAndClearException(&exception)) != JsNoError)
    {
      printf("Error on Error! Original error code=%d, new error code=%d; extra info=%s\n",errorCode, error, errorMessage);
      exit(EXIT_FAILURE);
    }

    JsPropertyIdRef messageName;
    if ((error = JsCreatePropertyId("message", strlen("message"), &messageName)) != JsNoError)
    {
      printf("Error on Error! Original error code=%d, new error code=%d; extra info=%s\n",errorCode, error, errorMessage);
      exit(EXIT_FAILURE);
    }

    JsValueRef messageValue;
    if ((error = JsGetProperty(exception, messageName, &messageValue)) != JsNoError)
    {
      printf("Error on Error! Original error code=%d, new error code=%d; extra info=%s\n",errorCode, error, errorMessage);
      exit(EXIT_FAILURE);
    }
    if ((error = JsCopyString(messageValue, buffer, EXCEPTION_MAX_LENGTH, &actualLength)) != JsNoError)
    {
      printf("Error on Error! Original error code=%d, new error code=%d; extra info=%s\n",errorCode, error, errorMessage);
      exit(EXIT_FAILURE);
    }

    buffer[actualLength] = 0;
    printf("Error=%s; extra info=%s\n", buffer, errorMessage);

    exit(EXIT_FAILURE);
  }
  ErrorCode& operator=(JsErrorCode errorCode) noexcept (false)
  {
    return (*this)(errorCode, "");
  }
  ErrorCode& operator=(const ErrorCode& errorCode) noexcept (true)
  {
    this->errCode = errorCode.errCode;
    this->withException = errorCode.withException;
    return *this;
  }
};
unsigned retrieveId(JsValueRef value);
static unsigned scriptId ;
static JsRuntimeHandle runtime;
static JsContextRef context;
static JsValueRef globalObject;
static ErrorCode errCode;
static JsValueRef breakpoint;
void debugCallback(JsDiagDebugEvent debugEvent, JsValueRef eventData, void* callbackState)
{
  printf("debugCallback called on %d\n", debugEvent);
  fflush(stdout);
  static bool allBreakDone = false;
  scriptId = retrieveId(eventData);
  if (!allBreakDone)
  {
    errCode = JsDiagRequestAsyncBreak(runtime);
    errCode = JsDiagSetBreakpoint(scriptId, 0, 0, &breakpoint);
    allBreakDone = true;
  }
}
int main()
{
  errCode = JsCreateRuntime(JsRuntimeAttributeNone, nullptr, &runtime);
  errCode = JsCreateContext(runtime, &context);
  errCode = JsSetCurrentContext(context);
  errCode = JsGetGlobalObject(&globalObject);
  errCode = JsDiagStartDebugging(runtime, debugCallback, nullptr);
  const char code[] = R"END(
                      var a = 0;
                      for(var i = 0; i < 10 ; i++)
                        a += i;
                      a++;
                      )END";
  unsigned currentSourceContext = 1;
  JsValueRef fname;
  JsValueRef jsResult;
  errCode = JsCreateString("", 0, &fname);
  JsValueRef scriptSource;
  errCode = JsCreateString(code,strlen(code), &scriptSource);
  errCode = JsRun(scriptSource, currentSourceContext++, fname, JsParseScriptAttributeNone, &jsResult);

  JsValueRef breakpoint;
  errCode = JsDiagSetBreakpoint(scriptId, 0, 0, &breakpoint);

  errCode = JsDiagRequestAsyncBreak(runtime);
  errCode = JsDiagSetStepType(JsDiagStepTypeContinue);

  return EXIT_SUCCESS;
}

[agarwal-sandeep]

@lemmel I don't see a definition of retrieveId in the code above so don't know which scriptId you got.
The scriptId for the source should be 1 and if I use that inside first call to debugCallback (JsDiagDebugEventSourceCompile) the JsDiagSetBreakpoint gets set and also hits after returning from debugCallback.

This is the code I executed

#include "stdafx.h"
#include <cstdio>
#include <cstring>
#include <cstdlib>
#include "ChakraCore.h"
#define EXCEPTION_MAX_LENGTH 255

class ErrorCode
{
    bool withException;
    JsErrorCode errCode;
public:
    explicit ErrorCode(bool withException = true) :withException(withException), errCode(JsNoError) {}
    explicit ErrorCode(JsErrorCode errCode, bool withException = true) :withException(withException)
    {
        (*this) = errCode;
    }
    ErrorCode(const ErrorCode& errorCode)
        :withException(errorCode.withException), errCode(errorCode.errorCode())
    {}
    operator bool() const
    {
        return errCode == JsNoError;
    }
    JsErrorCode errorCode() const { return errCode; }
    ErrorCode& operator()(JsErrorCode errorCode, const char* errorMessage) noexcept (false)
    {
        this->errCode = errorCode;
        if (errorCode == JsNoError)
            return *this;
        char buffer[EXCEPTION_MAX_LENGTH + 1];
        size_t actualLength;
        JsErrorCode error;

        JsValueRef exception;
        if ((error = JsGetAndClearException(&exception)) != JsNoError)
        {
            printf("Error on Error! Original error code=%d, new error code=%d; extra info=%s\n", errorCode, error, errorMessage);
            exit(EXIT_FAILURE);
        }

        JsPropertyIdRef messageName;
        if ((error = JsCreatePropertyId("message", strlen("message"), &messageName)) != JsNoError)
        {
            printf("Error on Error! Original error code=%d, new error code=%d; extra info=%s\n", errorCode, error, errorMessage);
            exit(EXIT_FAILURE);
        }

        JsValueRef messageValue;
        if ((error = JsGetProperty(exception, messageName, &messageValue)) != JsNoError)
        {
            printf("Error on Error! Original error code=%d, new error code=%d; extra info=%s\n", errorCode, error, errorMessage);
            exit(EXIT_FAILURE);
        }
        if ((error = JsCopyString(messageValue, buffer, EXCEPTION_MAX_LENGTH, &actualLength)) != JsNoError)
        {
            printf("Error on Error! Original error code=%d, new error code=%d; extra info=%s\n", errorCode, error, errorMessage);
            exit(EXIT_FAILURE);
        }

        buffer[actualLength] = 0;
        printf("Error=%s; extra info=%s\n", buffer, errorMessage);

        exit(EXIT_FAILURE);
    }
    ErrorCode& operator=(JsErrorCode errorCode) noexcept (false)
    {
        return (*this)(errorCode, "");
    }
    ErrorCode& operator=(const ErrorCode& errorCode) noexcept (true)
    {
        this->errCode = errorCode.errCode;
        this->withException = errorCode.withException;
        return *this;
    }
};
unsigned retrieveId(JsValueRef value);
static unsigned scriptId  = 1;
static JsRuntimeHandle runtime;
static JsContextRef context;
static JsValueRef globalObject;
static ErrorCode errCode;
static JsValueRef breakpoint;
void CHAKRA_CALLBACK debugCallback(JsDiagDebugEvent debugEvent, JsValueRef eventData, void* callbackState)
{
    printf("debugCallback called on %d\n", debugEvent);
    fflush(stdout);
    static bool allBreakDone = false;
    scriptId = 1; // retrieveId(eventData);
    if (!allBreakDone)
    {
        //errCode = JsDiagRequestAsyncBreak(runtime);
        errCode = JsDiagSetBreakpoint(scriptId, 0, 0, &breakpoint);
        allBreakDone = true;
    }
}
int main()
{
    errCode = JsCreateRuntime(JsRuntimeAttributeNone, nullptr, &runtime);
    errCode = JsCreateContext(runtime, &context);
    errCode = JsSetCurrentContext(context);
    errCode = JsGetGlobalObject(&globalObject);
    errCode = JsDiagStartDebugging(runtime, debugCallback, nullptr);
    const char code[] = R"END(
                      var a = 0;
                      for(var i = 0; i < 10 ; i++)
                        a += i;
                      a++;
                      )END";
    unsigned currentSourceContext = 1;
    JsValueRef fname;
    JsValueRef jsResult;
    errCode = JsCreateString("", 0, &fname);
    JsValueRef scriptSource;
    errCode = JsCreateString(code, strlen(code), &scriptSource);
    errCode = JsRun(scriptSource, currentSourceContext++, fname, JsParseScriptAttributeNone, &jsResult);

    /*
    JsValueRef breakpoint;
    errCode = JsDiagSetBreakpoint(1, 0, 0, &breakpoint);

    errCode = JsDiagRequestAsyncBreak(runtime);
    errCode = JsDiagSetStepType(JsDiagStepTypeContinue);*/

    

    return EXIT_SUCCESS;
}

[lemmel]

Hi ! Thanks for the answer.

RetrieveId returned me 1, so no change on this part.
Furthermore you removed the code that I used to demonstrate that there was a problem: the JsErrorDiagNotAtBreak error code was triggered on the line with JsDiagSetStepType (i.e. le last line of the source).
My idea was if a break was performed correctly then I could use a JsDiagSetStepType(JsDiagStepTypeContinue) to continue the code execution.

When I use your code adaptation and uncomment the last line, then I still get the error code. So either there is something I don't understand, or manually setting 1 do not the trick.

[agarwal-sandeep]

Any debugger operation needs to happen before debugCallback returns. So you need to call JsDiagSetStepType inside debugCallback.

If you have below code inside your debugCallback which sets breakpoint on source compile and on breakpoint hit do a step-in (F11) operation. You will get JsDiagDebugEventStepComplete callback.

switch (debugEvent)
    {
    case JsDiagDebugEventSourceCompile:
        if (!allBreakDone)
        {
            errCode = JsDiagSetBreakpoint(scriptId, 0, 0, &breakpoint);
            allBreakDone = true;
        }
        break;
    case JsDiagDebugEventBreakpoint:
        errCode = JsDiagSetStepType(JsDiagStepTypeStepIn);
        break;
    case JsDiagDebugEventStepComplete:
        break;
    default:
        break;
    }

[lemmel]

Any debugger operation needs to happen before debugCallback returns

So what is the use of the JsDiagStepTypeContinue value if whatever is done the script will run until the end of the script ?

Furthermore, if I understand well, when the user clicks (in a debugger application) on the pause button, will I have to block the thread in which ChakraCore is running (through the use of a semaphore-like too and inside the debugCallback) ?

[agarwal-sandeep]

ChakraCore doesn't run a debug loop. It's host responsibility to block the thread in debugCallback and process any interaction from debugger frontend.

JsDiagStepTypeContinue is to signal from debugger (Frontend) to debuggee (host running ChakraCore) to continue.

The normal workflow is to run a separate thread which receives messages from frontend and put them in a queue and then call JsDiagRequestAsyncBreak on main runtime. When runtime breaks (debugCallback invoked, most likely with JsDiagDebugEventAsyncBreak) process all messages from queue and wait for either a continue or step message from frontend. On receiving continue/step terminate the wait and come out of debugCallback.

[lemmel]

I think I'm beginning to understand how it works.

Just to make it clearer:

• When runtime breaks (debugCallback invoked, most likely with JsDiagDebugEventAsyncBreak) process all messages from queue

  ok

• wait for either a continue or step message from frontend

  So I'll block the ChakraCore thread (with somaphore-like mecanism) in the debugCallback function, and when in my GUI (or FrontEnd) thread I want to continue, I will release the ChakraCore thread. And there is no use for a JsDiagStepTypeContinue signal as no matter what the thread will continue until completion or an event.
  Is that it ?

[agarwal-sandeep]

Yes.

FYI - @kfarnung is working on providing a lib debug-companion which will provide a default implementation of this.

[lemmel]

Ok.
Many thanks for yours answers.

And lastly about the work of @kfarnung, I will not use it as I see not difficulty to code one "simple" wrapper, and I use Qt. I will provide a full wrapper of the debugging facilities (with only some of the features; e.g. no TTD) for Qt (in the same way I did provide one for ChakraCore here : Git Pull Request).

[richardzarr]

Working on a debugger for Chakracore... found this post extremely helpful. One issue I'm having is getting the code to step properly. I'm using JsDiagSetStepType() in the callback prior to releasing the thread, but it runs forever (or until it hits the next breakpoint which is working perfectly). Can anyone share some source code on how to properly implement the stepping function?

[kfarnung]

It's been a while since I worked on it, but there's a DevTools Protocol debugger library for ChakraCore. The behavior around stepping is a bit nuanced, here's the spot where I handle it:

https://github.com/microsoft/ChakraCore-Debugger/blob/9d58d20639ac1bc4bbdafa1d885ede0dde93db85/lib/Debugger.ProtocolHandler/Debugger.cpp#L206-L210

I'm a bit rusty here so I'm not seeing anything immediately wrong with the description you provide. Stepping did work properly the last time I was testing, so hopefully the code can help diagnose the issue.

[richardzarr]

Thanks! This is also helpful in that it verifies my structure... which is very similar to yours. Searching through the code I could not find where you execute jsCreateRuntime() - I wanted to see what attribute flags you are using. I'm using these:

JsMyRuntimeAttributes = JsRuntimeAttributeAllowScriptInterrupt + JsRuntimeAttributeEnableIdleProcessing + JsRuntimeAttributeDispatchSetExceptionsToDebugger + JsRuntimeAttributeEnableExperimentalFeatures + JsRuntimeAttributeDispatchSetExceptionsToDebugger;

Breakpoints work great... but stepping never calls back... until it hits another breakpoint.

[kfarnung]

I only pass JsRuntimeAttributeDispatchSetExceptionsToDebugger for my sample: https://github.com/microsoft/ChakraCore-Debugger/blob/9d58d20639ac1bc4bbdafa1d885ede0dde93db85/bin/Debugger.Sample/Debugger.Sample.cpp#L576

A couple of recommendations there, you should be using bitwise OR instead of adding:

JsMyRuntimeAttributes =
    JsRuntimeAttributeAllowScriptInterrupt |
    JsRuntimeAttributeDispatchSetExceptionsToDebugger |
    JsRuntimeAttributeDispatchSetExceptionsToDebugger |
    JsRuntimeAttributeEnableExperimentalFeatures |
    JsRuntimeAttributeEnableIdleProcessing;

It looks like you may have a bug there as well, you're adding the value for JsRuntimeAttributeDispatchSetExceptionsToDebugger twice. That wouldn't matter for a bitwise OR, but will throw things off if you're adding the flags.