Generate completions at runtime

No longer generate completions at build time; instead add a new
--completions argument to allow generating completions at runtime.

This removes one set of artifacts written to $OUT_DIR, and thus goes one
step towards removing the OUT_DIR dependency from the whole release
process, which in turn fixes the release pipeline.

See GH-284

CHANGELOG.md

@@ -8,9 +8,18 @@ Use `cargo release` to create a new release.
 
 ## [Unreleased]
 
+### Added
+- mdcat now includes a `--completions` argument to generate shell completions for all major shells (see [GH-286]).
+
 ### Changed
 - Update dependencies.
 
+### Removed
+- mdcat now longer builds shell completions during compilation (see [GH-286]).
+- Release artifacts no longer contain completions; use `mdcat --completions` to generate them instead (see [GH-286]).
+
+[GH-286]: https://github.com/swsnr/mdcat/pull/286
+
 ## [2.2.0] – 2024-07-11
 
 ### Changed

Cargo.toml

@@ -20,6 +20,7 @@ static = ["mdcat-http-reqwest/rustls-tls-native-roots"]
 [dependencies]
 anyhow = { version = "1.0.86", default-features = false, features = ["std"] }
 clap = { version = "4.5.8", default-features = false, features = ["std", "derive", "help", "usage", "error-context"] }
+clap_complete = "4.5.7"
 human-panic = { version = "2.0.0", default-features = false, features = ["color"] }
 pulldown-cmark = { workspace = true, features = ['simd'] }
 reqwest = { workspace = true }
@@ -37,11 +38,6 @@ pulldown-cmark-mdcat = { version = "=2.2.0", path = "pulldown-cmark-mdcat" }
 [dev-dependencies]
 similar-asserts = { workspace = true }
 
-[build-dependencies]
-# To generate completions during build
-clap = { version = "4.5.8", features = ["derive"] }
-clap_complete = "4.5.7"
-
 [target.'cfg(windows)'.dependencies]
 anstyle-query = { version = "1.1.0", default-features = false }
 

README.md

@@ -78,8 +78,7 @@ It still uses the system's CA roots however.
 
 The build process also generates the following additional files in `$OUT_DIR`:
 
-* Completions for Bash, Zsh, Fish, and Powershell, for both `mdcat` and `mdless`, in `completions` sub-directory.
-* A `mdcat.1` manpage, build from `mdcat.1.adoc` with the `asciidoctor` command from [AsciiDoctor].
+- A `mdcat.1` manpage, build from `mdcat.1.adoc` with the `asciidoctor` command from [AsciiDoctor].
   If `asciidoctor` is not found the build script prints a warning.
 
 These additional artifacts are included in the release builds.
@@ -89,6 +88,23 @@ You may also want to include an `mdless` link to `mdcat` (see above).
 
 [AsciiDoctor]: https://asciidoctor.org/
 
+## Packaging
+
+When packaging `mdcat` you may wish to include the following additional artifacts:
+
+- A symlink or hardlink from `mdless` to `mdcat` (see above).
+- Shell completions for relevant shells, by invoking `mdcat --completions` after building, e.g.
+
+  ```console
+  $ mdcat --completions fish > /usr/share/fish/vendor_completions.d/mdcat.fish
+  $ mdcat --completions bash > /usr/share/bash-completion/completions/mdcat
+  $ mdcat --completions zsh > /usr/share/zsh/site-functions/_mdcat
+  # Same for mdless if you include it
+  $ mdless --completions fish > /usr/share/fish/vendor_completions.d/mdless.fish
+  $ mdless --completions bash > /usr/share/bash-completion/completions/mdless
+  $ mdless --completions zsh > /usr/share/zsh/site-functions/_mdless
+  ```
+
 ## Troubleshooting
 
 `mdcat` can output extensive tracing information when asked to.

build.rs

@@ -8,28 +8,6 @@ use std::io::{Error, ErrorKind, Result};
 use std::path::Path;
 use std::process::Command;
 
