How do I build a project that uses sbt as its build system?

Question

I have downloaded a project which uses sbt as its build system and I want to build it. You'd think it would be as simple as typing "sbt" or something, but no.

I thought I'd add a question for this because it can take literally hours to figure this out on your own. I'm not joking.

Answer 1

tl;dr:

sbt compile

If you want to run it:

sbt run

To see what other targets are available:

sbt tasks

To get some (other) help, but mostly targeted at commands typed from the sbt console (ie, running sbt without parameters):

sbt help

This all assumes sbt version >= 0.10.0. To see what version of sbt is in use, do:

grep sbt.version project/build.properties

If there's no such file, and there's a file with extension ".sbt" on the base directory (not the project directory), then it's >= 0.10.0. Of course, if the grep works, it should tell you the version.

Answer 2

First, you'll want to use sbt-extras, because that automatically downloads and uses the right version of sbt. Trying to use the wrong version of sbt (newer or older than what the project you're trying to build says it requires) won't necessarily work, and may cause strange errors.

Run it:

~/path/to/sbt-extras/sbt

Wait for it to start up and download everything. If you need to use an authenticated proxy, you'll need to edit the script to specify the username and password for the proxy.

Check the version of Scala that sbt thinks it needs to build against (at the end of the output, if everything worked). If this is OK, fine, you don't need to do anything. If it isn't, you can temporarily specify a version explicitly with ++, e.g.:

++2.8.1

(If you want to make this permanent, you can edit the build definition files, but as that involves making a change to files under version control, that might not be what you want to do.)

Now, if you are using an older version of sbt, don't skip the next step! You could get strange errors if you do.

update

Now you can build and test what you've built:

test

If you get an error "Filename too long", this is not an sbt-specific problem, it's a scala problem, which most frequently affects Ubuntu users (technically, for Unbuntu users it's generally related to home directories encrypted with encfs). If you are using Scala >= 2.9, edit the build to use the scalac command-line option that allows you to specify a maximum filename length. Otherwise, if you are on Linux, you can redirect the build to /dev/shm or /tmp, by running these commands in a shell prompt (don't background sbt with CTRL+Z on Unix, because it may appear to stop working properly):

rm -rf target
ln -s /dev/shm target

(you may have to execute these commands in project/build instead or as well.)

Actually, it's probably better, and may even be more secure, to create a subdirectory of /dev/shm or /tmp and use that instead.

The compilation result should appear in target. You might then want to run it, if it's something you can run:

run

If everything looks OK, you can optionally publish the result locally so that the result can then be picked up automatically by other sbt builds:

publish-local