Mark cli args as non_exhaustive and warn that cli mod doesnt prov…

…ide 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
esp-rs · Dec 21, 2023 · 2665054 · 2665054
1 parent a8ce6d9
commit 2665054
Show file tree

Hide file tree

Showing 5 changed files with 56 additions and 19 deletions.
diff --git 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,26 +148,25 @@ 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<String>,
-
     /// Input partition table
     #[arg(long, value_name = "FILE")]
     pub partition_table: Option<PathBuf>,
-
     /// Specify a (binary) package within a workspace which may provide a partition table
     #[arg(long)]
     pub package: Option<String>,
 }
 
 /// 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<ImageFormatKind>,
-
     #[clap(flatten)]
     build_args: BuildArgs,
     #[clap(flatten)]

diff --git 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
@@ -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<String>,
-
     /// Input partition table
     #[arg(long, value_name = "FILE")]
     pub partition_table: Option<PathBuf>,
 }
 
 #[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
@@ -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,13 +77,15 @@ 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,
 }
 
 /// 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
@@ -25,19 +25,20 @@
 //! [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
 //! `raspberry` feature to allow your dependent application to use the Raspberry
 //! 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