Merge pull request #6718 from dotty-staging/debug-pickling

Add pickling crash debug guide when developing macros

Author: nicolasstucki

compiler/src/dotty/tools/dotc/core/tasty/TreePickler.scala

@@ -695,7 +695,7 @@ class TreePickler(pickler: TastyPickler) {
 
   def pickle(trees: List[Tree])(implicit ctx: Context): Unit = {
     trees.foreach(tree => if (!tree.isEmpty) pickleTree(tree))
-    def missing = forwardSymRefs.keysIterator.map(_.showLocated).toList
+    def missing = forwardSymRefs.keysIterator.map(sym => sym.showLocated + "(line " + sym.sourcePos.line + ")").toList
     assert(forwardSymRefs.isEmpty, i"unresolved symbols: $missing%, % when pickling ${ctx.source}")
   }
 

docs/docs/internals/debug-macros.md

@@ -30,3 +30,36 @@ If the position is in the compiler, then either report a compiler bug or
 fix the problem with `.withSpan(tree.span)`. The following fix is an example:
 
 - https://github.com/lampepfl/dotty/pull/6581
+
+## unresolved symbols in pickling
+
+Here is the usually stacktrace for unresolved symbols in pickling:
+
+```
+[error] java.lang.AssertionError: assertion failed: unresolved symbols: value pos (line 5565) when pickling scalatest/scalatest-test.dotty/target/scala-0.17/src_managed/test/org/scalatest/AssertionsSpec.scala
+[error] 	at dotty.DottyPredef$.assertFail(DottyPredef.scala:16)
+[error] 	at dotty.tools.dotc.core.tasty.TreePickler.pickle(TreePickler.scala:699)
+[error] 	at dotty.tools.dotc.transform.Pickler.run$$anonfun$10$$anonfun$8(Pickler.scala:60)
+[error] 	at dotty.runtime.function.JProcedure1.apply(JProcedure1.java:15)
+[error] 	at dotty.runtime.function.JProcedure1.apply(JProcedure1.java:10)
+[error] 	at scala.collection.immutable.List.foreach(List.scala:392)
+[error] 	at dotty.tools.dotc.transform.Pickler.run$$anonfun$2(Pickler.scala:83)
+[error] 	at dotty.runtime.function.JProcedure1.apply(JProcedure1.java:15)
+[error] 	at dotty.runtime.function.JProcedure1.apply(JProcedure1.java:10)
+[error] 	at scala.collection.immutable.List.foreach(List.scala:392)
+[error] 	at dotty.tools.dotc.transform.Pickler.run(Pickler.scala:83)
+[error] 	at dotty.tools.dotc.core.Phases$Phase.runOn$$anonfun$1(Phases.scala:316)
+[error] 	at scala.collection.immutable.List.map(List.scala:286)
+[error] 	at dotty.tools.dotc.core.Phases$Phase.runOn(Phases.scala:318)
+[error] 	at dotty.tools.dotc.transform.Pickler.runOn(Pickler.scala:87)
+```
+
+From the stack trace, we know `pos` at line 5565 cannot be resolved. For the
+compiler, it means that the name `pos` (usually a local name, but could also be
+a class member) is used in the code but its definition cannot be found.
+
+A possible cause of the problem is that the macro implementation accidentally
+dropped the definition of the referenced name.
+
+If you are confident that the macro implementation is correct, then it might be
+a bug of the compiler. Try to minimize the code and report a compiler bug.