From 752cd81f2e4b2cc848ff8de328b1a81c343a14d5 Mon Sep 17 00:00:00 2001 From: Emmanuel Leblond Date: Thu, 3 Oct 2024 16:26:24 +0200 Subject: [PATCH] Improve README documentation for electron & web bindings --- bindings/electron/README.md | 32 ++++++++++++ bindings/web/README.md | 84 +++++++++++++------------------- bindings/web/scripts/liveplay.py | 44 +++++++++++++++++ 3 files changed, 111 insertions(+), 49 deletions(-) create mode 100755 bindings/web/scripts/liveplay.py diff --git a/bindings/electron/README.md b/bindings/electron/README.md index ccd27188b11..012995ff5be 100644 --- a/bindings/electron/README.md +++ b/bindings/electron/README.md @@ -1,5 +1,22 @@ # libparsec-electron-bindings +## Build + +tl;dr: `../../make.py er` + +```shell +# First run (to install dependencies) +../../make.py electron-dev-install +# or just +../../make.py ei +# Subsequent runs +../../make.py electron-dev-rebuild +# Or just +../../make.py er +``` + +Basically `make.py` wraps the following commands: + ```shell npm install # (re)generate index.node @@ -7,3 +24,18 @@ npm run build:dev # Or for release npm run build:release ``` + +## Testing (the simple way) + +Start node shell + +```shell +node +``` + +Then import libparsec package and you're good ! + +```javascript +libparsec = require("./bindings/electron/dist/libparsec"); +await libparsec.listAvailableDevices("/foo") +``` diff --git a/bindings/web/README.md b/bindings/web/README.md index b8265ad265f..fe173ed7cd9 100644 --- a/bindings/web/README.md +++ b/bindings/web/README.md @@ -1,67 +1,53 @@ -
+# libparsec-electron-bindings -

wasm-pack-template

+Remember to have [`wasm-pack`](https://github.com/rustwasm/wasm-pack) installed ! - A template for kick starting a Rust and WebAssembly project using wasm-pack. - -

- Build Status -

- -

- Tutorial - | - Chat -

- - Built with 🦀🕸 by The Rust and WebAssembly Working Group -
+```shell +curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh +``` -## About +## Build -[**📚 Read this template tutorial! 📚**][template-docs] +tl;dr: `../../make.py wr` -This template is designed for compiling Rust libraries into WebAssembly and -publishing the resulting package to NPM. +```shell +# First run (to install dependencies) +../../make.py web-dev-install +# or just +../../make.py wi +# Subsequent runs +../../make.py web-dev-rebuild +# Or just +../../make.py wr +``` -Be sure to check out [other `wasm-pack` tutorials online][tutorials] for other -templates and usages of `wasm-pack`. +Basically `make.py` wraps the following commands: -[tutorials]: https://rustwasm.github.io/docs/wasm-pack/tutorials/index.html -[template-docs]: https://rustwasm.github.io/docs/wasm-pack/tutorials/npm-browser-packages/index.html +```shell +npm install +# (re)generate index.node +npm run build:dev +# Or for release +npm run build:release +``` -## 🚴 Usage +The internal build command itself relies on [`wasm-pack`](https://github.com/rustwasm/wasm-pack). -### 🐑 Use `cargo generate` to Clone this Template +## Interactive testing -[Learn more about `cargo generate` here.](https://github.com/ashleygwilliams/cargo-generate) +To easily play with the bindings: -``` -cargo generate --git https://github.com/rustwasm/wasm-pack-template.git --name my-project -cd my-project +```shell +python ./scripts/liveplay.py ``` -### 🛠️ Build with `wasm-pack build` +This starts a server exposing a web page with the bindings, from there you +can open your browser console and start playing with `libparsec`. -``` -wasm-pack build -``` +## Testing -### 🔬 Test in Headless Browsers with `wasm-pack test` +There is not much tests for now, but you can use them with: -``` +```shell wasm-pack test --headless --firefox ``` - -### 🎁 Publish to NPM with `wasm-pack publish` - -``` -wasm-pack publish -``` - -## 🔋 Batteries Included - -* [`wasm-bindgen`](https://github.com/rustwasm/wasm-bindgen) for communicating - between WebAssembly and JavaScript. -* [`console_error_panic_hook`](https://github.com/rustwasm/console_error_panic_hook) - for logging panic messages to the developer console. diff --git a/bindings/web/scripts/liveplay.py b/bindings/web/scripts/liveplay.py new file mode 100755 index 00000000000..e2ef34a1adb --- /dev/null +++ b/bindings/web/scripts/liveplay.py @@ -0,0 +1,44 @@ +#! /usr/bin/env python +# Parsec Cloud (https://parsec.cloud) Copyright (c) BUSL-1.1 2016-present Scille SAS + + +import sys +import subprocess +from pathlib import Path + + +BASEDIR = Path(__file__).parent +PKG_DIR = BASEDIR / "../pkg" + + +INDEX_HTML_SRC = """ + + + + + + + +

Open you browser console and start with e.g. + libparsec.listAvailableDevices("/foo")

+ + +""" + + +if __name__ == "__main__": + if not PKG_DIR.exists(): + raise SystemExit( + f"{PKG_DIR} doesn't exist, you should build the bindings with `make.py` first !" + ) + print(f"Creating {PKG_DIR}/index.html...") + (PKG_DIR / "index.html").write_text(INDEX_HTML_SRC) + + subprocess.check_call([sys.executable, "-m", "http.server", "8000"], cwd=PKG_DIR)