From 1c2d09600d1c73a5975d770b9450ed5576d50009 Mon Sep 17 00:00:00 2001
From: Max Desiatov <max@desiatov.com>
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 <max@desiatov.com>
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 <max@desiatov.com>
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 <max@desiatov.com>
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 <max@desiatov.com>
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
```