Make the libdw dependency of C++ backtraces optional

README.md

@@ -27,7 +27,7 @@ DeepJIT handles the JIT infrastructure so that kernel libraries can focus on the
 | **CUDA** | NVCC compiles CUDA source to CUBIN; the CUDA Driver API loads and launches kernels. | CUDA headers 12.4+, NVCC 12.9+, and PyTorch with CUDA support. |
 | **Ascend** | Bisheng and ld.lld compile and link Ascend kernel source; ACL loads and launches kernels. | CANN with `bin/bisheng`, `bin/ld.lld`, and the Ascend `adv_api` headers; ACL and `torch_npu` headers and runtime. |
 
-The host environment must provide Linux, a C++20 compiler and standard library with `std::format` support, and the dependencies for the selected backend. The default GIL support also requires Python and pybind11; consumers that manage the GIL themselves can disable it as described under [Integration](#integration). DeepJIT is intended to be embedded into your extension as a header-only dependency. CUDA consumers should compile with `TORCH_TARGET_VERSION=0x020a000000000000` and `USE_CUDA`; this targets PyTorch's stable ABI with PyTorch 2.10 as the minimum runtime version.
+The host environment must provide Linux, a C++20 compiler and standard library with `std::format` support, and the dependencies for the selected backend. The default GIL support also requires Python and pybind11; consumers that manage the GIL themselves can disable it as described under [Integration](#integration). Installing the elfutils development headers (`libdw-dev` on Debian/Ubuntu) additionally enables file and line information in C++ backtraces; without them backtraces keep function names only. DeepJIT is intended to be embedded into your extension as a header-only dependency. CUDA consumers should compile with `TORCH_TARGET_VERSION=0x020a000000000000` and `USE_CUDA`; this targets PyTorch's stable ABI with PyTorch 2.10 as the minimum runtime version.
 
 See [Integration](#integration) for setup, [CUDA](#cuda) for GPU usage, and [Ascend](#ascend) for NPU usage.
 

include/deep_jit/utils/exception.hpp

@@ -1,6 +1,11 @@
 #pragma once
 
-#include <elfutils/libdwfl.h>
+#if defined(__has_include)
+#    if __has_include(<elfutils/libdwfl.h>)
+#        include <elfutils/libdwfl.h>
+#        define DJ_HAS_LIBDW 1
+#    endif
+#endif
 
 #include <array>
 #include <cstdint>
@@ -18,6 +23,8 @@ namespace deep_jit::exception {
 
 namespace detail {
 
+#ifdef DJ_HAS_LIBDW
+
 struct DwflApi {
     struct FrameInfo {
         const char* function = nullptr;
@@ -96,6 +103,25 @@ struct DwflApi {
     }
 };
 
+#else
+
+// `libdw` headers are unavailable at build time. Backtraces fall back to
+// `dladdr` only: they keep demangled function names but report "??:0" for the
+// file and line of each frame. Install the elfutils development headers to
+// restore them.
+struct DwflApi {
+    struct FrameInfo {
+        const char* function = nullptr;
+        std::string file_line = "??:0";
+    };
+
+    bool valid() const { return false; }
+    void refresh() const {}
+    FrameInfo find(const std::uintptr_t) const { return {}; }
+};
+
+#endif
+
 inline bool is_python_frame(const Dl_info& info) {
     if (info.dli_sname != nullptr) {
         const std::string_view symbol(info.dli_sname);