From 8566e1c84d48e5a85428f1ad77418bb8aa72eb9a Mon Sep 17 00:00:00 2001 From: Lucas Date: Thu, 13 Apr 2023 17:40:53 +0200 Subject: [PATCH] Remove contributing section from docs All pages in the "Contribute" section have been added or not (if the information was already present). The purpose of this PR is to gather in one place the information in order not to lose the user wishing to get information in the documentation. --- docs/_docs/contributing/checklist.sh | 60 --- .../contributing/contribute-knowledge.md | 12 - docs/_docs/contributing/debug-tests.md | 124 ------ docs/_docs/contributing/debugging.md | 366 ------------------ docs/_docs/contributing/getting-started.md | 100 ----- docs/_docs/contributing/index.md | 4 - docs/_docs/contributing/procedures/index.md | 4 - docs/_docs/contributing/procedures/release.md | 155 -------- docs/_docs/contributing/procedures/vulpix.md | 35 -- docs/_docs/contributing/scala2-vs-scala3.md | 43 -- docs/_docs/contributing/testing.md | 207 ---------- docs/_docs/contributing/tools/ide.md | 37 -- docs/_docs/contributing/tools/index.md | 4 - docs/_docs/contributing/tools/mill.md | 21 - docs/_docs/contributing/tools/scalafix.md | 20 - docs/_docs/contributing/workflow.md | 110 ------ 16 files changed, 1302 deletions(-) delete mode 100755 docs/_docs/contributing/checklist.sh delete mode 100644 docs/_docs/contributing/contribute-knowledge.md delete mode 100644 docs/_docs/contributing/debug-tests.md delete mode 100644 docs/_docs/contributing/debugging.md delete mode 100644 docs/_docs/contributing/getting-started.md delete mode 100644 docs/_docs/contributing/index.md delete mode 100644 docs/_docs/contributing/procedures/index.md delete mode 100644 docs/_docs/contributing/procedures/release.md delete mode 100644 docs/_docs/contributing/procedures/vulpix.md delete mode 100644 docs/_docs/contributing/scala2-vs-scala3.md delete mode 100644 docs/_docs/contributing/testing.md delete mode 100644 docs/_docs/contributing/tools/ide.md delete mode 100644 docs/_docs/contributing/tools/index.md delete mode 100644 docs/_docs/contributing/tools/mill.md delete mode 100644 docs/_docs/contributing/tools/scalafix.md delete mode 100644 docs/_docs/contributing/workflow.md diff --git a/docs/_docs/contributing/checklist.sh b/docs/_docs/contributing/checklist.sh deleted file mode 100755 index d3cfe70b4e21..000000000000 --- a/docs/_docs/contributing/checklist.sh +++ /dev/null @@ -1,60 +0,0 @@ -# #!/usr/bin/env bash -stable=$1 - -rc="$(($stable+1))" -next="$(($rc+1))" - -stable_version="0.$stable.0" -rc_version="0.$rc.0-RC1" -next_version="0.$next.0" -stable_branch="0.$stable.x" -rc_branch="0.$rc.x" - -LIST='- [ ] Publish artifacts to Maven via CI - - [ ] On branch ``, set `baseVersion` to `` and `git tag` it as ``. This will publish artefacts to Sonatype and GitHub Release - - [ ] Merge branch `` into `master` to guarantee that all of the `` commits are propagated to `master` - - [ ] Look at the milestone of the RC version being released. Move all the open issues from it to the next milestone. - - [ ] Create branch `` from `master` - - [ ] On ``, set `baseVersion` to `` and `git tag` it as ``. This will publish artefacts to Sonatype and GitHub Release. - - [ ] On `master`, set `baseVersion` to `` -- [ ] Update `scalaVersion` (and, if applicable, the `sbt-dotty` version) in the Dotty ecosystem projects - - [ ] https://github.com/scala/scala3-example-project [![Build Status](https://travis-ci.org/scala/scala3-example-project.svg?branch=master)](https://travis-ci.org/scala/scala3-example-project) - - [ ] Committed to `master` - - [ ] https://github.com/scala/scala3-example-project/tree/mill - - [ ] https://github.com/scala/scala3.g8 [![Build Status](https://travis-ci.org/scala/scala3.g8.svg?branch=master)](https://travis-ci.org/scala/scala3.g8/) - - [ ] Committed to `master` - - [ ] https://github.com/scala/scala3-cross.g8 [![Build Status](https://travis-ci.org/scala/scala3-cross.g8.svg?branch=master)](https://travis-ci.org/scala/scala3-cross.g8/) - - [ ] Committed to `master` - - [ ] https://github.com/lampepfl/homebrew-brew [![Build Status](https://travis-ci.org/lampepfl/homebrew-brew.svg?branch=master)](https://travis-ci.org/lampepfl/homebrew-brew) - - [ ] Committed to `master` - - SHA256 sum for the artifact: `wget -q -O- https://github.com/lampepfl/dotty/releases/download//sha256sum.txt | grep ".tar.gz"` - - [ ] https://github.com/lampepfl/packtest [![Build Status](https://travis-ci.org/lampepfl/packtest.svg?branch=master)](https://travis-ci.org/lampepfl/packtest) - - [ ] Committed to `master` - - [ ] https://github.com/lampepfl/xml-interpolator [![Build Status](https://travis-ci.org/lampepfl/xml-interpolator.svg?branch=master)](https://travis-ci.org/lampepfl/xml-interpolator) - - [ ] PR submitted - - [ ] PR merged - - [ ] https://github.com/scalacenter/scastie - - [ ] PR submitted - - [ ] PR merged - - [ ] https://scastie.scala-lang.org/ -> Build Settings -> Dotty mentions `` - - [ ] Dotty reference compiler [![Build Status](http://dotty-ci.epfl.ch/api/badges/lampepfl/dotty/status.svg)](http://dotty-ci.epfl.ch/lampepfl/dotty) - - [ ] PR submitted - - [ ] PR merged - - [ ] Scalac [![Build Status](https://travis-ci.org/scala/scala.svg?branch=2.13.x)](https://travis-ci.org/scala/scala) - - [ ] PR submitted - - [ ] PR merged -- [ ] Announce the release - - [ ] Publish releases for the RC and stable versions on GitHub Releases - - [ ] Publish Blog Post on dotty.epfl.ch - - [ ] Make an announcement thread on https://contributors.scala-lang.org - - [ ] Tweet the announcement blog post on https://twitter.com/scala_lang - - [ ] Run workflow releases CI to publish scala on SDKMAN - https://github.com/lampepfl/dotty/actions/workflows/releases.yml - -[Instructions on how to release](https://dotty.epfl.ch/docs/contributing/release.html)' - -echo "$LIST" |\ - sed "s//$stable_version/g" |\ - sed "s//$rc_version/g" |\ - sed "s//$next_version/g" |\ - sed "s//$stable_branch/g" |\ - sed "s//$rc_branch/g" diff --git a/docs/_docs/contributing/contribute-knowledge.md b/docs/_docs/contributing/contribute-knowledge.md deleted file mode 100644 index 7164774ac1df..000000000000 --- a/docs/_docs/contributing/contribute-knowledge.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: doc-page -title: Contributing Knowledge ---- - -# Contribute Internals-related Knowledge -If you know anything useful at all about Dotty, feel free to log this knowledge: - -- [📜Log the Knowledge](https://github.com/lampepfl/dotty-knowledge/issues/new) -- [🎓More about Logging the Knowledge](https://github.com/lampepfl/dotty-knowledge/blob/master/README.md) - -In short, no need to make it pretty, particularly human-readable or give it a particular structure. Just dump the knowledge you have and we'll take it from there. \ No newline at end of file diff --git a/docs/_docs/contributing/debug-tests.md b/docs/_docs/contributing/debug-tests.md deleted file mode 100644 index a38338fcc745..000000000000 --- a/docs/_docs/contributing/debug-tests.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -layout: doc-page -title: Tests for Debuggability ---- - -## Tools Requires - -- JDB -- expect - -Both are usually pre-installed on macOS and linux distributions. - -## Debug Manually with JDB - -First, compile the file `tests/debug/while.scala`: - -```shell -$ scalac tests/debug/while.scala -``` - -Second, run the compiled class with debugging enabled (suppose the main class is `Test`): - -```shell -$ scala -d Test -``` - -Third, start JDB: - -```shell -$ jdb -attach 5005 -sourcepath tests/debug/ -``` - -You can run `help` for commands that supported by JDB. - -## Debug Automatically with Expect - -### 1. Annotate the source code with debug information. - -Following file (`tests/debug/while.scala`) is an example of annotated source code: - -```scala -object Test { - - def main(args: Array[String]): Unit = { - var a = 1 + 2 - a = a + 3 - a = 4 + 5 // [break] [step: while] - - while (a * 8 < 100) { // [step: a += 1] - a += 1 // [step: while] [cont: print] - } - - print(a) // [break] [cont] - } -} -``` - -The debugging information is annotated as comments to the code in brackets: - -```scala -val x = f(3) // [break] [next: line=5] -val y = 5 -``` - -1. A JDB command must be wrapped in brackets, like `[step]`. All JDB commands can be used. -2. To check output of JDB for a command, use `[cmd: expect]`. -3. If `expect` is wrapped in double quotes, regex is supported. -4. Break commands are collected and set globally. -5. Other commands will be send to jdb in the order they appear in the source file - -Note that JDB uses line number starts from 1. - -### 2. Generate Expect File - -Now we can run the following command to generate an expect file: - -```shell -compiler/test/debug/Gen tests/debug/while.scala > robot -``` - -### 3. Run the Test - -First, compile the file `tests/debug/while.scala`: - -```shell -$ scalac tests/debug/while.scala -``` - -Second, run the compiled class with debugging enabled: - -```shell -$ scala -d Test -``` - -Finally, run the expect script: - -```shell -expect robot -``` - -## Other Tips - -### Adding a New Test - -Just put the annotated source file under `tests/debug/`, it will be automatically -run by the test infrastructure. - -### Run All Debug Tests - -```shell -./compiler/test/debug/test -``` - -### Debug a Debug Test - -If there is any problem with a debug test, first check if the problematic -test work correctly with JDB without automation. - -Then, uncomment the following line in the generated expect file to check the -output of expect: - -``` -# exp_internal 1 -``` diff --git a/docs/_docs/contributing/debugging.md b/docs/_docs/contributing/debugging.md deleted file mode 100644 index 959ad6706290..000000000000 --- a/docs/_docs/contributing/debugging.md +++ /dev/null @@ -1,366 +0,0 @@ ---- -layout: doc-page -title: Debugging Techniques ---- - -# Debugging Techniques -- [Setting up the playground](#setting-up-the-playground) -- [Show for human readable output](#show-for-human-readable-output) -- [How to disable color](#how-to-disable-color) -- [Reporting as a non-intrusive println](#reporting-as-a-non-intrusive-println) -- [Printing out trees after phases](#printing-out-trees-after-phases) -- [Printing out stack traces of compile time errors](#printing-out-stack-traces-of-compile-time-errors) -- [Configuring the printer output](#configuring-the-printer-output) -- [Figuring out an object creation site](#figuring-out-an-object-creation-site) - * [Via ID](#via-id) - * [Via tracer](#via-tracer) -- [Built-in Logging Architecture](#built-in-logging-architecture) - * [Printers](#printers) - * [Tracing](#tracing) - * [Reporter](#reporter) - -Table of contents generated with markdown-toc - -## Setting up the playground -Consider the `../issues/Playground.scala` (relative to the Dotty directory) file is: - -```scala -object Playground { - def main(args: Array[String]) = { - println("Hello World") - } -} -``` - -Then, you can debug Dotty by compiling this file via `scalac ../issues/Playground.scala` (from the SBT console) and collecting various debug output in process. This section documents techniques you can use to collect the debug info. - -[This](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/typer/Typer.scala#L2231) is the entry point to the Typer. The job of the Typer is to take an untyped tree, compute its type and turn it into a typed tree by attaching the type information to that tree. We will use this entry point to practice debugging techniques. E.g.: - -```scala - def typed(tree: untpd.Tree, pt: Type, locked: TypeVars)(implicit ctx: Context): Tree = - trace(i"typing $tree", typr, show = true) { - println("Hello Debug!") - /*...*/ -``` - -Then: - -```shell -scalac ../issues/Playground.scala -``` - -The techniques discussed below can be tried out in place of `println("Hello Debug")` in that location. They are of course applicable throughout the codebase. - -## Show for human readable output -Many objects in the compiler have a `show` method available on them via implicit rich wrapper: - -```scala -println(tree.show) -``` - -This will output every single tree passing through the typer (or wherever else you inject it) in a human readable form. Try calling `show` on anything you want to be human-readable, and chances are it will be possible to do so. - -## How to disable color -Note that the `show` command above outputs the code in color. This is achieved by injecting special characters into the strings which terminals interpret as commands to change color of the output. This however may not be what you want, e.g. if you want to zero-in on a particular tree: - -```scala -if (tree.show == """println("Hello World")""") - println(s"${tree.show}\n${pt.show}\n${tree.uniqueId}\n===\n") -``` - -The intention above is to output an extended debug info on a tree that matches a particular human-readable representation. However, because of the color characters, the comparison will fail. - -To disable color output from `show`, run `scalac` as follows: - -`scalac -color:never ../issues/Playground.scala` - -## Reporting as a non-intrusive println -Consider you want to debug the `tree` that goes into `assertPositioned(tree)` in the `typed` method. You can do: - -```scala -println(tree.show) -assertPositioned(tree) -``` - -But you can also do: - -```scala -assertPositioned(tree.reporting(s"Tree is: $result")) -``` - -`extension (a: A) def reporting(f: WrappedResult[T] ?=> String, p: Printer = Printers.default): A` is defined on all types. The function `f` can be written without the argument since it is a context function. The `result` variable is a part of the `WrapperResult` – a tiny framework powering the `reporting` function. Basically, whenever you are using `reporting` on an object `A`, you can use the `result: A` variable from this function and it will be equal to the object you are calling `reporting` on. - -## Printing out trees after phases -To print out the trees you are compiling after the FrontEnd (scanner, parser, namer, typer) phases: - -```shell -scalac -Xprint:typer ../issues/Playground.scala -``` - -To print out the trees after Frontend and CollectSuperCalls phases: - -```shell -scalac -Xprint:typer,collectSuperCalls ../issues/Playground.scala -``` - -To print out the trees after all phases: - -```shell -scalac -Xprint:all ../issues/Playground.scala -``` - -To find out the list of all the phases and their names, check out [this](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/Compiler.scala#L34) line in `Compiler.scala`. Each `Phase` object has `phaseName` defined on it, this is the phase name. - -## Printing out stack traces of compile time errors -You can use the flag `-Ydebug-error` to get the stack trace of all the compile-time errors. Consider the following file: - -```scala -object Foo -object Foo -``` - -Clearly we cannot define an object `Foo` twice. Now compile it as follows: `scalac -Ydebug-error ../issues/Playground.scala` (use whatever path you saved it under). The result will be as follows: - -```scala --- Error: ../issues/Playground.scala:2:0 --------------------------------------- -2 |object Foo - |^ - |object Foo has already been compiled once during this run -java.lang.Thread.getStackTrace(Thread.java:1552) -dotty.tools.dotc.reporting.Reporting.error(Reporter.scala:139) -dotty.tools.dotc.core.Contexts$Context.error(Contexts.scala:71) -dotty.tools.dotc.typer.Namer.errorName$2(Namer.scala:300) -dotty.tools.dotc.typer.Namer.checkNoConflict$1(Namer.scala:306) -dotty.tools.dotc.typer.Namer.createSymbol(Namer.scala:353) -dotty.tools.dotc.typer.Namer.recur$1(Namer.scala:490) -dotty.tools.dotc.typer.Namer.recur$3$$anonfun$2(Namer.scala:495) -... -``` - -So, the error happened in the Namer's `checkNoConflict` method (after which all the stack frames represent the mechanics of issuing an error, not an intent that produced the error in the first place). - -## Configuring the printer output -Printing from the `show` and `-Xprint` is done from the Printers framework (discussed in more details below). The following settings influence the output of the printers: - -```scala -val printLines = BooleanSetting("-print-lines" , "Show source code line numbers.") withAbbreviation "--print-lines" -val uniqid = BooleanSetting("-uniqid" , "Uniquely tag all identifiers in debugging output.") withAbbreviation "--unique-id" -val XprintInline = BooleanSetting("-Xprint-inline" , "Show where inlined code comes from") -val XprintTypes = BooleanSetting("-Xprint-types" , "Print tree types (debugging option).") -val Ydebug = BooleanSetting("-Ydebug" , "Increase the quantity of debugging output.") -val YdebugFlags = BooleanSetting("-Ydebug-flags" , "Print all flags of definitions") -val YdebugMissingRefs = BooleanSetting("-Ydebug-missing-refs", "Print a stacktrace when a required symbol is missing") -val YdebugNames = BooleanSetting("-Ydebug-names" , "Show internal representation of names") -val YdebugPos = BooleanSetting("-Ydebug-pos" , "Show full source positions including spans") -val YdebugTrace = BooleanSetting("-Ydebug-trace" , "Trace core operations") -val YdebugTreeWithId = IntSetting ("-Ydebug-tree-with-id", "Print the stack trace when the tree with the given id is created", Int.MinValue) -val YprintDebug = BooleanSetting("-Yprint-debug" , "when printing trees, print some extra information useful for debugging.") -val YprintDebugOwners = BooleanSetting("-Yprint-debug-owners", "when printing trees, print owners of definitions.") -val YprintPos = BooleanSetting("-Yprint-pos" , "show tree positions.") -val YprintPosSyms = BooleanSetting("-Yprint-pos-syms" , "show symbol definitions positions.") -val YprintSyms = BooleanSetting("-Yprint-syms" , "when printing trees print info in symbols instead of corresponding info in trees.") -val YshowTreeIds = BooleanSetting("-Yshow-tree-ids" , "Uniquely tag all tree nodes in debugging output.") -val YshowVarBounds = BooleanSetting("-Yshow-var-bounds" , "Print type variables with their bounds") -val YtestPickler = BooleanSetting("-Ytest-pickler" , "self-test for pickling functionality; should be used with -Ystop-after:pickler") -``` - -They are defined in [ScalaSettings.scala](https://github.com/lampepfl/dotty/blob/main/compiler/src/dotty/tools/dotc/config/ScalaSettings.scala). E.g. `YprintPos` is defined as: - -```scala -val YprintPos: Setting[Boolean] = BooleanSetting("-Yprint-pos", "show tree positions.") -``` - -And is to be used as: - -```scala -scalac -Yprint-pos ../issues/Playground.scala -``` - -If used, all the trees output with `show` or via `-Xprint:typer` will also have positions attached to them, e.g.: - -```scala -package @ { - module object Playground { - def main( - args: - Array@[String@]@< - Playground.scala:2 - > - @ - ) = - { - println@("Hello World"@)@< - Playground.scala:3 - > - }@ - @ - }@ -}@ -@ -``` - -## Figuring out an object creation site -### Via ID -Every [Positioned](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/ast/Positioned.scala) (a parent class of `Tree`) object has a `uniqueId` field. It is an integer that is unique for that tree and doesn't change from compile run to compile run. You can output these IDs from any printer (such as the ones used by `.show` and `-Xprint`) via `-Yshow-tree-ids` flag, e.g.: - -```shell -scalac -Xprint:typer -Yshow-tree-ids ../issues/Playground.scala -``` - -Gives: - -```scala -package #1047 { - final lazy module val Playground: Playground$#1049 = - new Playground$#1049#1050#1051()#1052 - #1053 - final module class Playground$() extends Object#1090#1091#1092()#1093, _root_# - 1061 - .scala#1062.Serializable#1063 { this: Playground#1054.type#1055 => - def main(args: Array#1028[String#1033]#1034#1038): Unit#1039 = - { - println#1094("Hello World"#1041)#1095 - }#1096 - #1097 - }#1099 -}#1100 -``` - -You can then use these IDs to locate the creation site of a given tree using that ID via `-Ydebug-tree-with-id`, e.g.: - -```shell -scalac -Ydebug-tree-with-id 1049 ../issues/Playground.scala -``` - -When the tree with the correspond id is allocated, the following prompt will appear: - -``` -Debug tree (id=1049) creation -Ident(Playground$) - - -a)bort, s)tack, r)esume -``` - -If you input `s`, you will get a stack trace like this: - -``` -java.lang.Throwable - at dotty.tools.dotc.reporting.Reporter$.loop$1(Reporter.scala:55) - at dotty.tools.dotc.reporting.Reporter$.displayPrompt(Reporter.scala:63) - at dotty.tools.dotc.ast.Positioned.printTrace$1(Positioned.scala:32) - at dotty.tools.dotc.ast.Positioned.uniqueId_$eq(Positioned.scala:34) - at dotty.tools.dotc.ast.Positioned.(Positioned.scala:45) - at dotty.tools.dotc.ast.Trees$Tree.(Trees.scala:53) - at dotty.tools.dotc.ast.Trees$DenotingTree.(Trees.scala:266) - at dotty.tools.dotc.ast.Trees$NameTree.(Trees.scala:292) - at dotty.tools.dotc.ast.Trees$RefTree.(Trees.scala:298) - at dotty.tools.dotc.ast.Trees$Ident.(Trees.scala:375) - at dotty.tools.dotc.ast.untpd$.Ident(untpd.scala:301) - at dotty.tools.dotc.ast.desugar$.moduleDef(Desugar.scala:804) - at dotty.tools.dotc.ast.desugar$.defTree(Desugar.scala:1038) - at dotty.tools.dotc.typer.Namer.expand(Namer.scala:441) - at dotty.tools.dotc.typer.Namer.index$$anonfun$1(Namer.scala:722) - at dotty.runtime.function.JProcedure1.apply(JProcedure1.java:15) - at dotty.runtime.function.JProcedure1.apply(JProcedure1.java:10) - at scala.collection.immutable.List.foreach(List.scala:392) - at dotty.tools.dotc.typer.Namer.index(Namer.scala:722) - at dotty.tools.dotc.typer.Namer.recur$1(Namer.scala:484) - at dotty.tools.dotc.typer.Namer.indexExpanded(Namer.scala:501) - at dotty.tools.dotc.typer.Namer.index(Namer.scala:474) - at dotty.tools.dotc.typer.FrontEnd.enterSyms$$anonfun$1(FrontEnd.scala:69) - at dotty.runtime.function.JFunction0$mcV$sp.apply(JFunction0$mcV$sp.java:12) - at dotty.tools.dotc.typer.FrontEnd.monitor(FrontEnd.scala:41) - at dotty.tools.dotc.typer.FrontEnd.enterSyms(FrontEnd.scala:71) - at dotty.tools.dotc.typer.FrontEnd.runOn(FrontEnd.scala:100) - at dotty.tools.dotc.Run.runPhases$4$$anonfun$4(Run.scala:158) - at dotty.runtime.function.JProcedure1.apply(JProcedure1.java:15) - at dotty.runtime.function.JProcedure1.apply(JProcedure1.java:10) - at scala.collection.IndexedSeqOptimized.foreach(IndexedSeqOptimized.scala:36) - at scala.collection.IndexedSeqOptimized.foreach$(IndexedSeqOptimized.scala:33) - at scala.collection.mutable.ArrayOps$ofRef.foreach(ArrayOps.scala:198) - at dotty.tools.dotc.Run.runPhases$5(Run.scala:170) - at dotty.tools.dotc.Run.compileUnits$$anonfun$1(Run.scala:178) - at dotty.runtime.function.JFunction0$mcV$sp.apply(JFunction0$mcV$sp.java:12) - at dotty.tools.dotc.util.Stats$.maybeMonitored(Stats.scala:102) - at dotty.tools.dotc.Run.compileUnits(Run.scala:185) - at dotty.tools.dotc.Run.compileSources(Run.scala:120) - at dotty.tools.dotc.Run.compile(Run.scala:104) - at dotty.tools.dotc.Driver.doCompile(Driver.scala:34) - at dotty.tools.dotc.Driver.process(Driver.scala:172) - at dotty.tools.dotc.Driver.process(Driver.scala:141) - at dotty.tools.dotc.Driver.process(Driver.scala:153) - at dotty.tools.dotc.Driver.main(Driver.scala:180) - at dotty.tools.dotc.Main.main(Main.scala) -``` - -So that tree was created at: - -``` - at dotty.tools.dotc.ast.desugar$.moduleDef(Desugar.scala:804) -``` - -Since all the stack frames above it are technical frames executing the tree creation command, and the frame in question is the location where the intent of the tree creation was expressed. - -### Via tracer -Some objects may not be `Positioned` and hence their creation site is not debuggable via the technique in the section above. Say you target a tree at `Typer`'s `typed` method as follows: - -```scala -if (tree.show == """println("Hello World")""") { - val creationSite = "" - println(creationSite) -} -``` - -In other words, you have a reference to the object and want to know were it was created. To do so, go to the class definition of that object. In our case, `tree` is a [`Tree`](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/ast/Trees.scala#L52). Now, create a new `val` member of that type: - -```scala -val tracer = Thread.currentThread.getStackTrace.mkString("\n") -``` - -Then, from the `typed` method (or wherever you want to access the trace): - -```scala -if (tree.show == """println("Hello World")""") { - val creationSite = tree.tracer - println(creationSite) -} -``` - -## Built-in Logging Architecture -Dotty has a lot of debug calls scattered throughout the code, most of which are disabled by default. At least three (possibly intertwined) architectures for logging are used for that: - -- Printer -- Tracing -- Reporter - -These do not follow any particular system and so probably it will be easier to go with `println` most of the times instead. - -### Printers -Defined in [Printers.scala](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/config/Printers.scala) as a set of variables, each responsible for its own domain. To enable them, replace `noPrinter` with `default`. [Example](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/typer/Typer.scala#L2226) from the code: - -```scala -typr.println(i"make contextual function $tree / $pt ---> $ifun") -``` - -`typr` is a printer. - -### Tracing -Defined in [trace.scala](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/reporting/trace.scala). [Example](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/typer/Typer.scala#L2232) from the code: - -```scala -trace(i"typing $tree", typr, show = true) { // ... -``` - -To enable globally, change [tracingEnabled](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/config/Config.scala#L164) to `true` (will recompile a lot of code). - -You also need to set the printer referenced in the call (in the example, `typr`) to `default` as explained in the section on printers. - -To enable for a single trace, do the following: - -```scala -trace.force(i"typing $tree", typr, show = true) { // ... -``` - -### Reporter -Defined in [Reporter.scala](https://github.com/lampepfl/dotty/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/compiler/src/dotty/tools/dotc/reporting/Reporter.scala). Enables calls such as `report.log`. To enable, run scalac with `-Ylog:typer` option. diff --git a/docs/_docs/contributing/getting-started.md b/docs/_docs/contributing/getting-started.md deleted file mode 100644 index c842fd0a49d0..000000000000 --- a/docs/_docs/contributing/getting-started.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -layout: doc-page -title: Getting Started ---- - - - -Requirements ------------- -Make sure that you are using macOS or Linux (or WSL on Windows) with Java 8 or newer. You can determine which version of the JDK is the -default by typing `java -version` in a Terminal window. - -Compiling and Running ---------------------- -Start by cloning the repository: - -```bash -$ git clone https://github.com/lampepfl/dotty.git -$ cd dotty -$ sbt managedSources # Needed for IDE import to succeed -``` - -Dotty provides a standard sbt build: compiling, running and starting a repl can -all be done from within sbt: - -```bash -$ sbt -> scalac tests/pos/HelloWorld.scala -> scala HelloWorld -hello world -``` - -There are also bash scripts that can be used in the same way. Assuming that you have cloned the Dotty repo locally, append -the following line on your `.bash_profile`: - -```shell -$ export PATH=$HOME/dotty/bin:$PATH -``` - -and you will be able to run the corresponding commands directly from your console: - -```shell -# Compile code using Dotty -$ scalac tests/pos/HelloWorld.scala - -# Run it with the proper classpath -$ scala HelloWorld -``` - - -Starting a REPL ---------------- -```bash -$ sbt -> repl -Welcome to Scala.next (pre-alpha) (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_101). -Type in expressions to have them evaluated. -Type :help for more information. -scala> -``` - -or via bash: - -```bash -$ scala -``` -Publish to local repository ---------------------------------- -To test our cloned compiler on local projects: - -```bash -$ sbt publishLocal -``` -Then in the `build.sbt` file of a test project: - -```bash -ThisBuild / scalaVersion := "-bin-SNAPSHOT" -``` -where `dotty-version` can be found in the file `project/Build.scala`, like `3.0.0-M2` - - -Generating Documentation -------------------------- -To generate this page and other static page docs, run -```bash -$ sbt -> scaladoc/generateScalaDocumentation -``` -For more information, see `scaladoc/README.md`. - -Before contributing to Dotty, we invite you to consult the -[Dotty Developer Guidelines](https://github.com/lampepfl/dotty/blob/main/CONTRIBUTING.md). - - -Community -------------- -The main development discussion channels are: -- [github.com/lampepfl/dotty/discussions](https://github.com/lampepfl/dotty/discussions) -- [contributors.scala-lang.org](https://contributors.scala-lang.org) -- [gitter.im/scala/contributors](https://gitter.im/scala/contributors) diff --git a/docs/_docs/contributing/index.md b/docs/_docs/contributing/index.md deleted file mode 100644 index 6cf0def2d5e2..000000000000 --- a/docs/_docs/contributing/index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -layout: index -title: Contributing ---- diff --git a/docs/_docs/contributing/procedures/index.md b/docs/_docs/contributing/procedures/index.md deleted file mode 100644 index 01c76f72c00c..000000000000 --- a/docs/_docs/contributing/procedures/index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -layout: index -title: Procedures ---- diff --git a/docs/_docs/contributing/procedures/release.md b/docs/_docs/contributing/procedures/release.md deleted file mode 100644 index 8f66f8854d4c..000000000000 --- a/docs/_docs/contributing/procedures/release.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -layout: doc-page -title: Release Procedure ---- - -# Model -The easiest way to produce a release of a GitHub-based open-source software is to tag the most recent commit on the `master` with the version number at regular intervals of time or once a previously agreed milestone is reached. However, this approach to releasing would rest on the assumption that each commit at the `master` branch can potentially be made into a release. We cannot provide the release-grade quality guarantees for each of the `master` commits, though. - -Consequently, in Dotty, we are using the method above – releasing-by-tagging – to mark release candidates (RC’s) and not the stable releases. The stable releases are also marked by a tag, but we have a procedure to assure their quality. - -An RC is promoted to a stable release in one release cycle after its creation. The idea is that this way, we have one release cycle's time to examine the release candidate and find critical issues which cannot be allowed into a stable release. - -If such issues are found, their fixes end up on a separate branch dedicated to that release. In one release cycle after the RC creation, the RC, along with all its subsequent fixes, is promoted to a stable release by means of tagging it. - -# Example -Say we want to release the 0.14.0 version. In this section we describe the process to do so (at a glance). - -## At the Dotty Repo -1. Tag the latest `master` commit as `0.14.0-RC1`. This commit is the release candidate for the `0.14.0` version. -2. Create a branch from that commit called `0.14.x`. This branch is intended to host the subsequent fixes to the RC for the issues that cannot be allowed in the `0.14.0` stable release. -3. Up until the next release date, if we find some issues with `0.14.0-RC1` that cannot end up in the release, we push the fixes to the `0.14.x` branch. -4. At the next release date, we release `0.14.0` from the branch `0.14.x`. We do so by tagging the latest commit at the `0.14.x` branch as `0.14.0`. Some things to note here: - 1. At this point, `0.14.x` (the branch) and `0.14.0-RC1` (the tag at which `0.14.x` branched from `master`) may differ, and the `0.14.x` branch is a more mature version of the `0.14.0-RC1` tag. - 2. `0.14.0` is not the same as the `master`. Only the commits critical for the `0.14.0` release end up at `0.14.x` branch. Not all of the commits made to the `master` during the release cycle are critical to `0.14.0`. However, all of the commits from `0.14.x` must end up on the `master` branch, so we merge `0.14.x` into `master`. -5. After the `0.14.0` version is released, we start the process for releasing `0.15.0` – repeat this algorithm from the beginning with the version set to `0.15.0-RC1` at step (1). - -## At the CI -CI is set to automatically detect the tags of the format discussed above and perform the required release operations. Precisely, it will do two things for the release tags: - -- Publish the release jars to Maven -- Create the drafts at the GitHub [release](https://github.com/lampepfl/dotty/releases) page of the repository with the artefacts of the release. - -The CI operation is entirely automatic provided you have tagged the release correctly. No need to do anything here. - -### Canceling CI builds -**The below guidelines are needed only to speed up things. It is no mistake if you skip this section. However, if you do things wrong here, there may be trouble. So do it only if you feel yourself confident with the release cycle and the workings of the CI.** - -Note that after the first stage of the release cycle (see "Publishing artifacts to Maven via CI" section of the checklist below) only three test runs are required to be run at the CI: - -- `master` branch's latest *commit* with the updated `baseVersion` -- `` *tag* of the stable version being released -- `` *tag* of the RC version being released - -However, you may end up with as many as 6 tasks being run. The auxiliary tasks may include: - -- *commit* tests of the *tags* specified above. You may have two of these, corresponding to the two tags. You should see them appearing to have the same commit hash in the CI, but one of them will have the tag next to it and the other one will not. The *tag* one must remain, as the CI tasks on tags publish to maven. CI tasks on commits do not. So it is safe to cancel the task running on the commit, if the commit hash is the same as that of the tag's task commit. -- Older commit from the `master` branch. Look for all the tasks run on the `master` branch in the CI and see if there are more than one of these. Then, find the one testing the most recent commit of the branch. The others can safely be canceled. - -## Documentation -### Release Procedure Checklist -Before we start the release procedure, we create an issue with a release checklist. As we go through the release, we update the checklist. To generate the checklist, run the following command: - -`bash <(curl -sL https://raw.githubusercontent.com/lampepfl/dotty/master/docs/docs/contributing/checklist.sh) ` - -Above, `` is the stable version being released. For example, if you are releasing `0.14.0` and `0.15.0-RC1`, this variable is `14` and the command is as follows: - -`bash <(curl -sL https://raw.githubusercontent.com/lampepfl/dotty/master/docs/docs/contributing/checklist.sh) 14` - -Copy and paste the output into the release issue. - -The ecosystem update section for some projects also mentions a set of criteria upon which the project is to be marked in the checklist. When the Travis build status is specified next to the project's name, it is to be understood that this build must pass after all of the other criteria of that project are checked. Note that due to caching, the label image next to the link may not reflect the real status of the build. Therefore, to verify the status, click on the link and make sure that your recent commit passes. - -When no criteria is specified, common sense is to be used. - -### GitHub Releases and Blog Post -After the release is done, we document it as follows: - -- On the GitHub release page, modify the release drafts created by CI. The RC draft should include notable changes introduced since the previous RC. E.g. for `0.14.0-RC1` these are generated by `gren changelog -G --override -D prs --tags=0.13.0-RC1..0.14.0-RC1`. `gren` is available [here](https://github.com/github-tools/github-release-notes), and before running the above command, please make sure that (1) the `origin` branch points to the `lampepfl/dotty` repository and (2) the two tags mentioned in the command are pushed to the `master` branch of that repo. Otherwise, the command won't pick up the tags. -- Create a blog article documenting the most important changes done by the release. - -## Ecosystem -After releasing a new version of Dotty, we need to make sure to update the following related projects: - -- [Example Project](https://github.com/scala/scala3-example-project) - - To deploy locally: `git clone https://github.com/scala/scala3-example-project.git && cd dotty-example-project/` - - To test locally: `sbt run` - - [Commit](https://github.com/scala/scala3-example-project/commit/76bf0b4d708206b1901fa7f291f07cd470506e79) updating the Dotty version (only `README` and `build.sbt` files) -- [Example Project with Mill](https://github.com/scala/scala3-example-project/tree/mill) - - Deploy: `git clone https://github.com/scala/scala3-example-project && cd dotty-example-project && git checkout mill` - - Test: `mill root.run` - - [Commit 1](https://github.com/scala/scala3-example-project/commit/e1ad1905ef38d07943e0c176333ba24e306a2078) – `build.sc` only; [Commit 2](https://github.com/scala/scala3-example-project/commit/23bc5df89e72b782ab8e19157d6bbcb67eef30cd) -- [Dotty G8 template](https://github.com/scala/scala3.g8) - - Deploy: `git clone https://github.com/scala/scala3.g8.git` - - Test (note the relative path as argument to `sbt new`, hence this command should be run after Deploy in the same directory as Deploy): `sbt new file://./dotty.g8 --name=foo --description=bar && cd foo && sbt run` - - [Commit](https://github.com/scala/scala3.g8/commit/0cde8fa843e15e916f07f22a196f35a5988b26af) -- [Dotty G8 template with cross build support](https://github.com/scala/scala3-cross.g8) - - Deploy: `git clone https://github.com/scala/scala3-cross.g8.git` - - Test: `sbt new file://./dotty-cross.g8 --name=foo --description=bar && cd foo && sbt run` - - [Commit](https://github.com/scala/scala3-cross.g8/commit/0e3ea2ae8ba8d001e63e5098ff60d728036d358f) -- [Dotty Homebrew Formula](https://github.com/lampepfl/homebrew-brew) - - Deploy: `git clone https://github.com/lampepfl/homebrew-brew.git && cd homebrew-brew` - - [Commit](https://github.com/lampepfl/homebrew-brew/commit/04f7284564387754a360a354159f2f8d6156a6c7). SHA256 sum comes from the issue checklist computed for the release as specified above. The file with checksums is available at [GitHub Releases](https://github.com/lampepfl/dotty/releases) -> release in question -> assets -> `sha256sum.txt` -> `*.tar.gz` file sum. -- [Dotty test under various OSs](https://github.com/lampepfl/packtest) - - Deploy: `git clone https://github.com/lampepfl/packtest.git && cd packtest` - - [Commit](https://github.com/lampepfl/packtest/commit/6d3edf7333e0e788af7c4f4ab976b56905ddf9ed) -- [Scastie](https://github.com/scalacenter/scastie/) - - Deploy (copy-paste the command and append the release id, e.g. `15` for `0.15.0-RC1`): `git clone https://github.com/scalacenter/scastie.git && cd scastie && git remote add staging https://github.com/dotty-staging/scastie && git checkout -b dotty-release-` - - [PR](https://github.com/scalacenter/scastie/pull/433) – push your changes to `staging` repo (as defined in "Deploy" above) with `git push -u staging`, then submit the PR from there. -- [Dotty](https://github.com/lampepfl/dotty/) - - If you are reading this, Dotty should already be deployed on your machine :) - - [PR](https://github.com/lampepfl/dotty/pull/6557) -- [Scalac](https://github.com/scala/scala) - - Deploy: `git clone https://github.com/scala/scala.git && cd scala && git remote add staging https://github.com/dotty-staging/scala && git checkout -b dotty-release-` - - [PR](https://github.com/scala/scala/pull/7993) - -For each need to do the following: - -- Update Dotty version to the latest RC -- Update the sbt-dotty SBT plugin version to the latest published one -- Update the projects' source code to follow the Dotty developments if necessary - -# Procedure in Bash Scripts -The below procedure is compiled from [this](https://github.com/lampepfl/dotty/issues/5907#issue-409313505) and [this](https://github.com/lampepfl/dotty/issues/6235#issue-429265748) checklists. It assumes we want to publish the `0.14.0` given the `0.14.0-RC1` release candidate. - -Note that at the same time we will also publish the `0.15.0-RC1` release. We publish two releases at the same time as per the logic outlined at the [Example/At the Dotty Repo](#at-the-dotty-repo) and the [Model](#model) sections above: the step (5) in the algorithm outlined in the [Example](#at-the-dotty-repo) for the release cycle of `0.14.0` is the step (1) in the release cycle of `0.15.0`. - -The following commands assume a remote tracking repository named `origin` pointing to the main Dotty repository: `https://github.com/lampepfl/dotty.git`. - - -```bash - -######## Publish the 0.14.0 stable version – end the release cycle for 0.14.0 ######## -git checkout 0.14.x - -# Change `val baseVersion = "0.14.0-RC1"` to `val baseVersion = "0.14.0"` in project/Build.scala - -git commit -am 'Release Dotty 0.14.0' -git tag 0.14.0 -git push origin 0.14.0 - -git checkout master -git merge 0.14.x - -# Make sure the merge doesn't break anything. In doubt, create a PR to run the CL -git push origin master - -######## Publish the 0.15.0-RC1 unstable version – begin the release cycle for 0.15.0 ######## -# Move all the unfinished tasks from Milestone 15 to Milestone 16 on GitHub – see https://github.com/lampepfl/dotty/milestones - -git checkout -b 0.15.x - -# Change val baseVersion = "0.15.0" to val baseVersion = "0.15.0-RC1" - -git commit -am 'Release Dotty 0.15.0-RC1' -git tag 0.15.0-RC1 -git push origin 0.15.x -git push origin 0.15.0-RC1 - -git checkout master - -# Change val baseVersion = "0.15.0" to val baseVersion = "0.16.0" - this will be the next version after `0.15.0-RC1` is promoted to `0.15.0`. - -git commit -am 'Set baseVersion to 0.16.0' -git push origin master -``` \ No newline at end of file diff --git a/docs/_docs/contributing/procedures/vulpix.md b/docs/_docs/contributing/procedures/vulpix.md deleted file mode 100644 index 5e8a2eab425b..000000000000 --- a/docs/_docs/contributing/procedures/vulpix.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -layout: doc-page -title: Test Vulpix Framework ---- - -# Test Vulpix Framework -If you are modifying the Vulpix framework and need a playground with dummy tests to try out your modifications, do the following. - -Create the directory structure for the playground: - -```bash -mkdir -pv tests/playground/run tests/playground/neg -echo "stuff" > tests/playground/neg/Sample.scala -echo 'object Test { def main(args: Array[String]): Unit = {println("Hi")} }' > tests/playground/run/Sample.scala -``` - -In `CompilationTests.scala`: - -```scala - @Test def exampleNeg: Unit = { - implicit val testGroup: TestGroup = TestGroup("exampleNeg") - compileFilesInDir("tests/playground/neg", defaultOptions).checkExpectedErrors() - } - - @Test def exampleRun: Unit = { - implicit val testGroup: TestGroup = TestGroup("exampleRun") - compileFilesInDir("tests/playground/run", defaultOptions).checkRuns() - } -``` - -SBT: - -```scala -testOnly dotty.tools.dotc.CompilationTests -- *example* -``` diff --git a/docs/_docs/contributing/scala2-vs-scala3.md b/docs/_docs/contributing/scala2-vs-scala3.md deleted file mode 100644 index b92cbe2381ea..000000000000 --- a/docs/_docs/contributing/scala2-vs-scala3.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -layout: doc-page -title: Divergences between Scala 2 and Dotty ---- - -# Divergences between Scala 2 and Dotty -The following issues encountered when compiling Scala 2 code as-is under Dotty: - -## Scalafix candidates -- If a method is defined `toSet()`, it cannot be called `toSet`. -- “result type of implicit definition needs to be given explicitly” -- There are no `'Symbol`s in Scala 3, you must construct symbols via `new Symbol("foo")` instead of old `'foo` - -## Trivial -- Scala 2.13 libraries cannot be used from Dotty because the dotty-library is compiled against the 2.12 standard library which is not binary-compatible with the 2.13 one. We can't be compatible with both at the same time. -- To use Scala 2.12 dependencies from SBT with Dotty, use `withDottyCompat` as documented [here](https://github.com/scala/scala3-example-project#getting-your-project-to-compile-with-dotty). -- Feature warnings about implicits `scala.language.implicitConversions` are output by default, unlike in Scala 2. This creates noise. Unclear how to turn off. - -Implicit conversions must be applied explicitly: - -```scala -implicit def IterablePath[T](s: Iterable[T])(implicit conv: T => RelPath): RelPath = { - s.foldLeft(rel){_ / conv(_)} -} -``` - -Stronger compile time guarantees on variance. Scala 2 does not assert variance on default parameters to parameters of the function value type. E.g. in geny: - -```scala -# Dotty -def count(f: A => Boolean = (a: A) => true): Int = -| ^^^^^^^^^^^^^^ -|covariant type A occurs in contravariant position in type => A => Boolean of method count$default$1 -``` - -Fix: -```scala -# Dotty -def count[B >: A](f: B => Boolean = (_: B) => true): Int = -``` - -## Tricky -- Scala 3 macros are completely different from Scala 2 ones, requires a migration strategy of its own diff --git a/docs/_docs/contributing/testing.md b/docs/_docs/contributing/testing.md deleted file mode 100644 index a01cdb08f8ab..000000000000 --- a/docs/_docs/contributing/testing.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -layout: doc-page -title: Testing in Dotty ---- - -Running all tests in Dotty is as simple as: - -```bash -$ sbt test -``` - -Specifically, `sbt test` runs all tests that do _not_ require a bootstrapped -compiler. In practice, this means that it runs all compilation tests meeting -this criterion, as well as all non-compiler tests. - -The entire suite of tests can be run using the bootstrapped compiler as follows: - -```bash -$ sbt -> scala3-bootstrapped/test -``` - -There are currently several forms of tests in Dotty. These can be split into -two categories: - -## Unit tests -These tests can be found in `/test` and are used to check -functionality of specific parts of the codebase in isolation e.g: parsing, -scanning and message errors. - -To run all tests in e.g., for the compiler test-suite you can write: - -```bash -$ sbt -> scala3-compiler/test -``` - -To run a single test class you use `testOnly` and the fully qualified class name. -For example: - -```bash -> testOnly dotty.tools.dotc.transform.TreeTransformerTest -``` - -The test command follows a regular expression-based syntax `testOnly * -- *`. -The right-hand side picks a range of names for methods and the left-hand side picks a range of class names and their -fully-qualified paths. - -Consequently, you can restrict the aforementioned executed test to a subset of methods by appending ``-- *method_name``. -The example below picks up all methods with the name `canOverwrite`: - -```bash -> testOnly dotty.tools.dotc.transform.TreeTransformerTest -- *canOverwrite -``` - -Additionally, you can run all tests named `method_name`, in any class, without providing a class name: - -```bash -> testOnly -- *canOverwrite -``` - -You can also run all paths of classes of a certain name: - -```bash -> testOnly *.TreeTransformerTest -``` - -### Testing with checkfiles -Some tests support checking the output of the run or the compilation against a checkfile. A checkfile is a file in which the expected output of the compilation or run is defined. A test against a checkfile fails if the actual output mismatches the expected output. - -Currently, the `run` and `neg` (compilation must fail for the test to succeed) tests support the checkfiles. `run`'s checkfiles contain an expected run output of the successfully compiled program. `neg`'s checkfiles contain an expected error output during compilation. - -Absence of a checkfile is **not** a condition for the test failure. E.g. if a `neg` test fails with the expected number of errors and there is no checkfile for it, the test still passes. - -Checkfiles are located in the same directories as the tests they check, have the same name as these tests with the extension `*.check`. E.g. if you have a test named `tests/neg/foo.scala`, you can create a checkfile for it named `tests/neg/foo.check`. And if you have a test composed of several files in a single directory, e.g. `tests/neg/manyScalaFiles`, the checkfile will be `tests/neg/manyScalaFiles.check`. - -If the actual output mismatches the expected output, the test framework will dump the actual output in the file `*.check.out` and fail the test suite. It will also output the instructions to quickly replace the expected output with the actual output, in the following format: - -``` -Test output dumped in: tests/playground/neg/Sample.check.out - See diff of the checkfile - > diff tests/playground/neg/Sample.check tests/playground/neg/Sample.check.out - Replace checkfile with current output - > mv tests/playground/neg/Sample.check.out tests/playground/neg/Sample.check -``` - -To create a checkfile for a test, you can do one of the following: - -- Create a dummy checkfile with a random content, run the test, and, when it fails, use the `mv` command reported by the test to replace the dummy checkfile with the actual output. -- Manually compile the file you are testing with `scalac` and copy-paste whatever console output the compiler produces to the checkfile. - -## Integration tests -These tests are Scala source files expected to compile with Dotty (pos tests), -along with their expected output (run tests) or errors (neg tests). - -All of these tests are contained in the `./tests/*` directories and can be run with the `testCompilation` command. Tests in folders named `with-compiler` are an exception, see next section. - -Currently to run these tests you need to invoke from sbt: - -```bash -$ sbt -> testCompilation -``` - -(which is effectively the same with `testOnly dotty.tools.dotc.CompilationTests`) - -It is also possible to run tests filtered, again from sbt: - -```bash -$ sbt -> testCompilation companions -``` - -This will run both the test `./tests/pos/companions.scala` and -`./tests/neg/companions.scala` since both of these match the given string. -This also means that you could run `testCompilation` with no arguments to run all integration tests. - -When complex checkfiles must be updated, `testCompilation` can run in a mode where it overrides the checkfiles with the test outputs. -```bash -$ sbt -> testCompilation --update-checkfiles -``` - -Use `--help` to see all the options -```bash -$ sbt -> testCompilation --help -``` - -### Joint and separate sources compilation - -When the sources of a test consist of multiple source files places in a single directory they are passed to the compiler in a single run and the compiler decides in which order to compile them. In some cases, however, to reproduce a specific test scenario it might be necessary to compile the source files in several steps in a specified order. To achieve that one can add a `_${step_index}` suffix to a file name (before the `.scala` or `.java` extension) indicating the order of compilation. E.g. if the test directory contains files named `Foo_1.scala`, `Bar_2.scala` and `Baz_2.scala` then `Foo_1.scala` will be compiled first and after that `Bar_2.scala` together with `Baz_2.scala`. - -The other kind of suffix that can modify how particular files are compiled is `_c${compilerVersion}`. When specified, the file will be compiled with a specific version of the compiler instead of the one developed on the current branch. - -Different suffixes can be mixed together (their order is not important although consistency is advised), e.g. `Foo_1_c3.0.2`, `Bar_2_c3.1.0`. - -### Bootstrapped-only tests - -To run `testCompilation` on a bootstrapped Dotty compiler, use -`scala3-compiler-bootstrapped/testCompilation` (with the same syntax as above). -Some tests can only be run in bootstrapped compilers; that includes all tests -with `with-compiler` in their name. - -### From TASTy tests - -`testCompilation` has an additional mode to run tests that compile code from a `.tasty` file. - Modify blacklist and whitelists in `compiler/test/dotc` to enable or disable tests from `.tasty` files. - - ```bash - $ sbt - > testCompilation --from-tasty - ``` - - This mode can be run under `scala3-compiler-bootstrapped/testCompilation` to test on a bootstrapped Dotty compiler. - -### SemanticDB tests - -```bash -$ sbt -> scala3-compiler-bootstrapped/testOnly dotty.tools.dotc.semanticdb.SemanticdbTests -``` - -The output of the `extractSemanticDB` phase, enabled with `-Xsemanticdb` is tested with the bootstrapped JUnit test -`dotty.tools.dotc.semanticdb.SemanticdbTests`. It uses source files in `tests/semanticdb/expect` to generate -two kinds of output file that are compared with "expect files": placement of semanticdb symbol occurrences inline in -sourcecode (`*.expect.scala`), for human verification by inspection; and secondly metap formatted output which outputs -all information stored in semanticdb (`metac.expect`). -Expect files are used as regression tests to detect changes in the compiler. - -The test suite will create a new file if it detects any difference, which can be compared with the -original expect file, or if the user wants to globally replace all expect files for semanticdb they can use -`scala3-compiler-bootstrapped/test:runMain dotty.tools.dotc.semanticdb.updateExpect`, and compare the changes via version -control. - -### Test regimes - -Continuous integration, managed by GitHub Actions, does not run all jobs when a pull request is created. -In particular, test jobs for testing under JDK 8 and Windows are not run. Those jobs are run only for the nightly build. - -If a PR may fail differentially under either JDK 8 or Windows, the test jobs may be triggered by adding -a special command to the PR comment text: - -``` -[test_java8] -[test_windows_full] -``` -Furthermore, CI tests are bootstrapped. A job to also run tests non-bootstrapped may be triggered manually: -``` -[test_non_bootstrapped] -``` -A trivial PR, such as a fix for a typo in a comment or when contributing other documentation, may benefit by skipping CI tests altogether: -``` -[skip ci] -``` -Other jobs which are normally run can also be selectively skipped: -``` -[skip community_build] -[skip test_windows_fast] -``` - -## Troubleshooting - -Some of the tests depend on temporary state stored in the `out` directory. In rare cases, that directory -can enter an inconsistent state and cause spurious test failures. If you suspect a spurious test failure, -you can run `rm -rf out/*` from the root of the repository and run your tests again. If that fails, you -can try `git clean -xfd`. diff --git a/docs/_docs/contributing/tools/ide.md b/docs/_docs/contributing/tools/ide.md deleted file mode 100644 index 5db333bee9d9..000000000000 --- a/docs/_docs/contributing/tools/ide.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -layout: doc-page -title: Using an IDE ---- - -You can use either Metals (VS Code, vim) or IntelliJ IDEA as described on the -IDE sections of the [getting-started page](https://docs.scala-lang.org/scala3/getting-started.html) to work -on the Scala 3 codebase. There are however a few additional considerations to take into account. - - -## Bootstrapping Projects - -The sbt build for dotty implements bootstrapping within the same build, so each component has -two projects: - -``` -sbt:scala3> projects -... -[info] scala3-compiler -[info] scala3-compiler-bootstrapped -... -``` - -These duplicated projects can be confusing and cause issues in IDEs. - -When using Metals, the `-bootstrapped` projects are not exported. - -In IntelliJ IDEA, we recommend importing the dotty codebase through BSP, then the `-bootstrapped` -projects are not exported. - - -## Scala Version warning in Metals - -When using VS Code, Metals might show a warning that the Scala version (`3.0.0-[...]-NIGHTLY`) -is not supported. The reason is that the dotty repository sometimes uses a nightly build as -reference compiler. The IDE experience is going to be limited in this case (semantic features will -only within single files). diff --git a/docs/_docs/contributing/tools/index.md b/docs/_docs/contributing/tools/index.md deleted file mode 100644 index 92503ee82013..000000000000 --- a/docs/_docs/contributing/tools/index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -layout: index -title: IDEs and Tools ---- diff --git a/docs/_docs/contributing/tools/mill.md b/docs/_docs/contributing/tools/mill.md deleted file mode 100644 index 7d372835395f..000000000000 --- a/docs/_docs/contributing/tools/mill.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: doc-page -title: Basic Operations with Mill ---- - -Here's an example of how to test a project that uses mill: - -```bash -mill utest.jvm[2.12.8].test -``` - -- `utest.jvm` - the name of the compiled module (obtain from `build.sc`) -- `2.12.8` – Scala cross-compile version -- `test` – task to run on the module specified with the specified Scala version - -To get mill of the most recent version, first, find it in https://github.com/lihaoyi/mill/releases (e.g. `0.4.2-1-020e28`). Copy the download link and substitute it in the following command instead of `https://github.com/lihaoyi/mill/releases/download/0.4.1/0.4.1`: - -```bash -# From http://www.lihaoyi.com/mill/ -sudo sh -c '(echo "#!/usr/bin/env sh" && curl -L https://github.com/lihaoyi/mill/releases/download/0.4.1/0.4.1) > /usr/local/bin/mill && chmod +x /usr/local/bin/mill' -``` diff --git a/docs/_docs/contributing/tools/scalafix.md b/docs/_docs/contributing/tools/scalafix.md deleted file mode 100644 index 58c7d0eb7b3a..000000000000 --- a/docs/_docs/contributing/tools/scalafix.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -layout: doc-page -title: Working with Scalafix ---- - -# Working with Scalafix - -First, create a new rule as follows (command from https://scalacenter.github.io/scalafix/docs/developers/setup.html): - -```bash -sbt new scalacenter/scalafix.g8 --repo="Repository Name" -``` - -To run the rule against some codebase: - -```bash -scalafix -r file:scalafix/rules/src/main/scala/fix/YourRule.scala your/code/base/ -``` - -Where `YourRule.scala` is the rule you developed and `your/code/base` is the code base you are running the rule against. diff --git a/docs/_docs/contributing/workflow.md b/docs/_docs/contributing/workflow.md deleted file mode 100644 index 956ce2998c75..000000000000 --- a/docs/_docs/contributing/workflow.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -layout: doc-page -title: Workflow ---- - -Check [Getting Started](getting-started.md) for instructions on how to obtain the source code of dotty. -This document details common workflow patterns when working with Dotty. - -## Compiling files with scalac ## - -As we have seen you can compile a test file either from sbt: - -```bash -$ sbt -> scalac -``` - -or from terminal: - -```bash -$ scalac -``` - -Here are some useful debugging ``: - -* `-Xprint:PHASE1,PHASE2,...` or `-Xprint:all`: prints the `AST` after each - specified phase. Phase names can be found by examining the - `dotty.tools.dotc.transform.*` classes for their `phaseName` field e.g., `-Xprint:erasure`. - You can discover all phases in the `dotty.tools.dotc.Compiler` class -* `-Ylog:PHASE1,PHASE2,...` or `-Ylog:all`: enables `ctx.log("")` logging for - the specified phase. -* `-Ycheck:all` verifies the consistency of `AST` nodes between phases, in - particular checks that types do not change. Some phases currently can't be - `Ycheck`ed, therefore in the tests we run: - `-Ycheck:tailrec,resolveSuper,mixin,restoreScopes,labelDef`. -* the last frontier of debugging (before actual debugging) is the range of logging capabilities that -can be enabled through the `dotty.tools.dotc.config.Printers` object. Change any of the desired printer from `noPrinter` to -`default` and this will give you the full logging capability of the compiler. - -## Inspecting Types with Type Stealer ## - -You can inspect types with the main method `dotty.tools.printTypes` from the sbt shell, -passing at least three arguments: -- The first argument is a string that introduces some -Scala definitions -- The second argument introduces how the the remaining arguments should be interpreted, -comprising of - - `rhs` - the return type of a definition - - `class` - the signature of a class, after its name - - `method` - the signature of a method, after its name - - `type` - the signature of a type, after its name -- The remaining arguments are type signatures, these may reference definitions introduced by the first argument. - -Each type signature is then be printed, displaying their internal structure, alongside their class, using -the same representation that can later be used in pattern matching to decompose the type. - -Here, we inspect a refinement of a class `Box`: -```bash -$ sbt -> scala3-compiler-bootstrapped/Test/runMain dotty.tools.printTypes "class Box { def x: Any }" "rhs" "Box { def x: Int }" -RefinedType(TypeRef(ThisType(TypeRef(NoPrefix, module class )),class Box), x, ExprType(TypeRef(TermRef(ThisType(TypeRef(NoPrefix, module class )), object scala), class Int))) [class dotty.tools.dotc.core.Types$CachedRefinedType] -``` - -You can also pass the empty string as the second -argument, e.g. to inspect a standard library type: -```bash -$ sbt -> scala3-compiler-bootstrapped/Test/runMain dotty.tools.printTypes "" "rhs" "1 *: EmptyTuple" -AppliedType(TypeRef(TermRef(ThisType(TypeRef(NoPrefix, module class )), object scala), class *:), List(ConstantType(Constant(1)), TypeRef(TermRef(ThisType(TypeRef(NoPrefix, module class scala)), object Tuple$package), type EmptyTuple))) -``` - -Here are some other examples you can follow: -- `...printTypes "" class "[T] extends Foo[T] {}"` -- `...printTypes "" method "(x: Int): x.type"` -- `...printTypes "" type "<: Int" "= [T] =>> List[T]"` - -If you want to further inspect the types, and not just print them, the object `dotty.tools.DottyTypeStealer` has a -method `stealType`. It takes the same arguments as `printTypes`, but returns both a `Context` containing the -definitions passed, along with the list of types: -```scala -// compiler/test/dotty/tools/DottyTypeStealer.scala -object DottyTypeStealer extends DottyTest { - - enum Kind: - case `rhs`, `method`, `class`, `type` - ... - - def stealType(kind: Kind, source: String, typeStrings: String*): (Context, List[Type]) = { - ... - } -} -``` -Any test source within `compiler/test` can then call `stealType` for custom purposes. - -## Pretty-printing ## -Many objects in the scalac compiler implement a `Showable` trait (e.g. `Tree`, -`Symbol`, `Type`). These objects may be prettyprinted using the `.show` -method - -## SBT Commands Cheat Sheet ## -The basics of working with Dotty codebase are documented [here](https://dotty.epfl.ch/docs/contributing/getting-started.html) and [here](https://dotty.epfl.ch/docs/contributing/workflow.html). Below is a cheat sheet of some frequently used commands (to be used from SBT console – `sbt`). - - -| Command | Description | -|------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------| -| `scalac ../issues/Playground.scala` | Compile the given file – path relative to the Dotty directory. Output the compiled class files to the Dotty directory itself. | -| `scala Playground` | Run the compiled class `Playground`. Dotty directory is on classpath by default. | -| `repl` | Start REPL | -| `testOnly dotty.tools.dotc.CompilationTests -- *pos` | Run test (method) `pos` from `CompilationTests` suite. | -| `testCompilation sample` | In all test suites, run test files containing the word `sample` in their title. |