Skip to content

Commit e880e25

Browse files
syrusakbarysyrusakbary
committed
Improved Readme
1 parent aa47179 commit e880e25

File tree

1 file changed

+93
-107
lines changed

1 file changed

+93
-107
lines changed

‎packages/api/README.md‎

Lines changed: 93 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,51 @@
1-
# <img height="48" src="https://raw.githubusercontent.com/wasmerio/wasmer/master/assets/logo.png" alt="Wasmer logo" valign="middle"> Wasmer Python [![PyPI version](https://img.shields.io/pypi/v/wasmer)](https://badge.fury.io/py/wasmer) [![Wasmer Python Documentation](https://img.shields.io/badge/docs-read-green)](https://wasmerio.github.io/wasmer-python/api/wasmer/) [![Wasmer PyPI downloads](https://pepy.tech/badge/wasmer)](https://pypi.org/project/wasmer/) [![Wasmer Slack Channel](https://img.shields.io/static/v1?label=chat&message=on%20Slack&color=green)](https://slack.wasmer.io)
1+
# <img height="48" src="https://raw.githubusercontent.com/wasmerio/wasmer/master/assets/logo.png" alt="Wasmer logo" valign="middle"> Wasmer Python [![PyPI version](https://img.shields.io/pypi/v/wasmer)](https://badge.fury.io/py/wasmer) [![Wasmer Python Documentation](https://img.shields.io/badge/docs-read-green)](https://wasmerio.github.io/wasmer-python/api/wasmer/) [![Wasmer PyPI downloads](https://pepy.tech/badge/wasmer)](https://pypi.org/project/wasmer/) [![Wasmer Slack #python Channel](https://img.shields.io/static/v1?label=chat&message=on%20Slack&color=green)](https://slack.wasmer.io)
22

