Merge wasmerio#2365

2365: doc: Improve `README.md` r=Hywan a=Hywan

# Description

This PR improves our `README.md`.

* The “main” one has a better description of what Wasmer is by giving the keywords in the first sentence. It also lists more way to install Wasmer CLI. It removes the use of `<quote />` to indicate a note, it's semantically invalid. It explains super quickly the notion of compilers and engines by using the words “compilation strategies” and “artifact strategies”. It fixes various links. And more.
* It adds a `README.md` to the following directories:
  * `assets/`
  * `benches/`
   * `docs/`
  * `lib/`
* It improves the `README.md` of the following directories:
  * `fuzz/`


Co-authored-by: Ivan Enderlin <[email protected]>

Makefile

@@ -364,18 +364,19 @@ $(info )
 # Building #
 ############
 
-# Not really "all", just the default target that builds enough so make install will go through
+# Not really "all", just the default target that builds enough so make
+# install will go through.
 all: build-wasmer build-capi
 
-bench:
-	cargo bench $(compiler_features)
-
 build-wasmer:
 	cargo build --release --manifest-path lib/cli/Cargo.toml $(compiler_features) --bin wasmer
 
 build-wasmer-debug:
 	cargo build --manifest-path lib/cli/Cargo.toml $(compiler_features) --bin wasmer
 
+bench:
+	cargo bench $(compiler_features)
+
 # For best results ensure the release profile looks like the following
 # in Cargo.toml:
 # [profile.release]

PACKAGING.md

@@ -1,18 +1,46 @@
-## Wasmer distro packaging notes
-
-* Where possible, do not directly invoke cargo, but use the supplied Makefile
-	* wasmer has several compiler backends and the Makefile autodetects whether to enable llvm and singlepass.
-	  Set `ENABLE_{CRANELIFT,LLVM,SINGLEPASS}=1` to build the full set or fail trying
-	* Set `WASMER_CAPI_USE_SYSTEM_LIBFFI=1` to force dynamic linking of libffi on the shared library
-	* `make install` respects `DESTDIR`, but `prefix` must be configured as e.g. `WASMER_INSTALL_PREFIX=/usr make all`
-* In case you must build/install directly with cargo, make sure to enable at least one compiler backend feature
-  * Beware that compiling with `cargo build --workspace/--all --features ...` will not enable features on the subcrates in the workspace and result in a headless wasmer binary that can not run wasm files directly.
-* If you split the package into several subpackages, beware that the create-exe command of wasmer requires `libwasmer.a` to be installed at `$WASMER_INSTALL_PREFIX/lib/libwasmer.a`.
-  Suggestion for splitting:
-  * `wasmer` and `wasmer-headless`, containing the respective executables
-    * `wasmer-headless` contains a subset of `wasmer`'s functionality and should only be packaged when splitting - it must be built explicitly with `make build-wasmer-headless-minimal install-wasmer-headless-minimal`
-  * `libwasmer`, containing `libwasmer.so*`
-  * `libwasmer-dev`, containing the header files and a `.pc` file
-  * `libwasmer-static`, containing `libwasmer.a`
-
-The wasmer distro packaging story is still in its infancy, so feedback is very welcome.
+# Wasmer OS distro packaging notes
+
+* Wasmer is written in Rust. To build Wasmer, where possible, do not
+  directly invoke `cargo`, but use the supplied `Makefile`
+
+* Wasmer provides several compilers and the `Makefile` autodetects
+  when compilers can be compiled and/or installed. Set the environment
+  variables `ENABLE_{CRANELIFT,LLVM,SINGLEPASS}=1` to force compiler
+  to be build or to fail trying, e.g:
+
+  ```sh
+  $ ENABLE_LLVM=1 make build-wasmer
+  ```
+
+* `make install` respects `DESTDIR`, but `prefix` must be configured
+  with `WASMER_INSTALL_PREFIX`, e.g.:
+
+  ```sh
+  $ WASMER_INSTALL_PREFIX=/usr make install
+  ```
+
+* In case you must build/install directly with `cargo`, make sure to
+  enable at least one compiler feature, like e.g. `--features
+  cranelift`,
+
+  * Beware that compiling with `cargo build --workspace --features …`
+    will not enable features on the subcrates in the workspace and
+    result in a headless Wasmer binary that can not compile Wasm files
+    directly.
+
+* If you split the package into several subpackages, beware that the
+  `create-exe` command of the `wasmer` CLI requires `libwasmer.a` to
+  be installed at `$WASMER_INSTALL_PREFIX/lib/libwasmer.a`. Suggestions for splitting:
+
+  * The `wasmer-headless` CLI contains a subset of the `wasmer`'s functionalities
+    and should only be packaged when splitting — it must be built
+    explicitly with:
+
+    ```sh
+    $ make build-wasmer-headless-minimal install-wasmer-headless-minimal
+    ```
+  * `libwasmer`, containing `libwasmer.so*`,
+  * `libwasmer-dev`, containing the header files and a `.pc` file,
+  * `libwasmer-static`, containing `libwasmer.a`.
+
+The Wasmer distro packaging story is still in its infancy, so feedback is very welcome.