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)

score 6 · Accepted Answer · answered Nov 15 '13 at 20:29

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?

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. — 0__, Nov 15 '13 at 20:35
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. — 0__, Nov 15 '13 at 20:56

score 3 · Answer 2 · answered Nov 15 '13 at 20:00

3

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.

answered Nov 15 '13 at 20:00

jsuereth

5,604
40
40

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? – 0__ Nov 15 '13 at 20:05
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? – jsuereth Nov 16 '13 at 19:51
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. – 0__ Nov 17 '13 at 11:24

sbt ignores my scaladoc settings

2 Answers2