refactor: Break down generate() into smaller fns

Add two private helper methods `write_def_file()`
and `implib_file_name()`.

Expand the docstrings on some public items.

Author: ravenexp

src/lib.rs

@@ -79,7 +79,7 @@
 use std::ffi::OsStr;
 use std::fs::{create_dir_all, write};
 use std::io::{Error, ErrorKind, Result};
-use std::path::Path;
+use std::path::{Path, PathBuf};
 use std::process::Command;
 
 /// Import library file extension for the GNU environment ABI (MinGW-w64)
@@ -110,12 +110,18 @@ pub struct ImportLibraryGenerator {
     arch: String,
     // The compile target environment ABI name (as in `CARGO_CFG_TARGET_ENV`)
     env: String,
-    /// Python major and minor version
+    /// Major and minor Python version (for `pythonXY.dll` only)
     version: Option<(u8, u8)>,
 }
 
 impl ImportLibraryGenerator {
-    /// Creates a new import library generator for the specified compile target
+    /// Creates a new import library generator for the specified compile target.
+    ///
+    /// 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 new(arch: &str, env: &str) -> Self {
         Self {
             arch: arch.to_string(),
@@ -124,62 +130,37 @@ impl ImportLibraryGenerator {
         }
     }
 
-    /// Set python major and minor version
+    /// Sets major and minor version for the `pythonXY.dll` import library.
+    ///
+    /// The version-agnostic `python3.dll` is generated by default.
     pub fn version(&mut self, version: Option<(u8, u8)>) -> &mut Self {
         self.version = version;
         self
     }
 
-    /// Generates the import library in `out_dir`
+    /// Generates the Python DLL import library in `out_dir`.
+    ///
+    /// The version-agnostic `python3.dll` import library is generated
+    /// by default unless the version-specific `pythonXY.dll` import
+    /// was requested via `version()`.
     pub fn generate(&self, out_dir: &Path) -> Result<()> {
         create_dir_all(out_dir)?;
 
-        let mut defpath = out_dir.to_owned();
-        let (def_file, def_file_content) = match self.version {
-            None => ("python3.def", include_str!("python3.def")),
-            Some((3, 7)) => ("python37.def", include_str!("python37.def")),
-            Some((3, 8)) => ("python38.def", include_str!("python38.def")),
-            Some((3, 9)) => ("python39.def", include_str!("python39.def")),
-            Some((3, 10)) => ("python310.def", include_str!("python310.def")),
-            Some((3, 11)) => ("python311.def", include_str!("python311.def")),
-            _ => return Err(Error::new(ErrorKind::Other, "Unsupported Python version")),
-        };
-        defpath.push(def_file);
-
-        write(&defpath, def_file_content)?;
+        let defpath = self.write_def_file(out_dir)?;
+        let implib_file = self.implib_file_path(out_dir);
 
-        let impllib_ext = if self.env == "msvc" {
-            IMPLIB_EXT_MSVC
-        } else {
-            IMPLIB_EXT_GNU
-        };
-        let implib_file = match self.version {
-            Some((major, minor)) => {
-                format!("python{}{}{}", major, minor, impllib_ext)
-            }
-            None => format!("python3{}", impllib_ext),
-        };
         // Try to guess the `dlltool` executable name from the target triple.
         let mut command = match (self.arch.as_str(), self.env.as_str()) {
             // 64-bit MinGW-w64 (aka x86_64-pc-windows-gnu)
-            ("x86_64", "gnu") => {
-                self.build_dlltool_command(DLLTOOL_GNU, &implib_file, &defpath, out_dir)
-            }
+            ("x86_64", "gnu") => self.build_dlltool_command(DLLTOOL_GNU, &implib_file, &defpath),
             // 32-bit MinGW-w64 (aka i686-pc-windows-gnu)
-            ("x86", "gnu") => {
-                self.build_dlltool_command(DLLTOOL_GNU_32, &implib_file, &defpath, out_dir)
-            }
+            ("x86", "gnu") => self.build_dlltool_command(DLLTOOL_GNU_32, &implib_file, &defpath),
             // MSVC ABI (multiarch)
             (_, "msvc") => {
                 if let Some(command) = find_lib_exe(&self.arch) {
-                    self.build_dlltool_command(
-                        command.get_program(),
-                        &implib_file,
-                        &defpath,
-                        out_dir,
-                    )
+                    self.build_dlltool_command(command.get_program(), &implib_file, &defpath)
                 } else {
-                    self.build_dlltool_command(DLLTOOL_MSVC, &implib_file, &defpath, out_dir)
+                    self.build_dlltool_command(DLLTOOL_MSVC, &implib_file, &defpath)
                 }
             }
             _ => {
@@ -205,18 +186,61 @@ impl ImportLibraryGenerator {
         }
     }
 
+    /// Writes out the embedded Python library definitions file to `out_dir`.
+    ///
+    /// Returns the newly created `python3.def` or `pythonXY.def` file path.
+    fn write_def_file(&self, out_dir: &Path) -> Result<PathBuf> {
+        let (def_file, def_file_content) = match self.version {
+            None => ("python3.def", include_str!("python3.def")),
+            Some((3, 7)) => ("python37.def", include_str!("python37.def")),
+            Some((3, 8)) => ("python38.def", include_str!("python38.def")),
+            Some((3, 9)) => ("python39.def", include_str!("python39.def")),
+            Some((3, 10)) => ("python310.def", include_str!("python310.def")),
+            Some((3, 11)) => ("python311.def", include_str!("python311.def")),
+            _ => return Err(Error::new(ErrorKind::Other, "Unsupported Python version")),
+        };
+
+        let mut defpath = out_dir.to_owned();
+        defpath.push(def_file);
+
+        write(&defpath, def_file_content)?;
+
+        Ok(defpath)
+    }
+
+    /// Builds the generated import library file name.
+    ///
+    /// Returns the full import library file path under `out_dir`.
+    fn implib_file_path(&self, out_dir: &Path) -> PathBuf {
+        let libext = if self.env == "msvc" {
+            IMPLIB_EXT_MSVC
+        } else {
+            IMPLIB_EXT_GNU
+        };
+
+        let libname = match self.version {
+            Some((major, minor)) => {
+                format!("python{}{}{}", major, minor, libext)
+            }
+            None => format!("python3{}", libext),
+        };
+
+        let mut libpath = out_dir.to_owned();
+        libpath.push(libname);
+
+        libpath
+    }
+
     /// Generates the complete `dlltool` executable invocation command.
     ///
     /// Supports Visual Studio `lib.exe`, LLVM and MinGW `dlltool` flavors.
     fn build_dlltool_command(
         &self,
         dlltool: impl AsRef<OsStr>,
-        implib_file: &str,
+        libpath: &Path,
         defpath: &Path,
-        out_dir: &Path,
     ) -> Command {
         let dlltool = dlltool.as_ref();
-        let mut libpath = out_dir.to_owned();
         let mut command = if self.env == "msvc" {
             find_lib_exe(&self.arch).unwrap_or_else(|| Command::new(dlltool))
         } else {
@@ -225,8 +249,6 @@ impl ImportLibraryGenerator {
 
         // Check whether we are using LLVM `dlltool` or MinGW `dlltool`.
         if dlltool == DLLTOOL_MSVC {
-            libpath.push(implib_file);
-
             // LLVM tools use their own target architecture names...
             let machine = match self.arch.as_str() {
                 "x86_64" => "i386:x86-64",
@@ -243,8 +265,6 @@ impl ImportLibraryGenerator {
                 .arg("-l")
                 .arg(libpath);
         } else if Path::new(dlltool).file_name() == Some(LIB_MSVC.as_ref()) {
-            libpath.push(implib_file);
-
             // lib.exe use their own target architecure names...
             let machine = match self.arch.as_str() {
                 "x86_64" => "X64",
@@ -257,8 +277,6 @@ impl ImportLibraryGenerator {
                 .arg(format!("/DEF:{}", defpath.display()))
                 .arg(format!("/OUT:{}", libpath.display()));
         } else {
-            libpath.push(implib_file);
-
             command
                 .arg("--input-def")
                 .arg(defpath)
@@ -285,7 +303,7 @@ pub fn generate_implib_for_target(out_dir: &Path, arch: &str, env: &str) -> Resu
     ImportLibraryGenerator::new(arch, env).generate(out_dir)
 }
 
-/// Find Visual Studio lib.exe on Windows
+/// Finds Visual Studio `lib.exe` when running on Windows.
 #[cfg(windows)]
 fn find_lib_exe(arch: &str) -> Option<Command> {
     let target = match arch {
@@ -294,6 +312,7 @@ fn find_lib_exe(arch: &str) -> Option<Command> {
         "aarch64" => "aarch64-pc-windows-msvc",
         _ => return None,
     };
+
     cc::windows_registry::find(target, LIB_MSVC)
 }