简单构建工具 Simple Build Tool

课程涵盖了SBT！详细主题包括：

创建一个sbt 工程
基本命令 basic commands
sbt 控制台
持续执行命令 continuous command execution
自定义你的工程 customizing your project
定制命令 custom commands
sbt 源码快速浏览（如果你有时间的话）

关于SBT

SBT 是一个流行的构建工具。它是用Scala 写的同时提供了一些Scala 特性，它是一个生成为目的的构建工具。

为什么选择SBT？

Sane(ish) 依赖管理
- lvy 依赖管理
- Only-update-on-request 模式
创建任务全Scala 支持 * 持续执行命令
在工程环境里运行REPL

启程

下载jar 文件
创建调用jar 文件的sbt shell 脚本，比如

java -Xmx521M -jar sbt-launch.jar "$@"

确保在当前路径下它（刚刚创建的sbt）是可执行的
运行sbt来创建你的工程

cal ~/projects]$ sbt
Project does not exist, create new project? (y/N/s) y
Name: sample
Organization: com.twitter
Version [1.0]: 1.0-SNAPSHOT
Scala version [2.7.7]: 2.8.1
sbt version [0.7.4]:      
Getting Scala 2.7.7 ...
:: retrieving :: org.scala-tools.sbt#boot-scala
	confs: [default]
	2 artifacts copied, 0 already retrieved (9911kB/221ms)
Getting org.scala-tools.sbt sbt_2.7.7 0.7.4 ...
:: retrieving :: org.scala-tools.sbt#boot-app
	confs: [default]
	15 artifacts copied, 0 already retrieved (4096kB/167ms)
[success] Successfully initialized directory structure.
Getting Scala 2.8.1 ...
:: retrieving :: org.scala-tools.sbt#boot-scala
	confs: [default]
	2 artifacts copied, 0 already retrieved (15118kB/386ms)
[info] Building project sample 1.0-SNAPSHOT against Scala 2.8.1
[info]    using sbt.DefaultProject with sbt 0.7.4 and Scala 2.7.7
>

注意项目以SNAPSHOT 版本开始是一个不错的惯例。

项目轮廓

project - 工程定义文件
- project/build/.scala - 主要的个工程定义文件
- project/build/.properties - 工程，sbt 和scala 版本定义
src/main - 你的应用代码放在这，在一个说明代码语言的子目录里（比如，src/main/scala,src/main/java）
src/main/resources - 你想要放到jar 包里面的静态文件（比如，日志文件）
src/test - 和src/main 类似，不过使用来测试用的
lib_managed - 你工程依赖的jar 文件。通过sbt update 填充
target - 生成内容的地方，（比如生成的临时代码，class 文件，jars）

添加代码

我们将为简单的tweets 创建一个简单的JSON 解析器。把下面代码添加到/src/main/scala/com/twitter/sample/SimpleParser.scala

package com.twitter.sample

case class SimpleParsed(id: Long, text: String)

class SimpleParser {

  val tweetRegex = "\"id\":(.*),\"text\":\"(.*)\"".r

  def parse(str: String) = {
    tweetRegex.findFirstMatchIn(str) match {
      case Some(m) => {
        val id = str.substring(m.start(1), m.end(1)).toInt
        val text = str.substring(m.start(2), m.end(2))
        Some(SimpleParsed(id, text))
      }
      case _ => None
    }
  }
}

这代码很丑陋有很多bug，不过还好可以编译。

在控制台里面测试

SBT 可以被当做一个命令行脚本或者一个构建控制台。我们将主要把它当做构建控制台，但是更多的命令可以作为SBT 的一个参数传入命令单独运行，比如

sbt test

注意如果命令接受参数，你需要给整个参数路径加引号，比如

sbt 'test-only com.twitter.sample.SampleSpec'

方式很奇怪。

不管怎样，用我们的代码来运行，启动sbt

[local ~/projects/sbt-sample]$ sbt
[info] Building project sample 1.0-SNAPSHOT against Scala 2.8.1
[info]    using sbt.DefaultProject with sbt 0.7.4 and Scala 2.7.7
>

SBT 允许你在所有的工程依赖里加载一个Scala REPL。它在运行控制台之前编译你的项目源文件，给我们提供一个快速的解析方法。

> console
[info] 
[info] == compile ==
[info]   Source analysis: 0 new/modified, 0 indirectly invalidated, 0 removed.
[info] Compiling main sources...
[info] Nothing to compile.
[info]   Post-analysis: 3 classes.
[info] == compile ==
[info] 
[info] == copy-test-resources ==
[info] == copy-test-resources ==
[info] 
[info] == test-compile ==
[info]   Source analysis: 0 new/modified, 0 indirectly invalidated, 0 removed.
[info] Compiling test sources...
[info] Nothing to compile.
[info]   Post-analysis: 0 classes.
[info] == test-compile ==
[info] 
[info] == copy-resources ==
[info] == copy-resources ==
[info] 
[info] == console ==
[info] Starting scala interpreter...
[info] 
Welcome to Scala version 2.8.1.final (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_22).
Type in expressions to have them evaluated.
Type :help for more information.

scala>

我们的代码编译后，我们可以输入Scala 命令。我们会创建一个新的解析器，一个复制的tweet，一个明确的”任务“。

scala> import com.twitter.sample._            
import com.twitter.sample._

scala> val tweet = """{"id":1,"text":"foo"}"""
tweet: java.lang.String = {"id":1,"text":"foo"}

scala> val parser = new SimpleParser          
parser: com.twitter.sample.SimpleParser = com.twitter.sample.SimpleParser@71060c3e

scala> parser.parse(tweet)                    
res0: Option[com.twitter.sample.SimpleParsed] = Some(SimpleParsed(1,"foo"}))

scala>

增加依赖

我们针对这个很小集合输入的简单解析工作了，但是我们想要打断它插入一个测试。第一步是添加specs 测试类库以及给我们的项目添加一个真正的JSON 解析。为了做到这点，我们不得不在默认SBT 轮廓之外创建一个项目。

SBT 把project/build 路径下的Scala 文件当做项目定义。把下面的代码添加到project/build/SampleProject.scala。

mport sbt._

class SampleProject(info: ProjectInfo) extends DefaultProject(info) {
  val jackson = "org.codehaus.jackson" % "jackson-core-asl" % "1.6.1"
  val specs = "org.scala-tools.testing" % "specs_2.8.0" % "1.6.5" % "test"
}

一个项目的定义是一个SBT class。在这里我们扩展了SBT DefaultProject。

你通过val 声明一个依赖。SBT 使用反射来扫描你项目里的所有的依赖vals 然后在构建时创建一个依赖树。语法看起来可能有些陌生，但是它和maven 以来差不多。

<dependency>
    <groupId>org.codehaus.jackson</groupId>
    <artifactId>jackson-core-asl</artifactId>
    <version>1.6.1</version>
</dependency>
<dependency>
    <groupId>org.scala-tools.testing</groupId>
    <artifactId>specs_2.8.0</artifactId>
    <version>1.6.5</version>
    <scope>test</scope>
</dependency>

现在我可以给我们的工程下载依赖了。从命令行（不是sbt 控制台），运行sbt update

[local ~/projects/sbt-sample]$ sbt update
[info] Building project sample 1.0-SNAPSHOT against Scala 2.8.1
[info]    using SampleProject with sbt 0.7.4 and Scala 2.7.7
[info] 
[info] == update ==
[info] :: retrieving :: com.twitter#sample_2.8.1 [sync]
[info] 	confs: [compile, runtime, test, provided, system, optional, sources, javadoc]
[info] 	1 artifacts copied, 0 already retrieved (2785kB/71ms)
[info] == update ==
[success] Successful.
[info] 
[info] Total time: 1 s, completed Nov 24, 2010 8:47:26 AM
[info] 
[info] Total session time: 2 s, completed Nov 24, 2010 8:47:26 AM
[success] Build completed successfully.

你会看到sbt 检索specs 库。你现在将要拥有一个lib_managed 库，同时lib_managed/scala_2.8.1/test 将有specs_2.8.0-1.6.5.jar

添加测试

