Skip to content

Debugging instructions simplified #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jtulach merged 1 commit into from
Oct 6, 2026
Merged

Debugging instructions simplified #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 42 additions & 41 deletions BUILD.MD
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,8 @@

```bash
$ git clone --recurse-submodules https://github.com/apache/netbeans-vscode.git
$ cd netbeans-vscode/
$ cd netbeans-vscode
netbeans-vscode$ git submodule update --init
```

## Building
Expand All @@ -44,7 +45,8 @@ To build the VS Code extension invoke:
netbeans-vscode$ ant build-netbeans
netbeans-vscode$ ant build-vscode-ext
```
The resulting extension is then in the `build` directory, with the `.vsix` extension.
The resulting VSCode extension is then generated in the `build` directory -
a file with the `.vsix` extension.
The typical file name is `apache-netbeans-java-0.1.0.vsix` - the version can be
changed by using the `-Dvsix.version=x.y.z` property - that's what
[continuous integration server](https://ci-builds.apache.org/job/Netbeans/job/netbeans-vscode/)
Expand Down Expand Up @@ -96,20 +98,6 @@ java.lsp.server$ npm_config_https_proxy=http://your.proxy.com:port ant test-vsco
when executing the tests for the first time. That shall overcome the proxy
and download an instance of `code` to execute the tests with.

### Eating our own Dog Food

Using the application yourself is the best way of testing! If you want to
_edit/compile/debug_ Apache NetBeans sources, there is a way. After building
the project, execute:

```bash
vscode$ npm run apisupport
```

the system connects to associated autoupdate center and downloads, installs
and enables `org.netbeans.modules.apisupport.ant` module. With such module installed
one can open Apache NetBeans projects and work with them directly from VSCode.

## Running and Debugging

To use the extension created for developement you can run VS Code with
Expand All @@ -122,51 +110,59 @@ vscode$ code --extensionDevelopmentPath=`pwd` path_to_project
Or you can open the `vscode` folder in `code` directly and use **F5** to
debug the extension's *typescript code*.

To debug the *Java code*, launch the NetBeans part of the VS Code system first
and specify suitable debug arguments to start _standalone NBLS_ instance:

```bash
vscode$ npm run nbcode -- --jdkhome /jdk -J-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000
```
To debug the *Java code*, use following prepared script to launch `code` with
necessary arguments:

To add extra modules while debugging the NetBeans part
```bash
vscode$ npm run nbcode -- -J-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=8000 -J-Dnetbeans.extra.dirs=/path/to/extension
vscode$ npm run nbcode
```

Connect to the process with Java debugger, setup all breakpoints. Then launch
the VS Code extension (which connects to the already running _standalone NBLS_ Java process):

The script needs to have `code` and JDK available on classpath. It prints
out the command it attempts to invoke. One can either copy the command and
alter it, when necessary, but one can also provide extra arguments after `--`.
For example to add extra modules while debugging the NetBeans part
```bash
vscode$ code --extensionDevelopmentPath=`pwd` path_to_the_maven_project
vscode$ npm run nbcode -- -J-Dnetbeans.extra.dirs=/path/to/extension
```

To start from a clean state, following
The JPDA protocol listens on port 8000. Connect to the process with Java debugger,
setup all breakpoints. To start from a clean state the following
[CLI options](https://code.visualstudio.com/docs/editor/command-line)
maybe of an interest:
are being passed to the `code` by default:
- `--user-data-dir` - clean any user settings with this option
- `--extensions-dir` - avoid 3rd party extensions using this option

**Important note**: when `--user-data-dir` is used, the _standalone NBLS_ must be start as
The script also instructs the system to print messages (stderr, out) to the console
by adding `-J-Dnetbeans.logger.console=true` to the npm commandline.
This has the same effect as `netbeans.verbose = true` settings in the vscode.
Following summary is printed when using `npm run nbcode`:

```bash
vscode$ nbcode_userdir=/the-code-user-data-dir npm run nbcode -- --jdkhome /jdk -J-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000
Launching `code` with following arguments:
--extensionDevelopmentPath=/netbeans-vscode/vscode
--user-data-dir=/netbeans-vscode/vscode/out/userdir
--extensions-dir=/netbeans-vscode/vscode/out/extdir
and following additional environment variables:
netbeans_debug=-J-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000
```
So that the vscode can connect to the _standalone NBLS_ instance.

With such a summary of arguments passed `code` to
the code as well as environment variables additionally provided to the process one can
fully understand what the script is doing. The `netbeans_debug` variable is only added
if not already specified. As such one can fully control the debugging arguments by
defining the variable before executing the `npm` script:
```bash
netbeans_debug=-J-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=7777 npm run nbcode
```

<!--
### NBLS userdir locations

The default userdir location is inside the **global** vscode settings location:
- on Linux: `~/.config/Code/User/globalStorage/asf.apache-netbeans-java/userdir
- on MacOS X: ~/Library/Application Support/Code/User/globalStorage/asf.apache-netbeans-java/userdir

