Update documentation to reflect (anticipated) v0.5.0 #38
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| --- | ||
| layout: page | ||
| title: Scala.js sbt Plugin | ||
| --- | ||
| {% include JB/setup %} | ||
| | ||
| Scala.js comes with an sbt plugin that facilitates compiling, running and testing with Scala.js. For a quick start, have a look at our [bootstrapping skeleton](https://github.com/sjrd/scala-js-example-app). | ||
| | ||
| * [Setup](./sbt/setup.html) | ||
| * [Compiling, Running, Linking, Optimizing](./sbt/run.html) | ||
| * [Depending on Libraries](./sbt/depending.html) | ||
| * [JavaScript Environments](./sbt/js-envs.html) | ||
| * [Cross-Building](./sbt/cross-building.html) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| --- | ||
| layout: page | ||
| title: Cross-Building | ||
| --- | ||
| | ||
| Sometimes it is desirable to compile the same source code with Scala.js and Scala JVM. In order to do this, you need two different projects, one for Scala.js and one for Scala JVM and a folder with the shared source code. You then can tell sbt to use the shared source folder in addition to the normal source locations. | ||
| | ||
| We give a simple example of how such a project, we call it `foo`, could look. You can find this project on [GitHub](https://github.com/scala-js/scalajs-cross-compile-example). | ||
| | ||
| ## Directory Structure | ||
| | ||
| <project root> | ||
| +- foo-jvm | ||
| | +- src/main/scala | ||
| +- foo-js | ||
| | +- src/main/scala | ||
| +- foo-shared | ||
| +- src/main/scala | ||
| | ||
| In `foo-shared/src/main/scala` are the shared source files. In `foo-{js|jvm}/src/main/scala` are the source files specific to the respective platform (these folders are optional). | ||
| | ||
| ## sbt Build File | ||
| | ||
| Starting from sbt 0.13, you can write a multi-project build in a `.sbt` file. This is an example how your `build.sbt` could look like: | ||
| | ||
| name := "Foo root project" | ||
| | ||
| version := "0.1" | ||
| | ||
| lazy val root = project.in(file(".")).aggregate() | ||
| | ||
| lazy val fooJS = project.in(file("foo-js")).settings(scalaJSSettings: _*).settings( | ||
| name := "foo", | ||
| unmanagedSourceDirectories in Compile += root.base / "foo-shared" / "src" / "main" / "scala" | ||
| ) | ||
| | ||
| lazy val fooJVM = project.in(file("foo-jvm")).settings( | ||
| name := "foo", | ||
| unmanagedSourceDirectories in Compile += root.base / "foo-shared" / "src" / "main" / "scala" | ||
| ) | ||
| | ||
| You now have separate projects to compile towards Scala.js and Scala JVM. Note the same name given to both projects, this allows them to be published with corresponding artifact names: | ||
| | ||
| - `foo_2.10-0.1-SNAPSHOT.jar` | ||
| - `foo_sjs0.5.0-RC2_2.10-0.1-SNAPSHOT.jar` | ||
| | ||
| If you do not publish the artifacts, you may choose different names for the projects. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| --- | ||
| layout: page | ||
| title: Depending on Libraries | ||
| --- | ||
| | ||
| ## Depending on Scala.js libraries | ||
| | ||
| To be able to use a Scala library in Scala.js, it has to be separately compiled for Scala.js. You then can add it to your library dependencies as follows: | ||
| | ||
| libraryDependencies += "org.scala-lang.modules.scalajs" %%% "scalajs-dom" % "0.5" | ||
| | ||
| Note the `%%%` (instead of the usual `%%`) which will add the current Scala.js version to the artifact name. This allows to | ||
| | ||
| - Cross-publish libraries to different Scala.js versions | ||
| - Disambiguate Scala.js from Scala JVM libraries | ||
| | ||
| 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. | ||
| | ||
| ## Depending on JavaScript libraries | ||
| | ||
| Thanks to [WebJars](http://www.webjars.org/), you can easily fetch a JavaScript library like so: | ||
| | ||
| libraryDependencies += "org.webjars" % "jquery" % "1.10.2" | ||
| | ||
| 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: | ||
| | ||
| jsDependencies += "org.webjars" % "jquery" % "1.10.2" / "jquery.js" | ||
| | ||
| This will make your project depend on the respective WebJar and include a file named `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: | ||
| | ||
| <script type="text/javascript" src="..."></script> | ||
| | ||
| However, sometimes this doesn't work when running with Node.js. If this happens to you, change to Phantom.js (see below on how to do that). | ||
| | ||
| 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 `jasmine-test-framework` package for Scala.js (a thin wrapper around Jasmine), you do not need to explicitly depend or include `jasmine.js`; this mechanism does it for you. | ||
| | ||
| ### Scoping to a Configuration | ||
| | ||
| You may scope `jsDependencies` on a given configuration, just like for normal `libraryDependencies`: | ||
| | ||
| jsDependencies += "org.webjars" % "jquery" % "1.10.2" / "jquery.js" % "test" | ||
| | ||
| ### 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: | ||
| | ||
| jsDependencies += "org.webjars" % "jasmine" % "1.3.1" / "jasmine-html.js" dependsOn "jasmine.js" | ||
| | ||
| 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: | ||
| | ||
| jsDependencies += ProvidedJS / "myJSLibrary.js" | ||
| | ||
| 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: | ||
| | ||
| skip in packageJSDependencies := false | ||
| | ||
| in your project settings. The resulting file in the target folder will have the suffix `-jsdeps.js`. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit. This suggestion is invalid because no changes were made to the code. Suggestions cannot be applied while the pull request is closed. Suggestions cannot be applied while viewing a subset of changes. Only one suggestion per line can be applied in a batch. Add this suggestion to a batch that can be applied as a single commit. Applying suggestions on deleted lines is not supported. You must change the existing code in this line in order to create a valid suggestion. Outdated suggestions cannot be applied. This suggestion has been applied or marked resolved. Suggestions cannot be applied from pending reviews. Suggestions cannot be applied on multi-line comments. Suggestions cannot be applied while the pull request is queued to merge. Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"In general" -> "Most of the time"? I believe the former means more "always" than "most of the time".