Announcing Scala.js 0.6.20.

_config.yml

@@ -57,7 +57,7 @@ colors: #in hex code if not noted else
 
 ### VERSIONS ###
 versions:
- scalaJS: 0.6.19
+ scalaJS: 0.6.20
  scalaJSBinary: 0.6
  scalaJSDev: 1.0.0-M1
  scalaJSDevBinary: 1.0.0-M1

_posts/news/2017-09-01-announcing-scalajs-0.6.20.md

@@ -0,0 +1,182 @@
+---
+layout: post
+title: Announcing Scala.js 0.6.20
+category: news
+tags: [releases]
+permalink: /news/2017/09/01/announcing-scalajs-0.6.20/
+---
+
+
+We are pleased to announce the release of Scala.js 0.6.20!
+
+This release is mostly intended to bridge the gap between the 0.6.x and 1.x branches, to make it easier to cross-compile and/or migrate.
+
+Read on for more details.
+
+<!--more-->
+
+## Getting started
+
+If you are new to Scala.js, head over to
+[the tutorial]({{ BASE_PATH }}/tutorial/).
+
+## Release notes
+
+If upgrading from Scala.js 0.6.14 or earlier, make sure to read [the release notes of 0.6.15]({{ BASE_PATH }}/news/2017/03/21/announcing-scalajs-0.6.15/), which contain important migration information.
+
+As a minor release, 0.6.20 is backward source and binary compatible with previous releases in the 0.6.x series.
+Libraries compiled with earlier versions can be used with 0.6.20 without change.
+0.6.20 is also forward binary compatible with 0.6.{17-19}, but not with earlier releases: libraries compiled with 0.6.20 cannot be used by projects using 0.6.{0-16}.
+
+Please report any issues [on GitHub](https://github.com/scala-js/scala-js/issues).
+
+## Breaking changes
+
+### sbt 0.13.16 or above is required (or sbt 1.x)
+
+The sbt plugin of Scala.js 0.6.20 starts using features of sbt 0.13.16.
+If you are using an older version of sbt 0.13.x, you will have to upgrade to 0.13.16 or later.
+
+Since 0.6.19, Scala.js also supports sbt 1.0.0+.
+
+### `scalajs-env-selenium` has to be upgraded to 0.2.0
+
+Scala.js 0.6.20 contains internal changes to improve the so-called test adapter, which is the mechanism used by sbt to communicate with testing frameworks.
+These changes are invisible to you, but they broke [`scalajs-env-selenium`](https://github.com/scala-js/scala-js-env-selenium) 0.1.x.
+If you use it, you will have to upgrade it to 0.2.0.
+
+## Deprecations
+
+Scala.js 0.6.20 introduces more aggressive deprecations for features that will disappear in 1.x.
+Note that those features have already had better replacements since Scala.js 0.6.18; we are just making it more obvious that these new features should be used to be compatible with 1.x.
+
+### `@ScalaJSDefined`
+
+This annotation is now deprecated.
+Instead of using it, you should add the following to your project settings:
+
+{% highlight scala %}
+scalacOptions += "-P:scalajs:sjsDefinedByDefault"
+{% endhighlight %}
+
+and remove the `@ScalaJSDefined` annotations everywhere in your codebase.
+The semantics of your codebase will be unchanged.
+
+### `js.JSApp`
+
+`js.JSApp` has traditionally provided two services to an `object Foo` that extends it.
+These two services are replaced by two different features.
+
+#### Discoverability by sbt as main object
+
+Since Scala.js 0.6.18, the sbt plugin can recognize "standard" `main` methods of the form
+
+{% highlight scala %}
+def main(args: Array[String]): Unit = ...
+{% endhighlight %}
+
+in objects, even if they do not extend `js.JSApp`.
+Use such a main method to replace `js.JSApp` in the context of discoverability by sbt.
+
+To enable it as main method, make sure you also set
+
+{% highlight scala %}
+scalaJSUseMainModuleInitializer := true
+{% endhighlight %}
+
+in your project settings.
+
+#### Automatic export to JavaScript
+
+Given
+
+{% highlight scala %}
+package bar
+
+object Foo extends js.JSApp {
+ def main(): Unit = println("Hello world!")
+}
+{% endhighlight %}
+
+the object `Foo` and its `main` method are automatically exported such that JavaScript code can call
+
+{% highlight javascript %}
+bar.Foo().main();
+{% endhighlight %}
+
+To achieve exactly the same behavior without `js.JSApp`, define `Foo` as
+
+{% highlight scala %}
+package bar
+
+object Foo {
+ @JSExportTopLevel("bar.Foo")
+ protected def getInstance(): this.type = this
+
+ @JSExport
+ def main(): Unit = println("Hello world!")
+}
+{% endhighlight %}
+
+Alternatively, you can define it as
+
+{% highlight scala %}
+package bar
+
+object Foo {
+ @JSExportTopLevel("bar.Foo.main")
+ def main(): Unit = println("Hello world!")
+}
+{% endhighlight %}
+
+but in that case, the JavaScript code will have to be changed to
+
+{% highlight javascript %}
+bar.Foo.main();
+{% endhighlight %}
+
+### `jsDependencies += RuntimeDOM` and `requiresDOM := true`
+
+These settings will not be supported by [`sbt-jsdependencies`](https://github.com/scala-js/jsdependencies) 1.x, the new home of `jsDependencies` and related features.
+
+Instead of relying on them to configure a JS environment equipped with the DOM, you should explicitly do so.
+For example, to use Node.js with jsdom, use:
+
+{% highlight scala %}
+jsEnv := new org.scalajs.jsenv.jsdomnodejs.JSDOMNodeJSEnv()
+{% endhighlight %}
+
+## New features
+
+### Improved support for cross-compilation with 1.x and `jsDependencies`
+
+[The release notes of Scala.js 1.0.0-M1]({{ BASE_PATH }}/news/2017/07/03/announcing-scalajs-1.0.0-M1/) detail how to cross-compile between 0.6.x and 1.x.
+One aspect of it was particularly painful: handling the new `JSDependenciesPlugin`.
+Scala.js 0.6.20 makes this easier by introducing a shim of `JSDependenciesPlugin` inside sbt-scalajs.
+It is now sufficient to add the following to your `project/plugins.sbt`:
+
+{% highlight scala %}
+// For jsDependencies
+{
+ if (scalaJSVersion.startsWith("0.6.")) Nil
+ else Seq(addSbtPlugin("org.scala-js" % "sbt-jsdependencies" % "1.0.0-M1"))
+}
+{% endhighlight %}
+
+and add `enablePlugins(JSDependenciesPlugin)` to the projects that require it.
+There is no need for the hacky `project/JSDependenciesCompat.scala` anymore.
+
+### JDK APIs
+
+The following JDK API class has been added:
+
+* `java.util.SplittableRandom`
+
+## Bug fixes
+
+The following bugs have been fixed in 0.6.20:
+
+* [#3107](https://github.com/scala-js/scala-js/issues/3107) `ByteArrayOutputStream` (and in general all `Closeable`s) should be an `AutoCloseable`
+* [#3082](https://github.com/scala-js/scala-js/issues/3082) Incorrect handling of main generates broken code
+
+You can find the full list [on GitHub](https://github.com/scala-js/scala-js/issues?q=is%3Aissue+milestone%3Av0.6.20+is%3Aclosed).

doc/all-api.md

@@ -5,6 +5,17 @@ title: All previous versions of the Scala.js API
 
 ## All previous versions of the API
 
+### Scala.js 0.6.20
+* [0.6.20 scalajs-library]({{ site.production_url }}/api/scalajs-library/0.6.20/#scala.scalajs.js.package)
+* [0.6.20 scalajs-test-interface]({{ site.production_url }}/api/scalajs-test-interface/0.6.20/)
+* [0.6.20 scalajs-stubs]({{ site.production_url }}/api/scalajs-stubs/0.6.20/)
+* [0.6.20 scalajs-ir]({{ site.production_url }}/api/scalajs-ir/0.6.20/#org.scalajs.core.ir.package)
+* [0.6.20 scalajs-tools]({{ site.production_url }}/api/scalajs-tools/0.6.20/#org.scalajs.core.tools.package) ([Scala.js version]({{ site.production_url }}/api/scalajs-tools-js/0.6.20/#org.scalajs.core.tools.package))
+* [0.6.20 scalajs-js-envs]({{ site.production_url }}/api/scalajs-js-envs/0.6.20/#org.scalajs.jsenv.package)
+* [0.6.20 scalajs-js-envs-test-kit]({{ site.production_url }}/api/scalajs-js-envs-test-kit/0.6.20/#org.scalajs.jsenv.test.package)
+* [0.6.20 scalajs-test-adapter]({{ site.production_url }}/api/scalajs-sbt-test-adapter/0.6.20/#org.scalajs.testadapter.package)
+* [0.6.20 sbt-scalajs]({{ site.production_url }}/api/sbt-scalajs/0.6.20/#org.scalajs.sbtplugin.package)
+
 ### Scala.js 0.6.19
 * [0.6.19 scalajs-library]({{ site.production_url }}/api/scalajs-library/0.6.19/#scala.scalajs.js.package)
 * [0.6.19 scalajs-test-interface]({{ site.production_url }}/api/scalajs-test-interface/0.6.19/)

doc/internals/downloads.md

@@ -7,6 +7,14 @@ We strongly recommend using the SBT plugin, as shown in the [bootstrapping skele
 
 The CLI distribution requires `scala` and `scalac` (of the right major version) to be on the execution path. Unpack it wherever you like and add the `bin/` folder to your execution path.
 
+#### Scala.js 0.6.20
+* [0.6.20, Scala 2.12 (tgz, 17MB)]({{ site.production_url }}/files/scalajs_2.12-0.6.20.tgz)
+* [0.6.20, Scala 2.12 (zip, 17MB)]({{ site.production_url }}/files/scalajs_2.12-0.6.20.zip)
+* [0.6.20, Scala 2.11 (tgz, 29MB)]({{ site.production_url }}/files/scalajs_2.11-0.6.20.tgz)
+* [0.6.20, Scala 2.11 (zip, 29MB)]({{ site.production_url }}/files/scalajs_2.11-0.6.20.zip)
+* [0.6.20, Scala 2.10 (tgz, 23MB)]({{ site.production_url }}/files/scalajs_2.10-0.6.20.tgz)
+* [0.6.20, Scala 2.10 (zip, 23MB)]({{ site.production_url }}/files/scalajs_2.10-0.6.20.zip)
+
 #### Scala.js 0.6.19
 * [0.6.19, Scala 2.12 (tgz, 16MB)]({{ site.production_url }}/files/scalajs_2.12-0.6.19.tgz)
 * [0.6.19, Scala 2.12 (zip, 16MB)]({{ site.production_url }}/files/scalajs_2.12-0.6.19.zip)

doc/internals/version-history.md

@@ -5,6 +5,7 @@ title: Version history
 
 ## Version history of Scala.js
 
+- [0.6.20](/news/2017/09/01/announcing-scalajs-0.6.20/)
 - [0.6.19](/news/2017/07/29/announcing-scalajs-0.6.19/)
 - [1.0.0-M1](/news/2017/07/03/announcing-scalajs-1.0.0-M1/)
 - [0.6.18](/news/2017/06/28/announcing-scalajs-0.6.18/)

doc/project/building.md

@@ -44,9 +44,10 @@ Now, the .js file produced by `fastOptJS` will print `"Hello world!"`.
 Note that this will require that there is a *unique* such object or that the one to use be explicitly set with `mainClass in Compile := Some(<name>)`.
 If you explicitly set `mainClass`, note that it needs to be set on a per-configuration basis (i.e. the part `in Compile` is essential, otherwise the setting will be ignored). For further information see the Stack Overflow entry ['How to set mainClass in ScalaJS build.sbt?'](http://stackoverflow.com/questions/34965072/how-to-set-mainclass-in-scalajs-build-sbt) (specific to Scala.js) and the Stack Overflow entry ['How to set main class in build?'](http://stackoverflow.com/questions/6467423/how-to-set-main-class-in-build) (not specific to Scala.js).
 
-**Note for Scala.js 0.6.17 and earlier:** in Scala.js 0.6.17 and earlier, the main object was required to extend the special trait [`js.JSApp`]({{ site.production_url }}/api/scalajs-library/0.6.18/#scala.scalajs.js.JSApp).
+**Note for Scala.js 0.6.17 and earlier:** in Scala.js 0.6.17 and earlier, the main object was required to extend the special trait [`js.JSApp`]({{ site.production_url }}/api/scalajs-library/0.6.20/#scala.scalajs.js.JSApp).
 Since 0.6.18, any object with a standard `main` method will be recognized.
-`js.JSApp` is not recommended for new code.
+`js.JSApp` is now deprecated.
+See [the Scaladoc of `js.JSApp`]({{ site.production_url }}/api/scalajs-library/0.6.20/#scala.scalajs.js.JSApp) for migration tips.
 
 ## Running in the console
 
@@ -58,7 +59,7 @@ This will run the `-fastopt.js` file right inside of your sbt console.
 By default, the file is run with [Node.js](http://nodejs.org/), which you need to install separately.
 
 **Scala.js 0.6.x only:** If your application or one of its libraries requires a DOM (which can be specified with `jsDependencies += RuntimeDOM`), you will also need to install [`jsdom`](https://github.com/tmpvar/jsdom) with `npm install jsdom`.
-`jsDependencies += RuntimeDOM` is not recommended for new code, and should be replaced by `jsEnv := new org.scalajs.jsenv.jsdomnodejs.JSDOMNodeJSEnv()`.
+`jsDependencies += RuntimeDOM` is now deprecated, and should be replaced by `jsEnv := new org.scalajs.jsenv.jsdomnodejs.JSDOMNodeJSEnv()`.
 
 There are alternative JavaScript interpreters that are available.
 See [JavaScript environments](./js-environments.html) for more details.

doc/project/js-environments.md

@@ -46,6 +46,7 @@ libraryDependencies += "org.scala-js" %% "scalajs-env-jsdom-nodejs" % "1.0.0-M1"
 {% endhighlight %}
 
 **Scala.js 0.6.x:** This environment is selected by default if your application or one of its libraries declares a dependency on the DOM, with `jsDependencies += RuntimeDOM`.
+Note that this is deprecated, so you should use `jsEnv := ...` anyway.
 
 ## PhantomJS
 

doc/project/testing.md

@@ -4,7 +4,7 @@ title: Testing
 ---
 
 In this section we will discuss how to test Scala.js code managed as [Full cross project](./cross-build.html). All names
-for example subproject name such as `fooJVM` are taken from 
+for example subproject name such as `fooJVM` are taken from
 [cross compile example](https://github.com/scala-js/scalajs-cross-compile-example).
 
 ## Directory Structure
@@ -30,28 +30,39 @@ parts, so when calling `sbt> test` will effectively run both `fooJVM/test` and `
 
 ## Integration testing
 
-Configuring a regular non-Scala.js sbt project to have `it:test` is a well described task, see 
-[documentation](http://www.scala-sbt.org/0.13/docs/Testing.html#Integration+Tests) for more details.
-In a `CrossProject` it won't work out-of-the-box because of 2 reasons. First reason is that by default Scala JVM and
-Scala.js `it` configurations won't be aware of `shared/src/it/scala` folder. Second is that Scala.js `it` configuration
-by default does not contain `ScalaJSClassLoader` definition required for running Scala.js tests. To fix that you need to
-add the following settings to the crossProject definition along with `IntegrationTest` settings:
+Configuring a regular non-Scala.js sbt project to have `it:test` is
+[documented in sbt](http://www.scala-sbt.org/0.13/docs/Testing.html#Integration+Tests).
+For a Scala.js project, you will also need to install the Scala.js-specific settings and tasks to the `it` configuration, as follows:
 
 {% highlight scala %}
-lazy val cross = crossProject.in(file(".")).
+lazy val myProject = project.in(file(".")).
+ enablePlugins(ScalaJSPlugin).
+ // add the `it` configuration
+ configs(IntegrationTest).
+ // add `it` tasks
+ settings(Defaults.itSettings: _*).
+ // add Scala.js-specific settings and tasks to the `it` configuration
+ settings(inConfig(IntegrationTest)(ScalaJSPlugin.testConfigSettings): _*).
  ...
- // adding the `it` configuration
+{% endhighlight %}
+
+For a `crossProject`, you also need to setup the `shared/src/it/scala` source directory.
+The complete setup is as follows:
+
+{% highlight scala %}
+lazy val cross = crossProject.in(file(".")).
+ // add the `it` configuration
  configs(IntegrationTest).
- // adding `it` tasks
- settings(Defaults.itSettings:_*).
- // add `shared` folder to `jvm` source directories
- jvmSettings(unmanagedSourceDirectories in IntegrationTest ++=
-  CrossType.Full.sharedSrcDir(baseDirectory.value, "it").toSeq).
- // add `shared` folder to `js` source directories
- jsSettings(unmanagedSourceDirectories in IntegrationTest ++=
- CrossType.Full.sharedSrcDir(baseDirectory.value, "it").toSeq).
- // adding ScalaJSClassLoader to `js` configuration
- jsSettings(inConfig(IntegrationTest)(ScalaJSPluginInternal.scalaJSTestSettings):_*) 
+ // add `it` tasks
+ settings(Defaults.itSettings: _*).
+ // add Scala.js-specific settings and tasks to the `it` configuration
+ jsSettings(inConfig(IntegrationTest)(ScalaJSPlugin.testConfigSettings): _*).
+ // add the `shared` folder to source directories
+ settings(
+  unmanagedSourceDirectories in IntegrationTest ++=
+  CrossType.Full.sharedSrcDir(baseDirectory.value, "it").toSeq
+ ).
+ ...
 {% endhighlight %}
 
 Now you can put tests in `{shared|jvm|js}/src/it/scala` and they will run when you call `sbt> it:test`. Similarly to

tutorial/basic/index.md

@@ -44,10 +44,10 @@ scalaVersion := "2.12.2" // or any other Scala version >= 2.10.2
 scalaJSUseMainModuleInitializer := true
 {% endhighlight %}
 
-Last, we need a `project/build.properties` to specify the sbt version (>= 0.13.13):
+Last, we need a `project/build.properties` to specify the sbt version (>= 0.13.16):
 
 {% highlight scala %}
-sbt.version=0.13.15
+sbt.version=0.13.16
 {% endhighlight %}
 
 That is all we need to configure the build.
@@ -379,7 +379,7 @@ What basically happens here is that jQuery (which is automatically included beca
 To make the DOM available, add the following to your `build.sbt`:
 
 {% highlight scala %}
-jsDependencies += RuntimeDOM
+jsEnv := new org.scalajs.jsenv.jsdomnodejs.JSDOMNodeJSEnv()
 {% endhighlight %}
 
 This will use the [`jsdom`](https://github.com/tmpvar/jsdom) library to simulate a DOM in Node.js.
@@ -393,9 +393,6 @@ After reloading, you can invoke `run` successfully:
  [info] Running tutorial.webapp.TutorialApp
  [success] (...)
 
-Just like other library dependencies, `jsDependencies += RuntimeDOM` applies transitively: if you depend on a library that depends on the
-DOM, then you depend on the DOM as well.
-
 Alternatively to Node.js with jsdom, you can use [PhantomJS](http://phantomjs.org/) or even [Selenium](http://docs.seleniumhq.org/).
 You can find more information about this in the [documentation about JavaScript environments]({{ BASE_PATH }}/doc/project/js-environments.html).