|
| 1 | +/* Macros that restrict available definitions and select implementations |
| 2 | + * to match an ABI stability promise: |
| 3 | + * |
| 4 | + * - internal API/ABI (may change at any time) -- Py_BUILD_CORE* |
| 5 | + * - general CPython API/ABI (may change in 3.x.0) -- default |
| 6 | + * - Stable ABI: abi3, abi3t (long-term stable) -- Py_LIMITED_API, |
| 7 | + * Py_TARGET_ABI3T, _Py_OPAQUE_PYOBJECT |
| 8 | + * - Free-threading (incompatible with non-free-threading builds) |
| 9 | + * -- Py_GIL_DISABLED |
| 10 | + */ |
| 11 | + |
| 12 | +#ifndef _Py_PYABI_H |
| 13 | +#define _Py_PYABI_H |
| 14 | + |
| 15 | +/* Defines to build Python and its standard library: |
| 16 | + * |
| 17 | + * - Py_BUILD_CORE: Build Python core. Gives access to Python internals; should |
| 18 | + * not be used by third-party modules. |
| 19 | + * - Py_BUILD_CORE_BUILTIN: Build a Python stdlib module as a built-in module. |
| 20 | + * - Py_BUILD_CORE_MODULE: Build a Python stdlib module as a dynamic library. |
| 21 | + * |
| 22 | + * Py_BUILD_CORE_BUILTIN and Py_BUILD_CORE_MODULE imply Py_BUILD_CORE. |
| 23 | + * |
| 24 | + * On Windows, Py_BUILD_CORE_MODULE exports "PyInit_xxx" symbol, whereas |
| 25 | + * Py_BUILD_CORE_BUILTIN does not. |
| 26 | + */ |
| 27 | +#if defined(Py_BUILD_CORE_BUILTIN) && !defined(Py_BUILD_CORE) |
| 28 | +# define Py_BUILD_CORE |
| 29 | +#endif |
| 30 | +#if defined(Py_BUILD_CORE_MODULE) && !defined(Py_BUILD_CORE) |
| 31 | +# define Py_BUILD_CORE |
| 32 | +#endif |
| 33 | + |
| 34 | +/* Check valid values for target ABI macros. |
| 35 | + */ |
| 36 | +#if defined(Py_LIMITED_API) && Py_LIMITED_API+0 < 3 |
| 37 | + // Empty Py_LIMITED_API used to work; redefine to |
| 38 | + // Python 3.2 to be explicit. |
| 39 | +# undef Py_LIMITED_API |
| 40 | +# define Py_LIMITED_API 0x03020000 |
| 41 | +#endif |
| 42 | +#if defined(Py_TARGET_ABI3T) && Py_TARGET_ABI3T+0 < 0x030f0000 |
| 43 | +# error "Py_TARGET_ABI3T must be 0x030f0000 (3.15) or above" |
| 44 | +#endif |
| 45 | + |
| 46 | +/* Stable ABI for free-threaded builds (abi3t, introduced in PEP 803) |
| 47 | + * is enabled by one of: |
| 48 | + * - Py_TARGET_ABI3T, or |
| 49 | + * - Py_LIMITED_API and Py_GIL_DISABLED. |
| 50 | + * |
| 51 | + * These affect set the following, which Python.h should use internally: |
| 52 | + * - Py_LIMITED_API (defines the subset of API we expose) |
| 53 | + * - _Py_OPAQUE_PYOBJECT (additionally hides what's ABI-incompatible between |
| 54 | + * free-threaded & GIL) |
| 55 | + * |
| 56 | + * (Don't use Py_TARGET_ABI3T directly. It's currently only used to set these |
| 57 | + * 2 macros, and defined for users' convenience.) |
| 58 | + */ |
| 59 | +#if defined(Py_LIMITED_API) && defined(Py_GIL_DISABLED) \ |
| 60 | + && !defined(Py_TARGET_ABI3T) |
| 61 | +# define Py_TARGET_ABI3T Py_LIMITED_API |
| 62 | +#endif |
| 63 | +#if defined(Py_TARGET_ABI3T) |
| 64 | +# define _Py_OPAQUE_PYOBJECT |
| 65 | +# if !defined(Py_LIMITED_API) |
| 66 | +# define Py_LIMITED_API Py_TARGET_ABI3T |
| 67 | +# elif Py_LIMITED_API > Py_TARGET_ABI3T |
| 68 | + // if both are defined, use the *lower* version, |
| 69 | + // i.e. maximum compatibility |
| 70 | +# undef Py_LIMITED_API |
| 71 | +# define Py_LIMITED_API Py_TARGET_ABI3T |
| 72 | +# endif |
| 73 | +#else |
| 74 | +# ifdef _Py_OPAQUE_PYOBJECT |
| 75 | + // _Py_OPAQUE_PYOBJECT is a private macro; do not define it directly. |
| 76 | +# error "Define Py_TARGET_ABI3T to target abi3t." |
| 77 | +# endif |
| 78 | +#endif |
| 79 | + |
| 80 | +#if defined(Py_TARGET_ABI3T) |
| 81 | +# if !defined(Py_GIL_DISABLED) |
| 82 | + // Define Py_GIL_DISABLED for users' needs. Users check this macro to see |
| 83 | + // whether they need extra synchronization. |
| 84 | +# define Py_GIL_DISABLED |
| 85 | +# endif |
| 86 | +# if defined(_Py_IS_TESTCEXT) |
| 87 | + // When compiling for abi3t, contents of Python.h should not depend |
| 88 | + // on Py_GIL_DISABLED. |
| 89 | + // We ask GCC to error if it sees the macro from this point on. |
| 90 | + // Since users are free to the macro, and there's no way to undo the |
| 91 | + // poisoning at the end of Python.h, we only do this in a test module |
| 92 | + // (test_cext). |
| 93 | + // |
| 94 | + // Clang's poisoning is stricter than GCC's: it looks in `#elif` |
| 95 | + // expressions after matching `#if`s. We disable it for now. |
| 96 | + // We also provide an undocumented, unsupported opt-out macro to help |
| 97 | + // porting to other compilers. Consider reaching out if you use it. |
| 98 | +# if defined(__GNUC__) && !defined(__clang__) && !defined(_Py_NO_GCC_POISON) |
| 99 | +# undef Py_GIL_DISABLED |
| 100 | +# pragma GCC poison Py_GIL_DISABLED |
| 101 | +# endif |
| 102 | +# endif |
| 103 | +#endif |
| 104 | + |
| 105 | +/* The internal C API must not be used with the limited C API: make sure |
| 106 | + * that Py_BUILD_CORE* macros are not defined in this case. |
| 107 | + * But, keep the "original" values, under different names, for "exports.h" |
| 108 | + */ |
| 109 | +#ifdef Py_BUILD_CORE |
| 110 | +# define _PyEXPORTS_CORE |
| 111 | +#endif |
| 112 | +#ifdef Py_BUILD_CORE_MODULE |
| 113 | +# define _PyEXPORTS_CORE_MODULE |
| 114 | +#endif |
| 115 | +#ifdef Py_LIMITED_API |
| 116 | +# undef Py_BUILD_CORE |
| 117 | +# undef Py_BUILD_CORE_BUILTIN |
| 118 | +# undef Py_BUILD_CORE_MODULE |
| 119 | +#endif |
| 120 | + |
| 121 | +#endif // _Py_PYABI_H |
0 commit comments