Skip to content

Commit

Permalink
feat!: Use Path type for the output directory arg
Browse files Browse the repository at this point in the history 
This is a major public API change and requires a major crate SemVer bump.

Remove the legacy `generate_implib()` function from the public crate API.
The existing users should migrate to `generate_implib_for_target()`.

Update the crate documentation and remove all mentions of `generate_implib()`.

Bump the crate version to 0.2.0 (preliminary).
  • Loading branch information
@ravenexp
ravenexp committed Mar 21, 2022
1 parent 7a191c4 commit d1cf907
Show file tree
Hide file tree
Showing 3 changed files with 36 additions and 75 deletions.
2 changes: 1 addition & 1 deletion Cargo.toml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "python3-dll-a"
version = "0.1.2"
version = "0.2.0"
edition = "2021"
description = "Standalone python3.dll import library generator"
repository = "https://github.com/ravenexp/python3-dll-a"
Expand Down
34 changes: 11 additions & 23 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,41 +17,29 @@ to be present in `PATH` when targeting `*-pc-windows-msvc`.
Example `build.rs` script
-------------------------

The following script can be used to cross-compile Stable ABI
PyO3 extension modules for Windows (64-bit MinGW-w64):

```rust
fn main() {
if std::env::var("TARGET").unwrap() == "x86_64-pc-windows-gnu" {
let libdir = std::env::var("PYO3_CROSS_LIB_DIR")
.expect("PYO3_CROSS_LIB_DIR is not set when cross-compiling");
python3_dll_a::generate_implib(&libdir)
.expect("python3.dll import library generator failed");
}
}
```

A compatible `python3.dll` import library will be automatically created in
the directory pointed by `PYO3_CROSS_LIB_DIR` environment variable.

If both 64-bit and 32-bit or GNU and MSVC ABI (cross-)compile target
support is needed, the more generic `generate_implib_for_target()`
function must be used:

The following Cargo build script can be used to cross-compile Stable ABI
PyO3 extension modules for Windows (64/32-bit x86 or 64-bit ARM)
using either MinGW-w64 or MSVC target environment ABI:

```rust
fn main() {
if std::env::var("CARGO_CFG_TARGET_OS").unwrap() == "windows" {
let libdir = std::env::var("PYO3_CROSS_LIB_DIR")
let cross_lib_dir = std::env::var_os("PYO3_CROSS_LIB_DIR")
.expect("PYO3_CROSS_LIB_DIR is not set when cross-compiling");
let arch = std::env::var("CARGO_CFG_TARGET_ARCH").unwrap();
let env = std::env::var("CARGO_CFG_TARGET_ENV").unwrap();
python3_dll_a::generate_implib_for_target(&libdir, &arch, &env)

let libdir = std::path::Path::new(&cross_lib_dir);
python3_dll_a::generate_implib_for_target(libdir, &arch, &env)
.expect("python3.dll import library generator failed");
}
}
```

A compatible `python3.dll` import library file named `python3.dll.a`
or `python3.lib` will be automatically created in the directory
pointed by the `PYO3_CROSS_LIB_DIR` environment variable.

Example `cargo build` invocation
--------------------------------

Expand Down
75 changes: 24 additions & 51 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,40 +17,29 @@
//! Example `build.rs` script
//! -------------------------
//!
//! The following script can be used to cross-compile Stable ABI
//! PyO3 extension modules for Windows (64-bit MinGW-w64):
//!
//! ```no_run
//! fn main() {
//! if std::env::var("TARGET").unwrap() == "x86_64-pc-windows-gnu" {
//! let libdir = std::env::var("PYO3_CROSS_LIB_DIR")
//! .expect("PYO3_CROSS_LIB_DIR is not set when cross-compiling");
//! python3_dll_a::generate_implib(&libdir)
//! .expect("python3.dll import library generator failed");
//! }
//! }
//! ```
//!
//! A compatible `python3.dll` import library will be automatically created in
//! the directory pointed by `PYO3_CROSS_LIB_DIR` environment variable.
//!
//! If both 64-bit and 32-bit or GNU and MSVC ABI (cross-)compile target
//! support is needed, the more generic `generate_implib_for_target()`
//! function must be used:
//! The following Cargo build script can be used to cross-compile Stable ABI
//! PyO3 extension modules for Windows (64/32-bit x86 or 64-bit ARM)
//! using either MinGW-w64 or MSVC target environment ABI:
//!
//! ```no_run
//! fn main() {
//! if std::env::var("CARGO_CFG_TARGET_OS").unwrap() == "windows" {
//! let libdir = std::env::var("PYO3_CROSS_LIB_DIR")
//! let cross_lib_dir = std::env::var_os("PYO3_CROSS_LIB_DIR")
//! .expect("PYO3_CROSS_LIB_DIR is not set when cross-compiling");
//! let arch = std::env::var("CARGO_CFG_TARGET_ARCH").unwrap();
//! let env = std::env::var("CARGO_CFG_TARGET_ENV").unwrap();
//! python3_dll_a::generate_implib_for_target(&libdir, &arch, &env)
//!
//! let libdir = std::path::Path::new(&cross_lib_dir);
//! python3_dll_a::generate_implib_for_target(libdir, &arch, &env)
//! .expect("python3.dll import library generator failed");
//! }
//! }
//! ```
//!
//! A compatible `python3.dll` import library file named `python3.dll.a`
//! or `python3.lib` will be automatically created in the directory
//! pointed by the `PYO3_CROSS_LIB_DIR` environment variable.
//!
//! Example `cargo build` invocation
//! --------------------------------
//!
Expand All @@ -64,7 +53,7 @@
use std::fs::create_dir_all;
use std::fs::File;
use std::io::{BufWriter, Error, ErrorKind, Result, Write};
use std::path::{Path, PathBuf};
use std::path::Path;
use std::process::Command;

