From 2d2f18c159de890ab17dd65bc2f7f8d53d6c5b3f Mon Sep 17 00:00:00 2001
From: Fabian Boehm <FHomborg@gmail.com>
Date: Wed, 11 Dec 2024 16:43:48 +0100
Subject: [PATCH] installable builds: Fail when building man pages fails

This is unfortunately necessary, because otherwise it would not rerun
the build script just because you installed sphinx.

Because we use the man pages for --help output, they're pretty
necessary.

To override it, you can set $FISH_BUILD_DOCS=0, like

```fish
FISH_BUILD_DOCS=0 cargo install --path .
```
---
 README.rst |  8 +++++---
 build.rs   | 47 ++++++++++++++++++++++++++++++++++-------------
 2 files changed, 39 insertions(+), 16 deletions(-)

diff --git a/README.rst b/README.rst
index eaa0873f3..079ec88b3 100644
--- a/README.rst
+++ b/README.rst
@@ -176,9 +176,7 @@ and you can unpack them to ~/.local/share/fish/install/ (currently, subject to c
 
 You will have to use ``--install`` once per user and you will have to run it again when you upgrade fish. It will tell you to.
 
-To install fish as self-installable, just use ``cargo``, like:
-
-.. code:: bash
+To install fish as self-installable, just use ``cargo``, like::
 
    cargo install --path /path/to/fish # if you have a git clone
    cargo install --git https://github.com/fish-shell/fish-shell --tag 4.0 # to build from git once 4.0 is released
@@ -188,6 +186,10 @@ This will place the binaries in ``~/.cargo/bin/``, but you can place them wherev
 
 This build won't have the HTML docs (``help`` will open the online version) or translations.
 
+It requires sphinx by default, if sphinx-build is not available you can build without man pages by running it with $FISH_BUILD_DOCS set to 0::
+
+  FISH_BUILD_DOCS=0 cargo install --path .
+
 You can also link it statically (but not against glibc) and move it to other computers.
 
 Contributing Changes to the Code
diff --git a/build.rs b/build.rs
index 415a171bd..f812e390f 100644
--- a/build.rs
+++ b/build.rs
@@ -362,22 +362,43 @@ fn build_man(build_dir: &Path) {
     ];
     let _ = std::fs::create_dir_all(sec1dir.to_str().unwrap());
 
-    match Command::new("sphinx-build").args(args).output() {
+    rsconf::rebuild_if_env_changed("FISH_BUILD_DOCS");
+    if env::var("FISH_BUILD_DOCS") == Ok("0".to_string()) {
+        println!("cargo:warning=Skipping man pages because $FISH_BUILD_DOCS is set to 0");
+        return;
+    }
+
+    // We run sphinx to build the man pages.
+    // Every error here is fatal so cargo doesn't cache the result
+    // - if we skipped the docs with sphinx not installed, installing it would not then build the docs.
+    // That means you need to explicitly set $FISH_BUILD_DOCS=0 (`FISH_BUILD_DOCS=0 cargo install --path .`),
+    // which is unfortunate - but the docs are pretty important because they're also used for --help.
+    match Command::new("sphinx-build").args(args).spawn() {
+        Err(x) if x.kind() == std::io::ErrorKind::NotFound => {
+            panic!("Could not find sphinx-build to build man pages.\nInstall sphinx or disable building the docs by setting $FISH_BUILD_DOCS=0.");
+        }
         Err(x) => {
-            println!("cargo:warning=Could not build man pages: {:?}", x);
+            // Another error - permissions wrong etc
+            panic!(
+                "Error starting sphinx-build to build man pages: {:?}",
+                x
+            );
         }
-        Ok(x) => {
-            if !x.status.success() {
-                println!(
-                    "cargo:warning=Could not build man pages: {:?}",
-                    std::str::from_utf8(&x.stdout).unwrap()
+        Ok(mut x) => match x.wait() {
+            Err(err) => {
+                panic!(
+                    "Error waiting for sphinx-build to build man pages: {:?}",
+                    err
                 );
-                println!(
-                    "cargo:warning=Could not build man pages: {:?}",
-                    std::str::from_utf8(&x.stderr).unwrap()
-                );
-                panic!("Building docs failed");
             }
-        }
+            Ok(out) => {
+                if out.success() {
+                    // Success!
+                    return;
+                } else {
+                    panic!("sphinx-build failed to build the man pages.");
+                }
+            }
+        },
     }
 }