My favorites | Sign in
Project Home Downloads Wiki Issues
Search
for

sbt has moved

sbt has now completely moved to GitHub.

See https://github.com/harrah/xsbt/wiki.

Getting Started

Setup  

Featured
Updated Mar 14, 2012 by dmhar...@gmail.com

sbt has moved

sbt has now completely moved to GitHub.

See https://github.com/harrah/xsbt/wiki/Getting-Started-Setup.

Introduction

This page describes how to set up your project for use with sbt.

The basic steps are:

  1. Create a script to launch sbt.
  2. Create your project with sbt.
  3. Put libraries in lib and sources in src.
  4. Read RunningSbt for basic usage instructions.
  5. Read BuildConfiguration for further configuration.

Launching Sbt

The easiest way to launch sbt is to create a one-line script. Download sbt-launch.jar if you have not already.

Note: do not put sbt-launch.jar in your $SCALA_HOME/lib directory, your project's lib directory, or anywhere it will be put on a classpath.

Note: The encoding used by your terminal may differ from Java's default encoding for your platform. In this case, you will need to add the option -Dfile.encoding=<encoding> in the following scripts to set the encoding.

Unix

Put the jar in your ~/bin directory, put the line

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

in a file called sbt in your ~/bin directory and do

$ chmod u+x ~/bin/sbt

This allows you to launch sbt in any directory by typing sbt at the command prompt.

sbt will pick up any HTTP proxy settings from the http.proxy environment variable. If you are behind a proxy requiring authentication, you must in addition pass flags to set the http.proxyUser and http.proxyPassword properties:

java -Dhttp.proxyUser=username -Dhttp.proxyPassword=mypassword -Xmx512M -jar `dirname $0`/sbt-launch.jar "$@"

Windows

Create a batch file sbt.bat:

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

and put the jar in the same directory as the batch file. Put sbt.bat on your path so that you can launch sbt in any directory by typing sbt at the command prompt.

If you are behind a proxy on Windows, add flags to this second line for proxy host, port, and if applicable, username and password:

java -Dhttp.proxyHost=myproxy -Dhttp.proxyPort=8080 -Dhttp.proxyUser=username -Dhttp.proxyPassword=mypassword -Xmx512M -jar "%SCRIPT_DIR%sbt-launch.jar" %*

Create Project

Full Setup

When you run sbt and it does not find a project in the current directory, it asks if you want to create a new project. If you say yes, sbt will prompt for some basic information:

  • Project name: This name will be used in scaladocs and as part of the default name for generated packages.
  • Project organization: This is used for dependency management and is optional.
  • Project version: This is used in scaladocs, as part of the default name for generated packages, and for dependency management.
  • Scala version: This is version(s) of scala to build the project with. Multiple versions may be separated by spaces (see CrossBuild). Allowed values are (in theory) any version of Scala 2.7.2 or later available in the Scala Tools repository.
  • Sbt version: This is the version of sbt to build the project with. Currently, this should be 0.7.0, 0.7.1, 0.7.2, 0.7.3, 0.7.4, 0.7.5, or 0.7.7.

See Loader for more information on setting the versions of Scala and sbt to use to build your project. With the above information, sbt creates the project properties file and directory structure. These are described in the following section.

Quick Setup

In addition to 'yes' or 'no', you can type s (for scratch) when prompted to create a new project. This can be used to quickly get sbt compiling and running code without needing to do a full project setup. This option skips all of the prompts in a full setup and configures sbt to look in the current directory for sources and jars in addition to the usual places in a full project. Using sbt for a hello world might look like:

  $ echo 'object Hi { def main(args: Array[String]) { println("Hi!") } }' > hw.scala
  $ sbt
  Project does not exist, create new project? (y/N/s) : s
  ...
  > run
  ...
  Hi!

Directory Layout

Sources

Sbt uses the same directory structure as Maven for source files by default (all paths are relative to the project directory):

  src/
    main/
      resources/
         <files to include in main jar here>
      scala/
         <main Scala sources>
      java/
         <main Java sources>
    test/
      resources
         <files to include in test jar here>
      scala/
         <test Scala sources>
      java/
         <test Java sources>

Other directories in src/ will be ignored. Additionally, all hidden directories will be ignored.

Dependencies

All dependencies (jars) go in the

  lib/

directory or any subdirectory of lib. Again, hidden directories will be ignored. If you want to use ScalaCheck, specs, or ScalaTest for testing, those jars should go in here as well. Alternatively, you can configure sbt to automatically manage your dependencies (see LibraryManagement).

