Improve the FileMode API

Avoid users needing to deal with raw u16 numbers and return errors on
invalid values rather than making "invalid" part of the enum.

CHANGELOG.md

@@ -7,9 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+
 - Support for setting file capabilities via the RPMTAGS_FILECAPS header.
-- `PackageMetadata::get_file_entries` method can get capability headers for each file.
-- Support for symbolic link in file mode.
+- When parsing packages, the `PackageMetadata::get_file_entries` method provides
+  access to the capabilities for each file.
+- Support for symbolic links when adding files to a `Package`.
+
+### Breaking Changes
+
+- Refactored the `FileOptions` functions. Instead of using `FileOptions::new(path)` to
+  construct a file to be added during a package build, instead you use `FileOptions::regular()`,
+  `FileOptions::dir()`, or `FileOptions::symlink()` for a regular file, directory, or symbolic
+  link, respectively.
 
 ## 0.12.0
 
@@ -22,10 +31,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   included by default and can be clamped using the `PackageBuilder::source_date` method.
 - Several of the signer and verifier trait APIs were changed
 
-Note: The pace of breaking changes ought to slow down significantly from this point forwards.
-Most of the substantial changes which needed to be made have now been made. Thank you for your
-patience.
-
 ### Added
 
 - `PackageBuilder::source_date` method for clamping modification time of files,

README.md

@@ -32,32 +32,31 @@ This library does not build software like rpmbuild. It is meant for finished art
 use rpm::signature::pgp::{Signer, Verifier};
 
 let raw_secret_key = std::fs::read("./test_assets/secret_key.asc")?;
-// It's recommended to use timestamp of last commit in your VCS
+// It's recommended to use timestamp of last commit in your VCS rather than a constant
 let source_date = 1_600_000_000;
 let pkg = rpm::PackageBuilder::new("test", "1.0.0", "MIT", "x86_64", "some awesome package")
     .compression(rpm::CompressionType::Gzip)
     .with_file(
         "./test_assets/awesome.toml",
-        rpm::FileOptions::new("/etc/awesome/config.toml").is_config(),
+        rpm::FileOptions::regular("/etc/awesome/config.toml").is_config(),
     )?
     // file mode is inherited from source file
     .with_file(
         "./test_assets/awesome.py",
-        rpm::FileOptions::new("/usr/bin/awesome"),
+        rpm::FileOptions::regular("/usr/bin/awesome"),
     )?
     .with_file(
         "./test_assets/awesome.toml",
         // you can set a custom mode and custom user too
-        rpm::FileOptions::new("/etc/awesome/second.toml")
-            .mode(rpm::FileMode::regular(0o644))
+        rpm::FileOptions::regular("/etc/awesome/second.toml")
+            .permissions(0o644)
             .caps("cap_sys_admin,cap_net_admin=pe")?
             .user("hugo"),
     )?
     .with_file(
         "./test_assets/empty_file_for_symlink_create",
-        rpm::FileOptions::new("/usr/bin/awesome_link")
-            .mode(0o120644)
-            .symlink("/usr/bin/awesome"),
+        rpm::FileOptions::symlink("/usr/bin/awesome_link", "/usr/bin/awesome")
+            .permissions(0o644)
     .pre_install_script("echo preinst")
     // If you don't need reproducible builds,
     // you can remove the following line

src/constants.rs

@@ -548,7 +548,7 @@ bitflags! {
         // const SPECFILE = 1 << 5;  // first file in SRPM?
         const GHOST = 1 << 6;  // %%ghost
         const LICENSE = 1 << 7;  // %%license
-        const README = 1 << 8;  // %%readme
+        const README = 1 << 8;  // %%readme  // obsolete?
         // bits 9-10 unused
         const PUBKEY = 1 << 11;	// %%pubkey
         const ARTIFACT	= 1 << 12;	// %%artifact

src/lib.rs

@@ -26,18 +26,18 @@
 //!     .compression(rpm::CompressionType::Gzip)
 //!     .with_file(
 //!         "./test_assets/awesome.toml",
-//!         rpm::FileOptions::new("/etc/awesome/config.toml").is_config(),
+//!         rpm::FileOptions::regular("/etc/awesome/config.toml").is_config(),
 //!     )?
 //!     // file mode is inherited from source file
 //!     .with_file(
 //!         "./test_assets/awesome.py",
-//!         rpm::FileOptions::new("/usr/bin/awesome"),
+//!         rpm::FileOptions::regular("/usr/bin/awesome"),
 //!     )?
 //!     .with_file(
 //!         "./test_assets/awesome.toml",
 //!         // you can set a custom mode and custom user too
-//!         rpm::FileOptions::new("/etc/awesome/second.toml")
-//!             .mode(rpm::FileMode::regular(0o644))
+//!         rpm::FileOptions::regular("/etc/awesome/second.toml")
+//!             .permissions(0o644)
 //!             .user("hugo"),
 //!     )?
 //!     .pre_install_script("echo preinst")

src/rpm/builder.rs

@@ -264,17 +264,17 @@ impl PackageBuilder {
     /// let pkg = rpm::PackageBuilder::new("foo", "1.0.0", "Apache-2.0", "x86_64", "some baz package")
     ///     .with_file(
     ///         "./awesome-config.toml",
-    ///         rpm::FileOptions::new("/etc/awesome/config.toml").is_config(),
+    ///         rpm::FileOptions::regular("/etc/awesome/config.toml").is_config(),
     ///     )?
     ///     // file mode is inherited from source file
     ///     .with_file(
     ///         "./awesome-bin",
-    ///         rpm::FileOptions::new("/usr/bin/awesome"),
+    ///         rpm::FileOptions::regular("/usr/bin/awesome"),
     ///     )?
     ///      .with_file(
     ///         "./awesome-config.toml",
     ///         // you can set a custom mode, capabilities and custom user too
-    ///         rpm::FileOptions::new("/etc/awesome/second.toml").mode(0o100744).caps("cap_sys_admin=pe")?.user("hugo"),
+    ///         rpm::FileOptions::regular("/etc/awesome/second.toml").permissions(0o744).caps("cap_sys_admin=pe")?.user("hugo"),
     ///     )?
     ///     .build()?;
     /// # Ok(())
@@ -290,7 +290,7 @@ impl PackageBuilder {
         input.read_to_end(&mut content)?;
         let mut options = options.into();
         if options.inherit_permissions {
-            options.mode = (file_mode(&input)? as i32).into();
+            options.mode = (file_mode(&input)? as i32).try_into()?;
         }
 
         let modified_at = input.metadata()?.modified()?.try_into()?;