Skip to content

docs: fix typos and clarify a few things on the ide page #270

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
merged 3 commits into from
Oct 27, 2021
Merged

docs: fix typos and clarify a few things on the ide page #270

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4f4cf18
docs: fix typos and clarify a few things on the ide page
ckipp01 Oct 22, 2021
137f3a8
Change a wording in IDE a bit
romanowski Oct 27, 2021
94638de
docs: fixups on ide page
ckipp01 Oct 27, 2021
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
44 changes: 28 additions & 16 deletions website/docs/guides/ide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,22 +8,24 @@ IDE support is under development mainly because changes needs to be done in both
:::


Scala CLI currently integrates with build server using [BSP protocol](https://build-server-protocol.github.io/). At this moment Scala CLI is not automatically detected so we need to use [Build Server Discovery](https://build-server-protocol.github.io/docs/server-discovery.html) from BSP protocol, namely generate connection details file (`.bsp/scala-cli.json`).
Scala CLI currently Scala integrates with IDEs using [BSP protocol](https://build-server-protocol.github.io/). At this moment Scala CLI is not automatically detected so we need to use [Build Server Discovery](https://build-server-protocol.github.io/docs/server-discovery.html) from the BSP protocol. This is the main reason we create the BSP connection details file (`.bsp/scala-cli.json`) for your editor to pick up.

:::note
None of the following commands was run: `compile`, `run`, `test`, `setup-ide` or previously generated connection detail file was deleted, IDE will not use Scala CLI to configure workspace.

In such case, just run one of the commands above commands to recreate connection details file
If none of the following commands were ran: `compile`, `run`, `test`,
`setup-ide` or a `.bsp/scala-cli.json` file has yet to be created (or was deleted), your editor
won't pick up scala-cli as a build server. In that case, simply run one of the
those commands and the file will be created.
:::

Since Scala CLI has a command-line-first approach that is reflected in the IDE
integrations. By default, Scala CLI stores options passed to the last `compile`,
`run` or `test` commands and use those options to configure your IDE.

Since Scala CLI has a command-line-first approach and it is reflected in IDE integration. By default, Scala CLI stores options passed to last `compile`, `run` or `test` and use those options to configure IDE.

For more control we also expose [`setup-ide` command](../commands/setup-ide.md) that allows to fine tune options passed to IDE.
For more control we also expose a [`setup-ide` command](../commands/setup-ide.md) that allows to fine tune options passed to IDE.

Once `setup-ide` is used, Scala CLI does not update configuration based on latest command.
Once `setup-ide` is used, Scala CLI does not update configuration based on the latest command.

To enable automatic updates again, remove `.bsp` directory and run `compile`, `run` or `test` to recreate connection details file.
To enable automatic updates again, remove the `.bsp` directory and run `compile`, `run` or `test` to recreate the connection details file (`.bsp/scala-cli.json`).

For now non-local sources are supported. What are non-local sources? Gists, URLs or piped sources.

Expand All @@ -32,19 +34,28 @@ Scala CLI was tested with two main IDEs for Scala:
- [Metals](https://scalameta.org/metals/): LSP server for Scala used with [Visual Studio Code](https://code.visualstudio.com/), [Vim](https://www.vim.org/) and many other editors
- [Intelij Idea](https://www.jetbrains.com/idea/) with [Scala Plugin](https://confluence.jetbrains.com/display/SCA/Scala+Plugin+for+IntelliJ+IDEA?_ga=2.54176744.1963952405.1634470110-410935139.1631638301) installed

In ideal world, we would replace the rest of this Guide with something along the lines of: `Scala CLI works within IDEs above as you would expect` however mainly due to how fresh Scala CLI is and also due to our radical approach to the project structure using Scala CLI -powered project to your favourite IDE may not be as amazing as we would like.
In ideal world, we would replace the rest of this Guide with something along the
lines of: `Scala CLI works with all IDEs above as you would expect` however
mainly due to how fresh Scala CLI is and also due to our radical approach to the
project structure using a Scala CLI-powered projects with your favourite IDE may
not be as amazing as we would like to be.

Proper IDE integration is our top priority at this moment.
Proper IDE integration is our top priority at the moment.

## Metals

Once Metals pick up proper project structure then basic features like navigation, diagnostics or code completion should work.
Once Metals picks up proper project structure then basic features like navigation, diagnostics or code completion should work.

Currently release Metals (0.10.7) are not able to pick changes in build structure automatically and this even includes adding new source file. In order for Metals to pick up new files or changes in build structure 'Restart build server' action is needed.
The Current release Metals (0.10.8) is not able to pick changes in the build
structure automatically and this includes adding new source files. In order
for Metals to pick up new files or changes in build structure you'll need to
trigger the 'Restart build server' command.

Main classes and tests are at this moment to recognized in Metals.
Main classes and tests are at this moment not recognized in Metals.

Generally, mainly due to problems with keeping project structure up to date Metals can assists with writing code using Scala CLI, however it cannot be the source of true and we recommend falling back to command line in such cases.
Generally, mainly due to problems with keeping project structure up to date
Metals can assists with writing code while using Scala CLI, but it cannot be the
source of truth and we recommend falling back to command line in such cases.

## IntelliJ

Expand All @@ -54,4 +65,5 @@ With IntelliJ, we strongly suggested to placed your sources within a directory (

IntelliJ currently does not automatically pick up changes in project structure so any change in dependencies, compiler options etc. needs manual reload.

Similarly to Metals, currently we do not advise using IntelliJ as a source of truth. We recommend falling back to command line in such cases.
Similarly to Metals, we don't currently advise using Intellij as a source of
truth and we recommend falling back to command line in such cases.