|
| 1 | +# Scala Bson library |
| 2 | + |
| 3 | +The `bson-scala` project provides Scala-idiomatic wrappers for the Java Bson library. |
| 4 | +It currently supports: **Scala 2.11**, **Scala 2.12**, **Scala 2.13**, and **Scala 3**. |
| 5 | + |
| 6 | +## Scala Versions |
| 7 | + |
| 8 | +Supported Scala versions and their exact version numbers are defined in [`gradle.properties`](../gradle.properties): |
| 9 | + |
| 10 | +- `supportedScalaVersions` — the list of supported Scala versions |
| 11 | +- `defaultScalaVersion` — the version used when no `-PscalaVersion` flag is provided (currently `2.13`) |
| 12 | + |
| 13 | +## Build Configuration |
| 14 | + |
| 15 | +The Scala source set configuration, compiler options, and dependency wiring are all handled in [`buildSrc/src/main/kotlin/project/scala.gradle.kts`](../buildSrc/src/main/kotlin/project/scala.gradle.kts). |
| 16 | + |
| 17 | +## Library Dependencies |
| 18 | + |
| 19 | +Scala library and test dependencies for each version are defined in [`gradle/libs.versions.toml`](../gradle/libs.versions.toml). Look for entries prefixed with `scala-` in the `[versions]`, `[libraries]`, and `[bundles]` sections. |
| 20 | + |
| 21 | +## Directory Layout |
| 22 | + |
| 23 | +Source code is organized into version-specific directories. |
| 24 | +Shared code goes in the common `scala` directory, while version-specific code goes in the appropriate directory: |
| 25 | + |
| 26 | +``` |
| 27 | +src/main/ |
| 28 | +├── scala/ # Shared code (all Scala versions) |
| 29 | +├── scala-2/ # Scala 2 only (2.11, 2.12 and 2.13) |
| 30 | +├── scala-2.13/ # Scala 2.13 only |
| 31 | +├── scala-2.13-/ # Scala 2.12 & 2.11 |
| 32 | +├── scala-3/ # Scala 3 only |
| 33 | +``` |
| 34 | + |
| 35 | +Test code also supports the same directory structure. |
| 36 | +The source sets for each Scala version are configured in [`buildSrc/src/main/kotlin/project/scala.gradle.kts`](../buildSrc/src/main/kotlin/project/scala.gradle.kts). |
| 37 | +When adding new code, place it in the most general directory that applies. Only use a version-specific directory when the code requires syntax or APIs unique to that version. |
| 38 | + |
| 39 | +## Code Formatting (Spotless) |
| 40 | + |
| 41 | +Spotless defaults to **Scala 2.13** formatting rules. This means code in shared directories (`scala/`, `scala-2/`) is formatted with the 2.13 scalafmt configuration. |
| 42 | + |
| 43 | +For **Scala 3 specific code**, the `bson-scala/build.gradle.kts` shows how to configure Spotless to use a Scala 3 scalafmt config. It targets only files in `**/scala-3/**` and uses a separate `config/scala/scalafmt-3.conf`: |
| 44 | + |
| 45 | +```kotlin |
| 46 | +if (scalaVersion.equals("3")) { |
| 47 | + spotless { |
| 48 | + scala { |
| 49 | + clearSteps() |
| 50 | + target("**/scala-3/**") |
| 51 | + scalafmt("3.10.7").configFile(rootProject.file("config/scala/scalafmt-3.conf")) |
| 52 | + } |
| 53 | + } |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +Use this pattern in other `build.gradle.kts` files if they also contain Scala 3 specific code. |
| 58 | + |
| 59 | +## Testing |
| 60 | + |
| 61 | +By default, tests run against Scala 2.13. To test against a specific Scala version, pass the `-PscalaVersion` flag: |
| 62 | + |
| 63 | +```bash |
| 64 | +# Test bson-scala with Scala 3 |
| 65 | +./gradlew :bson-scala:scalaCheck -PscalaVersion=3 |
| 66 | + |
| 67 | +# Test bson-scala with Scala 2.12 |
| 68 | +./gradlew :bson-scala:scalaCheck -PscalaVersion=2.12 |
| 69 | + |
| 70 | +# Test bson-scala with the default (2.13) |
| 71 | +./gradlew :bson-scala:scalaCheck |
| 72 | +``` |
0 commit comments