From 4e47c1bc501df4ad185b4a65f45fe7c8045078a4 Mon Sep 17 00:00:00 2001 From: Nathan Goldbaum Date: Wed, 23 Oct 2024 10:29:01 -0600 Subject: [PATCH 1/4] Add example Cargo.toml and build.rs for exposing pyo3 cfgs --- pyo3-ffi/src/lib.rs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/pyo3-ffi/src/lib.rs b/pyo3-ffi/src/lib.rs index c6157401124..48028d53426 100644 --- a/pyo3-ffi/src/lib.rs +++ b/pyo3-ffi/src/lib.rs @@ -48,6 +48,22 @@ //! - `Py_LIMITED_API`: Marks code enabled when the `abi3` feature flag is enabled. //! - `PyPy` - Marks code enabled when compiling for PyPy. //! +//! Add [`pyo3-build-config`] as a build dependency in your `Cargo.toml`: +//! +//! ```toml +//! [build-dependency] +//! pyo3-build-config = "VER" +//! ``` +//! +//! And then either create a new `build.rs` file in the project root or modify +//! the existing `build.rs` file to call `use_pyo3_cfgs()`: +//! +//! ```rust +//! fn main() { +//! pyo3_build_config::use_pyo3_cfgs(); +//! } +//! ``` +//! //! # Minimum supported Rust and Python versions //! //! `pyo3-ffi` supports the following Python distributions: From 13f8c21acc77e12f716280c411f8fe530df40a2b Mon Sep 17 00:00:00 2001 From: Nathan Goldbaum Date: Wed, 23 Oct 2024 11:20:32 -0600 Subject: [PATCH 2/4] Document all of the config attributes --- pyo3-ffi/src/lib.rs | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/pyo3-ffi/src/lib.rs b/pyo3-ffi/src/lib.rs index 48028d53426..6f8df1f0b46 100644 --- a/pyo3-ffi/src/lib.rs +++ b/pyo3-ffi/src/lib.rs @@ -43,12 +43,25 @@ //! PyO3 uses `rustc`'s `--cfg` flags to enable or disable code used for different Python versions. //! If you want to do this for your own crate, you can do so with the [`pyo3-build-config`] crate. //! -//! - `Py_3_7`, `Py_3_8`, `Py_3_9`, `Py_3_10`: Marks code that is only enabled when -//! compiling for a given minimum Python version. +//! - `Py_3_7`, `Py_3_8`, `Py_3_9`, `Py_3_10`, `Py_3_11`, `Py_3_12`, `Py_3_13`: Marks code that is +//! only enabled when compiling for a given minimum Python version. //! - `Py_LIMITED_API`: Marks code enabled when the `abi3` feature flag is enabled. +//! - `Py_GIL_DISABLED`: Marks code that runs only in the free-threaded build of CPython. //! - `PyPy` - Marks code enabled when compiling for PyPy. +//! - `GraalPy` - Marks code enabled when compiling for GraalPy. //! -//! Add [`pyo3-build-config`] as a build dependency in your `Cargo.toml`: +//! Additionally, you can query for the values `Py_DEBUG`, `Py_REF_DEBUG`, +//! `Py_TRACE_REFS`, and `COUNT_ALLOCS` from `py_sys_config` to query for the +//! corresponding C build-time defines. For example, to conditionally define +//! debug code using `Py_DEBUG`, you could do: +//! +//! ```rust +//! #[cfg(py_sys_config = "Py_DEBUG")] +//! // code that only runs if python was compiled with Py_DEBUG +//! ``` +//! +//! To use these attributes, add [`pyo3-build-config`] as a build dependency in +//! your `Cargo.toml`: //! //! ```toml //! [build-dependency] From 40b9526c0368f7e836788622aa82a66a91d55746 Mon Sep 17 00:00:00 2001 From: Nathan Goldbaum Date: Wed, 23 Oct 2024 17:21:19 -0600 Subject: [PATCH 3/4] fix pyo3-ffi tests --- pyo3-ffi/Cargo.toml | 1 + pyo3-ffi/src/lib.rs | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/pyo3-ffi/Cargo.toml b/pyo3-ffi/Cargo.toml index 0e58197bbfd..18dddf19db9 100644 --- a/pyo3-ffi/Cargo.toml +++ b/pyo3-ffi/Cargo.toml @@ -39,6 +39,7 @@ generate-import-lib = ["pyo3-build-config/python3-dll-a"] [dev-dependencies] paste = "1" +pyo3-build-config = { path = "../pyo3-build-config", version = "=0.23.0-dev", features = ["resolve-config"] } [build-dependencies] pyo3-build-config = { path = "../pyo3-build-config", version = "=0.23.0-dev", features = ["resolve-config"] } diff --git a/pyo3-ffi/src/lib.rs b/pyo3-ffi/src/lib.rs index 6f8df1f0b46..ef462548e94 100644 --- a/pyo3-ffi/src/lib.rs +++ b/pyo3-ffi/src/lib.rs @@ -57,7 +57,7 @@ //! //! ```rust //! #[cfg(py_sys_config = "Py_DEBUG")] -//! // code that only runs if python was compiled with Py_DEBUG +//! println!("only runs if python was compiled with Py_DEBUG") //! ``` //! //! To use these attributes, add [`pyo3-build-config`] as a build dependency in From fa013c3b7d23bed9ffd20cf7b98de9de38257719 Mon Sep 17 00:00:00 2001 From: Nathan Goldbaum Date: Wed, 23 Oct 2024 19:16:36 -0600 Subject: [PATCH 4/4] ignore the code examples instead of adding a dev dependency --- pyo3-ffi/Cargo.toml | 1 - pyo3-ffi/src/lib.rs | 4 ++-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/pyo3-ffi/Cargo.toml b/pyo3-ffi/Cargo.toml index 18dddf19db9..0e58197bbfd 100644 --- a/pyo3-ffi/Cargo.toml +++ b/pyo3-ffi/Cargo.toml @@ -39,7 +39,6 @@ generate-import-lib = ["pyo3-build-config/python3-dll-a"] [dev-dependencies] paste = "1" -pyo3-build-config = { path = "../pyo3-build-config", version = "=0.23.0-dev", features = ["resolve-config"] } [build-dependencies] pyo3-build-config = { path = "../pyo3-build-config", version = "=0.23.0-dev", features = ["resolve-config"] } diff --git a/pyo3-ffi/src/lib.rs b/pyo3-ffi/src/lib.rs index ef462548e94..293c5171eb5 100644 --- a/pyo3-ffi/src/lib.rs +++ b/pyo3-ffi/src/lib.rs @@ -55,7 +55,7 @@ //! corresponding C build-time defines. For example, to conditionally define //! debug code using `Py_DEBUG`, you could do: //! -//! ```rust +//! ```rust,ignore //! #[cfg(py_sys_config = "Py_DEBUG")] //! println!("only runs if python was compiled with Py_DEBUG") //! ``` @@ -71,7 +71,7 @@ //! And then either create a new `build.rs` file in the project root or modify //! the existing `build.rs` file to call `use_pyo3_cfgs()`: //! -//! ```rust +//! ```rust,ignore //! fn main() { //! pyo3_build_config::use_pyo3_cfgs(); //! }