Skip to content
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

sbt-scalafix doc updates #1572

Merged
merged 3 commits into from
Apr 3, 2022
Merged

sbt-scalafix doc updates #1572

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d061196
ScalafixTestkitPlugin now brings scalafix-testkit
bjaglin Feb 10, 2022
5ab2192
advertize amm/cs-friendly syntax for dependency:
bjaglin Feb 10, 2022
f788479
support sbt 1.3.x and later only
bjaglin Mar 24, 2022
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
5 changes: 0 additions & 5 deletions docs/developers/local-rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,11 +185,6 @@ semantic rules.
+ )
+lazy val `scalafix-tests` = (project in file("scalafix/tests"))
+ .settings(
+ libraryDependencies +=
+ "ch.epfl.scala" %
+ "scalafix-testkit" %
+ _root_.scalafix.sbt.BuildInfo.scalafixVersion %
+ Test cross CrossVersion.full,
+ scalafixTestkitOutputSourceDirectories :=
+ (`scalafix-output` / Compile / sourceDirectories).value,
+ scalafixTestkitInputSourceDirectories :=
Expand Down
2 changes: 1 addition & 1 deletion docs/developers/tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -711,7 +711,7 @@ Once published, users can run your rule with the following sbt command.

```sh
// sbt shell
> scalafix dependency:NamedLiteralArguments@ch.epfl.scala:named-literal-arguments:VERSION
> scalafix dependency:NamedLiteralArguments@ch.epfl.scala::named-literal-arguments:VERSION
```

To permanently install the rule for a build, users can add the dependency to
Expand Down
30 changes: 15 additions & 15 deletions docs/rules/community-rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,11 @@ rewriting the code when possible.

| Repository | Artifact | Description |
| - | - | - |
[ghostbuster91/scalafix-unified](https://github.com/ghostbuster91/scalafix-unified) | `io.github.ghostbuster91.scalafix-unified:unified` | Set of opinionated rules to unify your codebase
[jatcwang/scalafix-named-params](https://github.com/jatcwang/scalafix-named-params) | `com.github.jatcwang:scalafix-named-params` | Add named parameters for your constructor and method calls
[liancheng/scalafix-organize-imports](https://github.com/liancheng/scalafix-organize-imports) | `com.github.liancheng:organize-imports` | Help you organize Scala import statements
[vovapolu/scaluzzi](https://github.com/vovapolu/scaluzzi) | `com.github.vovapolu:scaluzzi` | Ensure a subset of [scalazzi](http://yowconference.com.au/slides/yowwest2014/Morris-ParametricityTypesDocumentationCodeReadability.pdf)
[xuwei-k/scalafix-rules](https://github.com/xuwei-k/scalafix-rules) | `com.github.xuwei-k:scalafix-rules` | Avoid ambiguous or redundant Scala syntax & features
[ghostbuster91/scalafix-unified](https://github.com/ghostbuster91/scalafix-unified) | `io.github.ghostbuster91.scalafix-unified::unified` | Set of opinionated rules to unify your codebase
[jatcwang/scalafix-named-params](https://github.com/jatcwang/scalafix-named-params) | `com.github.jatcwang::scalafix-named-params` | Add named parameters for your constructor and method calls
[liancheng/scalafix-organize-imports](https://github.com/liancheng/scalafix-organize-imports) | `com.github.liancheng::organize-imports` | Help you organize Scala import statements
[vovapolu/scaluzzi](https://github.com/vovapolu/scaluzzi) | `com.github.vovapolu::scaluzzi` | Ensure a subset of [scalazzi](http://yowconference.com.au/slides/yowwest2014/Morris-ParametricityTypesDocumentationCodeReadability.pdf)
[xuwei-k/scalafix-rules](https://github.com/xuwei-k/scalafix-rules) | `com.github.xuwei-k::scalafix-rules` | Avoid ambiguous or redundant Scala syntax & features

## Migration rules

Expand All @@ -37,12 +37,12 @@ for the service.

| Repository | Artifact | Description |
| - | - | - |
[ohze/scala-rewrites](https://github.com/ohze/scala-rewrites) | `com.sandinh:scala-rewrites` | Rewrites for Scala
[OlegYch/enumeratum-scalafix](https://github.com/OlegYch/enumeratum-scalafix) | `io.github.olegych:enumeratum-scalafix` | Replace `scala.Enumeration` with enumeratum
[scala/scala-collection-compat](https://github.com/scala/scala-collection-compat) | `org.scala-lang.modules:scala-collection-migrations` | Rewrite upgrades to the 2.13 collections
[scala/scala-rewrites](https://github.com/scala/scala-rewrites) | `org.scala-lang:scala-rewrites` | Rewrites for Scala
[xuwei-k/play-ws-scalafix](https://github.com/xuwei-k/play-ws-scalafix) | `com.github.xuwei-k:play-ws-scalafix` | Migrate to play-ws-standalone
[xuwei-k/replace-symbol-literals](https://github.com/xuwei-k/replace-symbol-literals) | `com.github.xuwei-k:replace-symbol-literals` | Replace deprecated scala.Symbol literals `s/'foo/Symbol("foo")/`
[ohze/scala-rewrites](https://github.com/ohze/scala-rewrites) | `com.sandinh::scala-rewrites` | Rewrites for Scala
[OlegYch/enumeratum-scalafix](https://github.com/OlegYch/enumeratum-scalafix) | `io.github.olegych::enumeratum-scalafix` | Replace `scala.Enumeration` with enumeratum
[scala/scala-collection-compat](https://github.com/scala/scala-collection-compat) | `org.scala-lang.modules::scala-collection-migrations` | Rewrite upgrades to the 2.13 collections
[scala/scala-rewrites](https://github.com/scala/scala-rewrites) | `org.scala-lang::scala-rewrites` | Rewrites for Scala
[xuwei-k/play-ws-scalafix](https://github.com/xuwei-k/play-ws-scalafix) | `com.github.xuwei-k::play-ws-scalafix` | Migrate to play-ws-standalone
[xuwei-k/replace-symbol-literals](https://github.com/xuwei-k/replace-symbol-literals) | `com.github.xuwei-k::replace-symbol-literals` | Replace deprecated scala.Symbol literals `s/'foo/Symbol("foo")/`

## Code generation rules

Expand All @@ -51,7 +51,7 @@ by taking a route similar, yet parallel to macros.

| Repository | Artifact | Description |
| - | - | - |
[earldouglas/linear-scala](https://github.com/earldouglas/linear-scala) | `com.earldouglas:linear-scala-scalafix` | Add support for linear types in Scala
[rtimush/zio-magic-comments](https://github.com/rtimush/zio-magic-comments) | `com.timushev:zio-magic-comments` | Add explanatory graphs as comments to zio-magic methods
[sake92/kalem](https://github.com/sake92/kalem) | `ba.sake:kalem-rules` | Generate `with*` methods for classes
[typelevel/simulacrum-scalafix](https://github.com/typelevel/simulacrum-scalafix) | `org.typelevel:simulacrum-scalafix-annotations` | Simulacrum as Scalafix rules
[earldouglas/linear-scala](https://github.com/earldouglas/linear-scala) | `com.earldouglas::linear-scala-scalafix` | Add support for linear types in Scala
[rtimush/zio-magic-comments](https://github.com/rtimush/zio-magic-comments) | `com.timushev::zio-magic-comments` | Add explanatory graphs as comments to zio-magic methods
[sake92/kalem](https://github.com/sake92/kalem) | `ba.sake::kalem-rules` | Generate `with*` methods for classes
[typelevel/simulacrum-scalafix](https://github.com/typelevel/simulacrum-scalafix) | `org.typelevel::simulacrum-scalafix-annotations` | Simulacrum as Scalafix rules
4 changes: 2 additions & 2 deletions docs/rules/external-rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,12 @@ One method is to run rule dynamically with the following sbt command.

```sh
// sbt shell
> scalafix dependency:RULE@GROUP:ARTIFACT:VERSION
> scalafix dependency:RULE@GROUP::ARTIFACT:VERSION
```

Each parts stands for the following.
* `RULE`: A name of rule to be performed.
* `@GROUP:ARTIFACT:VERSION`: An id to specify a dependency containing rules.
* `@GROUP::ARTIFACT:VERSION`: An id to specify a dependency containing rules.

To permanently install the rule for a build, users can add the dependency to
`build.sbt` by updating `ThisBuild / scalafixDependencies`.
Expand Down
67 changes: 20 additions & 47 deletions docs/users/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@ pull request is tested on both Linux and Windows.
@SCALA211@, @SCALA212@ and @SCALA213@.

**Scala 3.x**: Scala 3 support is experimental and many built-in rules are not
supported. Make sure you follow the "sbt 1.3x and newer" instructions below.
supported.

## sbt

Start by installing the sbt 1.x plugin in `project/plugins.sbt`
Start by installing the sbt 1.3+ plugin in `project/plugins.sbt`

```scala
// project/plugins.sbt
Expand Down Expand Up @@ -74,8 +74,9 @@ the Scala compiler option `-Ywarn-unused-import` (or `-Wunused:imports` in

```diff
/*
* build.sbt, for sbt 1.3x and newer
* build.sbt
* SemanticDB is enabled for all sub-projects via ThisBuild scope.
* https://www.scala-sbt.org/1.x/docs/sbt-1.3-Release-Notes.html#SemanticDB+support
*/
inThisBuild(
List(
Expand All @@ -92,8 +93,9 @@ the Scala compiler option `-Ywarn-unused-import` (or `-Wunused:imports` in

```diff
/*
* build.sbt, for sbt 1.3x and newer
* build.sbt
* SemanticDB is enabled only for a sub-project.
* https://www.scala-sbt.org/1.x/docs/sbt-1.3-Release-Notes.html#SemanticDB+support
*/
lazy val myproject = project.settings(
scalaVersion := "@SCALA212@", // @SCALA211@, @SCALA213@, or 3.x
Expand All @@ -103,18 +105,6 @@ the Scala compiler option `-Ywarn-unused-import` (or `-Wunused:imports` in
)
```

```diff
// build.sbt, for sbt 1.2.x and older (Scala 2.x only)
lazy val myproject = project.settings(
scalaVersion := "@SCALA212@", // @SCALA211@, or @SCALA213@
+ addCompilerPlugin(scalafixSemanticdb), // enable SemanticDB
scalacOptions ++= List(
+ "-Yrangepos", // required by SemanticDB compiler plugin
+ "-Ywarn-unused-import" // required by `RemoveUnused` rule
)
)
```

For `project/*.scala` files, add
`import scalafix.sbt.ScalafixPlugin.autoImport._` to the top of the file to
resolve `scalafixSemanticdb`.
Expand Down Expand Up @@ -331,8 +321,7 @@ processed.

### Customize SemanticDB output directory

When using the `semanticdbEnabled` key with sbt 1.3x and newer, the
`*.semanticdb` files are available in the directory referenced by the
The `*.semanticdb` files are available in the directory referenced by the
`semanticdbTargetRoot` key, which defaults to `target/scala-x/meta`.

You can override this default to emit `*.semanticdb` files in a custom
Expand Down Expand Up @@ -382,44 +371,28 @@ session.
> scalafix RemoveUnused
```

The `scalafixEnable` command automatically runs
`addCompilerPlugin(scalafixSemanticdb)` and `scalacOptions += "-Yrangepos"` for
all eligible projects in the builds. The change in Scala compiler options means
the project needs to be re-built on the next `compile`.
The `scalafixEnable` command automatically enables semanticdb output and adds
`scalacOptions += "-Yrangepos"` for all eligible projects in the builds. The
change in Scala compiler options means the project may need to be re-built on
the next `compile`.

> The `scalafixEnable` command must be re-executed after every `reload` and when
> sbt shell is exited.

### Optionally enable SemanticDB
Copy link
Collaborator Author

@bjaglin bjaglin Mar 24, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed this as it's now fairly standard since https://www.scala-sbt.org/1.x/docs/sbt-1.3-Release-Notes.html#SemanticDB+support (link added at the top of the page)


It's possible to optionally enable the SemanticDB compiler plugin by updating
build.sbt like this:

```diff
// build.sbt
- addCompilerPlugin(scalafixSemanticdb)
- scalacOptions += "-Yrangepos"
+ def shouldEnableSemanticdb: Boolean = ??? // fill this part
+ libraryDependencies ++= {
+ if (shouldEnableSemanticdb) List(compilerPlugin(scalafixSemanticdb))
+ else List()
+ }
+ scalacOptions ++= {
+ if (shouldEnableSemanticdb) List("-Yrangepos")
+ else List()
+ }
```

### Verify installation

To verify that the SemanticDB compiler plugin is enabled, check that the
settings `scalacOptions` and `libraryDependencies` contain the values below.
settings `scalacOptions` and `allDependencies` contain the values below.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/sbt/sbt/blob/204bedac9cd474a2edc80e4835a591606338ea18/main/src/main/scala/sbt/plugins/SemanticdbPlugin.scala#L37-L43


```sh
> show scalacOptions
[info] * -Yrangepos
> show libraryDependencies
[info] * org.scalameta:semanticdb-scalac:@SCALA212@:plugin->default(compile)
> show Compile / scalacOptions
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

scalacenter/sbt-scalafix#203

...
[info] * List(..., -Yrangepos, ...)
...
> show allDependencies
...
[info] List(..., org.scalameta:semanticdb-scalac:@SCALA212@:plugin->default(compile), ...)
...
```

### Example project
Expand Down