Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 279 lines (176 sloc) 7.642 kb

standard-project

Standard-project is a basic set of extensions to sbt to codify best practices.

General Usage

Getting StandardProject

To make a plugin available to your project definition you need to create a file called "Plugins.scala" in the project/plugins directory of your project. This is pretty straightforward boilerplate. An example is

import sbt._

class Plugins(info: ProjectInfo) extends PluginDefinition(info) {
    val twitterRepo = "twitter-repo" at "http://maven.twttr.com/"
    val standardProject = "com.twitter" % "standard-project" % "0.11.36-NEST"
 }

Extending a StandardProject base

In general most projects will extend either StandardServiceProject (if they are an application) or StandardLibraryProject (if they're a library). They will then

  • Specify their specific dependencies
  • Optionally specify their main class

A full project specification follows

import sbt._
import com.twitter.sbt._

class MyProject(info: ProjectInfo) extends StandardServiceProject(info) {
  val util = "com.twitter" % "util" % "1.2.4"
  override def mainClass = Some("com.twitter.MyClass")
}

Reference

Extensible Classes

Instead of extending SBT's DefaultProject or DefaultParentProject, standard-project provides the following project classes you can extend.

StandardProject

This extends SBT's DefaultProject, and mixes in the following traits

  • StandardManagedProject
  • DependencyChecking
  • PublishLocalWithMavenStyleBasePattern
  • BuildProperties

It sets up an optional ivy cache directory specified by the SBT_CACHE environment variable, and sets up a resolver to point to "libs", allowing you to stick jars of the form [artifact]-[revision] in libs.

The Scala/Java compile order is set to JavaThenScala, and some handy default compile options are set.

The test action is overridden to allow disabling by setting the environment variable NO_TESTS to 1.

Finally, it provides the capability to compile to a ramdisk instead of the regular "target" subdirectory. If the environment SBT_RAMDISK_ROOT is set, a target-ramdisk directory will be softlinked to SBT_RAMDISK_ROOT and will be used as the output path.

StandardParentProject

Extends SBT's ParentProject and mixes in StandardManagedProject. This pretty much just lets you have subproject in a StandardProject setting.

StandardLibraryProject

Extends StandardProject and mixes in PackageDist. This is intended for use by libraries, i.e. projects that don't package and distribute an executable.

StandardServiceProject

Extends StandardProject and mixes in PackageDist. This is intended for use by "services", i.e. those applications that package and distribute something with a commonly executed main method

Traits

AdhocInlines

Allows specifying dependencies that you have the source for, via the following construct

val util = "com.twitter" % "util" % "1.1.3" relativePath("util")

This tells SBT to build util from source when possible, and use the artifact it puts into target as your dependency. Using adhoc inlines allows you to more easily make changes across multiple projects.

In order to use AdhocInlines functionality you must set the SBT_ADHOC_INLINE environment variable.

BuildProperties

Generates an object that contains your build info, e.g.

// AUTOGENERATED BY STANDARD-PROJECT. TURN BACK WHILE YOU STILL CAN!
package com.twitter.sbt
object BuildInfo {
  val version = "0.11.12-SNAPSHOT"
  val date = "2011-04-14"
}

It will be placed into your projects main package as defined in build.properties

CorrectDependencies

????

DefaultRepos

Sets up a standard set of repositories for your project. It uses the following environment variables

  • SBT_PROXY_REPO - if defined, use the given url as the only resolver
  • SBT_OPEN_TWITTER - if defined, use Twitter's internal open-source artifactory repo as the only resolver. This is intended for use by open source projects that can't pull from Twitter's private repo
  • SBT_TWITTER - if defined, use Twitter's internal artifactory repo

If none of these are set, it falls back to a list of "standard" repos.

DependencyChecking

Fails the build if your managed libraries directory doesn't exist (i.e. you haven't run sbt update)

EnsimeGenerator

Adds an action to generate a .ensime file for the project. Should really be a processor.

Environmentalist

Sets up a Map representation of the current environment in the val "environment"

FileFilter

Simple token replacement for source files. To replace all instances of "@foo@" with "bar" in source and write it to destination, do

filter(source, destination, Map("foo" -> "bar")

GitHelpers

Adds several utilities to tag/commit/check the current git tree

GithubPublisher

Support for publishing artifacts to github.

InlineDependencies

Predecessor of AdhocInlines??? Used by AdhocInlines???

IntegrationSpecs

Adds an integration-test action that will run all specs that end with "IntegrationSpec". Also excludes all IntegrationSpecs from the regular test actian.

LibDirClasspath

Adds all jar files in "lib" to the classpath. Semi-deprecated?

ManagedClasspathFilter

Scary stuff I don't understand very well.

NoisyDependencies

Make SBT bitch more about version mismatches?

PackageDist

Adds a package-dist action that wraps up scala stuff into our standard zip layout for deploys.

ProjectCache

Used to avoid multiple instantiation of projects across inline/birdcage builds.

ProjectDependencies

Predecessor to AdhocInlines?

PublishLocalWithMavenStyleBasePattern

Force publish-local to lay things out maven style. There were problems in the past with publish-local'd ivy style artifacts not picking up transitive dependencies. Bludgeoning SBT into maven style for this action seemed to fix it.

PublishSite

Builds a dope website including a processed README.md, anything in your src/site directory, and your generated javadoc.

Also adds a task to publish said site to a git repo.

PublishSourcesAndJavadocs

make publish and publish-local build/package/publish a -javadoc.jar and -sources.jar. Makes IDE users happy.

ReleaseManagement

A helper for bumping versions and publishing artifacts. If you're releasing stable versions you should mix this in. If you mix it in you should only use this to bump versions in build.properties. It's better that way.

SourceControlledProject

Support for getting git shas into currentRevision

StandardManagedProject

Mixes in

  • SourceControlledProject
  • ReleaseManagement
  • Versions
  • Environmentalist

Also disables cross compiling, sets managed style to maven and clears your local repo list

StrictDependencies

Have Ivy resolve conflicts by failing the build.

SubversionPublisher

Publish to an SVN repository (which presumably then has some magic in place to get artifacts published to an actual publc repo). Typically used by overriding subversionRepository, e.g.

override def subversionRepository = Some("http://svn.me.com/repo")

TartifactoryRepos

Sort of deprecated, more or less does what DefaultRepos does now. Use DefaultRepos instead.

TartifactoryPublisher

Publish to an artifactory instance. You'll need to enter credentials at the command line for each publish, or override publishtask yourself.

TemplateProject

Allow preprocessing of source files using fmpp?

UnpublishedProject

Overrides publish/deliver to do nothing

Versions

Adds tasks for bumping the major, minor and patch versions of a project.

Something went wrong with that request. Please try again.