diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ab83c6c5..a748f4ac6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ Features: Improvements: - Updated debugging documentation to add the LLDB configuration needed for macOS. [PR #3332](https://github.com/microsoft/vscode-cmake-tools/pull/3332) [@slhck](https://github.com/slhck) - In multi-root workspace, the Project Outline View now shows all configured projects. [PR #3270](https://github.com/microsoft/vscode-cmake-tools/pull/3270) [@vlavati](https://github.com/vlavati) +- Added script mode and ability to connect to externally launched CMake processes. [PR #3277](https://github.com/microsoft/vscode-cmake-tools/pull/3277) ## 1.15 Features: diff --git a/docs/README.md b/docs/README.md index d4e306668..970f463ca 100644 --- a/docs/README.md +++ b/docs/README.md @@ -41,6 +41,7 @@ CMake Tools is an extension designed to make it easy to work with CMake-based pr * [Quick debugging](debug-launch.md#quick-debugging) * [Debug using a launch.json file](debug-launch.md#debug-using-a-launchjson-file) * [Run without debugging](debug-launch.md#run-without-debugging) +* [Debugging CMake](debug.md) [Configure CMake Tools settings](cmake-settings.md) * [CMake Tools settings](cmake-settings.md#cmake-settings) diff --git a/docs/debug.md b/docs/debug.md new file mode 100644 index 000000000..1d113c6f0 --- /dev/null +++ b/docs/debug.md @@ -0,0 +1,72 @@ +# CMake Debugging + +Starting with CMake 3.27, debugging CMake is supported in CMake Tools. + +The following documentation will help you understand the various ways you can debug CMake scripts and cache generation. + +## Debugging from CMake Tools UI entry points + +The most common reason to debug CMake scripts and cache generation is to debug CMake cache generation. There are many ways that you can accomplish this: + +* Commands + * CMake: Configure with CMake Debugger + * CMake: Delete Cache and Reconfigure with CMake Debugger +* Folder Explorer + * Right click on CMakeLists.txt -> Configure All Projects with CMake Debugger. +* Project Outline + * Right click on CMakeLists.txt -> Configure All Projects with CMake Debugger. + * Expand the "..." in the project outline. There is an entry to use the Debugger. + +## Debugging from launch.json + +CMake Tools provides a new debug type `cmake`. + +The `cmake` debug type supports three different types of `cmakeDebugType`: `configure`, `external`, `script`. They each come with their own settings that can be used to modify and control the debug session. + +### Example launch.json + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "cmake", + "request": "launch", + "name": "CMake script debugging", + "cmakeDebugType": "script", + "scriptPath": "${workspaceFolder}/