From 07ff4b04a113b1bd9aef17f1edc2d8df8410fa4a Mon Sep 17 00:00:00 2001 From: srfrnk Date: Fri, 9 Oct 2020 07:40:10 +0100 Subject: [PATCH 1/3] Fixes #888 --- .gitignore | 2 +- Configuration.md | 520 ++++++++++++++++++++++++++--------------------- README.md | 1 + package.json | 14 ++ package.nls.json | 6 +- src/build.ts | 10 +- 6 files changed, 314 insertions(+), 239 deletions(-) diff --git a/.gitignore b/.gitignore index 98790543..35a57fb6 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,4 @@ node_modules vscode-java-debug-*.vsix packages/ dist -.DS_Store \ No newline at end of file +.DS_Store diff --git a/Configuration.md b/Configuration.md index 3b298eeb..f6c29466 100644 --- a/Configuration.md +++ b/Configuration.md @@ -1,149 +1,167 @@ # Java Debug Configuration ## Table of Contents -* [Auto generate the launch.json](#auto-generate-the-launchjson) -* [Modify the launch.json](#modify-the-launchjson) - * [Main](#main) - * mainClass - * projectName - * [Arguments](#arguments) - * args - * vmArgs - * [Environment](#environment) - * console - * env - * [Don't step into the specified classes or methods](#dont-step-into-the-specified-classes-or-methods) - * stepFilters - * [Attach to a debuggee](#attach-to-a-debuggee) - * hostName - * port - * [Attach to mvn task](#attach-to-mvn-task) - * [Attach to embedded maven tomcat server](#attach-to-embedded-maven-tomcat-server) - * [Use javac as the builder and attach to java process](#use-javac-as-the-builder-and-attach-to-java-process) -* [Modify the settings.json (User Setting)](#modify-the-settingsjson-user-setting) - * java.debug.settings.console - * java.debug.settings.forceBuildBeforeLaunch - * java.debug.settings.hotCodeReplace - * java.debug.settings.enableRunDebugCodeLens -* [FAQ](#faq) - - -The debugger provides two kinds of configuration: *launch.json* and *settings.json* (User Settings), see the [README](https://github.com/Microsoft/vscode-java-debug#options) for the supported configuration list. launch.json is used to control the configuration per debug session, and the user setting is shared by the whole workspace or VS Code. + +- [Auto generate the launch.json](#auto-generate-the-launchjson) +- [Modify the launch.json](#modify-the-launchjson) + - [Main](#main) + - mainClass + - projectName + - [Arguments](#arguments) + - args + - vmArgs + - [Environment](#environment) + - console + - env + - [Don't step into the specified classes or methods](#dont-step-into-the-specified-classes-or-methods) + - stepFilters + - [Attach to a debuggee](#attach-to-a-debuggee) + - hostName + - port + - [Attach to mvn task](#attach-to-mvn-task) + - [Attach to embedded maven tomcat server](#attach-to-embedded-maven-tomcat-server) + - [Use javac as the builder and attach to java process](#use-javac-as-the-builder-and-attach-to-java-process) +- [Modify the settings.json (User Setting)](#modify-the-settingsjson-user-setting) + - java.debug.settings.console + - java.debug.settings.forceBuildBeforeLaunch + - java.debug.settings.onBuildFailure + - java.debug.settings.hotCodeReplace + - java.debug.settings.enableRunDebugCodeLens +- [FAQ](#faq) + +The debugger provides two kinds of configuration: _launch.json_ and _settings.json_ (User Settings), see the [README](https://github.com/Microsoft/vscode-java-debug#options) for the supported configuration list. launch.json is used to control the configuration per debug session, and the user setting is shared by the whole workspace or VS Code. ## Auto generate the launch.json + When you run the program via `Run|Debug` CodeLens or `Run`/`Debug` context menu, the debugger automatically generates the launching configuration for you. ![runMenu](https://user-images.githubusercontent.com/14052197/67181889-715bb380-f410-11e9-9aef-c27ce697daa0.gif) ## Modify the launch.json + On the other hand, the debugger provides multiple configuration templates to help you to easily add a new configuration. When you type `"java"` or `""` in launch.json, it will trigger auto-completion suggestions. ![launchConfig](https://user-images.githubusercontent.com/14052197/67182212-3908a500-f411-11e9-9467-48ba2f6e0e39.gif) In case you want to manually edit the configuration, below are the explanation and samples about the common debug configurations. + ### Main -* `mainClass` - mainClass is used to define your program entry, and it's the most important configuration. The debugger provides three options to help you configure this key, see the samples below. - * `"mainClass": ""` - If you have no idea about what to set here, just leave it empty. The debugger will search all possible main classes from the workspace, then prompt you the list to choose for launch. -![emptyMainClass](https://user-images.githubusercontent.com/14052197/67261011-25bd0e80-f4d1-11e9-966d-3e82a4e261ce.gif) - * `"mainClass": "${file}"` - If you have multiple main Java files, use this to auto switch to your current focus program. The debugger will resolve the main class from current active Java file, and set it as the launching main class. -![currentFile](https://user-images.githubusercontent.com/14052197/67183367-d7960580-f413-11e9-9773-7df735710054.gif) +- `mainClass` - mainClass is used to define your program entry, and it's the most important configuration. The debugger provides three options to help you configure this key, see the samples below. + + - `"mainClass": ""` + If you have no idea about what to set here, just leave it empty. The debugger will search all possible main classes from the workspace, then prompt you the list to choose for launch. + ![emptyMainClass](https://user-images.githubusercontent.com/14052197/67261011-25bd0e80-f4d1-11e9-966d-3e82a4e261ce.gif) + + - `"mainClass": "${file}"` + If you have multiple main Java files, use this to auto switch to your current focus program. The debugger will resolve the main class from current active Java file, and set it as the launching main class. + ![currentFile](https://user-images.githubusercontent.com/14052197/67183367-d7960580-f413-11e9-9773-7df735710054.gif) + + - `"mainClass": "com.microsoft.app.myApp"` + The fully qualified class name, generally it's filled by the debugger's auto generation. + ![mainClass](https://user-images.githubusercontent.com/14052197/67190742-17181e00-f423-11e9-98ab-1c568f220ba7.gif) - * `"mainClass": "com.microsoft.app.myApp"` - The fully qualified class name, generally it's filled by the debugger's auto generation. -![mainClass](https://user-images.githubusercontent.com/14052197/67190742-17181e00-f423-11e9-98ab-1c568f220ba7.gif) +- `projectName` - The preferred project in which the debugger searches for classes. It's required for the evaluation feature. Most of the time, the debugger will auto generate the configuration for you. In case you want to manually configure it, here are the rules. -* `projectName` - The preferred project in which the debugger searches for classes. It's required for the evaluation feature. Most of the time, the debugger will auto generate the configuration for you. In case you want to manually configure it, here are the rules. - * When you open a maven project, the project name is the `artifactId`. - * When you open a gradle project, the project name is the `baseName` or the root folder name. - * When you open other Java files, leave the launch.json empty and allow the debugger auto generates the project name for you. + - When you open a maven project, the project name is the `artifactId`. + - When you open a gradle project, the project name is the `baseName` or the root folder name. + - When you open other Java files, leave the launch.json empty and allow the debugger auto generates the project name for you. - Pro Tip: The easiest way to get the project name is to install [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) extension, the top node in the JAVA DEPENDENCIES view is your project name. -![java-dependency-viewer](https://user-images.githubusercontent.com/14052197/67185034-7cfea880-f417-11e9-8a3b-a3af1a9e86bb.png) + Pro Tip: The easiest way to get the project name is to install [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) extension, the top node in the JAVA DEPENDENCIES view is your project name. + ![java-dependency-viewer](https://user-images.githubusercontent.com/14052197/67185034-7cfea880-f417-11e9-8a3b-a3af1a9e86bb.png) ### Arguments -* `args` - Program arguments which are used to pass application configuration to your program, and they are accessible via "args" String array parameter in your main method `public static void main(String[] args)`. It accepts three kinds of value, see the samples below. - * `"args": "arg0 arg1"` - Space separated String value. - ![programArgs](https://user-images.githubusercontent.com/14052197/67191536-5abf5780-f424-11e9-9664-6cc5805225bb.gif) - - * `"args": ["arg0", "arg1"]` - An array of String. - * `"args": "${command:SpecifyProgramArgs}"` - The debugger will prompt you with an input box to type the args value before launching the program. This is convenient when you have a program running against multiple data set. - ![specifyArgs](https://user-images.githubusercontent.com/14052197/67191890-0ff20f80-f425-11e9-8df2-5fd98e61c204.gif) - -* `vmArgs` - VM arguments are used to configure JVM options and platform properties. Most of these arguments have a prefix (-D, -X, -XX). For example, *-Xms256m* arguments defines the initial Java heap size to 256MB. And you can also use *-DpropertyName=propertyValue* to configure system properties for your program. These properties are read via API *System.getProperty(propertyName)*. It accepts a String or an array of String, see the samples below. - * `"vmArgs": "-Xms256m -Xmx1g -Dserver=production"` - Space separated String value. - * `"vmArgs": ["-Xms256m", "-Xmx1g", "-Dserver=production"]` - An array of String. + +- `args` - Program arguments which are used to pass application configuration to your program, and they are accessible via "args" String array parameter in your main method `public static void main(String[] args)`. It accepts three kinds of value, see the samples below. + + - `"args": "arg0 arg1"` + Space separated String value. + ![programArgs](https://user-images.githubusercontent.com/14052197/67191536-5abf5780-f424-11e9-9664-6cc5805225bb.gif) + + - `"args": ["arg0", "arg1"]` + An array of String. + - `"args": "${command:SpecifyProgramArgs}"` + The debugger will prompt you with an input box to type the args value before launching the program. This is convenient when you have a program running against multiple data set. + ![specifyArgs](https://user-images.githubusercontent.com/14052197/67191890-0ff20f80-f425-11e9-8df2-5fd98e61c204.gif) + +- `vmArgs` - VM arguments are used to configure JVM options and platform properties. Most of these arguments have a prefix (-D, -X, -XX). For example, _-Xms256m_ arguments defines the initial Java heap size to 256MB. And you can also use _-DpropertyName=propertyValue_ to configure system properties for your program. These properties are read via API _System.getProperty(propertyName)_. It accepts a String or an array of String, see the samples below. + - `"vmArgs": "-Xms256m -Xmx1g -Dserver=production"` + Space separated String value. + - `"vmArgs": ["-Xms256m", "-Xmx1g", "-Dserver=production"]` + An array of String. ### Environment -- `console` - The specified console to launch the current program. Current default value is `integratedTerminal`. You could customize it via the global user setting `java.debug.settings.console` for the whole workspace, or `console` in launch.json for each debug session. The `console` option in launch.json (if provided) takes precedence over `java.debug.settings.console` in user settings. - * `"console": "internalConsole"` - VS Code debug console (input stream not supported). If you're developing backend application, `internalConsole` is recommended. - ![internalConsole](https://user-images.githubusercontent.com/14052197/67193516-fef6cd80-f427-11e9-8a97-9014470c3a4d.gif) - - * `"console": "integratedTerminal"` - VS Code integrated terminal. If you're developing console application with io input requirements, you must use the terminal to accept user input. For example, use *Scanner* class for user input. - ![integratedTerminal](https://user-images.githubusercontent.com/14052197/67195762-251e6c80-f42c-11e9-89d0-9545560beea9.gif) - - * `"console": "externalTerminal"` - External terminal that can be configured in user settings. The user scenario is same as integrated terminal. The difference is opening an external terminal window to run your program. - ![externalTerminal](https://user-images.githubusercontent.com/14052197/67196194-eccb5e00-f42c-11e9-9d4c-6baa5eec18bc.gif) - -- `env` - The extra environment variables for the program. It's accessible via `System.getenv(key)`. It accepts key-value pairs. - ```json - "env": { - "HOST": "127.0.0.1", - "PORT": 8080 - } - ``` -### Don't step into the specified classes or methods +- `console` - The specified console to launch the current program. Current default value is `integratedTerminal`. You could customize it via the global user setting `java.debug.settings.console` for the whole workspace, or `console` in launch.json for each debug session. The `console` option in launch.json (if provided) takes precedence over `java.debug.settings.console` in user settings. -- `stepFilters` - Skip the specified classes or methods you don't want to step into. Class names should be fully qualified. Wildcard is supported. - - Skip the class loader. - ```json - "stepFilters": { - "classNameFilters": [ - "java.lang.ClassLoader", - ] - } - ``` - ![skipClassLoader](https://user-images.githubusercontent.com/14052197/67254877-ff3bab00-f4b1-11e9-8da0-22b49935bd57.gif) + - `"console": "internalConsole"` + VS Code debug console (input stream not supported). If you're developing backend application, `internalConsole` is recommended. + ![internalConsole](https://user-images.githubusercontent.com/14052197/67193516-fef6cd80-f427-11e9-8a97-9014470c3a4d.gif) - - Skip the JDK classes. - ```json - "stepFilters": { - "classNameFilters": [ - "java.*", - "javax.*", - "com.sun.*", - "sun.*", - "sunw.*", - "org.omg.*" - ] - } - ``` - ![skipJDK](https://user-images.githubusercontent.com/14052197/67255028-9dc80c00-f4b2-11e9-9113-bef0c0bdf5cb.gif) + - `"console": "integratedTerminal"` + VS Code integrated terminal. If you're developing console application with io input requirements, you must use the terminal to accept user input. For example, use _Scanner_ class for user input. + ![integratedTerminal](https://user-images.githubusercontent.com/14052197/67195762-251e6c80-f42c-11e9-89d0-9545560beea9.gif) + + - `"console": "externalTerminal"` + External terminal that can be configured in user settings. The user scenario is same as integrated terminal. The difference is opening an external terminal window to run your program. + ![externalTerminal](https://user-images.githubusercontent.com/14052197/67196194-eccb5e00-f42c-11e9-9d4c-6baa5eec18bc.gif) - - Skip the constructors and the synthetic methods. +- `env` - The extra environment variables for the program. It's accessible via `System.getenv(key)`. It accepts key-value pairs. ```json - "stepFilters": { - "skipSynthetics": true, - "skipStaticInitializers": true, - "skipConstructors": true - } + "env": { + "HOST": "127.0.0.1", + "PORT": 8080 + } ``` - ![skipMethods](https://user-images.githubusercontent.com/14052197/67255209-83daf900-f4b3-11e9-8533-70f6ff941e8d.gif) + +### Don't step into the specified classes or methods + +- `stepFilters` - Skip the specified classes or methods you don't want to step into. Class names should be fully qualified. Wildcard is supported. + + - Skip the class loader. + + ```json + "stepFilters": { + "classNameFilters": [ + "java.lang.ClassLoader", + ] + } + ``` + + ![skipClassLoader](https://user-images.githubusercontent.com/14052197/67254877-ff3bab00-f4b1-11e9-8da0-22b49935bd57.gif) + + - Skip the JDK classes. + + ```json + "stepFilters": { + "classNameFilters": [ + "java.*", + "javax.*", + "com.sun.*", + "sun.*", + "sunw.*", + "org.omg.*" + ] + } + ``` + + ![skipJDK](https://user-images.githubusercontent.com/14052197/67255028-9dc80c00-f4b2-11e9-9113-bef0c0bdf5cb.gif) + + - Skip the constructors and the synthetic methods. + ```json + "stepFilters": { + "skipSynthetics": true, + "skipStaticInitializers": true, + "skipConstructors": true + } + ``` + ![skipMethods](https://user-images.githubusercontent.com/14052197/67255209-83daf900-f4b3-11e9-8533-70f6ff941e8d.gif) ### Attach to a debuggee -- `hostName` - The host name or ip address of the debuggee you want to attach. -- `port` - The port of the debuggee you want to attach. -Before attaching to a debuggee, your debuggee program must be started with debug mode. The standard command line for debug mode is like `java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 -cp bin MyApp`, and then the debug port of your debuggee is *5005*. +- `hostName` - The host name or ip address of the debuggee you want to attach. +- `port` - The port of the debuggee you want to attach. + +Before attaching to a debuggee, your debuggee program must be started with debug mode. The standard command line for debug mode is like `java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 -cp bin MyApp`, and then the debug port of your debuggee is _5005_. + ```json { "type": "java", @@ -155,30 +173,36 @@ Before attaching to a debuggee, your debuggee program must be started with debug ``` In some cases, you may want to start your program with the external builder and launcher, then you can configure these jobs in [tasks.json](https://code.visualstudio.com/docs/editor/tasks) and attach to it. For example, launching springboot application via mvn command, and then attach a debugger. + #### Attach to mvn task -1) Configure your command in .vscode/tasks.json - The mvn task is a background task, you should use *problemMatcher* filter to tell VS Code it's ready. - ```json + +1. Configure your command in .vscode/tasks.json - The mvn task is a background task, you should use _problemMatcher_ filter to tell VS Code it's ready. + ```json { "label": "mvnDebug", "type": "shell", "command": "mvn spring-boot:run -Dspring-boot.run.jvmArguments=\"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005\"", "isBackground": true, - "problemMatcher": [{ - "pattern": [{ - "regexp": "\\b\\B", - "file": 1, - "location": 2, - "message": 3 - }], - "background": { - "activeOnStart": true, - "beginsPattern": "^.*Attaching agents:.*", - "endsPattern": "^.*Listening for transport dt_socket at address.*" + "problemMatcher": [ + { + "pattern": [ + { + "regexp": "\\b\\B", + "file": 1, + "location": 2, + "message": 3 + } + ], + "background": { + "activeOnStart": true, + "beginsPattern": "^.*Attaching agents:.*", + "endsPattern": "^.*Listening for transport dt_socket at address.*" + } } - }] + ] } ``` -2) Configure `preLaunchTask` and the debug port in .vscode/launch.json. +2. Configure `preLaunchTask` and the debug port in .vscode/launch.json. ```json { "type": "java", @@ -189,89 +213,102 @@ In some cases, you may want to start your program with the external builder and "preLaunchTask": "mvnDebug" } ``` -3) F5 will launch the mvn task, and attach the debugger. See the demo. -![attachToMvn](https://user-images.githubusercontent.com/14052197/67262705-4f2d6880-f4d8-11e9-9e2d-9c35a6613c08.gif) +3. F5 will launch the mvn task, and attach the debugger. See the demo. + ![attachToMvn](https://user-images.githubusercontent.com/14052197/67262705-4f2d6880-f4d8-11e9-9e2d-9c35a6613c08.gif) #### Attach to embedded maven tomcat server - - pom.xml sample for embedded tomcat server. - ```xml - ... - - org.apache.tomcat.maven - tomcat7-maven-plugin - 2.2 - - ... - ``` - - The steps to attach to the embedded maven tomcat server. - 1) Use .vscode/tasks.json to configure *run-tomcat* and *stop-tomcat* tasks. - ```json - { - "version": "2.0.0", - "tasks": [ - { - "label": "run-tomcat", - "type": "shell", - "command": "MAVEN_OPTS=\"$MAVEN_OPTS -agentlib:jdwp=transport=dt_socket,address=5005,server=y,suspend=n\" ./mvnw tomcat7:run", - "group": "build", - "isBackground": true, - "problemMatcher": [{ - "pattern": [{ - "regexp": "\\b\\B", - "file": 1, - "location": 2, - "message": 3 - }], + +- pom.xml sample for embedded tomcat server. + +```xml + ... + + org.apache.tomcat.maven + tomcat7-maven-plugin + 2.2 + + ... +``` + +- The steps to attach to the embedded maven tomcat server. + +1. Use .vscode/tasks.json to configure _run-tomcat_ and _stop-tomcat_ tasks. + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "run-tomcat", + "type": "shell", + "command": "MAVEN_OPTS=\"$MAVEN_OPTS -agentlib:jdwp=transport=dt_socket,address=5005,server=y,suspend=n\" ./mvnw tomcat7:run", + "group": "build", + "isBackground": true, + "problemMatcher": [ + { + "pattern": [ + { + "regexp": "\\b\\B", + "file": 1, + "location": 2, + "message": 3 + } + ], "background": { "activeOnStart": true, "beginsPattern": "^.*Listening for", "endsPattern": "^.*transport dt_socket at address.*" } - }] - }, - { - "label": "stop-tomcat", - "type": "shell", - "command": "echo ${input:terminate}}", - "problemMatcher": [] - } - ], - "inputs": [ - { - "id": "terminate", - "type": "command", - "command": "workbench.action.tasks.terminate", - "args": "run-tomcat" - } - ] - } - ``` - 2) Use .vscode/launch.json to configure the attach configuration. Use `preLaunchTask` to run tomcat before the attach, and `postDebugTask` to stop tomcat after the debug ends. - ```json - { - "version": "0.2.0", - "configurations": [ - { - "type": "java", - "name": "Debug (Attach)", - "request": "attach", - "hostName": "localhost", - "port": 5005, - "preLaunchTask": "run-tomcat", - "postDebugTask": "stop-tomcat" - } - ] - } - ``` - 3) F5 will auto start the tomcat server and attach the debugger. The demo below will show how to debug spring mvc in tomcat. - ![attachToEmbeddedTomcat](https://user-images.githubusercontent.com/14052197/67541153-80957680-f71a-11e9-9d59-e9aaa752fe33.gif) + } + ] + }, + { + "label": "stop-tomcat", + "type": "shell", + "command": "echo ${input:terminate}}", + "problemMatcher": [] + } + ], + "inputs": [ + { + "id": "terminate", + "type": "command", + "command": "workbench.action.tasks.terminate", + "args": "run-tomcat" + } + ] +} +``` + +2. Use .vscode/launch.json to configure the attach configuration. Use `preLaunchTask` to run tomcat before the attach, and `postDebugTask` to stop tomcat after the debug ends. + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "java", + "name": "Debug (Attach)", + "request": "attach", + "hostName": "localhost", + "port": 5005, + "preLaunchTask": "run-tomcat", + "postDebugTask": "stop-tomcat" + } + ] +} +``` - > If you want to try to debug your Java webapps in a standalone tomcat server, please try VS Code [Tomcat for Java](https://marketplace.visualstudio.com/items?itemName=adashen.vscode-tomcat) extension. +3. F5 will auto start the tomcat server and attach the debugger. The demo below will show how to debug spring mvc in tomcat. + ![attachToEmbeddedTomcat](https://user-images.githubusercontent.com/14052197/67541153-80957680-f71a-11e9-9d59-e9aaa752fe33.gif) - > If you want to try to debug embedded tomcat server with gradle plugin, see the [gradle sample](https://github.com/microsoft/vscode-java-debug/issues/140#issuecomment-343656398). +> If you want to try to debug your Java webapps in a standalone tomcat server, please try VS Code [Tomcat for Java](https://marketplace.visualstudio.com/items?itemName=adashen.vscode-tomcat) extension. + +> If you want to try to debug embedded tomcat server with gradle plugin, see the [gradle sample](https://github.com/microsoft/vscode-java-debug/issues/140#issuecomment-343656398). #### Use javac as the builder and attach to java process -1) Configure the javac builder and java runner jobs in .vscode/tasks.json. + +1. Configure the javac builder and java runner jobs in .vscode/tasks.json. ```json { "version": "2.0.0", @@ -287,24 +324,28 @@ In some cases, you may want to start your program with the external builder and "type": "shell", "command": "java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 -cp bin app.SimpleCalc", "isBackground": true, - "problemMatcher": [{ - "pattern": [{ - "regexp": "\\b\\B", - "file": 1, - "location": 2, - "message": 3 - }], - "background": { - "activeOnStart": true, - "beginsPattern": "^.*Listening for", - "endsPattern": "^.*transport dt_socket at address.*" + "problemMatcher": [ + { + "pattern": [ + { + "regexp": "\\b\\B", + "file": 1, + "location": 2, + "message": 3 + } + ], + "background": { + "activeOnStart": true, + "beginsPattern": "^.*Listening for", + "endsPattern": "^.*transport dt_socket at address.*" + } } - }] + ] } ] } ``` -2) Configure `preLaunchTask` and the debug port in .vscode/launch.json. +2. Configure `preLaunchTask` and the debug port in .vscode/launch.json. ```json { "version": "0.2.0", @@ -320,36 +361,45 @@ In some cases, you may want to start your program with the external builder and ] } ``` -3) F5 will run the tasks and attach the debugger. See the demo. -![attachToJava](https://user-images.githubusercontent.com/14052197/67263956-3cb52e00-f4dc-11e9-9c78-6e66cb3d7c2b.gif) +3. F5 will run the tasks and attach the debugger. See the demo. + ![attachToJava](https://user-images.githubusercontent.com/14052197/67263956-3cb52e00-f4dc-11e9-9c78-6e66cb3d7c2b.gif) ## Modify the settings.json (User Setting) -- `java.debug.settings.console` - The specified console to launch Java program, defaults to `integratedTerminal`. If you want to customize the console for a specific debug session, please use `console` option in launch.json instead. - ![terminal](https://user-images.githubusercontent.com/14052197/67256063-cf8fa180-f4b7-11e9-9455-77daad2f0ec9.gif) -- `java.debug.settings.forceBuildBeforeLaunch` - Force building the workspace before launching java program, defaults to `true`. Sometimes you may be bothered with the message *"Build failed, do you want to continue?"*, you could disable this setting to suppress the message. +- `java.debug.settings.console` - The specified console to launch Java program, defaults to `integratedTerminal`. If you want to customize the console for a specific debug session, please use `console` option in launch.json instead. + ![terminal](https://user-images.githubusercontent.com/14052197/67256063-cf8fa180-f4b7-11e9-9455-77daad2f0ec9.gif) + +- `java.debug.settings.forceBuildBeforeLaunch` - Force building the workspace before launching java program, defaults to `true`. Sometimes you may be bothered with the message _"Build failed, do you want to continue?"_, you could disable this setting to suppress the message. + +- `java.debug.settings.onBuildFailure` - Sometimes you may be bothered with the message _"Build failed, do you want to continue?"_, you could use this setting to suppress the message with a specific selection. -- `java.debug.settings.hotCodeReplace` - Reload the changed Java classes during debugging, defaults to `manual`. It supports `manual`, `auto`, `never`. - - `manual` - Click the toolbar to apply the changes. - ![hcr](https://user-images.githubusercontent.com/14052197/67256313-f5697600-f4b8-11e9-9db6-54540b6350ad.png) - - `auto` - Automatically apply the changes after saved. - - `never` - Never apply the changes. +- `java.debug.settings.hotCodeReplace` - Reload the changed Java classes during debugging, defaults to `manual`. It supports `manual`, `auto`, `never`. -- `java.debug.settings.enableRunDebugCodeLens` - Enable the code lens provider for the *Run* and *Debug* buttons over main entry points, defaults to `true`. - - `true` - Show the code lens. - ![codelens](https://user-images.githubusercontent.com/14052197/67256585-83922c00-f4ba-11e9-883f-2b3de3db2dfa.png) - - `false` - Show the Run/Debug link in the hover. - ![hover](https://user-images.githubusercontent.com/14052197/67256539-2ac29380-f4ba-11e9-8a5b-e5e1d0a27f0e.png) + - `manual` - Click the toolbar to apply the changes. + ![hcr](https://user-images.githubusercontent.com/14052197/67256313-f5697600-f4b8-11e9-9db6-54540b6350ad.png) + - `auto` - Automatically apply the changes after saved. + - `never` - Never apply the changes. + +- `java.debug.settings.enableRunDebugCodeLens` - Enable the code lens provider for the _Run_ and _Debug_ buttons over main entry points, defaults to `true`. + - `true` - Show the code lens. + ![codelens](https://user-images.githubusercontent.com/14052197/67256585-83922c00-f4ba-11e9-883f-2b3de3db2dfa.png) + - `false` - Show the Run/Debug link in the hover. + ![hover](https://user-images.githubusercontent.com/14052197/67256539-2ac29380-f4ba-11e9-8a5b-e5e1d0a27f0e.png) ## FAQ -### 1. No way to take input. -If you are using *Scanner(System.in)* to get the user input, you need change the user setting `java.debug.settings.console` to `integratedTerminal` or `externalTerminal`. -### 2. Code output is not in the DEBUG CONSOLE panel but Terminal. +### 1. No way to take input. + +If you are using _Scanner(System.in)_ to get the user input, you need change the user setting `java.debug.settings.console` to `integratedTerminal` or `externalTerminal`. + +### 2. Code output is not in the DEBUG CONSOLE panel but Terminal. + By default, the debugger uses the terminal to launch your program for better accepting user input. And you will see the original command line is displayed at the top of the terminal. If you want a cleaner console to show your code output, you could try to change the user setting `java.debug.settings.console` to `internalConsole`. Please notice that the internal console (VS Code built-in DEBUG CONSOLE) doesn't support user input. ### 3. The classpath changed when using terminal. -In order to avoid the command line being too long, the debugger will shorten your classpath into classpath.jar (for JDK 8 only) or argsfile (for JDK 9 and above) by default. If your program need read the original classpath value (for example, *System.getProperty("java.class.path")*), you could try to change the console to `internalConsole`, or use a higher JDK (9 and above) to launch your program. -### 4. Failed to launch debuggee in terminal with TransportTimeoutException. +In order to avoid the command line being too long, the debugger will shorten your classpath into classpath.jar (for JDK 8 only) or argsfile (for JDK 9 and above) by default. If your program need read the original classpath value (for example, _System.getProperty("java.class.path")_), you could try to change the console to `internalConsole`, or use a higher JDK (9 and above) to launch your program. + +### 4. Failed to launch debuggee in terminal with TransportTimeoutException. + When launching failed in terminal, then you could try to change the user setting `java.debug.settings.console` to `internalConsole`. diff --git a/README.md b/README.md index b3dc0e59..bac22b98 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,7 @@ Please also check the documentation of [Language Support for Java by Red Hat](ht - never - Never apply the changes. - `java.debug.settings.enableRunDebugCodeLens`: enable the code lens provider for the run and debug buttons over main entry points, defaults to `true`. - `java.debug.settings.forceBuildBeforeLaunch`: force building the workspace before launching java program, defaults to `true`. +- `java.debug.settings.onBuildFailure`: Select option to use when build fails, defaults to none (will prompt for selection). - `java.debug.settings.console`: The specified console to launch Java program, defaults to `integratedTerminal`. If you want to customize the console for a specific debug session, please modify the 'console' config in launch.json. - `internalConsole` - VS Code debug console (input stream not supported). - `integratedTerminal` - VS Code integrated terminal. diff --git a/package.json b/package.json index 3dc7b114..a3febaea 100644 --- a/package.json +++ b/package.json @@ -636,6 +636,20 @@ "description": "%java.debugger.configuration.forceBuildBeforeLaunch%", "default": true }, + "java.debug.settings.onBuildFailure": { + "type": "string", + "enum": [ + "Proceed", + "Fix...", + "Cancel" + ], + "enumDescriptions": [ + "%java.debugger.configuration.onBuildFailureProceed%", + "%java.debugger.configuration.onBuildFailureFix%", + "%java.debugger.configuration.onBuildFailureCancel%" + ], + "description": "%java.debugger.configuration.onBuildFailure%" + }, "java.debug.settings.console": { "type": "string", "enum": [ diff --git a/package.nls.json b/package.nls.json index 4cb26773..e1dc4da5 100644 --- a/package.nls.json +++ b/package.nls.json @@ -53,8 +53,12 @@ "java.debugger.configuration.hotCodeReplace.description": "Reload the changed Java classes during debugging. Make sure 'java.autobuild.enabled' is not disabled.", "java.debugger.configuration.enableRunDebugCodeLens.description": "Enable the run and debug code lens providers over main methods.", "java.debugger.configuration.forceBuildBeforeLaunch": "Force building the workspace before launching java program.", + "java.debugger.configuration.onBuildFailure": "Select option to use when build fails", + "java.debugger.configuration.onBuildFailureProceed": "Proceed with debugging", + "java.debugger.configuration.onBuildFailureFix": "Open fix menu", + "java.debugger.configuration.onBuildFailureCancel": "Cancel debugging", "java.debugger.configuration.console": "The specified console to launch Java program. If you want to customize the console for a specific debug session, please modify the 'console' config in launch.json.", "java.debugger.configuration.exceptionBreakpoint.skipClasses": "Skip the specified classes when breaking on exception. You could use the built-in variables such as '$JDK' and '$Libraries' to skip a group of classes, or add a specific class name expression, e.g. java.*, *.Foo", "java.debugger.configuration.jdwp.limitOfVariablesPerJdwpRequest.description": "The maximum number of variables or fields that can be requested in one JDWP request. The higher the value, the less frequently debuggee will be requested when expanding the variable view. Also a large number can cause JDWP request timeout.", "java.debugger.configuration.jdwp.requestTimeout.description": "The timeout (ms) of JDWP request when the debugger communicates with the target JVM." -} +} \ No newline at end of file diff --git a/src/build.ts b/src/build.ts index 1eb1e2bb..9713c809 100644 --- a/src/build.ts +++ b/src/build.ts @@ -9,6 +9,9 @@ import * as commands from "./commands"; import * as lsPlugin from "./languageServerPlugin"; import * as utility from "./utility"; +const JAVA_DEBUG_CONFIGURATION = "java.debug.settings"; +const ON_BUILD_FAILURE = "onBuildFailure"; + export async function buildWorkspace(): Promise { const buildResult = await instrumentOperation("build", async (operationId: string) => { let error; @@ -32,6 +35,9 @@ export async function buildWorkspace(): Promise { } async function handleBuildFailure(operationId: string, err: any): Promise { + const configuration = vscode.workspace.getConfiguration(JAVA_DEBUG_CONFIGURATION); + const onBuildFailure = configuration.get(ON_BUILD_FAILURE); + if (err instanceof utility.JavaExtensionNotEnabledError) { utility.guideToInstallJavaExtension(); return false; @@ -47,8 +53,8 @@ async function handleBuildFailure(operationId: string, err: any): Promise Date: Sat, 10 Oct 2020 08:54:32 +0100 Subject: [PATCH 2/3] PR fixes - changed to boolean --- Configuration.md | 515 +++++++++++++++++++++-------------------------- README.md | 2 +- package.json | 19 +- package.nls.json | 5 +- src/build.ts | 8 +- 5 files changed, 245 insertions(+), 304 deletions(-) diff --git a/Configuration.md b/Configuration.md index f6c29466..250700db 100644 --- a/Configuration.md +++ b/Configuration.md @@ -1,167 +1,150 @@ # Java Debug Configuration ## Table of Contents - -- [Auto generate the launch.json](#auto-generate-the-launchjson) -- [Modify the launch.json](#modify-the-launchjson) - - [Main](#main) - - mainClass - - projectName - - [Arguments](#arguments) - - args - - vmArgs - - [Environment](#environment) - - console - - env - - [Don't step into the specified classes or methods](#dont-step-into-the-specified-classes-or-methods) - - stepFilters - - [Attach to a debuggee](#attach-to-a-debuggee) - - hostName - - port - - [Attach to mvn task](#attach-to-mvn-task) - - [Attach to embedded maven tomcat server](#attach-to-embedded-maven-tomcat-server) - - [Use javac as the builder and attach to java process](#use-javac-as-the-builder-and-attach-to-java-process) -- [Modify the settings.json (User Setting)](#modify-the-settingsjson-user-setting) - - java.debug.settings.console - - java.debug.settings.forceBuildBeforeLaunch - - java.debug.settings.onBuildFailure - - java.debug.settings.hotCodeReplace - - java.debug.settings.enableRunDebugCodeLens -- [FAQ](#faq) - -The debugger provides two kinds of configuration: _launch.json_ and _settings.json_ (User Settings), see the [README](https://github.com/Microsoft/vscode-java-debug#options) for the supported configuration list. launch.json is used to control the configuration per debug session, and the user setting is shared by the whole workspace or VS Code. +* [Auto generate the launch.json](#auto-generate-the-launchjson) +* [Modify the launch.json](#modify-the-launchjson) + * [Main](#main) + * mainClass + * projectName + * [Arguments](#arguments) + * args + * vmArgs + * [Environment](#environment) + * console + * env + * [Don't step into the specified classes or methods](#dont-step-into-the-specified-classes-or-methods) + * stepFilters + * [Attach to a debuggee](#attach-to-a-debuggee) + * hostName + * port + * [Attach to mvn task](#attach-to-mvn-task) + * [Attach to embedded maven tomcat server](#attach-to-embedded-maven-tomcat-server) + * [Use javac as the builder and attach to java process](#use-javac-as-the-builder-and-attach-to-java-process) +* [Modify the settings.json (User Setting)](#modify-the-settingsjson-user-setting) + * java.debug.settings.console + * java.debug.settings.forceBuildBeforeLaunch + * java.debug.settings.hotCodeReplace + * java.debug.settings.onBuildFailureProceed + * java.debug.settings.enableRunDebugCodeLens +* [FAQ](#faq) + + +The debugger provides two kinds of configuration: *launch.json* and *settings.json* (User Settings), see the [README](https://github.com/Microsoft/vscode-java-debug#options) for the supported configuration list. launch.json is used to control the configuration per debug session, and the user setting is shared by the whole workspace or VS Code. ## Auto generate the launch.json - When you run the program via `Run|Debug` CodeLens or `Run`/`Debug` context menu, the debugger automatically generates the launching configuration for you. ![runMenu](https://user-images.githubusercontent.com/14052197/67181889-715bb380-f410-11e9-9aef-c27ce697daa0.gif) ## Modify the launch.json - On the other hand, the debugger provides multiple configuration templates to help you to easily add a new configuration. When you type `"java"` or `""` in launch.json, it will trigger auto-completion suggestions. ![launchConfig](https://user-images.githubusercontent.com/14052197/67182212-3908a500-f411-11e9-9467-48ba2f6e0e39.gif) In case you want to manually edit the configuration, below are the explanation and samples about the common debug configurations. - ### Main +* `mainClass` - mainClass is used to define your program entry, and it's the most important configuration. The debugger provides three options to help you configure this key, see the samples below. + * `"mainClass": ""` + If you have no idea about what to set here, just leave it empty. The debugger will search all possible main classes from the workspace, then prompt you the list to choose for launch. +![emptyMainClass](https://user-images.githubusercontent.com/14052197/67261011-25bd0e80-f4d1-11e9-966d-3e82a4e261ce.gif) -- `mainClass` - mainClass is used to define your program entry, and it's the most important configuration. The debugger provides three options to help you configure this key, see the samples below. - - - `"mainClass": ""` - If you have no idea about what to set here, just leave it empty. The debugger will search all possible main classes from the workspace, then prompt you the list to choose for launch. - ![emptyMainClass](https://user-images.githubusercontent.com/14052197/67261011-25bd0e80-f4d1-11e9-966d-3e82a4e261ce.gif) - - - `"mainClass": "${file}"` - If you have multiple main Java files, use this to auto switch to your current focus program. The debugger will resolve the main class from current active Java file, and set it as the launching main class. - ![currentFile](https://user-images.githubusercontent.com/14052197/67183367-d7960580-f413-11e9-9773-7df735710054.gif) - - - `"mainClass": "com.microsoft.app.myApp"` - The fully qualified class name, generally it's filled by the debugger's auto generation. - ![mainClass](https://user-images.githubusercontent.com/14052197/67190742-17181e00-f423-11e9-98ab-1c568f220ba7.gif) + * `"mainClass": "${file}"` + If you have multiple main Java files, use this to auto switch to your current focus program. The debugger will resolve the main class from current active Java file, and set it as the launching main class. +![currentFile](https://user-images.githubusercontent.com/14052197/67183367-d7960580-f413-11e9-9773-7df735710054.gif) -- `projectName` - The preferred project in which the debugger searches for classes. It's required for the evaluation feature. Most of the time, the debugger will auto generate the configuration for you. In case you want to manually configure it, here are the rules. + * `"mainClass": "com.microsoft.app.myApp"` + The fully qualified class name, generally it's filled by the debugger's auto generation. +![mainClass](https://user-images.githubusercontent.com/14052197/67190742-17181e00-f423-11e9-98ab-1c568f220ba7.gif) - - When you open a maven project, the project name is the `artifactId`. - - When you open a gradle project, the project name is the `baseName` or the root folder name. - - When you open other Java files, leave the launch.json empty and allow the debugger auto generates the project name for you. +* `projectName` - The preferred project in which the debugger searches for classes. It's required for the evaluation feature. Most of the time, the debugger will auto generate the configuration for you. In case you want to manually configure it, here are the rules. + * When you open a maven project, the project name is the `artifactId`. + * When you open a gradle project, the project name is the `baseName` or the root folder name. + * When you open other Java files, leave the launch.json empty and allow the debugger auto generates the project name for you. - Pro Tip: The easiest way to get the project name is to install [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) extension, the top node in the JAVA DEPENDENCIES view is your project name. - ![java-dependency-viewer](https://user-images.githubusercontent.com/14052197/67185034-7cfea880-f417-11e9-8a3b-a3af1a9e86bb.png) + Pro Tip: The easiest way to get the project name is to install [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) extension, the top node in the JAVA DEPENDENCIES view is your project name. +![java-dependency-viewer](https://user-images.githubusercontent.com/14052197/67185034-7cfea880-f417-11e9-8a3b-a3af1a9e86bb.png) ### Arguments - -- `args` - Program arguments which are used to pass application configuration to your program, and they are accessible via "args" String array parameter in your main method `public static void main(String[] args)`. It accepts three kinds of value, see the samples below. - - - `"args": "arg0 arg1"` - Space separated String value. - ![programArgs](https://user-images.githubusercontent.com/14052197/67191536-5abf5780-f424-11e9-9664-6cc5805225bb.gif) - - - `"args": ["arg0", "arg1"]` - An array of String. - - `"args": "${command:SpecifyProgramArgs}"` - The debugger will prompt you with an input box to type the args value before launching the program. This is convenient when you have a program running against multiple data set. - ![specifyArgs](https://user-images.githubusercontent.com/14052197/67191890-0ff20f80-f425-11e9-8df2-5fd98e61c204.gif) - -- `vmArgs` - VM arguments are used to configure JVM options and platform properties. Most of these arguments have a prefix (-D, -X, -XX). For example, _-Xms256m_ arguments defines the initial Java heap size to 256MB. And you can also use _-DpropertyName=propertyValue_ to configure system properties for your program. These properties are read via API _System.getProperty(propertyName)_. It accepts a String or an array of String, see the samples below. - - `"vmArgs": "-Xms256m -Xmx1g -Dserver=production"` - Space separated String value. - - `"vmArgs": ["-Xms256m", "-Xmx1g", "-Dserver=production"]` - An array of String. +* `args` - Program arguments which are used to pass application configuration to your program, and they are accessible via "args" String array parameter in your main method `public static void main(String[] args)`. It accepts three kinds of value, see the samples below. + * `"args": "arg0 arg1"` + Space separated String value. + ![programArgs](https://user-images.githubusercontent.com/14052197/67191536-5abf5780-f424-11e9-9664-6cc5805225bb.gif) + + * `"args": ["arg0", "arg1"]` + An array of String. + * `"args": "${command:SpecifyProgramArgs}"` + The debugger will prompt you with an input box to type the args value before launching the program. This is convenient when you have a program running against multiple data set. + ![specifyArgs](https://user-images.githubusercontent.com/14052197/67191890-0ff20f80-f425-11e9-8df2-5fd98e61c204.gif) + +* `vmArgs` - VM arguments are used to configure JVM options and platform properties. Most of these arguments have a prefix (-D, -X, -XX). For example, *-Xms256m* arguments defines the initial Java heap size to 256MB. And you can also use *-DpropertyName=propertyValue* to configure system properties for your program. These properties are read via API *System.getProperty(propertyName)*. It accepts a String or an array of String, see the samples below. + * `"vmArgs": "-Xms256m -Xmx1g -Dserver=production"` + Space separated String value. + * `"vmArgs": ["-Xms256m", "-Xmx1g", "-Dserver=production"]` + An array of String. ### Environment +- `console` - The specified console to launch the current program. Current default value is `integratedTerminal`. You could customize it via the global user setting `java.debug.settings.console` for the whole workspace, or `console` in launch.json for each debug session. The `console` option in launch.json (if provided) takes precedence over `java.debug.settings.console` in user settings. + * `"console": "internalConsole"` + VS Code debug console (input stream not supported). If you're developing backend application, `internalConsole` is recommended. + ![internalConsole](https://user-images.githubusercontent.com/14052197/67193516-fef6cd80-f427-11e9-8a97-9014470c3a4d.gif) + + * `"console": "integratedTerminal"` + VS Code integrated terminal. If you're developing console application with io input requirements, you must use the terminal to accept user input. For example, use *Scanner* class for user input. + ![integratedTerminal](https://user-images.githubusercontent.com/14052197/67195762-251e6c80-f42c-11e9-89d0-9545560beea9.gif) + + * `"console": "externalTerminal"` + External terminal that can be configured in user settings. The user scenario is same as integrated terminal. The difference is opening an external terminal window to run your program. + ![externalTerminal](https://user-images.githubusercontent.com/14052197/67196194-eccb5e00-f42c-11e9-9d4c-6baa5eec18bc.gif) + +- `env` - The extra environment variables for the program. It's accessible via `System.getenv(key)`. It accepts key-value pairs. + ```json + "env": { + "HOST": "127.0.0.1", + "PORT": 8080 + } + ``` -- `console` - The specified console to launch the current program. Current default value is `integratedTerminal`. You could customize it via the global user setting `java.debug.settings.console` for the whole workspace, or `console` in launch.json for each debug session. The `console` option in launch.json (if provided) takes precedence over `java.debug.settings.console` in user settings. - - - `"console": "internalConsole"` - VS Code debug console (input stream not supported). If you're developing backend application, `internalConsole` is recommended. - ![internalConsole](https://user-images.githubusercontent.com/14052197/67193516-fef6cd80-f427-11e9-8a97-9014470c3a4d.gif) - - - `"console": "integratedTerminal"` - VS Code integrated terminal. If you're developing console application with io input requirements, you must use the terminal to accept user input. For example, use _Scanner_ class for user input. - ![integratedTerminal](https://user-images.githubusercontent.com/14052197/67195762-251e6c80-f42c-11e9-89d0-9545560beea9.gif) - - - `"console": "externalTerminal"` - External terminal that can be configured in user settings. The user scenario is same as integrated terminal. The difference is opening an external terminal window to run your program. - ![externalTerminal](https://user-images.githubusercontent.com/14052197/67196194-eccb5e00-f42c-11e9-9d4c-6baa5eec18bc.gif) +### Don't step into the specified classes or methods -- `env` - The extra environment variables for the program. It's accessible via `System.getenv(key)`. It accepts key-value pairs. +- `stepFilters` - Skip the specified classes or methods you don't want to step into. Class names should be fully qualified. Wildcard is supported. + - Skip the class loader. ```json - "env": { - "HOST": "127.0.0.1", - "PORT": 8080 - } + "stepFilters": { + "classNameFilters": [ + "java.lang.ClassLoader", + ] + } ``` + ![skipClassLoader](https://user-images.githubusercontent.com/14052197/67254877-ff3bab00-f4b1-11e9-8da0-22b49935bd57.gif) -### Don't step into the specified classes or methods + - Skip the JDK classes. + ```json + "stepFilters": { + "classNameFilters": [ + "java.*", + "javax.*", + "com.sun.*", + "sun.*", + "sunw.*", + "org.omg.*" + ] + } + ``` + ![skipJDK](https://user-images.githubusercontent.com/14052197/67255028-9dc80c00-f4b2-11e9-9113-bef0c0bdf5cb.gif) -- `stepFilters` - Skip the specified classes or methods you don't want to step into. Class names should be fully qualified. Wildcard is supported. - - - Skip the class loader. - - ```json - "stepFilters": { - "classNameFilters": [ - "java.lang.ClassLoader", - ] - } - ``` - - ![skipClassLoader](https://user-images.githubusercontent.com/14052197/67254877-ff3bab00-f4b1-11e9-8da0-22b49935bd57.gif) - - - Skip the JDK classes. - - ```json - "stepFilters": { - "classNameFilters": [ - "java.*", - "javax.*", - "com.sun.*", - "sun.*", - "sunw.*", - "org.omg.*" - ] - } - ``` - - ![skipJDK](https://user-images.githubusercontent.com/14052197/67255028-9dc80c00-f4b2-11e9-9113-bef0c0bdf5cb.gif) - - - Skip the constructors and the synthetic methods. - ```json - "stepFilters": { - "skipSynthetics": true, - "skipStaticInitializers": true, - "skipConstructors": true - } - ``` - ![skipMethods](https://user-images.githubusercontent.com/14052197/67255209-83daf900-f4b3-11e9-8533-70f6ff941e8d.gif) + - Skip the constructors and the synthetic methods. + ```json + "stepFilters": { + "skipSynthetics": true, + "skipStaticInitializers": true, + "skipConstructors": true + } + ``` + ![skipMethods](https://user-images.githubusercontent.com/14052197/67255209-83daf900-f4b3-11e9-8533-70f6ff941e8d.gif) ### Attach to a debuggee +- `hostName` - The host name or ip address of the debuggee you want to attach. +- `port` - The port of the debuggee you want to attach. -- `hostName` - The host name or ip address of the debuggee you want to attach. -- `port` - The port of the debuggee you want to attach. - -Before attaching to a debuggee, your debuggee program must be started with debug mode. The standard command line for debug mode is like `java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 -cp bin MyApp`, and then the debug port of your debuggee is _5005_. - +Before attaching to a debuggee, your debuggee program must be started with debug mode. The standard command line for debug mode is like `java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 -cp bin MyApp`, and then the debug port of your debuggee is *5005*. ```json { "type": "java", @@ -173,36 +156,30 @@ Before attaching to a debuggee, your debuggee program must be started with debug ``` In some cases, you may want to start your program with the external builder and launcher, then you can configure these jobs in [tasks.json](https://code.visualstudio.com/docs/editor/tasks) and attach to it. For example, launching springboot application via mvn command, and then attach a debugger. - #### Attach to mvn task - -1. Configure your command in .vscode/tasks.json - The mvn task is a background task, you should use _problemMatcher_ filter to tell VS Code it's ready. - ```json +1) Configure your command in .vscode/tasks.json - The mvn task is a background task, you should use *problemMatcher* filter to tell VS Code it's ready. + ```json { "label": "mvnDebug", "type": "shell", "command": "mvn spring-boot:run -Dspring-boot.run.jvmArguments=\"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005\"", "isBackground": true, - "problemMatcher": [ - { - "pattern": [ - { - "regexp": "\\b\\B", - "file": 1, - "location": 2, - "message": 3 - } - ], - "background": { - "activeOnStart": true, - "beginsPattern": "^.*Attaching agents:.*", - "endsPattern": "^.*Listening for transport dt_socket at address.*" - } + "problemMatcher": [{ + "pattern": [{ + "regexp": "\\b\\B", + "file": 1, + "location": 2, + "message": 3 + }], + "background": { + "activeOnStart": true, + "beginsPattern": "^.*Attaching agents:.*", + "endsPattern": "^.*Listening for transport dt_socket at address.*" } - ] + }] } ``` -2. Configure `preLaunchTask` and the debug port in .vscode/launch.json. +2) Configure `preLaunchTask` and the debug port in .vscode/launch.json. ```json { "type": "java", @@ -213,102 +190,89 @@ In some cases, you may want to start your program with the external builder and "preLaunchTask": "mvnDebug" } ``` -3. F5 will launch the mvn task, and attach the debugger. See the demo. - ![attachToMvn](https://user-images.githubusercontent.com/14052197/67262705-4f2d6880-f4d8-11e9-9e2d-9c35a6613c08.gif) +3) F5 will launch the mvn task, and attach the debugger. See the demo. +![attachToMvn](https://user-images.githubusercontent.com/14052197/67262705-4f2d6880-f4d8-11e9-9e2d-9c35a6613c08.gif) #### Attach to embedded maven tomcat server - -- pom.xml sample for embedded tomcat server. - -```xml - ... - - org.apache.tomcat.maven - tomcat7-maven-plugin - 2.2 - - ... -``` - -- The steps to attach to the embedded maven tomcat server. - -1. Use .vscode/tasks.json to configure _run-tomcat_ and _stop-tomcat_ tasks. - -```json -{ - "version": "2.0.0", - "tasks": [ - { - "label": "run-tomcat", - "type": "shell", - "command": "MAVEN_OPTS=\"$MAVEN_OPTS -agentlib:jdwp=transport=dt_socket,address=5005,server=y,suspend=n\" ./mvnw tomcat7:run", - "group": "build", - "isBackground": true, - "problemMatcher": [ - { - "pattern": [ - { - "regexp": "\\b\\B", - "file": 1, - "location": 2, - "message": 3 - } - ], + - pom.xml sample for embedded tomcat server. + ```xml + ... + + org.apache.tomcat.maven + tomcat7-maven-plugin + 2.2 + + ... + ``` + - The steps to attach to the embedded maven tomcat server. + 1) Use .vscode/tasks.json to configure *run-tomcat* and *stop-tomcat* tasks. + ```json + { + "version": "2.0.0", + "tasks": [ + { + "label": "run-tomcat", + "type": "shell", + "command": "MAVEN_OPTS=\"$MAVEN_OPTS -agentlib:jdwp=transport=dt_socket,address=5005,server=y,suspend=n\" ./mvnw tomcat7:run", + "group": "build", + "isBackground": true, + "problemMatcher": [{ + "pattern": [{ + "regexp": "\\b\\B", + "file": 1, + "location": 2, + "message": 3 + }], "background": { "activeOnStart": true, "beginsPattern": "^.*Listening for", "endsPattern": "^.*transport dt_socket at address.*" } - } - ] - }, - { - "label": "stop-tomcat", - "type": "shell", - "command": "echo ${input:terminate}}", - "problemMatcher": [] - } - ], - "inputs": [ - { - "id": "terminate", - "type": "command", - "command": "workbench.action.tasks.terminate", - "args": "run-tomcat" - } - ] -} -``` - -2. Use .vscode/launch.json to configure the attach configuration. Use `preLaunchTask` to run tomcat before the attach, and `postDebugTask` to stop tomcat after the debug ends. - -```json -{ - "version": "0.2.0", - "configurations": [ - { - "type": "java", - "name": "Debug (Attach)", - "request": "attach", - "hostName": "localhost", - "port": 5005, - "preLaunchTask": "run-tomcat", - "postDebugTask": "stop-tomcat" - } - ] -} -``` - -3. F5 will auto start the tomcat server and attach the debugger. The demo below will show how to debug spring mvc in tomcat. - ![attachToEmbeddedTomcat](https://user-images.githubusercontent.com/14052197/67541153-80957680-f71a-11e9-9d59-e9aaa752fe33.gif) + }] + }, + { + "label": "stop-tomcat", + "type": "shell", + "command": "echo ${input:terminate}}", + "problemMatcher": [] + } + ], + "inputs": [ + { + "id": "terminate", + "type": "command", + "command": "workbench.action.tasks.terminate", + "args": "run-tomcat" + } + ] + } + ``` + 2) Use .vscode/launch.json to configure the attach configuration. Use `preLaunchTask` to run tomcat before the attach, and `postDebugTask` to stop tomcat after the debug ends. + ```json + { + "version": "0.2.0", + "configurations": [ + { + "type": "java", + "name": "Debug (Attach)", + "request": "attach", + "hostName": "localhost", + "port": 5005, + "preLaunchTask": "run-tomcat", + "postDebugTask": "stop-tomcat" + } + ] + } + ``` + 3) F5 will auto start the tomcat server and attach the debugger. The demo below will show how to debug spring mvc in tomcat. + ![attachToEmbeddedTomcat](https://user-images.githubusercontent.com/14052197/67541153-80957680-f71a-11e9-9d59-e9aaa752fe33.gif) -> If you want to try to debug your Java webapps in a standalone tomcat server, please try VS Code [Tomcat for Java](https://marketplace.visualstudio.com/items?itemName=adashen.vscode-tomcat) extension. + > If you want to try to debug your Java webapps in a standalone tomcat server, please try VS Code [Tomcat for Java](https://marketplace.visualstudio.com/items?itemName=adashen.vscode-tomcat) extension. -> If you want to try to debug embedded tomcat server with gradle plugin, see the [gradle sample](https://github.com/microsoft/vscode-java-debug/issues/140#issuecomment-343656398). + > If you want to try to debug embedded tomcat server with gradle plugin, see the [gradle sample](https://github.com/microsoft/vscode-java-debug/issues/140#issuecomment-343656398). #### Use javac as the builder and attach to java process - -1. Configure the javac builder and java runner jobs in .vscode/tasks.json. +1) Configure the javac builder and java runner jobs in .vscode/tasks.json. ```json { "version": "2.0.0", @@ -324,28 +288,24 @@ In some cases, you may want to start your program with the external builder and "type": "shell", "command": "java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 -cp bin app.SimpleCalc", "isBackground": true, - "problemMatcher": [ - { - "pattern": [ - { - "regexp": "\\b\\B", - "file": 1, - "location": 2, - "message": 3 - } - ], - "background": { - "activeOnStart": true, - "beginsPattern": "^.*Listening for", - "endsPattern": "^.*transport dt_socket at address.*" - } + "problemMatcher": [{ + "pattern": [{ + "regexp": "\\b\\B", + "file": 1, + "location": 2, + "message": 3 + }], + "background": { + "activeOnStart": true, + "beginsPattern": "^.*Listening for", + "endsPattern": "^.*transport dt_socket at address.*" } - ] + }] } ] } ``` -2. Configure `preLaunchTask` and the debug port in .vscode/launch.json. +2) Configure `preLaunchTask` and the debug port in .vscode/launch.json. ```json { "version": "0.2.0", @@ -361,45 +321,38 @@ In some cases, you may want to start your program with the external builder and ] } ``` -3. F5 will run the tasks and attach the debugger. See the demo. - ![attachToJava](https://user-images.githubusercontent.com/14052197/67263956-3cb52e00-f4dc-11e9-9c78-6e66cb3d7c2b.gif) +3) F5 will run the tasks and attach the debugger. See the demo. +![attachToJava](https://user-images.githubusercontent.com/14052197/67263956-3cb52e00-f4dc-11e9-9c78-6e66cb3d7c2b.gif) ## Modify the settings.json (User Setting) +- `java.debug.settings.console` - The specified console to launch Java program, defaults to `integratedTerminal`. If you want to customize the console for a specific debug session, please use `console` option in launch.json instead. + ![terminal](https://user-images.githubusercontent.com/14052197/67256063-cf8fa180-f4b7-11e9-9455-77daad2f0ec9.gif) -- `java.debug.settings.console` - The specified console to launch Java program, defaults to `integratedTerminal`. If you want to customize the console for a specific debug session, please use `console` option in launch.json instead. - ![terminal](https://user-images.githubusercontent.com/14052197/67256063-cf8fa180-f4b7-11e9-9455-77daad2f0ec9.gif) - -- `java.debug.settings.forceBuildBeforeLaunch` - Force building the workspace before launching java program, defaults to `true`. Sometimes you may be bothered with the message _"Build failed, do you want to continue?"_, you could disable this setting to suppress the message. +- `java.debug.settings.forceBuildBeforeLaunch` - Force building the workspace before launching java program, defaults to `true`. Sometimes you may be bothered with the message *"Build failed, do you want to continue?"*, you could disable this setting to suppress the message. -- `java.debug.settings.onBuildFailure` - Sometimes you may be bothered with the message _"Build failed, do you want to continue?"_, you could use this setting to suppress the message with a specific selection. +- `java.debug.settings.onBuildFailureProceed` - Sometimes you may be bothered with the message *"Build failed, do you want to continue?"*, you could use this setting to suppress the message and proceed. -- `java.debug.settings.hotCodeReplace` - Reload the changed Java classes during debugging, defaults to `manual`. It supports `manual`, `auto`, `never`. +- `java.debug.settings.hotCodeReplace` - Reload the changed Java classes during debugging, defaults to `manual`. It supports `manual`, `auto`, `never`. + - `manual` - Click the toolbar to apply the changes. + ![hcr](https://user-images.githubusercontent.com/14052197/67256313-f5697600-f4b8-11e9-9db6-54540b6350ad.png) + - `auto` - Automatically apply the changes after saved. + - `never` - Never apply the changes. - - `manual` - Click the toolbar to apply the changes. - ![hcr](https://user-images.githubusercontent.com/14052197/67256313-f5697600-f4b8-11e9-9db6-54540b6350ad.png) - - `auto` - Automatically apply the changes after saved. - - `never` - Never apply the changes. - -- `java.debug.settings.enableRunDebugCodeLens` - Enable the code lens provider for the _Run_ and _Debug_ buttons over main entry points, defaults to `true`. - - `true` - Show the code lens. - ![codelens](https://user-images.githubusercontent.com/14052197/67256585-83922c00-f4ba-11e9-883f-2b3de3db2dfa.png) - - `false` - Show the Run/Debug link in the hover. - ![hover](https://user-images.githubusercontent.com/14052197/67256539-2ac29380-f4ba-11e9-8a5b-e5e1d0a27f0e.png) +- `java.debug.settings.enableRunDebugCodeLens` - Enable the code lens provider for the *Run* and *Debug* buttons over main entry points, defaults to `true`. + - `true` - Show the code lens. + ![codelens](https://user-images.githubusercontent.com/14052197/67256585-83922c00-f4ba-11e9-883f-2b3de3db2dfa.png) + - `false` - Show the Run/Debug link in the hover. + ![hover](https://user-images.githubusercontent.com/14052197/67256539-2ac29380-f4ba-11e9-8a5b-e5e1d0a27f0e.png) ## FAQ - ### 1. No way to take input. - -If you are using _Scanner(System.in)_ to get the user input, you need change the user setting `java.debug.settings.console` to `integratedTerminal` or `externalTerminal`. +If you are using *Scanner(System.in)* to get the user input, you need change the user setting `java.debug.settings.console` to `integratedTerminal` or `externalTerminal`. ### 2. Code output is not in the DEBUG CONSOLE panel but Terminal. - By default, the debugger uses the terminal to launch your program for better accepting user input. And you will see the original command line is displayed at the top of the terminal. If you want a cleaner console to show your code output, you could try to change the user setting `java.debug.settings.console` to `internalConsole`. Please notice that the internal console (VS Code built-in DEBUG CONSOLE) doesn't support user input. ### 3. The classpath changed when using terminal. - -In order to avoid the command line being too long, the debugger will shorten your classpath into classpath.jar (for JDK 8 only) or argsfile (for JDK 9 and above) by default. If your program need read the original classpath value (for example, _System.getProperty("java.class.path")_), you could try to change the console to `internalConsole`, or use a higher JDK (9 and above) to launch your program. +In order to avoid the command line being too long, the debugger will shorten your classpath into classpath.jar (for JDK 8 only) or argsfile (for JDK 9 and above) by default. If your program need read the original classpath value (for example, *System.getProperty("java.class.path")*), you could try to change the console to `internalConsole`, or use a higher JDK (9 and above) to launch your program. ### 4. Failed to launch debuggee in terminal with TransportTimeoutException. - When launching failed in terminal, then you could try to change the user setting `java.debug.settings.console` to `internalConsole`. diff --git a/README.md b/README.md index bac22b98..4f8ff106 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,7 @@ Please also check the documentation of [Language Support for Java by Red Hat](ht - never - Never apply the changes. - `java.debug.settings.enableRunDebugCodeLens`: enable the code lens provider for the run and debug buttons over main entry points, defaults to `true`. - `java.debug.settings.forceBuildBeforeLaunch`: force building the workspace before launching java program, defaults to `true`. -- `java.debug.settings.onBuildFailure`: Select option to use when build fails, defaults to none (will prompt for selection). +- `java.debug.settings.onBuildFailureProceed`: Force to proceed when build fails, defaults to false. - `java.debug.settings.console`: The specified console to launch Java program, defaults to `integratedTerminal`. If you want to customize the console for a specific debug session, please modify the 'console' config in launch.json. - `internalConsole` - VS Code debug console (input stream not supported). - `integratedTerminal` - VS Code integrated terminal. diff --git a/package.json b/package.json index a3febaea..dd48f812 100644 --- a/package.json +++ b/package.json @@ -636,19 +636,10 @@ "description": "%java.debugger.configuration.forceBuildBeforeLaunch%", "default": true }, - "java.debug.settings.onBuildFailure": { - "type": "string", - "enum": [ - "Proceed", - "Fix...", - "Cancel" - ], - "enumDescriptions": [ - "%java.debugger.configuration.onBuildFailureProceed%", - "%java.debugger.configuration.onBuildFailureFix%", - "%java.debugger.configuration.onBuildFailureCancel%" - ], - "description": "%java.debugger.configuration.onBuildFailure%" + "java.debug.settings.onBuildFailureProceed": { + "type": "boolean", + "description": "%java.debugger.configuration.onBuildFailureProceed%", + "default": false }, "java.debug.settings.console": { "type": "string", @@ -772,4 +763,4 @@ "vscode-extension-telemetry": "^0.1.6", "vscode-extension-telemetry-wrapper": "^0.8.0" } -} +} \ No newline at end of file diff --git a/package.nls.json b/package.nls.json index e1dc4da5..940b1a5d 100644 --- a/package.nls.json +++ b/package.nls.json @@ -53,10 +53,7 @@ "java.debugger.configuration.hotCodeReplace.description": "Reload the changed Java classes during debugging. Make sure 'java.autobuild.enabled' is not disabled.", "java.debugger.configuration.enableRunDebugCodeLens.description": "Enable the run and debug code lens providers over main methods.", "java.debugger.configuration.forceBuildBeforeLaunch": "Force building the workspace before launching java program.", - "java.debugger.configuration.onBuildFailure": "Select option to use when build fails", - "java.debugger.configuration.onBuildFailureProceed": "Proceed with debugging", - "java.debugger.configuration.onBuildFailureFix": "Open fix menu", - "java.debugger.configuration.onBuildFailureCancel": "Cancel debugging", + "java.debugger.configuration.onBuildFailureProceed": "Force to proceed when build fails", "java.debugger.configuration.console": "The specified console to launch Java program. If you want to customize the console for a specific debug session, please modify the 'console' config in launch.json.", "java.debugger.configuration.exceptionBreakpoint.skipClasses": "Skip the specified classes when breaking on exception. You could use the built-in variables such as '$JDK' and '$Libraries' to skip a group of classes, or add a specific class name expression, e.g. java.*, *.Foo", "java.debugger.configuration.jdwp.limitOfVariablesPerJdwpRequest.description": "The maximum number of variables or fields that can be requested in one JDWP request. The higher the value, the less frequently debuggee will be requested when expanding the variable view. Also a large number can cause JDWP request timeout.", diff --git a/src/build.ts b/src/build.ts index 9713c809..8c2a4a80 100644 --- a/src/build.ts +++ b/src/build.ts @@ -10,7 +10,7 @@ import * as lsPlugin from "./languageServerPlugin"; import * as utility from "./utility"; const JAVA_DEBUG_CONFIGURATION = "java.debug.settings"; -const ON_BUILD_FAILURE = "onBuildFailure"; +const ON_BUILD_FAILURE_PROCEED = "onBuildFailureProceed"; export async function buildWorkspace(): Promise { const buildResult = await instrumentOperation("build", async (operationId: string) => { @@ -36,7 +36,7 @@ export async function buildWorkspace(): Promise { async function handleBuildFailure(operationId: string, err: any): Promise { const configuration = vscode.workspace.getConfiguration(JAVA_DEBUG_CONFIGURATION); - const onBuildFailure = configuration.get(ON_BUILD_FAILURE); + const onBuildFailureProceed = configuration.get(ON_BUILD_FAILURE_PROCEED); if (err instanceof utility.JavaExtensionNotEnabledError) { utility.guideToInstallJavaExtension(); @@ -53,8 +53,8 @@ async function handleBuildFailure(operationId: string, err: any): Promise Date: Sat, 10 Oct 2020 09:12:43 +0100 Subject: [PATCH 3/3] Squashed commit of the following: commit b76da40b8b3488f7e3840e20780e8757d1854586 Author: srfrnk Date: Sat Oct 10 09:11:32 2020 +0100 removed newline at EOF commit c80801c90e73942ab69f5266f5a5e525a236bd39 Author: srfrnk Date: Sat Oct 10 09:10:45 2020 +0100 Revert "removed newline at EOF" This reverts commit 8e2f872efa7f75939ca04ac03a64eaa1c6a536af. commit bd90bf2d573e05889fa386434560f82a9ec0eb85 Author: srfrnk Date: Sat Oct 10 09:10:07 2020 +0100 added newline at EOF commit 8e2f872efa7f75939ca04ac03a64eaa1c6a536af Author: srfrnk Date: Sat Oct 10 09:04:51 2020 +0100 removed newline at EOF commit c997a6c8ab0d33765361f14cc6aede0737c27b52 Author: Srfrnk Date: Sat Oct 10 09:03:55 2020 +0100 Removed newline at EOF commit 7738ddfb3b9fb754c40d38c504977509bf648fbe Author: Srfrnk Date: Sat Oct 10 09:03:00 2020 +0100 Edit outside vscode to prevent adding newline at EOF commit 586824fe6988e9c607470c0ca6983838ae93cded Author: Srfrnk Date: Sat Oct 10 09:01:58 2020 +0100 edit outside vscode to prevent whitespace changes. --- .gitignore | 2 +- Configuration.md | 68 ++++++++++++++++++++++++------------------------ package.json | 2 +- package.nls.json | 2 +- 4 files changed, 37 insertions(+), 37 deletions(-) diff --git a/.gitignore b/.gitignore index 35a57fb6..98790543 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,4 @@ node_modules vscode-java-debug-*.vsix packages/ dist -.DS_Store +.DS_Store \ No newline at end of file diff --git a/Configuration.md b/Configuration.md index 250700db..50dfd6a4 100644 --- a/Configuration.md +++ b/Configuration.md @@ -23,8 +23,8 @@ * [Modify the settings.json (User Setting)](#modify-the-settingsjson-user-setting) * java.debug.settings.console * java.debug.settings.forceBuildBeforeLaunch + * java.debug.settings.onBuildFailureProceed * java.debug.settings.hotCodeReplace - * java.debug.settings.onBuildFailureProceed * java.debug.settings.enableRunDebugCodeLens * [FAQ](#faq) @@ -42,16 +42,16 @@ On the other hand, the debugger provides multiple configuration templates to hel In case you want to manually edit the configuration, below are the explanation and samples about the common debug configurations. ### Main * `mainClass` - mainClass is used to define your program entry, and it's the most important configuration. The debugger provides three options to help you configure this key, see the samples below. - * `"mainClass": ""` - If you have no idea about what to set here, just leave it empty. The debugger will search all possible main classes from the workspace, then prompt you the list to choose for launch. + * `"mainClass": ""` + If you have no idea about what to set here, just leave it empty. The debugger will search all possible main classes from the workspace, then prompt you the list to choose for launch. ![emptyMainClass](https://user-images.githubusercontent.com/14052197/67261011-25bd0e80-f4d1-11e9-966d-3e82a4e261ce.gif) - * `"mainClass": "${file}"` + * `"mainClass": "${file}"` If you have multiple main Java files, use this to auto switch to your current focus program. The debugger will resolve the main class from current active Java file, and set it as the launching main class. ![currentFile](https://user-images.githubusercontent.com/14052197/67183367-d7960580-f413-11e9-9773-7df735710054.gif) - * `"mainClass": "com.microsoft.app.myApp"` - The fully qualified class name, generally it's filled by the debugger's auto generation. + * `"mainClass": "com.microsoft.app.myApp"` + The fully qualified class name, generally it's filled by the debugger's auto generation. ![mainClass](https://user-images.githubusercontent.com/14052197/67190742-17181e00-f423-11e9-98ab-1c568f220ba7.gif) * `projectName` - The preferred project in which the debugger searches for classes. It's required for the evaluation feature. Most of the time, the debugger will auto generate the configuration for you. In case you want to manually configure it, here are the rules. @@ -59,39 +59,39 @@ In case you want to manually edit the configuration, below are the explanation a * When you open a gradle project, the project name is the `baseName` or the root folder name. * When you open other Java files, leave the launch.json empty and allow the debugger auto generates the project name for you. - Pro Tip: The easiest way to get the project name is to install [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) extension, the top node in the JAVA DEPENDENCIES view is your project name. + Pro Tip: The easiest way to get the project name is to install [Java Dependency Viewer](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) extension, the top node in the JAVA DEPENDENCIES view is your project name. ![java-dependency-viewer](https://user-images.githubusercontent.com/14052197/67185034-7cfea880-f417-11e9-8a3b-a3af1a9e86bb.png) ### Arguments * `args` - Program arguments which are used to pass application configuration to your program, and they are accessible via "args" String array parameter in your main method `public static void main(String[] args)`. It accepts three kinds of value, see the samples below. - * `"args": "arg0 arg1"` + * `"args": "arg0 arg1"` Space separated String value. ![programArgs](https://user-images.githubusercontent.com/14052197/67191536-5abf5780-f424-11e9-9664-6cc5805225bb.gif) - * `"args": ["arg0", "arg1"]` + * `"args": ["arg0", "arg1"]` An array of String. - * `"args": "${command:SpecifyProgramArgs}"` - The debugger will prompt you with an input box to type the args value before launching the program. This is convenient when you have a program running against multiple data set. + * `"args": "${command:SpecifyProgramArgs}"` + The debugger will prompt you with an input box to type the args value before launching the program. This is convenient when you have a program running against multiple data set. ![specifyArgs](https://user-images.githubusercontent.com/14052197/67191890-0ff20f80-f425-11e9-8df2-5fd98e61c204.gif) * `vmArgs` - VM arguments are used to configure JVM options and platform properties. Most of these arguments have a prefix (-D, -X, -XX). For example, *-Xms256m* arguments defines the initial Java heap size to 256MB. And you can also use *-DpropertyName=propertyValue* to configure system properties for your program. These properties are read via API *System.getProperty(propertyName)*. It accepts a String or an array of String, see the samples below. - * `"vmArgs": "-Xms256m -Xmx1g -Dserver=production"` + * `"vmArgs": "-Xms256m -Xmx1g -Dserver=production"` Space separated String value. - * `"vmArgs": ["-Xms256m", "-Xmx1g", "-Dserver=production"]` + * `"vmArgs": ["-Xms256m", "-Xmx1g", "-Dserver=production"]` An array of String. ### Environment - `console` - The specified console to launch the current program. Current default value is `integratedTerminal`. You could customize it via the global user setting `java.debug.settings.console` for the whole workspace, or `console` in launch.json for each debug session. The `console` option in launch.json (if provided) takes precedence over `java.debug.settings.console` in user settings. - * `"console": "internalConsole"` + * `"console": "internalConsole"` VS Code debug console (input stream not supported). If you're developing backend application, `internalConsole` is recommended. ![internalConsole](https://user-images.githubusercontent.com/14052197/67193516-fef6cd80-f427-11e9-8a97-9014470c3a4d.gif) - * `"console": "integratedTerminal"` - VS Code integrated terminal. If you're developing console application with io input requirements, you must use the terminal to accept user input. For example, use *Scanner* class for user input. + * `"console": "integratedTerminal"` + VS Code integrated terminal. If you're developing console application with io input requirements, you must use the terminal to accept user input. For example, use *Scanner* class for user input. ![integratedTerminal](https://user-images.githubusercontent.com/14052197/67195762-251e6c80-f42c-11e9-89d0-9545560beea9.gif) - * `"console": "externalTerminal"` - External terminal that can be configured in user settings. The user scenario is same as integrated terminal. The difference is opening an external terminal window to run your program. + * `"console": "externalTerminal"` + External terminal that can be configured in user settings. The user scenario is same as integrated terminal. The difference is opening an external terminal window to run your program. ![externalTerminal](https://user-images.githubusercontent.com/14052197/67196194-eccb5e00-f42c-11e9-9d4c-6baa5eec18bc.gif) - `env` - The extra environment variables for the program. It's accessible via `System.getenv(key)`. It accepts key-value pairs. @@ -157,7 +157,7 @@ Before attaching to a debuggee, your debuggee program must be started with debug In some cases, you may want to start your program with the external builder and launcher, then you can configure these jobs in [tasks.json](https://code.visualstudio.com/docs/editor/tasks) and attach to it. For example, launching springboot application via mvn command, and then attach a debugger. #### Attach to mvn task -1) Configure your command in .vscode/tasks.json - The mvn task is a background task, you should use *problemMatcher* filter to tell VS Code it's ready. +1) Configure your command in .vscode/tasks.json - The mvn task is a background task, you should use *problemMatcher* filter to tell VS Code it's ready. ```json { "label": "mvnDebug", @@ -179,7 +179,7 @@ In some cases, you may want to start your program with the external builder and }] } ``` -2) Configure `preLaunchTask` and the debug port in .vscode/launch.json. +2) Configure `preLaunchTask` and the debug port in .vscode/launch.json. ```json { "type": "java", @@ -190,11 +190,11 @@ In some cases, you may want to start your program with the external builder and "preLaunchTask": "mvnDebug" } ``` -3) F5 will launch the mvn task, and attach the debugger. See the demo. +3) F5 will launch the mvn task, and attach the debugger. See the demo. ![attachToMvn](https://user-images.githubusercontent.com/14052197/67262705-4f2d6880-f4d8-11e9-9e2d-9c35a6613c08.gif) #### Attach to embedded maven tomcat server - - pom.xml sample for embedded tomcat server. + - pom.xml sample for embedded tomcat server. ```xml ... @@ -204,8 +204,8 @@ In some cases, you may want to start your program with the external builder and ... ``` - - The steps to attach to the embedded maven tomcat server. - 1) Use .vscode/tasks.json to configure *run-tomcat* and *stop-tomcat* tasks. + - The steps to attach to the embedded maven tomcat server. + 1) Use .vscode/tasks.json to configure *run-tomcat* and *stop-tomcat* tasks. ```json { "version": "2.0.0", @@ -247,7 +247,7 @@ In some cases, you may want to start your program with the external builder and ] } ``` - 2) Use .vscode/launch.json to configure the attach configuration. Use `preLaunchTask` to run tomcat before the attach, and `postDebugTask` to stop tomcat after the debug ends. + 2) Use .vscode/launch.json to configure the attach configuration. Use `preLaunchTask` to run tomcat before the attach, and `postDebugTask` to stop tomcat after the debug ends. ```json { "version": "0.2.0", @@ -264,7 +264,7 @@ In some cases, you may want to start your program with the external builder and ] } ``` - 3) F5 will auto start the tomcat server and attach the debugger. The demo below will show how to debug spring mvc in tomcat. + 3) F5 will auto start the tomcat server and attach the debugger. The demo below will show how to debug spring mvc in tomcat. ![attachToEmbeddedTomcat](https://user-images.githubusercontent.com/14052197/67541153-80957680-f71a-11e9-9d59-e9aaa752fe33.gif) > If you want to try to debug your Java webapps in a standalone tomcat server, please try VS Code [Tomcat for Java](https://marketplace.visualstudio.com/items?itemName=adashen.vscode-tomcat) extension. @@ -305,7 +305,7 @@ In some cases, you may want to start your program with the external builder and ] } ``` -2) Configure `preLaunchTask` and the debug port in .vscode/launch.json. +2) Configure `preLaunchTask` and the debug port in .vscode/launch.json. ```json { "version": "0.2.0", @@ -321,7 +321,7 @@ In some cases, you may want to start your program with the external builder and ] } ``` -3) F5 will run the tasks and attach the debugger. See the demo. +3) F5 will run the tasks and attach the debugger. See the demo. ![attachToJava](https://user-images.githubusercontent.com/14052197/67263956-3cb52e00-f4dc-11e9-9c78-6e66cb3d7c2b.gif) ## Modify the settings.json (User Setting) @@ -333,26 +333,26 @@ In some cases, you may want to start your program with the external builder and - `java.debug.settings.onBuildFailureProceed` - Sometimes you may be bothered with the message *"Build failed, do you want to continue?"*, you could use this setting to suppress the message and proceed. - `java.debug.settings.hotCodeReplace` - Reload the changed Java classes during debugging, defaults to `manual`. It supports `manual`, `auto`, `never`. - - `manual` - Click the toolbar to apply the changes. + - `manual` - Click the toolbar to apply the changes. ![hcr](https://user-images.githubusercontent.com/14052197/67256313-f5697600-f4b8-11e9-9db6-54540b6350ad.png) - `auto` - Automatically apply the changes after saved. - `never` - Never apply the changes. - `java.debug.settings.enableRunDebugCodeLens` - Enable the code lens provider for the *Run* and *Debug* buttons over main entry points, defaults to `true`. - - `true` - Show the code lens. + - `true` - Show the code lens. ![codelens](https://user-images.githubusercontent.com/14052197/67256585-83922c00-f4ba-11e9-883f-2b3de3db2dfa.png) - - `false` - Show the Run/Debug link in the hover. + - `false` - Show the Run/Debug link in the hover. ![hover](https://user-images.githubusercontent.com/14052197/67256539-2ac29380-f4ba-11e9-8a5b-e5e1d0a27f0e.png) ## FAQ -### 1. No way to take input. +### 1. No way to take input. If you are using *Scanner(System.in)* to get the user input, you need change the user setting `java.debug.settings.console` to `integratedTerminal` or `externalTerminal`. -### 2. Code output is not in the DEBUG CONSOLE panel but Terminal. +### 2. Code output is not in the DEBUG CONSOLE panel but Terminal. By default, the debugger uses the terminal to launch your program for better accepting user input. And you will see the original command line is displayed at the top of the terminal. If you want a cleaner console to show your code output, you could try to change the user setting `java.debug.settings.console` to `internalConsole`. Please notice that the internal console (VS Code built-in DEBUG CONSOLE) doesn't support user input. ### 3. The classpath changed when using terminal. In order to avoid the command line being too long, the debugger will shorten your classpath into classpath.jar (for JDK 8 only) or argsfile (for JDK 9 and above) by default. If your program need read the original classpath value (for example, *System.getProperty("java.class.path")*), you could try to change the console to `internalConsole`, or use a higher JDK (9 and above) to launch your program. -### 4. Failed to launch debuggee in terminal with TransportTimeoutException. +### 4. Failed to launch debuggee in terminal with TransportTimeoutException. When launching failed in terminal, then you could try to change the user setting `java.debug.settings.console` to `internalConsole`. diff --git a/package.json b/package.json index dd48f812..f64de636 100644 --- a/package.json +++ b/package.json @@ -763,4 +763,4 @@ "vscode-extension-telemetry": "^0.1.6", "vscode-extension-telemetry-wrapper": "^0.8.0" } -} \ No newline at end of file +} diff --git a/package.nls.json b/package.nls.json index 940b1a5d..9a7af5ed 100644 --- a/package.nls.json +++ b/package.nls.json @@ -58,4 +58,4 @@ "java.debugger.configuration.exceptionBreakpoint.skipClasses": "Skip the specified classes when breaking on exception. You could use the built-in variables such as '$JDK' and '$Libraries' to skip a group of classes, or add a specific class name expression, e.g. java.*, *.Foo", "java.debugger.configuration.jdwp.limitOfVariablesPerJdwpRequest.description": "The maximum number of variables or fields that can be requested in one JDWP request. The higher the value, the less frequently debuggee will be requested when expanding the variable view. Also a large number can cause JDWP request timeout.", "java.debugger.configuration.jdwp.requestTimeout.description": "The timeout (ms) of JDWP request when the debugger communicates with the target JVM." -} \ No newline at end of file +}