2019-02-19 17:01:44 -07:00
< p align = "center" >
< a href = "https://wasmer.io" target = "_blank" rel = "noopener noreferrer" >
2019-08-17 21:41:09 -07:00
< img width = "300" src = "https://raw.githubusercontent.com/wasmerio/wasmer/master/logo.png" alt = "Wasmer logo" >
2019-02-19 17:01:44 -07:00
< / a >
< / p >
2018-10-11 21:29:36 +02:00
2018-11-05 14:52:53 +01:00
< p align = "center" >
2019-08-31 21:13:46 -07:00
< a href = "https://dev.azure.com/wasmerio/wasmer/_build/latest?definitionId=3&branchName=master" >
< img src = "https://img.shields.io/azure-devops/build/wasmerio/wasmer/3.svg?style=flat-square" alt = "Build Status" >
2019-02-19 17:01:44 -07:00
< / a >
2019-12-04 13:11:11 -08:00
< a href = "https://docs.wasmer.io" >
< img src = "https://img.shields.io/badge/Docs-docs.wasmer.io-blue?style=flat-square" alt = "Documentation" >
< / a >
2019-02-19 17:01:44 -07:00
< a href = "https://github.com/wasmerio/wasmer/blob/master/LICENSE" >
2019-08-31 21:13:46 -07:00
< img src = "https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square" alt = "License" >
2019-02-19 17:01:44 -07:00
< / a >
2019-01-28 10:12:23 -08:00
< a href = "https://spectrum.chat/wasmer" >
2019-02-19 17:01:44 -07:00
< img src = "https://withspectrum.github.io/badge/badge.svg" alt = "Join the Wasmer Community" >
2019-01-28 10:12:23 -08:00
< / a >
2019-07-24 18:35:57 -07:00
< a href = "https://twitter.com/wasmerio" >
2019-08-31 21:13:46 -07:00
< img alt = "Follow @wasmerio on Twitter" src = "https://img.shields.io/twitter/follow/wasmerio?label=%40wasmerio&style=flat-square" >
2019-07-24 18:35:57 -07:00
< / a >
2018-11-05 14:52:53 +01:00
< / p >
2018-10-11 21:29:36 +02:00
2018-11-05 14:52:53 +01:00
## Introduction
2018-10-11 21:29:36 +02:00
2019-11-25 11:25:05 -08:00
[Wasmer ](https://wasmer.io/ ) is a standalone WebAssembly runtime for running WebAssembly [outside of the browser ](https://webassembly.org/docs/non-web/ ), supporting [WASI ](https://github.com/WebAssembly/WASI ) and [Emscripten ](https://emscripten.org/ ). Wasmer can be used standalone (via the CLI) and embedded in different languages, running in x86 and [ARM devices ](https://medium.com/wasmer/running-webassembly-on-arm-7d365ed0e50c ).
2019-09-01 01:33:21 -07:00
2019-12-04 13:11:11 -08:00
Install the Wasmer and [WAPM ](https://wapm.io ) cli with:
2018-12-07 11:21:04 -08:00
```sh
curl https://get.wasmer.io -sSfL | sh
```
2018-10-11 21:29:36 +02:00
2019-09-01 02:12:46 -07:00
> Note: *Wasmer is also [available on Windows](https://github.com/wasmerio/wasmer/releases)*
2019-07-31 18:09:23 -07:00
2019-09-01 01:56:23 -07:00
### Languages
2019-09-01 02:12:46 -07:00
Wasmer runtime can be used as a library embedded in different languages, so you can use WebAssembly anywhere:
2019-09-01 01:56:23 -07:00
2019-09-01 02:28:59 -07:00
| | Language | Author(s) | Maintenance | Release | Stars |
|-|-|-|-|-|-|
|  | [**Rust** ](https://github.com/wasmerio/wasmer-rust-example ) | Wasmer | actively developed | < a href = "https://crates.io/crates/wasmer-runtime/" target = "_blank" > </ a > |  |
|  | [**C/C++** ](https://github.com/wasmerio/wasmer-c-api ) | Wasmer | actively developed | < a href = "https://github.com/wasmerio/wasmer-c-api/" target = "_blank" > </ a > |  |
|  | [**Python** ](https://github.com/wasmerio/python-ext-wasm ) | Wasmer | actively developed | < a href = "https://pypi.org/project/wasmer/" target = "_blank" > </ a > |  |
|  | [**Go** ](https://github.com/wasmerio/go-ext-wasm ) | Wasmer | actively developed | < a href = "https://github.com/wasmerio/go-ext-wasm" target = "_blank" > </ a > |  |
|  | [**PHP** ](https://github.com/wasmerio/php-ext-wasm ) | Wasmer | actively developed | < a href = "https://pecl.php.net/package/wasm" target = "_blank" > </ a > |  |
|  | [**Ruby** ](https://github.com/wasmerio/ruby-ext-wasm ) | Wasmer | actively developed | < a href = "https://rubygems.org/gems/wasmer" target = "_blank" > </ a > |  |
|  | [**Postgres** ](https://github.com/wasmerio/postgres-ext-wasm ) | Wasmer | actively developed | < a href = "https://github.com/wasmerio/postgres-ext-wasm" target = "_blank" > </ a > |  |
2019-10-21 12:09:10 -07:00
|  | [**JavaScript** ](https://github.com/wasmerio/wasmer-js ) | Wasmer | actively developed | < a href = "https://www.npmjs.com/package/ @wasmer/wasi " target = "_blank" > </ a > |  |
2019-09-01 02:28:59 -07:00
|  | [**C#/.Net** ](https://github.com/migueldeicaza/WasmerSharp ) | [Miguel de Icaza ](https://github.com/migueldeicaza ) | actively developed | < a href = "https://www.nuget.org/packages/WasmerSharp/" target = "_blank" > </ a > |  |
|  | [**R** ](https://github.com/dirkschumacher/wasmr ) | [Dirk Schumacher ](https://github.com/dirkschumacher ) | actively developed | |  |
2020-01-16 01:19:21 +01:00
|  | [**Elixir** ](https://github.com/tessi/wasmex ) | [Philipp Tessenow ](https://github.com/tessi ) | actively developed | |  |
2019-09-01 02:28:59 -07:00
| ❓ | [your language is missing? ](https://github.com/wasmerio/wasmer/issues/new?assignees=&labels=%F0%9F%8E%89+enhancement&template=---feature-request.md&title= ) | | | |
2019-01-24 14:50:29 -08:00
2018-12-07 11:25:31 -08:00
### Usage
2018-10-11 21:29:36 +02:00
2019-02-19 17:01:44 -07:00
Wasmer can execute both the standard binary format (`.wasm` ) and the text
2018-11-05 14:52:53 +01:00
format defined by the WebAssembly reference interpreter (`.wat` ).
2018-10-11 21:29:36 +02:00
2019-04-10 11:34:18 -07:00
Once installed, you will be able to run any WebAssembly files (_including Lua, PHP, SQLite and nginx!_):
2018-10-14 23:49:10 +02:00
```sh
2019-01-22 11:34:36 -08:00
# Run Lua
2019-12-04 13:11:11 -08:00
wasmer examples/lua.wasm
2018-10-14 23:49:10 +02:00
```
2019-07-24 17:43:17 -07:00
*You can find more `wasm/wat` examples in the [examples ](./examples ) directory.*
2019-12-04 13:11:11 -08:00
### Docs
2019-05-03 10:19:35 -07:00
2019-12-04 13:11:11 -08:00
Wasmer documentation lives on [docs.wasmer.io ](https://docs.wasmer.io ).
2019-05-03 10:19:35 -07:00
2019-01-22 11:34:36 -08:00
## Code Structure
Wasmer is structured into different directories:
2019-02-19 17:01:44 -07:00
- [`src` ](./src ): code related to the Wasmer executable itself
2019-01-22 11:34:36 -08:00
- [`lib` ](./lib ): modularized libraries that Wasmer uses under the hood
2019-09-30 19:47:10 -07:00
- [`examples` ](./examples ): some useful examples for getting started with Wasmer
2019-01-22 11:34:36 -08:00
2019-01-22 21:22:23 -08:00
## Dependencies
2018-10-11 21:29:36 +02:00
2019-02-19 17:01:44 -07:00
Building Wasmer requires [rustup ](https://rustup.rs/ ).
2019-01-22 21:22:23 -08:00
2019-07-31 18:09:23 -07:00
To build Wasmer on Windows, download and run [`rustup-init.exe` ](https://win.rustup.rs/ )
2019-01-22 21:22:23 -08:00
then follow the onscreen instructions.
2019-02-14 09:58:33 -08:00
To build on other systems, run:
2019-01-22 21:22:23 -08:00
```sh
curl https://sh.rustup.rs -sSf | sh
```
### Other dependencies
Please select your operating system:
2019-01-24 14:50:29 -08:00
2019-07-24 17:42:03 -07:00
< details >
2019-07-24 18:15:18 -07:00
< summary > < b > macOS< / b > < / summary >
2019-07-24 17:42:03 -07:00
< p >
2019-01-22 21:22:23 -08:00
#### macOS
2019-02-19 17:01:44 -07:00
If you have [Homebrew ](https://brew.sh/ ) installed:
2019-01-22 21:22:23 -08:00
2019-01-24 14:50:29 -08:00
```sh
2019-01-22 21:22:23 -08:00
brew install cmake
```
2019-09-30 19:47:10 -07:00
Or, if you have [MacPorts ](https://www.macports.org/install.php ):
2019-01-22 21:22:23 -08:00
```sh
sudo port install cmake
```
2019-07-24 17:42:03 -07:00
< / p >
< / details >
< details >
2019-07-24 18:15:18 -07:00
< summary > < b > Debian-based Linuxes< / b > < / summary >
2019-07-24 17:42:03 -07:00
< p >
2019-07-24 18:15:18 -07:00
2019-01-22 21:22:23 -08:00
#### Debian-based Linuxes
2019-01-24 14:50:29 -08:00
```sh
2019-04-23 21:26:19 -04:00
sudo apt install cmake pkg-config libssl-dev
2019-01-22 21:22:23 -08:00
```
2019-09-30 19:47:10 -07:00
2019-07-24 17:42:03 -07:00
< / p >
< / details >
< details >
2019-07-24 18:15:18 -07:00
< summary > < b > FreeBSD< / b > < / summary >
2019-07-24 17:42:03 -07:00
< p >
2019-01-22 21:22:23 -08:00
2019-04-01 09:48:32 +02:00
#### FreeBSD
```sh
pkg install cmake
```
2019-09-30 19:47:10 -07:00
2019-07-24 17:42:03 -07:00
< / p >
< / details >
< details >
2019-07-24 18:15:18 -07:00
< summary > < b > Windows< / b > < / summary >
2019-07-24 17:42:03 -07:00
< p >
2019-04-01 09:48:32 +02:00
2019-01-22 21:22:23 -08:00
#### Windows (MSVC)
2019-09-30 19:47:10 -07:00
Windows support is _experimental_ . WASI is fully supported, but Emscripten support is in the works (this means
2019-07-31 18:09:23 -07:00
nginx and Lua do not work on Windows - you can track the progress on [this issue ](https://github.com/wasmerio/wasmer/issues/176 )).
2019-01-22 21:22:23 -08:00
2019-03-07 18:06:53 -08:00
1. Install [Visual Studio ](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=15 )
2. Install [Rust for Windows ](https://win.rustup.rs )
2019-11-19 13:53:36 -08:00
3. Install [Git for Windows ](https://git-scm.com/download/win ). Allow it to add `git.exe` to your PATH (default
2019-01-24 14:50:29 -08:00
settings for the installer are fine).
2019-01-22 21:22:23 -08:00
2019-11-19 13:53:36 -08:00
4. Install [CMake ](https://cmake.org/download/ ). Ensure CMake is in your PATH.
2019-03-07 18:06:53 -08:00
2019-11-19 13:53:36 -08:00
5. Install [LLVM 8.0 ](https://prereleases.llvm.org/win-snapshots/LLVM-8.0.0-r351033-win64.exe )
2019-09-30 19:47:10 -07:00
< / p >
< / details >
2019-02-14 09:58:33 -08:00
2019-01-22 21:22:23 -08:00
## Building
2019-09-30 19:47:10 -07:00
2019-12-19 14:00:26 -05:00
[](https://blog.rust-lang.org/2019/11/07/Rust-1.39.0.html)
2019-01-22 21:22:23 -08:00
Wasmer is built with [Cargo ](https://crates.io/ ), the Rust package manager.
2018-10-11 21:29:36 +02:00
2019-08-22 11:26:23 -07:00
The Singlepass backend requires nightly, so if you want to use it,
2019-07-05 18:57:30 -07:00
Set Rust Nightly:
2019-09-30 19:47:10 -07:00
2019-07-05 18:57:30 -07:00
```
rustup default nightly
```
2019-09-30 19:47:10 -07:00
Otherwise an up to date (see badge above) version of stable Rust will work.
2019-08-22 11:26:23 -07:00
2019-07-05 18:57:30 -07:00
And install Wasmer
2019-09-30 19:47:10 -07:00
2018-10-11 21:29:36 +02:00
```sh
2018-12-17 23:13:23 -06:00
# checkout code
git clone https://github.com/wasmerio/wasmer.git
2018-10-11 21:29:36 +02:00
cd wasmer
# install tools
2019-07-31 21:11:29 -07:00
make release-clif # To build with cranelift (default)
make release-llvm # To build with llvm support
make release-singlepass # To build with singlepass support
# or
make release # To build with singlepass, cranelift and llvm support
2018-10-11 21:29:36 +02:00
```
2018-10-14 23:49:10 +02:00
## Testing
2019-02-19 17:01:44 -07:00
Thanks to [spec tests ](https://github.com/wasmerio/wasmer/tree/master/lib/spectests/spectests ) we can ensure 100% compatibility with the WebAssembly spec test suite.
2018-10-24 12:07:52 +02:00
2019-07-05 18:36:34 -07:00
You can run all the tests with:
2018-10-14 23:49:10 +02:00
```sh
2019-07-05 18:57:30 -07:00
rustup default nightly
2018-11-15 13:30:00 -08:00
make test
2018-10-14 23:49:10 +02:00
```
2019-07-05 18:36:34 -07:00
### Testing backends
2018-10-24 12:07:52 +02:00
2019-07-05 18:36:34 -07:00
Each backend can be tested separately:
2018-10-24 12:07:52 +02:00
2019-07-05 18:36:34 -07:00
* Singlepass: `make singlepass`
* Cranelift: `make cranelift`
* LLVM: `make llvm`
### Testing integrations
Each integration can be tested separately:
* Spec tests: `make spectests`
* Emscripten: `make emtests`
2019-11-22 11:15:26 +09:00
* WASI: `make wasitests`
2019-07-05 18:36:34 -07:00
* Middleware: `make middleware`
2019-07-05 19:55:03 -07:00
* C API: `make capi`
2019-01-18 12:20:13 -08:00
2019-02-22 12:31:31 -08:00
## Benchmarking
Benchmarks can be run with:
```sh
2019-07-31 08:53:33 +09:00
make bench-[backend]
# for example
make bench-singlepass
2019-02-22 12:31:31 -08:00
```
2018-10-24 12:07:52 +02:00
## Roadmap
2018-10-14 23:54:28 +02:00
Wasmer is an open project guided by strong principles, aiming to be modular, flexible and fast. It is open to the community to help set its direction.
2019-02-19 17:01:44 -07:00
Below are some of the goals of this project (in order of priority):
2018-10-24 12:07:52 +02:00
2019-02-19 17:01:44 -07:00
- [x] It should be 100% compatible with the [WebAssembly spec tests ](https://github.com/wasmerio/wasmer/tree/master/lib/spectests/spectests )
2018-11-21 22:15:13 -08:00
- [x] It should be fast _(partially achieved)_
2019-04-23 10:37:35 -04:00
- [x] Support WASI - released in [0.3.0 ](https://github.com/wasmerio/wasmer/releases/tag/0.3.0 )
2019-12-04 13:11:11 -08:00
- [x] Support Emscripten calls
- [ ] Support Go JS ABI calls _(in the works)_
2018-12-07 11:25:31 -08:00
## Architecture
2019-07-31 18:09:23 -07:00
If you would like to know how Wasmer works under the hood, please see [docs/architecture.md ](./docs/architecture.md ).
2018-12-07 11:25:31 -08:00
2018-10-11 21:29:36 +02:00
## License
2019-02-19 17:01:44 -07:00
Wasmer is primarily distributed under the terms of the [MIT license ](http://opensource.org/licenses/MIT ) ([LICENSE ](./LICENSE )).
2018-12-19 13:00:07 -08:00
2019-02-19 17:01:44 -07:00
[ATTRIBUTIONS ](./ATTRIBUTIONS.md )