This guide demonstrates how to create a Scala library in the standard form using Gradle’s Build Init plugin.

What you’ll build

You’ll generate a Scala library with the standard layout.

What you’ll need

  • About

  • A text editor

  • A command prompt

  • The Java Development Kit (JDK), version 1.7 or higher

  • A Gradle distribution, version 4.10.3 or better

Check the user manual

Gradle comes with a built-in plugin called the Build Init plugin. It is documented in the Gradle User Manual. The plugin has one task, called init, that generates the project. The init task calls the (also built-in) wrapper task to create a Gradle wrapper script, gradlew.

The first step is to create a folder for the new project and change directory into it.

$ mkdir building-scala-libraries
$ cd building-scala-libraries

Run the init task

From inside the new project directory, run the init task with the scala-library argument.

$ gradle init --type scala-library --package guidesamples
> Task :wrapper

Select build script DSL:
  1: Groovy
  2: Kotlin
Enter selection (default: Groovy) [1..2]

Project name (default: building-scala-libraries):

> Task :init
Get more help with your project:

2 actionable tasks: 2 executed

The init task runs the wrapper task first, which generates the gradlew and gradlew.bat wrapper scripts. Then it creates the new project with the following structure:

├── build.gradle
├── gradle
│   └── wrapper  (1)
│       ├── gradle-wrapper.jar
│       └──
├── gradlew
├── gradlew.bat
├── settings.gradle
└── src
    ├── main
    │   └── scala  (2)
    │       └── guidesamples
    │           └── Library.scala
    └── test
        └── scala (3)
            └── guidesamples
                └── LibrarySuite.scala
1 Generated folder for wrapper files
2 Default Scala source folder
3 Default Scala test folder

Review the generated project files

The settings.gradle file is heavily commented, but has only one active line:

Generated settings.gradle = 'building-scala-libraries' (1)
1 This assigns the name of the root project.

The generated build.gradle file also has many comments. The active portion is reproduced here (note version numbers for the dependencies may be updated in later versions of Gradle):

Generated build.gradle
plugins {
    id 'scala'

    id 'java-library'

repositories {
    jcenter() (1)

dependencies {
    implementation 'org.scala-lang:scala-library:2.12.9' (2)

    testImplementation 'junit:junit:4.12' (3)
    testImplementation 'org.scalatest:scalatest_2.12:3.0.8' (4)

    testRuntimeOnly 'org.scala-lang.modules:scala-xml_2.12:1.2.0' (5)
1 Public Bintray Artifactory repository
2 Scala version that this project will include as dependency
3 JUnit testing library
4 Scala testing library
5 Scala XML library is required for testing

The build file adds the scala plugin. This is an extension of the java plugins and adds additional tasks for compiling Scala source code. It also allows for joint compilation of Scala and Java files if found in the appropriate scala source folders.

The file src/main/scala/Library.scala is shown here:

Generated src/main/scala/Library.scala
package guidesamples

class Library {
  def someLibraryMethod(): Boolean = true

The generated Scala test suite, src/test/scala/LibrarySuite.scala is shown next:

Generated src/test/scala/LibrarySuite.scala
package guidesamples

import org.scalatest.FunSuite
import org.junit.runner.RunWith
import org.scalatest.junit.JUnitRunner

class LibrarySuite extends FunSuite {
  test("someLibraryMethod is always true") {
    def library = new Library()

The generated test class consists of a single Scala FunSuite. The test instantiates the Library class, invokes the someLibraryMethod method, and checks that the returned value is `true.

Execute the build

To build the project, run the build task. You can use the regular gradle command, but when a project includes a wrapper script, it is considered good form to use it instead.

$ ./gradlew build
> Task :compileJava NO-SOURCE
> Task :compileScala
> Task :processResources NO-SOURCE
> Task :classes
> Task :jar
> Task :assemble
> Task :compileTestJava NO-SOURCE
> Task :compileTestScala
> Task :processTestResources NO-SOURCE
> Task :testClasses
> Task :test
> Task :check
> Task :build

4 actionable tasks: 4 executed
The first time you run the wrapper script, gradlew, there may be a delay while that version of gradle is downloaded and stored locally in your ~/.gradle/wrapper/dists folder.

The first time you run the build, Gradle will check whether or not you already have the Scala, ScalaTest and JUnit libraries in your cache under your ~/.gradle directory. If not, the libraries will be downloaded and stored there. The next time you run the build, the cached versions will be used. The build task compiles the classes, runs the tests, and generates a test report.

You can view the test report by opening the HTML output file, located at build/reports/tests/test/index.html.

A sample report is shown here:

Test Summary

Congratulations, you have just completed the step from creating a Scala library! You can can now customise this to your own project needs.

Adding API documentation

The scala plugin has built-in support for Scala’s API documentation tool scaladoc.

The code generated by the Build Init plugin already placed a comment on the Library.scala file. Modify the comment to become Scaladoc markup.

/** This Scala source file was generated by the Gradle 'init' task.
package guidesamples

class Library {
  def someLibraryMethod(): Boolean = true

Run the scaladoc task.

$ ./gradlew scaladoc
> Task :compileJava NO-SOURCE
> Task :compileScala UP-TO-DATE
> Task :processResources NO-SOURCE
> Task :classes UP-TO-DATE

> Task :scaladoc
[ant:scaladoc] Element '/working-directory/building-scala-libraries/build/classes/java/main' does not exist.
[ant:scaladoc] Element '/working-directory/building-scala-libraries/build/resources/main' does not exist.

2 actionable tasks: 1 executed, 1 up-to-date

You can view the generated Scaladoc by opening the HTML file, located at build/docs/scaladoc/index.html.


You now have a new Scala project that you generated using Gradle’s build init plugin. In the process, you saw:

  • How to generate a Scala library

  • How the generated build file and sample Scala files are structured

  • How to run the build and view the test report

  • Generating API documentation.

Next Steps

Help improve this guide

Have feedback or a question? Found a typo? Like all Gradle guides, help is just a GitHub issue away. Please add an issue or pull request to gradle/guides and we’ll get back to you.