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

Add documentation for Scala 3 sandwiches #1008

Merged
merged 2 commits into from
Mar 23, 2021
Merged

Add documentation for Scala 3 sandwiches #1008

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cff4c87
Replace mapped cross versions with constant
adpi2 Mar 22, 2021
ae01607
Introduce for3Use2_13 and for3_13Use3
adpi2 Mar 22, 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
51 changes: 37 additions & 14 deletions src/reference/02-DetailTopics/01-Using-sbt/03-Cross-Build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -285,6 +285,29 @@ depending on the value of `crossPaths`.
Because (unlike Scala library) Scala compiler is not forward compatible among
the patch releases, compiler plugins should use `CrossVersion.full`.

#### Scala 3 specific cross-versions

In a Scala 3 project you can use Scala 2.13 libraries:

```scala
("a" % "b" % "1.0") cross CrossVersion.for3Use2_13
```

This is equivalent to using `%%` except it resolves the `_2.13` variant
of the library when `scalaVersion` is 3.x.y.

Conversely we have `CrossVersion.for2_13Use3` to use the `_3` variant of the
library when `scalaVersion` is 2.13.x:

```scala
("a" % "b" % "1.0") cross CrossVersion.for2_13Use3
```

**Warning for library authors:** It is generally not safe to publish
a Scala 3 library that depends on a Scala 2.13 library or vice-versa.
The reason is to prevent your end users from having two versions `x_2.13`
and `x_3` of the same x library in their classpath.

#### More about using cross-built libraries

You can have fine-grained control over the behavior for different Scala versions
Expand Down Expand Up @@ -317,31 +340,31 @@ distinguish variant but binary compatible Scala toolchain builds.
("a" % "b" % "1.0").cross(CrossVersion.patch)
```

This uses a custom function to determine the Scala version to use based
on the binary Scala version:
`CrossVersion.constant` fixes a constant value:

```scala
("a" % "b" % "1.0") cross CrossVersion.binaryMapped {
case "2.9.1" => "2.9.0" // remember that pre-2.10, binary=full
case "2.10" => "2.10.0" // useful if a%b was released with the old style
case x => x
}
("a" % "b" % "1.0") cross CrossVersion.constant("2.9.1")
```

This uses a custom function to determine the Scala version to use based
on the full Scala version:
It is equivalent to:

```scala
("a" % "b" % "1.0") cross CrossVersion.fullMapped {
case "2.9.1" => "2.9.0"
case x => x
}
"a" % "b_2.9.1" % "1.0"
```

A custom function is mainly used when cross-building and a dependency
A constant cross version is mainly used when cross-building and a dependency
isn't available for all Scala versions or it uses a different convention
than the default.

```scala
("a" % "b" % "1.0") cross CrossVersion.constant {
scalaVersion.value match {
case "2.9.1" => "2.9.0"
case x => x
}
}
```

#### Note about sbt-release

sbt-release implemented cross building support by copy-pasting sbt 0.13's `+` implementation,
Expand Down