|
| 1 | +# Scala 3 build layout |
| 2 | + |
| 3 | +This document explains how the Fukuii build works after the Scala 3 migration and what tooling is actually required inside the dev container or any local environment. |
| 4 | + |
| 5 | +## Toolchain |
| 6 | + |
| 7 | +| Tool | Version | Purpose | |
| 8 | +| --- | --- | --- | |
| 9 | +| JDK | 21 (Temurin) | Runtime/toolchain for Scala 3 and Pekko | |
| 10 | +| sbt | 1.10.7 | Single build driver (no nested builds) | |
| 11 | +| Scala | 3.3.4 (LTS) | Only Scala version compiled in this repo | |
| 12 | +| scalafmt / scalafix | 2.5.2 / 0.13.0 | Formatting and linting (invoked via sbt) | |
| 13 | +| protobuf (protoc) | >= 3.21 | Generates sources via `sbt-protoc` | |
| 14 | +| solc | 0.8.x | Solidity compiler for `solidityCompile` task | |
| 15 | +| Metals (VS Code) | 1.6.x | Language server only; not part of the published build | |
| 16 | + |
| 17 | +Everything else (Sonar, Zinc experiments, duplicate builds) has been removed so the build graph is deterministic. |
| 18 | + |
| 19 | +## Project graph |
| 20 | + |
| 21 | +``` |
| 22 | +root (node) |
| 23 | +├── bytes |
| 24 | +├── crypto (depends on bytes) |
| 25 | +├── rlp (depends on bytes) |
| 26 | +├── scalanet |
| 27 | +└── scalanet-discovery (depends on scalanet) |
| 28 | +``` |
| 29 | + |
| 30 | +Each sub-module inherits `commonSettings` defined in `build.sbt`, which sets: |
| 31 | + |
| 32 | +- Scala 3.3.4, fatal warnings disabled when `FUKUII_DEV=true` |
| 33 | +- shared scalac options and test settings |
| 34 | +- scalafix dependencies (organize-imports) |
| 35 | +- cross compilation configs for Integration/Evm/Rpc/Benchmark |
| 36 | + |
| 37 | +`project/Dependencies.scala` is the single source of truth for library versions (Pekko, Cats, Circe, RocksDB, etc.). Keep it updated there only; the main build file consumes those values exclusively. |
| 38 | + |
| 39 | +## sbt plugins in use |
| 40 | + |
| 41 | +Only the following plugins remain active in `project/plugins.sbt` because they are referenced by the Scala 3 build: |
| 42 | + |
| 43 | +- `sbt-buildinfo` – emits `BuildInfo.scala` |
| 44 | +- `sbt-javaagent` – wires Kanela for Pekko telemetry |
| 45 | +- `sbt-native-packager` + `sbt-assembly` – CLI and distribution packaging |
| 46 | +- `sbt-git`, `sbt-ci-release` – release metadata and tagging |
| 47 | +- `sbt-scalafmt`, `sbt-scalafix`, `sbt-scoverage`, `sbt-scapegoat`, `sbt-updates`, `sbt-api-mappings` |
| 48 | +- `sbt-protoc` – invoked via `scalapb.sbt` to compile protobuf overrides |
| 49 | + |
| 50 | +We intentionally removed auto-generated `metals.sbt` files and the recursive `project/project/...` tree to avoid the "fukuii-build-build-build" loops that broke Metals imports. Metals now runs against the regular build via BSP. |
| 51 | + |
| 52 | +## Dev container / Metals notes |
| 53 | + |
| 54 | +1. The dev container already installs sbt and JDK 21; you only need to run `sbt sbtVersion` once to warm the caches. |
| 55 | +2. `.gitignore` now blocks `project/metals.sbt` and the entire `project/project/` hierarchy. If Metals asks to create those files, let it—they will appear as untracked artifacts and should stay that way. |
| 56 | +3. To refresh Metals/BSP after dependency changes, run: |
| 57 | + |
| 58 | +```bash |
| 59 | +sbt "reload plugins" clean compile |
| 60 | +``` |
| 61 | + |
| 62 | +Metals will detect the updated `.bsp/sbt.json` and re-import automatically. |
| 63 | + |
| 64 | +## Usage checkpoints |
| 65 | + |
| 66 | +- Format all modules: `sbt formatAll` |
| 67 | +- Compile everything (Scala + protobuf + Solidity): `sbt compile-all` |
| 68 | +- Run essential tests (fast suite): `sbt testEssential` |
| 69 | +- Build the distribution artifact: `sbt dist` |
| 70 | + |
| 71 | +Running these commands successfully is the verification gate for any build change. Keep new tools or plugins off the critical path unless they are required by the Scala 3 codebase and documented here. |
0 commit comments