Add troubleshooting section

src/SUMMARY.md

@@ -7,6 +7,7 @@
   - [Comparing `std` and `no_std`](./overview/comparing-std-and-no_std.md)
 - [Rust on ESP targets](./installation/index.md)
   - [Installation](./installation/installation.md)
+  - [Troubleshooting](./installation/troubleshooting.md)
 - [Tooling](./tooling/index.md)
   - [Text Editors and IDEs](./tooling/text-editors-and-ides.md)
   - [espflash](./tooling/espflash.md)

src/installation/troubleshooting.md

@@ -0,0 +1,80 @@
+# Troubleshooting
+
+Here, we will present a list of common errors that may appear when building a project alongside the reason and a solution to them.
+
+## Environment variable LIBCLANG_PATH not set
+```sh
+thread 'main' panicked at 'Unable to find libclang: "couldn't find any valid shared libraries matching: ['libclang.so', 'libclang-*.so', 'libclang.so.*', 'libclang-*.so.*'], set the `LIBCLANG_PATH` environment variable to a path where one of these files can be found (invalid: [])"', /home/esp/.cargo/registry/src/github.com-1ecc6299db9ec823/bindgen-0.60.1/src/lib.rs:2172:31
+```
+We need `libclang` for [`bindgen`] to generate the Rust bindings to the ESP-IDF C headers.
+Make sure the environment variable `LIBCLANG_PATH` is set and pointing to our custom fork of LLVM:
+- Unix:
+  ```sh
+  export $HOME/.espressif/tools/xtensa-esp32-elf-clang/esp-15.0.0-20221014-x86_64-unknown-linux-gnu/esp-clang/lib
+  ```
+- Windows:
+  ```powershell
+  $Env:LIBCLANG_PATH="%USERPROFILE%/.espressif/tools/xtensa-esp32-elf-clang/esp-15.0.0-20221014-x86_64-unknown-linux-gnu/esp-clang/bin/libclang.dll"
+  $Env:PATH+=";%USERPROFILE%/.espressif/tools/xtensa-esp32-elf-clang/esp-15.0.0-20221014-x86_64-unknown-linux-gnu/esp-clang/bin/"
+  ```
+
+[`bindgen`]: https://github.com/rust-lang/rust-bindgen
+## Missing `libtinfo.so.5`
+```sh
+thread 'main' panicked at 'Unable to find libclang: "the `libclang` shared library at /home/user/.espressif/tools/xtensa-esp32-elf-clang/esp-15.0.0-20221014-x86_64-unknown-linux-gnu/esp-clang/lib/libclang.so.15.0.0 could not be o
+pened: libtinfo.so.5: cannot open shared object file: No such file or directory"', /home/user/.cargo/registry/src/github.com-1ecc6299db9ec823/bindgen-0.60.1/src/lib.rs:2172:31
+```
+Our current version of LLVM, 15, requires `libtinfo.so.5`. This dependency will probably be removed in our future LLVM releases, but for the moment, please, make sure you have it installed:
+- Ubuntu/Debian: `sudo apt-get install libtinfo5`
+- Fedora: `sudo dnf install ncurses-compat-libs`
+- openSUSE: `sudo dnf install libncurses5`
+- Arch Linux: `sudo pacman -S ncurses5-compat-libs`
+
+
+## Missing `ldproxy`
+```sh
+error: linker `ldproxy` not found
+  |
+  = note: No such file or directory (os error 2)
+```
+
+If you are trying to build a `std` application [`ldproxy`] must be installed.
+```sh
+cargo install ldproxy
+```
+For more information, see [ldproxy section].
+
+[`ldproxy`]: https://github.com/esp-rs/embuild/tree/master/ldproxy
+[ldproxy section]: installation.md#ldproxy
+
+
+## Using wrong Rust toolchain
+```sh
+$ cargo build
+error: failed to run `rustc` to learn about target-specific information
+
+Caused by:
+  process didn't exit successfully: `rustc - --crate-name ___ --print=file-names --target xtensa-esp32-espidf --crate-type bin --crate-type rlib --crate-type dylib --crate-type cdylib --crate-type staticlib --crate-type proc-macro --print=sysroot --print=cfg` (exit status: 1)
+  --- stderr
+  error: Error loading target specification: Could not find specification for target "xtensa-esp32-espidf". Run `rustc --print target-list` for a list of built-in targets
+```
+
+If you are encountering the previous error or a similar one, you are probably not using the proper Rust toolchain, remember that [for Xtensa targets, you need to use Espressif Rust fork toolchain], there are several ways to do it:
+- A [toolchain override] shorthand used on the command-line: `cargo +esp`.
+- Set `RUSTUP_TOOLCHAIN` environment variable to `esp`.
+- Set a [directory override]: `rustup override set esp`
+- Add a [rust-toolchain.toml] file to you project:
+  ```toml
+  [toolchain]
+  channel = "esp"
+  ```
+- Set `esp` as [default toolchain].
+
+For more information on toolchain overriding, see the [Overrides chapter of The rustup book].
+
+[for Xtensa targets, you need to use Espressif Rust fork toolchain]: index.md#rust-in-xtensa-targets
+[toolchain override]: https://rust-lang.github.io/rustup/overrides.html#toolchain-override-shorthand
+[directory override]: https://rust-lang.github.io/rustup/overrides.html#directory-overrides
+[rust-toolchain.toml]: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file
+[default toolchain]: https://rust-lang.github.io/rustup/overrides.html#default-toolchain
+[Overrides chapter of The rustup book]: https://rust-lang.github.io/rustup/overrides.html#overrides