From fede6bf11451670f40eae2688e84836c64f72452 Mon Sep 17 00:00:00 2001 From: amr-crabnebula Date: Thu, 28 Sep 2023 01:28:19 +0300 Subject: [PATCH] chore: update REAMD and documentation --- README.md | 69 +++++++++++++++++++++++++++++++---- crates/config/Cargo.toml | 1 + crates/packager/Cargo.toml | 11 +++++- crates/packager/README.md | 69 +++++++++++++++++++++++++++++++---- crates/packager/src/config.rs | 3 ++ crates/packager/src/error.rs | 7 +++- crates/packager/src/lib.rs | 61 +++++++++++++++++++++++++++++-- crates/packager/src/sign.rs | 3 ++ crates/updater/Cargo.toml | 2 +- 9 files changed, 204 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 6ad029cb..022b9146 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,79 @@ # cargo-packager -Rust executable packager, bundler and updater. +Rust executable packager, bundler and updater. A tool and library to generate installers or app bundles for your executables. +It also has a comptabile updater through [cargo-packager-updater](https://docs.rs/cargo-packager-updater). -## Installation +## CLI -``` +### Installation + +```sh cargo install cargo-pacakger --locked ``` -## Usage +### Usage -``` +```sh cargo pacakger ``` -## Configuration +### Supported pacakges + +- macOS + - DMG (.dmg) + - Bundle (.app) +- Linux + - Debian package (.deb) + - AppImage (.AppImage) +- Windows + - NSIS (.exe) + - MSI using WiX Toolset (.msi) + +### Configuration By default, `cargo-pacakger` reads configuration from `Packager.toml` or `pacakger.json` if exists, and from `package.metadata.packager` table in `Cargo.toml`. -You can specify a custom configuration file using `-c/--config` flag. All configuration options could be either a single config or array of configs. +You can also specify a custom configuration file using `-c/--config` cli argument. +All configuration options could be either a single config or array of configs. For full list of configuration options, see https://docs.rs/cargo-packager/latest/cargo-packager/struct.Config.html You could also use the schema from GitHub releases to validate your configuration or have auto completions in your IDE. + +### Building your application before packaging + +By default, `cargo-packager` doesn't build your application, it only looks for it inside the directory specified in `config.out_dir` or `--out-dir` cli arg, +However, `cargo-pacakger` has an option to specify a shell command to be executed before packaing your app, `beforePackagingCommand`. + +### Cargo profiles + +By default, `cargo-packager` looks for binaries built using the `debug` profile, if your `beforePackagingCommand` builds your app using `cargo build --release`, you will also need to +run `cargo-pacakger` in release mode `cargo packager --release`, otherwise, if you have a custom cargo profile, you will need to specify it using `--profile` cli arg `cargo pacakger --profile custom-release-profile`. + +For more information, checkout the available [configuration options](https://docs.rs/cargo-packager/latest/cargo-packager/struct.Config.html) and for a list of available CLI +commands and arguments, run `cargo packager --help`. + +## Examples + +The [`examples`](./examples/) directory contains a number of varying examples, if you want to build them all run `cargo r -p cargo-pacakger -- --release` in the root of this repository. Just make sure to have the tooling for each example installed on your system. You can find what tooling they require by checking the README in each example. The README also contains a command to build this example alone if you wish. + +Examples list (non-exhaustive): + +- [`tauri`](./examples/tauri/) +- [`wry`](./examples/wry/) +- [`dioxus`](./examples/dioxus/) +- [`egui`](./examples/egui/) +- [`deno`](./examples/deno/) +- [`slint`](./examples/slint/) + +## Library + +This crate is also published to crates.io as a library that you can integrate into your tooling, just make sure to disable the default-feature flags. + +```sh +cargo add cargo-packager --no-default-features +``` + +#### Feature flags + +- **`cli`**: Enables the CLI specifc features and dependencies. Enabled by default. +- **`tracing`**: Enables `tracing` crate integration. diff --git a/crates/config/Cargo.toml b/crates/config/Cargo.toml index 5aecc752..0da12a66 100644 --- a/crates/config/Cargo.toml +++ b/crates/config/Cargo.toml @@ -4,6 +4,7 @@ version = "0.0.0" description = "Config types for cargo-packager." edition = "2021" license = "Apache-2.0 OR MIT" +repository = "https://github.com/crabnebula-dev/cargo-packager" [features] clap = ["dep:clap"] diff --git a/crates/packager/Cargo.toml b/crates/packager/Cargo.toml index 907d506d..444fb26e 100644 --- a/crates/packager/Cargo.toml +++ b/crates/packager/Cargo.toml @@ -1,9 +1,18 @@ [package] name = "cargo-packager" version = "0.0.0" -description = "Rust executable packager and bundler." +description = "Rust executable packager and bundler CLI and library." edition = "2021" license = "Apache-2.0 OR MIT" +keywords = ["bundle", "package", "cargo"] +categories = [ + "command-line-interface", + "command-line-utilities", + "development-tools::cargo-plugins", + "development-tools::build-utils", + "os", +] +repository = "https://github.com/crabnebula-dev/cargo-packager" [features] default = ["cli"] diff --git a/crates/packager/README.md b/crates/packager/README.md index 4faaa962..d3d75a71 100644 --- a/crates/packager/README.md +++ b/crates/packager/README.md @@ -1,24 +1,77 @@ -# cargo-packager +Rust executable packager, bundler and updater. A tool and library to generate installers or app bundles for your executables. +It also has a comptabile updater through [cargo-packager-updater](https://docs.rs/cargo-packager-updater). -Rust executable packager and bundler CLI and library. +## CLI -## Installation +### Installation -``` +```sh cargo install cargo-pacakger --locked ``` -## Usage +### Usage -``` +```sh cargo pacakger ``` -## Configuration +### Supported pacakges + +- macOS + - DMG (.dmg) + - Bundle (.app) +- Linux + - Debian package (.deb) + - AppImage (.AppImage) +- Windows + - NSIS (.exe) + - MSI using WiX Toolset (.msi) + +### Configuration By default, `cargo-pacakger` reads configuration from `Packager.toml` or `pacakger.json` if exists, and from `package.metadata.packager` table in `Cargo.toml`. -You can specify a custom configuration file using `-c/--config` flag. +You can also specify a custom configuration file using `-c/--config` cli argument. +All configuration options could be either a single config or array of configs. For full list of configuration options, see https://docs.rs/cargo-packager/latest/cargo-packager/struct.Config.html You could also use the schema from GitHub releases to validate your configuration or have auto completions in your IDE. + +### Building your application before packaging + +By default, `cargo-packager` doesn't build your application, it only looks for it inside the directory specified in `config.out_dir` or `--out-dir` cli arg, +However, `cargo-pacakger` has an option to specify a shell command to be executed before packaing your app, `beforePackagingCommand`. + +### Cargo profiles + +By default, `cargo-packager` looks for binaries built using the `debug` profile, if your `beforePackagingCommand` builds your app using `cargo build --release`, you will also need to +run `cargo-pacakger` in release mode `cargo packager --release`, otherwise, if you have a custom cargo profile, you will need to specify it using `--profile` cli arg `cargo pacakger --profile custom-release-profile`. + +For more information, checkout the available [configuration options](https://docs.rs/cargo-packager/latest/cargo-packager/struct.Config.html) and for a list of available CLI +commands and arguments, run `cargo packager --help`. + +## Examples + +The [`examples`](../../examples/) directory contains a number of varying examples, if you want to build them all run `cargo r -p cargo-pacakger -- --release` in the root of this repository. Just make sure to have the tooling for each example installed on your system. You can find what tooling they require by checking the README in each example. The README also contains a command to build this example alone if you wish. + +Examples list (non-exhaustive): + +- [`tauri`](../../examples/tauri/) +- [`wry`](../../examples/wry/) +- [`dioxus`](../../examples/dioxus/) +- [`egui`](../../examples/egui/) +- [`deno`](../../examples/deno/) +- [`slint`](../../examples/slint/) + +## Library + +This crate is also published to crates.io as a library that you can integrate into your tooling, just make sure to disable the default-feature flags. + +```sh +cargo add cargo-packager --no-default-features +``` + +#### Feature flags + +- **`cli`**: Enables the CLI specifc features and dependencies. Enabled by default. +- **`tracing`**: Enables `tracing` crate integration. diff --git a/crates/packager/src/config.rs b/crates/packager/src/config.rs index c9b591c6..298bea77 100644 --- a/crates/packager/src/config.rs +++ b/crates/packager/src/config.rs @@ -1,3 +1,5 @@ +//! Configuration type and associated utilities. + use std::path::{Path, PathBuf}; pub use cargo_packager_config::*; @@ -11,6 +13,7 @@ pub(crate) struct IResource { pub target: PathBuf, } +/// [Config] extenstion trait pub trait ConfigExt { /// Returns the windows specific configuration fn windows(&self) -> Option<&WindowsConfig>; diff --git a/crates/packager/src/error.rs b/crates/packager/src/error.rs index b2dadcb1..5ca72eda 100644 --- a/crates/packager/src/error.rs +++ b/crates/packager/src/error.rs @@ -141,7 +141,9 @@ pub enum Error { /// Invalid framework. #[error("Invalid framework {framework}: {reason}")] InvalidFramework { + /// Framework name framework: String, + /// Reason why this framework is invalid reason: &'static str, }, /// Invalid icons. @@ -158,7 +160,10 @@ pub enum Error { FailedToParseNotarytoolOutput(String), /// Failed to find API key file. #[error("Could not find API key file. Please set the APPLE_API_KEY_PATH environment variables to the path to the {filename} file")] - ApiKeyMissing { filename: String }, + ApiKeyMissing { + /// Filename of the API key. + filename: String, + }, /// Missing notarize environment variables. #[error("Could not find APPLE_ID & APPLE_PASSWORD or APPLE_API_KEY & APPLE_API_ISSUER & APPLE_API_KEY_PATH environment variables found")] MissingNotarizeAuthVars, diff --git a/crates/packager/src/lib.rs b/crates/packager/src/lib.rs index 2c6eea2b..fb6eb10b 100644 --- a/crates/packager/src/lib.rs +++ b/crates/packager/src/lib.rs @@ -1,7 +1,22 @@ -//! cargo-packager is a tool that generates installers or app bundles for rust executables. -//! It supports auto updating through [cargo-update-packager](https://docs.rs/cargo-update-packager). +//! `cargo-packager` is a tool and library to generate installers or app bundles for your executables. +//! It also has a comptabile updater through [cargo-packager-updater](https://docs.rs/cargo-packager-updater). +//! +//! ## CLI +//! +//! ### Installation +//! +//! ```sh +//! cargo install cargo-pacakger --locked +//! ``` +//! +//! ### Usage +//! +//! ```sh +//! cargo pacakger +//! ``` +//! +//! ### Supported pacakges //! -//! # Platform support //! - macOS //! - DMG (.dmg) //! - Bundle (.app) @@ -9,9 +24,47 @@ //! - Debian package (.deb) //! - AppImage (.AppImage) //! - Windows -//! - MSI using WiX Toolset (.msi) //! - NSIS (.exe) +//! - MSI using WiX Toolset (.msi) +//! +//! ### Configuration +//! +//! By default, `cargo-pacakger` reads configuration from `Packager.toml` or `pacakger.json` if exists, and from `package.metadata.packager` table in `Cargo.toml`. +//! You can also specify a custom configuration file using `-c/--config` cli argument. +//! All configuration options could be either a single config or array of configs. +//! +//! For full list of configuration options, see [config::Config] +//! +//! You could also use the schema from GitHub releases to validate your configuration or have auto completions in your IDE. +//! +//! ### Building your application before packaging +//! +//! By default, `cargo-packager` doesn't build your application, it only looks for it inside the directory specified in `config.out_dir` or `--out-dir` cli arg, +//! However, `cargo-pacakger` has an option to specify a shell command to be executed before packaing your app, `beforePackagingCommand`. +//! +//! ### Cargo profiles +//! +//! By default, `cargo-packager` looks for binaries built using the `debug` profile, if your `beforePackagingCommand` builds your app using `cargo build --release`, you will also need to +//! run `cargo-pacakger` in release mode `cargo packager --release`, otherwise, if you have a custom cargo profile, you will need to specify it using `--profile` cli arg `cargo pacakger --profile custom-release-profile`. +//! +//! For more information, checkout the available [configuration options](config::Config) and for a list of available CLI +//! commands and arguments, run `cargo packager --help`. +//! +//! ## Library +//! +//! This crate is also published to crates.io as a library that you can integrate into your tooling, just make sure to disable the default-feature flags. +//! +//! ```sh +//! cargo add cargo-packager --no-default-features +//! ``` +//! +//! #### Feature flags +//! +//! - **`cli`**: Enables the CLI specifc features and dependencies. Enabled by default. +//! - **`tracing`**: Enables `tracing` crate integration. + #![cfg_attr(doc_cfg, feature(doc_cfg))] +#![deny(missing_docs)] use std::path::PathBuf; diff --git a/crates/packager/src/sign.rs b/crates/packager/src/sign.rs index a434580b..b81a5372 100644 --- a/crates/packager/src/sign.rs +++ b/crates/packager/src/sign.rs @@ -14,9 +14,12 @@ use minisign::{sign, KeyPair as KP, SecretKey, SecretKeyBox}; use crate::util; +/// A public and secret key pair. #[derive(Clone, Debug)] pub struct KeyPair { + /// Publick key pub pk: String, + /// Secret key pub sk: String, } diff --git a/crates/updater/Cargo.toml b/crates/updater/Cargo.toml index e30fc4f1..a72a9be5 100644 --- a/crates/updater/Cargo.toml +++ b/crates/updater/Cargo.toml @@ -4,6 +4,6 @@ version = "0.0.0" description = "Rust executable updater." edition = "2021" license = "Apache-2.0 OR MIT" - +repository = "https://github.com/crabnebula-dev/cargo-packager" [dependencies]