Add extraProjects and derivedProjects (formerly known as buildExtras and projectExtras)

[eed3si9n]

Fixes #2532

This adds support to generate synthetic subprojects from an auto plugin.

In addition, a method called projectOrigin is added to distinguish Organic, BuildExtra, ProjectExtra, and GenericRoot.

To generate subprojects, override buildExtras
method as follows:

import sbt._
import Keys._

object BuildExtrasPlugin extends AutoPlugin {
  override def buildExtras: Seq[Project] =
    List("foo", "bar", "baz") map generateProject

  def generateProject(id: String): Project =
    Project(id, file(id)).
      settings(
        name := id
      )
}

Subprojects may also be derived from an existing subproject
by overriding projectExtras.

import sbt._
import Keys._

object ProjectExtrasPlugin extends AutoPlugin {
  // Enable this plugin by default
  override def requires: Plugins = sbt.plugins.CorePlugin
  override def trigger = allRequirements

  override def projectExtras(proj: ProjectDefinition[_]): Seq[Project] =
    // Make sure to exclude project extras to avoid recursive generation
    if (proj.projectOrigin != ProjectOrigin.ProjectExtra) {
      val id = proj.id + "1"
      Seq(
        Project(id, file(id)).
          enablePlugins(DatabasePlugin)
      )
    }
    else Nil
}

/review @dwijnand, @Duhemm

[dwijnand]

Wow knocking them out the park this week, awesome.

I'm only concerned with the name buildExtras: for builds where all the projecrs are programmatically generated it sounds a bit weird. So I was thinking perhaps just "projects" (like we have projectSettings, not extraProjectSettings).

projectExtras I'm not sure of either, but I don't have any better suggestions.

[eed3si9n]

So I was thinking perhaps just "projects" (like we have projectSettings, not extraProjectSettings).

• If I call it projects that would imply both the organic one and synthetic ones.
• If I call it syntethicProjects or extras that would imply both the build-level and project-level.

buildExtras I think has a nice symmetry with buildSettings and easy to grasp what it would do.

[dwijnand]

I see the organic/synthetic project argument. But what's a project-level project?

[eed3si9n]

def projectExtras(proj: ProjectDefinition[_]): Seq[Project].
project-level extras allow you to generate a synthetic subproject from an existing stuff.

[dwijnand]

I see. Cool.

On Sat, 27 Aug 2016, 12:36 eugene yokota, notifications@github.com wrote:

def projectExtras(proj: ProjectDefinition[_]): Seq[Project].
project-level extras allow you to generate a synthetic subproject from an
existing stuff.

—
You are receiving this because you were mentioned.

Reply to this email directly, view it on GitHub
#2717 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAVCIvR7_JMVyMReQvQjAm1MrowZ1r6uks5qkBMrgaJpZM4JuqPL
.

[dwijnand]

Is this TODO right?

[eed3si9n]

It should be additional projectOrigin parameter, I guess.

[dwijnand]

I'm really happy to see progress, thank you.

Reviewed, some minor tweaks, but generally LGTM.

[eed3si9n]

Pushed a commit per reviews.

[mslinn]

Docs addressing motivation (why does this feature exist, what problems does it solve) would be helpful.

[clhodapp]

I agree 100% with @dwijnand's first comment. The feature itself here is absolutely terrific. That said, calling these "extras" feels really under-descriptive to me. There are innumerable "extra" things that could be generated by a plugin, so, as a user, why would I assume that the "extras" would be projects? Also, @dwijnand indicates, this naming would feel kind of weird if you were in a setting where most projects were generated (maybe someone defines a plugin in the future for opinionated builds described by a JSON dependencies file, for instance). Why not just call them generatedProjects and generatedSubprojects?

[clhodapp]

Or derivedProjects for the second one might be more accurate

[eed3si9n]

There are innumerable "extra" things that could be generated by a plugin, so, as a user, why would I assume that the "extras" would be projects?

A typical build user would not see the method name when they consume a plugin. This is mostly for advanced plugin authors.

I want the names that can be used as noun phrase like projectSettings and buildSettings that would distinguish the build- and project-level clearly. generatedProjects + derivedProjects are not bad, but they are more subtle because you can claim that both are "generated" and/or "derived" off of something like JSON. Can we come up with something that's unambiguous?

[ahjohannessen]

Why not just subProjects ?

[clhodapp]

How about independentProjects and derivedProjects?

One thing I'll note now that I've thought about it is that sbt's model doesn't even really include the notion of "subprojects" unless you count aggregation (which I don't think is in play here). There are just "projects". So isn't it a bit confusing to say that these generated projects are "subprojects"?

[mslinn]

I do not believe it is accurate to say SBT does not support the concept of subprojects. See dependsOn in the multi-project build page.

[eed3si9n]

ok. How about:

def extraProjects: Seq[Project]
def derivedProjects(proj: ProjectDefinition[_]): Seq[Project]

?

[clhodapp]

That combo is better than any one so far. From my point of view, the bikeshedding can stop with them ;). Thanks again for this great feature.

[clhodapp]

@mslinn That usage of "subproject" means "subproject of the build" not "subproject of another project" and is roughly synonymous with just "project".

[mslinn]

@clhodapp if this is going to be an ongoing source of confusion, the docs should introduce a term like "build subproject" or "subbuild" - I don't care if the b's are elided or not.

[eed3si9n]

Sent PR for the rename (#2738)