enso/docs/sbt-cheatsheet.md
Pavel Marek 2ea2a57651
ydoc-server is a separate module (#10156)
- Remove remnants of deprecated Scala parser
- The following projects are now JPMS modules provided on system module-path (in components directory):
  - `ydoc-server`
  - `profiling-utils`
  - `syntax-rust-definition`
- The contents of the aforementioned modules are excluded from both `runner.jar` and `runtime.jar` fat jars.
- Suggestions are serialized and deserialized with our Persistance framework, rather than via the default Java OutputObjectWriter.
2024-06-07 12:56:42 +02:00

71 lines
2.9 KiB
Markdown

# sbt cheatsheet
This document contains various references and notes about sbt build definition.
One of the motivation for this document is that the
[official sbt documentation](https://www.scala-sbt.org/1.x/docs/index.html) is
not very informative.
### Resources
- [Official sbt documentation](https://www.scala-sbt.org/1.x/docs/index.html)
- [sbt.Keys](https://github.com/sbt/sbt/blob/1.10.x/main/src/main/scala/sbt/Keys.scala)
defines all the tasks and settings keys, including their documentation.
### Logging
- Get reference to the logger via `streams.value.log`.
- Log and error via `streams.value.log.error("My error")`
- Note that this will not cause the task to fail, this will only log an
`[error]` message. IF you want to fail a task, refer to
[Fail a task](#fail-a-task).
### Fail a task
- Simply throw a `java.lang.RuntimeException`.
- This will always work - it will crash the whole sbt process with the
RuntimeException. But it is not the official recommended way.
### Inspect tasks and settings
- `inspect tree project/assembly`
- This prints all the tasks and settings that will be executed when
`project / assembly` is run.
- It may be helpful to increase the width of the ASCI tree with
`set asciiGraphWidth := 150`.
- See `help inspect`.
## See all the transitive dependencies
- `print dependencyTree`
- This shows all the transitive dependencies for the default `Compile` scope.
- `print Test/dependencyTree`
- This show all the transitive dependencies for the `Test` scope.
### Debugging sbt tasks
- There is `--jvm-debug` cmd line option to sbt which allows to attach a
debugger to the sbt process.
- This option is not very handy, as you will still not be able to add a
breakpoint to various task definitions inside `build.sbt`, only to some
classes in the `project` directory. Moreover, once you run `reload`, the
debugging will not work for sure.
- This is because sbt internally compiles everything from `build.sbt` a
various anonymous classes and the debugger does not see their sources.
- It is better to either use `println` directly, or to use
`streams.value.log.info` to log messages.
### Exclude internal sbt project from a fat jar
- Fat jar for `fat-project` is assembled via the `fat-project / assembly` task.
- There is `fat-project / assembly / assemblyExcludedJars` setting which is of
type `Def.ClassPath`.
- To exclude internal `project` one must:
- Set `project / Compile / exportJars := true`. This ensures that
`project / Compile / exportedProducts` is a path to the jar.
- In `fat-project / assembly / assemblyExcludedJars` get the path to the
`project` jar via `project / Compile / exportedProducts`.
- Declare dependency on `project / Compile / packageBin` from
`fat-project / assembly`.
- Note that this is complicated because `assemblyExcludedJars` setting only
works if it points to an already existing jar file.