diff --git a/.swift-version b/.swift-version index ff4900d30..a14e1af6f 100644 --- a/.swift-version +++ b/.swift-version @@ -1 +1 @@ -wasm-5.3-SNAPSHOT-2020-10-02-a +wasm-5.3-SNAPSHOT-2020-10-20-a diff --git a/README.md b/README.md index 4c02fedfb..8119d8c41 100644 --- a/README.md +++ b/README.md @@ -4,23 +4,7 @@ Swift framework to interact with JavaScript through WebAssembly. -## Requirements - -This library only supports [`swiftwasm/swift`](https://github.com/swiftwasm/swift) distribution toolchain. Please install Swift for WebAssembly toolchain from [Release Page](https://github.com/swiftwasm/swift/releases) - -The toolchains can be installed via [`swiftenv`](https://github.com/kylef/swiftenv) like official nightly toolchain. - -e.g. - -```sh - -$ swiftenv install https://github.com/swiftwasm/swift/releases/download/swift-wasm-5.3-SNAPSHOT-2020-08-10-a/swift-wasm-5.3-SNAPSHOT-2020-08-10-a-osx.tar.gz -$ swift --version -Swift version 5.3-dev (LLVM 09686f232a, Swift 5a196c7f13) -Target: x86_64-apple-darwin19.6.0 -``` - -## Usage +## Getting started This JavaScript code @@ -48,13 +32,11 @@ Can be written in Swift using JavaScriptKit ```swift import JavaScriptKit -let alert = JSObject.global.alert.function! -let document = JSObject.global.document.object! +let document = JSObject.global.document -let divElement = document.createElement!("div").object! +let divElement = document.createElement("div") divElement.innerText = "Hello, world" -let body = document.body.object! -_ = body.appendChild!(divElement) +_ = document.body.appendChild(divElement) struct Owner: Codable { let name: String @@ -68,7 +50,82 @@ struct Pet: Codable { let jsPet = JSObject.global.pet let swiftPet: Pet = try JSValueDecoder().decode(from: jsPet) -alert("Swift is running on browser!") +JSObject.global.alert("Swift is running in the browser!") +``` + +### Usage in a browser application + +The easiest way to get started with JavaScriptKit in your browser app is with [the `carton` +bundler](https://carton.dev). + +As a part of these steps +you'll install `carton` via [Homebrew](https://brew.sh/) on macOS (unfortunately you'll have to build +it manually on Linux). Assuming you already have Homebrew installed, you can create a new app +that uses JavaScriptKit by following these steps: + +1. Install `carton`: + +``` +brew install swiftwasm/tap/carton +``` + +If you had `carton` installed before this, make sure you have version 0.6.1 or greater: + +``` +carton --version ``` -Please see [Example](https://github.com/swiftwasm/JavaScriptKit/tree/main/Example) directory for more information +2. Create a directory for your project and make it current: + +``` +mkdir SwiftWasmApp && cd SwiftWasmApp +``` + +3. Initialize the project from a template with `carton`: + +``` +carton init --template basic +``` + +4. Build the project and start the development server, `carton dev` can be kept running + during development: + +``` +carton dev +``` + +5. Open [http://127.0.0.1:8080/](http://127.0.0.1:8080/) in your browser and a developer console + within it. You'll see `Hello, world!` output in the console. You can edit the app source code in + your favorite editor and save it, `carton` will immediately rebuild the app and reload all + browser tabs that have the app open. + +You can also build your project with webpack.js and a manually installed SwiftWasm toolchain. Please +see the following sections and the [Example](https://github.com/swiftwasm/JavaScriptKit/tree/main/Example) +directory for more information in this more advanced use case. + +### Manual toolchain installation + +This library only supports [`swiftwasm/swift`](https://github.com/swiftwasm/swift) distribution +toolchain. The toolchain can be installed via [`swiftenv`](https://github.com/kylef/swiftenv), in +the same way as the official Swift nightly toolchain. + +You have to install the toolchain manually when working on the source code JavaScriptKit itself, +especially if you change anything in the JavaScript runtime parts. This is because the runtime is +embedded in `carton` and currently can't be replaced dynamically with the JavaScript code you've +updated locally. + +Just pass a toolchain archive URL for [the latest SwiftWasm 5.3 +snapshot](https://github.com/swiftwasm/swift/releases) appropriate for your platform: + +```sh +$ swiftenv install https://github.com/swiftwasm/swift/releases/download/swift-wasm-5.3-SNAPSHOT-2020-10-20-a/swift-wasm-5.3-SNAPSHOT-2020-10-20-a-macos_x86_64.pkg +``` + +You can also use the `install-toolchain.sh` helper script that uses a hardcoded toolchain snapshot: + +```sh +$ ./scripts/install-toolchain.sh +$ swift --version +Swift version 5.3 (swiftlang-5.3.0) +Target: x86_64-apple-darwin19.6.0 +``` diff --git a/scripts/install-toolchain.sh b/scripts/install-toolchain.sh index b6a82df24..068d4ff14 100755 --- a/scripts/install-toolchain.sh +++ b/scripts/install-toolchain.sh @@ -18,13 +18,13 @@ fi case $(uname -s) in Darwin) - toolchain_download="$swift_tag-osx.tar.gz" + toolchain_download="$swift_tag-macos_x86_64.pkg" ;; Linux) if [ $(grep RELEASE /etc/lsb-release) == "DISTRIB_RELEASE=18.04" ]; then - toolchain_download="$swift_tag-ubuntu18.04.tar.gz" + toolchain_download="$swift_tag-ubuntu18.04_x86_64.tar.gz" elif [ $(grep RELEASE /etc/lsb-release) == "DISTRIB_RELEASE=20.04" ]; then - toolchain_download="$swift_tag-ubuntu20.04.tar.gz" + toolchain_download="$swift_tag-ubuntu20.04_x86_64.tar.gz" else echo "Unknown Ubuntu version" exit 1