Build Configuration

Build configuration is done in the project directory:

  project/
    build.properties
    build/
    boot/

The build.properties file contains the project name, version, and organization, the versions of Scala and sbt used to build the project, and any other user-defined properties (see Properties). You can directly edit this file to change these properties or you can use the set command at the interactive prompt (see Basic Usage). The build directory is where further configuration is done and is described in BuildConfiguration. The boot directory is where the versions of Scala and sbt used to build the project are downloaded to.

Products

Generated files (classes, jars, analysis, and documentation) will be written to the

  target/

directory. Automatically managed dependencies are downloaded to:

  lib_managed/

Version Control

sbt creates and uses several directories that you will normally want to exclude from version control:

  target/
  lib_managed/
  project/boot/
  project/build/target/
  project/plugins/target/
  project/plugins/lib_managed/
  project/plugins/src_managed/

A .gitignore for an sbt project should contain these entries:

target/
lib_managed/
src_managed/
project/boot/

Next Step

Read Basic Usage for basic sbt usage information.

Summary

  1. Create a launcher script.
  2. Setup your project information and directory structure by running sbt in your project directory.
  3. Put libraries in lib or configure automatic dependency management.
  4. Read RunningSbt for basic usage instructions.
  5. Start with BuildConfiguration for further project configuration.
Comment by lypa...@gmail.com, Apr 15, 2009

copying the launcher into the bin dir and creating the script

#!/bin/sh
java -Xmx256M -jar `dirname $0`/sbt-launcher.jar "$@"

works for me

Comment by jzaugg, Jun 9, 2009

Or on Windows:

set SCRIPT_DIR=%~dp0
java %SBT_OPTS% -Xmx256M -jar "%SCRIPT_DIR%sbt-launcher-0.4.6.jar" %*

SBT_OPTS allows one to configure a HTTP proxy which is needed for Ivy. For example: set SBT_OPTS=-Dhttp.proxyHost=172.22.100.15 -Dhttp.proxyPort=8080

I suggest this should be added to FAQ.

Comment by project member dmhar...@gmail.com, Jun 9, 2009

Thanks to both of you.

jzaugg: on unix, you can configure the proxy with the http.proxy environment variable and sbt will pick it up. Is http.proxy used in windows?

-Mark

Comment by zhu....@gmail.com, Jun 29, 2009

dmharrah, thanks for this nice simple, yet elegant tool. It is a proof that Scala can be used in a wide range situations, from a build script to a large application. It saves me lots of time in building Scala apps and learning Scala!

Comment by project member dmhar...@gmail.com, Aug 24, 2009

sbt does work with 1.5. It might be something with your setup, since people use Mac+1.5. You might try asking on the mailing list. It might have come up before.

-Mark

Comment by dcsob...@gmail.com, Dec 18, 2009

Scala 2.7.7 should be added to the current list of supported Scala versions. Maybe a hint about 2.8 as well?

Comment by project member dmhar...@gmail.com, Dec 18, 2009

Thanks, Daniel. I've added 2.7.7. The best way to use 2.8 is really through sbt 0.6.x, but 0.6.x is still labeled experimental/in development. So, I'm not sure what I'd say there.

Thanks, Mark

Comment by Russ.Pai...@gmail.com, Dec 21, 2009

