From 26650544c7a9782697b32785388cc4bbbffc5e14 Mon Sep 17 00:00:00 2001 From: Sergio Gasquez Arcos Date: Thu, 21 Dec 2023 09:14:58 +0100 Subject: [PATCH] Mark cli args as `non_exhaustive` and warn that `cli` mod doesnt provide SemVer guarantees. (#517) * docs: Add warnings that cli mod does not provide semver guarantees * feat: Mark cli args as non_exhaustive * docs: Update cli warning --- cargo-espflash/src/main.rs | 8 +++---- espflash/README.md | 42 +++++++++++++++++++++++++++--------- espflash/src/bin/espflash.rs | 6 ++++-- espflash/src/cli/mod.rs | 12 +++++++++++ espflash/src/lib.rs | 7 +++--- 5 files changed, 56 insertions(+), 19 deletions(-) diff --git a/cargo-espflash/src/main.rs b/cargo-espflash/src/main.rs index 702c6a43..a33f43a6 100644 --- a/cargo-espflash/src/main.rs +++ b/cargo-espflash/src/main.rs @@ -109,6 +109,7 @@ enum Commands { } #[derive(Debug, Args)] +#[non_exhaustive] struct BuildArgs { /// Binary to build and flash #[arg(long)] @@ -147,19 +148,17 @@ struct BuildArgs { /// Erase named partitions based on provided partition table #[derive(Debug, Args)] +#[non_exhaustive] pub struct ErasePartsArgs { /// Connection configuration #[clap(flatten)] pub connect_args: ConnectArgs, - /// Labels of the partitions to be erased #[arg(value_name = "LABELS", value_delimiter = ',')] pub erase_parts: Vec, - /// Input partition table #[arg(long, value_name = "FILE")] pub partition_table: Option, - /// Specify a (binary) package within a workspace which may provide a partition table #[arg(long)] pub package: Option, @@ -167,6 +166,7 @@ pub struct ErasePartsArgs { /// Build and flash an application to a target device #[derive(Debug, Args)] +#[non_exhaustive] struct FlashArgs { #[clap(flatten)] build_args: BuildArgs, @@ -177,11 +177,11 @@ struct FlashArgs { } #[derive(Debug, Args)] +#[non_exhaustive] struct SaveImageArgs { /// Image format to flash #[arg(long, value_enum)] pub format: Option, - #[clap(flatten)] build_args: BuildArgs, #[clap(flatten)] diff --git a/espflash/README.md b/espflash/README.md index a836975c..cdeb30d3 100644 --- a/espflash/README.md +++ b/espflash/README.md @@ -11,15 +11,18 @@ Supports the **ESP32**, **ESP32-C2/C3/C6**, **ESP32-H2**, **ESP32-S2/S3**, and * ## Table of Contents -- [Installation](#installation) -- [Usage](#usage) - - [Permissions on Linux](#permissions-on-linux) - - [Windows Subsystem for Linux](#windows-subsystem-for-linux) - - [Cargo Runner](#cargo-runner) -- [Configuration File](#configuration-file) - - [Configuration examples](#configuration-examples) -- [License](#license) - - [Contribution](#contribution) +- [espflash](#espflash) + - [Table of Contents](#table-of-contents) + - [Installation](#installation) + - [Usage](#usage) + - [Permissions on Linux](#permissions-on-linux) + - [Windows Subsystem for Linux](#windows-subsystem-for-linux) + - [Cargo Runner](#cargo-runner) + - [Using `espflash` as a Library](#using-espflash-as-a-library) + - [Configuration File](#configuration-file) + - [Configuration Examples](#configuration-examples) + - [License](#license) + - [Contribution](#contribution) ## Installation @@ -93,7 +96,7 @@ Check your Linux distribution’s documentation for more information. ### Windows Subsystem for Linux -It is _not_ currently possible to use `cargo-espflash` from within WSL1. There are no plans to add support for WSL1 at this time. +It is _not_ currently possible to use `espflash` from within WSL1. There are no plans to add support for WSL1 at this time. It is also _not_ possible to flash chips using the built-in `USB_SERIAL_JTAG` peripheral when using WSL2, because resetting also resets `USB_SERIAL_JTAG` peripheral, which then disconnects the chip from WSL2. Chips _can_ be flashed via UART using WSL2, however. @@ -108,6 +111,25 @@ runner = "espflash flash --baud=921600 --monitor /dev/ttyUSB0" With this configuration you can flash and monitor you application using `cargo run`. +## Using `espflash` as a Library + +`espflash` can be used as a library in other applications: +```toml +espflash = { version = "2.1", default-features = false } +``` +or `cargo add espflash --no-default-features` + +> **Warning** +> Note that the `cli` module does not provide SemVer guarantees. + +We disable the `default-features` to opt-out the `cli` feature, which is enabled by default; you likely will not need any of these types or functions in your application so there’s no use pulling in the extra dependencies. + +Just like when using `espflash` as an application, you can enable the raspberry feature to allow your dependent application to use the Raspberry Pi’s built-in UART: + +```toml +espflash = { version = "2.1", default-features = false, features = ["raspberry"] } +``` + ## Configuration File It's possible to specify a serial port and/or USB VID/PID values by setting them in a configuration file. The location of this file differs based on your operating system: diff --git a/espflash/src/bin/espflash.rs b/espflash/src/bin/espflash.rs index 9cb4fc64..3488a242 100644 --- a/espflash/src/bin/espflash.rs +++ b/espflash/src/bin/espflash.rs @@ -87,21 +87,21 @@ enum Commands { /// Erase named partitions based on provided partition table #[derive(Debug, Args)] +#[non_exhaustive] pub struct ErasePartsArgs { /// Connection configuration #[clap(flatten)] pub connect_args: ConnectArgs, - /// Labels of the partitions to be erased #[arg(value_name = "LABELS", value_delimiter = ',')] pub erase_parts: Vec, - /// Input partition table #[arg(long, value_name = "FILE")] pub partition_table: Option, } #[derive(Debug, Args)] +#[non_exhaustive] struct FlashArgs { /// Connection configuration #[clap(flatten)] @@ -117,6 +117,7 @@ struct FlashArgs { } #[derive(Debug, Args)] +#[non_exhaustive] struct SaveImageArgs { /// ELF image to flash image: PathBuf, @@ -133,6 +134,7 @@ struct SaveImageArgs { /// Writes a binary file to a specific address in the chip's flash #[derive(Debug, Args)] +#[non_exhaustive] struct WriteBinArgs { /// Address at which to write the binary file #[arg(value_parser = parse_uint32)] diff --git a/espflash/src/cli/mod.rs b/espflash/src/cli/mod.rs index 16583a47..3a2aad94 100644 --- a/espflash/src/cli/mod.rs +++ b/espflash/src/cli/mod.rs @@ -4,6 +4,9 @@ //! and [espflash] command-line applications, and are likely not of much use //! otherwise. //! +//! Important note: The cli module DOES NOT provide SemVer guarantees, +//! feel free to opt-out by disabling the default `cli` feature. +//! //! [cargo-espflash]: https://crates.io/crates/cargo-espflash //! [espflash]: https://crates.io/crates/espflash @@ -45,6 +48,7 @@ mod serial; /// Establish a connection with a target device #[derive(Debug, Args)] +#[non_exhaustive] pub struct ConnectArgs { /// Baud rate at which to communicate with target device #[arg(short = 'b', long, env = "ESPFLASH_BAUD")] @@ -73,6 +77,7 @@ pub struct ConnectArgs { /// Generate completions for the given shell #[derive(Debug, Args)] +#[non_exhaustive] pub struct CompletionsArgs { /// Shell to generate completions for. pub shell: Shell, @@ -80,6 +85,7 @@ pub struct CompletionsArgs { /// Erase entire flash of target device #[derive(Debug, Args)] +#[non_exhaustive] pub struct EraseFlashArgs { /// Connection configuration #[clap(flatten)] @@ -88,6 +94,7 @@ pub struct EraseFlashArgs { /// Erase specified region of flash #[derive(Debug, Args)] +#[non_exhaustive] pub struct EraseRegionArgs { /// Connection configuration #[clap(flatten)] @@ -102,6 +109,7 @@ pub struct EraseRegionArgs { /// Configure communication with the target device's flash #[derive(Debug, Args)] +#[non_exhaustive] pub struct FlashConfigArgs { /// Flash frequency #[arg(short = 'f', long, value_name = "FREQ", value_enum)] @@ -116,6 +124,7 @@ pub struct FlashConfigArgs { /// Flash an application to a target device #[derive(Debug, Args)] +#[non_exhaustive] #[group(skip)] pub struct FlashArgs { /// Path to a binary (.bin) bootloader file @@ -155,6 +164,7 @@ pub struct FlashArgs { /// Operations for partitions tables #[derive(Debug, Args)] +#[non_exhaustive] pub struct PartitionTableArgs { /// Optional output file name, if unset will output to stdout #[arg(short = 'o', long, value_name = "FILE")] @@ -172,6 +182,7 @@ pub struct PartitionTableArgs { /// Save the image to disk instead of flashing to device #[derive(Debug, Args)] +#[non_exhaustive] #[group(skip)] pub struct SaveImageArgs { /// Custom bootloader for merging @@ -201,6 +212,7 @@ pub struct SaveImageArgs { /// Open the serial monitor without flashing #[derive(Debug, Args)] +#[non_exhaustive] pub struct MonitorArgs { /// Connection configuration #[clap(flatten)] diff --git a/espflash/src/lib.rs b/espflash/src/lib.rs index b0e4cff6..1585c876 100644 --- a/espflash/src/lib.rs +++ b/espflash/src/lib.rs @@ -25,11 +25,12 @@ //! [espflash] can also be used as a library: //! //! ```toml -//! espflash = { version = "2.0", default-features = false } +//! espflash = { version = "2.1", default-features = false } //! ``` //! //! We add `default-features` here to disable the `cli` feature, which is -//! enabled by default; you likely will not need any of these types or functions +//! enabled by default. Its important to note that the cli module does not +//! provide SemVer guarantees. You likely will not need any of these types or functions //! in your application so there's no use pulling in the extra dependencies. //! //! Just like when using [espflash] as an application, you can enable the @@ -37,7 +38,7 @@ //! Pi's built-in UART: //! //! ```toml -//! espflash = { version = "2.0", default-features = false, features = ["raspberry"] } +//! espflash = { version = "2.1", default-features = false, features = ["raspberry"] } //! ``` //! //! [espflash]: https://crates.io/crates/espflash