2019-02-19 17:01:44 -07:00
< p align = "center" >
< a href = "https://wasmer.io" target = "_blank" rel = "noopener noreferrer" >
< img width = "400" src = "https://raw.githubusercontent.com/wasmerio/wasmer/master/logo.png" alt = "Wasmer logo" >
< / a >
< / p >
2018-10-11 21:29:36 +02:00
2018-11-05 14:52:53 +01:00
< p align = "center" >
2019-02-19 17:01:44 -07:00
< a href = "https://circleci.com/gh/wasmerio/wasmer/" >
< img src = "https://img.shields.io/circleci/project/github/wasmerio/wasmer/master.svg" alt = "Build Status" >
< / a >
< a href = "https://github.com/wasmerio/wasmer/blob/master/LICENSE" >
< img src = "https://img.shields.io/github/license/wasmerio/wasmer.svg" alt = "License" >
< / 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" >
< img alt = "Follow @wasmerio on Twitter" src = "https://img.shields.io/twitter/follow/wasmerio?label=%40wasmerio&style=social" >
< / 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-05-15 04:02:04 -07:00
[Wasmer ](https://wasmer.io/ ) is a standalone JIT WebAssembly runtime, aiming to be fully compatible with [WASI ](https://github.com/WebAssembly/WASI ) and [Emscripten ](https://emscripten.org/ ).
2018-12-07 11:21:04 -08:00
Install Wasmer with:
```sh
curl https://get.wasmer.io -sSfL | sh
```
2018-10-11 21:29:36 +02:00
2019-07-31 18:09:23 -07:00
> Note: *Wasmer is also available on Windows. Download the [`WasmerInstaller.exe` from the Github Releases](https://github.com/wasmerio/wasmer/releases) page.*
2019-04-10 18:37:22 -07:00
Wasmer runtime can also be embedded in different languages, so you can use WebAssembly anywhere ✨:
2019-05-01 14:50:39 +02:00
2019-07-31 18:09:23 -07:00
* [**🦀 Rust** ](https://github.com/wasmerio/wasmer-rust-example )
2019-07-31 18:18:37 -07:00
* [**🔗 C/C++** ](https://github.com/wasmerio/wasmer-c-api )
2019-07-31 18:19:42 -07:00
* [**#️⃣ C#** ](https://github.com/migueldeicaza/WasmerSharp )
2019-05-01 14:50:39 +02:00
* [**🐘 PHP** ](https://github.com/wasmerio/php-ext-wasm )
* [**🐍 Python** ](https://github.com/wasmerio/python-ext-wasm )
* [**💎 Ruby** ](https://github.com/wasmerio/ruby-ext-wasm )
2019-05-29 12:36:09 -07:00
* [**🐹 Go** ](https://github.com/wasmerio/go-ext-wasm )
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
wasmer run 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-05-03 10:19:35 -07:00
#### With WAPM
2019-05-06 16:41:59 -07:00
Installing Wasmer through `wasmer.io` includes
2019-07-24 17:44:06 -07:00
[`wapm` ](https://github.com/wasmerio/wapm-cli ), the [WebAssembly Package Manager ](https://wapm.io/ ).
2019-05-03 10:19:35 -07:00
2019-05-03 10:21:26 -07:00
Wapm allows you to easily download, run, and distribute WebAssembly binaries.
2019-05-03 10:19:35 -07:00
```sh
# Install cowsay globally
2019-05-03 10:28:42 -07:00
wapm install -g cowsay
2019-05-03 10:19:35 -07:00
# Run cowsay
wapm run cowsay "Hello, world!"
```
For more information about wapm, check out the [website ](https://www.wapm.io )
and this [example program ](https://github.com/wapm-packages/rust-wasi-example ).
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-02-19 17:01:44 -07:00
- [`examples` ](./examples ): some useful examples to 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-02-19 17:01:44 -07:00
Or, in case 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-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-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-07-31 18:09:23 -07:00
Windows support is _experimental_ . WASI is fully supported, but Emscripten support is on the works (this means
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 )
3. Install [Python for Windows ](https://www.python.org/downloads/release/python-2714/ ). The Windows x86-64 MSI installer is fine.
2019-02-19 17:01:44 -07:00
Make sure to enable "Add python.exe to Path" during installation.
2019-01-22 21:22:23 -08:00
2019-03-07 18:06:53 -08:00
4. 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-03-07 18:06:53 -08:00
5. Install [CMake ](https://cmake.org/download/ ). Ensure CMake is in your PATH.
2019-07-22 17:50:10 -07:00
6. Install [LLVM 8.0 ](https://prereleases.llvm.org/win-snapshots/LLVM-8.0.0-r351033-win64.exe )
2019-07-24 17:42:03 -07:00
< / p >
< / details >
2019-02-14 09:58:33 -08:00
2019-01-22 21:22:23 -08:00
## Building
Wasmer is built with [Cargo ](https://crates.io/ ), the Rust package manager.
2018-10-11 21:29:36 +02:00
2019-07-05 18:57:30 -07:00
Set Rust Nightly:
```
rustup default nightly
```
And install Wasmer
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
# make sure that `python` is accessible.
2019-07-05 18:36:34 -07:00
make install
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`
* WASI: `make wasi`
* 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-07-24 18:15:18 -07:00
- [x] Support Emscripten calls _(in the works)_
- [ ] Support Go js ABI calls
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 )