Merge pull request #915 from IntersectMBO/mgalazyn/doc/add-troubleshooting-to-wasm-readme

Add troubleshooting to cardano-wasm README

Author: carbolymer

cardano-wasm/README.md

@@ -12,15 +12,15 @@ Enter the Nix shell by writing `nix develop .#wasm` on a shell in this folder an
 
 For the installation we will need some dependencies. In Debian based distros we can install them using apt like this:
 
-```console
+```bash
 sudo apt install happy pkgconf libtool git wget curl jq unzip zstd tar gzip
 ```
 
 #### Installing `ghc` for wasm
 
 Then it is necessary to get `ghc` for wasm, and you see how to do that [here](https://gitlab.haskell.org/haskell-wasm/ghc-wasm-meta#getting-started-without-nix). At the moment, it is necessary to install a version of `ghc` that has `base <= 4.20`, so I would recommend installing `wasm32-wasi-9.10` like this:
 
-```console
+```bash
 wget "https://gitlab.haskell.org/haskell-wasm/ghc-wasm-meta/-/archive/master/ghc-wasm-meta-master.tar.gz"
 tar -zxf ghc-wasm-meta-master.tar.gz
 cd ghc-wasm-meta-master
@@ -44,41 +44,41 @@ Then we need to compile three libraries to WASM: `libblst`, `libsodium`, and `li
 
 In order to not interfere with the system library installation, we will create a folder to serve as our prefix:
 
-```console
+```bash
 mkdir -p ~/prefix/{lib/pkgconfig,include}
 ```
 
 #### Installing `libblst`
 
 We can obtain `libblst` from GitHub [here](https://github.com/supranational/blst). So we can use `git` to get its source code:
 
-```console
+```bash
 git clone "https://github.com/supranational/blst.git"
 ```
 
 Then we get into the downloaded folder and we build it as follows:
 
-```console
+```bash
 cd blst
 ./build.sh
 ```
 
 And we copy the result and includes to our prefix as follows:
 
-```console
+```bash
 cp libblst.a ~/prefix/lib/
 cp bindings/{blst.h,blst_aux.h} ~/prefix/include/
 ```
 
 We generate a dynamic version of the library:
 
