Merge pull request #5425 from wasmerio/fix-build-docs

chore: Update build docs
wasmerio · Feb 24, 2025 · e547869 · e547869
2 parents e689b33 + b1e1974
commit e547869
Show file tree

Hide file tree

Showing 15 changed files with 75 additions and 31 deletions.
diff --git a/docs/BUILD.md b/docs/BUILD.md
@@ -2,7 +2,7 @@
 
 ## Installing Rustup
 
-Building Wasmer from source requires [Rust](https://rustup.rs/) **1.67+**.
+Building Wasmer from source requires [Rust](https://rustup.rs/) **1.81+**.
 
 The easiest way to install Rust on your system is via Rustup. To get Rustup on Linux and macOS, you can run the following:
 
@@ -15,14 +15,31 @@ curl https://sh.rustup.rs -sSf | sh
 
 ## Installing Additional Dependencies
 
+### Linux 
+Linux is fully supported by Wasmer. WASI(x) is also fully supported. Users
+building from source can enable the LLVM backend following the instruction in
+the dedicated section below and installing LLVM version 18. To install it,
+refer to [LLVM's download
+page](https://github.com/llvm/llvm-project/releases/tag/llvmorg-18.1.7) or
+check your distro's package manager.
+
+
+### macOS
+macOS is fully supported by Wasmer. WASI(x) is also fully supported. Users
+building from source can enable the LLVM backend following the instruction in
+the dedicated section below and installing LLVM version 18. To install it on
+macOS, you can use [homebrew](https://brew.sh/): `brew install llvm@18`.
+
+
 ### Windows
 
-Windows is fully supported by Wasmer. WASI is also fully supported.
+Windows is fully supported by Wasmer. WASI(x) is also fully supported.
 
 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 [Git for Windows](https://git-scm.com/download/win). Allow it to add `git.exe` to your PATH (default settings for the installer are fine).
-4. \(optional\) Install [LLVM 11.0](https://prereleases.llvm.org/win-snapshots/LLVM-11.0.0-2663a25f-win64.exe)
+4. \(optional\) Install [LLVM 18.0](https://github.com/llvm/llvm-project/releases/download/llvmorg-18.1.7/LLVM-18.1.7-win64.exe)
+
 
 ## Building the Wasmer Runtime
 
@@ -35,41 +52,53 @@ git clone https://github.com/wasmerio/wasmer.git
 cd wasmer
 ```
 
-Wasmer supports three different compilers at the moment:
+Wasmer supports six different backends at the moment: `singlepass`,
+`cranelift`, `LLVM`, `V8`, `wasmi` and `wamr`.
 
 ### Singlepass Compiler
 
-Build Wasmer:
+The Singlepass compiler works on Linux, Darwin and Windows systems on amd64
+platforms and on Linux and Darwin systems on aarch64 platforms. Currently, it
+doesn't work on `RISC-V` or `loongarch64`. On system in which it can be used it
+is enabled by default.
+
+You can build Wasmer by running this command in the root of the repo:
 
 ```text
 make build-wasmer
 ```
 
-**Note**: you should see this `Enabled Compilers: singlepass` in console. 
+**Note**: you should see `singlepass` appear in the `Enabled Compilers: ...` message in the console. 
 
-You may disable Singlepass compiler with `export ENABLE_SINGLEPASS=0`.
+You may disable the Singlepass backend with the `ENABLE_SINGLEPASS=0` environment
+variable, and force its enabling with `ENABLE_SINGLEPASS=1`.
 
 ### Cranelift Compiler
 
-The Cranelift compiler will work if you are on a X86 or ARM machine. It will be detected automatically, so you don't need to do anything to your system to enable it.
+The Cranelift compiler will work if you are on a X86 or ARM machine. On system
+in which it can be used it is enabled by default.
+
+You can build Wasmer by running this command in the root of the repo:
 
 ```text
 make build-wasmer
 ```
 
-**Note**: should see this as the first line in the console:  
-`Enabled Compilers: cranelift`
+**Note**: you should see `cranelift` appear in the `Enabled Compilers: ...` message in the console. 
 
-You may disable the Cranelift compiler with `export ENABLE_CRANELIFT=0`.
+You may disable the Cranelift backend with the `ENABLE_SINGLEPASS=0` environment
+variable, and force its enabling with `ENABLE_SINGLEPASS=1`.
 
 ### LLVM Compiler
 
-If you want support for the Wasmer LLVM compiler, then you will also need to ensure:
+If you want support for the Wasmer LLVM compiler, then you will also need to:
 
-* Ensure that LLVM 10.0.x &gt; is installed on your system
+* Ensure that LLVM >=18.0.x  is installed on your system
   * You can refer to [LLVM install instructions](https://github.com/wasmerio/wasmer/tree/master/lib/compiler-llvm#requirements)
   * You can also [download and use a prebuilt LLVM binary](https://releases.llvm.org/download.html)
-* In case `llvm-config` is not accessible, set the correct environment variable for LLVM to access: For example, the environment variable for LLVM 11.0.x would be: `LLVM_SYS_110_PREFIX=/path/to/unpacked/llvm-11.0`
+* In case `llvm-config` is not accessible, set the correct environment variable
+  for LLVM to access: For example, the environment variable for LLVM 18.0.x
+  would be: `LLVM_SYS_180_PREFIX=/path/to/unpacked/llvm-18.0`
 
 And create a Wasmer release
 
@@ -82,6 +111,19 @@ make build-wasmer
 
 You may disable the LLVM compiler with `export ENABLE_LLVM=0`.
 
+### V8, wasmi and wamr 
+To enable any of these backends, you can set the according `ENABLE_<backend>=1`
+flag at build time. The build script itself will download the necessary
+libraries at build time.
+
+Note, however, that these backends are not supported on all the platforms that
+Wasmer can run on.
+
+For example, to have a Wasmer build with all three backends enabled you can run: 
+```text
+ENABLE_V8=1 ENABLE_WASMI=1 ENABLE_WAMR=1 make build-wasmer
+```
+
 ### All compilers
 
 Once you have LLVM and Rust, you can just run:

diff --git a/docs/cn/README.md b/docs/cn/README.md
@@ -5,7 +5,7 @@
 
   <p>
     <a href="https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild">
-      <img src="https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?event=push" alt="Build Status">
+      <img src="https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square" alt="Build Status">
     </a>
     <a href="https://github.com/wasmerio/wasmer/blob/main/LICENSE">
       <img src="https://img.shields.io/github/license/wasmerio/wasmer.svg" alt="License">

diff --git a/docs/de/README.md b/docs/de/README.md
@@ -5,7 +5,7 @@
 
   <p>
     <a href="https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild">
-      <img src="https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square" alt="Build Status">
+      <img src="https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square" alt="Build Status">
     </a>
     <a href="https://github.com/wasmerio/wasmer/blob/main/LICENSE">
       <img src="https://img.shields.io/github/license/wasmerio/wasmer.svg" alt="Lizenz">

diff --git a/docs/es/README.md b/docs/es/README.md
@@ -5,7 +5,7 @@
 
   <p>
     <a href="https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild">
-      <img src="https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square" alt="Build Status">
+      <img src="https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square" alt="Build Status">
     </a>
     <a href="https://github.com/wasmerio/wasmer/blob/main/LICENSE">
       <img src="https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square" alt="License">

diff --git a/docs/ko/README.md b/docs/ko/README.md
@@ -5,7 +5,7 @@
 
   <p>
     <a href="https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild">
-      <img src="https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square" alt="Build Status">
+      <img src="https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square" alt="Build Status">
     </a>
     <a href="https://github.com/wasmerio/wasmer/blob/main/LICENSE">
       <img src="https://img.shields.io/github/license/wasmerio/wasmer.svg" alt="License">

diff --git a/lib/api/README.md b/lib/api/README.md
@@ -1,4 +1,4 @@
-# `wasmer` [![Build Status](https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE) [![crates.io](https://img.shields.io/crates/v/wasmer.svg)](https://crates.io/crates/wasmer)
+# `wasmer` [![Build Status](https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE) [![crates.io](https://img.shields.io/crates/v/wasmer.svg)](https://crates.io/crates/wasmer)
 
 [`Wasmer`](https://wasmer.io/) is the most popular
 [WebAssembly](https://webassembly.org/) runtime for Rust. It supports JIT (Just

diff --git a/lib/c-api/README.md b/lib/c-api/README.md
@@ -1,4 +1,4 @@
-# `wasmer-c-api` [![Build Status](https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE)
+# `wasmer-c-api` [![Build Status](https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE)
 
 This crate exposes a C and a C++ API for the Wasmer runtime. It also fully supports the [wasm-c-api common API](https://github.com/WebAssembly/wasm-c-api).
 

diff --git a/lib/cli-compiler/README.md b/lib/cli-compiler/README.md
@@ -1,4 +1,5 @@
-# `wasmer-cli-compiler` [![Build Status](https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE)
+# `wasmer-cli-compiler` 
+[![Build Status](https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE)
 
 This crate is the Wasmer Compiler only CLI.
 

diff --git a/lib/cli/README.md b/lib/cli/README.md
@@ -1,4 +1,4 @@
-# `wasmer-cli` [![Build Status](https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE)
+# `wasmer-cli` [![Build Status](https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE)
 
 This crate is the Wasmer CLI.
 

diff --git a/lib/compiler-cranelift/README.md b/lib/compiler-cranelift/README.md
@@ -1,4 +1,4 @@
-# `wasmer-compiler-cranelift` [![Build Status](https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE) [![crates.io](https://img.shields.io/crates/v/wasmer-compiler-cranelift.svg)](https://crates.io/crates/wasmer-compiler-cranelift)
+# `wasmer-compiler-cranelift` [![Build Status](https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE) [![crates.io](https://img.shields.io/crates/v/wasmer-compiler-cranelift.svg)](https://crates.io/crates/wasmer-compiler-cranelift)
 
 This crate contains a compiler implementation based on Cranelift.
 

diff --git a/lib/compiler-llvm/README.md b/lib/compiler-llvm/README.md
@@ -1,4 +1,4 @@
-# `wasmer-compiler-llvm` [![Build Status](https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE) [![crates.io](https://img.shields.io/crates/v/wasmer-compiler-llvm.svg)](https://crates.io/crates/wasmer-compiler-llvm)
+# `wasmer-compiler-llvm` [![Build Status](https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE) [![crates.io](https://img.shields.io/crates/v/wasmer-compiler-llvm.svg)](https://crates.io/crates/wasmer-compiler-llvm)
 
 This crate contains a compiler implementation based on [the LLVM Compiler Infrastructure][LLVM].
 
@@ -23,20 +23,20 @@ to native speeds.
 ## Requirements
 
 The LLVM compiler requires a valid installation of LLVM in your system.
-It currently requires **LLVM 15**.
+It currently requires **LLVM 18**.
 
 
 You can install LLVM easily on your Debian-like system via this command:
 
 ```bash
 wget https://apt.llvm.org/llvm.sh -O /tmp/llvm.sh
-sudo bash /tmp/llvm.sh 15
+sudo bash /tmp/llvm.sh 18
 ```
 
 Or in macOS:
 
 ```bash
-brew install llvm@15
+brew install llvm@18
 ```
 
 Or via any of the [pre-built binaries that LLVM offers][llvm-pre-built].

diff --git a/lib/compiler-singlepass/README.md b/lib/compiler-singlepass/README.md
@@ -1,4 +1,5 @@
-# `wasmer-compiler-singlepass` [![Build Status](https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE) [![crates.io](https://img.shields.io/crates/v/wasmer-compiler-singlepass.svg)](https://crates.io/crates/wasmer-compiler-singlepass)
+# `wasmer-compiler-singlepass` 
+[![Build Status](https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE) [![crates.io](https://img.shields.io/crates/v/wasmer-compiler-singlepass.svg)](https://crates.io/crates/wasmer-compiler-singlepass)
 
 This crate contains a compiler implementation based on the Singlepass linear compiler.
 

diff --git a/lib/compiler/README.md b/lib/compiler/README.md
@@ -1,4 +1,4 @@
-# `wasmer-compiler` [![Build Status](https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE)
+# `wasmer-compiler` [![Build Status](https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE)
 
 This crate is the base for Compiler implementations.
 

diff --git a/lib/vm/README.md b/lib/vm/README.md
@@ -1,4 +1,4 @@
-# `wasmer-vm` [![Build Status](https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE)
+# `wasmer-vm` [![Build Status](https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE)
 
 This crate contains the Wasmer VM runtime library, supporting the Wasm ABI used by wasmer.
 

diff --git a/lib/wasix/README.md b/lib/wasix/README.md
@@ -1,4 +1,4 @@
-# `wasmer-wasi` [![Build Status](https://github.com/wasmerio/wasmer/workflows/build/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE) [![crates.io](https://img.shields.io/crates/v/wasmer-wasi.svg)](https://crates.io/crates/wasmer-wasi)
+# `wasmer-wasi` [![Build Status](https://github.com/wasmerio/wasmer/actions/workflows/build.yml/badge.svg?style=flat-square)](https://github.com/wasmerio/wasmer/actions?query=workflow%3Abuild) [![Join Wasmer Slack](https://img.shields.io/static/v1?label=Slack&message=join%20chat&color=brighgreen&style=flat-square)](https://slack.wasmer.io) [![MIT License](https://img.shields.io/github/license/wasmerio/wasmer.svg?style=flat-square)](https://github.com/wasmerio/wasmer/blob/main/LICENSE) [![crates.io](https://img.shields.io/crates/v/wasmer-wasi.svg)](https://crates.io/crates/wasmer-wasi)
 
 This crate provides the necessary imports to use WASI easily from Wasmer.
 [WebAssembly System Interface](https://github.com/WebAssembly/WASI)