https://github.com/esp-rs/esp-idf-hal/issues/319

BUILD-OPTIONS.md

@@ -309,6 +309,21 @@ The following configuration options are available:
 
   The currently detected environment variables that might be problematic are as follows: `CC`, `CXX`, `CFLAGS`, `CCFLAGS`, `CXXFLAGS`, `CPPFLAGS`, `LDFLAGS`, `GCC_EXEC_PREFIX`, `COMPILER_PATH`, `C_INCLUDE_PATH`, `CPLUS_INCLUDE_PATH`.
 
+- ### *`esp_idf_espup_clang_symlink`*, `$ESP_IDF_ESPUP_CLANG_SYMLINK`
+
+  Background:
+
+  As part of installing the `esp` Rust toolchain, the `espup` utility - on Unix-like systems - configures a hidden symlink in its private folder that points to the Clang compiler library that is also distributed with the `esp` Rust toolchain (and which - just like the `esp` Rust toolchain itself - does support the `xtensa` architecture). 
+
+  Since `esp-idf-sys` uses `bindgen` to generate raw bindings for the C ESP IDF APIs, it needs to have the `LIBCLANG_PATH` env var configured to point to the CLang library.
+  
+  `esp-idf-sys` does this automatically, by using the symlink provided by `espup`.
+
+  Following options are available:
+  * `try` (default) - Check if the symlink is available and use it; continue the build expecting a user-defined `LIBCLANG_PATH` env var otherwise
+  * `warn` - Same as `try` but report a warning if the symlink is not available
+  * `err` - Fail the build if the symlink is not available or broken
+  * `ignore` - Do not use the symlink at all
 
 - ### *`esp_idf_component_manager`*, `$ESP_IDF_COMPONENT_MANAGER`
 

build/common.rs

@@ -451,3 +451,48 @@ pub fn sanitize_project_path() -> Result<()> {
 
     Ok(())
 }
+
+pub fn setup_clang_env() -> Result<()> {
+    const POLICY_VAR: &str = "ESP_IDF_ESPUP_CLANG_SYMLINK";
+    let policy = std::env::var(POLICY_VAR)
+        .ok()
+        .unwrap_or("try".into())
+        .to_lowercase();
+
+    if policy != "ignore" {
+        #[allow(deprecated)]
+        let espup_clang_path =
+            std::env::home_dir().map(|home| home.join(".espup").join("esp-clang"));
+
+        let err_msg = if let Some(espup_clang_path) = espup_clang_path {
+            if let Some(real_path) = std::fs::read_link(&espup_clang_path).ok() {
+                if real_path.is_dir() {
+                    std::env::set_var("LIBCLANG_PATH", real_path.as_os_str());
+                    None
+                } else {
+                    Some(format!(
+                        "Symlink {} points to a file",
+                        espup_clang_path.display()
+                    ))
+                }
+            } else {
+                Some(format!(
+                    "Symlink {} does not exist or points to a non-existing location",
+                    espup_clang_path.display()
+                ))
+            }
+        } else {
+            Some(format!("Cannot locate user home directory"))
+        };
+
+        if let Some(err_msg) = err_msg {
+            if policy == "warn" {
+                cargo::print_warning(format!("(esp-idf-sys) {err_msg}"));
+            } else if policy == "err" {
+                bail!(err_msg);
+            }
+        }
+    }
+
+    Ok(())
+}

build/native/cargo_driver.rs

@@ -20,8 +20,8 @@ use strum::IntoEnumIterator;
 use self::chip::Chip;
 use crate::common::{
     self, list_specific_sdkconfigs, manifest_dir, sanitize_c_env_vars, sanitize_project_path,
-    workspace_dir, EspIdfBuildOutput, EspIdfComponents, InstallDir, NO_PATCHES, V_4_3_2_PATCHES,
-    V_4_4_3_PATCHES, V_5_0_PATCHES,
+    setup_clang_env, workspace_dir, EspIdfBuildOutput, EspIdfComponents, InstallDir, NO_PATCHES,
+    V_4_3_2_PATCHES, V_4_4_3_PATCHES, V_5_0_PATCHES,
 };
 use crate::config::{BuildConfig, ESP_IDF_GLOB_VAR_PREFIX, ESP_IDF_TOOLS_INSTALL_DIR_VAR};
 
@@ -31,6 +31,7 @@ pub mod config;
 pub fn build() -> Result<EspIdfBuildOutput> {
     sanitize_project_path()?;
     sanitize_c_env_vars()?;
+    setup_clang_env()?;
 
     let out_dir = cargo::out_dir();
     let target = env::var("TARGET")?;

build/native/cmake_driver.rs

@@ -4,7 +4,7 @@ use std::{env, iter};
 use anyhow::{anyhow, Context, Result};
 use embuild::bindgen;
 
-use crate::common::{sanitize_project_path, EspIdfBuildOutput, EspIdfComponents};
+use crate::common::{sanitize_project_path, setup_clang_env, EspIdfBuildOutput, EspIdfComponents};
 
 pub const CARGO_CMAKE_BUILD_ACTIVE_VAR: &str = "CARGO_CMAKE_BUILD_ACTIVE";
 pub const CARGO_CMAKE_BUILD_INCLUDES_VAR: &str = "CARGO_CMAKE_BUILD_INCLUDES";
@@ -15,6 +15,7 @@ const CARGO_CMAKE_BUILD_ESP_IDF_VAR: &str = "CARGO_CMAKE_BUILD_ESP_IDF";
 
 pub fn build() -> Result<EspIdfBuildOutput> {
     sanitize_project_path()?;
+    setup_clang_env()?;
 
     let components = EspIdfComponents::from(
         env::var(CARGO_CMAKE_BUILD_LINK_LIBRARIES_VAR)?