sbt ignores my scaladoc settings

Question

I am trying to follow the sbt documentation for scaladoc generation. I have a multi project (i.e. aggregate with sub-projects) build which was a ./build.sbt for general settings. I added the last entry in the following example:

scalacOptions in ThisBuild ++= Seq("-deprecation", "-unchecked", "-feature")

scalacOptions in ThisBuild += "-no-specialization"

// API docs
scalacOptions in ThisBuild in (Compile,doc) ++= Seq(
  "-diagrams", "-doc-title", name.value
)

This doesn't have any effect. Neither does scaladoc attempt to generate diagrams, nor is the main document title set, so simply these settings are ignored. Likewise, if I add a "-foobar" option, no error appears.

How to fix this (in build.sbt, I don't want to go into project/Build.scala, thanks)

Oquendo

Answer 1

So as Josh said, somehow the ThisBuild / ThisProject stuff overwrites each other.

The solution was to migrate the project/Build.sbt from the sbt 0.12 times into build.sbt, which fortunately was mostly copy + paste, as sbt 0.13 now accepts a lot of normal Scala code in there (not objects, though...).

I then defined

lazy val commonSettings = Project.defaultSettings ++ Seq(
  ...
  scalacOptions  ++= Seq(
    "-no-specialization",
    // "-Xelide-below", "INFO", // elide debug logging!
    "-deprecation", "-unchecked", "-feature"
  ),
  // API docs:
  scalacOptions in (Compile, doc) ++= Seq(
    "-diagrams",
    "-diagrams-dot-path", "/usr/local/bin/dot",
    // "-diagrams-dot-timeout", "20", "-diagrams-debug",
    "-doc-title", name.value
  ),
  ...
)

And it works.

---

The last annoying bit is the requirement for "-diagrams-dot-path", this truly sucks as it is an open source project, and I don't want to force that path onto anyone else. Why the heck doesn't it find dot on my $PATH which does include /user/local/bin?

Oquendo

OS X madness: bash $PATH is not seen by desktop applications. Since I run sbt from within IntelliJ IDEA, sys.env("PATH") is almost empty. My guess is adding /usr/local/bin to a PATH entry in ~/.MacOSX/environment.plist might solve this. – Oquendo

This works. One must be careful to include /usr/bin:/bin:/usr/sbin:/sbin in the PATH entry of environment.plist, because defining that entry otherwise overrides the default (these two paths). Afterwards, system needs reboot, and dot will be found by scaladoc. – Oquendo

Answer 2

So, if you run inspect on the doc task, you'll find that the setting sbt is looking for is:

scalacOptions in ThisProject in (Compile, doc)

ThisBuild is reserved for things that are re-used across projects (or shared that way), like scalaVersions.

Now, the issue is that scalacOptions in ThisProject in (Compile,doc) will first read from scalacOptions in ThisProject in Compile before checking scalacOptions in ThisProject before going down to ThisBuild.

Most likely, something is specifying the scalacOptions at a higher precedence and your setting is ignored. You should drop the in ThisBuild and things should work for the root project.

Underfur

Not sure I understand. If I change to in ThisProject the result is the same—no diagrams. If I add the options directly to main scalacOptions, scaladoc produces diagrams, but the normal compilation fails because option -diagrams not understood. If I drop in ThisBuild for the main scalacOptions, they are not applied to my different sub projects. I thought the whole point of sbt settings management is that when I use ++=, dependencies are smartly coalesced and not overwritten? – Oquendo

Ah, so you have subprojects? The hierarchy of setting inherentance for scaladoc requires you to re-specify the scaladoc settings on each project. That's perhaps a limitation of how we pull settings, but a few inspect tree compile:doc commands and that'll show you where we're getting the settings. The common settings approach you list below is definitely a good one. I'd like to merge that with this one to make sure the description of setting inheritance is included. Does what I wrote make sense or does it need expanded? – Underfur

Yes, it has subprojects. Still not sure I understand your approach. Running inspect doc just gives me myroot/compile:doc::scalacOptions. Running inspect tree compile:doc also doesn't make my brain understand what is going on. But yes, feel free to merge the common settings approach, it worked for me. – Oquendo