ci: completion/manpage generation script spring cleaning (#795)

* ci: spring cleaning of completions autogen

This commit changes a few things/cleans up stuff:
- Completion and manpage generation now drops the files off in
  `./target/tmp/bottom` rather than arbitrarily in the build directory.
  This was originally done because I was lazy and just needed it to work
  in CI, but it's kinda gross if you want to build the manpages in your
  own directory.
- CI was updated to handle this.
- Only run if the `BTM_GENERATE` env var is actually non-empty.

* docs: update for manpage/completion gen

* ci: auto delete autogen comp/manpage dir

* ci: fix incorrect mv for autogen

The mv was too late, should be earlier in the workflow.

* ci: specify shell in autogen delete

* docs: more updates to manpage/comp docs

* ci: unify env vars

* ci: skip autogen on build-msi

.github/workflows/build_releases.yml

@@ -11,15 +11,16 @@ on:
 
 env:
   CARGO_INCREMENTAL: 0
+  RUST_BACKTRACE: 1
+  BTM_GENERATE: true
+  COMPLETION_DIR: "target/tmp/bottom/completion/"
+  MANPAGE_DIR: "target/tmp/bottom/manpage/"
 
 jobs:
   build-binaries:
     name: "Build binaries"
     runs-on: ${{ matrix.info.os }}
     container: ${{ matrix.info.container }}
-    env:
-      RUST_BACKTRACE: 1
-      BTM_GENERATE: true
     strategy:
       fail-fast: false
       matrix:
@@ -143,6 +144,12 @@ jobs:
           use-cross: ${{ matrix.info.cross }}
           cross-version: 0.2.4
 
+      - name: Move automatically generated completion/manpage
+        shell: bash
+        run: |
+          mv "$COMPLETION_DIR" completion
+          mv "$MANPAGE_DIR" manpage
+
       - name: Bundle release and completion (Windows)
         if: matrix.info.os == 'windows-2019'
         shell: bash
@@ -188,11 +195,17 @@ jobs:
           name: release
           path: release
 
+      # If I add more shared cleanup stuff in the future, I should move to a separate script, perhaps.
+      - name: Delete automatically generated completion/manpage to not cache
+        shell: bash
+        run: |
+          rm -r ./target/tmp/bottom/
+
   build-msi:
     name: "Build MSI installer"
     runs-on: "windows-2019"
     env:
-      RUST_BACKTRACE: 1
+      BTM_GENERATE: ""
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
@@ -259,9 +272,6 @@ jobs:
               dpkg: armhf,
               container: "ghcr.io/clementtsang/cargo-deb-armv7-unknown-linux-gnueabihf",
             }
-    env:
-      RUST_BACKTRACE: 1
-      BTM_GENERATE: true
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
@@ -285,6 +295,12 @@ jobs:
           use-cross: ${{ matrix.info.cross }}
           cross-version: 0.2.4
 
+      - name: Move automatically generated completion/manpage
+        shell: bash
+        run: |
+          mv "$COMPLETION_DIR" completion
+          mv "$MANPAGE_DIR" manpage
+
       - name: Zip manpage
         run: |
           gzip ./manpage/btm.1
@@ -325,3 +341,8 @@ jobs:
           retention-days: 3
           name: release
           path: release
+
+      - name: Delete automatically generated completion/manpage to not cache
+        shell: bash
+        run: |
+          rm -r ./target/tmp/bottom/

.gitignore

@@ -34,4 +34,4 @@ deny.toml
 
 # mkdocs
 site/
-docs/site
+docs/site

Cargo.toml

@@ -20,7 +20,7 @@ exclude = [
     "codecov.yml",
     "deployment/",
     "docs/",
-    "sample_configs/"
+    "sample_configs/",
 ]
 
 [[bin]]
