Getting Started with Sbt
Total Page:16
File Type:pdf, Size:1020Kb
Getting Started with sbt Contents Preface ................................... 4 Installing sbt ................................ 4 Tips and Notes ............................ 5 Installing sbt on Mac ............................ 5 Installing from a third-party package ................ 5 Installing from a universal package ................. 5 Installing manually .......................... 5 Installing sbt on Windows ......................... 5 Windows installer ........................... 5 Installing from a universal package ................. 5 Installing manually .......................... 6 Installing sbt on Linux ........................... 6 Installing from a universal package ................. 6 RPM and DEB ............................ 6 Gentoo ................................. 6 Installing manually .......................... 6 Installing sbt manually ........................... 6 Unix .................................. 7 Windows ............................... 7 Hello, World ................................ 8 Create a project directory with source code ............ 8 Build definition ............................ 9 1 Setting the sbt version ........................ 10 Directory structure ............................. 10 Base directory ............................. 10 Source code .............................. 10 sbt build definition files ....................... 11 Build products ............................ 11 Configuring version control ..................... 11 Running ................................... 11 Interactive mode ........................... 12 Batch mode .............................. 12 Continuous build and test ...................... 12 Common commands ......................... 13 Tab completion ............................ 13 History Commands .......................... 13 .sbt build definition ............................ 14 .sbt vs .scala Build Definition .................. 14 What is a Build Definition? ..................... 15 How build.sbt defines settings .................... 15 Settings must be separated by blank lines ............. 16 Keys .................................. 16 Defining tasks and settings ..................... 18 Keys in sbt interactive mode .................... 18 Imports in build.sbt ......................... 19 Adding library dependencies ..................... 19 Scopes .................................... 19 The whole story about keys ..................... 19 Scope axes ............................... 20 Global scope ............................. 21 Delegation ............................... 21 Referring to scoped keys when running sbt ............. 22 Examples of scoped key notation .................. 22 2 Inspecting scopes ........................... 23 Referring to scopes in a build definition .............. 24 When to specify a scope ....................... 26 More kinds of setting ............................ 26 Refresher: Settings .......................... 26 Appending to previous values: += and ++= ............. 27 Computing a value based on other keys’ values .......... 27 Appending with dependencies: += and ++= ............. 29 Library dependencies ............................ 30 Unmanaged dependencies ...................... 30 Managed Dependencies ....................... 31 Multi-project builds ............................ 34 Multiple projects ........................... 34 Dependencies ............................. 34 Default root project ......................... 36 Navigating projects interactively .................. 37 Common code ............................. 37 Using plugins ................................ 37 What is a plugin? ........................... 37 Declaring a plugin .......................... 38 Enabling and disabling auto plugins ................ 38 Global plugins ............................ 40 Available Plugins ........................... 40 Custom settings and tasks ......................... 40 Defining a key ............................. 40 Implementing a task ......................... 41 Use plugins! .............................. 42 .scala build definition ........................... 42 sbt is recursive ............................ 42 .scala source files in the build definition project ......... 43 Relating build.sbt to Build.scala .................. 44 3 When to use .scala files ...................... 46 The build definition project in interactive mode .......... 46 Reminder: it’s all immutable .................... 46 Getting Started summary ......................... 47 sbt: The Core Concepts ....................... 47 Advanced Notes ............................ 48 Preface sbt uses a small number of concepts to support flexible and powerful build definitions. There are not that many concepts, but sbt is not exactly like other build systems and there are details you will stumble on if you haven’t read the documentation. The Getting Started Guide covers the concepts you need to know to create and maintain an sbt build definition. It is highly recommended to read the Getting Started Guide! If you are in a huge hurry, the most important conceptual background can be found in .sbt build definition, scopes, and more kinds of setting. But we don’t promise that it’s a good idea to skip the other pages in the guide. It’s best to read in order, as later pages in the Getting Started Guide build on concepts introduced earlier. Thanks for trying out sbt and have fun! Installing sbt To create an sbt project, you’ll need to take these steps: • Install sbt and create a script to launch it. • Setup a simple hello world project – Create a project directory with source files in it. – Create your build definition. • Move on to running to learn how to run sbt. • Then move on to .sbt build definition to learn more about build definitions. Ultimately, the installation of sbt boils down to a launcher JAR and a shell script, but depending on your platform, we provide several ways to make the process less tedious. Head over to the installation steps for Mac, Windows, Linux, or manual installation. 4 Tips and Notes If you have any trouble running sbt, see Setup Notes on terminal encodings, HTTP proxies, and JVM options. Installing sbt on Mac Installing from a third-party package Note: Third-party packages may not provide the latest version. Please make sure to report any issues with these packages to the relevant maintainers. Macports $ port install sbt Homebrew $ brew install sbt Installing from a universal package Download ZIP or TGZ package, and expand it. Installing manually See instruction to install manually. Installing sbt on Windows Windows installer Download msi installer and install it. Installing from a universal package Download ZIP or TGZ package and expand it. 5 Installing manually See instruction to install manually. Installing sbt on Linux Installing from a universal package Download ZIP or TGZ package and expand it. RPM and DEB The following packages are also officially supported: • RPM package • DEB package Note: Please report any issues with these to the sbt-launcher- package project. Gentoo In the official tree there is no ebuild for sbt. But there are ebuilds to merge sbt from binaries. To merge sbt from this ebuilds you can do: $ mkdir -p /usr/local/portage && cd /usr/local/portage $ git clone git://github.com/whiter4bbit/overlays.git $ echo "PORTDIR_OVERLAY=$PORTDIR_OVERLAY /usr/local/portage/overlays" >> /etc/make.conf $ emerge sbt-bin Note: Please report any issues with the ebuild here. Installing manually See instruction to install manually. Installing sbt manually Manual installation requires downloading sbt-launch.jar and creating a script to start it. 6 Unix Put sbt-launch.jar in ~/bin. Create a script to run the jar, by creating ~/bin/sbt with these contents: SBT_OPTS="-Xms512M -Xmx1536M -Xss1M -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256M" java $SBT_OPTS -jar `dirname $0`/sbt-launch.jar "$@" Make the script executable: $ chmod u+x ~/bin/sbt Windows Manual installation for Windows varies by terminal type and whether Cygwin is used. In all cases, put the batch file or script on the path so that you can launch sbt in any directory by typing sbt at the command prompt. Also, adjust JVM settings according to your machine if necessary. Non-Cygwin For non-Cygwin users using the standard Windows terminal, create a batch file sbt.bat: set SCRIPT_DIR=%~dp0 java -Xms512M -Xmx1536M -Xss1M -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256M -jar "%SCRIPT_DIR%sbt-launch.jar" %* and put the downloaded sbt-launch.jar in the same directory as the batch file. Cygwin with the standard Windows termnial If using Cygwin with the standard Windows terminal, create a bash script ~/bin/sbt: SBT_OPTS="-Xms512M -Xmx1536M -Xss1M -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256M" java $SBT_OPTS -jar sbt-launch.jar "$@" Replace sbt-launch.jar with the path to your downloaded sbt-launch.jar and remember to use cygpath if necessary. Make the script executable: $ chmod u+x ~/bin/sbt 7 Cygwin with an Ansi terminal Cygwin with an Ansi terminal (supports Ansi escape sequences and is configurable via stty), create a bash script ~/bin/sbt: SBT_OPTS="-Xms512M -Xmx1536M -Xss1M -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256M" stty -icanon min 1 -echo > /dev/null 2>&1 java -Djline.terminal=jline.UnixTerminal -Dsbt.cygwin=true $SBT_OPTS -jar sbt-launch.jar "$@" stty icanon echo > /dev/null 2>&1 Replace sbt-launch.jar with the path to your downloaded sbt-launch.jar and remember to use cygpath if necessary. Then, make the script executable: $ chmod u+x ~/bin/sbt In order for backspace to work correctly