End user oriented README.md and dedicated BUILD.md (#2546)
* End user oriented README.md and dedicated BUILD.md
* Fixing extension description and marking extension as technology preview in package.json.
* Use VS Code instead of VSCode
* User projects are build with netbeans.jdkhome specified JDK
* Updating titles
* Using * instead of 1 as a hyperlink label
* Update README.md
VSNetBeans -> Apache NetBeans Language Server
Co-authored-by: Dusan Balek <dusan.balek@oracle.com>
diff --git a/java/java.lsp.server/vscode/BUILD.md b/java/java.lsp.server/vscode/BUILD.md
new file mode 100644
index 0000000..46d66ec
--- /dev/null
+++ b/java/java.lsp.server/vscode/BUILD.md
@@ -0,0 +1,98 @@
+# Developing NetBeans based Extension for VS Code
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+## Getting the Code
+
+```bash
+$ git clone https://github.com/apache/netbeans.git
+$ cd netbeans/
+```
+
+## Building
+
+To build the VS Code extension invoke:
+
+```bash
+netbeans$ ant build
+netbeans$ cd java/java.lsp.server
+java.lsp.server$ ant build-vscode-ext -D3rdparty.modules=.*nbjavac.*
+```
+
+The `3rdparty.modules` property doesn't have to be set at all.
+The resulting extension is then in the `build` directory, with the `.vsix` extension.
+
+### Building for Development
+
+If you want to develop the extension, use these steps for building instead:
+
+```bash
+netbeans$ cd java/java.lsp.server
+java.lsp.server$ ant build-lsp-server -D3rdparty.modules=.*nbjavac.*
+java.lsp.server$ cd vscode
+vscode$ npm install
+vscode$ npm run watch
+```
+
+The `3rdparty.modules` property doesn't have to be set at all.
+This target is faster than building the `.vsix` file. Find the instructions
+for running and debugging below.
+
+### Cleaning
+
+Often it is also important to properly clean everything. Use:
+
+```bash
+java.lsp.server$ ant clean-vscode-server
+java.lsp.server$ cd ../..
+netbeans$ ant clean
+```
+
+## Running and Debugging
+
+Have a sample Maven project, open it in NetBeans first and select the main file for both
+the Run and Debug actions.
+
+To use the extension created for developement you can run VS Code with
+following parameter:
+
+```bash
+vscode$ code --extensionDevelopmentPath=`pwd` path_to_the_maven_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:
+
+```bash
+vscode$ npm run nbcode -- --jdkhome /jdk-14/ -J-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000
+```
+
+Connect to the process with Java debugger, setup all breakpoints. Then launch
+and connect from the VS Code extension:
+
+```bash
+vscode$ code --extensionDevelopmentPath=`pwd` path_to_the_maven_project
+```
+
diff --git a/java/java.lsp.server/vscode/README.md b/java/java.lsp.server/vscode/README.md
index 50ca1f0..e36fdbc 100644
--- a/java/java.lsp.server/vscode/README.md
+++ b/java/java.lsp.server/vscode/README.md
@@ -1,4 +1,4 @@
-# NBCode: A NetBeans based Extension for VSCode
+# Apache NetBeans Language Server Extension for VS Code
<!--
@@ -21,80 +21,40 @@
-->
+This is a technology preview of [Apache NetBeans](http://netbeans.org)
+based extension for VS Code. Use it to get all the _goodies of NetBeans_
+via the VS Code user interface! Run on __JDK8__[*], __JDK11__, __JDK15__, etc.
-Get all the goodies of NetBeans via the VSCode user interface!
+[*]: <http://github.com/oracle/nb-javac> "Running on JDK8 requires additional download of GPLv2 with ClassPath Exception code"
-## Building
+Invoke "Open Folder" action to open project directories with `pom.xml` or `build.gradle`
+build scripts. Edit, compile and debug (with the __Java 8+__ debugger configuration)
+the `.java` application and test files in such projects. Debug not only Java code,
+but JavaScript, Python, Ruby polyglot programs at once.
-To build the VS Code extension invoke:
+## Getting Started
-```bash
-netbeans$ ant build
-netbeans$ cd java/java.lsp.server
-java.lsp.server$ ant build-vscode-ext -D3rdparty.modules=.*nbjavac.*
-```
+Follow the
+[online instructions](https://cwiki.apache.org/confluence/display/NETBEANS/Apache+NetBeans+extension+for+Visual+Studio+Code)
+to set your environment up to support
+[typical development use-cases](https://cwiki.apache.org/confluence/display/NETBEANS/Apache+NetBeans+extension+for+Visual+Studio+Code).
-The `3rdparty.modules` property doesn't have to be set at all.
-The resulting extension is then in the `build` directory, with the `.vsix` extension.
+## Supported Actions
-### Building for Development
+* __Java: Compile Workspace__ - invoke Maven or Gradle build
+* __GraalVM: Pause in Script__ - place a breakpoint into first executed polyglot script
+* debugger __Java 8+__ - start test or main class on JDK8+ in polyglot mode
-If you want to develop the extension, use these steps for building instead:
+## Supported Options
-```bash
-netbeans$ cd java/java.lsp.server
-java.lsp.server$ ant build-lsp-server -D3rdparty.modules=.*nbjavac.*
-java.lsp.server$ cd vscode
-vscode$ npm install
-vscode$ npm run watch
-```
-
-The `3rdparty.modules` property doesn't have to be set at all.
-This target is faster than building the `.vsix` file. Find the instructions
-for running and debugging below.
-
-### Cleaning
-
-Often it is also important to properly clean everything. Use:
-
-```bash
-java.lsp.server$ ant clean-vscode-server
-java.lsp.server$ cd ../..
-netbeans$ ant clean
-```
-
-## Running and Debugging
-
-Have a sample Maven project, open it in NetBeans first and select the main file for both
-the Run and Debug actions.
-
-To use the extension created for developement you can run VSCode with
-following parameter:
-
-```bash
-vscode$ code --extensionDevelopmentPath=`pwd` path_to_the_maven_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 VSCode system first
-and specify suitable debug arguments:
-
-```bash
-vscode$ npm run nbcode -- --jdkhome /jdk-14/ -J-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000
-```
-
-Connect to the process with Java debugger, setup all breakpoints. Then launch
-and connect from the VSCode extension:
-
-```bash
-vscode$ code --extensionDevelopmentPath=`pwd` path_to_the_maven_project
-```
+* __netbeans.jdkhome__ - path to the JDK, see dedicated section below
+* __netbeans.verbose__ - enables verbose extension logging
+* __netbeans.conflict.check__ - avoid conflicts with other Java extensions, see below
## Selecting the JDK
-The NbCode Java part needs to run on a JDK. The JDK is being searched in
+The user projects are built, run and debugged using the same JDK which runs the
+Apache NetBeans Language Server. The JDK is being searched in
following locations:
- `netbeans.jdkhome` setting (workspace then user settings)
@@ -103,7 +63,7 @@
- `JAVA_HOME` environment variable
- current system path
-As soon as one of the settings is changed, the NbCode Java part is restarted.
+As soon as one of the settings is changed, the Language Server is restarted.
## Conflicts with other Java Extensions
@@ -111,3 +71,9 @@
extension. To avoid duplicated code completion and other misleading clashes
the extension disables certain functionality known to cause problems. This
behavior can be disabled by setting `netbeans.conflict.check` setting to `false`.
+
+## Contributing
+
+Read [building instructions](BUILD.md) to help Apache community to
+improve the extension.
+
diff --git a/java/java.lsp.server/vscode/package.json b/java/java.lsp.server/vscode/package.json
index 963da4d..3517c59 100644
--- a/java/java.lsp.server/vscode/package.json
+++ b/java/java.lsp.server/vscode/package.json
@@ -1,10 +1,11 @@
{
"name": "apache-netbeans-java",
"displayName": "Apache NetBeans Language Server",
- "description": "An Apache NetBeans Language Server plugin for Visual Studio Code",
+ "description": "Apache NetBeans Language Server Extension for Visual Studio Code",
"author": "Apache NetBeans",
"license": "Apache 2.0",
"version": "0.1.0",
+ "preview": true,
"repository": {
"type": "git",
"url": "https://github.com/apache/netbeans"
