Environment Setup and Artifacts Fetching Using Coursier

1. Introduction

Setting up a Scala development environment can sometimes be difficult, especially for newcomers. We might need to spend a considerable amount of time on the internet to install the required tools. Additionally, switching between JDK implementations requires multiple steps that can be difficult to keep track of.

Coursier is a tool that simplifies the process of setting up a Scala development environment. In this tutorial, we’ll look at how we can use Coursier to manage the development environment.

2. What Is Coursier?

Coursier is an artifact fetching tool written in Scala. Coursier has been used by SBT for fetching the library dependencies since 1.3.0. It supports the parallel downloading of artifacts without any global lock. Additionally, Coursier recently introduced the feature of single-click Scala environment setup, which installs everything needed to get started with Scala development.

3. Development Environment Setup

Let’s take a closer look at how we can use Coursier to set up and manage the development environment.

3.1. Downloading

Let’s start by downloading and installing the coursier-cli tool. For Linux and Mac OS, we can use curl:

curl -fLo cs https://git.io/coursier-cli-"$(uname | tr LD ld)"

3.2. Installation

Once downloaded, we’ll need to give executable permission to the cs file:

chmod +x cs

Next, we’ll execute the command to run the setup:

./cs setup -y

This will install the JDK, Scala REPL, Ammonite REPL, SBT, and Scala Compiler by default. It also will set the relevant environment and profile variables so that the installed applications can be directly accessible from anywhere. The -y argument will run through the setup accepting the default settings.

Since the PATH variable is updated, we’ll need to close the current terminal and open it again.

We can then verify the setup was successful by simply checking the Java version:

java -version

Similarly, we can check if Scala and SBT are also installed by simply executing scala and sbt commands in the terminal. We can also find all the installed applications by running cs list.

That’s it! With only the cs setup command, the Scala development environment is ready for development.

3.3. Keeping the Environment Up to Date

Using Coursier, it is very easy to keep the development environment up to date:

cs update

This will update all the Coursier managed applications to the latest versions if available. If we want to update a single application, we can do that by specifying the application to update:

cs update ammonite

This will update only Ammonite REPL to the latest available version.

4. Managing the JDK

4.1. Installing a Different JVM

By default, Coursier installs AdoptOpenJDK-8. If we want to use AdoptOpenJDK-11, we can easily do that by running cs java and specifying the version:

cs java --jvm 11 --setup

This will download AdoptOpenJDK-11 and set it as default. If we omit the –setup flag, Coursier will still install the JDK 11 but won’t set it as the default JVM.

Additionally, we can list the Coursier managed JDKs by using the –installed flag:

cs java --installed

4.2. Temporarily Switch the JVM

Sometimes, we may want to switch to a different JVM for the current session. This is done by running cs java with the –env flag:

cs java --jvm 14 --env

This will print the required export statements to switch the JDK to 14:

export CS_FORMER_JAVA_HOME="$JAVA_HOME"
export JAVA_HOME="/home/yadu/.cache/coursier/jvm/[email protected]"
export PATH="/home/yadu/.cache/coursier/jvm/[email protected]/bin:$PATH"

We can then execute these statements in the current terminal and verify the Java version has been updated to JDK 14. Additionally, if JDK-14 is not installed, Coursier will first install it and then print the export statements.

4.3. Installing a Specific Version of the JVM

Let’s say we want to install version 20.2.0 of the GraalVM. First, we’ll want to see a list of the supported JVMs:

cs java --available

This will return a list of the available JVMs:

...
graalvm:20.1.0
graalvm:20.2.0
graalvm:20.3.0
...

We can see that version 20.2.0 of the GraalVM is supported. So let’s install it:

cs java --jvm graalvm:20.2.0

5. Managing the Scala Environment

We can use Coursier to manage SBT, Scala REPL, Scala Compiler and Ammonite REPL.

5.1. Scala REPL and Compiler

We can uninstall Scala REPL using the uninstall command:

cs uninstall scala

Again, we can install Scala REPL by using the install command:

cs install scala

To install a particular version of Scala REPL, we can use the launch command:

cs launch scala:2.13.5

We can also update Scala REPL to the latest available version:

cs update scala

It’s also possible to launch a particular version of Scala REPL. This is very useful in cases where we need to try out some specific code in multiple Scala versions. Let’s launch Scala REPL for 2.12.12:

cs launch scala:2.12.12

Additionally, we can pass additional parameters to the cs launch command to customize our environment. If we want to use Scala REPL with JVM-11:

cs launch scala:2.12.12 --jvm 11

Coursier will download the requested versions of all JVMs and applications to its cache directory for the first time. Subsequent install commands will only update the path variables accordingly.

5.2. Other Scala Applications

Coursier supports more Scala-based applications like Ammonite, Scalafmt, and Metals. We can install, uninstall and launch these applications using the install, uninstall and launch commands.

5.3. Installing Contrib Applications

Apart from the core applications, there are many other applications available as well. To install the apps from Contrib channel, we’ll pass the additional parameter –contrib. We can install Zookeeper by:

cs install zookeeper --contrib

5.4. Installing Custom Applications

We can also manage our own applications that we’ve published to a central or local artifact repository like Maven Central, Sonatype, or JFrog. Let’s look at the steps involved in this.

First, we’ll configure the repository credentials using the credentials.properties file. Then, we’ll need to package our application and create a launcher using the bootstrap command:

cs bootstrap -r https://central_repo/repository groupId:artifactId:version -o app_name

The next step is to create a JSON descriptor file and publish it to a central location.

Finally, we can install the application using the cs install command by passing the path to the descriptor file:

cs install --channel https://app.descriptor.com/app_name.json app_name

Now, the application is installed and can be accessed by anyone using Coursier, using the command app_name.

6. Managing Library Artifacts

Coursier started as a tool that would quickly fetch artifacts. Later, the features like managing JVMs and Scala applications were added. Let’s see some other major features of Coursier.

6.1. CS Resolve

We can use Coursier to identify the transitive dependencies of a particular library:

cs resolve cs resolve com.typesafe.akka::akka-actor:2.5.6

This will show us all the dependencies of akka-actor-2.5.6;

If we want to view the dependencies in a tree structure, we need to add -t to the end:

cs resolve cs resolve com.typesafe.akka::akka-actor:2.5.6 -t

6.2. CS Complete

We can use the complete command to search for the different libraries:

cs complete org.scala-lang:

This will return a list of all published libraries under the groupId org.scala-lang.

Additionally, we can extend this to list all published versions of scala-library:

cs complete org.scala-lang:scala-library:

6.3. CS Fetch

The resolve command will only download the metadata files, whereas we can use fetch to download a particular library by providing the maven coordinates:

cs fetch org.scala-lang:scala-library:2.13.6

This will download version 2.13.6 of the scala-library.

7. Conclusion

In this tutorial, we looked at Coursier and many of the features available to help make the Scala development environment management easier.