考察并注释代码 #12
考察并注释代码 #12
Conversation
| build_tarball_stream(XzEncoder::new_stream(f, xz), root)?; | ||
| // 执行压缩操作并对数据流完整性进行查验（以 ? 确保每一个步骤正确完成）： | ||
| // | ||
| // - 使用 into_inner() 确保压缩包内容完整 |
There was a problem hiding this comment.
into_inner 其实不是“确保压缩包内容完整”的意思。请参考 https://docs.rs/xz/latest/xz/read/struct.XzEncoder.html#method.into_inner 对 into_inner 方法的描述
| /// - root（tar 压缩包路径，类型为路径） | ||
| /// - target（目标文件，类型为路径） | ||
| /// | ||
| /// 不同于 archive_xz_tarball 函数，由于 gzip 压缩不支持多线程，因此无需定义 threads 参数 |
There was a problem hiding this comment.
Tip
Rust 的 /// 文档注释支持 Markdown 语法
| pub fn archive_gz_tarball(root: &Path, target: &Path) -> Result<()> { | ||
| // f：使用 File 方式实现在目标路径 target 创建 xz 压缩包文件 |
There was a problem hiding this comment.
这句话不太像是中文。
另外 File 是 Rust 标准库的一个结构体（structure），不是“方式”或“方法”（method）。
| let f = File::create(target)?; | ||
| let builder = build_tarball_stream(GzEncoder::new(f, Compression::best()), root)?; | ||
| // builder: 使用 Builder<GzEncoder<File>> 方式实现 gz 压缩包生成流程 | ||
| // 此处去前面定义的 f（目标文件）作为参数，定义了目标文件路径 |
There was a problem hiding this comment.
| // 此处去前面定义的 f（目标文件）作为参数，定义了目标文件路径 | |
| // 此处使用前面定义的 f（目标文件）作为参数，定义了目标文件路径 |
这里的 f 参数主要作用是提供数据流，而不是路径。路径是传递进来的参数。
| builder.into_inner()?.finish()?.sync_all()?; | ||
|
|
||
| Ok(()) | ||
| } | ||
|
|
||
| /// 生成 tar 包装的压缩包 (.tar.*) 数据流，取两个函数： | ||
| /// | ||
| /// - stream（输入流，W - 循环读取输出直到读取完毕） |
There was a problem hiding this comment.
需要注意的是，这里的 W 不是数据类型。这里使用了 Rust 的泛型（generics）系统。
这里的函数定义了 <W: Write> 这个 trait 限制，使得 stream 参数可以是任何带有/含有 Write 这个 trait 的数据类型。
| // - root 参数用于定义 SquashFS 取用文件的路径 | ||
| // - target 参数用于定义保存 SquashFS 文件的路径 | ||
| // - "-comp xz"：定义压缩方式为 xz，该格式压缩比好且性能较为良好 | ||
| // - "-processors _threads_"：此处取 threads 参数定义压缩线程数，将其 u32 类型转换为系统命令参数 |
There was a problem hiding this comment.
| // - "-processors _threads_"：此处取 threads 参数定义压缩线程数，将其 u32 类型转换为系统命令参数 | |
| // - "-processors _threads_"：此处取 threads 参数定义压缩线程数，将其 u32 类型转换为字符串 |
to_string() 返回类型为 String 。需要注意的是，Rust 里面确实有“系统命令参数”这种类型。详情参见 https://doc.rust-lang.org/stable/std/ffi/struct.OsString.html
| std::io::copy(&mut reader, &mut hasher)?; | ||
|
|
||
| // 返回计算后的 SHA-256 校验和 |
There was a problem hiding this comment.
这里漏写一个步骤：
由于 hasher.finalize() 返回的是二进制结果（文档显示的返回结果是 GenericArray<[u8], Self::OutputSize> 不过你看作 &[u8] 就好），
我们这里需要把它格式化成使用十六进制格式的字符串。这里的 {:x} 格式化描述里面的 x 指的是“hex”，所以就是将数据以十六进制格式输出的意思。
| builder.follow_symlinks(false); | ||
| // 从先前定义的 root 参数（系统根路径）读取文件，并保存到归档的根路径 (.) | ||
| // FIXME: 此处 path 参数为何不使用 /？ |
There was a problem hiding this comment.
FIXME: 此处 path 参数为何不使用 /？
因为此处的 builder 参数是基于宿主设备的，你可以看作 tar 命令归档文件时候的情况。
在归档文件的时候，自然不是基于客户系统的文件路径来的。
| fn build_tarball_stream<W: Write>(stream: W, root: &Path) -> Result<Builder<W>, anyhow::Error> { | ||
| // 使用 Builder<W> 方式实现 tar 压缩流程，即从输入流读取数据并包进 tar 包中 |
There was a problem hiding this comment.
这里的描述不正确。
请注意观察 stream 参数的 trait 限制：这里 stream 参数的限制为 <W: Write> ，并非读取操作。
|
|
||
| // 标准：/etc/apt/sources.list 文件权限位应为 0644 | ||
| // | ||
| // FIXME: 为何需要这样定义？前面使用 write() 写入的文件应该是根据 umask 设置的，默认应为 0644 |
There was a problem hiding this comment.
Rust 标准库内的跨平台 write 函数有时不遵守 umask 定义。
这里是为了安全起见，定死 0644 权限位。
|
I'll do this later... |
本 PR 用于追踪 aoscbootstrap 的注释工作，当前代码注释较少且简略，加之本人在学习 Rust，因此希望通过补充注释来学习代码，并为后续代码审查提供便利
欢迎在 PR 审阅界面标注出不正确或不准确的注释