Repository files navigation

This is the home of theScala 2standard library, compiler, and language spec.

For Scala 3, visitscala/scala3.

Issues and bug reports for Scala 2 are located inscala/bug. That tracker is also where new contributors may find issues to work on:good first issues,help wanted.

For coordinating broader efforts, we also use thescala/scala-dev tracker.

To contribute here, please open apull request from your fork of this repository.

Be aware that we can't accept additions to the standard library, only modifications to existing code. Binary compatibility forbids adding new public classes or public methods. Additions are made toscala-library-next instead.

We require that you sign theScala CLA before we can merge any of your work, to protect Scala's future as open source software.

The general workflow is as follows.

1. Find/file an issue in scala/bug (or submit a well-documented PR right away!).
2. Fork the scala/scala repo.
3. Push your changes to a branch in your forked repo. For coding guidelines, gohere.
4. Submit a pull request to scala/scala from your forked repo.

For more information on building and developing the core of Scala, read the rest of this README, especially forsetting up your machine!

In order to get in touch with other Scala contributors, join the#scala-contributors channel on theScala Discord chat, or post oncontributors.scala-lang.org (Discourse).

If you need some help with your PR at any time, please feel free to @-mention anyone from the list below, and we will do our best to help you out:

	username	talk to me about...
	@lrytz	back end, optimizer, named & default arguments, reporters
	@retronym	compiler performance, weird compiler bugs, lambdas
	@SethTisue	getting started, build, CI, community build, Jenkins, docs, library, REPL
	@dwijnand	pattern matcher, MiMa, partest
	@som-snytt	warnings/lints/errors, REPL, compiler options, compiler internals, partest
	@Ichoran	collections library, performance
	@viktorklang	concurrency, futures
	@sjrd	interactions with Scala.js
	@NthPortal	library, concurrency,scala.math,LazyList,Using, warnings
	@bishabosha	TASTy reader
	@joroKr21	higher-kinded types, implicits, variance

P.S.: If you have some spare time to help out around here, we would be delighted to add your name to this list!

Target the oldest branch you would like your changes to end up in. We periodically merge forward from 2.12.x to 2.13.x. Most changes should target 2.13.x, as 2.12.x is now under minimal maintenance.

If your change is difficult to merge forward, you may be asked to also submit a separate PR targeting the newer branch.

If your change is version-specific and shouldn't be merged forward, put[nomerge] in the PR name.

If your change is a backport from a newer branch and thus doesn't need to be merged forward, put[backport] in the PR name.

Most changes should target 2.13.x. We are increasingly reluctant to target 2.12.x unless there is a special reason (e.g. if an especially bad bug is found, or if there is commercial sponsorship). SeeScala 2 maintenance.

Most importantly:

scala/+--build.sbt                 The main sbt build definition+--project/                  The rest of the sbt build+--src/                      All sources   +---/library              Scala Standard Library   +---/reflect              Scala Reflection   +---/compiler             Scala Compiler+--test/                     The Scala test suite   +---/files                Partest tests   +---/junit                JUnit tests   +---/scalacheck           ScalaCheck tests+--spec/                     The Scala language specification

but also:

scala/   +---/library-aux          Scala Auxiliary Library, for bootstrapping and documentation purposes   +---/interactive          Scala Interactive Compiler, for clients such as an IDE (aka Presentation Compiler)   +---/intellij             IntelliJ project templates   +---/manual               Scala's runner scripts "man" (manual) pages   +---/partest              Scala's internal parallel testing framework   +---/partest-javaagent    Partest's helper java agent   +---/repl                 Scala REPL core   +---/repl-frontend        Scala REPL frontend   +---/scaladoc             Scala's documentation tool   +---/scalap               Scala's class file decompiler   +---/testkit              Scala's unit-testing kit+--admin/                    Scripts for the CI jobs and releasing+--doc/                      Additional licenses and copyrights+--scripts/                  Scripts for the CI jobs and releasing+--tools/                    Scripts useful for local development+--build/                    Build products+--dist/                     Build products+--target/                   Build products

You need the following tools:

• Java SDK. The baseline version is 8 for both 2.12.x and 2.13.x. It is almost always fineto use a later SDK (such as 17 or 21) for local development. CI will verify against thebaseline version.
• sbt

MacOS and Linux work. Windows may work if you use Cygwin. Community help with keepingthe build working on Windows and documenting any needed setup is appreciated.

We are grateful for the following OSS licenses:

• JProfiler Java profiler
• YourKit Java Profiler
• IntelliJ IDEA
• 

During ordinary development, a new Scala build is built by thepreviously released version, known as the "reference compiler" or,slangily, as "STARR" (stable reference release). Building with STARRis sufficient for most kinds of changes.

However, a full build of Scala isbootstrapped. Bootstrapping hastwo steps: first, build with STARR; then, build again using thefreshly built compiler, leaving STARR behind. This guarantees thatevery Scala version can build itself.

If you change the code generation part of the Scala compiler, yourchanges will only show up in the bytecode of the library and compilerafter a bootstrap. Our CI does a bootstrapped build.

Bootstrapping locally: To perform a bootstrap, runrestarrFullwithin an sbt session. This will build and publish the Scaladistribution to your local artifact repository and then switch sbt touse that version as its newscalaVersion. You may then revert backwithreload. NoterestarrFull will also write the STARR versiontobuildcharacter.properties so you can switch back to it withrestarr without republishing. This will switch the sbt session touse thebuild-restarr andtarget-restarr directories instead ofbuild andtarget, which avoids wiping out classfiles andincremental metadata. IntelliJ will continue to be configured tocompile and run tests using the starr version inversions.properties.

For history on how the current scheme was arrived at, seehttps://groups.google.com/d/topic/scala-internals/gp5JsM1E0Fo/discussion.

Building with fatal warnings: To make warnings in the project fatal (i.e. turn them into errors), runset Global / fatalWarnings := true in sbt (replaceGlobal with the name of a module—such asreflect—to only make warnings fatal for that module). To disable fatal warnings again, eitherreload sbt, or runset Global / fatalWarnings := false (again, replaceGlobal with the name of a module if you only enabled fatal warnings for that module). CI always has fatal warnings enabled.

Once you've started ansbt session you can run one of the core commands:

• compile compiles all sub-projects (library, reflect, compiler, scaladoc, etc)
• scala /scalac run the REPL / compiler directly from sbt (accept options /arguments)
• enableOptimizer reloads the build with the Scala optimizer enabled. Our releases are built this way. Enable this when working on compiler performance improvements. When the optimizer is enabled the build will be slower and incremental builds can be incorrect.
• setupPublishCore runsenableOptimizer and configures a version number based on the current Git SHA. Often used as part of bootstrapping:sbt setupPublishCore publishLocal && sbt -Dstarr.version=<VERSION> testAll
• dist/mkBin generates runner scripts (scala,scalac, etc) inbuild/quick/bin
• dist/mkPack creates a build in the Scala distribution format inbuild/pack
• junit/test runs the JUnit tests;junit/testOnly *Foo runs a subset
• scalacheck/test runs scalacheck tests, usetestOnly to run a subset
• partest runs partest tests (accepts options, trypartest --help)
• publishLocal publishes a distribution locally (can be used asscalaVersion inother sbt projects)
  • Optionallyset baseVersionSuffix := "bin-abcd123-SNAPSHOT"whereabcd123 is the git hash of the revision being published. You can alsouse something custom like"bin-mypatch". This changes the version number from2.13.2-SNAPSHOT to something more stable (2.13.2-bin-abcd123-SNAPSHOT).
  • Note that the-bin string marks the version binary compatible. Using it insbt will cause thescalaBinaryVersion to be2.13. If the version is notbinary compatible, we recommend using-pre, e.g.,2.14.0-pre-abcd123-SNAPSHOT.
  • Optionallyset ThisBuild / Compile / packageDoc / publishArtifact := falseto skip generating / publishing API docs (speeds up the process).

If a command results in an error message likea module is not authorized to depend on itself, it may be that a global sbt plugin is causinga cyclical dependency. Try disabling global sbt plugins (perhaps bytemporarily commenting them out in~/.sbt/1.0/plugins/plugins.sbt).

We recommend keeping local test files in thesandbox directory which is listed inthe.gitignore of the Scala repo.

Note that sbt's incremental compilation is often too coarse for the Scala compilercodebase and re-compiles too many files, resulting in long build times (checksbt#1104 for progress on that front). In themeantime you can:

• Use IntelliJ IDEA for incremental compiles (seeIDE Setup below) - itsincremental compiler is a bit less conservative, but usually correct.

We suggest using IntelliJ IDEA (seesrc/intellij/README.md).

Metals may also work, but we don'tyet have instructions or sample configuration for that. A pull requestin this area would be exceedingly welcome. In the meantime, we arecollecting guidance atscala/scala-dev#668.

In order to use IntelliJ's incremental compiler:

• rundist/mkBin in sbt to get a build and the runner scripts inbuild/quick/bin
• run "Build" - "Make Project" in IntelliJ

Now you can edit and build in IntelliJ and use the scripts (compiler, REPL) todirectly test your changes. You can also run thescala,scalac andpartestcommands in sbt. Enable "Ant mode" (explained above) to prevent sbt's incrementalcompiler from re-compiling (too many) files before eachpartest invocation.

Our guidelines for contributing are explained inCONTRIBUTING.md.It contains useful information on our coding standards, testing, documentation, howwe use git and GitHub and how to get your code reviewed.

You may also want to check out the following resources:

• The"Scala Hacker Guide"covers some of the same ground as this README, but in greater detail and in a moretutorial style, using a running example.
• Scala documentation site

Once you submit a PR your commits will be automatically tested by the Scala CI.

Our CI setup is always evolving. Seescala/scala-dev#751for more details on how things currently work and how we expect theymight change.

If you see a spurious failure on Jenkins, you can post/rebuild as a PR comment.Thescabot README lists all available commands.

If you'd like to test your patch before having everything polished for review,you can have Travis CI build your branch (make sure you have a fork and have Travis CIenabled for branch builds on it first, and then push your branch). Alsofeel free to submit a draft PR. In case your draft branch containsa large number of commits (that you didn't clean up / squash yet for review),consider adding[ci: last-only] to the PR title. That way only the last commitwill be tested, saving some energy and CI-resources. Note that inactive draft PRswill be closed eventually, which does not mean the change is being rejected.

CI performs a compiler bootstrap. The first task,validatePublishCore, publishesa build of your commit to the temporary repositoryhttps://scala-ci.typesafe.com/artifactory/scala-pr-validation-snapshots.Note that this build is not yet bootstrapped, its bytecode is built using thecurrent STARR. The version number is2.13.2-bin-abcd123-SNAPSHOT whereabcd123is the commit hash. For binary incompatible builds, the version number is2.14.0-pre-abcd123-SNAPSHOT.

You can use Scala builds in the validation repository locally by adding a resolverand specifying the correspondingscalaVersion:

$ sbt> set resolvers += "pr" at "https://scala-ci.typesafe.com/artifactory/scala-pr-validation-snapshots/"> set scalaVersion := "2.13.17-bin-abcd123-SNAPSHOT"> console

The Scala CI publishes these tohttps://scala-ci.typesafe.com/artifactory/scala-integration/ .

Using a nightly build in sbt and other tools is explained on thisdoc page.

Although we casually refer to these as "nightly" builds, they aren'tactually built nightly, but "mergely". That is to say, a build ispublished for every merged PR.

The Scala CI runs as a Jenkins instance onscala-ci.typesafe.com,configured by a chef cookbook atscala/scala-jenkins-infra.

The build bot that watches PRs, triggers testing builds and applies the "reviewed" labelafter an LGTM comment is in thescala/scabot repo.

The Scala community build is an important method for testing Scalareleases. A community build can be launched for any Scala commit, evenbefore the commit's PR has been merged. That commit is then used tobuild a large number of open-source projects from source and run theirtest suites.

To request a community build run on your PR, just ask in a comment onthe PR and a Scala team member (probably @SethTisue) will take care ofit. (details)

Community builds run on the Scala Jenkins instance. The jobs arenamed..-integrate-community-build. See thescala/community-buildsrepo.