Skip to content

Commit

Permalink
Improve docs on system support
Browse files Browse the repository at this point in the history
  • Loading branch information
webmaster128 committed Feb 23, 2022
1 parent 0bab52e commit 2106284
Show file tree
Hide file tree
Showing 3 changed files with 135 additions and 33 deletions.
4 changes: 4 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ insert_final_newline = true
indent_style = space
indent_size = 4

[*.py]
indent_style = space
indent_size = 4

[{Makefile,*.go}]
indent_style = tab
indent_size = 4
72 changes: 39 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,39 +14,45 @@ link with, and Go developers should just be able to import this directly.

## Supported Platforms

Requires Rust 1.51+, Requires Go 1.17+

Since this package includes a rust prebuilt dll, you cannot just import the go code,
but need to be on a system that works with an existing dll. Currently this is Linux
(tested on Ubuntu, Debian, and CentOS7) and MacOS. We have a build system for Windows,
but it is [not supported][wasmer_support] by the Wasmer Singlepass backend which we rely upon.

[wasmer_support]: https://docs.wasmer.io/ecosystem/wasmer/wasmer-features

### Overview

| | [x86] | [x86_64] | [ARM32] | [ARM64] |
| ------------- | ------------------- | ------------------- | -------------------- | -------------------- |
| Linux (glibc) | ❌‍ || ❌‍ <sub>[#53]</sub> | ❌‍ <sub>[#53]</sub> |
| Linux (muslc) | ❌‍ || ❌‍ <sub>[#53]</sub> | ❌‍ <sub>[#53]</sub> |
| macOS | ❌‍ || ❌‍ <sub>[#53]</sub> | ❌‍ <sub>[#53]</sub> |
| Windows | ❌ <sub>[#28]</sub> | ❌ <sub>[#28]</sub> | ❌ <sub>[#28]</sub> | ❌ <sub>[#28]</sub> |

[x86]: https://en.wikipedia.org/wiki/X86
[x86_64]: https://en.wikipedia.org/wiki/X86-64
[arm32]: https://en.wikipedia.org/wiki/AArch32
[arm64]: https://en.wikipedia.org/wiki/AArch64
[#28]: https://github.com/CosmWasm/wasmvm/issues/28
[#53]: https://github.com/CosmWasm/wasmvm/issues/53

✅ Supported and activly maintained.

❌ Blocked by external dependency.

🤷‍ Not supported because nobody cares so far. Feel free to look into it.

This is all blocked on [wasmer support for singlepass backend](https://docs.wasmer.io/ecosystem/wasmer/wasmer-features#compiler-support-by-chipset).
We can only move on these wasmvm issues when the upstream has support.
Requires Rust 1.55+ and Go 1.17+.

The Rust implementation of the VM is compiled to a library called libwasmvm. This is
then linked to the Go code when the final binary is built. For that reason not all
systems supported by Go are supported by this project.

Linux (tested on Ubuntu, Debian, and CentOS7, Alpine) and macOS is supported.
We are working on Windows (#288).

[#288]: https://github.com/CosmWasm/wasmvm/pull/288

### Builds of libwasmvm

Our system currently supports the following builds. In general we can only support targets
that are [supported by Wasmer's singlepass backend](https://docs.wasmer.io/ecosystem/wasmer/wasmer-features#compiler-support-by-chipset),
which for example excludes all 32 bit systems.

<!-- AUTO GENERATED BY libwasmvm_builds.py START -->

| OS family | Arch | Linking | Supported | Wasmer 2.2+ | Note |
| --------------- | ------- | ------- | -------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Linux (glibc) | x86_64 | shared | ✅​libwasmvm.so | ✅​libwasmvm.so | |
| Linux (glibc) | x86_64 | static | 🚫​ | 🚫​ | Would link libwasmvm statically but glibc dynamically as static glibc linking is not recommended. Potentially interesting for Osmosis. |
| Linux (glibc) | aarch64 | shared | 🚫​ | ✅​libwasmvm.aarch64.so | |
| Linux (glibc) | aarch64 | static | 🚫​ | 🚫​ | |
| Linux (musl) | x86_64 | shared | 🚫​ | 🚫​ | Possible but not needed |
| Linux (musl) | x86_64 | static | ✅​libwasmvm_muslc.a | ✅​libwasmvm_muslc.a | |
| Linux (musl) | aarch64 | shared | 🚫​ | 🚫​ | Possible but not needed |
| Linux (musl) | aarch64 | static | 🚫​ | ✅​libwasmvm_muslc.aarch64.a | |
| macOS | x86_64 | shared | ✅​libwasmvm.dylib | ✅​libwasmvm.dylib | Fat/universal library with multiple archs (#294) |
| macOS | x86_64 | static | 🚫​ | 🚫​ | |
| macOS | aarch64 | shared | 🚫​ | ✅​libwasmvm.dylib | Fat/universal library with multiple archs (#294) |
| macOS | aarch64 | static | 🚫​ | 🚫​ | |
| Windows (mingw) | x86_64 | shared | 🏗​wasmvm.dll | 🏗​wasmvm.dll | See #288 |
| Windows (mingw) | x86_64 | static | 🚫​ | 🚫​ | |
| Windows (mingw) | aarch64 | shared | 🚫​ | 🚫​ | |
| Windows (mingw) | aarch64 | static | 🚫​ | 🚫​ | |

<!-- AUTO GENERATED BY libwasmvm_builds.py END -->

## Docs

Expand Down
92 changes: 92 additions & 0 deletions docs/libwasmvm_builds.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@


oss = ["Linux (glibc)", "Linux (musl)", "macOS", "Windows (mingw)"]
cpus = ["x86_64", "aarch64"]
build_types = ["shared", "static"]
# libc = ["glibc", "musl"]

ZERO_WIDTH_SPACE = "\u200B"
SUPPORTED = "✅" + ZERO_WIDTH_SPACE
UNSUPPORTED = "🚫" + ZERO_WIDTH_SPACE
UNKNOWN = "🤷" + ZERO_WIDTH_SPACE
UNDER_CONSTRUCTION = "🏗" + ZERO_WIDTH_SPACE

def is_supported(os, cpu, build_type):
if cpu == "aarch64":
return UNSUPPORTED
if os == "Windows (mingw)":
if cpu == "x86_64" and build_type == "shared":
return UNDER_CONSTRUCTION + "wasmvm.dll"
else:
return UNSUPPORTED
if os == "macOS" and build_type == "static":
return UNSUPPORTED
if os == "macOS" and build_type == "shared":
return SUPPORTED + "libwasmvm.dylib"
if os == "Linux (musl)":
if build_type == "static":
return SUPPORTED + "libwasmvm_muslc.a"
if build_type == "shared":
return UNSUPPORTED
if os == "Linux (glibc)":
if build_type == "static":
return UNSUPPORTED
if build_type == "shared":
return SUPPORTED + "libwasmvm.so"
return UNKNOWN

def wasmer22_supported(os, cpu, build_type):
if os == "Windows (mingw)":
if cpu == "x86_64" and build_type == "shared":
return UNDER_CONSTRUCTION + "wasmvm.dll"
else:
return UNSUPPORTED
if os == "macOS" and build_type == "static":
return UNSUPPORTED
if os == "macOS" and build_type == "shared":
return SUPPORTED + "libwasmvm.dylib"
if os == "Linux (musl)":
if build_type == "static":
if cpu == "x86_64":
return SUPPORTED + "libwasmvm_muslc.a"
elif cpu == "aarch64":
return SUPPORTED + "libwasmvm_muslc.aarch64.a"
if build_type == "shared":
return UNSUPPORTED
if os == "Linux (glibc)":
if build_type == "static":
return UNSUPPORTED
if build_type == "shared":
if cpu == "x86_64":
return SUPPORTED + "libwasmvm.so"
elif cpu == "aarch64":
return SUPPORTED + "libwasmvm.aarch64.so"
return UNKNOWN

def get_note(os, cpu, build_type):
if os == "Windows (mingw)" and cpu == "x86_64" and build_type == "shared":
return "See #288"
if os == "Linux (glibc)" and cpu == "x86_64" and build_type == "static":
return "Would link libwasmvm statically but glibc dynamically as static glibc linking is not recommended. Potentially interesting for Osmosis."
if os == "Linux (musl)" and build_type == "shared":
return "Possible but not needed"
if os == "macOS" and build_type == "shared":
return "Fat/universal library with multiple archs (#294)"
return ""

print("<!-- AUTO GENERATED BY libwasmvm_builds.py START -->")
print("| OS family | Arch | Linking | Supported | Wasmer 2.2+ | Note |")
print("| --------------- | ------- | ------- | ------------------- | ----------------------------- | ------- |")

for os in oss:
for cpu in cpus:
for build_type in build_types:
s1 = is_supported(os, cpu, build_type)
s2 = wasmer22_supported(os, cpu, build_type)
note = get_note(os, cpu, build_type)
print(
"| {:<15} | {:<7} | {:<7} | {:<19} | {:<29} | {} |".format(
os, cpu, build_type, s1, s2, note
)
)
print("<!-- AUTO GENERATED BY libwasmvm_builds.py END -->")

0 comments on commit 2106284

Please sign in to comment.