From 8866d903a949fbd6425dca5013e951893ef1cb6b Mon Sep 17 00:00:00 2001 From: Wolf Vollprecht Date: Sun, 23 Jul 2023 17:13:43 +0200 Subject: [PATCH] add documentation to all the crates --- crates/rattler/src/install/apple_codesign.rs | 2 ++ crates/rattler/src/install/link.rs | 12 ++++++++++ crates/rattler/src/install/mod.rs | 24 ++++++++++++++++++++ crates/rattler/src/lib.rs | 1 + crates/rattler/src/package_cache.rs | 1 + crates/rattler/src/validation.rs | 12 ++++++++++ crates/rattler_macros/src/lib.rs | 4 ++++ 7 files changed, 56 insertions(+) diff --git a/crates/rattler/src/install/apple_codesign.rs b/crates/rattler/src/install/apple_codesign.rs index b91bad257..acf06daac 100644 --- a/crates/rattler/src/install/apple_codesign.rs +++ b/crates/rattler/src/install/apple_codesign.rs @@ -1,3 +1,5 @@ +//! Code signing for Apple Silicon binaries + use super::LinkFileError; use std::path::Path; diff --git a/crates/rattler/src/install/link.rs b/crates/rattler/src/install/link.rs index 2440377ca..a5c110642 100644 --- a/crates/rattler/src/install/link.rs +++ b/crates/rattler/src/install/link.rs @@ -1,3 +1,5 @@ +//! This module contains the logic to link a give file from the package cache into the target directory. +//! See [`link_file`] for more information. use crate::install::python::PythonInfo; use rattler_conda_types::package::{FileMode, PathType, PathsEntry, PrefixPlaceholder}; use rattler_conda_types::{NoArchType, Platform}; @@ -10,29 +12,39 @@ use std::path::{Path, PathBuf}; use super::apple_codesign::{codesign, AppleCodeSignBehavior}; +/// Errors that can occur when calling [`link_file`]. #[derive(Debug, thiserror::Error)] pub enum LinkFileError { + /// An IO error occurred. #[error(transparent)] IoError(#[from] std::io::Error), + /// The parent directory of the destination file could not be created. #[error("failed to create parent directory")] FailedToCreateParentDirectory(#[source] std::io::Error), + /// The source file could not be opened. #[error("could not open source file")] FailedToOpenSourceFile(#[source] std::io::Error), + /// The source file metadata could not be read. #[error("could not source file metadata")] FailedToReadSourceFileMetadata(#[source] std::io::Error), + /// The destination file could not be opened. #[error("could not open destination file for writing")] FailedToOpenDestinationFile(#[source] std::io::Error), + /// The permissions could not be updated on the destination file. #[error("could not update destination file permissions")] FailedToUpdateDestinationFilePermissions(#[source] std::io::Error), + /// The binary (dylib or executable) could not be signed (codesign -f -s -) on + /// macOS ARM64 (Apple Silicon). #[error("failed to sign Apple binary")] FailedToSignAppleBinary, + /// No Python version was specified when installing a noarch package. #[error("cannot install noarch python files because there is no python version specified ")] MissingPythonInfo, } diff --git a/crates/rattler/src/install/mod.rs b/crates/rattler/src/install/mod.rs index 300c5644a..4e816620a 100644 --- a/crates/rattler/src/install/mod.rs +++ b/crates/rattler/src/install/mod.rs @@ -1,3 +1,18 @@ +//! This module contains the logic to install a package into a prefix. The main entry point is the +//! [`link_package`] function. +//! +//! The [`link_package`] function takes a package directory and a target directory. The package +//! directory is the directory that contains the extracted package archive. The target directory is +//! the directory into which the package should be installed. The target directory is also called +//! the "prefix". +//! +//! The [`link_package`] function will read the `paths.json` file from the package directory and +//! link all files specified in that file into the target directory. The `paths.json` file contains +//! a list of files that should be installed and how they should be installed. For example, the +//! `paths.json` file might contain a file that should be copied into the target directory. Or it +//! might contain a file that should be linked into the target directory. The `paths.json` file +//! also contains a SHA256 hash for each file. This hash is used to verify that the file was not +//! tampered with. pub mod apple_codesign; mod driver; mod entry_point; @@ -34,30 +49,39 @@ use tracing::instrument; /// An error that might occur when installing a package. #[derive(Debug, thiserror::Error)] pub enum InstallError { + /// The operation was cancelled. #[error("the operation was cancelled")] Cancelled, + /// The paths.json file could not be read. #[error("failed to read 'paths.json'")] FailedToReadPathsJson(#[source] std::io::Error), + /// The index.json file could not be read. #[error("failed to read 'index.json'")] FailedToReadIndexJson(#[source] std::io::Error), + /// The link.json file could not be read. #[error("failed to read 'link.json'")] FailedToReadLinkJson(#[source] std::io::Error), + /// A file could not be linked. #[error("failed to link '{0}'")] FailedToLink(PathBuf, #[source] LinkFileError), + /// The target prefix is not UTF-8. #[error("target prefix is not UTF-8")] TargetPrefixIsNotUtf8, + /// Failed to create the target directory. #[error("failed to create target directory")] FailedToCreateTargetDirectory(#[source] std::io::Error), + /// A noarch package could not be installed because no python version was specified. #[error("cannot install noarch python package because there is no python version specified")] MissingPythonInfo, + /// Failed to create a python entry point for a noarch package. #[error("failed to create Python entry point")] FailedToCreatePythonEntryPoint(#[source] std::io::Error), } diff --git a/crates/rattler/src/lib.rs b/crates/rattler/src/lib.rs index cd8da68a0..e437713c8 100644 --- a/crates/rattler/src/lib.rs +++ b/crates/rattler/src/lib.rs @@ -8,6 +8,7 @@ //! in a wide variaty of tools that do not rely on Python. Rust has excellent support for //! interfacing with many other languages (WASM, Javascript, Python, C, etc) and is therefor a good //! candidate for a reimplementation. +#![deny(missing_docs)] use std::path::PathBuf; diff --git a/crates/rattler/src/package_cache.rs b/crates/rattler/src/package_cache.rs index ae0ee849d..b611900b0 100644 --- a/crates/rattler/src/package_cache.rs +++ b/crates/rattler/src/package_cache.rs @@ -79,6 +79,7 @@ struct Package { /// An error that might be returned from one of the caching function of the [`PackageCache`]. #[derive(Debug, Clone, thiserror::Error)] pub enum PackageCacheError { + /// An error occurred while fetching the package. #[error(transparent)] FetchError(#[from] Arc), } diff --git a/crates/rattler/src/validation.rs b/crates/rattler/src/validation.rs index 443791ff3..557aa045c 100644 --- a/crates/rattler/src/validation.rs +++ b/crates/rattler/src/validation.rs @@ -22,18 +22,23 @@ use std::{ /// corrupted. #[derive(Debug, thiserror::Error)] pub enum PackageValidationError { + /// Neither a `paths.json` file nor a deprecated `files` file was found. #[error("neither a 'paths.json' or a deprecated 'files' file was found")] MetadataMissing, + /// An error occurred while reading the `paths.json` file. #[error("failed to read 'paths.json' file")] ReadPathsJsonError(#[source] std::io::Error), + /// An error occurred while reading the deprecated `files` file. #[error("failed to read validation data from deprecated files")] ReadDeprecatedPathsJsonError(#[source] std::io::Error), + /// The path seems to be corrupted. #[error("the path '{0}' seems to be corrupted")] CorruptedEntry(PathBuf, #[source] PackageEntryValidationError), + /// An error occurred while reading the `index.json` file. #[error("failed to read 'index.json'")] ReadIndexJsonError(#[source] std::io::Error), } @@ -41,24 +46,31 @@ pub enum PackageValidationError { /// An error that indicates that a specific file in a package archive directory seems to be corrupted. #[derive(Debug, thiserror::Error)] pub enum PackageEntryValidationError { + /// An error occurred while reading the metadata of the file. #[error("failed to retrieve file metadata'")] GetMetadataFailed(#[source] std::io::Error), + /// The file does not exist. #[error("the file does not exist")] NotFound, + /// The file is not a symbolic link. #[error("expected a symbolic link")] ExpectedSymlink, + /// The file is not a directory. #[error("expected a directory")] ExpectedDirectory, + /// The size of the file does not match the expected size. #[error("incorrect size, expected {0} but file on disk is {1}")] IncorrectSize(u64, u64), + /// An IO error occurred while reading the file. #[error("an io error occurred")] IoError(#[from] std::io::Error), + /// The SHA256 hash of the file does not match the expected hash. #[error("sha256 hash mismatch, expected '{0}' but file on disk is '{1}'")] HashMismatch(String, String), } diff --git a/crates/rattler_macros/src/lib.rs b/crates/rattler_macros/src/lib.rs index c1de153cc..17e9e954a 100644 --- a/crates/rattler_macros/src/lib.rs +++ b/crates/rattler_macros/src/lib.rs @@ -1,3 +1,7 @@ +//! Some macros for the Rattler project. + +#![deny(missing_docs)] + use proc_macro::TokenStream; use quote::quote_spanned; use syn::{parse_macro_input, Data, DeriveInput, Fields, FieldsNamed, Ident};