From 81d9e8719c8cd8fff02eb45b778a5016b95179bc Mon Sep 17 00:00:00 2001 From: David Hewitt <1939362+davidhewitt@users.noreply.github.com> Date: Mon, 13 Jul 2020 22:39:05 +0100 Subject: [PATCH] Replace `extension-module` feature with `PYO3_MAKE_EXTENSION_MODULE` --- CHANGELOG.md | 1 + Cargo.toml | 5 ----- README.md | 1 - build.rs | 2 +- examples/rustapi_module/Cargo.toml | 1 - examples/word-count/Cargo.toml | 2 +- guide/src/building_and_distribution.md | 28 ++++---------------------- guide/src/faq.md | 11 +--------- src/lib.rs | 5 +++-- 9 files changed, 11 insertions(+), 45 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4cd89a9458e..bfe85e7ae1a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Correct FFI definitions `Py_SetProgramName` and `Py_SetPythonHome` to take `*const` argument instead of `*mut`. [#1021](https://github.com/PyO3/pyo3/pull/1021) - Rename `PyString::to_string` to `to_str`, change return type `Cow` to `&str`. [#1023](https://github.com/PyO3/pyo3/pull/1023) - Correct FFI definition `_PyLong_AsByteArray` `*mut c_uchar` argument instead of `*const c_uchar`. [#1029](https://github.com/PyO3/pyo3/pull/1029) +- Replace `extension-module` feature with `PYO3_MAKE_EXTENSION_MODULE` environment variable. See the migration guide for help with upgrading. [#1040](https://github.com/PyO3/pyo3/pull/1040) ### Removed - Remove `PyString::as_bytes`. [#1023](https://github.com/PyO3/pyo3/pull/1023) diff --git a/Cargo.toml b/Cargo.toml index 177e3482036..0d917dff333 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -44,11 +44,6 @@ nightly = [] # this is no longer needed internally, but setuptools-rust assumes this feature python3 = [] -# Use this feature when building an extension module. -# It tells the linker to keep the python symbols unresolved, -# so that the module can also be used with statically linked python interpreters. -extension-module = [] - # The stable cpython abi as defined in PEP 384. Currently broken with # many compilation errors. Pull Requests working towards fixing that # are welcome. diff --git a/README.md b/README.md index ae4fbbc8eb7..3257251f61b 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,6 @@ crate-type = ["cdylib"] [dependencies.pyo3] version = "0.11.1" -features = ["extension-module"] ``` **`src/lib.rs`** diff --git a/build.rs b/build.rs index a091e3e3169..ca8881f4f8e 100644 --- a/build.rs +++ b/build.rs @@ -485,7 +485,7 @@ fn configure(interpreter_config: &InterpreterConfig) -> Result { check_target_architecture(interpreter_config)?; - let is_extension_module = env::var_os("CARGO_FEATURE_EXTENSION_MODULE").is_some(); + let is_extension_module = env::var_os("PYO3_MAKE_EXTENSION_MODULE").is_some(); if !is_extension_module || cfg!(target_os = "windows") { println!("{}", get_rustc_link_lib(&interpreter_config)?); if let Some(libdir) = &interpreter_config.libdir { diff --git a/examples/rustapi_module/Cargo.toml b/examples/rustapi_module/Cargo.toml index 98e728ee8c0..0917bcf61e5 100644 --- a/examples/rustapi_module/Cargo.toml +++ b/examples/rustapi_module/Cargo.toml @@ -9,7 +9,6 @@ edition = "2018" [dependencies.pyo3] path = "../../" -features = ["extension-module"] [lib] name = "rustapi_module" diff --git a/examples/word-count/Cargo.toml b/examples/word-count/Cargo.toml index 70f82bdd70d..576f51f3d4f 100644 --- a/examples/word-count/Cargo.toml +++ b/examples/word-count/Cargo.toml @@ -6,7 +6,7 @@ edition = "2018" [dependencies] rayon = "1.0.2" -pyo3 = { path = "../..", features = ["extension-module"] } +pyo3 = { path = "../.." } [lib] name = "word_count" diff --git a/guide/src/building_and_distribution.md b/guide/src/building_and_distribution.md index 354261d76c0..9690c3c2b3d 100644 --- a/guide/src/building_and_distribution.md +++ b/guide/src/building_and_distribution.md @@ -8,35 +8,15 @@ PyO3 uses a build script to determine the Python version and set the correct lin Different linker arguments must be set for libraries/extension modules and binaries, which includes both standalone binaries and tests. (More specifically, binaries must be told where to find libpython and libraries must not link to libpython for [manylinux](https://www.python.org/dev/peps/pep-0513/) compliance). -Since PyO3's build script can't know whether you're building a binary or a library, you have to activate the `extension-module` feature to get the build options for a library, or it'll default to binary. - -If you have e.g. a library crate and a profiling crate alongside, you need to use optional features. E.g. you put the following in the library crate: - -```toml -[dependencies] -pyo3 = "0.6" - -[lib] -name = "hyperjson" -crate-type = ["rlib", "cdylib"] - -[features] -default = ["pyo3/extension-module"] -``` - -And this in the profiling crate: - -```toml -[dependencies] -my_main_crate = { path = "..", default-features = false } -pyo3 = "0.6" -``` +Since PyO3's build script can't know whether you're building a binary or a library, it defaults to building for binaries. To build a library, you should set the `PYO3_MAKE_EXTENSION_MODULE` environment variable to a nonempty value. On Linux/macOS you might have to change `LD_LIBRARY_PATH` to include libpython, while on windows you might need to set `LIB` to include `pythonxy.lib` (where x and y are major and minor version), which is normally either in the `libs` or `Lib` folder of a Python installation. ## Distribution -There are two ways to distribute your module as a Python package: The old, [setuptools-rust](https://github.com/PyO3/setuptools-rust), and the new, [maturin](https://github.com/pyo3/maturin). setuptools-rust needs several configuration files (`setup.py`, `MANIFEST.in`, `build-wheels.sh`, etc.). maturin doesn't need any configuration files, however it does not support some functionality of setuptools such as package data ([pyo3/maturin#258](https://github.com/PyO3/maturin/issues/258)) and requires a rigid project structure, while setuptools-rust allows (and sometimes requires) configuration with python code. +There are two ways to distribute your module as a Python package: +- [`maturin`](https://github.com/pyo3/maturin) is the typical way to build and package PyO3 extension modules. It is deliberately opinionated about project structure, which allows it to need minimal configuration. +- [`setuptools-rust`](https://github.com/PyO3/setuptools-rust), in contrast, needs several configuration files (`setup.py`, `MANIFEST.in`, `build-wheels.sh`, etc.). This complexity comes at added flexibility, allowing configuration using python code. ## Cross Compiling diff --git a/guide/src/faq.md b/guide/src/faq.md index 96e7c0740de..b93ef856759 100644 --- a/guide/src/faq.md +++ b/guide/src/faq.md @@ -17,13 +17,4 @@ PyO3 provides a struct [`GILOnceCell`] which works equivalently to `OnceCell` bu ## I can't run `cargo test`: I'm having linker issues like "Symbol not found" or "Undefined reference to _PyExc_SystemError"! -Currently, [#341](https://github.com/PyO3/pyo3/issues/341) causes `cargo test` to fail with linking errors when the `extension-module` feature is activated. For now you can work around this by making the `extension-module` feature optional and running the tests with `cargo test --no-default-features`: - -```toml -[dependencies.pyo3] -version = "*" - -[features] -extension-module = ["pyo3/extension-module"] -default = ["extension-module"] -``` +If `PYO3_MAKE_EXTENSION_MODULE` environment variable is non-empty, PyO3 will not link against libpython. This will lead to errors like the above at link time. diff --git a/src/lib.rs b/src/lib.rs index bc72a770113..8d88453e8f6 100755 --- a/src/lib.rs +++ b/src/lib.rs @@ -37,7 +37,9 @@ //! //! ## Using Rust from Python //! -//! PyO3 can be used to generate a native Python module. +//! PyO3 can be used to generate a native Python module. For a zero-configuration +//! package to aid with compiling and packaging the module, see +//! [`maturin`](https://github.com/PyO3/maturin). //! //! **`Cargo.toml`** //! @@ -53,7 +55,6 @@ //! //! [dependencies.pyo3] //! version = "0.11.1" -//! features = ["extension-module"] //! ``` //! //! **`src/lib.rs`**