Add version_suffix_components setting (#352)

Author: kpcyrd

README.md

@@ -135,6 +135,10 @@ version = "1.2.3"
 install_subdir = "gstreamer-1.0"
 # Used to disable versioning links when installing the dynamic library
 versioning = false
+# Instead of using semver, select a fixed number of version components for your SONAME version suffix:
+# Setting this to 1 with a version of 0.0.0 allows a suffix of `.so.0`
+# Setting this to 3 always includes the full version in the SONAME (indicate any update is ABI breaking)
+#version_suffix_components = 2
 # Add `-Cpanic=abort` to the RUSTFLAGS automatically, it may be useful in case
 # something might panic in the crates used by the library.
 rustflags = "-Cpanic=abort"

src/build.rs

@@ -14,6 +14,7 @@ use cargo::util::command_prelude::{ArgMatches, ArgMatchesExt, CompileMode, Profi
 use cargo::util::interning::InternedString;
 use cargo::{CliResult, Config};
 
+use anyhow::Context as _;
 use cargo_util::paths::{copy, create, create_dir_all, open, read, read_bytes, write};
 use semver::Version;
 
@@ -400,16 +401,43 @@ pub struct PkgConfigCApiConfig {
     pub strip_include_path_components: usize,
 }
 
+#[derive(Debug)]
+pub enum VersionSuffix {
+    Major,
+    MajorMinor,
+    MajorMinorPatch,
+}
+
 #[derive(Debug)]
 pub struct LibraryCApiConfig {
     pub name: String,
     pub version: Version,
     pub install_subdir: Option<String>,
     pub versioning: bool,
+    pub version_suffix_components: Option<VersionSuffix>,
     pub import_library: bool,
     pub rustflags: Vec<String>,
 }
 
+impl LibraryCApiConfig {
+    pub fn sover(&self) -> String {
+        let major = self.version.major;
+        let minor = self.version.minor;
+        let patch = self.version.patch;
+
+        match self.version_suffix_components {
+            None => match (major, minor, patch) {
+                (0, 0, patch) => format!("0.0.{patch}"),
+                (0, minor, _) => format!("0.{minor}"),
+                (major, _, _) => format!("{major}"),
+            },
+            Some(VersionSuffix::Major) => format!("{major}"),
+            Some(VersionSuffix::MajorMinor) => format!("{major}.{minor}"),
+            Some(VersionSuffix::MajorMinorPatch) => format!("{major}.{minor}.{patch}"),
+        }
+    }
+}
+
 #[derive(Debug, Default)]
 pub struct InstallCApiConfig {
     pub include: Vec<InstallTarget>,
@@ -619,6 +647,7 @@ fn load_manifest_capi_config(pkg: &Package) -> anyhow::Result<CApiConfig> {
     let mut version = pkg.version().clone();
     let mut install_subdir = None;
     let mut versioning = true;
+    let mut version_suffix_components = None;
     let mut import_library = true;
     let mut rustflags = Vec::new();
 
@@ -636,6 +665,19 @@ fn load_manifest_capi_config(pkg: &Package) -> anyhow::Result<CApiConfig> {
             .get("versioning")
             .and_then(|v| v.as_bool())
             .unwrap_or(true);
+
+        if let Some(value) = library.get("version_suffix_components") {
+            let value = value.as_integer().with_context(|| {
+                format!("Value for `version_suffix_components` is not an integer: {value:?}")
+            })?;
+            version_suffix_components = Some(match value {
+                1 => VersionSuffix::Major,
+                2 => VersionSuffix::MajorMinor,
+                3 => VersionSuffix::MajorMinorPatch,
+                _ => anyhow::bail!("Out of range value for version suffix components: {value}"),
+            });
+        }
+
         import_library = library
             .get("import_library")
             .and_then(|v| v.as_bool())
@@ -655,6 +697,7 @@ fn load_manifest_capi_config(pkg: &Package) -> anyhow::Result<CApiConfig> {
         version,
         install_subdir,
         versioning,
+        version_suffix_components,
         import_library,
         rustflags,
     };
@@ -1246,3 +1289,66 @@ pub fn ctest(
 
     ops::run_tests(ws, &ops, &test_args)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use semver::Version;
+
+    fn make_test_library_config(version: &str) -> LibraryCApiConfig {
+        LibraryCApiConfig {
+            name: "example".to_string(),
+            version: Version::parse(version).unwrap(),
+            install_subdir: None,
+            versioning: true,
+            version_suffix_components: None,
+            import_library: true,
+            rustflags: vec![],
+        }
+    }
+
+    #[test]
+    pub fn test_semver_zero_zero_zero() {
+        let library = make_test_library_config("0.0.0");
+        let sover = library.sover();
+        assert_eq!(sover, "0.0.0");
+    }
+
+    #[test]
+    pub fn test_semver_zero_one_zero() {
+        let library = make_test_library_config("0.1.0");
+        let sover = library.sover();
+        assert_eq!(sover, "0.1");
+    }
+
+    #[test]
+    pub fn test_semver_one_zero_zero() {
+        let library = make_test_library_config("1.0.0");
+        let sover = library.sover();
+        assert_eq!(sover, "1");
+    }
+
+    #[test]
+    pub fn text_one_fixed_zero_zero_zero() {
+        let mut library = make_test_library_config("0.0.0");
+        library.version_suffix_components = Some(VersionSuffix::Major);
+        let sover = library.sover();
+        assert_eq!(sover, "0");
+    }
+
+    #[test]
+    pub fn text_two_fixed_one_zero_zero() {
+        let mut library = make_test_library_config("1.0.0");
+        library.version_suffix_components = Some(VersionSuffix::MajorMinor);
+        let sover = library.sover();
+        assert_eq!(sover, "1.0");
+    }
+
+    #[test]
+    pub fn text_three_fixed_one_zero_zero() {
+        let mut library = make_test_library_config("1.0.0");
+        library.version_suffix_components = Some(VersionSuffix::MajorMinorPatch);
+        let sover = library.sover();
+        assert_eq!(sover, "1.0.0");
+    }
+}

src/install.rs

@@ -3,11 +3,9 @@ use std::path::{Component, Path, PathBuf};
 
 use cargo::core::Workspace;
 use cargo_util::paths::{copy, create_dir_all};
-use semver::Version;
 
 use crate::build::*;
 use crate::build_targets::BuildTargets;
-use crate::VersionExt;
 
 fn append_to_destdir(destdir: Option<&Path>, path: &Path) -> PathBuf {
     if let Some(destdir) = destdir {
@@ -107,8 +105,10 @@ pub(crate) struct UnixLibNames {
 }
 
 impl UnixLibNames {
-    pub(crate) fn new(lib_type: LibType, lib_name: &str, lib_version: &Version) -> Option<Self> {
-        let main_version = lib_version.main_version();
+    pub(crate) fn new(lib_type: LibType, library: &LibraryCApiConfig) -> Option<Self> {
+        let lib_name = &library.name;
+        let lib_version = &library.version;
+        let main_version = library.sover();
 
         match lib_type {
             LibType::So => {
@@ -236,12 +236,10 @@ pub fn cinstall(ws: &Workspace, packages: &[CPackage]) -> anyhow::Result<()> {
         if let Some(ref shared_lib) = build_targets.shared_lib {
             ws.config().shell().status("Installing", "shared library")?;
 
-            let lib_name = &capi_config.library.name;
             let lib_type = LibType::from_build_targets(build_targets);
             match lib_type {
                 LibType::So | LibType::Dylib => {
-                    let lib = UnixLibNames::new(lib_type, lib_name, &capi_config.library.version)
-                        .unwrap();
+                    let lib = UnixLibNames::new(lib_type, &capi_config.library).unwrap();
                     lib.install(capi_config, shared_lib, &install_path_lib)?;
                 }
                 LibType::Windows => {

src/lib.rs

@@ -5,18 +5,3 @@ pub mod config;
 pub mod install;
 pub mod pkg_config_gen;
 pub mod target;
-
-trait VersionExt {
-    /// build the main version string
-    fn main_version(&self) -> String;
-}
-
-impl VersionExt for semver::Version {
-    fn main_version(&self) -> String {
-        match (self.major, self.minor, self.patch) {
-            (0, 0, patch) => format!("0.0.{patch}"),
-            (0, minor, _) => format!("0.{minor}"),
-            (major, _, _) => format!("{major}"),
-        }
-    }
-}

src/pkg_config_gen.rs

@@ -298,6 +298,7 @@ mod test {
                     version: Version::parse("0.1.0").unwrap(),
                     install_subdir: None,
                     versioning: true,
+                    version_suffix_components: None,
                     import_library: true,
                     rustflags: Vec::default(),
                 },

src/target.rs

@@ -3,7 +3,6 @@ use std::path::Path;
 use anyhow::*;
 
 use crate::build::CApiConfig;
-use crate::VersionExt;
 
 /// Split a target string to its components
 ///
@@ -70,7 +69,7 @@ impl Target {
         let os = &self.os;
         let env = &self.env;
 
-        let sover = version.main_version();
+        let sover = capi_config.library.sover();
 
         if os == "android" {
             lines.push(format!("-Wl,-soname,lib{lib_name}.so"));