Document the new `CYTHON_EXTERN_C` macro (GH-5366)

See https://github.com/cython/cython/pull/5371

2 files changed, 30 insertions, 0 deletions

diff --git a/docs/src/userguide/external_C_code.rst b/docs/src/userguide/external_C_code.rst
index 28fb6bcae..6108d2cbf 100644
--- a/docs/src/userguide/external_C_code.rst
+++ b/docs/src/userguide/external_C_code.rst
@@ -496,6 +496,30 @@ file consists of the full dotted name of the module, e.g. a module called
     the resulting ``.so`` file like a dynamic library.
     Beware that this is not portable, so it should be avoided.
 
+C++ public declarations
+^^^^^^^^^^^^^^^^^^^^^^^
+
+When a file is compiled as C++, its public functions are declared as C++ API (using ``extern "C++"``) by default.
+This disallows to call the functions from C code.  If the functions are really meant as a plain C API,
+the ``extern`` declaration needs to be manually specified by the user.
+This can be done by setting the ``CYTHON_EXTERN_C`` C macro to ``extern "C"`` during the compilation of the generated C++ file::
+
+    from setuptools import Extension, setup
+    from Cython.Build import cythonize
+
+    extensions = [
+        Extension(
+            "module", ["module.pyx"],
+            define_macros=[("CYTHON_EXTERN_C", 'extern "C"')],
+            language="c++",
+        )
+    ]
+
+    setup(
+        name="My hello app",
+        ext_modules=cythonize(extensions),
+    )
+
 .. _api:
 
 C API Declarations
diff --git a/docs/src/userguide/migrating_to_cy30.rst b/docs/src/userguide/migrating_to_cy30.rst
index 3a3db5b97..e870f00e8 100644
--- a/docs/src/userguide/migrating_to_cy30.rst
+++ b/docs/src/userguide/migrating_to_cy30.rst
@@ -264,6 +264,12 @@ When running into an error it is required to add the corresponding operator::
         Example operator++(int)
         Example operator--(int)
 
+Public Declarations in C++
+==========================
+
+Public declarations in C++ mode are exported as C++ API in Cython 3, using ``extern "C++"``.
+This behaviour can be changed by setting the export keyword using the ``CYTHON_EXTERN_C`` macro
+to allow Cython modules to be implemented in C++ but callable from C.
 
 ``**`` power operator
 =====================