A quick guide to setting up Simple Build Tool (SBT) to work on the dojo projects.

This assumes you have already got scala and obtained the dojo projects. If not, you should do that first.

Install Simple Build Tool

1. Download the SBT jar file from the project home page (http://code.google.com/p/simple-build-tool) and put it somewhere safe. I put mine in /usr/local/bin.

2. Create an SBT launch script. On Linux / Mac this could be /usr/local/bin/sbt. It needs to be on your PATH and don't forget to make it executable.

On Linux this would be something like:

#!/bin/bash

java -Xmx512M -jar `dirname $0`/sbt-launch.jar "$@"

On Windows:

set SCRIPT_DIR=%~dp0
java -Xmx512M -jar "%SCRIPT_DIR%sbt-launch.jar" %*

More detailed instructions on this can be found here.

3. Now you should be able to run the sbt command and see some output like:

Project does not exist, create new project? (y/N/s)

If you see the above message then you know you have SBT installed ok.

Configure the project

There are a couple of options here. SBT supports nested projects so we can configure a project file that handles minesweeper as well as any future dojo projects. Alternatively each project can be configured separately with its own independent project file.

Let's set up a parent project with minesweeper as a sub-project.

1. Open a terminal and cd into the top level of your cloned git repository.

2. Run the sbt command and you should see:

Project does not exist, create new project? (y/N/s)

3. Enter y to create a new project and SBT will prompt you for some information about the project. This will end up in your <project root>/project/build.properties file.

Enter something like the following:

Name: LSUG Dojo
Organization: LSUG
Version [1.0]: <enter>
Scala version [2.7.7]: 2.8.0
sbt version [0.7.4]: <enter>

SBT now downloads and builds some of its own dependencies. Note: It doesn't matter that SBT compiles itself using Scala 2.7.7, it can still build your projects using Scala 2.8.

4. At this point, if your project has a maven pom file, sbt can usually figure out how to build it (try sbt update compile and see what happens). If not, or if as in this case we want to configure things in a slightly different way, we need to create a project file. Projects are configured using Scala and the SBT API and they live in the directory <project root>/project/build. If this doesn't exist, you should create it now.

5. Now to create our project configuration file. The project file can be called anything you want, as ours will contain definitions for sub-projects, let's call it DojoProjects.scala.

// <project root>/project/build/DojoProjects.scala

import sbt._

/**
 * Main project class extends ParentProject because it will contain sub-projects.
 * See: http://code.google.com/p/simple-build-tool/wiki/SubProjects for details.
 */
class DojoProjects(info: ProjectInfo) extends ParentProject(info) { 
  
  // Create a reference for the minesweeper sub-project
  lazy val minesweeper = project("minesweeper-dojo", "Minesweeper Dojo", new Minesweeper(_))  
  
  // Here is the actual configuration for the minesweeper project, note we extend DefaultProject here.
  // This could also be defined as a separate project file inside the minesweeper project.
  class Minesweeper(info: ProjectInfo) extends DefaultProject(info) {

    // Specify sub-project specific dependencies using SBT's DSL for doing so.
    // If you need any other repositories apart from the default ones, these could be registered here also
    // or in the parent project. See: http://code.google.com/p/simple-build-tool/wiki/LibraryManagement    
    val junit = "junit" % "junit" % "4.8.1"    
    val scalatest = "org.scalatest" % "scalatest" % "1.2"  
  }
}

6. If you now start the SBT console by entering the command sbt the project file will be compiled. If the console was already running you can use the reload action to re-compile the project file.

7. In the SBT console you should now run sbt update to fetch any missing dependencies.

8. When working with sub-projects you can use the projects command to list the available projects. Doing so here should yield:

> projects
	Minesweeper Dojo 1.0
	LSUG Dojos 1.0

9. Let's switch to the minesweeper project by giving the project command the name of the project to switch to:

> project Minesweeper Dojo
Set current project to Minesweeper Dojo 1.0

10. We're now in a position to start working with the minesweeper project. We can use the test command to build and run our tests however, at this point SBT (which integrates with ScalaTest) won't be able to see our tests which are implemented using JUnit. We'll see something like this in the output:

[info] == test-finish ==
[info] No tests to run.
[info] == test-finish ==

For SBT to be able to automatically find and run our tests we need our test suites to extend org.scalatest.junit.JUnitSuite.

11. We need to modify BoardReaderTest so that it extends JUnitSuite.

import org.scalatest.junit.JUnitSuite
import org.junit.Test
import org.junit.Assert.assertThat
import org.hamcrest.CoreMatchers._

class BoardReaderTest extends JUnitSuite { ... }

Now when you run sbt test to build and run you should see some test results. Hopefully with no failures!

[info] == test-finish ==
[error] Failed: : Total 6, Failed 2, Errors 0, Passed 3, Skipped 1
[info] == test-finish ==

12. Housekeeping - you might want to add the following to your .gitignore file(s) to keep things clean:

target 
lib_managed 
src_managed 
project/boot 
project/build/target

13. That's pretty much it. You can compile your main source with the compile command, your tests with the test-compile command. And you could even run your tests continuously as you code by adding a ~ before the test command, like so ~test. Then your tests will be run each time you save a file. For more details on the available commands try the help and actions commands. There is also loads more detail on the usage of SBT here http://code.google.com/p/simple-build-tool/wiki/RunningSbt and here http://code.google.com/p/simple-build-tool/wiki/TriggeredExecution.

This has been a very brief intro to using SBT and it can do much more than just compile and run your projects. So it's well worth reading through the documentation here: http://code.google.com/p/simple-build-tool

As SBT files don't conflict with Maven (or IntelliJ as far as I know) we could possibly commit this configuration into the repository for everyone to use. But that's a decision which is up to the Dojo to decide.