Home

Awesome

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.16"
}

Extending a StandardProject base

In general a project will extend either StandardServiceProject (if it's are an application) or StandardLibraryProject (if it's a library). It will then

A full project specification follows

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

class MyProject(info: ProjectInfo) extends StandardServiceProject(info) {
  val utilCore = "com.twitter" % "util-core" % "1.2.4"
  override def mainClass = Some("com.example.awesome.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

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].jar 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.

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

Enforces stronger maven/ivy dependency checking, and whines if there are version incompatibilities in the dependency tree.

DefaultRepos

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

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.

Ramdiskable

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.

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

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")

ArtifactoryPublisher

publish to a standard ibiblio resolver. This has odd interactions with SubversionPublisher for historical reasons. Be careful: you must mix this in after SubversionPublisher if you use both.

There are two additional environment variables that control the actual resolver used to publish.

  1. if SBT_PROXY_PUBLISH is set and proxyPublishRepo is defined, proxyPublishRepo is used
  2. if SBT_PROXY_PUBLISH_REPO is set, it is used as the root URL to publish to

Credentials are read from ~/.artifactory-credentials, and look like the following {code} realm=Artifactory Realm host=<your host> user=<you> password=<your password> {code}

Settings of interest

TartifactoryRepos

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

TartifactoryPublisher

Deprecated. See ArtifactoryPublisher.

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.