/// Stable ABI Python DLL file name
Expand Down Expand Up @@ -96,18 +85,18 @@ const STABLE_ABI_DEFS: &str = include_str!("../Misc/stable_abi.txt");
/// Generates `python3.dll` import library directly from the embedded
/// Python Stable ABI definitions data for the specified compile target.
///
/// The import library file named `python3.dll.a` is created
/// The import library file named `python3.dll.a` or `python3.lib` is created
/// in directory `out_dir`.
///
/// The compile target architecture name (as in `CARGO_CFG_TARGET_ARCH`)
/// is passed in `arch`.
///
/// The compile target environment ABI name (as in `CARGO_CFG_TARGET_ENV`)
/// is passed in `env`.
pub fn generate_implib_for_target(out_dir: &str, arch: &str, env: &str) -> Result<()> {
pub fn generate_implib_for_target(out_dir: &Path, arch: &str, env: &str) -> Result<()> {
create_dir_all(out_dir)?;

let mut defpath = PathBuf::from(out_dir);
let mut defpath = out_dir.to_owned();
defpath.push(DEF_FILE);

let stable_abi_exports = parse_stable_abi_defs(STABLE_ABI_DEFS);
Expand Down Expand Up @@ -144,8 +133,8 @@ pub fn generate_implib_for_target(out_dir: &str, arch: &str, env: &str) -> Resul
/// Generates the complete `dlltool` executable invocation command.
///
/// Supports both LLVM and MinGW `dlltool` flavors.
fn build_dlltool_command(dlltool: &str, arch: &str, defpath: &Path, out_dir: &str) -> Command {
let mut libpath = PathBuf::from(out_dir);
fn build_dlltool_command(dlltool: &str, arch: &str, defpath: &Path, out_dir: &Path) -> Command {
let mut libpath = out_dir.to_owned();
let mut command = Command::new(dlltool);

// Check whether we are using LLVM `dlltool` or MinGW `dlltool`.
Expand Down Expand Up @@ -180,19 +169,6 @@ fn build_dlltool_command(dlltool: &str, arch: &str, defpath: &Path, out_dir: &st
command
}

/// Generates `python3.dll` import library directly from the embedded
/// Python Stable ABI definitions data for the default 64-bit MinGW-w64
/// compile target.
///
/// The import library file named `python3.dll.a` is created
/// in directory `out_dir`.
///
/// The import library is generated for the default `x86_64-pc-windows-gnu`
/// cross-compile target.
pub fn generate_implib(out_dir: &str) -> Result<()> {
generate_implib_for_target(out_dir, "x86_64", "gnu")
}

/// Exported DLL symbol definition
struct DllExport {
/// Export symbol name
Expand Down Expand Up @@ -249,6 +225,8 @@ fn write_export_defs(writer: &mut impl Write, dll_name: &str, exports: &[DllExpo

#[cfg(test)]
mod tests {
use std::path::PathBuf;

use super::*;

#[test]
Expand All @@ -259,8 +237,7 @@ mod tests {
dir.push("x86_64-pc-windows-gnu");
dir.push("python3-dll");

let out_dir = dir.to_str().unwrap();
generate_implib(out_dir).unwrap();
generate_implib_for_target(&dir, "x86_64", "gnu").unwrap();
}

#[test]
Expand All @@ -270,8 +247,7 @@ mod tests {
dir.push("i686-pc-windows-gnu");
dir.push("python3-dll");

let out_dir = dir.to_str().unwrap();
generate_implib_for_target(out_dir, "x86", "gnu").unwrap();
generate_implib_for_target(&dir, "x86", "gnu").unwrap();
}

#[test]
Expand All @@ -281,8 +257,7 @@ mod tests {
dir.push("x86_64-pc-windows-msvc");
dir.push("python3-dll");

let out_dir = dir.to_str().unwrap();
generate_implib_for_target(out_dir, "x86_64", "msvc").unwrap();
generate_implib_for_target(&dir, "x86_64", "msvc").unwrap();
}

#[test]
Expand All @@ -292,8 +267,7 @@ mod tests {
dir.push("i686-pc-windows-msvc");
dir.push("python3-dll");

let out_dir = dir.to_str().unwrap();
generate_implib_for_target(out_dir, "x86", "msvc").unwrap();
generate_implib_for_target(&dir, "x86", "msvc").unwrap();
}

#[test]
Expand All @@ -303,8 +277,7 @@ mod tests {
dir.push("aarch64-pc-windows-msvc");
dir.push("python3-dll");

let out_dir = dir.to_str().unwrap();
generate_implib_for_target(out_dir, "aarch64", "msvc").unwrap();
generate_implib_for_target(&dir, "aarch64", "msvc").unwrap();
}

#[test]
Expand Down

0 comments on commit d1cf907

Please sign in to comment.