I am playing with Scala 2.8 (I can't tolerate a language without default arguments and passing by name). I see that sbt seems to have 2.7.7 hardwired. Is there a simple way to make sbt use Scala 2.8? Thanks.

Russ P.

Comment by project member dmhar...@gmail.com, Dec 21, 2009

sbt is designed to work with multiple Scala versions. You can use 2.7.2 through 2.7.7 out of the box, for example. The problem with 2.8 is that it is not released yet and so any two revisions are likely to be binary incompatible.

The new iteration of sbt (0.6.x) was designed to work around this limitation. So, you might try using 0.6.8, the current version. It is labeled experimental, but my current priority is making it the next released version and some well-known projects are using it with success (as far as I can tell). You can find details in the mailing list archives or you can just go for the download from the downloads section.

Thanks, Mark

Mailing list: http://groups.google.com/group/simple-build-tool Downloads: http://code.google.com/p/simple-build-tool/downloads/list

Comment by Russ.Pai...@gmail.com, Dec 21, 2009

I downloaded sbt 0.6.8. How do I tell it to use Scala 2.8? I've downloaded a nightly build of 2.8 a couple weeks ago. I see some instructions for using nightly builds, but they seem to apply to earlier versions of sbt. Are those the instructions I need to follow?

Comment by project member dmhar...@gmail.com, Dec 21, 2009

To switch the version being used for building:

  > set build.scala.versions 2.8.0.Beta1-RC5
  > reload 

To temporarily change to a version:

  > ++2.8.0.Beta1-RC5 

If you want to use a local Scala version, add the following to your project definition:

  override def localScala =
    defineScala("2.8.0-local", (scalaHome / "build" / "pack" ).asFile) :: Nil 

and reference it as 2.8.0-local.

Comment by ajohan...@gmail.com, Mar 31, 2010

It would be nice if some of the generated stuff could be grouped up and stored under a hidden directory in the root of the project. Similar to how git, mercurial, and maven hide all their cruft in hidden directory structures at the root.

I like SBT a lot, but the clutter is one thing I definitely do not like. It would also be nice if instead of using files in lib_managed if it could use files in .m2/repository ... or at least use them they were available.

Thank you fork all the work on SBT.

Comment by kulasama@gmail.com, May 2, 2010

hi all i used the command java -Xmx512M -jar dirname $0/sbt-launch.jar "$@" but the file ~/bin/sbt not generated. why?

Comment by shirishr...@gmail.com, Jun 18, 2010

Some applications require stack size to be set greater than the default value i.e 512 Kb. The command I use is java -Xmx512M -Xss1024k -jar dirname $0/sbt-launch(version).jar "$@"

Comment by csabacs...@gmail.com, Jun 18, 2010

Proxy configuration error: You probably access the destination server through a proxy server that is not well configured

In case some files are downloaded and others are not, sbt might try to use both http and https. You will have to set both trough command line or environment variables.

Ex.

set SCRIPT_DIR=D:\Scala\sbt\
java -Dhttp.proxyHost=proxy_ip -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy_ip -Dhttps.proxyPort=8080 -Xmx512M -jar "%SCRIPT_DIR%sbt-launch-0.7.4.jar" %*
Comment by llh110...@gmail.com, Jul 1, 2010

hi everyone ! when i run ~/bin/sbt/sbt or sbt but failed which print: sbt: command not found

i put sbt-launch.jar and sbt file in ~/bin/sbt directory and my sbt file are:

 #!/bin/sh 
java -Xmx256M -Xss1024k -jar dirname $0/sbt-launcher.jar "$@"}}}
 what can i do
Comment by pedrofu...@gmail.com, Jul 4, 2010

Since there is no mention of Cygwin here is the script used as 'bin/sbt':

dir=`dirname $0`
java -Xmx512M -jar `cygpath -w $dir`/sbt-launch-0.7.4.jar "$@"
Comment by dan.simp...@gmail.com, Jul 22, 2010

Scala 2.8 is now released. How can I get sbt 0.7.4 to accept 2.8 as the scala version? Broken?

Comment by Kirk.St...@gmail.com, Jul 26, 2010

I have the same question. When I put in 2.8 or 2.8.0 for the scala version, sbt merrily goes and fetches scala 2.7.7.

Comment by sanjsmai...@gmail.com, Aug 6, 2010

Same question as above. How do I get sbt to use 2.8.0 instead of fetching 2.7.7?

Comment by ittay.d...@gmail.com, Aug 16, 2010

same question here. i already have scala 2.8.0, how do i make the launcher use it?

Comment by steven.marcus, Aug 20, 2010

I had problems with sbt under cygwin, even using pedrofurla's hint above. This post had the solution: http://blog.andrewbeacock.com/2009/10/how-to-get-scala-working-with-rxvt.html

So now this seems to work:

dir=dirname $0
java -Djline.terminal=jline.UnixTerminal -Xmx512M -jar cygpath -w $dir/sbt-launch.jar "$@"
Comment by polux2...@gmail.com, Oct 9, 2010

Hello, thanks for this really nice tool!

The instructions are not very clear to the newcomers: it starts with "create a script to launch sbt" and if you don't go further you don't understand that it is explained below, and get stuck at that step.

Comment by polux2...@gmail.com, Oct 9, 2010

Also the real jar is not named sbt-launch.jar but contains a version number. Maybe a separate page with precise instructions for newbies would be helpful?

Comment by andrew.r...@gmail.com, Oct 10, 2010

specify 2.8.0 as the version and it will download it with maven2 no problem

Comment by Phi...@GMX.net, Oct 13, 2010

