Documentation improvement

.github/workflows/auto-build.yml

@@ -186,4 +186,4 @@ jobs:
           r2-secret-access-key: ${{ secrets.R2_SECRET_ACCESS_KEY }}
           r2-bucket: ${{ secrets.R2_BUCKET }}
           source-dir: ./dist
-          destination-dir: ./u/v0.1.4/
+          destination-dir: ./u/v0.1.5/

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "seal-updater"
-version = "0.1.4"
+version = "0.1.5"
 authors = ["檀轶步棋"]
 edition = "2021"
 

build.rs

@@ -1,15 +1,15 @@
-#[cfg(target_family = "unix")]
 fn main() {
-
-}
-
-#[cfg(target_family = "windows")]
-fn main() {
-    // dependency, supported OS and privilege are set by default
-    // see documentation for [embed_manifest::new_manifest]
-    embed_manifest::embed_manifest(embed_manifest::new_manifest("SealUpdater"))
-        .expect("failed to create manifest");
-    println!("cargo:rerun-if-changed=build.rs");
+    if cfg!(windows) {
+        // By default, the manifest:
+        //
+        //   - is compatible with from Windows 7 to Windows 11
+        //   - uses "AsInvoker" execution level
+        //   - adds a dependency on Common Controls 6.0.0.0
+        //
+        embed_manifest::embed_manifest(embed_manifest::new_manifest("SealUpdater"))
+            .expect("failed to create manifest");
+        println!("cargo:rerun-if-changed=build.rs");
 
-    static_vcruntime::metabuild();
+        static_vcruntime::metabuild();
+    }
 }

src/runner/decompress.rs

@@ -12,27 +12,36 @@ use crate::global::{CMD_OPT, UPD_NAME};
 
 use super::progress;
 
+/// A wrapper that helps get the count of entries in a GZ archive.
 struct ReseekableArchive(File);
 
 impl ReseekableArchive {
     fn new(file: File) -> Self {
         Self(file)
     }
 
+    /// Gets the count of entries in this file. Does not consume self.
     fn count(&mut self) -> io::Result<usize> {
+        // `decoder` and `archive` hold a reference to the underlying file.
+        // since they are local, this is fine.
         let decoder = GzDecoder::new(&mut self.0);
         let mut archive = tar::Archive::new(decoder);
+
         let count = archive.entries()?.count();
         self.0.seek(SeekFrom::Start(0))?;
+
         Ok(count)
     }
 
+    /// Consumes self and returns the inner archive.
     fn archive(self) -> tar::Archive<GzDecoder<File>> {
         let decoder = GzDecoder::new(self.0);
         tar::Archive::new(decoder)
     }
 }
 
+/// Extract the content from the archive at `src` to `dst`. The source can be a ZIP or
+/// a TAR file; the ZIP format is tried first, then TAR as fallback.
 pub(crate) fn decompress(
     src: impl AsRef<Path>,
     dst: impl AsRef<Path>,
@@ -60,13 +69,15 @@ pub(crate) fn decompress(
             e
         })?;
         let mut archive = ReseekableArchive::new(file);
+
         let count = archive
             .count()
             .map_err(|e| {
                 warn!("无法获取 GZ 压缩包的文件数量: {}", e);
                 e
             })
             .unwrap_or(0);
+
         untar(archive.archive(), dst.as_ref(), count)?;
     }
 
@@ -84,24 +95,28 @@ fn unzip(file: File, target: &Path) -> Result<(), Box<dyn Error>> {
             error!("获取 ZIP 文件 entry 时出现错误: {}", e);
             e
         })?;
+
         if CMD_OPT.verbose {
             progress::ProgressBar::blackout();
             println!("  {} {}", "decompressing:".yellow(), zip_file.name());
             _ = io::stdout().flush();
         }
+
         let name = zip_file
             .enclosed_name()
             .ok_or("文件名不安全，可能导致 zip slip")
             .map_err(|e| {
                 error!("发现不安全的文件名，解压缩终止: {}", e);
                 e
             })?;
+
         let dest = if name.to_string_lossy() != UPD_NAME {
             target.join(name)
         } else {
             target.join("new_updater").join(name)
         };
         make_file(&mut zip_file, &dest)?;
+
         progress_bar.progress();
     }
 
@@ -127,11 +142,13 @@ fn untar<T: Read>(
         error!("获取 GZ 文件 entry 时出现错误: {}", e);
         e
     })?;
+
     for entry in entries {
         let mut tar_file = entry.map_err(|e| {
             error!("获取 GZ 文件 entry 时出现错误: {}", e);
             e
         })?;
+
         let name = tar_file.path().map_err(|e| {
             error!("获取文件名时出现错误: {}", e);
             e
@@ -142,7 +159,6 @@ fn untar<T: Read>(
             println!("  {} {}", "reading:".yellow(), name.to_string_lossy());
             _ = io::stdout().flush();
         }
-        progress_bar.progress();
 
         if !is_path_safe(name.components()) {
             error!("发现不安全的文件名，解压缩终止: {:?}", name);
@@ -155,6 +171,8 @@ fn untar<T: Read>(
             target.join("new_updater").join(name)
         };
         make_file(&mut tar_file, &dest)?;
+
+        progress_bar.progress();
     }
     Ok(())
 }

src/runner/mod.rs

@@ -11,6 +11,8 @@ use crate::{
 mod decompress;
 mod progress;
 
+/// The main upgrade executor. It waits for the main process (if specified) to exit,
+/// renames the old file and extracts new file from the package.
 pub fn upgrade() -> Result<(), Box<dyn Error>> {
     let args = &CMD_OPT;
     if args.pid != 0 {

src/runner/progress.rs

@@ -2,6 +2,7 @@ use std::cmp::max;
 use std::error::Error;
 use std::io::Write;
 
+/// A simple progress bar.
 pub struct ProgressBar {
     max: usize,
     current: usize,
@@ -28,6 +29,7 @@ impl ProgressBar {
         bar_width / 10 * 10
     }
 
+    /// Erases the whole line on terminal.
     pub fn blackout() {
         let width = match term_size::dimensions_stdout() {
             None => 80,
@@ -37,6 +39,7 @@ impl ProgressBar {
         _ = std::io::stdout().flush();
     }
 
+    /// Progresses by one.
     pub fn progress(&mut self) {
         _ = self.progress_by(1);
     }