-```console
+```bash
 wasm32-wasi-clang -shared -Wl,--whole-archive ~/prefix/lib/libblst.a -o ~/prefix/lib/libblst.so
 ```
 
 And finally we write an entry for `pkgconfig`, so that later `ghc` can find our prefix:
 
-```
+```bash
 cat <<EOF > $HOME/prefix/lib/pkgconfig/libblst.pc
 prefix=$HOME/prefix
 exec_prefix=\${prefix}
@@ -98,21 +98,21 @@ EOF
 
 Finally we leave the folder:
 
-```console
+```bash
 cd ..
 ```
 
 #### Installing `libsodium`
 
 We can also obtain `libsodium` from its website [here](https://libsodium.org). We can use `wget` to get the source code for one of its releases. For example:
 
-```console
+```bash
 wget "https://download.libsodium.org/libsodium/releases/libsodium-1.0.20-stable.tar.gz"
 ```
 
 Then we extract it, get into the created folder and compile it as follows:
 
-```console
+```bash
 tar -zxf libsodium-1.0.20-stable.tar.gz
 cd libsodium-stable
 ./configure --host=wasm32-wasi --prefix=$HOME/prefix
@@ -122,7 +122,7 @@ make install
 
 Finally we generate a dynamic version of the library, and we leave the folder:
 
-```console
+```bash
 wasm32-wasi-clang -shared -Wl,--whole-archive ~/prefix/lib/libsodium.a -o ~/prefix/lib/libsodium.so
 cd ..
 ```
@@ -131,13 +131,13 @@ cd ..
 
 We can obtain `libsecp256k1 ` from GitHub [here](https://github.com/bitcoin-core/secp256k1). So we can use `git` to get its source code:
 
-```console
+```bash
 git clone "https://github.com/bitcoin-core/secp256k1.git"
 ```
 
 Then we get into the downloaded folder, and we build it as follows:
 
-```console
+```bash
 cd secp256k1
 ./autogen.sh
 ./configure --prefix=$HOME/prefix --host=wasm32-wasi --enable-module-schnorrsig SECP_CFLAGS=-fPIC
@@ -147,7 +147,7 @@ make install
 
 Finally we generate a dynamic version of the library, and we leave the folder:
 
-```console
+```bash
 wasm32-wasi-clang -shared -Wl,--whole-archive ~/prefix/lib/libsecp256k1.a -o  ~/prefix/lib/libsecp256k1.so
 cd ..
 ```
@@ -156,46 +156,46 @@ cd ..
 
 First we make sure we have `pkg-config` installed, in Debian based distros this can be done with apt:
 
-```console
+```bash
 sudo apt install pkgconf
 ```
 
 And we set the variable `PKG_CONFIG_PATH` to inform `pkg-config` of where the entries for wasm are stored:
 
-```console
+```bash
 export PKG_CONFIG_PATH=$HOME/prefix/lib/pkgconfig
 ```
 
 Then we get into the `cardano-wasm` subfolder of the clone of `cardano-api`.
 
-```console
+```bash
 cd cardano-api/cardano-wasm
 ```
 
 ### Compiling `cardano-wasm`
 
-Once we have the environment set up we can procede to build the wasm module as follows:
+Once we have the environment set up we can proceed to build the wasm module as follows:
 
-```console
+```bash
 wasm32-wasi-cabal update
-wasm32-wasi-cabal build
+wasm32-wasi-cabal build cardano-wasm
 ```
 
 That will generate the `wasm` module, and you can find where it was generated by using the following command:
 
-```console
+```bash
 echo "$(env -u CABAL_CONFIG wasm32-wasi-cabal list-bin exe:cardano-wasm | tail -n1)"
 ```
 
 And you can see the exported functions by using the following command:
 
-```console
+```bash
 wasm-dis "$(env -u CABAL_CONFIG wasm32-wasi-cabal list-bin exe:cardano-wasm | tail -n1)" | grep "export "
 ```
 
 To generate a post-link module with the exports you can write:
 
-```console
+```bash
 $(wasm32-wasi-ghc --print-libdir)/post-link.mjs -i "$(env -u CABAL_CONFIG wasm32-wasi-cabal list-bin exe:cardano-wasm | tail -n1)" -o cardano-wasm.js
 ```
 
@@ -205,6 +205,54 @@ You can find more information in [this url](https://ghc.gitlab.haskell.org/ghc/d
 
 And you can find an example of how to use it in the `example` subfolder. This example assumes that the generated `.wasm` and `.js` files as well as the files from the `lib-wrapper` subfolder, all reside in the same folder as the code in `example` subfolder.
 
+### Troubleshooting guide
+
+#### `Failed to load dynamic interface file for ...` GHC-47808 error
+
+When you're seeing an error similar to:
+```console
+[1 of 4] Compiling Data.Constraint.Compose ( src/Data/Constraint/Compose.hs, dist/build/Data/Constraint/Compose.o, dist/build/Data/Constraint/Compose.dyn_o )
+src/Data/Constraint/Compose.hs:14:1: error: [GHC-47808]
+    Failed to load dynamic interface file for Data.Constraint:
+      Exception when reading interface file  /home/mgalazyn/.local/share/cabal/store/ghc-9.10.1.20250327-inplace/constraints-0.14.2-7fc45a1b31889530ee7f295fd8bc8535f521e6eaac4bbc3cc5df34e174a5eacf/lib/Data/Constraint.dyn_hi
+        /home/mgalazyn/.local/share/cabal/store/ghc-9.10.1.20250327-inplace/constraints-0.14.2-7fc45a1b31889530ee7f295fd8bc8535f521e6eaac4bbc3cc5df34e174a5eacf/lib/Data/Constraint.dyn_hi: withBinaryFile: does not exist (No such file or directory)
+   |
+14 | import Data.Constraint
+   | ^^^^^^^^^^^^^^^^^^^^^^
+```
+
+Most likely the reason is that `cabal` store is polluted with non-wasm and/or nix and non-nix package information and `ghc-pkg` is unable to find the right dependencies.
+You can try to isolate `cabal` environment for WASM build from other builds.
+In other words, paths in `cabal path` command output should be different than for other builds.
+
+##### When using `nix`
+
+Try entering development shell in an isolated environment, and setting `$HOME` to a different directory, making `cabal` use different state directory.
+```bash
+nix develop -i .#wasm
+export HOME=`pwd`  # or some other path that you want cabal state in
+wasm32-wasi-cabal update
+wasm32-wasi-cabal build cardano-wasm
+```
+
+#### Cabal error Cabal-7125 `Failed to download ... The exception was: user error (https not supported)`
+
+This can happen when using `nix develop -i`. To work around that add to your `cabal.project.local`:
+
+```
+http-transport: curl
+```
+thus making `cabal` use `curl` for HTTP connections instead.
+
+#### Build is getting stuck at one of the dependencies
+
+It may happen that the build gets stuck on one of the dependencies, and if you check the CPU usage of the compiler process, you'll see a value close to 0.
+To work around that, disable build concurrency:
+
+```bash
+wasm32-wasi-cabal build cardano-wasm -j1 --ghc-options="-j1" --no-semaphore
+```
+
 ## Running the example
 
 To run the example in the `example` subfolder:
@@ -234,7 +282,7 @@ To run the example in the `example` subfolder:
            description: "Ledger Cddl Format", type: "Tx ConwayEra"} (test, line 20)
     ```
 
-## Running the GRPC example
+## Running the GRPC example
 
 To run the example in the `grpc-example` subfolder:
 

flake.nix

@@ -205,6 +205,7 @@
           lib.optionalAttrs (system != "x86_64-darwin") {
             wasm = wasm-pkgs.mkShell {
               packages = [
+                wasm-pkgs.curl
                 inputs.ghc-wasm-meta.packages.${system}.all_9_10
                 wasm-pkgs.pkg-config
                 wasm.libsodium