readme/faq: document `rlib` crate type better
This commit is contained in:
parent
b152fd6317
commit
c1c4a5ffa5
10
README.md
10
README.md
|
@ -45,6 +45,11 @@ edition = "2018"
|
|||
|
||||
[lib]
|
||||
name = "string_sum"
|
||||
# "cdylib" is necessary to produce a shared library for Python to import from.
|
||||
#
|
||||
# Downstream Rust code (including code in `bin/`, `examples/`, and `tests/`) will not be able
|
||||
# to `use string_sum;` unless the "rlib" or "lib" crate type is also included, e.g.:
|
||||
# crate-type = ["cdylib", "rlib"]
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies.pyo3]
|
||||
|
@ -91,11 +96,6 @@ rustflags = [
|
|||
|
||||
While developing, you can symlink (or copy) and rename the shared library from the target folder: On MacOS, rename `libstring_sum.dylib` to `string_sum.so`, on Windows `libstring_sum.dll` to `string_sum.pyd`, and on Linux `libstring_sum.so` to `string_sum.so`. Then open a Python shell in the same folder and you'll be able to `import string_sum`.
|
||||
|
||||
Adding the `cdylib` arguments in the `Cargo.toml` files changes the way your crate is compiled.
|
||||
Other Rust projects using your crate will have to link against the `.so` or `.pyd` file rather than include your library directly as normal.
|
||||
In order to make available your crate in the usual way for Rust user, you you might want to consider using both `crate-type = ["cdylib", "rlib"]` so that Rust users can use the `rlib` (the default lib crate type).
|
||||
Another possibility is to create a new crate to perform the binding.
|
||||
|
||||
To build, test and publish your crate as a Python module, you can use [maturin](https://github.com/PyO3/maturin) or [setuptools-rust](https://github.com/PyO3/setuptools-rust). You can find an example for setuptools-rust in [examples/word-count](https://github.com/PyO3/pyo3/tree/master/examples/word-count), while maturin should work on your crate without any configuration.
|
||||
|
||||
## Using Python from Rust
|
||||
|
|
|
@ -28,6 +28,29 @@ extension-module = ["pyo3/extension-module"]
|
|||
default = ["extension-module"]
|
||||
```
|
||||
|
||||
## I can't run `cargo test`: my crate cannot be found for tests in `tests/` directory!
|
||||
|
||||
The Rust book suggests to [put integration tests inside a `tests/` directory](https://doc.rust-lang.org/book/ch11-03-test-organization.html#integration-tests).
|
||||
|
||||
For a PyO3 `extension-module` project where the `crate-type` is set to `"cdylib"` in your `Cargo.toml`,
|
||||
the compiler won't be able to find your crate and will display errors such as `E0432` or `E0463`:
|
||||
|
||||
```
|
||||
error[E0432]: unresolved import `my_crate`
|
||||
--> tests/test_my_crate.rs:1:5
|
||||
|
|
||||
1 | use my_crate;
|
||||
| ^^^^^^^^^^^^ no external crate `my_crate`
|
||||
```
|
||||
|
||||
The best solution is to make your crate types include both `rlib` and `cdylib`:
|
||||
|
||||
```
|
||||
# Cargo.toml
|
||||
[lib]
|
||||
crate-type = ["cdylib", "rlib"]
|
||||
```
|
||||
|
||||
## Ctrl-C doesn't do anything while my Rust code is executing!
|
||||
|
||||
This is because Ctrl-C raises a SIGINT signal, which is handled by the calling Python process by simply setting a flag to action upon later. This flag isn't checked while Rust code called from Python is executing, only once control returns to the Python interpreter.
|
||||
|
|
|
@ -49,6 +49,11 @@
|
|||
//!
|
||||
//! [lib]
|
||||
//! name = "string_sum"
|
||||
//! # "cdylib" is necessary to produce a shared library for Python to import from.
|
||||
//! #
|
||||
//! # Downstream Rust code (including code in `bin/`, `examples/`, and `tests/`) will not be able
|
||||
//! # to `use string_sum;` unless the "rlib" or "lib" crate type is also included, e.g.:
|
||||
//! # crate-type = ["cdylib", "rlib"]
|
||||
//! crate-type = ["cdylib"]
|
||||
//!
|
||||
//! [dependencies.pyo3]
|
||||
|
|
Loading…
Reference in New Issue