When the environment variable `nbcode_userdir` (to e.g. `/tmp/foo`) is set when starting vscode or nbcode (npm run nbcode), the userdir will point to `/tmp/foo/userdir`.

### Debug output
_Standalone NBLS_ can be instructed to print messages (stderr, out) to the console: add `-J-Dnetbeans.logger.console=true` to the npm commandline. This has the same effect as `netbeans.verbose = true` settings in the vscode.

### LSP protocol tracing
Messages from the LSP protocol can be displayed in vscode by setting `java.trace.server = verbose` setting in vscode JSON settings. Sometimes it may be needed to record LSP requests and responses in the debug output log stream from the Apache NetBeans language server so that requests are properly ordered with logs from executed actions. This can be enabled on language server startup by adding `-J-Dorg.netbeans.modules.java.lsp.server.lsptrace.level=FINEST`
to the NBLS commandline.

### Debugging separately from global NBLS
By default the extension uses **global** userdir of the **global** vscode instance and uses NBLS data in there. In case this is not desired, the `launch.json` must be changed:
```
Expand All @@ -179,3 +175,8 @@ When using _standalone NBLS_ at the same time, the NBLS must be started as
vscode$ user_data_dir=/path/to/development/area npm run nbcode -- --jdkhome /jdk -J-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000
```
This way the NBLS will use a separate config/cache directory and will not interfere with the default / global installation.
-->

### LSP protocol tracing
Messages from the LSP protocol can be displayed in vscode by setting `java.trace.server = verbose` setting in vscode JSON settings. Sometimes it may be needed to record LSP requests and responses in the debug output log stream from the Apache NetBeans language server so that requests are properly ordered with logs from executed actions. This can be enabled on language server startup by adding `-J-Dorg.netbeans.modules.java.lsp.server.lsptrace.level=FINEST`
to the NBLS commandline.
5 changes: 0 additions & 5 deletions build.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -193,11 +193,6 @@
<arg value="run" />
<arg value="test" />
</exec>
<exec executable="npm${cmd.suffix}" failonerror="true" dir="vscode">
<arg value="--allow-same-version"/>
<arg value="run" />
<arg value="apisupport" />
</exec>
</target>

<target name="build-netbeans" description="Build netbeans">
Expand Down
5 changes: 2 additions & 3 deletions vscode/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1513,12 +1513,11 @@
},
"scripts": {
"vscode:prepublish": "npm run compile",
"clean": "rm -rf out && rm -rf nbcode",
"compile": "tsc -p ./ && node ./esbuild.js",
"watch": "tsc -watch -p ./ | node ./esbuild.js --watch",
"test": "node ./out/test/runTest.js",
"nbcode": "node ./out/nbcode.js",
"nbjavac": "node ./out/nbcode.js -J-Dnetbeans.close=true --modules --install .*nbjavac.*",
"apisupport": "node ./out/nbcode.js -J-Dnetbeans.close=true --modules --install '(org.netbeans.libs.xerces|org.netbeans.modules.editor.structure|org.netbeans.modules.xml|org.netbeans.modules.xml.axi|org.netbeans.modules.xml.retriever|org.netbeans.modules.xml.schema.model|org.netbeans.modules.xml.tax|org.netbeans.modules.xml.text|org.netbeans.modules.ant.browsetask|.*apisupport.*|org.netbeans.modules.debugger.jpda.ant)' && node ./out/nbcode.js -J-Dnetbeans.close=true --modules --enable .*apisupport.ant"
"nbcode": "npm run compile && node ./out/nbcode.js"
},
"devDependencies": {
"@types/glob": "^7.1.1",
Expand Down
Loading
Loading