-
-
Notifications
You must be signed in to change notification settings - Fork 1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Upgrading to clap v3 and the derive API with the current docs is painful #3490
Comments
As a workaround until the docs are up to speed, the derive API is largely based on In fact, structopt's docs have this to say:
@epage in fact, adding a short note linking to structopt might be a decent stopgap. |
It looks like you were trying to both migrate from clap 2 to clap 3 and from builder to derive at the same time. I would recommend doing these one at a time. I might even recommend clap 2 to clap 3.0 to clap 3.1 to derive. Having too many variables at play when porting between things makes it harder to follow and harder to root cause failures. I think this would have also made it easier to understand what the deprecation messages was intending.
The derive reference is linked to directly from docs.rs/clap and our README. Any input on why that was missed so we can explore how to make that more discoverable?
This is in the introductory section of the tutorial. Any thoughts on why you missed this and what we can do to improve the discoverability?
There is only one set of deprecation messages, so we have to give them from the perspective of the builder API.
The tutorial is a more appropriate starting off point when someone is selecting an API. And we link from the tutorial, docs.rs/clap, and the README to the derive, so I think I'd rather focus on simpler messaging here rather than linking to all related documentation,
As I said earlier, those are going away. Overall in the derive reference, we are focusing on the principles for how the API works (how to map between derive and builder) rather than trying to document how each item in the builder API gets exposed in the derive API.
In the past, our examples were just code samples with inline documentation. Our examples were broken for a long time. I know the current system isn't perfect but this is a way we can have tests for our examples to keep them up to date. I also think seeing real-world output helps make it clear what the code is doing. One option we have considered for this is if we switched to
I get this. On the flip side is the maintenance and verification involved in updating past messages. |
Everything covered in the structopt documentation is covered in clap documentation. I'd rather focus on improving that than punting to incompatible documentation that will just lead to more confusion |
With all of that said, we do have an open issue for the derive documentation. I appreciate the user report and wanted to directly respond to your feedback but I would prefer if we move any further conversation over to that. |
One of the concerns in clap-rs#3490 was the finding of derive reference. Having it at the end for a "next step" seems appropriate.
Hi! Thank you for all your work on Clap :-)
I'm in the process of converting a Clap v2 app to Clap v3.1.0.
I decided to use the new derive API, since https://docs.rs/clap/latest/clap/#selecting-an-api describes it as:
As the first part of migrating, I wanted to configure the app settings using the derive API.
Our existing clap v2 implementation does:
Following the derive tutorial, I found an example for app settings, in
02_app_settings.rs
:clap/examples/tutorial_derive/02_app_settings.rs
Lines 7 to 8 in f7b5cdc
As such, in order to set
AppSettings::GlobalVersion
I tried using:However this gave a deprecation warning:
Trying that suggestion (ie:
s/GlobalVersion/PropagateVersion/
in the snippet above) gave yet another deprecation warning:Trying that suggestion, resulted in code that doesn't compile:
After that, I tried looking on https://docs.rs/clap/latest/clap/ to see if there was a reference about how to map builder API names to derive API names, but the only useful content on there I could find was links back to the tutorial.
Revisiting the tutorial, I noticed this (which I'd missed first time around, since it's pretty hard to spot):
However looking at that derive reference page, there are zero references to (or examples of)
global_setting
, and no mention of how to useCommand::*
settings.After that, I tried searching the repo for
global_setting
to see if there were additional examples (eg https://github.com/clap-rs/clap/search?q=global_setting), however that only turned up usages of the deprecated syntax, eg:clap/tests/derive/structopt.rs
Line 9 in 416ac71
Eventually, searching for
propagate_version
I found this usage in a later tutorial step, which seems to be what I need:clap/examples/tutorial_derive/03_04_subcommands.rs
Line 5 in 7aa4566
Since the tutorial only links to examples, rather than inlining them in the markdown, I hadn't seen that, since I hadn't gotten as subcommands yet.
Anyway, sorry for the long form issue - I just thought it would be useful to describe the discovery steps I went through - since the process of using Clap v3 with the derive API is really very painful/frustrating at the moment - and it's hard to capture the intersection of several rough edges via individual bug reports.
I'm just left feeling a bit puzzled that the project docs landing page seems to be encouraging people to use the derive API, when most of the docs, deprecation messages, changelog entries etc seem to only reference the builder API, with the derive API seemingly a second class citizen, that's much harder for Clap beginners to use?
Things that may help:
global_setting
andsetting
etc.AppSettings::GlobalVersion
(and any others like it) so they don't suggest using an API which itself is also deprecated.Many thanks!
The text was updated successfully, but these errors were encountered: