Welcome!
This is the official repository for the Scala Programming Language
standard library, compiler, and language spec.
How to contribute
To contribute in this repo, please open a pull request from your fork of this repository.
We do have to ask you to sign the Scala CLA before we can merge any of your work, to protect its open source nature.
For more information on building and developing the core of Scala, make sure to read
the rest of this README!
In order to get in touch with other Scala contributors, join
scala/contributors (Gitter) or post on
contributors.scala-lang.org (Discourse).
Reporting issues
Please report bugs at the scala/bug issue tracker. We use the scala/scala-dev tracker for coordinating bigger work items.
Get in touch!
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..., --------------------------------------------------------------------------------------------------, ----------------------------------------------------------------, ---------------------------------------------------, , @adriaanm, type checker, pattern matcher, infrastructure, language spec, , @SethTisue, getting started, build, developer docs, community build, Jenkins, library, , @retronym, compiler performance, weird compiler bugs, Java 8 lambdas, REPL, , @szeiger, collections, build, , @lrytz, back end, optimizer, named & default arguments, , @Ichoran, collections library, performance, , @viktorklang, concurrency, futures, , @axel22, concurrency, parallel collections, specialization, , @dragos, specialization, back end, , @janekdb, documentation, , @sjrd, interactions with Scala.js, P.S.: If you have some spare time to help out around here, we would be delighted to add your name to this list!
Repository structure
scala/
+--build.sbt The main sbt build script
+--lib/ Pre-compiled libraries for the build
+--src/ All sources
+---/library Scala Standard Library
+---/reflect Scala Reflection
+---/compiler Scala Compiler
+---/intellij IntelliJ project templates
+--spec/ The Scala language specification
+--scripts/ Scripts for the CI jobs (including building releases)
+--test/ The Scala test suite
+---/files Partest tests
+---/junit JUnit tests
+---/scalacheck ScalaCheck tests
+--build/ [Generated] Build output directory
Get ready to contribute
Requirements
You need the following tools:
- Java SDK. The baseline version is 8 for both 2.12.x and 2.13.x. It may be possible to use a
later SDK for local development, but the CI will verify against the baseline
version.
- sbt (sbt 0.13 on the 2.12.x branch, sbt 1 on the 2.13.x branch)
MacOS and Linux work. Windows may work if you use Cygwin. Community help with keeping
the build working on Windows is appreciated.
We are grateful for the following OSS licenses:
Build setup
Basics
During ordinary development, a new Scala build is built by the
previously released version. For short we call the previous release
"starr": the stable reference release. Building with starr is
sufficient for most kinds of changes.
However, a full build of Scala (a bootstrap, as performed by our CI)
requires two layers. This guarantees that every Scala version can
build itself. If you change the code generation part of the Scala
compiler, your changes will only show up in the bytecode of the
library and compiler after a bootstrap. See below for how to do a
bootstrap build locally.
For history on how the current scheme was arrived at, see
https://groups.google.com/d/topic/scala-internals/gp5JsM1E0Fo/discussion.
Using the sbt build
Once you've started an sbt 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)dist/mkBin generates runner scripts (scala, scalac, etc) in build/quick/bindist/mkPack creates a build in the Scala distribution format in build/packtest runs the JUnit test, testOnly *immutable.ListTest runs a subsetpartest runs partest tests (accepts options, try partest --help)scalacheck/test runs scalacheck tests, scalacheck/testOnly *FloatFormatTest runs a subsetpublishLocal publishes a distribution locally (can be used as scalaVersion in
other sbt projects)
- Optionally
set baseVersionSuffix := "-bin-abcd123-SNAPSHOT"
where abcd123 is the git hash of the revision being published. You can also
use something custom like "-bin-mypatch". This changes the version number from
2.12.2-SNAPSHOT to something more stable (2.12.2-bin-abcd123-SNAPSHOT).
- Note that the
-bin string marks the version binary compatible. Using it in
sbt will cause the scalaBinaryVersion to be 2.12. If the version is not
binary compatible, we recommend using -pre, e.g., 2.13.0-pre-abcd123-SNAPSHOT.
- Optionally
set publishArtifact in (Compile, packageDoc) in ThisBuild := false
to skip generating / publishing API docs (speeds up the process).
If a command results in an error message like a module is not authorized to depend on itself, it may be that a global SBT plugin (such as ENSIME) is
resulting in a cyclical dependency. Try disabling global SBT plugins (perhaps by
temporarily commenting them out in ~/.sbt/1.0/plugins/plugins.sbt).
Sandbox
We recommend to keep local test files in the sandbox directory which is listed in
the .gitignore of the Scala repo.
Incremental compilation
Note that sbt's incremental compilation is often too coarse for the Scala compiler
codebase and re-compiles too many files, resulting in long build times (check
sbt#1104 for progress on that front). In the
meantime you can:
- Use IntelliJ IDEA for incremental compiles (see IDE Setup below) - its
incremental compiler is a bit less conservative, but usually correct.
Bootstrapping locally
To perform a bootstrap using sbt
- first a build is published either locally or on a temporary repository,
- then a separate invocation of sbt (using the previously built version as
starr)
is used to build / publish the actual build.
Assume the current starr version is 2.12.0 (defined in
versions.properties) and the current version is 2.12.0-SNAPSHOT
(defined in build.sbt). To perform a local bootstrap:
- Run
publishLocal (you may want to specify a custom version suffix and skip
generating API docs, see above).
- Quit sbt and start a new sbt instance using
sbt -Dstarr.version=<version> where
<version> is the version number you published locally.
- If the version number you published is not binary compatible with the current
starr, set every scalaBinaryVersion := "2.12.0-M4". This is not required if
the version you published locally is binary compatible, i.e., if the current
starr is a 2.12.x release and not a milestone / RC.
The last step is required to resolve modules (scala-partest, etc). It
assumes that the module releases for the current starr work (in terms of binary
compatibility) with the local starr that you published locally. A full bootstrap
requires re-building the all the modules. On our CI this is handled by the
bootstrap script, but it (currently) cannot
be easily executed locally.
IDE setup
You may use IntelliJ IDEA (see src/intellij/README.md),
or ENSIME (see this page on the ENSIME site).
(Support for Eclipse has decayed and been removed, but could be resurrected by
a volunteer.)
In order to use IntelliJ's incremental compiler:
- run
dist/mkBin in sbt to get a build and the runner scripts in build/quick/bin
- run "Build" - "Make Project" in IntelliJ
Now you can edit and build in IntelliJ and use the scripts (compiler, REPL) to
directly test your changes. You can also run the scala, scalac and partest
commands in sbt. Enable "Ant mode" (explained above) to prevent sbt's incremental
compiler from re-compiling (too many) files before each partest invocation.
Coding guidelines
Our guidelines for contributing are explained in CONTRIBUTING.md.
It contains useful information on our coding standards, testing, documentation, how
we use git and GitHub and how to get your code reviewed.
You may also want to check out the following resources:
Scala CI
Once you submit a PR your commits will be automatically tested by the Scala CI.
If you see a spurious build failure, you can post /rebuild as a PR comment.
The scabot README lists all available commands.
If you'd like to test your patch before having everything polished for review,
feel free to submit a PR and add the WIP label. In case your WIP branch contains
a 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 commit
will be tested, saving some energy and CI-resources. Note that inactive WIP PRs
will be closed eventually, which does not mean the change is being rejected.
CI performs a full bootstrap. The first task, validate-publish-core, publishes
a build of your commit to the temporary repository
https://scala-ci.typesafe.com/artifactory/scala-pr-validation-snapshots.
Note that this build is not yet bootstrapped, its bytecode is built using the
current starr. The version number is 2.12.2-bin-abcd123-SNAPSHOT where abcd123
is the commit hash. For binary incompatible builds, the version number is
2.13.0-pre-abcd123-SNAPSHOT.
You can use Scala builds in the validation repository locally by adding a resolver
and specifying the corresponding scalaVersion:
$ sbt
> set resolvers += "pr" at "https://scala-ci.typesafe.com/artifactory/scala-pr-validation-snapshots/"
> set scalaVersion := "2.12.2-bin-abcd123-SNAPSHOT"
> console
Note that the scala modules are currently not built/published against the
tested version during CI validation.
Nightly builds
The Scala CI builds nightly download releases (including all modules) and publishes
them to the following locations:
The CI also publishes nightly API docs:
Using a nightly build in sbt is explained in
this Stack Overflow answer
Scala CI internals
The Scala CI runs as a Jenkins instance on scala-ci.typesafe.com,
configured by a chef cookbook at scala/scala-jenkins-infra.
The build bot that watches PRs, triggers testing builds and applies the "reviewed" label
after an LGTM comment is in the scala/scabot repo.
The Scala community build is an important method for testing Scala
releases. A community build can be launched for any Scala commit, even
before the commit's PR has been merged. That commit is then used to
build a large number of open-source projects from source and run their
test suites.
To request a community build run on your PR, just ask in a comment on
the PR and a Scala team member (probably @SethTisue) will take care of
it. (details)
Community builds run on the Scala Jenkins instance. The jobs are
named ..-integrate-community-build. See the
scala/community-builds
repo.