Trying SBT (Simple Build Tool) for compiling a simple (one file, perhaps two) Scala application with some dependencies (Apache Pivot) on Windows as specifying all the jars on the command line quickly becomes annoying... (I try to convert the tutorial files to Scala).

Following the instructions here I have put the jar file in C:\Java\scala-2.8.0.final\misc and the sbt.cmd file in C:\Java\scala-2.8.0.final\bin Content of the latter:

@echo off
java -Xmx512M -jar C:\Java\scala-2.8.0.final\misc\sbt-launch-0.7.4.jar %*

As shown above, I use the current version, 0.7.4, supposed to support Scala 2.8. So far so good, when I type sbt on the command line, I get a prompt:

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

Trying what is suggested, I answer s for a simple "hello world" setup (Quick Setup), perfect for my simple need (precisely a HelloScala? derived from the HelloJava? tutorial of Pivot). Gah! Apparently it starts to download Scala 2.7.7! Hey, I want 2.8, and I want the local version, no need to download yet another copy! And certainly not a copy per (micro-)project!

So I find the LocalScala page. Good, you have thought of this need. Bad, it is crypted... What is this ScalaInstance? object? Where to put it? "Override the localScala method to declare these local instances to sbt" Indeed, but where I am supposed to put the given code snippet?

Do I have to read the whole wiki before starting to experiment?

So I look at BuildConfiguration and have a hint: I have to create a .scala file in the project/build directory. Let's try it. First, let's make the project hierarchy:

> sbt
Project does not exist, create new project? (y/N/s) y
Name: Text
Organization: PhiLhoSoft
Version [1.0]:
Scala version [2.7.7]: 2.8.0
sbt version [0.7.4]:
Getting Scala 2.7.7 ...
^C^C^C^C^C^C
Terminer le programme de commandes (O/N) ?
^C

