Support subprojects with macro definitions and usage

[eed3si9n]

[swachter]

Unidoc is not able to process sources with macro annotations. E.g. when the class

class ExtendSecureOrInsecureLoggers extends StaticAnnotation {

  inline def apply(defn: Any): Any = meta {
    ...
  }
}

is processed by Unidoc then the following error is reported:

[error] /home/was1wa3/bikesensor/log-switch/src/main/scala/com/bosch/inst/base/log/ExtendSecureOrInsecureLoggers.scala:12: ';' expected but 'def' found.
[error]   inline def apply(defn: Any): Any = meta {
[error]

[raboof]

I'm running into this while generating the documentation for akka-http, which now requires a macro to be expanded for the project to compile.

Is there a fundamental reason why macro expansion cannot be taken into account while compiling the project from/for unidoc?

[eed3si9n]

The compiler requires macros to be precompiled, which is achieved typically by putting into separate subproject. Meanwhile Scsladoc I think requires full compilation of all sources.

Does scalacOptions in (ScalaUnidoc, unidoc) += "-Ymacro-expand:none" not work?

[raboof]

To be a bit more specific, the macro is defined in the akka-parsing subproject, and looks like this:

object since213macro {
  def impl(c: Context)(annottees: c.Expr[Any]*): c.Expr[Any] = annottees match {
    case Seq(method) ⇒
      import c.universe._
      if (scala.util.Properties.versionNumberString.startsWith("2.13"))
        method
      else
        c.Expr[Nothing](EmptyTree)
    case _ ⇒
      throw new IllegalArgumentException("Please annotate single expressions")
  }
}
class since213 extends StaticAnnotation {
  def macroTransform(annottees: Any*): Any = macro since213macro.impl
}

It is used in the akka-http-core subproject, which depends on akka-parsing and where it marks some code that is only valid on 2.13. When compiling the docs for akka-http-core with 2.12, however, it seems the macro is not applied, and we cannot generate unidoc due to compile errors relating to the to-be-removed code. 'normal' compilation and even 'compile:doc' work fine.

So for this case it seems the fact that the macro is not expanded is the problem, rather than the solution. Does that make sense?

I understand currently unidoc cannot deal with expanding macro's, but in my case "just not expanding macro's" does not seem feasible either - so I'm curious what it would entail to add support for expanding macro's work to unidoc.

[raboof]

Adding "-Xplugin:/home/aengelen/.ivy2/cache/org.scalamacros/paradise_2.12.8/jars/paradise_2.12.8-2.1.1.jar" to the unidoc scalacOptions seems to work, so that is promising

[alexklibisz]

Adding "-Xplugin:/home/aengelen/.ivy2/cache/org.scalamacros/paradise_2.12.8/jars/paradise_2.12.8-2.1.1.jar" to the unidoc scalacOptions seems to work, so that is promising

Can you give an example of this? I'm having trouble in a project that uses circe/macroparadise.

[raboof]

Ah, I should have been more specific: it works for me with macro usage, but not with macro definitions. I applied it to https://github.com/akka/akka-http/pull/2484/files in akka-http (the sbt side unfortunately is rather hacky).

[corey-at-protenus]

I had a similar issue: The unidoc task was failing with macro code. For our project, in scala 2.13, the solution was fairly simple:

1. filter the macro project from unidoc.
2. enable macro annotations

    ScalaUnidoc / unidoc / scalacOptions += "-Ymacro-annotations",
    ScalaUnidoc / unidoc / unidocProjectFilter := inAnyProject -- inProjects(projectMacros)

where projectMacros is a project that defines a macro annotation used by the other modules.

This seems to trick (?) unidoc to depending on the macro project per-usual. Getting the usual two stage compile needed by macros. Leaves out the macro docs but eh.