From 7097e74c04e39dadd4796f98c2836c67e3bf94bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C4=B0brahim=20Sait=20Akar=C3=A7e=C5=9Fme?=
 <72226290+saitakarcesme@users.noreply.github.com>
Date: Tue, 22 Sep 2026 00:17:14 +0200
Subject: [PATCH] Document header dependencies for source distributions

---
 doc/source/cdef.rst     | 13 ++++++++++++-
 doc/source/overview.rst |  2 ++
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/doc/source/cdef.rst b/doc/source/cdef.rst
index 7ea06c70..e7fb73c6 100644
--- a/doc/source/cdef.rst
+++ b/doc/source/cdef.rst
@@ -353,7 +353,7 @@ code.
 
 The keywords arguments to ``set_source()`` control how the C compiler
 will be called.  They are passed directly to distutils_ or setuptools_
-and include at least ``sources``, ``include_dirs``, ``define_macros``,
+and include at least ``sources``, ``depends``, ``include_dirs``, ``define_macros``,
 ``undef_macros``, ``libraries``, ``library_dirs``, ``extra_objects``,
 ``extra_compile_args`` and ``extra_link_args``.  You typically need at
 least ``libraries=['foo']`` in order to link with ``libfoo.so`` or
@@ -367,6 +367,17 @@ first argument to ``sources``).  See the distutils documentation for
 .. _distutils: http://docs.python.org/3.11/distutils/setupscript.html#describing-extension-modules
 .. _setuptools: https://setuptools.pypa.io/
 
+If your C sources include project-local header files, list those files in
+``depends``, for example ``depends=['pi.h']``.  Setuptools uses this list
+both to detect when an extension needs rebuilding and to include the files
+in a source distribution.  Use paths relative to the project root.
+``include_dirs`` only tells the compiler where to search for headers; it
+does not add those headers to the source distribution.  Without them, a
+wheel built from the source distribution (as done by ``python -m build``)
+can fail even if compilation from the working tree succeeds.  List the
+headers themselves, including any project-local headers they include;
+``depends`` does not recursively discover ``#include`` dependencies.
+
 An extra keyword argument processed internally is
 ``source_extension``, defaulting to ``".c"``.  The file generated will
 be actually called ``module_name + source_extension``.  Example for
diff --git a/doc/source/overview.rst b/doc/source/overview.rst
index 44a86046..6ae2bd73 100644
--- a/doc/source/overview.rst
+++ b/doc/source/overview.rst
@@ -343,6 +343,8 @@ the C extension:
           #include "pi.h"
       """,
           sources=['pi.c'],   # includes pi.c as additional sources
+          depends=['pi.h'],   # includes pi.h in source distributions
+          include_dirs=['.'], # lets the compiler find pi.h
           libraries=['m'])    # on Unix, link with the math library
 
       if __name__ == "__main__":