microsoft / chakracore-debugger Goto Github PK

View Code? Open in Web Editor NEW

32.0 26.0 27.0 382 KB

Debugging companion library for the ChakraCore JavaScript engine

License: MIT License

C++ 97.22% JavaScript 1.11% Batchfile 0.09% Python 0.16% C 1.42%

chakracore-debugger's Introduction

ChakraCore-Debugger

ChakraCore-Debugger is a C++ companion library which enables the debugging of ChakraCore using the DevTools Protocol.

Features

Enables drop-in support for debugging ChakraCore in host applications
Supports Visual Studio Code and other compatible clients
Exposes a C ABI for use by C99 consumers
Flexibility to replace the transport service code to meet the needs of the host

Status

This project is still in active development, but ready for integration. Future work is tracked in the issue tracker.

Usage

Prerequisites

Windows
Visual Studio 2017
Python 2.7 (For generating the protocol parser only; must be in the PATH)

Building

ChakraCore-Debugger depends on ChakraCore from NuGet. All other dependencies are header-only and included as submodules.

Clone the project (and submodules):

> git clone --recurse-submodules https://github.com/Microsoft/ChakraCore-Debugger

Launch the solution file:

> cd .\ChakraCore-Debugger\
> .\ChakraCore.Debugger.sln

Right-click the "ChakraCore.Debugger.Sample" project and click "Set as StartUp Project".
Choose the desired build configuration and platform (e.g. Debug - x64).
Right-click on the Solution in "Solution Explorer" and click "Restore NuGet Packages".
Set the debugger arguments in the "ChakraCore.Debugger.Sample" project to pass the startup parameters and the name of a script to run (e.g. --inspect-brk --port 9229 test.js).
Hit F5 to start debugging.

Connecting

Connect to the sample application using Visual Studio Code.

Navigate to a working folder and launch Visual Studio Code:

> pushd <working folder>
> code .

Switch to the "Debug (Ctrl+Shift+D)" panel and click the "Configure or Fix 'launch.json'" gear button.
Select the "Node.js" environment.
Add a new configuration:

{
    "type": "node",
    "request": "attach",
    "name": "Attach",
    "port": 9229,
    "protocol": "inspector"
}

Save the "launch.json" file and click the "Start Debugging" play button.
Execution should break on the first line of the script.

Documentation

Design Spec

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Reporting Security Issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at [email protected]. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

Contact Us

If you have any questions, please open an issue and prepend "[Question]" to the title.

chakracore-debugger's People

Contributors

Stargazers

Watchers

chakracore-debugger's Issues

Allow values to be mutated at runtime

This will require new functionality in ChakraCore to light it up.

Need #ifndef before #define WIN32_LEAN_AND_MEAN

#define WIN32_LEAN_AND_MEAN needs #ifndef WIN32_LEAN_AND_MEAN / #endif around it, since it might already be defined.

Documentation (wiki?)

Time Travel Debugging support

The bulk of this work is hooking up the TimeTravel domain to existing ChakraCore functionality.

Cross-platform build support using CMake

Investigating using CMake for all build platforms, including Windows. The one problem is NuGet which is a Windows-only concept.

Enable `console` redirection

This requires some interaction with the host since console is not a standard part of the Global object. We need some way to expose some console functions that pass through to the host-provided functions.

Test cases for the websocket server

These are probably redundant with #12 other than some basic API tests.

WebSocket++ log redirection to file

Test cases for the protocol handler

Some basic C++ test cases to verify the functionality of the protocol handler.

Support connecting with `vscode-chrome-debug`

Currently we connect using the vscode-node-debug2 extension, but it would be good to support the Chrome extension as well.

Implement `DebuggerImpl::continueToLocation`

This can be implemented completely in this library by setting a breakpoint and removing it once it's hit.

Handle UTF-8 messages

Currently the code only supports ASCII for input/output, we need to convert the UTF-8 wire protocol to UTF-16 for further processing.

https://github.com/Microsoft/ChakraCore-Debugger/blob/411521bff3119ce09712e92021bf22252df588a3/lib/Debugger.Protocol/String16.cpp#L124-L144

Calculate the hash for the loaded script source

It's not completely clear what the use-case is here nor whether there is a prescribed hash algorithm that must be used.

Cross-platform sample updates

Need to remove all Windows-only API usage and transition from UTF-16 to UTF-8 internally. This should make it easier to write a common core of code that just has a shell of platform-specific behavior.

Add NuGet package support

The current plan is for the NuGet package to contain the libs and headers, but possibly a DLL as well.

