Shell Completion Script and Manpage generation
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
src
tests
.appveyor.yml
.clog.toml
.gitignore
.mention-bot
.travis.yml
CHANGELOG.md
CONTRIBUTORS.md
Cargo.toml
LICENSE-APACHE
LICENSE-MIT
README.md
justfile
rustfmt.toml

README.md

clap_generate

Crates.io Crates.io licenselicense Join the chat at https://gitter.im/clap-rs/clap_generate

Linux: Build Status Windows: Build status

Table of Contents

Created by gh-md-toc

What's New

For full details, see CHANGELOG.md

About

FAQ

Features

Quick Example

Usage

Optional Dependencies / Features

Features enabled by default

Opt-in features

Dependencies Tree

More Information

How to Contribute

Details on how to contribute can be found in the CONTRIBUTING.md file.

Compatibility Policy

Because clap_generate takes SemVer and compatibility seriously, this is the official policy regarding breaking changes and minimum required versions of Rust.

clap_generate will pin the minimum required version of Rust to the CI builds. Bumping the minimum version of Rust is considered a minor breaking change, meaning at a minimum the minor version of clap_generate will be bumped.

In order to keep from being surprised of breaking changes, it is highly recommended to use the ~major.minor.patch style in your Cargo.toml only if you wish to target a version of Rust that is older than current stable minus two releases:

[dependencies]
clap_generate = "~3.0.0"

This will cause only the patch version to be updated upon a cargo update call, and therefore cannot break due to new features, or bumped minimum versions of Rust.

Warning about '~' Dependencies

Using ~ can cause issues in certain circumstances.

From @alexcrichton:

Right now Cargo's version resolution is pretty naive, it's just a brute-force search of the solution space, returning the first resolvable graph. This also means that it currently won't terminate until it proves there is not possible resolvable graph. This leads to situations where workspaces with multiple binaries, for example, have two different dependencies such as:

# In one Cargo.toml
[dependencies]
clap_generate = "~3.0.0"

# In another Cargo.toml
[dependencies]
clap_generate = "3.0.0"

This is inherently an unresolvable crate graph in Cargo right now. Cargo requires there's only one major version of a crate, and being in the same workspace these two crates must share a version. This is impossible in this location, though, as these version constraints cannot be met.

Minimum Version of Rust

clap_generate will officially support current stable Rust, minus two releases, but may work with prior releases as well. For example, current stable Rust at the time of this writing is 1.27.0, meaning clap_generate is guaranteed to compile with 1.25.0 and beyond (although in practice clap_generate is much more conservative).

At the 1.28.0 stable release, clap_generate will be guaranteed to compile with 1.26.0 and beyond, etc.

Upon bumping the minimum version of Rust (assuming it's within the stable-2 range), it must be clearly annotated in the CHANGELOG.md

Breaking Changes

clap_generate takes a similar policy to Rust and will bump the major version number upon breaking changes with only the following exceptions:

  • The breaking change is to fix a security concern
  • The breaking change is to be fixing a bug (i.e. relying on a bug as a feature)
  • The breaking change is a feature isn't used in the wild, or all users of said feature have given approval prior to the change

License

clap_generate is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See the LICENSE-APACHE and LICENSE-MIT files in this repository for more information.

Related Crates

There are several excellent crates which can be used with clap, I recommend checking them all out! If you've got a crate that would be a good fit to be used with clap open an issue and let me know, I'd love to add it!

  • clap - The main clap crate!
  • clap_derive - This crate allows you to define a struct, and build a CLI from it! No more "stringly typed" and it uses clap behind the scenes
  • assert_cli - This crate allows you test your CLIs in a very intuitive and functional way!

Recent Breaking Changes

Deprecations