@@ -113,7 +113,11 @@ section = "utility"
 assets = [
     ["target/release/btm", "usr/bin/", "755"],
     ["LICENSE", "usr/share/doc/btm/", "644"],
-    ["manpage/btm.1.gz", "usr/share/man/man1/btm.1.gz", "644"],
+    [
+        "manpage/btm.1.gz",
+        "usr/share/man/man1/btm.1.gz",
+        "644",
+    ],
     [
         "completion/btm.bash",
         "usr/share/bash-completion/completions/btm",
@@ -124,7 +128,11 @@ assets = [
         "usr/share/fish/vendor_completions.d/btm.fish",
         "644",
     ],
-    ["completion/_btm", "usr/share/zsh/vendor-completions/", "644"],
+    [
+        "completion/_btm",
+        "usr/share/zsh/vendor-completions/",
+        "644",
+    ],
 ]
 extended-description = """\
 A customizable cross-platform graphical process/system monitor for the terminal. Supports Linux, macOS, and Windows.

build.rs

@@ -23,32 +23,39 @@ fn create_dir(dir: &Path) -> Result<()> {
 }
 
 fn main() -> Result<()> {
-    if env::var_os("BTM_GENERATE").is_some() {
+    const COMPLETION_DIR: &str = "target/tmp/bottom/completion";
-        // OUT_DIR is where extra build files are written to for Cargo.
+    const MANPAGE_DIR: &str = "target/tmp/bottom/manpage";
-        let completion_out_dir = PathBuf::from("completion");
-        let manpage_out_dir = PathBuf::from("manpage");
 
-        create_dir(&completion_out_dir)?;
+    match env::var_os("BTM_GENERATE") {
-        create_dir(&manpage_out_dir)?;
+        Some(var) if !var.is_empty() => {
+            let completion_out_dir = PathBuf::from(COMPLETION_DIR);
+            let manpage_out_dir = PathBuf::from(MANPAGE_DIR);
 
-        // Generate completions
+            create_dir(&completion_out_dir)?;
-        let mut app = build_app();
+            create_dir(&manpage_out_dir)?;
-        generate_to(Shell::Bash, &mut app, "btm", &completion_out_dir)?;
-        generate_to(Shell::Zsh, &mut app, "btm", &completion_out_dir)?;
-        generate_to(Shell::Fish, &mut app, "btm", &completion_out_dir)?;
-        generate_to(Shell::PowerShell, &mut app, "btm", &completion_out_dir)?;
-        generate_to(Shell::Elvish, &mut app, "btm", &completion_out_dir)?;
 
-        // Generate manpage
+            // Generate completions
-        let app = app.name("btm");
+            let mut app = build_app();
-        let man = clap_mangen::Man::new(app);
+            generate_to(Shell::Bash, &mut app, "btm", &completion_out_dir)?;
-        let mut buffer: Vec<u8> = Default::default();
+            generate_to(Shell::Zsh, &mut app, "btm", &completion_out_dir)?;
-        man.render(&mut buffer)?;
+            generate_to(Shell::Fish, &mut app, "btm", &completion_out_dir)?;
-        std::fs::write(manpage_out_dir.join("btm.1"), buffer)?;
+            generate_to(Shell::PowerShell, &mut app, "btm", &completion_out_dir)?;
+            generate_to(Shell::Elvish, &mut app, "btm", &completion_out_dir)?;
+
+            // Generate manpage
+            let app = app.name("btm");
+            let man = clap_mangen::Man::new(app);
+            let mut buffer: Vec<u8> = Default::default();
+            man.render(&mut buffer)?;
+            std::fs::write(manpage_out_dir.join("btm.1"), buffer)?;
+        }
+        _ => {}
     }
 
     println!("cargo:rerun-if-changed=build.rs");
     println!("cargo:rerun-if-changed=./src/clap.rs");
+    println!("cargo:rerun-if-changed=.{}", COMPLETION_DIR);
+    println!("cargo:rerun-if-changed=.{}", MANPAGE_DIR);
     println!("cargo:rerun-if-env-changed=BTM_GENERATE");
 
     Ok(())

docs/content/contribution/packaging-and-distribution.md

@@ -24,13 +24,30 @@ You'll then want to build with:
 cargo build --release --locked
 ```
 
-Completion files are automatically generated during this process, and are located in the directory `target/release/build/bottom-<gibberish>/out`. Note there may be multiple folders that look like `target/release/build/bottom-<gibberish>`. To programmatically determine which is the right folder, you might want to use something like:
+### Manpage and completion generation
+
+bottom uses a [`build.rs`](https://github.com/ClementTsang/bottom/blob/master/build.rs) script to automatically generate
+a manpage and shell completions for the following shells:
+
+- Bash
+- Zsh
+- Fish
+- Powershell
+- Elvish
+
+If you want to generate manpages and/or completion files, set the `BTM_GENERATION` env var to a non-empty value. For
+example, run something like this:
 
 ```bash
-$(ls target/release/build/bottom-*/out/btm.bash | head -n1 | xargs dirname)
+BTM_GENERATE=true cargo build --release --locked
 ```
 
-You may find the [Arch package install script template](https://github.com/ClementTsang/bottom/blob/master/deployment/linux/arch/PKGBUILD.template) useful as a reference.
+This will automatically generate completion and manpage files in `target/tmp/bottom/`. If you wish to regenerate the
+files, modify/delete either these files or set `BTM_GENERATE` to some other non-empty value to retrigger the build
+script.
+
+For more information, you may want to look at either the [`build.rs`](https://github.com/ClementTsang/bottom/blob/master/build.rs)
+file or the [binary build CI workflow](https://github.com/ClementTsang/bottom/blob/master/.github/workflows/build_releases.yml).
 
 ## Adding an installation source