-
Notifications
You must be signed in to change notification settings - Fork 53
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* feat: β¨ Add Troubleshooting chapter * docs: π Add LIBCLANG_PATH error * docs: π Add libtinfo.so.5 error * docs: π Add missing ldproxy error * docs: π Add using wrong toolchain * docs: π Fix typos * docs: π Add language to codeblocks * docs: π Fix link
- Loading branch information
1 parent
9c7c02b
commit 8edceb9
Showing
2 changed files
with
81 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |