Need help with scala?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

scala
13.0K Stars 3.0K Forks Apache License 2.0 36.2K Commits 71 Opened issues

Description

Scala 2 compiler and standard library. For bugs, see scala/bug

Services available

!
?

Need anything else?

Contributors list

Welcome!

This is the official repository for the Scala Programming Language standard library, compiler, and language spec.

How to contribute

Issues and bug reports for scala/scala are located in scala/bug. This tracker is also where new contributors may find good first issues to work on.

To contribute in this repo, please open a pull request from your fork of this repository.

For coordinating bigger work items, we use the scala/scala-dev tracker.

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 to scala-library-next instead.

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.

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, go here. 4. Submit a pull request to scala/scala from your forked repo.

For more information on building and developing the core of Scala, make sure to read the rest of this README, especially for setting up your machine!

Get in touch!

In order to get in touch with other Scala contributors, join scala/contributors (Gitter) or post on contributors.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... | --------------------------------------------------------------------------------------------------|----------------------------------------------------------------|---------------------------------------------------| |

@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, reporters | |
@Ichoran
| collections library, performance | |
@viktorklang
| concurrency, futures | |
@axel22
| concurrency, parallel collections, specialization | |
@dragos
| specialization, back end | |
@janekdb
| documentation | |
@sjrd
| interactions with Scala.js | |
@NthPortal
| library, concurrency,

scala.math
,
LazyList
,
Using
|

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

Branches

Target the oldest branch you would like your changes to end up in. We periodically merge forward from older release branches (e.g., 2.12.x) to new ones (e.g. 2.13.x).

If your change might be 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 therefore doesn't need to be merged forward, put

[backport]
in the PR name.

Choosing a branch

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).

The 2.11.x branch is now inactive and no further 2.11.x releases are planned -- unless unusual, unforeseeable circumstances arise. You should not target 2.11.x without asking maintainers first.

Repository structure

scala/
+--build.sbt                 The main sbt build script
+--lib/                      Pre-compiled libraries for the build
+--src/                      All sources
   +---/library              Scala Standard Library
   +---/library-aux          Scala Auxiliary Library, for bootstrapping and documentation purposes
   +---/reflect              Scala Reflection
   +---/compiler             Scala Compiler
   +---/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
+--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

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

Tools we use

We are grateful for the following OSS licenses: - JProfiler Java profiler - YourKit Java Profiler - IntelliJ IDEA

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)
  • 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
    which runs
    enableOptimizer
    and also configures a version number based on the current Git SHA. Often used as part of bootstrapping
    sbt setupPublishCore publishLocal && sbt -Dstarr.version= testAll
  • dist/mkBin
    generates runner scripts (
    scala
    ,
    scalac
    , etc) in
    build/quick/bin
  • dist/mkPack
    creates a build in the Scala distribution format in
    build/pack
  • test
    runs the JUnit test,
    testOnly *immutable.ListTest
    runs a subset
  • partest
    runs partest tests (accepts options, try
    partest --help
    )
  • scalacheck/test
    runs scalacheck tests,
    scalacheck/testOnly *FloatFormatTest
    runs a subset
  • publishLocal
    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 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 run

restarrFull
within an sbt session. This will build and publish the Scala distribution to your local artifact repository and then switch sbt to use that version as its new
scalaVersion
. You may then revert back with
reload
. Note
restarrFull
will also write the STARR version to
buildcharacter.properties
so you can switch back to it with
restarr
without republishing (though incremental compilation will recompile from scratch, sadly.)

IDE setup

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

(Metals should also work, but we don't yet have instructions or sample configuration for that. A pull request in this area would be exceedingly welcome.)

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: - The "Scala Hacker Guide" covers some of the same ground as this README, but in greater detail and in a more tutorial style, using a running example. - Scala documentation site

Scala CI

Build Status

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, you can have Travis CI build your branch (make sure you have a fork and have Travis CI enabled for branch builds on it first, and then push your branch). Also feel free to submit a draft PR. In case your draft 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 draft PRs will be closed eventually, which does not mean the change is being rejected.

CI performs a compiler 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

"Nightly" builds

The Scala CI builds nightly download releases and publishes them to https://scala-ci.typesafe.com/artifactory/scala-integration/ .

Using a nightly build in sbt is explained in this Stack Overflow answer

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

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.

Community build

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.