diff --git a/book/src/concepts.md b/book/src/concepts.md index 70ff7ae45..a419b6a2a 100644 --- a/book/src/concepts.md +++ b/book/src/concepts.md @@ -47,7 +47,7 @@ Ok so you've defined your App, but what should we actually build for it? Let's l [workspace.metadata.dist] # The preferred cargo-dist version to use in CI (Cargo.toml SemVer syntax) cargo-dist-version = "0.0.3" -# CI backends to support (see 'cargo dist generate-ci') +# CI backends to support ci = ["github"] # The installers to generate for each app installers = ["shell", "powershell"] diff --git a/book/src/config.md b/book/src/config.md index a6cbf7a01..f41c13d46 100644 --- a/book/src/config.md +++ b/book/src/config.md @@ -63,11 +63,11 @@ Example: `cargo-dist-version = "0.0.3"` **This can only be set globally** -This is added automatically by `cargo dist init`, and is a recording of its own version for the sake of reproducibility and documentation. When you run [generate-ci][] the resulting CI scripts will use that version of cargo-dist to build your applications. +This is added automatically by `cargo dist init`, and is a recording of its own version for the sake of reproducibility and documentation. When you run [generate][] the resulting CI scripts will use that version of cargo-dist to build your applications. The syntax must be a valid [Cargo-style SemVer Version][semver-version] (not a VersionReq!). -If you delete the key, generate-ci will just use the version of cargo-dist that's currently running. +If you delete the key, generate will just use the version of cargo-dist that's currently running. ### rust-toolchain-version @@ -79,11 +79,11 @@ Example: `rust-toolchain-version = "1.67.1"` **This can only be set globally** -This is added automatically by `cargo dist init`, recorded for the sake of reproducibility and documentation. It represents the "ideal" Rust toolchain to build your project with. This is in contrast to the builtin Cargo [rust-version][] which is used to specify the *minimum* supported Rust version. When you run [generate-ci][] the resulting CI scripts will install that version of the Rust toolchain with [rustup][]. There's nothing special about the chosen value, it's just a hardcoded "recent stable version". +This is added automatically by `cargo dist init`, recorded for the sake of reproducibility and documentation. It represents the "ideal" Rust toolchain to build your project with. This is in contrast to the builtin Cargo [rust-version][] which is used to specify the *minimum* supported Rust version. When you run [generate][] the resulting CI scripts will install that version of the Rust toolchain with [rustup][]. There's nothing special about the chosen value, it's just a hardcoded "recent stable version". The syntax must be a valid rustup toolchain like "1.60.0" or "stable" (should not specify the platform, we want to install this toolchain on all platforms). -If you delete the key, generate-ci won't explicitly setup a toolchain, so whatever's on the machine will be used (with things like rust-toolchain.toml behaving as normal). Before being deprecated the default was to `rustup update stable`, but this is no longer the case. +If you delete the key, generate won't explicitly setup a toolchain, so whatever's on the machine will be used (with things like rust-toolchain.toml behaving as normal). Before being deprecated the default was to `rustup update stable`, but this is no longer the case. ### ci @@ -93,7 +93,7 @@ Example: `ci = ["github"]` **This can only be set globally** -This is a list of CI backends you want to support, allowing subsequent runs of [generate-ci][] to know what CI scripts to generate. Its presence also enables certain CI-specific features. For instance if "github" is included we'll try to generate the body for a Github Release and tell [installers][] to fetch binaries from a Github Release. Once we introduce more CI backends we'll need to more completely rationalize what that means. In all likelihood each set of CI scripts will need to explicitly select just its own CI by passing `--ci=...` for every invocation. +This is a list of CI backends you want to support, allowing subsequent runs of [generate][] to know what CI scripts to generate. Its presence also enables certain CI-specific features. For instance if "github" is included we'll try to generate the body for a Github Release and tell [installers][] to fetch binaries from a Github Release. Once we introduce more CI backends we'll need to more completely rationalize what that means. In all likelihood each set of CI scripts will need to explicitly select just its own CI by passing `--ci=...` for every invocation. "github" is currently the only supported CI backend. @@ -424,7 +424,7 @@ Caveat: the default "host" Artifact Mode does something fuzzier with `--target` [cargo-manifest]: https://doc.rust-lang.org/cargo/reference/manifest.html [concepts]: ./concepts.md [workspace]: https://doc.rust-lang.org/cargo/reference/workspaces.html -[generate-ci]: ./cli.md#cargo-dist-generate-ci +[generate]: ./cli.md#cargo-dist-generate [semver-version]: https://docs.rs/semver/latest/semver/struct.Version.html [rust-version]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field [rustup]: https://rust-lang.github.io/rustup/ diff --git a/book/src/simple-guide.md b/book/src/simple-guide.md index 6af350129..0ddb26edb 100644 --- a/book/src/simple-guide.md +++ b/book/src/simple-guide.md @@ -20,7 +20,7 @@ You can rerun `init` as many times as you want, as it also functions as an "upda cargo dist init ``` -[`init`][init] on its own just edits your Cargo.toml to include the recommended defaults. If you have enabled CI support, it will also run `cargo dist generate-ci` after setting things up. This ensures your config and your CI scripts are in sync, but will unfortunately clobber any hand-edits you made to the scripts. +[`init`][init] on its own just edits your Cargo.toml to include the recommended defaults. If you have enabled CI support, it will also run `cargo dist generate` after setting things up. This ensures your config and your CI scripts are in sync, but will unfortunately clobber any hand-edits you made to the scripts. Let's look at those defaults that were added (yes those comments are generated too, you will never stop me from adding more docs!!!): @@ -34,7 +34,7 @@ lto = "thin" [workspace.metadata.dist] # The preferred cargo-dist version to use in CI (Cargo.toml SemVer syntax) cargo-dist-version = "0.0.6" -# CI backends to support (see 'cargo dist generate-ci') +# CI backends to support ci = ["github"] # The installers to generate for each app installers = [] @@ -58,11 +58,11 @@ cargo-dist uses the existence of `[profile.dist]` in your Cargo.toml to detect i Next let's talk about `[workspace.metadata.dist]`. Cargo allows other tools to include their own project-wide settings in this kind of [metadata table][workspace-metadata]. See [config][] for the full set of options, but here we'll look at the defaults. -`cargo-dist-version = "0.0.6"` is cargo-dist recording its own version in your config for the sake of reproducibility and documentation. When you run [generate-ci][] the resulting CI scripts will use that version of cargo-dist. +`cargo-dist-version = "0.0.6"` is cargo-dist recording its own version in your config for the sake of reproducibility and documentation. When you run [generate][] the resulting CI scripts will use that version of cargo-dist. -`rust-toolchain-version = "1.67.1"` is the Rust toolchain that is considered "ideal" for building your application, recorded for the sake of reproducibility and documentation. This is in contrast to the builtin Cargo [rust-version][] which is used to specify the *minimum* supported Rust version. When you run [generate-ci][] the resulting CI scripts will install that version of the Rust toolchain with [rustup][]. There's nothing special about the chosen value, it's just a hardcoded "recent stable version". +`rust-toolchain-version = "1.67.1"` is the Rust toolchain that is considered "ideal" for building your application, recorded for the sake of reproducibility and documentation. This is in contrast to the builtin Cargo [rust-version][] which is used to specify the *minimum* supported Rust version. When you run [generate][] the resulting CI scripts will install that version of the Rust toolchain with [rustup][]. There's nothing special about the chosen value, it's just a hardcoded "recent stable version". -`ci = ["github"]` lets subsequent runs of [generate-ci][] know what CI scripts to generate. Its presence also enables certain Github-specific features like generating the body for a Github Release and telling installers to fetch binaries from a Github Release. It will be enabled by default if you have `repository = "https://github.com/..."` consistently set in your Cargo.toml(s). ("github" is currently the only supported CI backend.) +`ci = ["github"]` lets subsequent runs of [generate][] know what CI scripts to generate. Its presence also enables certain Github-specific features like generating the body for a Github Release and telling installers to fetch binaries from a Github Release. It will be enabled by default if you have `repository = "https://github.com/..."` consistently set in your Cargo.toml(s). ("github" is currently the only supported CI backend.) `installer = []` is just saying that we haven't enabled any [installers][]. Installers are intentionally excluded here to keep this example focused. @@ -72,7 +72,7 @@ Next let's talk about `[workspace.metadata.dist]`. Cargo allows other tools to i ### The CI Script -Because we set `ci = ["github"]`, [init][] invoked [generate-ci][] for us. Creating the Github CI workflow we wanted at `.github/workflows/release.yml`. Rather than including the full text here, I'll just link [cargo-dist's own release.yml][release-yml], because cargo-dist is self-hosting and has an extremely boring build/config that is basically equivalent to the one we're looking at in this example. +Because we set `ci = ["github"]`, [init][] invoked [generate][] for us. Creating the Github CI workflow we wanted at `.github/workflows/release.yml`. Rather than including the full text here, I'll just link [cargo-dist's own release.yml][release-yml], because cargo-dist is self-hosting and has an extremely boring build/config that is basically equivalent to the one we're looking at in this example. The first thing you might notice is that there's a *lot* of comments describing the script. As always: you will never stop me from writing more docs and shoving them in your face. Actually ok you *can* stop me because I need to write a lot of docs here and those comments are already decent docs. Feel free to peruse them to get a feel for it. @@ -195,7 +195,7 @@ If none of the previous rules apply, "1.0.0-prerelease.1" will also match a spec [cargo-release]: https://github.com/crate-ci/cargo-release [git-tag]: https://git-scm.com/book/en/v2/Git-Basics-Tagging [init]: ./cli.md#cargo-dist-init -[generate-ci]: ./cli.md#cargo-dist-generate-ci +[generate]: ./cli.md#cargo-dist-generate [cargo-profile]: https://doc.rust-lang.org/cargo/reference/profiles.html [thin-lto]: https://doc.rust-lang.org/cargo/reference/profiles.html#lto [workspace-metadata]: https://doc.rust-lang.org/cargo/reference/workspaces.html#the-metadata-table diff --git a/cargo-dist/src/cli.rs b/cargo-dist/src/cli.rs index 64aa2b1dc..2615ca3c5 100644 --- a/cargo-dist/src/cli.rs +++ b/cargo-dist/src/cli.rs @@ -117,7 +117,7 @@ pub enum Commands { /// Setup or update cargo-dist /// /// This will interactively guide you through the process of selecting configuration options - /// and will also automatically run 'cargo dist generate-ci' afterwards as necessary. It will + /// and will also automatically run 'cargo dist generate' afterwards as necessary. It will /// also handle updating your project to a new version of cargo-dist if you're running one. #[clap(disable_version_flag = true)] Init(InitArgs), @@ -227,9 +227,9 @@ pub struct InitArgs { /// during the interactive prompts. #[clap(long, short)] pub yes: bool, - /// Don't automatically invoke 'cargo dist generate-ci' at the end - #[clap(long)] - pub no_generate_ci: bool, + /// Don't automatically invoke 'cargo dist generate' at the end + #[clap(long, alias = "no-generate-ci")] + pub no_generate: bool, /// A path to a json file containing values to set in workspace.metadata.dist /// and package.metadata.dist, for building tools that edit these configs. /// diff --git a/cargo-dist/src/config.rs b/cargo-dist/src/config.rs index 73bd3b0ca..c64ae5d5e 100644 --- a/cargo-dist/src/config.rs +++ b/cargo-dist/src/config.rs @@ -22,7 +22,7 @@ pub struct DistMetadata { /// /// FIXME: Should we produce a warning if running locally with a different version? In theory /// it shouldn't be a problem and newer versions should just be Better... probably you - /// Really want to have the exact version when running generate-ci to avoid generating + /// Really want to have the exact version when running generate to avoid generating /// things other cargo-dist versions can't handle! #[serde(rename = "cargo-dist-version")] #[serde(skip_serializing_if = "Option::is_none")] @@ -49,9 +49,8 @@ pub struct DistMetadata { /// /// Currently only accepts "github". /// - /// When running `generate-ci` with no arguments this list will be used. - /// - /// This value isn't Optional because it's global, and therefore can't be overriden by packages. + /// When running `generate` this list will be used if it's Some, otherwise all known + /// CI backends will be used. #[serde(skip_serializing_if = "Option::is_none")] pub ci: Option>, @@ -441,7 +440,7 @@ impl DistMetadata { pub struct Config { /// Whether we need to compute an announcement tag or if we can fudge it /// - /// Commands like generate-ci and init don't need announcements, but want to run gather_work + /// Commands like generate and init don't need announcements, but want to run gather_work pub needs_coherent_announcement_tag: bool, /// The subset of artifacts we want to build pub artifact_mode: ArtifactMode, diff --git a/cargo-dist/src/init.rs b/cargo-dist/src/init.rs index 923c544b0..4e34e1afa 100644 --- a/cargo-dist/src/init.rs +++ b/cargo-dist/src/init.rs @@ -21,7 +21,7 @@ pub struct InitArgs { /// Whether to auto-accept the default values for interactive prompts pub yes: bool, /// Don't automatically generate ci - pub no_generate_ci: bool, + pub no_generate: bool, /// A path to a json file containing values to set in workspace.metadata.dist pub with_json_config: Option, } @@ -117,7 +117,7 @@ pub fn do_init(cfg: &Config, args: &InitArgs) -> Result<()> { eprintln!(); // regenerate anything that needs to be - if !args.no_generate_ci { + if !args.no_generate { eprintln!("running 'cargo dist generate' to apply any changes"); eprintln!(); @@ -754,12 +754,7 @@ fn apply_dist_to_metadata(metadata: &mut toml_edit::Item, meta: &DistMetadata) { rust_toolchain_version.as_deref(), ); - apply_string_list( - table, - "ci", - "# CI backends to support (see 'cargo dist generate-ci')\n", - ci.as_ref(), - ); + apply_string_list(table, "ci", "# CI backends to support\n", ci.as_ref()); apply_string_list( table, diff --git a/cargo-dist/src/main.rs b/cargo-dist/src/main.rs index 7c5f4bafd..2556d2bf5 100644 --- a/cargo-dist/src/main.rs +++ b/cargo-dist/src/main.rs @@ -214,7 +214,7 @@ fn cmd_init(cli: &Cli, args: &InitArgs) -> Result<(), miette::Report> { }; let args = cargo_dist::InitArgs { yes: args.yes, - no_generate_ci: args.no_generate_ci, + no_generate: args.no_generate, with_json_config: args.with_json_config.clone(), }; do_init(&config, &args) diff --git a/cargo-dist/tests/gallery/dist.rs b/cargo-dist/tests/gallery/dist.rs index c31862dde..5fe85ffad 100644 --- a/cargo-dist/tests/gallery/dist.rs +++ b/cargo-dist/tests/gallery/dist.rs @@ -159,7 +159,7 @@ impl<'a> TestContext<'a, Tools> { self.load_dist_results(test_name) } - /// Run 'cargo dist generate-ci' and return paths to various files that were generated + /// Run 'cargo dist generate' and return paths to various files that were generated pub fn cargo_dist_generate(&self, test_name: &str) -> Result { let github_ci_path = Utf8Path::new(".github/workflows/release.yml").to_owned(); let wxs_path = Utf8Path::new("wix/main.wxs").to_owned(); @@ -171,7 +171,7 @@ impl<'a> TestContext<'a, Tools> { LocalAsset::remove_file(&wxs_path)?; } - // run generate-ci + // run generate eprintln!("running cargo dist generate..."); self.tools .cargo_dist diff --git a/cargo-dist/tests/snapshots/markdown-help.snap b/cargo-dist/tests/snapshots/markdown-help.snap index d48bb2ab3..67fe7ab9f 100644 --- a/cargo-dist/tests/snapshots/markdown-help.snap +++ b/cargo-dist/tests/snapshots/markdown-help.snap @@ -132,7 +132,7 @@ This subcommand accepts all the [global options](#global-options) ## cargo dist init Setup or update cargo-dist -This will interactively guide you through the process of selecting configuration options and will also automatically run 'cargo dist generate-ci' afterwards as necessary. It will also handle updating your project to a new version of cargo-dist if you're running one. +This will interactively guide you through the process of selecting configuration options and will also automatically run 'cargo dist generate' afterwards as necessary. It will also handle updating your project to a new version of cargo-dist if you're running one. ### Usage @@ -146,8 +146,8 @@ Automatically accept all recommended/default values This is equivalent to just mashing ENTER over and over during the interactive prompts. -#### `--no-generate-ci` -Don't automatically invoke 'cargo dist generate-ci' at the end +#### `--no-generate` +Don't automatically invoke 'cargo dist generate' at the end #### `--with-json-config ` A path to a json file containing values to set in workspace.metadata.dist and package.metadata.dist, for building tools that edit these configs.