Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add installation doc #391

Merged
merged 1 commit into from
Oct 11, 2024
Merged

doc: add installation doc #391

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 31 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,24 @@ wRPC fully supports the unreleased native [WIT] `stream` and `future` data types

See [specification](./SPEC.md) for more info.

## Installation

Using [`cargo`](https://doc.rust-lang.org/cargo/index.html):
```sh
cargo install wrpc
```

Using [`nix`](https://zero-to-nix.com/start/install):
```sh
nix profile install github:bytecodealliance/wrpc

# or, without installing:

nix shell github:bytecodealliance/wrpc
```

You can also download individual binaries from the [release page](https://github.com/bytecodealliance/wrpc/releases)

## Quickstart

wRPC usage examples for different programming languages can be found at [examples](./examples).
Expand All @@ -47,7 +65,7 @@ There are 2 different kinds of examples:
- Native wRPC applications, tied to a particular wRPC transport (like Unix Domain Sockets, TCP, QUIC or NATS.io)
- Generic Wasm components, that need to run in a Wasm runtime. Those can be executed, for example, using `wrpc-wasmtime`, to polyfill imports at runtime and serve exports using wRPC.

### `hello` example
### `hello` example using NATS.io transport

In this example we will serve and invoke a simple [`hello`](./examples/wit/hello/hello.wit) application using:

Expand All @@ -61,6 +79,8 @@ In this example we will serve and invoke a simple [`hello`](./examples/wit/hello
- `nats-server` >= 2.10.20 or `docker` >= 24.0.6 (or any other OCI runtime)
- `rust` >= 1.80.1

NOTE: Nix users can just run `nix develop` anywhere in the repository to get all dependencies correctly set up

#### How-To

In the steps below, `wasm32-wasip1` target will be used, because it is currently available in stable Rust and also conveniently configured in [`rust-toolchain.toml`](./rust-toolchain.toml) in the root of this repository.
Expand All @@ -85,15 +105,7 @@ In the steps below, `wasm32-wasip1` target will be used, because it is currently

> NB: Rust uses `_` separators in the filename, because a component is built as a reactor-style library

3. Build the wRPC Wasm runtime:

```sh
cargo build --release --bin wrpc-wasmtime
```

> Output is in target/release/wrpc-wasmtime or target/release/wrpc-wasmtime.exe on Windows

4. Run NATS (more thorough documentation available [here](https://docs.nats.io/running-a-nats-service/introduction/running)):
3. Run NATS (more thorough documentation available [here](https://docs.nats.io/running-a-nats-service/introduction/running)):

- using standalone binary:
```sh
Expand All @@ -105,21 +117,21 @@ In the steps below, `wasm32-wasip1` target will be used, because it is currently
docker run --rm -it --name nats-server -p 4222:4222 nats:2.10.20-alpine3.20
```

5. Serve Wasm `hello` server via NATS:
4. Serve Wasm `hello` server via NATS:

```sh
./target/release/wrpc-wasmtime nats serve rust rust ./target/wasm32-wasip1/release/hello_component_server.wasm
wrpc-wasmtime nats serve rust rust ./target/wasm32-wasip1/release/hello_component_server.wasm
```

- Sample output:
> INFO async_nats: event: connected
>
> INFO wrpc_wasmtime_cli: serving instance function name="hello"

6. Call Wasm `hello` server using a Wasm `hello` client via NATS:
5. Call Wasm `hello` server using a Wasm `hello` client via NATS:

```sh
./target/release/wrpc-wasmtime nats run rust ./target/wasm32-wasip1/release/hello-component-client.wasm
wrpc-wasmtime nats run rust ./target/wasm32-wasip1/release/hello-component-client.wasm
```

- Sample output in the client:
Expand All @@ -132,28 +144,28 @@ In the steps below, `wasm32-wasip1` target will be used, because it is currently
>
> INFO wrpc_wasmtime_cli: successfully served instance function invocation

7. Call the Wasm `hello` server using a native wRPC `hello` client:
6. Call the Wasm `hello` server using a native wRPC `hello` client:

```sh
cargo run -p hello-nats-client rust
```

8. Serve native wRPC `hello` server:
7. Serve native wRPC `hello` server:

```sh
cargo run -p hello-nats-server native
```

9. Call both the native wRPC `hello` server and Wasm `hello` server using native wRPC `hello` client:
8. Call both the native wRPC `hello` server and Wasm `hello` server using native wRPC `hello` client:

```sh
cargo run -p hello-nats-client rust native
```

10. Call native wRPC `hello` server using Wasm `hello` client via NATS:
9. Call native wRPC `hello` server using Wasm `hello` client via NATS:

```sh
./target/release/wrpc-wasmtime nats run native ./target/wasm32-wasip1/release/hello-component-client.wasm
wrpc-wasmtime nats run native ./target/wasm32-wasip1/release/hello-component-client.wasm
```

## Repository structure
Expand Down
Loading