Skip to content

Commit 388c842

Browse files
testforstephentestforstephen
authored
Update the descriptions of the launch configs in README (#1176)
* Update the descriptions for the launch configs
1 parent c873821 commit 388c842

2 files changed

Lines changed: 114 additions & 37 deletions

File tree

‎Configuration.md‎

Lines changed: 68 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,9 @@ When you run the program via `Run|Debug` CodeLens or `Run`/`Debug` context menu,
3636
![runMenu](https://user-images.githubusercontent.com/14052197/67181889-715bb380-f410-11e9-9aef-c27ce697daa0.gif)
3737

3838
## Modify the launch.json
39+
If you don't see `.vscode/launch.json` in your VS Code window, you can go to "Run and Debug" viewlet to create an initial launch.json.
40+
![create launch.json](https://user-images.githubusercontent.com/14052197/172300183-7758eb9b-5e61-485b-b238-a63a98a9fb11.png)
41+
3942
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.
4043
![launchConfig](https://user-images.githubusercontent.com/14052197/67182212-3908a500-f411-11e9-9467-48ba2f6e0e39.gif)
4144

@@ -59,7 +62,7 @@ In case you want to manually edit the configuration, below are the explanation a
5962
* When you open a gradle project, the project name is the `baseName` or the root folder name.
6063
* When you open other Java files, leave the launch.json empty and allow the debugger auto generates the project name for you.
6164

62-
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.
65+
> 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.
6366
![java-dependency-viewer](https://user-images.githubusercontent.com/14052197/67185034-7cfea880-f417-11e9-8a3b-a3af1a9e86bb.png)
6467

6568
### Arguments
@@ -96,51 +99,96 @@ In case you want to manually edit the configuration, below are the explanation a
9699

97100
- `env` - The extra environment variables for the program. It's accessible via `System.getenv(key)`. It accepts key-value pairs.
98101
```json
99-
"env": {
100-
"HOST": "127.0.0.1",
101-
"PORT": 8080
102+
{
103+
"version": "0.2.0",
104+
"configurations": [
105+
{
106+
"type": "java",
107+
"name": "Launch Hello",
108+
"request": "launch",
109+
"env": {
110+
"HOST": "127.0.0.1",
111+
"PORT": 8080
112+
}
113+
}
114+
]
102115
}
103116
```
104117

105118
- `envFile` - Absolute path to a file containing environment variable definitions.
106119
```json
107-
"envFile": "${workspaceFolder}/.env"
120+
{
121+
"version": "0.2.0",
122+
"configurations": [
123+
{
124+
"type": "java",
125+
"name": "Launch Hello",
126+
"request": "launch",
127+
"envFile": "${workspaceFolder}/.env"
128+
}
129+
]
130+
}
108131
```
109132

110133
### Don't step into the specified classes or methods
111134

112135
- `stepFilters` - Skip the specified classes or methods you don't want to step into. Class names should be fully qualified. Wildcard is supported.
113136
- Skip the class loader.
114137
```json
115-
"stepFilters": {
116-
"classNameFilters": [
117-
"java.lang.ClassLoader",
138+
{
139+
"version": "0.2.0",
140+
"configurations": [
141+
{
142+
"type": "java",
143+
"name": "Launch Hello",
144+
"request": "launch",
145+
"stepFilters": {
146+
"skipClasses": [
147+
"java.lang.ClassLoader",
148+
]
149+
}
150+
}
118151
]
119152
}
120153
```
121154
![skipClassLoader](https://user-images.githubusercontent.com/14052197/67254877-ff3bab00-f4b1-11e9-8da0-22b49935bd57.gif)
122155

123156
- Skip the JDK classes.
124157
```json
125-
"stepFilters": {
126-
"classNameFilters": [
127-
"java.*",
128-
"javax.*",
129-
"com.sun.*",
130-
"sun.*",
131-
"sunw.*",
132-
"org.omg.*"
158+
{
159+
"version": "0.2.0",
160+
"configurations": [
161+
{
162+
"type": "java",
163+
"name": "Launch Hello",
164+
"request": "launch",
165+
"stepFilters": {
166+
"skipClasses": [
167+
"$JDK"
168+
]
169+
}
170+
}
133171
]
134172
}
135173
```
136174
![skipJDK](https://user-images.githubusercontent.com/14052197/67255028-9dc80c00-f4b2-11e9-9113-bef0c0bdf5cb.gif)
137175

138176
- Skip the constructors and the synthetic methods.
139177
```json
140-
"stepFilters": {
141-
"skipSynthetics": true,
142-
"skipStaticInitializers": true,
143-
"skipConstructors": true
178+
{
179+
"version": "0.2.0",
180+
"configurations": [
181+
{
182+
"type": "java",
183+
"name": "Launch Hello",
184+
"request": "launch",
185+
"stepFilters": {
186+
"skipSynthetics": true,
187+
"skipStaticInitializers": true,
188+
"skipConstructors": true
189+
}
190+
}
191+
]
144192
}
145193
```
146194
![skipMethods](https://user-images.githubusercontent.com/14052197/67255209-83daf900-f4b3-11e9-8533-70f6ff941e8d.gif)

‎README.md‎

Lines changed: 46 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -35,24 +35,37 @@ ext install vscode-java-debug
3535
## Use
3636

3737
- Launch VS Code
38-
- Open a Java project (Maven/Gradle/Eclipse)
38+
- Open a Java project (Maven/Gradle/Eclipse/Single Java file)
3939
- Open a Java file to activate the extensions
40-
- Add debug configurations and edit launch.json
41-
- To launch: specify `mainClass`
42-
- To attach: specify `hostName` and `port`
43-
- Press F5
40+
- Press `F5`
4441

4542
Please also check the documentation of [Language Support for Java by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) if you have trouble setting up your project.
4643

4744
## Options
4845

4946
### Launch
5047

51-
- `mainClass` (required) - The fully qualified class name (e.g. [java module name/]com.xyz.MainApp) or the java file path of the program entry.
52-
- `args` - The command line arguments passed to the program. Use `"${command:SpecifyProgramArgs}"` to prompt for program arguments. It accepts a string or an array of string.
48+
- `mainClass` - The fully qualified name of the class containing the main method. If not specified, the debugger automatically resolves the possible main class from current project.
49+
- `${file}` - Current Java file.
50+
- `com.mypackage.Main` - The fully qualified class name.
51+
- `com.java9.mymodule/com.mypackage.Main` - The fully qualified module name and class name.
52+
- `/path/to/Main.java` - The file path of the main class.
53+
- `args` - The command line arguments passed to the program.
54+
- `"${command:SpecifyProgramArgs}"` - Prompt user for program arguments.
55+
- A space-separated string or an array of string.
5356
- `sourcePaths` - The extra source directories of the program. The debugger looks for source code from project settings by default. This option allows the debugger to look for source code in extra directories.
54-
- `modulePaths` - The modulepaths for launching the JVM. If not specified, the debugger will automatically resolve from current project.
55-
- `classPaths` - The classpaths for launching the JVM. If not specified, the debugger will automatically resolve from current project.
57+
- `modulePaths` - The modulepaths for launching the JVM. If not specified, the debugger will automatically resolve from current project. If multiple values are specified, the debugger will merge them together.
58+
- `$Auto` - Automatically resolve the modulepaths of current project.
59+
- `$Runtime` - The modulepaths within 'runtime' scope of current project.
60+
- `$Test` - The modulepaths within 'test' scope of current project.
61+
- `!/path/to/exclude` - Exclude the specified path from modulepaths.
62+
- `/path/to/append` - Append the specified path to the modulepaths.
63+
- `classPaths` - The classpaths for launching the JVM. If not specified, the debugger will automatically resolve from current project. If multiple values are specified, the debugger will merge them together.
64+
- `$Auto` - Automatically resolve the classpaths of current project.
65+
- `$Runtime` - The classpaths within 'runtime' scope of current project.
66+
- `$Test` - The classpaths within 'test' scope of current project.
67+
- `!/path/to/exclude` - Exclude the specified path from classpaths.
68+
- `/path/to/append` - Append the specified path to the classpaths.
5669
- `encoding` - The `file.encoding` setting for the JVM. Possible values can be found in https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html.
5770
- `vmArgs` - The extra options and system properties for the JVM (e.g. -Xms\<size\> -Xmx\<size\> -D\<name\>=\<value\>), it accepts a string or an array of string.
5871
- `projectName` - The preferred project in which the debugger searches for classes. There could be duplicated class names in different projects. This setting also works when the debugger looks for the specified main class when launching a program. It is required when the workspace has multiple java projects, otherwise the expression evaluation and conditional breakpoint may not work.
@@ -71,7 +84,11 @@ Please also check the documentation of [Language Support for Java by Red Hat](ht
7184
- `auto` - Automatically detect the command line length and determine whether to shorten the command line via an appropriate approach.
7285
- `stepFilters` - Skip specified classes or methods when stepping.
7386
- `classNameFilters` - [**Deprecated** - replaced by `skipClasses`] Skip the specified classes when stepping. Class names should be fully qualified. Wildcard is supported.
74-
- `skipClasses` - Skip the specified classes when stepping. 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
87+
- `skipClasses` - Skip the specified classes when stepping.
88+
- `$JDK` - Skip the JDK classes from the default system bootstrap classpath, such as rt.jar, jrt-fs.jar.
89+
- `$Libraries` - Skip the classes from application libraries, such as Maven, Gradle dependencies.
90+
- `java.*` - Skip the specified classes. Wildcard is supported.
91+
- `java.lang.ClassLoader` - Skip the classloaders.
7592
- `skipSynthetics` - Skip synthetic methods when stepping.
7693
- `skipStaticInitializers` - Skip static initializer methods when stepping.
7794
- `skipConstructors` - Skip constructor methods when stepping.
@@ -88,7 +105,11 @@ Please also check the documentation of [Language Support for Java by Red Hat](ht
88105
- `projectName` - The preferred project in which the debugger searches for classes. There could be duplicated class names in different projects. It is required when the workspace has multiple java projects, otherwise the expression evaluation and conditional breakpoint may not work.
89106
- `stepFilters` - Skip specified classes or methods when stepping.
90107
- `classNameFilters` - [**Deprecated** - replaced by `skipClasses`] Skip the specified classes when stepping. Class names should be fully qualified. Wildcard is supported.
91-
- `skipClasses` - Skip the specified classes when stepping. 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
108+
- `skipClasses` - Skip the specified classes when stepping.
109+
- `$JDK` - Skip the JDK classes from the default system bootstrap classpath, such as rt.jar, jrt-fs.jar.
110+
- `$Libraries` - Skip the classes from application libraries, such as Maven, Gradle dependencies.
111+
- `java.*` - Skip the specified classes. Wildcard is supported.
112+
- `java.lang.ClassLoader` - Skip the classloaders.
92113
- `skipSynthetics` - Skip synthetic methods when stepping.
93114
- `skipStaticInitializers` - Skip static initializer methods when stepping.
94115
- `skipConstructors` - Skip constructor methods when stepping.
@@ -104,18 +125,26 @@ Please also check the documentation of [Language Support for Java by Red Hat](ht
104125
- `java.debug.settings.maxStringLength`: the maximum length of string displayed in "Variables" or "Debug Console" viewlet, the string longer than this length will be trimmed, defaults to `0` which means no trim is performed.
105126
- `java.debug.settings.numericPrecision`: the precision when formatting doubles in "Variables" or "Debug Console" viewlet.
106127
- `java.debug.settings.hotCodeReplace`: Reload the changed Java classes during debugging, defaults to `manual`. Make sure `java.autobuild.enabled` is not disabled for [VSCode Java](https://github.com/redhat-developer/vscode-java). See the [wiki page](https://github.com/Microsoft/vscode-java-debug/wiki/Hot-Code-Replace) for more information about usages and limitations.
107-
- manual - Click the toolbar to apply the changes.
108-
- auto - Automatically apply the changes after compilation.
109-
- never - Never apply the changes.
128+
- `manual` - Click the toolbar to apply the changes.
129+
- `auto` - Automatically apply the changes after compilation.
130+
- `never` - Never apply the changes.
110131
- `java.debug.settings.enableRunDebugCodeLens`: enable the code lens provider for the run and debug buttons over main entry points, defaults to `true`.
111132
- `java.debug.settings.forceBuildBeforeLaunch`: force building the workspace before launching java program, defaults to `true`.
112133
- `java.debug.settings.onBuildFailureProceed`: Force to proceed when build fails, defaults to false.
113134
- `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.
114135
- `internalConsole` - VS Code debug console (input stream not supported).
115136
- `integratedTerminal` - VS Code integrated terminal.
116137
- `externalTerminal` - External terminal that can be configured in user settings.
117-
- `java.debug.settings.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
118-
- `java.debug.settings.stepping.skipClasses`: Skip the specified classes when stepping. 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
138+
- `java.debug.settings.exceptionBreakpoint.skipClasses`: Skip the specified classes when breaking on exception.
139+
- `$JDK` - Skip the JDK classes from the default system bootstrap classpath, such as rt.jar, jrt-fs.jar.
140+
- `$Libraries` - Skip the classes from application libraries, such as Maven, Gradle dependencies.
141+
- `java.*` - Skip the specified classes. Wildcard is supported.
142+
- `java.lang.ClassLoader` - Skip the classloaders.
143+
- `java.debug.settings.stepping.skipClasses`: Skip the specified classes when stepping.
144+
- `$JDK` - Skip the JDK classes from the default system bootstrap classpath, such as rt.jar, jrt-fs.jar.
145+
- `$Libraries` - Skip the classes from application libraries, such as Maven, Gradle dependencies.
146+
- `java.*` - Skip the specified classes. Wildcard is supported.
147+
- `java.lang.ClassLoader` - Skip the classloaders.
119148
- `java.debug.settings.stepping.skipSynthetics`: Skip synthetic methods when stepping.
120149
- `java.debug.settings.stepping.skipStaticInitializers`: Skip static initializer methods when stepping.
121150
- `java.debug.settings.stepping.skipConstructors`: Skip constructor methods when stepping.
@@ -124,7 +153,7 @@ Please also check the documentation of [Language Support for Java by Red Hat](ht
124153
- `java.debug.settings.vmArgs`: The default VM arguments to launch the Java program. Eg. Use '-Xmx1G -ea' to increase the heap size to 1GB and enable assertions. If you want to customize the VM arguments for a specific debug session, please modify the 'vmArgs' config in launch.json.
125154
- `java.silentNotification`: Controls whether notifications can be used to report progress. If true, use status bar to report progress instead. Defaults to `false`.
126155

127-
Pro Tip: The documentation [Configuration.md](https://github.com/microsoft/vscode-java-debug/blob/master/Configuration.md) provides lots of samples to demonstrate how to use these debug configurations, recommend to take a look.
156+
> Pro Tip: The documentation [Configuration.md](https://github.com/microsoft/vscode-java-debug/blob/master/Configuration.md) provides lots of samples to demonstrate how to use these debug configurations, recommend to take a look.
128157
129158
## Troubleshooting
130159
Reference the [Troubleshooting Guide](https://github.com/Microsoft/vscode-java-debug/blob/master/Troubleshooting.md) for common errors.

0 commit comments

Comments
 (0)