Fixes issue #33.

[question] Can't retarget solution to different Windows SDK version

Hi there,

I'm trying to build this project in VS2017 and am having trouble retargeting it to my Windows SDK version. I followed the build steps issued in the README and then retargeted the solution to 10.0.17134.0 which I have installed locally. The vcxproj file reflects the global setting <WindowsTargetPlatformVersion>10.0.17134.0</WindowsTargetPlatformVersion> for each project, but I nonetheless get this error when trying to build:

The Windows SDK version 10.0.16299.0 was not found. Install the required version of Windows SDK or change the SDK version in the project property pages or by right-clicking the solution and selecting "Retarget solution".

Do you know what might be happening?

Inline breakpoints break at the beginning of the line instead of the specified column

If an inline breakpoint is set on a statement in the middle of the line, the breakpoint breaks at the beginning of the line.

For example, with this statement:

setTImeout(() => console.log("TIMED OUT"), 5000);

If the breakpoint is set on the console.log() statement, column 17, then the breakpoint should break once the console.log() statement is reached.

Instead, it will break when setTimeout() is being called.

It simply seems to ignore the column offset and only use the line, because the breakpoint binds to the beginning of the line.

Implement `ProtocolHelpers::ToProtocolValue`

This code needs to recursively traverse a given JavaScript object and build up an equivalent protocol object.

Investigate support for conditional breakpoints

This can be done completely in this library by adding breakpoints and then on break checking the condition and only breaking if the condition is met.

Breakpoint source location matching with Chrome DevTools

The Chrome DevTools debugger seems to send set-breakpoint-by-URL requests with the file:/// prefix stripped out of the URL. This prevents breakpoints from ever getting set in the engine, because DebuggerBreakpoint::IsScriptMatch() matches on exact URL string. Matching "file:///X" to "X" and vice versa in that routine fixes it.

This repo is missing important files

There are important files that Microsoft projects should all have that are not present in this repository. A pull request has been opened to add the missing file(s). When the pr is merged this issue will be closed automatically.

Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

Merge this pull request

End-to-end test cases

The current plan is to use Node.js as the harness to connect and exercise the code.

Please document how to run unit tests

Need code to compile using C++17

websocketpp does not build with C++17. zaphoyd/websocketpp#669

I made a branch which enables the projects to build using C++17: https://github.com/akrantz/ChakraCore-Debugger/tree/c%2B%2B17

Async callstacks support

This feature is dependent on changes in ChakraCore.

Enable HTTP endpoint for `/json/list` and friends

Details: https://github.com/kfarnung/ChakraCore-Debugger/blob/master/doc/debug-companion.md#http

TODO:

Allow friendly name for the runtime
Implement /json/protocol
Get the ChakraCore version rather than hardcoding it

Multiple runtime support

The existing code already supports separate runtimes hosted by the same websocket server, but the end-to-end flow hasn't been designed or completed.

Publish a new nuget built with v142 (VS 2019)

I just upgraded to Visual Studio 2019.
I still need to use v141 of the platform toolset though since ChakraCore.Debugger.ProtocolHandler.lib was built with v141

Add a trace logger

Build with /W4

Currently the code builds with /W3 cleanly, but there have been requests for /W4. The issue is that two of the dependencies (inspector_protocol and websocketpp) don't build cleanly with /W4.

VS Code breakpoint problems

I'm embedding ChakraCore and ChakraCore-Debug, and I'm running into a weird problem with VS Code. There are some similar issues reported on StackOverflow for VS Code with a Node debuggee, so it might be some generic problem on the VS Code side, but those threads all think that problem is in Node, so maybe there's a parallel bug in CC-D.

Launch a CC/CC-D debuggee from VS Code
Pause in the debugger, anywhere in the Javascript code
Set a breakpoint on a source line that doesn't have executable code
The breakpoint will appear correctly on the next line with executable code
Click on that same no-code line again to clear the breakpoint
** Problem: The breakpoint isn't cleared. VS Code now thinks it has two breakpoints on the nearby code line.
Click a third time on the no-code line to try clearing the breakpoint again
** Problem: The debuggee terminates abruptly

The abrupt termination seems to be coming from the VS Code side - if you look at the debuggee under the native code debugger, it doesn't appear to be crashing with an exception. But something's clearly in a bad state.

Package as a DLL

This was raised as part of #33, but that was closed out without addressing the DLL aspect. It would be nice to have this repackaged as a DLL rather than static .lib's, to allow linking with VC++ configurations that aren't identical.