现在我们添加了测试类库，把下面的代码放到 src/test/scala/com/twitter/sample/SimpleParserSpec.scala

package com.twitter.sample

import org.specs._

object SimpleParserSpec extends Specification {
  "SimpleParser" should {
    val parser = new SimpleParser()
    "work with basic tweet" in {
      val tweet = """{"id":1,"text":"foo"}"""
      parser.parse(tweet) match {
        case Some(parsed) => {
          parsed.text must be_==("foo")
          parsed.id must be_==(1)
        }
        case _ => fail("didn't parse tweet")
      }
    }
  }
}

在sbt 控制台里，运行测试

> test
[info] 
[info] == compile ==
[info]   Source analysis: 0 new/modified, 0 indirectly invalidated, 0 removed.
[info] Compiling main sources...
[info] Nothing to compile.
[info]   Post-analysis: 3 classes.
[info] == compile ==
[info] 
[info] == test-compile ==
[info]   Source analysis: 0 new/modified, 0 indirectly invalidated, 0 removed.
[info] Compiling test sources...
[info] Nothing to compile.
[info]   Post-analysis: 10 classes.
[info] == test-compile ==
[info] 
[info] == copy-test-resources ==
[info] == copy-test-resources ==
[info] 
[info] == copy-resources ==
[info] == copy-resources ==
[info] 
[info] == test-start ==
[info] == test-start ==
[info] 
[info] == com.twitter.sample.SimpleParserSpec ==
[info] SimpleParserSpec
[info] SimpleParser should
[info]   + work with basic tweet
[info] == com.twitter.sample.SimpleParserSpec ==
[info] 
[info] == test-complete ==
[info] == test-complete ==
[info] 
[info] == test-finish ==
[info] Passed: : Total 1, Failed 0, Errors 0, Passed 1, Skipped 0
[info]  
[info] All tests PASSED.
[info] == test-finish ==
[info] 
[info] == test-cleanup ==
[info] == test-cleanup ==
[info] 
[info] == test ==
[info] == test ==
[success] Successful.
[info] 
[info] Total time: 0 s, completed Nov 24, 2010 8:54:45 AM
>

我们的测试工作了！现在我们来添加更多。SBT 提供的更好的方式是运行触发行为。Prefacing 一个含有tilde 的动作会开始一个循环，它会在源文件改变时运行。让我们运行run～test 看看会发生什么。

[info] == test ==
[success] Successful.
[info] 
[info] Total time: 0 s, completed Nov 24, 2010 8:55:50 AM
1. Waiting for source changes... (press enter to interrupt)

现在让我们来添加下面的测试用例

"reject a non-JSON tweet" in {
      val tweet = """"id":1,"text":"foo""""
      parser.parse(tweet) match {
        case Some(parsed) => fail("didn't reject a non-JSON tweet")
        case e => e must be_==(None)
      }
    }

    "ignore nested content" in {
      val tweet = """{"id":1,"text":"foo","nested":{"id":2}}"""
      parser.parse(tweet) match {
        case Some(parsed) => {
          parsed.text must be_==("foo")
          parsed.id must be_==(1)
        }
        case _ => fail("didn't parse tweet")
      }
    }

    "fail on partial content" in {
      val tweet = """{"id":1}"""
      parser.parse(tweet) match {
        case Some(parsed) => fail("didn't reject a partial tweet")
        case e => e must be_==(None)
      }
    }

当我们保存文件的时候，SBT 检测到改变，运行测试，然后通知我们我们的解析是lame

[info] == com.twitter.sample.SimpleParserSpec ==
[info] SimpleParserSpec
[info] SimpleParser should
[info]   + work with basic tweet
[info]   x reject a non-JSON tweet
[info]     didn't reject a non-JSON tweet (Specification.scala:43)
[info]   x ignore nested content
[info]     'foo","nested":{"id' is not equal to 'foo' (SimpleParserSpec.scala:31)
[info]   + fail on partial content

现在让我们重新开始我们更真实的的JSON 解析

package com.twitter.sample

import org.codehaus.jackson._
import org.codehaus.jackson.JsonToken._

