diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index acf0111..efb05f2 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -169,7 +169,7 @@ For repositories whose build scripts need a selected Rust toolchain inside Cross `--stop-after` can stop at `inspect`, `metadata`, `verify`, `build`, `package`, `release`, `upload`, or `binstall`. `verify` runs host `cargo check` and `cargo test`; `--skip-tests` skips only tests. A successful Cross build from a clean checkout records its Git commit, package, targets, profile, lock mode, container engine, active Rust toolchain, and binary list. A later run with the same inputs reuses those regular binary files from Cargo's target directory; dirty checkouts, changed inputs, missing files, and invalid cache records build in a fresh target directory instead. `--recompile` explicitly bypasses a matching completed build. `release` creates or reuses the Gitea release; `upload` uploads archives and checksums. The final stage downloads assets anonymously for public repositories or with Gitea authentication for private repositories, checks their checksums and archive layout, and runs isolated `cargo-binstall` installs for public targets. `--skip-binstall-test` skips that install check, while retaining download verification. -`--draft --stop-after upload` is useful when a release must stay private for review. Private repositories require `--skip-binstall-test`; cargo-binstall cannot fetch their attachment URLs, even when Gitea authentication is configured. `--prerelease` and `--draft` set properties when a release is created; reusing a release preserves its existing settings. `-m/--message TEXT` sets release notes, while `--message-file PATH` reads them from a UTF-8 file; they are mutually exclusive. Notes are included when creating a release and replace the body of an existing tagged release when explicitly supplied. Asset replacement is not transactional: if an upload fails after a matching asset is deleted, retry the publication explicitly. +`--draft --stop-after upload` is useful when a release must stay private for review. Private repositories require `--skip-binstall-test`; cargo-binstall cannot fetch their attachment URLs, even when Gitea authentication is configured. `--prerelease` and `--draft` set properties when a release is created; reusing a release preserves its existing settings. `-m/--message TEXT` sets release notes, while `--message-file PATH` reads them from a UTF-8 file; they are mutually exclusive. Notes are included when creating a release and replace the body of an existing tagged release when explicitly supplied. Releases with macOS artifacts automatically append an artifact-specific quarantine-removal section unless the notes already contain a `## macOS Workaround` heading. Asset replacement is not transactional: if an upload fails after a matching asset is deleted, retry the publication explicitly. ## Artifact contract @@ -182,7 +182,7 @@ my-tool-x86_64-unknown-linux-musl-v0.1.0.tgz └── my-tool-helper ``` -Windows archive members have an `.exe` suffix. Raw assets are target-qualified to remain unambiguous, for example `my-tool-x86_64-unknown-linux-musl-v0.1.0` and `my-tool-x86_64-pc-windows-gnu-v0.1.0.exe`. `SHA256SUMS` lists every generated asset. Archive ownership and timestamps are normalized; identical binary bytes and modes produce identical archives. Separate builds can still produce different binaries. +Windows archive members have an `.exe` suffix. Raw assets are target-qualified to remain unambiguous, for example `my-tool-x86_64-unknown-linux-musl-v0.1.0` and `my-tool-x86_64-pc-windows-gnu-v0.1.0.exe`. Apple raw assets omit the dotted version suffix, for example `my-tool-aarch64-apple-darwin`; use the versioned tgz archive by default. `SHA256SUMS` lists every generated asset. Archive ownership and timestamps are normalized; identical binary bytes and modes produce identical archives. Separate builds can still produce different binaries. ## Authentication and security diff --git a/docs/automated-macos-releases.md b/docs/automated-macos-releases.md index 907011a..ad2c5ea 100644 --- a/docs/automated-macos-releases.md +++ b/docs/automated-macos-releases.md @@ -166,14 +166,17 @@ a successful build or create/upload a partial release. ## Artifacts and target-aware verification -Apple binary names have no `.exe` suffix. Existing archive and raw-binary -naming applies unchanged. For version `{version}` and package `tiny-wb`: +Apple binary names have no `.exe` suffix. Versioned tgz archives remain the +recommended download because their internal executable names are ordinary Cargo +binary names. Standalone Apple asset names omit the version so Finder does not +mistake the final dotted version component for a file extension. For version +`{version}` and package `tiny-wb`: ```text tiny-wb-aarch64-apple-darwin-v{version}.tgz -tiny-wb-aarch64-apple-darwin-v{version} +tiny-wb-aarch64-apple-darwin tiny-wb-x86_64-apple-darwin-v{version}.tgz -tiny-wb-x86_64-apple-darwin-v{version} +tiny-wb-x86_64-apple-darwin ``` Each tgz has the cargo-binstall layout: @@ -190,6 +193,17 @@ All local archives are checked before any release creation. Existing remote collision handling, replacement policy, upload, authenticated/private download handling, and checksum verification apply to Apple assets too. +When a release contains Apple artifacts, the publisher adds a +`## macOS Workaround` section to the release body. It is generated from the +artifacts being uploaded: named bundles are preferred, then canonical tgz +archives, with standalone binaries used only when no archive exists. The shell +snippet names the correct architecture, archive, extracted root, and executable +members. It extracts into `~/Downloads`, applies +`xattr -rd com.apple.quarantine` to the complete extracted tree, restores the +executable bits, and starts a GUI executable when one has a `-gui` name. User +notes supplied with `--message` or `--message-file` appear before this section. +An existing `## macOS Workaround` heading prevents a duplicate section. + For every Apple executable, the Linux host parses the Mach-O header and load commands and requires: diff --git a/src/cli.rs b/src/cli.rs index 61ab55f..97142f8 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -109,7 +109,7 @@ pub fn run(mut args: Cli) -> Result<(), Error> { "--prepare-repo is a separate mode; omit --stop-after.".into(), )); } - let release_message = match args.message_file.as_deref() { + let supplied_release_message = match args.message_file.as_deref() { Some(path) => Some(std::fs::read_to_string(path).map_err(|e| { Error(format!( "cannot read release message file {}: {e}", @@ -444,12 +444,15 @@ pub fn run(mut args: Cli) -> Result<(), Error> { } let (api, private) = publication.ok_or_else(|| Error("Publication client was not initialized.".into()))?; + let release_message = + release_message_with_macos_workaround(supplied_release_message.as_deref(), &artifacts)?; let release = api.ensure_release( &tag, &commit, args.draft, args.prerelease, release_message.as_deref(), + supplied_release_message.is_some(), )?; ui::success(format_args!("Release ready: {tag}")); if args.stop_after == Some(Stage::Release) { @@ -482,6 +485,145 @@ pub fn run(mut args: Cli) -> Result<(), Error> { Ok(()) } +fn release_message_with_macos_workaround( + supplied: Option<&str>, + artifacts: &[crate::package::Artifact], +) -> Result, Error> { + const HEADING: &str = "## macOS Workaround"; + if supplied.is_some_and(|message| message.contains(HEADING)) { + return Ok(supplied.map(str::to_owned)); + } + let Some(workaround) = macos_workaround(artifacts)? else { + return Ok(supplied.map(str::to_owned)); + }; + Ok(Some( + match supplied.map(str::trim_end).filter(|s| !s.is_empty()) { + Some(message) => format!("{message}\n\n{workaround}"), + None => workaround, + }, + )) +} + +fn macos_workaround(artifacts: &[crate::package::Artifact]) -> Result, Error> { + use crate::{bundle::Format, package::ArtifactContents}; + + let apple = artifacts + .iter() + .filter(|artifact| build::is_apple(&artifact.target)) + .collect::>(); + if apple.is_empty() { + return Ok(None); + } + let has_bundle = apple + .iter() + .any(|artifact| matches!(artifact.contents, ArtifactContents::Bundle { .. })); + let has_archive = apple + .iter() + .any(|artifact| matches!(artifact.contents, ArtifactContents::Archive { .. })); + let selected = apple.into_iter().filter(|artifact| { + if has_bundle { + matches!(artifact.contents, ArtifactContents::Bundle { .. }) + } else if has_archive { + matches!(artifact.contents, ArtifactContents::Archive { .. }) + } else { + matches!(artifact.contents, ArtifactContents::Binary) + } + }); + let mut sections = Vec::new(); + for artifact in selected { + let filename = artifact + .path + .file_name() + .and_then(|name| name.to_str()) + .ok_or_else(|| Error("Invalid macOS artifact filename".into()))?; + let platform = if artifact.target.starts_with("aarch64-") { + "Apple Silicon" + } else { + "Intel Mac" + }; + let commands = match &artifact.contents { + ArtifactContents::Bundle { + root, + format, + entries, + } => archive_workaround( + filename, + root, + *format, + entries + .iter() + .filter(|entry| entry.mode & 0o111 != 0) + .map(|entry| entry.destination.as_str()), + ), + ArtifactContents::Archive { root, binaries } => archive_workaround( + filename, + root, + Format::Tgz, + binaries.iter().map(String::as_str), + ), + ArtifactContents::Binary => { + let quoted = shell_quote(filename); + format!( + "downloads=\"$HOME/Downloads\"\nexecutable=\"$downloads\"/{quoted}\nxattr -d com.apple.quarantine \"$executable\" 2>/dev/null || true\nchmod +x \"$executable\"\n\"$executable\"" + ) + } + }; + sections.push(format!( + "For **{platform}** (`{filename}`), run in Terminal:\n```sh\n{commands}\n```" + )); + } + if sections.is_empty() { + return Ok(None); + } + Ok(Some(format!( + "## macOS Workaround\n\nIf macOS blocks these downloaded, unsigned executables, remove their quarantine attribute manually after verifying and trusting the release. Download the indicated archive into `~/Downloads`; the commands extract it there, remove quarantine recursively from everything in the extracted directory, restore executable permissions, and start the first executable.\n\n{}", + sections.join("\n\n") + ))) +} + +fn archive_workaround<'a>( + filename: &str, + root: &str, + format: crate::bundle::Format, + executables: impl Iterator, +) -> String { + let filename = shell_quote(filename); + let root = shell_quote(root); + let executables = executables.collect::>(); + let extraction = match format { + crate::bundle::Format::Tgz => "tar -xzf \"$archive\" -C \"$downloads\"", + crate::bundle::Format::Zip => "ditto -x -k \"$archive\" \"$downloads\"", + }; + let paths = executables + .iter() + .map(|path| format!("\"$bundle\"/{}", shell_quote(path))) + .collect::>(); + let chmod = if paths.is_empty() { + String::new() + } else { + format!("\nchmod +x {}", paths.join(" ")) + }; + let launch = paths + .iter() + .zip(executables.iter()) + .find(|(_, executable)| { + executable + .rsplit('/') + .next() + .is_some_and(|name| name.ends_with("-gui")) + }) + .map(|(path, _)| path) + .or_else(|| paths.first()) + .map_or_else(String::new, |path| format!("\n{path}")); + format!( + "downloads=\"$HOME/Downloads\"\narchive=\"$downloads\"/{filename}\n{extraction}\nbundle=\"$downloads\"/{root}\nxattr -rd com.apple.quarantine \"$bundle\"{chmod}{launch}" + ) +} + +fn shell_quote(value: &str) -> String { + format!("'{}'", value.replace('\'', "'\"'\"'")) +} + fn read_token_file(path: &std::path::Path) -> Result { if !path.is_file() { return Err(Error(format!( @@ -516,6 +658,10 @@ fn read_token_file(path: &std::path::Path) -> Result { #[cfg(test)] mod tests { use super::*; + use crate::{ + bundle::{Entry, Format}, + package::{Artifact, ArtifactContents}, + }; use std::{fs, path::Path}; fn write(root: &Path, relative: &str, content: &str) { @@ -634,6 +780,76 @@ mod tests { .is_err()); } + #[test] + fn macos_workaround_uses_actual_bundle_and_quarantines_its_complete_tree() { + let artifacts = vec![ + Artifact { + target: "aarch64-apple-darwin".into(), + path: "dist/pptx-reporter-aarch64-apple-darwin".into(), + contents: ArtifactContents::Binary, + sha256: "0".repeat(64), + }, + Artifact { + target: "aarch64-apple-darwin".into(), + path: "dist/pptx-reporter-portable-aarch64-apple-darwin-v0.1.2.tgz".into(), + contents: ArtifactContents::Bundle { + root: "pptx-reporter-portable-aarch64-apple-darwin-v0.1.2".into(), + format: Format::Tgz, + entries: vec![ + Entry { + destination: "pptx-reporter".into(), + sha256: "1".repeat(64), + mode: 0o755, + }, + Entry { + destination: "pptx-reporter-gui".into(), + sha256: "2".repeat(64), + mode: 0o755, + }, + Entry { + destination: "resources/font.ttf".into(), + sha256: "3".repeat(64), + mode: 0o644, + }, + ], + }, + sha256: "4".repeat(64), + }, + ]; + let message = release_message_with_macos_workaround(Some("Release notes"), &artifacts) + .unwrap() + .unwrap(); + assert!(message.starts_with("Release notes\n\n## macOS Workaround")); + assert!(message.contains("tar -xzf \"$archive\" -C \"$downloads\"")); + assert!(message.contains("xattr -rd com.apple.quarantine \"$bundle\"")); + assert!(message + .contains("chmod +x \"$bundle\"/'pptx-reporter' \"$bundle\"/'pptx-reporter-gui'")); + assert!(message.contains("\n\"$bundle\"/'pptx-reporter-gui'\n```")); + assert!(!message.contains("executable=\"$downloads\"")); + } + + #[test] + fn macos_workaround_is_not_duplicated_or_added_to_other_targets() { + let linux = Artifact { + target: "x86_64-unknown-linux-gnu".into(), + path: "dist/demo.tgz".into(), + contents: ArtifactContents::Archive { + root: "demo".into(), + binaries: vec!["demo".into()], + }, + sha256: "0".repeat(64), + }; + assert_eq!( + release_message_with_macos_workaround(Some("Notes"), &[linux]).unwrap(), + Some("Notes".into()) + ); + let existing = "Notes\n\n## macOS Workaround\n\nCustom instructions"; + assert_eq!( + release_message_with_macos_workaround(Some(existing), &[]).unwrap(), + Some(existing.into()) + ); + } + #[test] fn token_file_accepts_one_token_and_trailing_newlines() { let temp = tempfile::tempdir().unwrap(); diff --git a/src/gitea.rs b/src/gitea.rs index 02fff0c..71e9bdd 100644 --- a/src/gitea.rs +++ b/src/gitea.rs @@ -121,6 +121,7 @@ impl Gitea { draft: bool, prerelease: bool, message: Option<&str>, + replace_existing_message: bool, ) -> Result { let encoded = encode(tag); let remote = self @@ -151,7 +152,7 @@ impl Gitea { }; let release: RemoteRelease = serde_json::from_value(release) .map_err(|_| Error("Gitea release response is missing id or draft state.".into()))?; - if existed { + if existed && replace_existing_message { if let Some(message) = message { self.request( Method::PATCH, @@ -362,7 +363,7 @@ mod tests { ]); let api = Gitea::with_token(&format!("{host}/gitea/team/demo"), "test-token").unwrap(); let release = api - .ensure_release("v0.1.0", "abc", false, true, Some("Release notes")) + .ensure_release("v0.1.0", "abc", false, true, Some("Release notes"), false) .unwrap(); assert_eq!(release.id, 7); let requests = handle.join().unwrap(); @@ -391,7 +392,7 @@ mod tests { ]); let api = Gitea::with_token(&format!("{host}/gitea/team/demo"), "test-token").unwrap(); assert_eq!( - api.ensure_release("v0.1.0", "abc", false, false, Some("Updated notes")) + api.ensure_release("v0.1.0", "abc", false, false, Some("Updated notes"), true,) .unwrap() .id, 9 @@ -456,7 +457,7 @@ mod tests { }]); let api = Gitea::with_token(&format!("{host}/team/demo"), "test-token").unwrap(); let error = api - .ensure_release("v0.1.0", "abc", false, false, None) + .ensure_release("v0.1.0", "abc", false, false, None, false) .unwrap_err() .to_string(); assert!(error.contains("HTTP 401")); @@ -478,7 +479,7 @@ mod tests { }]); let api = Gitea::with_token(&format!("{host}/team/demo"), "test-token").unwrap(); let error = api - .ensure_release("v0.1.0", "abc", false, false, None) + .ensure_release("v0.1.0", "abc", false, false, None, false) .unwrap_err() .to_string(); assert!(error.contains(expected), "{error}"); @@ -546,7 +547,7 @@ mod tests { }]); let api = Gitea::with_token(&format!("{host}/team/demo"), "test-token").unwrap(); assert!(api - .ensure_release("v0.1.0", "abc", false, false, None) + .ensure_release("v0.1.0", "abc", false, false, None, false) .unwrap_err() .to_string() .contains("invalid JSON")); diff --git a/src/policy.rs b/src/policy.rs index e8d23d9..d7496e3 100644 --- a/src/policy.rs +++ b/src/policy.rs @@ -19,7 +19,11 @@ pub fn binary_filename(binary: &str, target: &str) -> String { } pub fn binary_asset_name(binary: &str, target: &str, version: &str) -> String { - binary_filename(&format!("{binary}-{target}-v{version}"), target) + if target.ends_with("-apple-darwin") { + binary_filename(&format!("{binary}-{target}"), target) + } else { + binary_filename(&format!("{binary}-{target}-v{version}"), target) + } } pub fn binstall_metadata(prefix: &str) -> [(&'static str, String); 3] { @@ -52,6 +56,10 @@ mod tests { binary_asset_name("demo", "x86_64-pc-windows-gnu", "0.3.1"), "demo-x86_64-pc-windows-gnu-v0.3.1.exe" ); + assert_eq!( + binary_asset_name("demo", "aarch64-apple-darwin", "0.3.1"), + "demo-aarch64-apple-darwin" + ); let metadata = binstall_metadata("release-"); assert_eq!( metadata[0].1, diff --git a/tests/cli_release_flow.rs b/tests/cli_release_flow.rs index 61a58b0..70b89e6 100644 --- a/tests/cli_release_flow.rs +++ b/tests/cli_release_flow.rs @@ -477,7 +477,7 @@ with open(os.environ['CROSS_LOG'],'a') as stream: stream.write('zig:'+target+'\n assert!(artifact_dir .join(format!("demo-{target}-v2.3.4.tgz")) .is_file()); - let binary = artifact_dir.join(format!("demo-{target}-v2.3.4")); + let binary = artifact_dir.join(format!("demo-{target}")); assert!(binary.is_file()); assert_ne!( fs::metadata(binary).unwrap().permissions().mode() & 0o111,