-#[allow(dead_code)]
-mod mdcat {
-    include!("src/args.rs");
-}
-
-fn gen_completions<P: AsRef<Path>>(out_dir: P) -> Result<()> {
-    use clap::CommandFactory;
-    use clap_complete::*;
-
-    let completions = out_dir.as_ref().join("completions");
-    std::fs::create_dir_all(&completions).expect("Failed to create $OUT_DIR/completions");
-    for program in ["mdcat", "mdless"] {
-        for shell in [Shell::Bash, Shell::Zsh, Shell::Fish, Shell::PowerShell] {
-            let mut command = mdcat::Args::command();
-            let subcommand = command.find_subcommand_mut(program).unwrap();
-            generate_to(shell, subcommand, program, &completions)?;
-        }
-    }
-
-    Ok(())
-}
-
 fn build_manpage<P: AsRef<Path>>(out_dir: P) -> Result<()> {
     let target_file = out_dir.as_ref().join("mdcat.1");
 
@@ -61,11 +39,6 @@ fn build_manpage<P: AsRef<Path>>(out_dir: P) -> Result<()> {
 fn main() {
     let out_dir = std::env::var_os("OUT_DIR").expect("OUT_DIR not set");
 
-    println!("cargo:rerun-if-changed=src/args.rs");
-    if let Err(error) = gen_completions(&out_dir) {
-        println!("cargo:warning=Failed to build completions: {error}");
-    }
-
     println!("cargo:rerun-if-changed=mdcat.1.adoc");
     if let Err(error) = build_manpage(&out_dir) {
         println!("cargo:warning=Failed to build manpage: {error}");

mdcat.1.adoc

@@ -115,6 +115,11 @@ This is the default when run as `mdcat`.
 --detect-terminal::
     Detect the terminal program, print its name, and exit.
 
+--completions=_SHELL_::
+    Generate completions for _SHELL_ to standard output and exit.
+
+    _SHELL_ can be one of `bash`, `zsh`, `fish`, `powershell`, or `elvish`.
+
 -h::
 --help::
     Show a help message to the user and exit.

scripts/package

@@ -19,8 +19,7 @@ package_windows() {
     mv LICENSE LICENSE.txt
     7z a "${archive_file}" \
         "./target/${TARGET}/release/mdcat.exe" \
-        ./README.md ./CHANGELOG.md ./LICENSE.txt ./mdcat.1.adoc \
-        "${OUTDIR}/completions"
+        ./README.md ./CHANGELOG.md ./LICENSE.txt ./mdcat.1.adoc
     if [[ -n "${GITHUB_OUTPUT:-}" ]]; then
         echo "file=${archive_file}" >>"${GITHUB_OUTPUT}"
         echo "name=${ARCHIVE_NAME}.zip" >>"${GITHUB_OUTPUT}"
@@ -38,7 +37,7 @@ package_unix() {
     cp -r \
         README.md CHANGELOG.md LICENSE \
         "target/${TARGET}/release/mdcat" \
-        "${OUTDIR}/mdcat.1" "${OUTDIR}/completions" \
+        "${OUTDIR}/mdcat.1" \
         "${pkg_dir}/${ARCHIVE_NAME}"
     tar -czf "${PWD}/${archive_file}" -C "${pkg_dir}" "${ARCHIVE_NAME}"
     echo "file=${archive_file}" >>"${GITHUB_OUTPUT}"

src/args.rs

@@ -5,6 +5,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 use clap::ValueHint;
+use clap_complete::Shell;
 
 fn after_help() -> &'static str {
     "See 'man 1 mdcat' for more information.
@@ -61,7 +62,6 @@ pub enum Command {
 }
 
 impl Command {
-    #[allow(dead_code)]
     pub fn paginate(&self) -> bool {
         match *self {
             // In both cases look at the option indicating the non-default
@@ -107,6 +107,9 @@ pub struct CommonArgs {
     /// Skip terminal detection and only use ANSI formatting.
     #[arg(long = "ansi", conflicts_with = "no_colour")]
     pub ansi_only: bool,
+    /// Generate completions for a shell to standard output and exit.
+    #[arg(long)]
+    pub completions: Option<Shell>,
 }
 
 /// What resources mdcat may access.

src/main.rs

@@ -9,7 +9,8 @@
 
 //! Show CommonMark documents on TTYs.
 
-use clap::Parser;
+use clap::{CommandFactory, Parser};
+use clap_complete::generate;
 use mdcat::{create_resource_handler, process_file};
 use pulldown_cmark_mdcat::terminal::{TerminalProgram, TerminalSize};
 use pulldown_cmark_mdcat::{Settings, Theme};
@@ -41,6 +42,17 @@ fn main() {
     let args = Args::parse().command;
     event!(target: "mdcat::main", Level::TRACE, ?args, "mdcat arguments");
 
+    if let Some(shell) = args.completions {
+        let binary = match args {
+            mdcat::args::Command::Mdcat { .. } => "mdcat",
+            mdcat::args::Command::Mdless { .. } => "mdless",
+        };
+        let mut command = Args::command();
+        let subcommand = command.find_subcommand_mut(binary).unwrap();
+        generate(shell, subcommand, binary, &mut std::io::stdout());
+        std::process::exit(0);
+    }
+
     let terminal = if args.no_colour {
         TerminalProgram::Dumb
     } else if args.paginate() || args.ansi_only {