case class SimpleParsed(id: Long, text: String)

class SimpleParser {

  val parserFactory = new JsonFactory()

  def parse(str: String) = {
    val parser = parserFactory.createJsonParser(str)
    if (parser.nextToken() == START_OBJECT) {
      var token = parser.nextToken()
      var textOpt:Option[String] = None
      var idOpt:Option[Long] = None
      while(token != null) {
        if (token == FIELD_NAME) {
          parser.getCurrentName() match {
            case "text" => {
              parser.nextToken()
              textOpt = Some(parser.getText())
            }
            case "id" => {
              parser.nextToken()
              idOpt = Some(parser.getLongValue())
            }
            case _ => // noop
          }
        }
        token = parser.nextToken()
      }
      if (textOpt.isDefined && idOpt.isDefined) {
        Some(SimpleParsed(idOpt.get, textOpt.get))
      } else {
        None
      }
    } else {
      None
    }
  }
}

这是一个简单的Jackson 解析。当我们保存的时候，SBT 重新编译我们的代码然后重新运行测试。让它更好！

info] SimpleParser should
[info]   + work with basic tweet
[info]   + reject a non-JSON tweet
[info]   x ignore nested content
[info]     '2' is not equal to '1' (SimpleParserSpec.scala:32)
[info]   + fail on partial content
[info] == com.twitter.sample.SimpleParserSpec ==

恩，我们需要检查伴生类。让我们添加一些丑陋的guard 来给我们的reading loop。

def parse(str: String) = {
    val parser = parserFactory.createJsonParser(str)
    var nested = 0
    if (parser.nextToken() == START_OBJECT) {
      var token = parser.nextToken()
      var textOpt:Option[String] = None
      var idOpt:Option[Long] = None
      while(token != null) {
        if (token == FIELD_NAME && nested == 0) {
          parser.getCurrentName() match {
            case "text" => {
              parser.nextToken()
              textOpt = Some(parser.getText())
            }
            case "id" => {
              parser.nextToken()
              idOpt = Some(parser.getLongValue())
            }
            case _ => // noop
          }
        } else if (token == START_OBJECT) {
          nested += 1
        } else if (token == END_OBJECT) {
          nested -= 1
        }
        token = parser.nextToken()
      }
      if (textOpt.isDefined && idOpt.isDefined) {
        Some(SimpleParsed(idOpt.get, textOpt.get))
      } else {
        None
      }
    } else {
      None
    }
  }

它生效了！

打包和部署

在这里我们可以运行package 命令来生成jar 文件。不管怎样，我们可能想要和我们的团队共享我们的jar 文件。为了做到这一点我们将要构建与标准工程，这将会给我们一个大的头部开始。

第一步就是在SBT plugin 里面包含StandardProject 。插件是给你的构建引入依赖的一种方式，和你的project 一样。这些依赖定义在project/plugins/Plugins.scala 里。把下面的代码添加到你的Plugins.scala 文件里。

import sbt._

class Plugins(info: ProjectInfo) extends PluginDefinition(info) {
  val twitterMaven = "twitter.com" at "http://maven.twttr.com/"
  val defaultProject = "com.twitter" % "standard-project" % "0.7.14"
}

注意我们指定了一个maven 开发库做为依赖。这是因为标准的工程类库是被我们托管的，它不是默认检查的sbt 开发库。

我们也个呢更新我们的project 定义来扩展StandardProject，包括SVN 发布trait，以及定义开发库做为希望发布的那样。把SampleProject.scala 按如下修改

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

class SampleProject(info: ProjectInfo) extends StandardProject(info) with SubversionPublisher {
  val jackson = "org.codehaus.jackson" % "jackson-core-asl" % "1.6.1"
  val specs = "org.scala-tools.testing" % "specs_2.8.0" % "1.6.5" % "test"

  override def subversionRepository = Some("http://svn.local.twitter.com/maven/")
}

现在如果我们运行publish 命令我们会看到如下

