From 1a6489953f3ea6dd9959cc7186624c8f23c37c76 Mon Sep 17 00:00:00 2001 From: Tobias Schlatter Date: Wed, 9 Dec 2020 09:43:03 +0100 Subject: [PATCH 1/3] Remove documentation for 0.6.x 0.6.x has been EOL for ~half a year now. --- doc/interoperability/export-to-javascript.md | 107 ------------------ doc/interoperability/facade-types.md | 18 +-- doc/interoperability/global-scope.md | 4 +- .../sjs-defined-js-classes.md | 18 +-- doc/project/building.md | 30 ----- doc/project/cross-build.md | 3 - doc/project/dependencies.md | 91 --------------- doc/project/js-environments.md | 37 +----- doc/project/module.md | 4 - doc/semantics.md | 9 -- libraries/facades.md | 5 +- libraries/libs.md | 3 - libraries/testing.md | 9 -- 13 files changed, 7 insertions(+), 331 deletions(-) diff --git a/doc/interoperability/export-to-javascript.md b/doc/interoperability/export-to-javascript.md index 6383d32d..df6dd7ed 100644 --- a/doc/interoperability/export-to-javascript.md +++ b/doc/interoperability/export-to-javascript.md @@ -55,26 +55,6 @@ object HelloWorld { exports the `HelloWorld` object in JavaScript. -**Pre 0.6.15 note**: Before Scala.js 0.6.15, objects were exported as 0-argument -functions using `@JSExport`, rather than directly with `@JSExportTopLevel`. This -is deprecated in 0.6.x, and not supported anymore in Scala.js 1.x. - -### Exporting under a namespace (deprecated) - -**Note:** Deprecated since Scala.js 0.6.26, and not supported anymore in Scala.js 1.x. - -The export name can contain dots, in which case the exported object is namespaced in JavaScript. -For example, - -{% highlight scala %} -@JSExportTopLevel("myapp.foo.MainObject") -object HelloWorld { - ... -} -{% endhighlight %} - -will be accessible in JavaScript using `myapp.foo.MainObject`. - ## Exporting classes The `@JSExportTopLevel` annotation can also be used to export Scala.js classes @@ -99,10 +79,6 @@ will log the string `"Foo(3)"` to the console. This particular example works because it calls `toString()`, which is always exported to JavaScript. Other methods must be exported explicitly as shown in the next section. -**Pre 0.6.15 note**: Before Scala.js 0.6.15, classes were exported using -`@JSExport` instead of `@JSExportTopLevel`, with the same meaning. This is -deprecated in 0.6.x, and not supported anymore in Scala.js 1.x. - ## Exports with modules When [emitting a module for Scala.js code](../project/module.html), top-level exports are not sent to the JavaScript global scope. @@ -202,49 +178,6 @@ gives: Hint to recognize this error: the methods are named `$js$exported$meth$` followed by the JavaScript export name. -### Exporting for call with named parameters (deprecated) - -**Note:** Since Scala.js 0.6.11, `@JSExportNamed` is deprecated, and is not supported anymore in Scala.js 1.x. -Refer to [the Scaladoc]({{ site.production_url }}/api/scalajs-library/0.6.18/#scala.scalajs.js.annotation.JSExportNamed) for migration tips. - -It is customary in Scala to call methods with named parameters if this eases understanding of the code or if many arguments with default values are present: - -{% highlight scala %} -def foo(x: Int = 1, y: Int = 2, z: Int = 3) = ??? - -foo(y = 3, x = 2) -{% endhighlight %} - -A rough equivalent in JavaScript is to pass an object with the respective properties: -{% highlight javascript %} -foo({ - y: 3, - x: 2 -}); -{% endhighlight %} - -The `@JSExportNamed` annotation allows to export Scala methods for use in JavaScript with named parameters: - -{% highlight scala %} -class A { - @JSExportNamed - def foo(x: Int, y: Int = 2, z: Int = 3) = ??? -} -{% endhighlight %} - -Note that default parameters are not required. `foo` can then be called like this: -{% highlight javascript %} -var a = // ... -a.foo({ - y: 3, - x: 2 -}); -{% endhighlight %} - -Not specifying `x` in this case will fail at runtime (since it does not have a default value). - -Just like `@JSExport`, `@JSExportNamed` takes the name of the exported method as an optional argument. - ## Exporting top-level methods While an `@JSExport`ed method inside an `@JSExportTopLevel` object allows JavaScript code to call a "static" method, @@ -401,43 +334,3 @@ class B(val a: Int) extends A { def sum(x: Int, y: Int): Int = x + y } {% endhighlight %} - -## Deprecated: Automatically exporting descendent objects or classes - -**Pre 0.6.15 note**: Before Scala.js 0.6.15, this deprecated feature used to be -often used to "reflectively" instantiate classes and load objects. This use case -has been replaced by the -[`scala.scalajs.reflect.Reflect`]({{ site.production_url }}/api/scalajs-library/latest/#scala.scalajs.reflect.Reflect$) -API. -This feature is not supported anymore in Scala.js 1.x. - -When applied to a class or trait, `@JSExportDescendentObjects` causes all -objects extending it to be automatically exported as 0-arg functions, under -their fully qualified name. For example: - -{% highlight scala %} -package foo.test - -@JSExportDescendentObjects -trait Test { - @JSExport - def test(param: String): Unit -} - -// automatically exported as foo.test.Test1 -object Test1 extends Test { - // exported through inheritance - def test(param: String): Unit = { - println(param) - } -} -{% endhighlight %} - -can be used from JavaScript as: - -{% highlight javascript %} -foo.test.Test1().test("hello"); // note the () in Test1() -{% endhighlight %} - -Similarly, `@JSExportDescendentClasses` causes all non-abstract classes -the annotated class or trait to be exported under their fully qualified name. diff --git a/doc/interoperability/facade-types.md b/doc/interoperability/facade-types.md index eef97c7e..5c5920d4 100644 --- a/doc/interoperability/facade-types.md +++ b/doc/interoperability/facade-types.md @@ -25,12 +25,7 @@ There are also non-native JS traits (aka Scala.js-defined JS traits), documented The latter have more restrictions, but can be *implemented* from Scala.js code. Native JS traits as described here should only be used for interfaces that are exclusively implemented by the JavaScript library--not for interfaces/contracts meant to be implemented by the user of said library. -**Scala.js 0.6.x:** In Scala.js 0.6.x, unless using the `-P:scalajs:sjsDefinedByDefault` compiler option, the annotation `@js.native` is assumed by default, with a deprecation warning. -You might still find old code that does not yet use it to annotate native JS types. - In native JS types, all concrete definitions must have `= js.native` as body. -Any other body will be handled as if it were `= js.native`, and a warning will be emitted. -(In Scala.js 1.x, this is an error.) Here is an example giving types to a small portion of the API of `Window` objects in browsers. @@ -179,10 +174,6 @@ class RegExp(pattern: String) extends js.Object { } {% endhighlight %} -**Pre 0.6.15 note**: Before Scala.js 0.6.15, the `@JSGlobal` annotation did not -exist, so you will find old code that does not yet use it to annotate native JS -classes. - The call `new RegExp("[ab]*")` will map to the obvious in JavaScript, i.e., `new RegExp("[ab]*")`, meaning that the identifier `RegExp` will be looked up in the global scope. @@ -288,10 +279,7 @@ object DOMGlobalScope extends js.Object { } {% endhighlight %} -Prior to 0.6.13, `extends js.GlobalScope` was used instead of `@JSGlobalScope`. -`js.GlobalScope` is now deprecated. - -**Scala.js 1.x:** Also read [access to the JavaScript global scope](./global-scope.html). +Also read [access to the JavaScript global scope](./global-scope.html). ## Imports from other JavaScript modules @@ -577,9 +565,7 @@ reflective call can therefore not be generated. Sometimes, it is more convenient to manipulate JavaScript values in a dynamically typed way. Although it is not recommended to do so for APIs that are used repetitively, Scala.js lets you call JavaScript in a dynamically typed fashion if you want to. -The basic entry point is to grab a dynamically typed reference to the global scope, with `js.Dynamic.global`, which is of type `js.Dynamic`. - -**Scala.js 1.x:** In Scala.js 1.x, `js.Dynamic.global` is a [global scope object](./global-scope.html) instead of an actual value of type `js.Dynamic`. +The basic entry point is to grab a dynamically typed reference to the [global scope](./global-scope.html), with `js.Dynamic.global`, which is of type `js.Dynamic`. You can read and write any field of a `js.Dynamic`, as well as call any method with any number of arguments. All input types are assumed to be of type diff --git a/doc/interoperability/global-scope.md b/doc/interoperability/global-scope.md index 83eacb6c..6123408b 100644 --- a/doc/interoperability/global-scope.md +++ b/doc/interoperability/global-scope.md @@ -3,8 +3,6 @@ layout: doc title: Access to the JavaScript global scope in Scala.js --- -**This page applies to Scala.js 1.x only.** - Unlike Scala, JavaScript has a *global scope*, where global variables are defined. For example, one can define a variable `foo` at the top-level of a script: @@ -212,7 +210,7 @@ if (!js.isUndefined(js.Dynamic.global.Promise)) { } {% endhighlight %} -In Scala.js 1.x, accessing `js.Dynamic.global.Promise` will throw a `ReferenceError` if `Promise` is not defined, so this does not work anymore. +In modern Scala.js, accessing `js.Dynamic.global.Promise` will throw a `ReferenceError` if `Promise` is not defined, so this does not work anymore. Instead, you must use `js.typeOf`: {% highlight scala %} diff --git a/doc/interoperability/sjs-defined-js-classes.md b/doc/interoperability/sjs-defined-js-classes.md index 43438528..a39e9760 100644 --- a/doc/interoperability/sjs-defined-js-classes.md +++ b/doc/interoperability/sjs-defined-js-classes.md @@ -6,20 +6,6 @@ title: Non-native JS types (aka Scala.js-defined JS types) A non-native JS type, aka Scala.js-defined JS type, is a JavaScript type implemented in Scala.js code. This is in contrast to native JS types, described in [the facade types reference](./facade-types.html), which represent APIs implemented in JavaScript code. -## About `@ScalaJSDefined` - -In Scala.js 0.6.x, the `@ScalaJSDefined` is necessary to declare a non-native JS type, also called a Scala.js-defined JS type. -Starting from Scala.js 1.x however, the annotation is not necessary anymore. -Since Scala.js 0.6.17, you can opt-in for the new semantics of 1.x where `@ScalaJSDefined` is not necessary, by giving the option `-P:scalajs:sjsDefinedByDefault` to scalac. -In an sbt build, this is done with - -{% highlight scala %} -scalacOptions += "-P:scalajs:sjsDefinedByDefault" -{% endhighlight %} - -The present documentation assumes that you are using this option (or Scala.js 1.x). -Code snippets mention the necessary `@ScalaJSDefined` in comments as a reference for older versions. - ## Defining a non-native JS type Any class, trait or object that inherits from `js.Any` is a JS type. @@ -36,7 +22,7 @@ class Foo extends js.Object { } {% endhighlight %} -Such classes are called *non-native JS classes*, and are also known as Scala.js-defined JS classes (especially in 0.6.x). +Such classes are called *non-native JS classes*, and were previously known as Scala.js-defined JS classes. All their members are automatically visible from JavaScript code. The class itself (its constructor function) is not visible by default, but can be exported with `@JSExportTopLevel`. Moreover, they can extend JavaScript classes (native or not), and, if exported, be extended by JavaScript classes. @@ -324,8 +310,6 @@ val pos = new Position { } {% endhighlight %} -Note that anonymous classes extending `js.Any` are always non-native, even in 0.6.x without `-P:scalajs:sjsDefinedByDefault` nor `@ScalaJSDefined`. - #### Use case: configuration objects For configuration objects that have fields with default values, concrete members with `= js.undefined` can be used in the trait. diff --git a/doc/project/building.md b/doc/project/building.md index 108d8664..9300c50a 100644 --- a/doc/project/building.md +++ b/doc/project/building.md @@ -37,11 +37,6 @@ Just like in a JVM project, sbt will automatically detect the object with a `mai 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()`. 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.20/#scala.scalajs.js.JSApp). -Since 0.6.18, any object with a standard `main` method will be recognized. -`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. - ## Produce JavaScript code To produce JavaScript code from your Scala code, you need to call the linker: @@ -66,19 +61,9 @@ You can run a Scala.js application (that has `scalaJSUseMainModuleInitializer` s This will run the `main.js` file right inside of your sbt console. By default, the file is run with [Node.js](https://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/jsdom/jsdom) with `npm install jsdom`. -`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. -### Deprecated: Run without `scalaJSUseMainModuleInitializer` - -**Scala.js 0.6.x only** - -It is still possible to `run` a Scala.js application that does not have `scalaJSUseMainModuleInitializer := true`. -However, this is not recommended anymore. - ## Disabling the optimizations If, for some reason (for example, to make stepping through the code with a debugger more predictable), you want to disable the optimizations, you can do so with the following sbt setting: @@ -106,18 +91,3 @@ You can run your code and tests in fullOpt stage with the following command: **Note for Scala.js 1.2.x and earlier:** in Scala.js 1.2.x and earlier, we used `fullOptJS` instead of `fullLinkJS`, which always produces a single file with the suffix `-opt.js`. `scalaJSStage` works the same way in Scala.js 1.2.x and in later versions. - -## Deprecated: Writing Launcher Code - -**Scala.js 0.6.x only** - -For applications that do not use `scalaJSUseMainModuleInitializer := true`, it is possible to generate a small .js file that calls the `main` method, known as a "launcher" file. -This is done with the following sbt setting: - -{% highlight scala %} -persistLauncher := true -{% endhighlight %} - -The resulting file in the target folder will have the suffix `-launcher.js`. - -This feature is deprecated: applications should migrate to using `scalaJSUseMainModuleInitializer`. diff --git a/doc/project/cross-build.md b/doc/project/cross-build.md index dbac42cb..e518b66c 100644 --- a/doc/project/cross-build.md +++ b/doc/project/cross-build.md @@ -38,9 +38,6 @@ addSbtPlugin("org.portable-scala" % "sbt-scalajs-crossproject" % "1.0.0") You can then use the `crossProject` builder in your `build.sbt` file: {% highlight scala %} -// If using Scala.js 0.6.x, also add the following import: -//import sbtcrossproject.CrossPlugin.autoImport.{crossProject, CrossType} - ThisBuild / scalaVersion := "2.13.1" lazy val root = project.in(file(".")). diff --git a/doc/project/dependencies.md b/doc/project/dependencies.md index 07ff838b..2a8791b4 100644 --- a/doc/project/dependencies.md +++ b/doc/project/dependencies.md @@ -20,94 +20,3 @@ Note the `%%%` (instead of the usual `%%`) which will add the current Scala.js v Some Scala.js core libraries (such as the Scala.js library itself) do not need the `%%%` since their version number *is* the Scala.js version number itself. Note that you can also use `%%%` in a Scala/JVM project, in which case it will be the same as `%%`. This allows you to use the same `libraryDependencies` settings when cross compiling Scala/JVM and Scala.js. - -## Deprecated: Depending on JavaScript libraries - -The `jsDependencies` mechanism should be considered deprecated. -Use [scalajs-bundler](https://scalacenter.github.io/scalajs-bundler/) instead. - -**Scala.js 1.x note:** since Scala.js 1.x, this functionality is not part of the core Scala.js sbt plugin. -Instead, it is provided by [sbt-jsdependencies](https://github.com/scala-js/jsdependencies). - -The rest of this section applies to Scala.js 0.6.x only. -[Scala.js 0.6.x has reached End of Life.]({{ BASE_PATH }}/doc/internals/scalajs-0.6.x-eol.html) - -Thanks to [WebJars](http://www.webjars.org/), you can easily fetch a JavaScript library like so: - -{% highlight scala %} -libraryDependencies += "org.webjars" % "jquery" % "2.1.4" -{% endhighlight %} - -This will fetch the required JAR containing jQuery. However, it will not include it once you run your JavaScript code, since there is no class-loading process for JavaScript. - -The Scala.js sbt plugin has `jsDependencies` for this purpose. You can write: - -{% highlight scala %} -jsDependencies += "org.webjars" % "jquery" % "2.1.4" / "2.1.4/jquery.js" -{% endhighlight %} - -This will make your project depend on the respective WebJar and include a file named `**/2.1.4/jquery.js` in the said WebJar when your project is run or tested. We are trying to make the semantics of "include" to be as close as possible to writing: - -{% highlight html %} - -{% endhighlight %} - -All `jsDependencies` and associated metadata (e.g. for ordering) are persisted in a file (called `JS_DEPENDENCIES`) and shipped with the artifact your project publishes. For example, if you depend on the `scalajs-jquery` package for Scala.js, you do not need to explicitly depend or include `jquery.js`; this mechanism does it for you. - -Note: This will **not** dump the JavaScript libraries in the file containing your compiled Scala.js code as this would not work across all JavaScript virtual machines. However, the Scala.js plugin can generate a separate file that contains all raw JavaScript dependencies (see [below](#packageJSDependencies)). - -### Scoping to a Configuration - -You may scope `jsDependencies` on a given configuration, just like for normal `libraryDependencies`: - -{% highlight scala %} -jsDependencies += "org.webjars" % "jquery" % "2.1.4" / "jquery.js" % "test" -{% endhighlight %} - -### CommonJS name - -Some (most?) JavaScript libraries try to adapt the best they can to the environment in which they are being executed. -When they do so, you have to specify explicitly the name under which they are exported in a CommonJS environment (such as Node.js), otherwise they won't work when executed in Node.js. -This is the purpose of the `commonJSName` directive, to be used like this: - -{% highlight scala %} -jsDependencies += "org.webjars" % "mustachejs" % "0.8.2" / "mustache.js" commonJSName "Mustache" -{% endhighlight %} - -which essentially translates to a prelude - -{% highlight javascript %} -var Mustache = require("mustache.js"); -{% endhighlight %} - -when running with Node.js from sbt (with `run`, `test`, etc.). - -### Dependency Ordering - -Since JavaScript does not have a class loading mechanism, the order in which libraries are loaded may matter. If this is the case, you can specify a library's dependencies like so: - -{% highlight scala %} -jsDependencies += "org.webjars" % "jasmine" % "1.3.1" / "jasmine-html.js" dependsOn "jasmine.js" -{% endhighlight %} - -Note that the dependee must be declared as explicit dependency elsewhere, but not necessarily in this project (for example in a project the current project depends on). - -### Local JavaScript Files - -If you need to include JavaScript files which are provided in the resources of your project, use: - -{% highlight scala %} -jsDependencies += ProvidedJS / "myJSLibrary.js" -{% endhighlight %} - -This will look for `myJSLibrary.js` in the resources and include it. It is an error if it doesn't exist. You may use ordering and scoping if you need. - -### Write a Dependency File - -If you want all JavaScript dependencies to be concatenated to a single file (for easy inclusion into a HTML file for example), you can set: - -{% highlight scala %} -skip in packageJSDependencies := false -{% endhighlight %} - -in your project settings. The resulting file in the target folder will have the suffix `-jsdeps.js`. diff --git a/doc/project/js-environments.md b/doc/project/js-environments.md index 934db82c..51d9b288 100644 --- a/doc/project/js-environments.md +++ b/doc/project/js-environments.md @@ -6,8 +6,6 @@ title: JavaScript Environments In order to decide how to run JavaScript code, the Scala.js sbt plugin uses the setting key `jsEnv`. By default, `jsEnv` is set to use [Node.js](http://nodejs.org/), which you need to install separately. -**Scala.js 0.6.x:** If your application or one of its libraries requires a DOM (which can be specified with `jsDependencies += RuntimeDOM`), the `JSDOMNodeJSEnv` environment described will be used by default. - ## Node.js Node.js is the default environment used by Scala.js. @@ -39,15 +37,12 @@ jsEnv := new org.scalajs.jsenv.jsdomnodejs.JSDOMNodeJSEnv() You will need to `npm install jsdom` for the above environment to work. -**Scala.js 1.x:** The above setting requires the following line in your `project/plugins.sbt`: +The above setting requires the following line in your `project/plugins.sbt`: {% highlight scala %} libraryDependencies += "org.scala-js" %% "scalajs-env-jsdom-nodejs" % "1.0.0" {% 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 [PhantomJS](http://phantomjs.org/) is a Webkit-based headless browser. @@ -57,30 +52,12 @@ You can use it with Scala.js with the following sbt setting: jsEnv := PhantomJSEnv().value {% endhighlight %} -**Scala.js 1.x:** The above setting requires the following line in your `project/plugins.sbt`: +The above setting requires the following line in your `project/plugins.sbt`: {% highlight scala %} addSbtPlugin("org.scala-js" % "sbt-scalajs-env-phantomjs" % "1.0.0") {% endhighlight %} -### Disabling auto-termination of PhantomJS - -**Scala.js 0.6.x only** - -By default, the PhantomJS interpreter terminates itself as soon as the `main()` method returns. -This may not be what you want, if for example you register time-outs or use WebSockets. -You can disable this behavior with the following setting: - -{% highlight scala %} -jsEnv := PhantomJSEnv(autoExit = false).value -{% endhighlight %} - -You can terminate the interpreter from your Scala code with - -{% highlight scala %} -System.exit(0) -{% endhighlight %} - ### Passing arguments to PhantomJS You can pass command-line arguments to the PhantomJS interpreter like this: @@ -96,13 +73,3 @@ For more options of the PhantomJS environment, see [Selenium](http://docs.seleniumhq.org/) provides a programmatic interface to real browsers. See the separate project [scalajs-env-selenium](https://github.com/scala-js/scala-js-env-selenium) for instructions on how to use with Scala.js. - -## Rhino (deprecated) - -**Scala.js 0.6.x only** - -Rhino can be used with the following sbt setting: - -{% highlight scala %} -scalaJSUseRhino in Global := true -{% endhighlight %} diff --git a/doc/project/module.md b/doc/project/module.md index b5d448cd..9e62622d 100644 --- a/doc/project/module.md +++ b/doc/project/module.md @@ -17,9 +17,6 @@ scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.ESModule) } scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.CommonJSModule) } {% endhighlight %} -**Important:** Using this setting is incompatible with the (deprecated) setting `persistLauncher := true`. -It is also basically incompatible with `jsDependencies`; use [scalajs-bundler](https://scalacenter.github.io/scalajs-bundler/) instead. - When emitting a module, `@JSExportTopLevel`s are really *exported* from the Scala.js module. Moreover, you can use top-level `@JSImport` to [import native JavaScript stuff](../interoperability/facade-types.html#import) from other JavaScript module. @@ -33,7 +30,6 @@ import scala.scalajs.js.annotation._ @JSImport("bar.js", "Foo") class JSFoo(val x: Int) extends js.Object -// @ScalaJSDefined // required for Scala.js 0.6.x, unless using -P:scalajs:sjsDefinedByDefault @JSExportTopLevel("Babar") class Foobaz(x: String) extends js.Object { val inner = new JSFoo(x.length) diff --git a/doc/semantics.md b/doc/semantics.md index 4e575cdc..e48ccb5f 100644 --- a/doc/semantics.md +++ b/doc/semantics.md @@ -112,10 +112,6 @@ conditions, checking them is typically too expensive. Therefore, all of these are considered [undefined behavior](http://en.wikipedia.org/wiki/Undefined_behavior). -**Scala.js 0.6.x only:** -In Scala.js 0.6.x, `ArithmeticException`s, such as integer division by 0, are also considered undefined behavior. -This is not the case in Scala.js 1.x anymore, where they are reliably thrown. - Some of these, however, can be configured to be compliant with the JVM specification using sbt settings. Currently, only `ClassCastException`s (thrown by invalid `asInstanceOf` calls) and `ArrayIndexOutOfBoundsException`s (thrown by array indexing) @@ -147,13 +143,8 @@ JVM semantics, you can do so with an sbt setting. For example, this setting enables compliant `asInstanceOf`s: {% highlight scala %} -// Scala.js 1.x scalaJSLinkerConfig ~= { _.withSemantics(_.withAsInstanceOfs( org.scalajs.linker.interface.CheckedBehavior.Compliant)) } - -// Scala.js 0.6.x -scalaJSLinkerConfig ~= { _.withSemantics(_.withAsInstanceOfs( - org.scalajs.core.tools.sem.CheckedBehavior.Compliant)) } {% endhighlight %} Note that this will have (potentially major) performance impacts. diff --git a/libraries/facades.md b/libraries/facades.md index 89dcbe47..6c121331 100644 --- a/libraries/facades.md +++ b/libraries/facades.md @@ -8,10 +8,7 @@ title: JavaScript library facades These facades wrap existing JavaScript libraries, giving you type safe access to their functionality. Some of the facades may only partially expose the underlying JavaScript library functionality, so make sure to check out the details. To quickly start using one of these libraries, just click on the dependency clipboard button to get the -relevant SBT dependency definition. - -**Scala.js 1.x:** At the moment, the list below is maintained for Scala.js 0.6.x only. -Consult the readmes of relevant projects to see whether they support milestones of Scala.js 1.x. +relevant sbt dependency definition. {% include library.html lib=site.data.library.jsfacades %} diff --git a/libraries/libs.md b/libraries/libs.md index 5496d3fb..8e2f6e6d 100644 --- a/libraries/libs.md +++ b/libraries/libs.md @@ -8,9 +8,6 @@ title: Scala libraries Many Scala libraries have been updated to be compatible with Scala.js. To quickly start using one of these libraries, just click on the dependency clipboard button to get the relevant SBT dependency definition. -**Scala.js 1.x:** At the moment, the list below is maintained for Scala.js 0.6.x only. -Consult the readmes of relevant projects to see whether they support milestones of Scala.js 1.x. - {% include library.html lib=site.data.library.scalalibs %} ------- diff --git a/libraries/testing.md b/libraries/testing.md index 07c39816..bb8ee9ba 100644 --- a/libraries/testing.md +++ b/libraries/testing.md @@ -8,13 +8,4 @@ title: Testing Several Scala testing frameworks have been updated to be compatible with Scala.js. To quickly start using one of these libraries, just click on the dependency clipboard button to get the relevant SBT dependency definition. -**Scala.js 1.x:** At the moment, the list below is maintained for Scala.js 0.6.x only. -Consult the readmes of relevant projects to see whether they support milestones of Scala.js 1.x. - {% include library.html lib=site.data.library.testlibs %} - - - - - - From d59cacbf36c2a85b01864f57b145f7d002f74c27 Mon Sep 17 00:00:00 2001 From: Tobias Schlatter Date: Tue, 8 Dec 2020 09:44:09 +0100 Subject: [PATCH 2/3] Remove tutorial for 0.6.x --- doc/tutorial/basic/0.6.x.md | 552 ------------------------------------ doc/tutorial/basic/index.md | 2 - 2 files changed, 554 deletions(-) delete mode 100644 doc/tutorial/basic/0.6.x.md diff --git a/doc/tutorial/basic/0.6.x.md b/doc/tutorial/basic/0.6.x.md deleted file mode 100644 index a2f5440d..00000000 --- a/doc/tutorial/basic/0.6.x.md +++ /dev/null @@ -1,552 +0,0 @@ ---- -layout: doc -title: Basic tutorial (Scala.js 0.6.x) ---- - -**This page applies only to Scala.js 0.6.x. [Go the newer tutorial for Scala.js 1.x](./).** - -[Scala.js 0.6.x has reached End of Life.]({{ BASE_PATH }}/doc/internals/scalajs-0.6.x-eol.html) - -This is a step-by-step tutorial where we start with the setup of a Scala.js sbt project and end up having some user interaction and unit testing. The code created in this tutorial is available with one commit per step in the [scalajs-tutorial](https://github.com/scala-js/scalajs-tutorial/tree/0.6.x) repository on GitHub. - -## Step 0: Prerequisites - -To go through this tutorial, you will need to [download & install sbt](https://www.scala-sbt.org/1.x/docs/Setup.html). Note that no prior sbt knowledge (only a working installation) is required to follow the tutorial. - -You will also need to [download & install Node.js](https://nodejs.org/en/download/). - -To run the complete tutorial application, you will also need to install jsdom as explained [below](#supporting-the-dom). - -## Step 1: Setup - -First create a new folder where your sbt project will go. - -### sbt Setup - -To setup Scala.js in a new sbt project, we need to do two things: - -1. Add the Scala.js sbt plugin to the build -2. Enable the plugin in the project - -Adding the Scala.js sbt plugin is a one-liner in `project/plugins.sbt` (all file names we write in this tutorial are relative to the project root): - -{% highlight scala %} -addSbtPlugin("org.scala-js" % "sbt-scalajs" % "{{ site.versions.scalaJS06x }}") -{% endhighlight %} - -We also setup basic project settings and enable this plugin in the sbt build file (`build.sbt`, in the project root directory): - -{% highlight scala %} -enablePlugins(ScalaJSPlugin) - -name := "Scala.js Tutorial" -scalaVersion := "2.13.1" // or any other Scala version >= 2.10.2 - -// This is an application with a main method -scalaJSUseMainModuleInitializer := true -{% endhighlight %} - -Last, we need a `project/build.properties` to specify the sbt version (you can find the latest version [here](https://www.scala-sbt.org/download.html)): - -{% highlight scala %} -sbt.version=1.3.7 -{% endhighlight %} - -That is all we need to configure the build. - -If at this point you prefer to use an IDE, you can import the build into [VS Code with Metals](https://scalameta.org/metals/) (or any other editor supported by Metals) or IntelliJ IDEA (see "Installation" [here](https://docs.scala-lang.org/getting-started/intellij-track/getting-started-with-scala-in-intellij.html)). -Note that for compiling and running your application, you will still need to use sbt from the command line. - -### HelloWorld application - -For starters, we add a very simple `TutorialApp` in the `tutorial.webapp` package. Create the file `src/main/scala/tutorial/webapp/TutorialApp.scala`: - -{% highlight scala %} -package tutorial.webapp - -object TutorialApp { - def main(args: Array[String]): Unit = { - println("Hello world!") - } -} -{% endhighlight %} - -As you expect, this will simply print "HelloWorld" when run. To run this, simply launch `sbt` and invoke the `run` task: - - $ sbt - sbt:Scala.js Tutorial> run - [info] Compiling 1 Scala source to (...)/scalajs-tutorial/target/scala-2.13/classes ... - [info] Fast optimizing (...)/scalajs-tutorial/target/scala-2.13/scala-js-tutorial-fastopt.js - [info] Running tutorial.webapp.TutorialApp - Hello world! - [success] (...) - -Congratulations! You have successfully compiled and run your first Scala.js application. -The code is actually run by a JavaScript interpreter, namely Node. - -**Source maps in Node.js**: To get your stack traces resolved on Node.js, you will have to install the `source-map-support` package. - - $ npm install source-map-support - -## Step 2: Integrating with HTML - -Now that we have a simple JavaScript application, we would like to use it in an HTML page. To do this, we need two steps: - -1. Generate a single JavaScript file out of our compiled code -2. Create an HTML page which includes that file - -### Generate JavaScript - -To generate a single JavaScript file using sbt, just use the `fastOptJS` task: - - > fastOptJS - [info] Fast optimizing (...)/scalajs-tutorial/target/scala-2.13/scala-js-tutorial-fastopt.js - [success] (...) - -This will perform some fast optimizations and generate the `target/scala-2.13/scala-js-tutorial-fastopt.js` file containing the JavaScript code. - -(It is possible that the `[info]` does not appear, if you have just run the program and not made any change to it.) - -### Create the HTML Page - -To load and launch the created JavaScript, you will need an HTML file. Create the file `scalajs-tutorial-fastopt.html` (or whatever name you prefer, for example `index-dev.html`) in the project root with the following content. We will go in the details right after. - -{% highlight html %} - - - - - The Scala.js Tutorial - - - - - - -{% endhighlight %} - -The script tag simply includes the generated code (attention, you might need to adapt the Scala version from `2.13` to `2.12` (or even `2.10` or `2.11`) here if you are using an older version of Scala). - -Since we have set `scalaJSUseMainModuleInitializer := true` in the build, the `TutorialApp.main(args: Array[String])` method is automatically called at the end of the `-fastopt.js` file (with an empty array as argument). - -If you now open the newly created HTML page in your favorite browser, you will see ... nothing. The `println` in the `main` method goes right to the JavaScript console, which is not shown by default in a browser. However, if you open the JavaScript console (e.g. in Chrome: right click -> Inspect Element -> Console) you can see the HelloWorld message. - -## Step 3: Using the DOM - -As the last step has shown, running JavaScript inside an HTML page is not particularly useful if you cannot interact with the page. -That's what the DOM API is for. - -### Adding the DOM Library - -To use the DOM, it is best to use the statically typed Scala.js DOM library. To add it to your sbt project, add the following line to your `build.sbt`: - -{% highlight scala %} -libraryDependencies += "org.scala-js" %%% "scalajs-dom" % "{{ site.versions.scalaJSDOM }}" -{% endhighlight %} - -sbt-savvy folks will notice the `%%%` instead of the usual `%%`. It means we are using a Scala.js library and not a -normal Scala library. Have a look at the [Dependencies](../../project/dependencies.html) guide for details. Don't forget -to reload the build file if sbt is still running: - - sbt:Scala.js Tutorial> reload - [info] Loading settings for project global-plugins from plugins.sbt ... - [info] Loading global plugins from (...)/.sbt/1.0/plugins - [info] Loading settings for project scalajs-tutorial-build from plugins.sbt ... - [info] Loading project definition from (...)/scalajs-tutorial/project - [info] Loading settings for project scala-js-tutorial from build.sbt ... - [info] Set current project to Scala.js Tutorial (in build file:(...)/scalajs-tutorial/) - -If you are using an IDE plugin, you will also have to reimport the build for autocompletion to work. - -### Using the DOM Library - -Now that we added the DOM library, let's adapt our HelloWorld example to add a `

` tag to the body of the page, rather than printing to the console. - -First of all, we import a couple of things: - -{% highlight scala %} -import org.scalajs.dom -import org.scalajs.dom.document -{% endhighlight %} - -`dom` is the root of the JavaScript DOM and corresponds to the global scope of JavaScript (aka the `window` object). -We additionally import `document` (which corresponds to `document` in JavaScript) for convenience. - -We now create a method that allows us to append a `

` tag with a given text to a given node: - -{% highlight scala %} -def appendPar(targetNode: dom.Node, text: String): Unit = { - val parNode = document.createElement("p") - val textNode = document.createTextNode(text) - parNode.appendChild(textNode) - targetNode.appendChild(parNode) -} -{% endhighlight %} - -Replace the call to `println` with a call to `appendPar` in the `main` method: - -{% highlight scala %} -def main(args: Array[String]): Unit = { - appendPar(document.body, "Hello World") -} -{% endhighlight %} - -### Rebuild the JavaScript - -To rebuild the JavaScript, simply invoke `fastOptJS` again: - - sbt:Scala.js Tutorial> fastOptJS - [info] Compiling 1 Scala source to (...)/scalajs-tutorial/target/scala-2.13/classes ... - [info] Fast optimizing (...)/scalajs-tutorial/target/scala-2.13/scala-js-tutorial-fastopt.js - [success] (...) - -As you can see from the log, sbt automatically detects that the sources must be recompiled before fast optimizing. - -You can now reload the HTML in your browser and you should see a nice "Hello World" message. - -Re-typing `fastOptJS` each time you change your source file is cumbersome. Luckily sbt is able to watch your files and recompile as needed: - - sbt:Scala.js Tutorial> ~fastOptJS - [success] (...) - [info] 1. Monitoring source files for scalajs-tutorial/fastOptJS... - [info] Press to interrupt or '?' for more options. - -From this point in the tutorial we assume you have an sbt with this command running, so we don't need to bother with rebuilding each time. - -## Step 4: Reacting on User Input - -This step shows how you can add a button and react to events on it by still just using the DOM (we will use jQuery in the next step). We want to add a button that adds another `

` tag to the body when it is clicked. - -We start by adding a method to `TutorialApp` which will be called when the button is clicked: - -{% highlight scala %} -@JSExportTopLevel("addClickedMessage") -def addClickedMessage(): Unit = { - appendPar(document.body, "You clicked the button!") -} -{% endhighlight %} - -You will notice the `@JSExportTopLevel` annotation. -It tells the Scala.js compiler to make that method callable as top-level function from JavaScript. We must also import this annotation: - -{% highlight scala %} -import scala.scalajs.js.annotation.JSExportTopLevel -{% endhighlight %} - -To find out more about how to call Scala.js methods from JavaScript, have a look at the [Export Scala.js API to -JavaScript](../../interoperability/export-to-javascript.html) guide. - -Since we now have a method that is callable from JavaScript, all we have to do is add a button to our HTML and set its -`onclick` attribute (make sure to add the button *before* the ` -{% endhighlight %} - -This can easily become very cumbersome, if you depend on multiple libraries. The Scala.js sbt plugin provides a -mechanism for libraries to declare the plain JavaScript libraries they depend on and bundle them in a single file. All -you have to do is activate this and then include the file. - -In your `build.sbt`, set: - -{% highlight scala %} -skip in packageJSDependencies := false -jsDependencies += - "org.webjars" % "jquery" % "2.2.1" / "jquery.js" minified "jquery.min.js" -{% endhighlight %} - -After reloading and rerunning `fastOptJS`, this will create `scala-js-tutorial-jsdeps.js` containing all JavaScript -libraries next to the main JavaScript file. We can then simply include this file and don't need to worry about -JavaScript libraries anymore: - -{% highlight html %} - - -{% endhighlight %} - -### Setup UI in Scala.js - -We still want to get rid of the `onclick` attribute of our `""") - .click(() => addClickedMessage()) - .appendTo(jQuery("body")) -{% endhighlight %} - -This brings another unexpected advantage: We don't need to give it an ID anymore but can directly use the jQuery object -to install the on-click handler. - -We now define the `ButtonClick` test just below the `HelloWorld` test: - -{% highlight scala %} -test("ButtonClick") { - def messageCount = - jQuery("p:contains('You clicked the button!')").length - - val button = jQuery("button:contains('Click me!')") - assert(button.length == 1) - assert(messageCount == 0) - - for (c <- 1 to 5) { - button.click() - assert(messageCount == c) - } -} -{% endhighlight %} - -After defining a helper method that counts the number of messages, we retrieve the button from the DOM and verify we -have exactly one button and no messages. In the loop, we simulate a click on the button and then verify that the number -of messages has increased. - -You can now call the `test` task again: - - > test - [info] Compiling 1 Scala source to (...)/scalajs-tutorial/target/scala-2.13/test-classes... - [info] Fast optimizing (...)/scalajs-tutorial/target/scala-2.13/scala-js-tutorial-test-fastopt.js - -------------------------------- Running Tests -------------------------------- - + tutorial.webapp.TutorialTest.HelloWorld 3ms - + tutorial.webapp.TutorialTest.ButtonClick 6ms - Tests: 2, Passed: 2, Failed: 0 - [success] Total time: 15 s, completed 16-mars-2018 20:07:33 - -This completes the testing part of this tutorial. - -## Step 7: Optimizing for Production - -Here we show a couple of things you might want to do when you promote your application to production. - -### Full Optimization - -Size is critical for JavaScript code on the web. To compress the compiled code even further, the Scala.js sbt plugin -uses the advanced optimizations of the [Google Closure Compiler](http://developers.google.com/closure/compiler/). To run -full optimizations, simply use the `fullOptJS` task: - - > fullOptJS - [info] Full optimizing (...)/scalajs-tutorial/target/scala-2.13/scala-js-tutorial-opt.js - [info] Closure: 0 error(s), 0 warning(s) - [success] (...) - -Note that this can take a while on a larger project (tens of seconds), which is why we typically don't use `fullOptJS` -during development, but `fastOptJS` instead. If you want to `run` and `test` the full-optimized version from sbt, -you need to change the *stage* using the following sbt setting: - - > set scalaJSStage in Global := FullOptStage - -(by default, the stage is `FastOptStage`) - -We also need to create our final production HTML file `scalajs-tutorial.html` which includes the fully optimized code: - -{% highlight html %} - - - - - The Scala.js Tutorial - - - - - - - - -{% endhighlight %} - -### Compression - -If you serve your Scala.js application from a web server, you should additionally -gzip the resulting `.js` files. This step might reduce the size of your application down -to 20% of its original size. - -The setup depends on your server stack. A common option is to use -[sbt-web](https://github.com/sbt/sbt-web), -[sbt-web-scalajs](https://github.com/vmunier/sbt-web-scalajs) and -[sbt-gzip](https://github.com/sbt/sbt-gzip) -if you have a Play or Akka-http server. - -This completes the Scala.js tutorial. Refer to our [documentation page](../../index.html) for deeper insights into various -aspects of Scala.js. diff --git a/doc/tutorial/basic/index.md b/doc/tutorial/basic/index.md index d441c755..8c6cf2d6 100644 --- a/doc/tutorial/basic/index.md +++ b/doc/tutorial/basic/index.md @@ -3,8 +3,6 @@ layout: doc title: Basic tutorial --- -**This page applies only to Scala.js 1.x. If you need 0.6.x, [go the older tutorial for Scala.js 0.6.x](./0.6.x.html).** - This is a step-by-step tutorial where we start with the setup of a Scala.js sbt project and end up having some user interaction and unit testing. The code created in this tutorial is available with one commit per step in the [scalajs-tutorial](https://github.com/scala-js/scalajs-tutorial) repository on GitHub. ## Step 0: Prerequisites From fd427bf521423da048283a74d072f1bb77332125 Mon Sep 17 00:00:00 2001 From: Tobias Schlatter Date: Wed, 9 Dec 2020 09:55:45 +0100 Subject: [PATCH 3/3] Reference last version with 0.6.x doc in 0.6.x EOL doc --- doc/internals/scalajs-0.6.x-eol.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/internals/scalajs-0.6.x-eol.md b/doc/internals/scalajs-0.6.x-eol.md index 575a45ca..43756746 100644 --- a/doc/internals/scalajs-0.6.x-eol.md +++ b/doc/internals/scalajs-0.6.x-eol.md @@ -18,3 +18,5 @@ Please upgrade to Scala.js 1.x as soon as possible. See [the release notes of Scala.js 1.0.0]({{ BASE_PATH }}/news/2020/02/25/announcing-scalajs-1.0.0/) for important migration information. There are no plans to offer paid support for Scala.js 0.6.x. + +The last version of this website with 0.6.x documentation is at [9799280](https://github.com/scala-js/scala-js-website/tree/9799280483e3a21bb519e624b7fdb16e6a6af9c9).