:-( At least I have project/boot and a build.properties file with these settings. OK, let's create project/build and put there Text.scala:

import sbt._

class ApachePivotTextTutorial(info: ProjectInfo) extends DefaultProject(info)
{
  lazy val hi = task { println("Apache Pivot Text Tutorial"); None }
  override def localScala =
    defineScala("2.8.0-local", new File("C:/Java/scala-2.8.0.final")) :: Nil
}

Let's modify project/boot/build.properties to change 2.8.0 to 2.8.0-local Trying again:

> sbt
Getting Scala 2.7.7 ...
^C^C^C^C^C^C
Terminer le programme de commandes (O/N) ?
^C

> sbt "++2.8.0-local"
Getting Scala 2.7.7 ...
^C^C^C^C^C^C
Terminer le programme de commandes (O/N) ?
^C

:-(( So I am stuck... Can you include some simple instructions for absolute beginners like me wanting to use their local install of Scala on small projects? Is there an option to create a project hierarchy without starting to download Scala?

Comment by mcdonnel...@gmail.com, Oct 29, 2010

As of the time of writing (October 2010), SBT uses Scala 2.7.7 for itself. It's alarming to specify (say) 2.8.1.RC4 and then see the message 'getting 2.7.7'. However, because SBT uses Ivy for dependency management, this will only happen once.

After SBT downloads its own version of Scala, then it will attend to yours. I'm hoping to get editor rights on the Wiki, as the documentation isn't as helpful as it could be.

Comment by baron...@gmail.com, Nov 4, 2010

Does the s in sbt really stand for simple? like the s in soap once stood for simple, until it became embarrassingly ironic.

Comment by martinw...@gmail.com, Nov 11, 2010

Hello I'm new to the whole stuff and I'm trying to find my way through sbt. When I run sbt in my empty folder and tell it to use scala 2.8.1.final Iget:

F:\dev_scala\OltsLift?>sbt

F:\dev_scala\OltsLift?>set SCRIPT_DIR=F:\Program Files (x86)\SBT\

F:\dev_scala\OltsLift?>java -Xmx512M -jar "F:\Program Files (x86)\SBT\sbt-launch- 0.7.4.jar" Getting Scala 2.8.1.final ...

:: problems summary :: :::: WARNINGS

module not found: org.scala-lang#scala-compiler;2.8.1.final

==== local: tried

...

::::::::::::::::::::::::::::::::::::::::::::::
:: UNRESOLVED DEPENDENCIES ::
::::::::::::::::::::::::::::::::::::::::::::::
:: org.scala-lang#scala-compiler;2.8.1.final: not found
:: org.scala-lang#scala-library;2.8.1.final: not found
::::::::::::::::::::::::::::::::::::::::::::::

:: USE VERBOSE OR DEBUG MESSAGE LEVEL FOR MORE DETAILS unresolved dependency: org.scala-lang#scala-compiler;2.8.1.final: not found unresolved dependency: org.scala-lang#scala-library;2.8.1.final: not found Error during sbt execution: Error retrieving required libraries

(see F:\dev_scala\OltsLift?\project\boot\update.log for complete log)
error? Could not retrieve Scala 2.8.1.final

Provide a new Scala version or press enter to exit:

What am i missing i have scala 2.8.1.final installed.

regards martin

Comment by andy.cze...@gmail.com, Nov 24, 2010

I'm having a problem running SBT under ENSIME under Windows. it works great for me on my Mac.

http://sandbox.andyczerwonka.com/video/ensime_windows.swf

I think it's probably the way I setup my sbt.bat file. Has anyone else seen this behavior?

Comment by andy.cze...@gmail.com, Nov 25, 2010

Alright.. I finally figured it out. Add this to your options when starting sbt (sbt.bat):

-Djline.terminal=jline.UnsupportedTerminal?

Comment by steve.g...@gmail.com, Feb 16, 2011

I've noticed than when working under Windows, putting simply "java" in sbt.bat file will ALWAYS trigger the recompilation of the sbt files. You must had the full path of your java.exe binary in order to prevent that.

So change the sbt.bat content with this (or adapt with your java.exe path):

set SCRIPT_DIR=%~dp0 
"C:\Program Files (x86)\java\jdk1.6.0_23\bin\java.exe" -Xmx512M -jar "%SCRIPT_DIR%sbt-launch.jar" %*
Comment by slochmann@gmail.com, Feb 26, 2011

I'm running Window7 and the sbt.bat file just is not working for me. I created the sbt.bat file in the same directory as the sbt-launch.jar; Added the bat file to the PATH; however, when I go to a command prompt I get: {{{'sbt' is not recognized as an internal or external command, operable program or batch file.}}}

The sbt.bat file is: java -Xmx512M -jar "C:\tools\sbt\sbt-launch.jar" %*

If I type the line above into the command prompt it works.

PATH=....;C:\Program Files\Java\jdk1.6.0_18\bin;C:\tools\apache\apache-maven\bin;C:\tools\scala\bin;C:\tools\sbt\sbt.bat;

Any ideas?

Comment by john.w.p...@gmail.com, Apr 7, 2011

slochmann,

Instead of the last part of your PATH being 'C:\tools\sbt\sbt.bat' I would recommend changing it to 'C:\tools\sbt\'

I'm not sure, but I don't think you should name executables directly in the PATH; you should only be naming the directories that they are found inside.

Comment by peter.sc...@gmail.com, Apr 15, 2011

In cygwin, via rxvt, I found that the only way I could get it to work hassle-free was by using an alias, and the complete path of the jar file:

alias sbt='java -Xmx512m -Djline.terminal=jline.UnixTerminal -jar `cygpath -w /cygdrive/c/path/to/my/sbt-launch-0.7.5.jar`'

Comment by ecarlosf...@gmail.com, May 3, 2011

A better script for the launch

FILENAME=$0
if [ -h $FILENAME ]
  then
    FILE_NAME=`readlink $0`
fi
java -Xmx512M -jar `dirname $FILE_NAME`/sbt-launch-0.7.5.jar "$@"

so the sbt file can be placed on any path:

mkdir /opt/sbt
cd /opt/sbt
wget  http://simple-build-tool.googlecode.com/files/sbt-launch-0.7.5.jar

# create a file and add the script above 
vim sbt

chmod 755 sbt
ln -s /opt/sbt/sbt /usr/bin/sbt
Comment by nilu...@gmail.com, May 24, 2011

ok thanks

Comment by leedm...@gmail.com, Jun 3, 2011

When I run sbt reload, the file project/plugins/project/build.properties which is usually (always?) modified. The onlyy modification is the timestamp in the comment at the top of the file.

Should it be added to my .gitignore file?

Comment by JayUnit...@gmail.com, Jul 20, 2011

I get an UNRESOLVED DEPENDENCIES error " :: org.scala-tools.sbt#sbt_2.8.1;0.7.7: not found "

Not sure what it means ?

Comment by pha...@gmail.com, Aug 3, 2011

for the people getting "unresolved dependancies"

see: https://github.com/harrah/xsbt/wiki/Migrating-from-SBT-0.7.x-to-0.10.x and follow "Step 2: A technique for switching an existing project"

Powered by Google Project Hosting