diff --git a/README.md b/README.md index fe3f551..21b7618 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ 这里是 https://github.com/esp-rs/book 的简体中文翻译 -目前进度:正在施工。跟踪到 139c00e +目前进度:已经翻译完成,跟踪到 139c00e --- diff --git a/src/misc/troubleshooting.md b/src/misc/troubleshooting.md index 8ef56d7..f42add5 100644 --- a/src/misc/troubleshooting.md +++ b/src/misc/troubleshooting.md @@ -1,20 +1,20 @@ # 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 +## 未设置 `LIBCLANG_PATH` 环境变量 ```text 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 you have sourced the export file generated by `espup`, see [Set up the environment variables][set-up-the-environment-variables]. +我们需要 `libclang` 来让 [`bindgen`] 生成 ESP-IDF C 头文件到 Rust 的绑定。 +确保你已经 source 了 `espup` 生成的 export 文件,请参阅[配置环境变量][set-up-the-environment-variables]。 [`bindgen`]: https://github.com/rust-lang/rust-bindgen -[set-up-the-environment-variables]: ./../installation/riscv-and-xtensa.md#3-set-up-the-environment-variables +[set-up-the-environment-variables]: ./../installation/riscv-and-xtensa.md#3-配置环境变量 -## Missing `ldproxy` +## 缺少 `ldproxy` ```shell error: linker `ldproxy` not found @@ -22,7 +22,7 @@ error: linker `ldproxy` not found = note: No such file or directory (os error 2) ``` -If you are trying to build a `std` application [`ldproxy`][ldproxy] must be installed. See [`std` Development Requirements][rust-esp-book-std-requirements] +要构建 `std` 应用,必须安装 [`ldproxy`][ldproxy]。请参阅 [`std` 开发依赖项][rust-esp-book-std-requirements] ```shell cargo install ldproxy @@ -31,7 +31,7 @@ cargo install ldproxy [ldproxy]: https://github.com/esp-rs/embuild/tree/master/ldproxy [rust-esp-book-std-requirements]: ./../installation/std-requirements.md -## Using the Wrong Rust Toolchain +## 使用了错误的 Rust 工具链 ```text $ cargo build @@ -43,18 +43,18 @@ Caused by: 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][toolchain-override] shorthand used on the command-line: `cargo +esp`. -- Set `RUSTUP_TOOLCHAIN` environment variable to `esp`. -- Set a [directory override][directory-override]: `rustup override set esp` -- Add a [`rust-toolchain.toml`][rust-toolchain-toml] file to you project: +如果遇到了上面的错误,或类似的错误,可能是因为没有使用合适的 Rust 工具链。注意:对于 `Xtensa` 目标,需要使用乐鑫分支的 Rust 工具链,有这几种方法: +- 在命令行中使用[工具链 override][toolchain-override] 简写: `cargo +esp`。 +- 将 `RUSTUP_TOOLCHAIN` 环境变量设置为 `esp`。 +- 设置[目录 override][directory-override]:`rustup override set esp` +- 在项目中添加 [`rust-toolchain.toml`][rust-toolchain-toml] 文件: ```toml [toolchain] channel = "esp" ``` -- Set `esp` as [default toolchain][default-toolchain]. +- 将 `esp` 设置为[默认工具链][default-toolchain]。 -For more information on toolchain overriding, see the [Overrides chapter][overrides-rust-book] of The rustup book. +关于工具链 override 的更多信息,请参阅 The rustup book 的 [Overrides chapter][overrides-rust-book] 章节。 [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 @@ -64,15 +64,15 @@ For more information on toolchain overriding, see the [Overrides chapter][overri ## Windows -### Long Path Names +### 长路径名 -When using Windows, you may encounter issues building a new project if using long path names. Follow these steps to substitute the path of your project: +使用 Windows 时,如果使用了长路径名,你可能会在构建新项目时遇到问题。请按照以下步骤替换项目的路径: ```powershell -subst r: +subst r: <你的项目的路径> cd r:\ ``` -### Missing ABI +### 缺失 ABI ```powershell Compiling cc v1.0.69 @@ -89,8 +89,8 @@ warning: build failed, waiting for other jobs to finish... error: build failed ``` -The reason for this error is that we are missing the MSVC C++, hence we aren't meeting the [Compile-time Requirements]. Please, install [Visual Studio 2013 (or later) or the Visual C++ Build Tools 2019]. For Visual Studio, make sure to check the "C++ tools" and "Windows 10 SDK" options. -If using GNU ABI, install [MinGW/MSYS2 toolchain]. +出现此错误的原因是我们缺少 MSVC C++,因此不满足[编译时要求][Compile-time Requirements]。请安装 [Visual Studio 2013(或更高版本)或 Visual C++ Build Tools 2019][Visual Studio 2013 (or later) or the Visual C++ Build Tools 2019]。对于 Visual Studio,确保选择了 “C++ tools” 和 “Windows 10 SDK” 选项。 +如果使用 GNU ABI,请安装 [MinGW/MSYS2 工具链][MinGW/MSYS2 toolchain]。 [Compile-time Requirements]: https://github.com/rust-lang/cc-rs#compile-time-requirements [Visual Studio 2013 (or later) or the Visual C++ Build Tools 2019]: https://rust-lang.github.io/rustup/installation/windows.html @@ -98,24 +98,24 @@ If using GNU ABI, install [MinGW/MSYS2 toolchain]. ## FAQ -### `sdkconfig.defaults` File is Updated but it Doesn't Appear to Have Had Any Effect +### 更新了 `sdkconfig.defaults` 文件,但没有任何效果 -You must clean your project and rebuild for changes in the `sdkconfig.defaults` to take effect: +必须清理并重新构建项目,才能使 `sdkconfig.defaults` 中的修改生效: ```shell cargo clean cargo build ``` -### The Documentation for the Crates Mentioned on This Page is out of Date or Missing +### 本页提到的 crate 的文档已过时或丢失 -Due to the [resource limits] imposed by [docs.rs], internet access is blocked while building documentation. For this reason, we are unable to build the documentation for `esp-idf-sys` or any crate depending on it. +由于 [docs.rs] 施加的[资源限制][resource limits],构建文档时不允许访问互联网。因此,我们无法构建 `esp-idf-sys` 或任何依赖于它的 crate 的文档。 -Instead, we are building the documentation and hosting it ourselves on GitHub Pages: +作为替代,我们构建了文档,并将其托管在 GitHub Pages 上: -- [`esp-idf-hal` Documentation] -- [`esp-idf-svc` Documentation] -- [`esp-idf-sys` Documentation] +- [`esp-idf-hal` 文档][`esp-idf-hal` documentation] +- [`esp-idf-svc` 文档][`esp-idf-svc` documentation] +- [`esp-idf-sys` 文档][`esp-idf-sys` documentation] [resource limits]: https://docs.rs/about/builds#hitting-resource-limits [docs.rs]: https://docs.rs @@ -123,23 +123,23 @@ Instead, we are building the documentation and hosting it ourselves on GitHub Pa [`esp-idf-svc` documentation]: https://esp-rs.github.io/esp-idf-svc/esp_idf_svc/ [`esp-idf-sys` documentation]: https://esp-rs.github.io/esp-idf-sys/esp_idf_sys/ -### A Stack Overflow in Task `main` has Been Detected +### A Stack Overflow in Task `main` has Been Detected(`main` 任务栈溢出) -If the second-stage bootloader reports this error, you likely need to increase the stack size for the main task. This can be accomplished by adding the following to the `sdkconfig.defaults` file: +如果第二阶段 bootloader 报告了这个错误,你可能需要增加 main 任务的栈大小。可以通过将以下内容添加到 `sdkconfig.defaults` 文件来实现: ```text CONFIG_ESP_MAIN_TASK_STACK_SIZE=7000 ``` -In this example, we are allocating 7 kB for the main task's stack. +在本例中,我们为 main 任务的栈分配了 7 kB。 -### How to Disable Watchdog Timer(s)? +### 如何关闭看门狗定时器? -Add to your `sdkconfig.defaults` file: +向 `sdkconfig.defaults` 文件添加: ```text CONFIG_INT_WDT=n CONFIG_ESP_TASK_WDT=n ``` -Recall that you must clean your project before rebuilding when modifying these configuration files. +请记住,修改了这些配置文件后,必须在重新构建之前清理项目。