Improve development guides (#809)

* Improve development guides

* Apply suggestions from code review

Co-authored-by: Erdem Yerebasmaz <[email protected]>

* Add Firefox prerequisites

---------

Co-authored-by: Erdem Yerebasmaz <[email protected]>

Author: dangeross

.github/workflows/main.yml

@@ -59,12 +59,12 @@ jobs:
         run: cargo clippy -- -D warnings
 
   clippy-wasm:
-    name: Cargo Clippy WASM
+    name: Cargo Clippy Wasm
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install WASM target
+      - name: Install Wasm target
         run: rustup target add wasm32-unknown-unknown
 
       - uses: Swatinem/rust-cache@v2
@@ -126,12 +126,12 @@ jobs:
           fi
 
   build-wasm:
-    name: Cargo Build WASM
+    name: Cargo Build Wasm
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install WASM target
+      - name: Install Wasm target
         run: rustup target add wasm32-unknown-unknown
 
       - uses: Swatinem/rust-cache@v2
@@ -278,12 +278,12 @@ jobs:
         run: cargo test --no-default-features --features uniffi-25
 
   test-wasm:
-    name: Test WASM
+    name: Test Wasm
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install WASM target
+      - name: Install Wasm target
         run: rustup target add wasm32-unknown-unknown
 
       - name: Install wasm-pack
@@ -304,7 +304,7 @@ jobs:
       - name: Setup emsdk
         uses: mymindstorm/setup-emsdk@v14
 
-      - name: Test WASM
+      - name: Test Wasm
         run: make wasm-test
 
   notification-plugin:

CONTRIBUTING.md

@@ -36,9 +36,9 @@ __*[lib/core](lib/core)*__
 
 __*[lib/wasm](lib/wasm)*__
 * [model.rs](lib/wasm/src/model.rs) - Update the structs/enums exported.
-* [lib.rs](lib/wasm/src/lib.rs) - Update the Rust interface for the WASM bindings.
+* [lib.rs](lib/wasm/src/lib.rs) - Update the Rust interface for the Wasm bindings.
 
-After making these changes the [Dart](packages/dart), [Flutter](packages/flutter) and [React Native](packages/react-native) bindings code also need to be regenerated and included in your pull request. You can regenerate these from the project root using `make codegen`. Please see the prerequisites for [Flutter](lib/bindings/langs/flutter/README.md), [React Native](packages/react-native/DEVELOPING.md) and [WASM](lib/wasm/DEVELOPING.md) if this is your first time generating code.
+After making these changes the [Dart](packages/dart), [Flutter](packages/flutter) and [React Native](packages/react-native) bindings code also need to be regenerated and included in your pull request. You can regenerate these from the project root using `make codegen`. Please see the prerequisites for [Flutter](lib/bindings/langs/flutter/README.md), [React Native](packages/react-native/DEVELOPMENT.md) and [Wasm](lib/wasm/DEVELOPMENT.md) if this is your first time generating code.
 
 #### Testing
 Please adequately test your code using the existing tests and write additional tests for new features. You can run the tests from the project root using `make test`. You can also make use of the [CLI](cli) to test changes while developing your feature.

DEVELOPMENT.md

@@ -1,4 +1,15 @@
-## Setup
+# Development guide
+Please see the development guides for each crate/package:
+
+### Crates
+* [SDK Bindings](lib/bindings/DEVELOPMENT.md)
+* [SDK Core](lib/core/DEVELOPMENT.md)
+* [SDK Wasm](lib/wasm/DEVELOPMENT.md)
+
+### Packages
+* [React Native](packages/react-native/DEVELOPMENT.md)
+
+## Automatic format & syntax checking
 To configure automatic code formatting and syntax checking for this repository, you can run the following command once:
 ```bash
 git config --local core.hooksPath .githooks/

Makefile

@@ -1,5 +1,10 @@
 all: fmt codegen clippy
 
+init:
+	make -C ./lib/bindings init
+	make -C ./lib/core init
+	make -C ./lib/wasm init
+
 fmt:
 	cd lib && cargo fmt
 	cd cli && cargo fmt

lib/bindings/DEVELOPMENT.md

@@ -0,0 +1,30 @@
+# Development guide - Bindings crate
+This crate is responsible for building UniFFI bindings.
+
+## Prerequisites
+To build you need to first install:
+- [Protobuf](https://protobuf.dev/installation/)
+```bash
+brew install protobuf
+```
+
+Set the ANDROID_NDK_HOME env variable to your Android NDK directory:
+```bash
+export ANDROID_NDK_HOME=<your android ndk directory>
+```
+
+On first usage you will need to run:
+```bash
+make init
+```
+
+## Building
+To build bindings for individual languages please see the available [Makefile tasks](lib/bindings/makefile). Otherwise to build all bindings run:
+```bash
+make all
+```
+
+## Testing
+```bash
+make test
+```

lib/bindings/README.md

@@ -61,7 +61,7 @@ ecies = { version = "0.2.7", default-features = false, features = ["pure"] }
 semver = "1.0.23"
 lazy_static = "1.5.0"
 
-# Non-WASM dependencies
+# Non-Wasm dependencies
 [target.'cfg(not(all(target_family = "wasm", target_os = "unknown")))'.dependencies]
 electrum-client = { version = "0.21.0", default-features = false, features = [
     "use-rustls-ring",
@@ -74,7 +74,7 @@ tokio-stream = { version = "0.1.14", features = ["sync"] }
 tonic = { version = "^0.8", features = ["tls", "tls-webpki-roots"] }
 uuid = { version = "1.8.0", features = ["v4"] }
 
-# WASM dependencies
+# Wasm dependencies
 [target.'cfg(all(target_family = "wasm", target_os = "unknown"))'.dependencies]
 console_log = "1"
 lwk_wollet = { version = "0.9.0", default-features = false, features = [
@@ -92,11 +92,11 @@ tonic = { version = "0.12", default-features = false, features = [
 sdk-common = { workspace = true, features = ["test-utils"] }
 paste = "1.0.15"
 
-# Non-WASM dev dependencies
+# Non-Wasm dev dependencies
 [target.'cfg(not(all(target_family = "wasm", target_os = "unknown")))'.dev-dependencies]
 tempdir = "0.3.7"
 
-# WASM dev dependencies
+# Wasm dev dependencies
 [target.'cfg(all(target_family = "wasm", target_os = "unknown"))'.dev-dependencies]
 wasm-bindgen-test = "0.3.33"
 rand = "0.8"

lib/core/Cargo.toml

@@ -0,0 +1,26 @@
+# Development guide - Core crate
+
+## Prerequisites
+To compile the Core crate you will first need to install:
+- [Protobuf](https://protobuf.dev/installation/)
+- [Emscripten](https://emscripten.org/docs/getting_started/downloads.html) for compiling to Wasm
+- [Firefox](https://mozilla.org/firefox/download/) for testing Wasm
+
+```bash
+brew install protobuf emscripten
+```
+
+On first usage you will need to run:
+```bash
+make init
+```
+
+## Testing
+To test all targets run:
+```bash
+make test
+```
+This comprises the following make tasks:
+```bash
+make cargo-test wasm-test
+```

lib/core/DEVELOPMENT.md

@@ -189,7 +189,7 @@ impl LiquidSdkBuilder {
             None => {
                 #[cfg(all(target_family = "wasm", target_os = "unknown"))]
                 return Err(anyhow!(
-                    "Must provide a WASM-compatible persister on WASM builds"
+                    "Must provide a Wasm-compatible persister on Wasm builds"
                 ));
                 #[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
                 Arc::new(Persister::new_using_fs(

lib/core/README.md

@@ -0,0 +1,35 @@
+# Development guide - Wasm crate
+This crate is responsible for building Wasm specific bindings.
+
+## Prerequisites
+To build some dependencies you need to first install
+- [Protobuf](https://protobuf.dev/installation/)
+- [Emscripten](https://emscripten.org/docs/getting_started/downloads.html) for compiling to Wasm
+- [Firefox](https://mozilla.org/firefox/download/) for testing Wasm
+
+```bash
+brew install protobuf emscripten
+```
+
+On first usage you will need to run:
+```bash
+make init
+```
+
+## Building
+```bash
+make pack
+```
+
+This will generate the following artifacts:
+
+- `pkg/package.json`
+- `pkg/breez_sdk_liquid_wasm_bg.wasm`
+- `pkg/breez_sdk_liquid_wasm_bg.d.wasm`
+- `pkg/breez_sdk_liquid_wasm.d.ts`
+- `pkg/breez_sdk_liquid_wasm.js`
+
+## Testing
+```bash
+make test
+```

lib/core/src/sdk.rs

@@ -6,6 +6,7 @@ endif
 
 init:
 	cargo install wasm-pack
+	rustup target add wasm32-unknown-unknown
 
 clippy:
 	$(CLANG_PREFIX) cargo clippy --target=wasm32-unknown-unknown -- -D warnings

lib/wasm/DEVELOPING.md

@@ -1,4 +1,4 @@
-# Setting up a development environment
+# Development guide - React Native package
 
 The Breez Liquid SDK React Native plugin consumes the underlying Breez Liquid SDK from the following sources:
 
@@ -12,8 +12,8 @@ All the following commands can be run in the `packages/react-native` directory.
 
 ## Prerequisites
 
-Set the ANDROID_NDK_HOME env variable to your SDK home directory:
-```
+Set the ANDROID_NDK_HOME env variable to your Android NDK directory:
+```bash
 export ANDROID_NDK_HOME=<your android ndk directory>
 ```
 

lib/wasm/DEVELOPMENT.md

@@ -44,4 +44,4 @@ yarn ios
 
 ## Development
 
-To develop the Breez Liquid SDK alongside the React Native module and example app, please read [DEVELOPING.md](../DEVELOPING.md) for details on how to setup your development environment.
+To develop the Breez Liquid SDK alongside the React Native module and example app, please read [DEVELOPMENT.md](../DEVELOPMENT.md) for details on how to setup your development environment.