sbt - RootProject and ProjectRef

Question

I have been trying to find more information on RootProject and ProjectRef, but looks like it is not mentioned at all in sbt documentation.

I understand that if you are referencing a root project you should use RootProject and ProjectRef when you are referencing a sub-project. However it is not clear how the behavior will be different between them. Can somebody please help explain?

Also the fact that it is not documented, does it mean that RootProject and ProjectRef are not the recommended way to reference other sbt projects?

Thanks.

Answer 1

A single sbt build has a single project/ directory for .scala build definitions and plugin definitions. There can be multiple subprojects within that build with their own .sbt files, but not their own project/*.scala files.

When you want to include other, separate builds directly instead of using their published binaries, you use "source dependencies". This is what RootProject and ProjectRef declare. ProjectRef is the most general: you specify the location of the build (a URI) and the ID of the project in the build (a String) that you want to depend on. RootProject is a convenience that selects the root project for the build at the URI you specify.

Source dependencies do have an overhead: startup time, memory usage, and command line usability. If the group of projects don't need to be separate, it is best to use a single build with standard subprojects.