33
A complete and mature WebAssembly runtime for Python based on
44
[Wasmer](https://github.com/wasmerio/wasmer).
55

6-
Features:
6+
### Features
77

8-
* **Easy to use**: The `wasmer` API mimics the standard WebAssembly API,
9-
* **Fast**: `wasmer` executes the WebAssembly modules as fast as
10-
possible, close to **native speed**,
11-
* **Safe**: All calls to WebAssembly will be fast, but more
12-
importantly, completely safe and sandboxed,
13-
* **Modular**: `wasmer` can compile the WebAssembly modules with
14-
different engines or compiler.
15-
16-
**Documentation**: [browse the detailed API
17-
documentation](https://wasmerio.github.io/wasmer-python/api/wasmer/wasmer.html) full of
18-
examples.
19-
20-
**Examples** as tutorials: [browse the `examples/`
21-
directory](https://github.com/wasmerio/wasmer-python/tree/master/examples),
22-
it's the best place for a complete introduction!
23-
24-
## Quick Introduction
25-
26-
The `wasmer` package brings the required API to execute WebAssembly
27-
modules. In a nutshell, `wasmer` compiles the WebAssembly module into
28-
compiled code, and then executes it. `wasmer` is designed to work in
29-
various environments and platforms: From nano single-board computers
30-
to large and powerful servers, including more exotic ones. To address
31-
those requirements, Wasmer provides 2 engines and 3 compilers.
32-
33-
Succinctly, an _engine_ is responsible to drive the _compilation_ and
34-
the _execution_ of a WebAssembly module. By extension, a _headless_
35-
engine can only execute a WebAssembly module, i.e. a module that has
36-
previously been compiled, or compiled, serialized and deserialized. By
37-
default, the `wasmer` package comes with 2 headless engines:
38-
39-
1. `wasmer.engine.JIT`, the compiled machine code lives in memory,
40-
2. `wasmer.engine.Native`, the compiled machine code lives in a shared
41-
object file (`.so`, `.dylib`, or `.dll`), and is natively executed.
42-
43-
Because `wasmer` does not embed compilers in its package, engines are
44-
headless, i.e. they can't compile WebAssembly module; they can only
45-
execute them. Compilers live in their own standalone packages. Let's
46-
briefly introduce them:
47-
48-
| Compiler package | Description | PyPi |
49-
|-|-|-|
50-
| `wasmer_compiler_singlepass` | Super fast compilation times, slower execution times. Not prone to JIT-bombs. *Ideal for blockchains* | [![On PyPi](https://img.shields.io/pypi/v/wasmer_compiler_singlepass)](https://pypi.org/project/wasmer_compiler_singlepass/) [![Downloads](https://pepy.tech/badge/wasmer_compiler_singlepass)](https://pypi.org/project/wasmer_compiler_singlepass/) |
51-
| `wasmer_compiler_cranelift` | Fast compilation times, fast execution times. *Ideal for development* | [![On PyPi](https://img.shields.io/pypi/v/wasmer_compiler_cranelift)](https://pypi.org/project/wasmer_compiler_cranelift/) [![Downloads](https://pepy.tech/badge/wasmer_compiler_cranelift)](https://pypi.org/project/wasmer_compiler_cranelift/) |
52-
| `wasmer_compiler_llvm` | Slow compilation times, very fast execution times (close to native, sometimes faster). *Ideal for Production* | [![On PyPi](https://img.shields.io/pypi/v/wasmer_compiler_llvm)](https://pypi.org/project/wasmer_compiler_llvm/) [![Downloads](https://pepy.tech/badge/wasmer_compiler_llvm)](https://pypi.org/project/wasmer_compiler_llvm/) |
53-
54-
We generally recommend `wasmer_compiler_cranelift` for development
55-
purposes and `wasmer_compiler_llvm` in production.
56-
57-
Learn more by reading [the documentation of the `wasmer.engine`
58-
submodule](https://wasmerio.github.io/wasmer-python/api/wasmer/wasmer.html#engine).
8+
* Secure by default. No file, network, or environment access, unless explicitly enabled.
9+
* Supports [WASI](https://github.com/WebAssembly/WASI) and [Emscripten](https://emscripten.org/) out of the box.
10+
* Fast. Run WebAssembly at near-native speeds.
11+
* Embeddable in [multiple programming languages](https://github.com/wasmerio/wasmer/#-language-integrations)
12+
* Compliant with latest WebAssembly Proposals (SIMD, Reference Types, Threads, ...)
5913

6014
## Install
6115

6216
To install the `wasmer` Python package, and let's say the
6317
`wasmer_compiler_cranelift` compiler, just run those commands in your shell:
6418

6519
```sh
66-
$ pip install wasmer==1.1.0
67-
$ pip install wasmer_compiler_cranelift==1.1.0
20+
$ pip install wasmer wasmer_compiler_cranelift
6821
```
6922

7023
And you're ready to get fun!
7124

72-
## Example
73-
74-
We highly recommend to read the
75-
[`examples/`](https://github.com/wasmerio/wasmer-python/tree/master/examples)
76-
directory, which contains a sequence of examples/tutorials. It's the
77-
best place to learn by reading examples.
78-
79-
But for the most eager of you, and we know you're numerous you
80-
mischievous, there is a quick toy program in
81-
`examples/appendices/simple.rs`, written in Rust:
82-
83-
```rust
84-
#[no_mangle]
85-
pub extern fn sum(x: i32, y: i32) -> i32 {
86-
x + y
87-
}
88-
```
25+
**Documentation**: [browse the detailed API
26+
documentation](https://wasmerio.github.io/wasmer-python/api/wasmer/wasmer.html) full of
27+
examples.
8928

90-
After compilation to WebAssembly, the
91-
[`examples/appendices/simple.wasm`](https://github.com/wasmerio/wasmer-python/blob/master/examples/appendices/simple.wasm)
92-
binary file is generated. ([Download
93-
it](https://github.com/wasmerio/wasmer-python/raw/master/examples/appendices/simple.wasm)).
29+
**Examples**: as tutorials: [browse the `examples/`
30+
directory](https://github.com/wasmerio/wasmer-python/tree/master/examples),
31+
it's the best place for a complete introduction!
9432

95-
Then, we can execute it in Python:
33+
## Usage
9634

9735
```python
9836
from wasmer import engine, Store, Module, Instance
99-
from wasmer_compiler_cranelift import Compiler
10037

101-
# Let's define the store, that holds the engine, that holds the compiler.
102-
store = Store(engine.JIT(Compiler))
38+
store = Store()
10339

10440
# Let's compile the module to be able to execute it!
105-
module = Module(store, open('simple.wasm', 'rb').read())
41+
module = Module(store, """
42+
(module
43+
(type (func (param i32 i32) (result i32)))
44+
(func (export "sum") (type 0) (param i32) (param i32) (result i32)
45+
local.get 0
46+
local.get 1
47+
i32.add))
48+
""")
10649

10750
# Now the module is compiled, we can instantiate it.
10851
instance = Instance(module)
@@ -119,40 +62,48 @@ And then, finally, enjoy by running:
11962
$ python examples/appendices/simple.py
12063
```
12164

122-
# Development
65+
We highly recommend to read the
66+
[`examples/`](https://github.com/wasmerio/wasmer-python/tree/master/examples)
67+
directory, which contains a sequence of examples/tutorials. It's the
68+
best place to learn by reading examples.
12369

124-
The Python extension is written in [Rust], with [`pyo3`] and
125-
[`maturin`].
12670

127-
First, you need to install Rust and Python. We will not make you the
128-
affront to explain to you how to install Python (if you really need,
129-
check [`pyenv`](https://github.com/pyenv/pyenv/)). For Rust though, we
130-
advise to use [`rustup`](https://rustup.rs/), then:
71+
## Quick Introduction
13172

132-
```sh
133-
$ rustup install stable
134-
```
73+
The `wasmer` package brings the required API to execute WebAssembly
74+
modules. In a nutshell, `wasmer` compiles the WebAssembly module into
75+
compiled code, and then executes it. `wasmer` is designed to work in
76+
various environments and platforms: From nano single-board computers
77+
to large and powerful servers, including more exotic ones. To address
78+
those requirements, Wasmer provides 2 engines and 3 compilers.
13579

136-
To set up your environment, you'll need [`just`], and then, install
137-
the prelude of this project:
80+
Succinctly, an _engine_ is responsible to drive the _compilation_ and
81+
the _execution_ of a WebAssembly module. By extension, a _headless_
82+
engine can only execute a WebAssembly module, i.e. a module that has
83+
previously been compiled, or compiled, serialized and deserialized. By
84+
default, the `wasmer` package comes with 2 headless engines:
13885

139-
```sh
140-
$ cargo install just
141-
$ just --list # to learn about all the available recipes
142-
$ just prelude
143-
```
86+
1. `wasmer.engine.Universal`, the compiled machine code lives in memory,
87+
2. `wasmer.engine.Native`, the compiled machine code lives in a shared
88+
object file (`.so`, `.dylib`, or `.dll`), and is natively executed.
14489

145-
It will install `pyo3` and `maturin` for Python and for Rust. It will
146-
also install [`virtualenv`].
90+
Because `wasmer` does not embed compilers in its package, engines are
91+
headless, i.e. they can't compile WebAssembly module; they can only
92+
execute them. Compilers live in their own standalone packages. Let's
93+
briefly introduce them:
14794

148-
Then, simply run:
95+
| Compiler package | Description | PyPi |
96+
|-|-|-|
97+
| `wasmer_compiler_singlepass` | Super fast compilation times, slower execution times. Not prone to JIT-bombs. *Ideal for blockchains* | [![On PyPi](https://img.shields.io/pypi/v/wasmer_compiler_singlepass)](https://pypi.org/project/wasmer_compiler_singlepass/) [![Downloads](https://pepy.tech/badge/wasmer_compiler_singlepass)](https://pypi.org/project/wasmer_compiler_singlepass/) |
98+
| `wasmer_compiler_cranelift` | Fast compilation times, fast execution times. *Ideal for development* | [![On PyPi](https://img.shields.io/pypi/v/wasmer_compiler_cranelift)](https://pypi.org/project/wasmer_compiler_cranelift/) [![Downloads](https://pepy.tech/badge/wasmer_compiler_cranelift)](https://pypi.org/project/wasmer_compiler_cranelift/) |
99+
| `wasmer_compiler_llvm` | Slow compilation times, very fast execution times (close to native, sometimes faster). *Ideal for Production* | [![On PyPi](https://img.shields.io/pypi/v/wasmer_compiler_llvm)](https://pypi.org/project/wasmer_compiler_llvm/) [![Downloads](https://pepy.tech/badge/wasmer_compiler_llvm)](https://pypi.org/project/wasmer_compiler_llvm/) |
100+
101+
We generally recommend `wasmer_compiler_cranelift` for development
102+
purposes and `wasmer_compiler_llvm` in production.
103+
104+
Learn more by reading [the documentation of the `wasmer.engine`
105+
submodule](https://wasmerio.github.io/wasmer-python/api/wasmer/wasmer.html#engine).
149106

150-
```sh
151-
$ source .env/bin/activate
152-
$ just build api
153-
$ just build compiler-cranelift
154-
$ python examples/appendices/simple.py
155-
```
156107

157108
## Supported platforms
158109

@@ -282,6 +233,41 @@ Distributions](https://www.python.org/dev/peps/pep-0425/)).
282233

283234
</details>
284235

236+
# Development
237+
238+
The Python extension is written in [Rust], with [`pyo3`] and
239+
[`maturin`].
240+
241+
First, you need to install Rust and Python. We will not make you the
242+
affront to explain to you how to install Python (if you really need,
243+
check [`pyenv`](https://github.com/pyenv/pyenv/)). For Rust though, we
244+
advise to use [`rustup`](https://rustup.rs/), then:
245+
246+
```sh
247+
$ rustup install stable
248+
```
249+
250+
To set up your environment, you'll need [`just`], and then, install
251+
the prelude of this project:
252+
253+
```sh
254+
$ cargo install just
255+
$ just --list # to learn about all the available recipes
256+
$ just prelude
257+
```
258+
259+
It will install `pyo3` and `maturin` for Python and for Rust. It will
260+
also install [`virtualenv`].
261+
262+
Then, simply run:
263+
264+
```sh
265+
$ source .env/bin/activate
266+
$ just build api
267+
$ just build compiler-cranelift
268+
$ python examples/appendices/simple.py
269+
```
270+
285271
## Testing
286272

287273
Build all the packages and run the tests:

0 commit comments

Comments
 (0)