Standard-project is a basic set of extensions to sbt to codify best practices.
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"
}
In general a project will extend either
StandardServiceProject (if it's are an application) or
StandardLibraryProject (if it's a library). It will then
- Specify its specific dependencies
- Optionally specify its main class
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")
}
Instead of extending SBT's DefaultProject or DefaultParentProject, standard-project provides the following project classes you can extend.
This extends SBT's DefaultProject, and mixes in the following traits
- StandardManagedProject
- DependencyChecking
- PublishLocalWithMavenStyleBasePattern
- PublishSourcesAndJavadocs
- BuildProperties
- Ramdiskable
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.
Extends SBT's ParentProject and mixes in StandardManagedProject. This pretty much just lets you have subproject in a StandardProject setting.
Extends StandardProject and mixes in PackageDist. This is intended for use by libraries, i.e. projects that don't package and distribute an executable.
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
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.
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
Enforces stronger maven/ivy dependency checking, and whines if there are version incompatibilities in the dependency tree.
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. (deprecated)
If none of these are set, it falls back to a list of "standard" repos.
Fails the build if your managed libraries directory doesn't exist
(i.e. you haven't run sbt update)
Adds an action to generate a .ensime file for the project. Should really be a processor.
Sets up a Map representation of the current environment in the val "environment"
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")
Adds several utilities to tag/commit/check the current git tree
Support for publishing artifacts to github.
Predecessor of AdhocInlines??? Used by AdhocInlines???
Adds an integration-test action that will run all specs that end with "IntegrationSpec". Also excludes all IntegrationSpecs from the regular test actian.
Adds all jar files in "lib" to the classpath. Semi-deprecated?
Scary stuff I don't understand very well.
Make SBT bitch more about version mismatches?
Adds a package-dist action that wraps up scala stuff into our standard zip layout for deploys.
Used to avoid multiple instantiation of projects across inline/birdcage builds.
Predecessor to AdhocInlines?
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.
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.
make publish and publish-local build/package/publish a -javadoc.jar and -sources.jar. Makes IDE users happy.
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.
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.
Support for getting git shas into currentRevision
Mixes in
- SourceControlledProject
- ReleaseManagement
- Versions
- Environmentalist
Also disables cross compiling, sets managed style to maven and clears your local repo list
Have Ivy resolve conflicts by failing the build.
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")
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.
- if SBT_PROXY_PUBLISH is set and proxyPublishRepo is defined, proxyPublishRepo is used
- 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= user= password= {code}
- proxyPublishRepo: Option[String] - the base url of the repo to publish to.
- proxyQualifier: String - used to build up proxyRepoPublishTarget
- proxySnapshotOrRelease: String - used to define the resolver type as well as build up proxyRepoPublishtarget
- proxyRepoPublishTarget: String - the uri within proxyPublishRepo to publish to. Defaults to {code} "libs-%ss-%s".format(proxySnapshotOrRelease, proxyQualifier) {code}
- proxyPublish: Boolean - whether or not to use the proxy to publish. Defaults to {code} environment.get("SBT_CI").isDefined {code}
- repositories: Seq[Resolver] - adds the proxy resolver to repositories if it's defined
Sort of deprecated, more or less does what DefaultRepos does now. Use DefaultRepos instead.
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.
Allow preprocessing of source files using fmpp?
Overrides publish/deliver to do nothing
Adds tasks for bumping the major, minor and patch versions of a project.