SBT directory structure. What's "project"?

Question

A play project has a "project" folder like this:

• project
  • target
  • project
    • target

I always thought this is just one of those life mysteries that I shouldn't think too much about, but today my curiosity got the best of me.

Googling gave me this which mentions that the top-level "project" folder is for sbt configuration. I wonder why they didn't call that ".sbt" a la ".git" and why there is still a file "build.sbt" outside that folder, but I suppose there is no fun in making things actually make sense.

It also doesn't mention why it contains another "project" folder inside it.

Why is there a nested "project" folder?

Priggery

Answer 1

http://www.scala-sbt.org/0.13/tutorial/Organizing-Build.html:

build.sbt conceals how sbt really works. sbt builds are defined with Scala code. That code, itself, has to be built. What better way than with sbt?

The project directory is another build inside your build, which knows how to build your build. To distinguish the builds, we sometimes use the term proper build to refer to your build, and meta-build to refer to the build in project. The projects inside the metabuild can do anything any other project can do. Your build definition is an sbt project.

And the turtles go all the way down. If you like, you can tweak the build definition of the build definition project, by creating a project/project/ directory.

Lawton

should have actually read the page... I just looked at the structure graph – Priggery

To elaborate on this, plugins for SBT are typically configured in the metabuild, since they need to be available to build your actual project. It's not typical to have a meta-metabuild...but you could. – Leasehold

FTR, we have a meta-meta-build in github.com/scala-js/scala-js, which contains a source generator that generates sources for the build project, i.e., for the meta-build. So yes, you can! – Raindrop

Would it make sense to add project directory to git? Most sbt gitignores don't ignore it, but I don't see why I should add it – Scopas

@Scopas Yes, of course it does. E.g. it's where SBT plugins are set up. The question is, why would you ignore it? – Lawton

Well I can delete it and it gets created when I run sbt build. – Scopas

It's project/target/ which will be created like that and it should already be ignored. All other contents of project will be lost, and they may be important. – Lawton

Answer 2

SBT is recursive. It defines build properties for your project with scala code. Where to place scala code? To the another project inside the current project. But if the project definition itself is a proper project then it can be configured with another sbt configuration. And so on. Scala guys like recursive structures.

You can change scala compiler version, scala compiler options for nested (in meta sense) projects. It probably can change the way the metaproject is interpreted and that can affect the upmost project.

Vet

"You can change scala compiler version" This is the one thing you shouldn't change, since for meta-builds it has to be the same version SBT itself uses. – Lawton