markdown getting-started-in-scala.md

Posted 2021-05-06

# Getting Started in Scala

This is my attempt to give Scala newcomers a quick-and-easy rundown to the prerequisite steps they need to a) try Scala, and b) get a standard project up and running on their machine.  I'm not going to talk about the language at all; there are plenty of better resources a google search away.  This is just focused on the prerequisite tooling and machine setup.  I will *not* be assuming you have any background in JVM languages.  So if you're coming from Python, Ruby, JavaScript, Haskell, or anywhere…  I hope to present the information you need without assuming anything.

*Disclaimer*  It has been over a decade since I was new to Scala, and when I was new to Scala, I was coming from a Java and Ruby background.  This has probably caused me to unknowingly make some assumptions.  Please feel free to call me out in comments/[tweets](https://twitter.com/djspiewak)!

One assumption I'm *knowingly* making is that you're on a Unix-like platform.  Sorry, Windows users.

## Getting the JVM

Everything we're going to do with Scala requires the JVM.  Even if you ultimately intend to do in-browser development with [Scala.js](https://www.scala-js.org) or run on the LLVM backend with [Scala Native](http://www.scala-native.org), you're still going to need the JVM just to run the Scala compiler.  Fortunately, this is relatively straightforward.

The latest major version of the JVM (as of this writing) is 8 (sometimes referenced as "1.8" for legacy reasons).  You can download it [here](http://www.oracle.com/technetwork/java/javase/downloads/index-jsp-138363.html) (I believe that link is stable).  At a minimum, you will need the JRE (Java Runtime Environment), but I recommend grabbing the JDK anyway.  It's a somewhat larger download, but it comes baked with some goodies that you will find useful down the road.

Install the relevant JRE for your platform, and make sure that the `java` executable is available on your `PATH`.  You can double-check that you have the appropriate version by running the following command:

```bash
$ java -version
```

You should see "1.8.*somethingorother*"  Because reasons.

## Trying Scala

At the present time, there is no *great* solution for trying out Scala in your browser without installing anything.  There are a few implementations of the [Scala Fiddle](https://scalafiddle.io) concept, and the one linked is (I think) the best.  Because of technical limitations at present, the turnaround time is longer than one would like, and it's difficult to play around with libraries.  You could also try [scala-repl](http://www.scala-repl.org/code/welcome), which is a somewhat Mathematica-like environment in your browser, hosted as a local server instance.

I'm going to recommend the following pair of commands instead:

```bash
$ curl -L -o amm https://git.io/vP4Gw && chmod +x amm
$ ./amm
```

I'm a random person on the internet telling you to download a random URL and execute it.  Please treat this with the appropriate suspicion!  Here's what you're installing: [Ammonite-REPL](http://www.lihaoyi.com/Ammonite/#Ammonite-REPL).

The results of this pair of commands will be a running Scala REPL with syntax coloring and reasonable error messages.  *For the most part*, any Scala tutorial snippets you find on the internet should work in this environment.  The exceptions are related to overloading, scoping, and class companions.  But if you aren't doing anything related to those things, you should be fine.  Here's a quick try-out:

```scala
@ println("Hello, World!") 
Hello, World!
```

To exit the REPL, type `exit`.  <kbd>Ctrl</kbd>-<kbd>C</kbd> will kill a long-running expression (e.g. if you accidentally write an infinite loop).

The Ammonite REPL is generally better than the stock Scala REPL, so I recommend just hanging onto this executable.  I make use of it on a daily basis!

## Installing SBT

Ok, enough messing around.  Let's get a real project up and running, using the same toolchain that nearly every Scala developer uses on a daily basis.  We need to start by installing SBT.

[SBT (Scala Build Tool)](http://www.scala-sbt.org) is the standard build system for Scala.  It's a little bit like Maven, Gradle, Gems, or NPM; and as with all of those tools, it comes with its own quirks and weirdness.  Fortunately, most of those quirks aren't going to bother you as you get started.

I recommend installing Paul Phillips' excellent [sbt-extras](https://github.com/paulp/sbt-extras) script:

```bash
$ curl -L -o sbt https://raw.githubusercontent.com/paulp/sbt-extras/master/sbt && chmod +x sbt
```

SBT does have a standard script that is similar to PaulP's, but it's simply not as good.  PaulP's script has some weirdness (particularly relating to some of the optional flags), but it generally does the job extremely well and it is very much the *de facto* standard SBT launcher script.

One of the things about Scala that is often very ill-explained is this: **you don't download or install Scala**.  SBT will download, configure and cache the correct version of Scala for your project, along with all of its dependencies.  Most Scala developers don't even have Scala installed outside of SBT!

## Creating a Project

I would love it if I could say at this point "just run this one command and you're done!"  But sadly, there's some more boilerplating we need to do.

The first step is to create your project's directory structure.  I generally do something like this (for a project named **funzles**):

```bash
$ mkdir -p funzles/src/{main,test}/scala/funzles
$ cd funzles
```

This is generally followed by a `git init`, but we'll leave that for now.  The `src/main/scala/` directory convention comes from Maven, a build system and package manager for Java.  It does have some advantages, but you're certainly going to have to get used to some very deeply nested directories!  Generally speaking, you'll put your main project source files under `src/main/scala/`, while your tests are going to go in `src/test/scala/`.  It is possible to organize your project files differently, but SBT understands this convention right out of the box, and other Scala developers will be very at home in your project if you stick to the standards.

### Configuring Your Build

Now we need to configure SBT so it understands more about our project than the fact that we're using Scala.  To do this, we need to create a file named **build.sbt** in the root directory of your project.  For now, the following contents should be sufficient:

```sbt
name := "funzles"

scalaVersion := "2.11.8"
```

At the time of this writing, 2.11.8 is the latest Scala version (with 2.12 in release candidate stage).  You should replace this version string with whatever the latest Scala version is (the latest version is listed below the giant logo [here](http://www.scala-lang.org)).

A brief aside about SBT…  SBT's configuration syntax (in `.sbt` files) is very extensive.  There's a *ton* of stuff you can do with it.  I do not recommend falling down that particular rabbit hole if you're new to Scala!  If you decide to start doing more complex things, there are resources to help you do more with SBT (I recommend the book [*SBT In Action*](https://www.manning.com/books/sbt-in-action) as well as the [official SBT documentation pages](http://www.scala-sbt.org/0.13/docs/index.html)).

### Building and Running

Fortunately, we're all done with the boilerplate stuff!  We can actually start doing real coding with a real project (sort of).  Start by launching SBT (assuming you put the `sbt` script from earlier on your `PATH`):

```bash
$ sbt
```

In general, you're going to want to have SBT open in your project whenever you're doing development work.  As you probably could see from running that command, SBT takes a bit of time to start (though much longer when it's your first time!).  The SBT prompt offers several commands which are extremely useful, and keeping SBT itself open allows it to cache results and be significantly more efficient, reducing turnaround time on compilation and testing and increasing your productivity.  Some quick commands to try:

- `compile` – Compiles all of the *main* source files in your project.  This task is incremental: if a file hasn't changed, and its dependent files have not changed, it will not be recompiled.
- `test` – Compiles (if necessary) and runs all of the *test* source files in your project.  Main source files will also be compiled if necessary.
  + `test-quick` – Compiles your main and test files (if necessary) and calculates which tests (relative to your last test run) have been affected by file changes.  *Only* those tests are run.  So the first time you run this command, it will run every test.  The second time (if you make no file changes), no tests will be run.  If you change some files, just the tests which touch those files will be rerun.  I use this command a lot!
- `run` – Compiles (if necessary) and runs the `main` class in your *main* source files.  If there is no main class, you'll get an error.  If there are multiple main classes, you'll be prompted to choose the one you want.
- `exit` – Gets you out of Dodge (<kbd>Ctrl</kbd>-<kbd>C</kbd> also works!)
- `show <setting>` – Prints out the value of the setting key specified by the `setting` parameter (without angle brackets).  For example, `show name` should print out **funzles**.

Tab completion works, by the way!  There are literally hundreds of available commands, of varying usefulness and specialization.  Feel free to poke around.  SBT doesn't have the ability to randomly break anything, and nothing you do in the SBT prompt (outside of the `save` command, which you should not use) will affect any of your source files.  So it's safe to experiment!

### Editing

There are Scala modes available for basically all of the major editors.  There are also two major Scala IDEs (Integrated Development Environment) which provide richer language-aware features like content assist (i.e. "intellisense"), inline error reporting, debugging and more.  I do not use an IDE when I'm doing Scala development; a text editor (like Emacs) works just fine.  But if you prefer an IDE, the following options are recommended:

- [IntelliJ](https://confluence.jetbrains.com/display/SCA/Scala+Plugin+for+IntelliJ+IDEA) – This is more or less the gold standard for Scala IDEs.  At least in my experience, almost everyone who uses a Scala IDE uses this one.
- [Eclipse](http://scala-ide.org) – The Eclipse plugin is sponsored by Lightbend (who also sponsors most of the work on Scala itself).  It is very good, and it is free, but it's somewhat less ubiquitous than IntelliJ in my experience.

If you (like me!) prefer to just stick with a plain old text editor, as I said, nearly all of them have very solid Scala modes.  If you prefer to stick with a plain old text editor, you probably already have a strong preference as to the one you want to stick with, but just to keep you informed…  The following editors have particularly good Scala modes, listed in order of quality:

- **Emacs** – I'm not an Emacs user, but honestly the Emacs Scala mode is second to none.  The many contributors over the years have simply done a superb job of making the language feel very much a first-class citizen in the editor.
- **Sublime 3** – This is my editor of choice, and several recent changes to the Scala mode have made it objectively one of the most comprehensive and accurate modes in existence (second only to Emacs).  Note that Sublime 2 does *not* have the latest changes, and its Scala mode is proportionally less powerful.
- **Vim** – Vim's Scala mode is a little bit behind.  Depending on what version you acquire, you may or may not see support for things like macros or string interpolation.  Additionally, there are some weird quirks with a few of the lesser-used corners of the language (such as pattern guards).  But it does the job and it does it quite well.
- **Atom** – Atom is basically solid at everything it does, and Scala is no exception.  The original version of Atom's Scala mode appears to have been based on the Sublime 2 Scala mode, and shares many of its flaws, but it gets the job done.
- **TextMate** – I can't speak to this mode too specifically, but I know that several of the Sublime 3 Scala mode improvements have been backported to recent TextMate builds.  I am not aware if the latest stable TextMate has these changes.
- **jEdit** – The Scala mode is excellent and has consistently accurate syntax highlighting and auto-indentation.  There are some limitations though, and syntax highlighting may not work quite as well if you format your Scala code using a non-standard style.

As another sidebar, there exists a middle-ground project between a full IDE like IntelliJ and a raw text editor like Emacs.  That middle ground is [ENSIME](http://ensime.github.io).  Very much inspired by the SLIME project for Emacs, ENSIME is a subprocess which provides many IDE-like features inside the context of a basic text editor.  Several editors are supported, but Emacs is the most stable and full-featured by far.

### Creating, Compiling and Running

Use your editor of choice to create a file in the **src/main/scala/funzles/** directory with the following contents (the name of the file isn't significant, though it must use the `.scala` extension):

```scala
package funzles

object Fun {
  def main(args: Array[String]): Unit = {
    println("Hello, World!")
  }
}
```

From within the SBT prompt, run the following command (you can also run `sbt run` from your shell prompt, but again, you will pay the startup penalty every time):

```
> run
```

SBT will compile and run your `Fun` class, printing *Hello, World!* to standard output.

One very useful trick of SBT is the `~` prefix.  You can prepend a `~` to *any* SBT command.  The result of this prefix is the command will run once, followed by SBT pausing and monitoring your project files.  Whenever your source files change, it will immediately re-run the command, followed by another pause to monitor files for subsequent runs.  This will continue until you break out of the `~` by using <kbd>Enter</kbd>.  For example, run the following command:

```
> ~run
```

Now go back to your editor, and add the following line to the `main` method:

```scala
// ...
println("...do you read me?")
```

By the time you tab back to your terminal application, your class should have been recompiled and rerun, with the results waiting for you.

Once you get ramped up in Scala, you will find yourself using `~` almost all the time in SBT.  It is particularly useful in conjunction with the `test-quick` command referenced earlier.

## Depending on Libraries

Before we close out, it's worth noting briefly how it is you can depend upon third-party libraries.  The JVM has a very extensive ecosystem of libraries, built up over more than 20 years of community development.  Scala can trivially access any Java library, and SBT is very much aware of the Java ecosystem.

Let's say that you want to do some low-level asynchronous network IO using the fantastic [Netty framework](https://netty.io).  You will want to look for the latest version at [search.maven.org](http://search.maven.org).  After a bit of digging, it looks like the latest Netty artifact (at the time of this writing) is [here](http://search.maven.org/#artifactdetails%7Cio.netty%7Cnetty-all%7C4.1.6.Final%7Cjar).  Specifically, the full artifact descriptor is `io.netty:netty-all:4.1.6.Final`.  We can instruct SBT to make this framework available to our project by modifying our **build.sbt** file:

```sbt
name := "funzles"

scalaVersion := "2.11.8"

libraryDependencies += "io.netty" % "netty-all" % "4.1.6.Final"
```

If you still have the SBT prompt open (which you should!), run the `reload` command.  This will cause SBT to pick up the latest changes to the **build.sbt** file.  Now that you've done this, you can use Netty within your project sources as described in [their documentation](https://netty.io/wiki/user-guide-for-4.x.html).

Now, Netty is a Java framework.  Scala frameworks can be added to our project using much the same mechanism, but the syntax and process is a little different.  Let's imagine that we want to add a library for doing abstracted functional programming, similar to what we would get in Haskell out of the box.  After a bit of googling, we might find that [Cats](https://github.com/typelevel/cats) is one such project.  Visiting the project page on GitHub, we see early on in the README the following incantation (as of this writing):

```sbt
libraryDependencies += "org.typelevel" %% "cats" % "0.7.2"
```

So all we need to do is add that to our **build.sbt** file, run another `reload` and we should be good to go!

```sbt
name := "funzles"

scalaVersion := "2.11.8"

libraryDependencies += "io.netty" % "netty-all" % "4.1.6.Final"
libraryDependencies += "org.typelevel" %% "cats" % "0.7.2"
```

Most libraries written in Scala will have a line like this in their README, which makes it quite easy to add almost any Scala library to an SBT build without messing around at search.maven.org.

One thing you will notice is that this dependency uses *two* percent signs (`%`) rather than just the one that we used with Netty.  Without going into too much detail, this is part of SBT's workaround mechanism for the fact that binary compatibility in Scala can be a hard problem.  As a general rule, if you're depending on a Java library, just use one `%`.  If you're depending on a Scala library, use two.

### Testing

Testing is incredibly important in all languages, which is why I'm not going to spend any time on it at all!  :-)  More seriously, Scala has two standard testing frameworks (with a third standard support framework used by both), and nearly code written in the language is tested using one of these two:

- [ScalaTest](http://www.scalatest.org) – A very broad test framework offering support for several testing paradigms (JUnit-style unit testing, RSpec-style BDD, and everything in between).  ScalaTest supports a very large number of test definition styles, selected by the trait you inherit (e.g. `FunSpec`).
- [Specs2](http://etorreborre.github.io/specs2/) – A slightly more narrowly-focused test framework which focuses on BDD.  Specs2 supports two different test definition styles: mutable and immutable.  I *highly* recommend sticking with the mutable definition style, as it is more straightforward and far more commonly used in the Scala ecosystem.

I personally prefer Specs2, but frankly both frameworks provide nearly the same general functionality.  Be warned that Specs2's documentation and most of its examples generally focuses on the *immutable* API, which as I mentioned, is less conventional.  Partially for this reason, ScalaTest has significantly better documentation for test definition and structure, while Specs2 has significantly better documentation for its assertion functionality (matchers).

## Next Steps

You're now up and running with a fully-functional, no-holds-barred Scala project environment.  All the training wheels are off here: this is literally the same sort of environment (build setup, filesystem and editor) that nearly all Scala developers use on a daily basis!  So where do you go from here?

My recommendation would be to continue working through the many excellent Scala learning resources.  Coursera has some very good formal courses.  There are several books.  You can find an endless number of tutorials online spanning all knowledge levels.  Twitter, IRC and Gitter are all excellent resources, and you will find many members of the Scala community willing and eager to help you.  Get out there and make something awesome!

---

Dual licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)/[CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)