diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 86 |
1 files changed, 39 insertions, 47 deletions
@@ -42,8 +42,6 @@ P.S.: If you have some spare time to help out around here, we would be delighted ``` scala/ +--build.sbt The main sbt build script -+--build.xml The deprecated Ant build script -+--pull-binary-libs.sh Pulls binary artifacts from remote repository, used by build scripts +--lib/ Pre-compiled libraries for the build +--src/ All sources +---/library Scala Standard Library @@ -64,13 +62,11 @@ scala/ ## Requirements You need the following tools: - - A Java SDK. The baseline version is 6 for 2.11.x, 8 for 2.12.x. It's possible - to use a later SDK for local development, but the CI will verify against the baseline - version. - - sbt, we recommend the [sbt-extras](https://github.com/paulp/sbt-extras) runner - script. It provides sensible default jvm options (stack and heap size). - - curl (for `./pull-binary-libs.sh`, used by the sbt / ant build). - - Apache Ant (version 1.9.x, minimum 1.9.3; Ant 1.10+ doesn't work on Java 6) if you are using the ant build. + - Java SDK. The baseline version is 8 for 2.12.x. It may be possible to use a + later SDK for local development, but the CI will verify against the baseline + version. + - sbt. We recommend the [sbt-extras](https://github.com/paulp/sbt-extras) runner + script. It provides sensible default jvm options (stack and heap size). Mac OS X and Linux work. Windows may work if you use Cygwin. Community help with keeping the build working on Windows is appreciated. @@ -79,32 +75,25 @@ the build working on Windows is appreciated. ### Basics -Scala is built in layers, where each layer is a complete Scala compiler and library. -Here is a short description of the layers, from bottom to top: +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 Scala release. Building with starr is +sufficient for most kinds of changes. - - `starr`: the stable reference Scala release. We use an official release of - Scala (specified by `starr.version` in [versions.properties](versions.properties)), - downloaded from the Central Repository. - - `locker` (deprecated, only in ant): an intermediate layer that existed in the - ant build to perform a bootstrap. - - `quick`: the development layer which is incrementally built when working on - changes in the compiler or library. - - `strap` (deprecated, only in ant) : a test layer used to check stability of - the build. +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. -The sbt build uses `starr` to build `quick`. This is sufficient for most development -scenarios: changes to the library or the compiler can be tested by running the `quick` -Scala (see below for how to do that). +For history on how the current scheme was arrived at, see +https://groups.google.com/d/topic/scala-internals/gp5JsM1E0Fo/discussion. -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 reflect in the -bytecode of the library and compiler after a bootstrap. See below for how to create -a bootstrap build locally. - -### Using the Sbt Build +### Using the sbt Build Core commands: + - `compile` compiles all sub-projects (library, reflect, compiler, scaladoc, etc) - `scala` / `scalac` run the REPL / compiler directly from sbt (accept options / arguments) @@ -114,10 +103,13 @@ Core commands: - `partest` runs partest tests (accepts options, try `partest --help`) - `publishLocal` publishes a distribution locally (can be used as `scalaVersion` in other sbt projects) - - Optionally `set VersionUtil.baseVersionSuffix in Global := "abcd123-SNAPSHOT"` + - Optionally `set baseVersionSuffix := "-bin-abcd123-SNAPSHOT"` where `abcd123` is the git hash of the revision being published. You can also - use something custom like `"mypatch"`. This changes the version number from - `2.12.0-SNAPSHOT` to something more stable (`2.12.0-abcd123-SNAPSHOT`). + 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). @@ -132,20 +124,20 @@ Note that sbt's incremental compilation is often too coarse for the Scala compil codebase and re-compiles too many files, resulting in long build times (check [sbt#1104](https://github.com/sbt/sbt/issues/1104) for progress on that front). In the meantime you can: - - Enable "ant mode" in which sbt only re-compiles source files that were modified. + - Enable "Ant mode" in which sbt only re-compiles source files that were modified. Create a file `local.sbt` containing the line `antStyle := true`. Add an entry `local.sbt` to your `~/.gitignore`. - Use IntelliJ IDEA for incremental compiles (see [IDE Setup](#ide-setup) below) - its incremental compiler is a bit less conservative, but usually correct. -#### Local Bootstrap Build +#### 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-M4` (defined in +Assume the current `starr` version is `2.12.0` (defined in [versions.properties](versions.properties)) and the current version is `2.12.0-SNAPSHOT` (defined in [build.sbt](build.sbt)). To perform a local bootstrap: - Run `publishLocal` (you may want to specify a custom version suffix and skip @@ -166,8 +158,9 @@ be easily executed locally. ### IDE Setup -You may use IntelliJ IDEA ([src/intellij/README.md](src/intellij/README.md)) or the -Scala IDE for Eclipse (see [src/eclipse/README.md](src/eclipse/README.md)). +You may use IntelliJ IDEA (see [src/intellij/README.md](src/intellij/README.md)), +the Scala IDE for Eclipse (see [src/eclipse/README.md](src/eclipse/README.md)), +or ENSIME (see [this page on the ENSIME site](http://ensime.github.io//contributing/scalac/)). 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` @@ -175,7 +168,7 @@ In order to use IntelliJ's incremental compiler: 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 +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 @@ -192,7 +185,7 @@ You may also want to check out the following resources: # Scala CI -Once you submit a PR your commits will are automatically tested by the 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](https://github.com/scala/scabot) lists all available commands. @@ -208,8 +201,9 @@ 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.0-abcd123-SNAPSHOT` where `abcd123` -is the commit hash. +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`: @@ -217,7 +211,7 @@ and specifying the corresponding `scalaVersion`: ``` $ sbt > set resolvers += "pr" at "https://scala-ci.typesafe.com/artifactory/scala-pr-validation-snapshots/" -> set scalaVersion := "2.12.0-abcd123-SNAPSHOT" +> set scalaVersion := "2.12.2-bin-abcd123-SNAPSHOT" > console ``` @@ -237,10 +231,8 @@ The CI also publishes nightly API docs: - [2.11.x](http://www.scala-lang.org/files/archive/nightly/2.11.x/api/?C=M;O=D) - [symlink to the latest](http://www.scala-lang.org/files/archive/nightly/2.11.x/api/2.11.x/) -Note that we currently don't publish nightly (or SNAPSHOT) builds in maven or ivy -format to any repository. You can track progress on this front at -[scala-jenkins-infra#133](https://github.com/scala/scala-jenkins-infra/issues/133) -and [scala-dev#68](https://github.com/scala/scala-dev/issues/68). +Using a nightly build in sbt is explained in +[this answer on Stack Overflow](http://stackoverflow.com/questions/40622878) ## Scala CI Internals |