Add script mode and ability to connect to externally launched CMake process.

[gcampbell-msft]

This change addresses item #3248 as well as adding functionality.

This updates the options that are available in launch.json for the cmake debug type.

The following changes are proposed:

• Add required cmakeDebugType to the launch.json that defines whether the user is trying to debug under the three available modes: configure, external, script.
• Add the ability to debug externally launched CMake processes, or to debug a CMake script.
• Adds an activation event when a debug session of type cmake is initiated.
• Remove the check for whether cmakeDebugType is external regarding dapLog. We can simply assign it unconditionally, knowing that it will be ignored in the external mode. In script and configure it will be used as normal.
• Adds the ability to run and debug CMake script files when there is no launch.json present through the "Run and Debug" button.
• Adds initial snippets that help people create launch.json configurations.

The purpose of this change is to add the ability to debug externally launched CMake processes or debug Cmake scripts.

[gcampbell-msft]

NOTE: This should not be merged before we release 1.15.

[Neumann-A]

I got:

with the script stuff.

External debugging worked as expected.

Configure debugging still cannot be stopped if the pipe never connects. This only happens if you trick code to use a different CMake which only reacts like CMake without the debugger; e.g. set "cmake.cmakePath" to a batch file with the following:

@ECHO OFF
SETLOCAL EnableDelayedExpansion

set call_cmake=1
REM Call CMake always except if the debugger should be attached
FOR %%a IN (%*) do (
    set "_arg_=%%a"
    if !_arg_!==--debugger set call_cmake=0
)

@ECHO OFF
if !call_cmake!==1 cmake.exe %* && Exit /B %ERRORLEVEL%

[Neumann-A]

can this get an optional "command" : [] field/array? So that VS code executes the command I would normally use to start the cmake pipe externally?

[gcampbell-msft]

To help me think through the possible design implications, could you go into more detail regarding your use case for the external mode?

What kind of external processes are you expecting? It is a CMake invocation? Or is it invoking something else that internally invokes CMake?
What are you expecting or hoping to use in the "command" field?

Thanks!

[Neumann-A]

It is a CMake invocation? Or is it invoking something else that internally invokes CMake?

Could be both of those.

What are you expecting or hoping to use in the "command" field?

For example I could write a (CMake) script (not the debug target) which does the following:

• FetchContent vcpkg
• bootstrap vcpkg
• vcpkg install (with some additional options to pass on the debugger pipe info)
• vcpkg internally calls cmake -P which could be debugged
• vcpkg internally calls cmake in configure mode which could be debugged

The intention of having a command field is to automate the process. E.g.
"command" : ["cmake", "-P", "my-internal-cmake-caller-script.cmake", "-DDEBUGGER_PIPE_NAME=<name_of_debugger_pipe>"]
DEBUGGER_PIPE_NAME is internally passed on to some process calling cmake. (doesn't really matter what it is)

But if "command" is added "workingDir" probably also makes sense to define where the command is executed.

[Neumann-A]

That being said I am also happy with the current approach. It is just that it takes more manual labor for startup.

[gcampbell-msft]

Understood. I wonder if using a preLaunchTask is what you want. This way the pre launch task can be fully arbitrary. Do you think using that would suit your needs?

[Neumann-A]

Don't know about that. If there is a possibility to detach then probably yes if it needs to return than probably no. Need to read up on that first.

[gcampbell-msft]

I just tested and found that if you set up a tasks.json task with the following settings as part of that task:

"isBackground": true,
        // This task is run before some debug tasks.
        // Problem is, it's a watch script, and since it never exits, VSCode
        // complains. All this is needed so VSCode just lets it run.
        "problemMatcher": [
            {
            "pattern": [
                {
                "regexp": ".",
                "file": 1,
                "location": 2,
                "message": 3
                }
            ],
            "background": {
                "activeOnStart": true,
                "beginsPattern": ".",
                "endsPattern": ".",
            }
            }
        ]

then you can successfully have a preLaunch task.

[Neumann-A]

Hmm I need some delay or some retry count to connect the debugger to the pipe since the debugger wants to start before the prelaunch task reached the point where the pipe is opened. (That being said: Hitting the run button simply twice works as expected; somehow vs code sees that the task is still running and does not rerun it.)

[Neumann-A]

OK I think there is nothing to do here. I can just define a task and let it run via VS Code directly instead of manually typing it. Never used task since I mainly use CMake presets. Would be nice if there is a way to somehow get the pipename from a task.json via some variable.

[gcampbell-msft]

I got: with the script stuff.

External debugging worked as expected.

Configure debugging still cannot be stopped if the pipe never connects. This only happens if you trick code to use a different CMake which only reacts like CMake without the debugger; e.g. set "cmake.cmakePath" to a batch file with the following:

@ECHO OFF
SETLOCAL EnableDelayedExpansion

set call_cmake=1
REM Call CMake always except if the debugger should be attached
FOR %%a IN (%*) do (
    set "_arg_=%%a"
    if !_arg_!==--debugger set call_cmake=0
)

@ECHO OFF
if !call_cmake!==1 cmake.exe %* && Exit /B %ERRORLEVEL%

This may be because I haven't done any handling of variables. To confirm, could you attempt it again by putting either a relative or full path?

UPDATE: Actually, this seems to already be natively handled from launch.json. I realized I wasn't handling a case where scriptEnv was undefined. Could you please try it again?

[Neumann-A]

Could you please try it again?

If you give me a new vsix, then yes. One problem I have is that code always tries to reinstall the current release extension.

[Brian-Ruff-CardinalPeak]

This PR was a timely discovery for me; I need to debug a cmake issue with several subprocess invocations of cmake. Is there an existing mechanism to get .vsix files for this branch? I was able to attach the debugger to the initial cmake process via configure/reconfigure with CMake debugger, but am not yet having success with an external to attach to a subprocess. I pulled the branch and was able to create a .vsix - I haven't done much with VSCode extensions at all.

[Brian-Ruff-CardinalPeak]

One item I noted, it seems like an extension can provide seed/snippets via the Add Configuration UI, though I'm not familiar with the mechanism/API.

[gcampbell-msft]

@benmcmorran @snehara99 This PR is ready for review and testing.

[gcampbell-msft]

@snehara99 @benmcmorran ping for review.

[benmcmorran]

What's the ^ for? Does this act as a regex? If it's not, we can probably hardcode something like <script>.cmake even though it won't exist just to make the example clearer.

[gcampbell-msft]

I don't think so. I copied it from somewhere and it seemed to simply allow us to insert it without resolving the ${workspaceFolder} to an actual value.

When I created an automatic debug configuration using this, this is what appeared:

[gcampbell-msft]

@benmcmorran ping for review.

Specifically, #3277 (comment)

[Neumann-A]

@gcampbell-msft Is this waiting on something?

[gcampbell-msft]

@gcampbell-msft Is this waiting on something?

We are pending another code review. Our team hopes to get on this in the next week or two, thank you for the ping!

[gcampbell-msft]

Merging without tests because they passed prior to the changelog changes, and the changelog doesn't affect tests.
The Windows tests fail due to other changes, they are not due to this PR.