[info] == deliver ==
IvySvn Build-Version: null
IvySvn Build-DateTime: null
[info] :: delivering :: com.twitter#sample;1.0-SNAPSHOT :: 1.0-SNAPSHOT :: release :: Wed Nov 24 10:26:45 PST 2010
[info] 	delivering ivy file to /Users/mmcbride/projects/sbt-sample/target/ivy-1.0-SNAPSHOT.xml
[info] == deliver ==
[info] 
[info] == make-pom ==
[info] Wrote /Users/mmcbride/projects/sbt-sample/target/sample-1.0-SNAPSHOT.pom
[info] == make-pom ==
[info] 
[info] == publish ==
[info] :: publishing :: com.twitter#sample
[info] Scheduling publish to http://svn.local.twitter.com/maven/com/twitter/sample/1.0-SNAPSHOT/sample-1.0-SNAPSHOT.jar
[info] 	published sample to com/twitter/sample/1.0-SNAPSHOT/sample-1.0-SNAPSHOT.jar
[info] Scheduling publish to http://svn.local.twitter.com/maven/com/twitter/sample/1.0-SNAPSHOT/sample-1.0-SNAPSHOT.pom
[info] 	published sample to com/twitter/sample/1.0-SNAPSHOT/sample-1.0-SNAPSHOT.pom
[info] Scheduling publish to http://svn.local.twitter.com/maven/com/twitter/sample/1.0-SNAPSHOT/ivy-1.0-SNAPSHOT.xml
[info] 	published ivy to com/twitter/sample/1.0-SNAPSHOT/ivy-1.0-SNAPSHOT.xml
[info] Binary diff deleting com/twitter/sample/1.0-SNAPSHOT
[info] Commit finished r977 by 'mmcbride' at Wed Nov 24 10:26:47 PST 2010
[info] Copying from com/twitter/sample/.upload to com/twitter/sample/1.0-SNAPSHOT
[info] Binary diff finished : r978 by 'mmcbride' at Wed Nov 24 10:26:47 PST 2010
[info] == publish ==
[success] Successful.
[info] 
[info] Total time: 4 s, completed Nov 24, 2010 10:26:47 AM

过一会儿以后，我们可以到binaries.local.twitter.com:http://binaries.local.twitter/maven/com/twitter/sample/1.0-SNAPSHOT/ 来找到publish.jar。

添加任务

任务就是Scala 函数，添加任务的最简单方法就是在工程定义里面用task 方法来include 一个val，比如。

lazy val print = task {log.info("a test action"); None}

如果你想要添加依赖和描述你可以向这样

lazy val print = task {log.info("a test action"); None}.dependsOn(compile) describedAs("prints a line after compile")

如果你重新加载我们的工程并且运行print 命令，你会看到如下

> print
[info] 
[info] == print ==
[info] a test action
[info] == print ==
[success] Successful.
[info] 
[info] Total time: 0 s, completed Nov 24, 2010 11:05:12 AM
>

因此，它工作了，如果你在单个项目里定义一个任务，这个任务还好。无论如何，如果你把它定义在一个插件里会相当的代办。我会这么办

lazy val print = printAction
def printAction = printTask.dependsOn(compile) describedAs("prints a line after compile")
def printTask = task {log.info("a test action"); None}

它允许消费者重载任务本身，任务的依赖和/或描述，或者是动作。更多的SBT 构建行为遵循这个模式。做为例子，我们修改了builtin 包task，来打印当前处理的时间戳。

lazy val printTimestamp = task { log.info("current time is " + System.currentTimeMillis); None}
override def packageAction = super.packageAction.dependsOn(printTimestamp)

StandardProject 有一些调整默认SBT 和订制任务的例子。

快速参考

一般命令

actions - 显示这个项目里的可见命令
update - 下载依赖
compile - 编译源
test - 运行测试
package - 创建可发布的jar 文件
publish-local - 在你的local ivy 缓存里安装build jar
publish - 把你的jar 文件放入到远程repo 里（如果配置的话）

Moar 命令

test-failed - 运行任何失败的specs
test-quick - 运行任何失败的并且或者有依赖更新的specs
clean-cache - 清空各种sbt 缓存文件。和sbt clean 类似
clean-lib - 清空lib_managed 里的一切

项目轮廓

TBD