From a2e9e1cec1a6d77b15b29ac420ba896a9a568575 Mon Sep 17 00:00:00 2001 From: Eugene Yokota Date: Sat, 21 Sep 2024 17:28:40 -0400 Subject: [PATCH] Split IDE guide into separate recipes --- src/reference/SUMMARY.md | 3 + src/reference/guide/IDE.md | 245 +----------------- src/reference/recipes/hello-world.md | 4 +- src/reference/recipes/import-to-intellij.md | 129 +++++++++ src/reference/recipes/use-neovim.md | 83 ++++++ .../recipes/use-sbt-as-metals-build-server.md | 58 +++++ 6 files changed, 285 insertions(+), 237 deletions(-) create mode 100644 src/reference/recipes/import-to-intellij.md create mode 100644 src/reference/recipes/use-neovim.md create mode 100644 src/reference/recipes/use-sbt-as-metals-build-server.md diff --git a/src/reference/SUMMARY.md b/src/reference/SUMMARY.md index 7d13335a..8d559b36 100644 --- a/src/reference/SUMMARY.md +++ b/src/reference/SUMMARY.md @@ -24,5 +24,8 @@ - [Remote cache setup](reference/remote-cache-setup.md) - [Recipes]() - [Write hello world](recipes/hello-world.md) + - [Use sbt as Metals build server](recipes/use-sbt-as-metals-build-server.md) + - [Import to IntelliJ IDEA](recipes/import-to-intellij.md) + - [Use Neovim](recipes/use-neovim.md) - [Appendix]() - [Setup notes](setup-notes.md) diff --git a/src/reference/guide/IDE.md b/src/reference/guide/IDE.md index 0533a004..0b24c447 100644 --- a/src/reference/guide/IDE.md +++ b/src/reference/guide/IDE.md @@ -1,250 +1,25 @@ [metals]: https://scalameta.org/metals/ [intellij]: https://www.jetbrains.com/idea/ - [intellij-scala-plugin-2021-2]: https://blog.jetbrains.com/scala/2021/07/27/intellij-scala-plugin-2021-2/#Compiler-based_highlighting - [lsp]: https://microsoft.github.io/language-server-protocol/ [vscode]: https://code.visualstudio.com/ [neovim]: https://neovim.io/ - [bsp]: https://build-server-protocol.github.io/ - [vscode-debugging]: https://code.visualstudio.com/docs/editor/debugging - [intellij-debugging]: https://www.jetbrains.com/help/idea/debugging-code.html - [nvim-metals]: https://github.com/scalameta/nvim-metals - [lsp.lua]: https://github.com/scalameta/nvim-metals/discussions/39#discussion-82302 sbt with IDEs ============= While it's possible to code Scala with just an editor and sbt, most programmers today use an Integrated Development Environment, or IDE for short. -Two of the popular IDEs in Scala are [Metals][metals] and [IntelliJ IDEA][intellij], -and they both integrate with sbt builds. +Two of the popular IDEs in Scala are [Metals][metals] and [IntelliJ IDEA][intellij], and they both integrate with sbt builds. -- [Using sbt as Metals build server](#metals) -- [Importing to IntelliJ IDEA](#intellij-import) -- [Using sbt as IntelliJ IDEA build server](#intellij-bsp) -- [Using Neovim as Metals frontend](#nvim-metals) +A few of the advantages of using the IDEs are: - -### Using sbt as Metals build server +- Jump to definition +- Code completion based on static types +- Listing compilation errors, and jumping to the error positions +- Interactive debugging -[Metals][metals] is an open source _language server_ for Scala, which can -act as the backend for [VS Code][vscode] and other editors that support [LSP][lsp]. -Metals in turn supports different _build servers_ including sbt via the [Build Server Protocol][bsp] (BSP). +Here are a few recipes on how to configure the IDEs to integrate with sbt: -To use Metals on VS Code: - -1. Install Metals from Extensions tab:
- ![Metals](../files/metals0.png) -2. Open a directory containing a `build.sbt` file. -3. From the menubar, run View > Command Palette... (`Cmd-Shift-P` on macOS) "Metals: Switch build server", and select "sbt"
- ![Metals](../files/metals2.png) -4. Once the import process is complete, open a Scala file to see that code completion works:
- ![Metals](../files/metals3.png) - -Use the following setting to opt-out some of the subprojects from BSP. - -```scala -bspEnabled := false -``` - -When you make changes to the code and save them (`Cmd-S` on macOS), Metals will invoke sbt to do -the actual building work. - -#### Interactive debugging on VS Code - -1. Metals supports interactive debugging by setting break points in the code:
- ![Metals](../files/metals4.png) -2. Interactive debugging can be started by right-clicking on an unit test, and selecting "Debug Test." - When the test hits a break point, you can inspect the values of the variables:
- ![Metals](../files/metals5.png) - -See [Debugging][vscode-debugging] page on VS Code documentation for more details on how to navigate an interactive debugging session. - -#### Logging into sbt session - -While Metals uses sbt as the build server, we can also log into the same sbt session using a thin client. - -- From Terminal section, type in `sbt --client`
- ![Metals](../files/metals6.png) - -This lets you log into the sbt session Metals has started. In there you can call `testOnly` and other tasks with -the code already compiled. - - -### Importing to IntelliJ IDEA - -[IntelliJ IDEA][intellij] is an IDE created by JetBrains, and the Community Edition is open source under Apache v2 license. -IntelliJ integrates with many build tools, including sbt, to import the project. -This is a more traditional approach that might be more reliable than using BSP approach. - -To import a build to IntelliJ IDEA: - -1. Install Scala plugin on the Plugins tab:
- ![IntelliJ](../files/intellij1.png) -2. From Projects, open a directory containing a `build.sbt` file.
- ![IntelliJ](../files/intellij2.png) -3. Once the import process is complete, open a Scala file to see that code completion works. - -IntelliJ Scala plugin uses its own lightweight compilation engine to detect errors, which is fast but sometimes incorrect. Per [compiler-based highlighting][intellij-scala-plugin-2021-2], IntelliJ can be configured to use the Scala compiler for error highlighting. - -#### Interactive debugging with IntelliJ IDEA - -1. IntelliJ supports interactive debugging by setting break points in the code:
- ![IntelliJ](../files/intellij4.png) -2. Interactive debugging can be started by right-clicking on an unit test, and selecting "Debug '<test name>'." -　　Alternatively, you can click the green "run" icon on the left part of the editor near the unit test. - When the test hits a break point, you can inspect the values of the variables:
- ![IntelliJ](../files/intellij5.png) - -See [Debug Code][intellij-debugging] page on IntelliJ documentation for more details on how to navigate an interactive debugging session. - - -### Using sbt as IntelliJ IDEA build server (advanced) - -Importing the build to IntelliJ means that you're effectively using IntelliJ as the build tool and the compiler while you code (see also [compiler-based highlighting][intellij-scala-plugin-2021-2]). -While many users are happy with the experience, depending on the code base some of the compilation errors may be false, it may not work well with plugins that generate sources, and generally you might want to code with the identical build semantics as sbt. -Thankfully, modern IntelliJ supports alternative _build servers_ including sbt via the [Build Server Protocol][bsp] (BSP). - -The benefit of using BSP with IntelliJ is that you're using sbt to do the actual build work, so if you are the kind of programmer who had sbt session up on the side, this avoids double compilation. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Import to IntelliJBSP with IntelliJ
Reliability✅ Reliable behavior⚠️ Less mature. Might encounter UX issues.
Responsiveness✅⚠️
Correctness⚠️ Uses its own compiler for type checking, but can be configured to use scalac✅ Uses Zinc + Scala compiler for type checking
Generated source❌ Generated source requires resync✅
Build reuse❌ Using sbt side-by-side requires double build✅
- -To use sbt as build server on IntelliJ: - -1. Install Scala plugin on the Plugins tab. -2. To use the BSP approach, do not use Open button on the Project tab:
- ![IntelliJ](../files/intellij7.png) -3. From menubar, click New > "Project From Existing Sources", or Find Action (`Cmd-Shift-P` on macOS) and - type "Existing" to find "Import Project From Existing Sources":
- ![IntelliJ](../files/intellij8.png) -4. Open a `build.sbt` file. Select **BSP** when prompted:
- ![IntelliJ](../files/intellij9.png) -5. Select **sbt (recommended)** as the tool to import the BSP workspace:
- ![IntelliJ](../files/intellij10.png) -6. Once the import process is complete, open a Scala file to see that code completion works:
- ![IntelliJ](../files/intellij11.png) - -Use the following setting to opt-out some of the subprojects from BSP. - -```scala -bspEnabled := false -``` - -- Open Preferences, search BSP and check "build automatically on file save", and uncheck "export sbt projects to Bloop before import":
- ![IntelliJ](../files/intellij12.png) - -When you make changes to the code and save them (`Cmd-S` on macOS), IntelliJ will invoke sbt to do -the actual building work. - -See also Igal Tabachnik's [Using BSP effectively in IntelliJ and Scala](https://hmemcpy.com/2021/09/bsp-and-intellij/) for more details. - -#### Logging into sbt session - -We can also log into the existing sbt session using the thin client. - -- From Terminal section, type in `sbt --client` - ![IntelliJ](../files/intellij6.png) - -This lets you log into the sbt session IntelliJ has started. In there you can call `testOnly` and other tasks with -the code already compiled. - - -### Using Neovim as Metals frontend (advanced) - -[Neovim][neovim] is a modern fork of Vim that supports [LSP][lsp] out-of-box, -which means it can be configured as a frontend for Metals. - -Chris Kipp, who is a maintainer of Metals, created [nvim-metals][nvim-metals] plugin that provides comprehensive Metals support on Neovim. To install nvim-metals, create `lsp.lua` under `\$XDG_CONFIG_HOME/nvim/lua/` based on Chris's [lsp.lua][lsp.lua] and adjust to your preference. For example, comment out its plugins section and load the listed plugins using the plugin manager of your choice such as vim-plug. - -In `init.vim`, the file can be loaded as: - -``` -lua << END -require('lsp') -END -``` - -Per `lsp.lua`, `g:metals_status` should be displayed on the status line, which can be done using lualine.nvim etc. - -1. Next, open a Scala file in an sbt build using Neovim. -2. Run `:MetalsInstall` when prompted. -3. Run `:MetalsStartServer`. -4. If the status line is set up, you should see something like "Connecting to sbt" or "Indexing."
- -5. Code completion works when you're in Insert mode, and you can tab through the candidates:
- - -- A build is triggered upon saving changes, and compilation errors are displayed inline:
- - -#### Go to definition - -1. You can jump to definition of the symbol under cursor by using `gD` (exact keybinding can be customized):
- -2. Use `Ctrl-O` to return to the old buffer. - -#### Hover - -- To display the type information of the symbol under cursor, like hovering, use `K` in Normal mode:
- - -#### Listing diagnostics - -1. To list all compilation errors and warnings, use `aa`:
- -2. Since this is in the standard quickfix list, you can use the command such as `:cnext` and `:cprev` to nagivate through the errors and warnings. -3. To list just the errors, use `ae`. - -#### Interactive debugging with Neovim - -1. Thanks to nvim-dap, Neovim supports interactive debugging. Set break points in the code using `dt`:
- -2. Nagivate to a unit test, confirm that it's built by hovering (`K`), and then - "debug continue" (`dc`) to start a debugger. - Choose "1: RunOrTest" when prompted. -3. When the test hits a break point, you can inspect the values of the variables by debug hovering (`dK`):
- -4. "debug continue" (`dc`) again to end the session. - -See [nvim-metals][nvim-metals] regarding further details. - -#### Logging into sbt session - -We can also log into the existing sbt session using the thin client. - -1. In a new vim window type `:terminal` to start the built-in terminal. -2. Type in `sbt --client`
- - -Even though it's inside Neovim, tab completion etc works fine inside. +- [Use sbt as Metals build server](../recipes/use-sbt-as-metals-build-server.md) +- [Import to IntelliJ IDEA](../recipes/import-to-intellij.md) +- [Use Neovim](../recipes/use-neovim.md) diff --git a/src/reference/recipes/hello-world.md b/src/reference/recipes/hello-world.md index 6f3d0319..a572c552 100644 --- a/src/reference/recipes/hello-world.md +++ b/src/reference/recipes/hello-world.md @@ -1,8 +1,8 @@ How to write hello world ======================== -Problem -------- +Objective +--------- I want to write a hello world program in Scala, and run it. diff --git a/src/reference/recipes/import-to-intellij.md b/src/reference/recipes/import-to-intellij.md new file mode 100644 index 00000000..5b854b3c --- /dev/null +++ b/src/reference/recipes/import-to-intellij.md @@ -0,0 +1,129 @@ +Import to IntelliJ IDEA +======================= + + [intellij]: https://www.jetbrains.com/idea/ + [intellij-debugging]: https://www.jetbrains.com/help/idea/debugging-code.html + [intellij-scala-plugin-2021-2]: https://blog.jetbrains.com/scala/2021/07/27/intellij-scala-plugin-2021-2/#Compiler-based_highlighting + [bsp]: https://build-server-protocol.github.io/ + +```admonish warning +This is a draft documentation of sbt 2.x that is yet to be released. +This is a placeholder, copied from sbt 1.x. +``` + +Objective +--------- + +I want to import sbt build to IntelliJ IDEA. + +Steps +----- + +[IntelliJ IDEA][intellij] is an IDE created by JetBrains, and the Community Edition is open source under Apache v2 license. IntelliJ integrates with many build tools, including sbt, to import the project. + +To import a build to IntelliJ IDEA: + +1. Install Scala plugin on the Plugins tab:
+ ![IntelliJ](../files/intellij1.png) +2. From Projects, open a directory containing a `build.sbt` file.
+ ![IntelliJ](../files/intellij2.png) +3. Once the import process is complete, open a Scala file to see that code completion works. + +IntelliJ Scala plugin uses its own lightweight compilation engine to detect errors, which is fast but sometimes incorrect. Per [compiler-based highlighting][intellij-scala-plugin-2021-2], IntelliJ can be configured to use the Scala compiler for error highlighting. + +### Interactive debugging with IntelliJ IDEA + +1. IntelliJ supports interactive debugging by setting break points in the code:
+ ![IntelliJ](../files/intellij4.png) +2. Interactive debugging can be started by right-clicking on an unit test, and selecting "Debug '<test name>'." Alternatively, you can click the green "run" icon on the left part of the editor near the unit test. + When the test hits a break point, you can inspect the values of the variables:
+ ![IntelliJ](../files/intellij5.png) + +See [Debug Code][intellij-debugging] page on IntelliJ documentation for more details on how to navigate an interactive debugging session. + +Alternative +----------- + +### Using sbt as IntelliJ IDEA build server (advanced) + +Importing the build to IntelliJ means that you're effectively using IntelliJ as the build tool and the compiler while you code (see also [compiler-based highlighting][intellij-scala-plugin-2021-2]). +While many users are happy with the experience, depending on the code base some of the compilation errors may be false, it may not work well with plugins that generate sources, and generally you might want to code with the identical build semantics as sbt. +Thankfully, modern IntelliJ supports alternative _build servers_ including sbt via the [Build Server Protocol][bsp] (BSP). + +The benefit of using BSP with IntelliJ is that you're using sbt to do the actual build work, so if you are the kind of programmer who had sbt session up on the side, this avoids double compilation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Import to IntelliJBSP with IntelliJ
Reliability✅ Reliable behavior⚠️ Less mature. Might encounter UX issues.
Responsiveness✅⚠️
Correctness⚠️ Uses its own compiler for type checking, but can be configured to use scalac✅ Uses Zinc + Scala compiler for type checking
Generated source❌ Generated source requires resync✅
Build reuse❌ Using sbt side-by-side requires double build✅
+ +To use sbt as build server on IntelliJ: + +1. Install Scala plugin on the Plugins tab. +2. To use the BSP approach, do not use Open button on the Project tab:
+ ![IntelliJ](../files/intellij7.png) +3. From menubar, click New > "Project From Existing Sources", or Find Action (`Cmd-Shift-P` on macOS) and + type "Existing" to find "Import Project From Existing Sources":
+ ![IntelliJ](../files/intellij8.png) +4. Open a `build.sbt` file. Select **BSP** when prompted:
+ ![IntelliJ](../files/intellij9.png) +5. Select **sbt (recommended)** as the tool to import the BSP workspace:
+ ![IntelliJ](../files/intellij10.png) +6. Once the import process is complete, open a Scala file to see that code completion works:
+ ![IntelliJ](../files/intellij11.png) + +Use the following setting to opt-out some of the subprojects from BSP. + +```scala +bspEnabled := false +``` + +- Open Preferences, search BSP and check "build automatically on file save", and uncheck "export sbt projects to Bloop before import":
+ ![IntelliJ](../files/intellij12.png) + +When you make changes to the code and save them (`Cmd-S` on macOS), IntelliJ will invoke sbt to do +the actual building work. + +See also Igal Tabachnik's [Using BSP effectively in IntelliJ and Scala](https://hmemcpy.com/2021/09/bsp-and-intellij/) for more details. + +#### Logging into sbt session + +We can also log into the existing sbt session using the thin client. + +- From Terminal section, type in `sbt --client` + ![IntelliJ](../files/intellij6.png) + +This lets you log into the sbt session IntelliJ has started. In there you can call `testOnly` and other tasks with +the code already compiled. + + + + diff --git a/src/reference/recipes/use-neovim.md b/src/reference/recipes/use-neovim.md new file mode 100644 index 00000000..77dc9b2c --- /dev/null +++ b/src/reference/recipes/use-neovim.md @@ -0,0 +1,83 @@ +Use Neovim +========== + + [metals]: https://scalameta.org/metals/ + [nvim-metals]: https://github.com/scalameta/nvim-metals + [lsp.lua]: https://github.com/scalameta/nvim-metals/discussions/39#discussion-82302 + +```admonish warning +This is a draft documentation of sbt 2.x that is yet to be released. +This is a placeholder, copied from sbt 1.x. +``` + +Objective +--------- + +I want to use Metals on Neovim with sbt as the build server. + +Steps +----- + +Chris Kipp, who is a maintainer of Metals, created [nvim-metals][nvim-metals] plugin that provides comprehensive Metals support on Neovim. To install nvim-metals, create `lsp.lua` under `$XDG_CONFIG_HOME/nvim/lua/` based on Chris's [lsp.lua][lsp.lua] and adjust to your preference. For example, comment out its plugins section and load the listed plugins using the plugin manager of your choice such as vim-plug. + +In `init.vim`, the file can be loaded as: + +```lua +lua << END +require('lsp') +END +``` + +Per `lsp.lua`, `g:metals_status` should be displayed on the status line, which can be done using lualine.nvim etc. + +1. Next, open a Scala file in an sbt build using Neovim. +2. Run `:MetalsInstall` when prompted. +3. Run `:MetalsStartServer`. +4. If the status line is set up, you should see something like "Connecting to sbt" or "Indexing."
+ +5. Code completion works when you're in Insert mode, and you can tab through the candidates:
+ + +- A build is triggered upon saving changes, and compilation errors are displayed inline:
+ + +#### Go to definition + +1. You can jump to definition of the symbol under cursor by using `gD` (exact keybinding can be customized):
+ +2. Use `Ctrl-O` to return to the old buffer. + +#### Hover + +- To display the type information of the symbol under cursor, like hovering, use `K` in Normal mode:
+ + +#### Listing diagnostics + +1. To list all compilation errors and warnings, use `aa`:
+ +2. Since this is in the standard quickfix list, you can use the command such as `:cnext` and `:cprev` to nagivate through the errors and warnings. +3. To list just the errors, use `ae`. + +#### Interactive debugging with Neovim + +1. Thanks to nvim-dap, Neovim supports interactive debugging. Set break points in the code using `dt`:
+ +2. Nagivate to a unit test, confirm that it's built by hovering (`K`), and then + "debug continue" (`dc`) to start a debugger. + Choose "1: RunOrTest" when prompted. +3. When the test hits a break point, you can inspect the values of the variables by debug hovering (`dK`):
+ +4. "debug continue" (`dc`) again to end the session. + +See [nvim-metals][nvim-metals] regarding further details. + +#### Logging into sbt session + +We can also log into the existing sbt session using the thin client. + +1. In a new vim window type `:terminal` to start the built-in terminal. +2. Type in `sbt --client`
+ + +Even though it's inside Neovim, tab completion etc works fine inside. diff --git a/src/reference/recipes/use-sbt-as-metals-build-server.md b/src/reference/recipes/use-sbt-as-metals-build-server.md new file mode 100644 index 00000000..b1b2be08 --- /dev/null +++ b/src/reference/recipes/use-sbt-as-metals-build-server.md @@ -0,0 +1,58 @@ +Use sbt as Metals build server +============================== + + [metals]: https://scalameta.org/metals/ + [vscode-debugging]: https://code.visualstudio.com/docs/editor/debugging + + +```admonish warning +This is a draft documentation of sbt 2.x that is yet to be released. +This is a placeholder, copied from sbt 1.x. +``` + +Objective +--------- + +I want to use [Metals][metals] on VS Code with sbt as the build server. + +Steps +----- + +To use Metals on VS Code: + +1. Install Metals from Extensions tab:
+ ![Metals](../files/metals0.png) +2. Open a directory containing a `build.sbt` file. +3. From the menubar, run View > Command Palette... (`Cmd-Shift-P` on macOS) "Metals: Switch build server", and select "sbt"
+ ![Metals](../files/metals2.png) +4. Once the import process is complete, open a Scala file to see that code completion works:
+ ![Metals](../files/metals3.png) + +Use the following setting to opt-out some of the subprojects from BSP. + +```scala +bspEnabled := false +``` + +When you make changes to the code and save them (`Cmd-S` on macOS), Metals will invoke sbt to do +the actual building work. + +#### Interactive debugging on VS Code + +1. Metals supports interactive debugging by setting break points in the code:
+ ![Metals](../files/metals4.png) +2. Interactive debugging can be started by right-clicking on an unit test, and selecting "Debug Test." + When the test hits a break point, you can inspect the values of the variables:
+ ![Metals](../files/metals5.png) + +See [Debugging][vscode-debugging] page on VS Code documentation for more details on how to navigate an interactive debugging session. + +#### Logging into sbt session + +While Metals uses sbt as the build server, we can also log into the same sbt session using a thin client. + +- From Terminal section, type in `sbt --client`
+ ![Metals](../files/metals6.png) + +This lets you log into the sbt session Metals has started. In there you can call `testOnly` and other tasks with +the code already compiled.