Skip to content

Remove 0.6.x from living documentation #526

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 9, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions doc/internals/scalajs-0.6.x-eol.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
107 changes: 0 additions & 107 deletions doc/interoperability/export-to-javascript.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -202,49 +178,6 @@ gives:
Hint to recognize this error: the methods are named `$js$exported$meth$`
followed by the JavaScript export name.

### <a name="JSExportNamed"></a> 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,
Expand Down Expand Up @@ -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.
18 changes: 2 additions & 16 deletions doc/interoperability/facade-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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).

## <a name="import"></a> Imports from other JavaScript modules

Expand Down Expand Up @@ -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
Expand Down
4 changes: 1 addition & 3 deletions doc/interoperability/global-scope.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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 %}
Expand Down
18 changes: 1 addition & 17 deletions doc/interoperability/sjs-defined-js-classes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
30 changes: 0 additions & 30 deletions doc/project/building.md
Original file line number Diff line number Diff line change
Expand Up @@ -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(<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.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:
Expand All @@ -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:
Expand Down Expand Up @@ -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`.
3 changes: 0 additions & 3 deletions doc/project/cross-build.md
Original file line number Diff line number Diff line change
Expand Up @@ -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(".")).
Expand Down
91 changes: 0 additions & 91 deletions doc/project/dependencies.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 %}
<script type="text/javascript" src="..."></script>
{% 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.

### <a name="packageJSDependencies"></a> 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`.
Loading