From 1c2d09600d1c73a5975d770b9450ed5576d50009 Mon Sep 17 00:00:00 2001 From: Max Desiatov Date: Wed, 7 Oct 2020 22:06:29 +0100 Subject: [PATCH 1/5] Mention the `install-toolchain.sh` script in `README.md` --- README.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 4c02fedfb..3bea12048 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,10 @@ 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. +This library only supports [`swiftwasm/swift`](https://github.com/swiftwasm/swift) distribution toolchain. The toolchains can be installed via [`swiftenv`](https://github.com/kylef/swiftenv) like official nightly toolchain. You can use the `install-toolchain.sh` helper script that does this for you: ```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 +$ ./scripts/install-toolchain.sh $ swift --version Swift version 5.3-dev (LLVM 09686f232a, Swift 5a196c7f13) Target: x86_64-apple-darwin19.6.0 From fb798a5f1a7e61975ffb8dd74a2f48704bb167a7 Mon Sep 17 00:00:00 2001 From: Max Desiatov Date: Mon, 19 Oct 2020 17:47:17 +0100 Subject: [PATCH 2/5] Update toolchain version, script, and `README.md` --- .swift-version | 2 +- README.md | 90 ++++++++++++++++++++++++++++++------ scripts/install-toolchain.sh | 9 ++-- 3 files changed, 84 insertions(+), 17 deletions(-) diff --git a/.swift-version b/.swift-version index ff4900d30..a6165cb1c 100644 --- a/.swift-version +++ b/.swift-version @@ -1 +1 @@ -wasm-5.3-SNAPSHOT-2020-10-02-a +wasm-5.3-SNAPSHOT-2020-10-16-a \ No newline at end of file diff --git a/README.md b/README.md index 3bea12048..b8c7e7a23 100644 --- a/README.md +++ b/README.md @@ -4,18 +4,7 @@ Swift framework to interact with JavaScript through WebAssembly. -## Requirements - -This library only supports [`swiftwasm/swift`](https://github.com/swiftwasm/swift) distribution toolchain. The toolchains can be installed via [`swiftenv`](https://github.com/kylef/swiftenv) like official nightly toolchain. You can use the `install-toolchain.sh` helper script that does this for you: - -```sh -$ ./scripts/install-toolchain.sh -$ swift --version -Swift version 5.3-dev (LLVM 09686f232a, Swift 5a196c7f13) -Target: x86_64-apple-darwin19.6.0 -``` - -## Usage +## Getting started This JavaScript code @@ -66,4 +55,79 @@ let swiftPet: Pet = try JSValueDecoder().decode(from: jsPet) alert("Swift is running on browser!") ``` -Please see [Example](https://github.com/swiftwasm/JavaScriptKit/tree/main/Example) directory for more information +### 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 +``` + +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-16-a/swift-wasm-5.3-SNAPSHOT-2020-10-16-a-macos-x86_64.tar.gz +``` + +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-dev (LLVM 09686f232a, Swift 5a196c7f13) +Target: x86_64-apple-darwin19.6.0 +``` \ No newline at end of file diff --git a/scripts/install-toolchain.sh b/scripts/install-toolchain.sh index b6a82df24..1e401d889 100755 --- a/scripts/install-toolchain.sh +++ b/scripts/install-toolchain.sh @@ -18,13 +18,16 @@ fi case $(uname -s) in Darwin) - toolchain_download="$swift_tag-osx.tar.gz" + toolchain_download="$swift_tag-macos-x86_64.tar.gz" + echo '-macos' >> .swift-version ;; 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" + echo '-ubuntu18.04' >> .swift-version 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" + echo '-ubuntu20.04' >> .swift-version else echo "Unknown Ubuntu version" exit 1 From 3601a34156194cf95bea826317aac11f88852215 Mon Sep 17 00:00:00 2001 From: Max Desiatov Date: Tue, 20 Oct 2020 17:22:54 +0100 Subject: [PATCH 3/5] Update example code in `README.md` --- README.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b8c7e7a23..0e6a988e7 100644 --- a/README.md +++ b/README.md @@ -32,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 @@ -52,7 +50,7 @@ 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 @@ -130,4 +128,4 @@ $ ./scripts/install-toolchain.sh $ swift --version Swift version 5.3-dev (LLVM 09686f232a, Swift 5a196c7f13) Target: x86_64-apple-darwin19.6.0 -``` \ No newline at end of file +``` From e14ee9dc204c20baec029035545abe3b9cf003a6 Mon Sep 17 00:00:00 2001 From: Max Desiatov Date: Wed, 21 Oct 2020 09:43:45 +0100 Subject: [PATCH 4/5] Update .swift-version --- .swift-version | 2 +- scripts/install-toolchain.sh | 9 +++------ 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/.swift-version b/.swift-version index a6165cb1c..a14e1af6f 100644 --- a/.swift-version +++ b/.swift-version @@ -1 +1 @@ -wasm-5.3-SNAPSHOT-2020-10-16-a \ No newline at end of file +wasm-5.3-SNAPSHOT-2020-10-20-a diff --git a/scripts/install-toolchain.sh b/scripts/install-toolchain.sh index 1e401d889..068d4ff14 100755 --- a/scripts/install-toolchain.sh +++ b/scripts/install-toolchain.sh @@ -18,16 +18,13 @@ fi case $(uname -s) in Darwin) - toolchain_download="$swift_tag-macos-x86_64.tar.gz" - echo '-macos' >> .swift-version + 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-x86_64.tar.gz" - echo '-ubuntu18.04' >> .swift-version + 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-x86_64.tar.gz" - echo '-ubuntu20.04' >> .swift-version + toolchain_download="$swift_tag-ubuntu20.04_x86_64.tar.gz" else echo "Unknown Ubuntu version" exit 1 From 3254c812b279cce830e1523cf8838d66cb910208 Mon Sep 17 00:00:00 2001 From: Max Desiatov Date: Wed, 21 Oct 2020 10:34:06 +0100 Subject: [PATCH 5/5] Update Swift version in README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0e6a988e7..8119d8c41 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ 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-16-a/swift-wasm-5.3-SNAPSHOT-2020-10-16-a-macos-x86_64.tar.gz +$ 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: @@ -126,6 +126,6 @@ You can also use the `install-toolchain.sh` helper script that uses a hardcoded ```sh $ ./scripts/install-toolchain.sh $ swift --version -Swift version 5.3-dev (LLVM 09686f232a, Swift 5a196c7f13) +Swift version 5.3 (swiftlang-5.3.0) Target: x86_64-apple-darwin19.6.0 ```