From 6b15cffbabeb72c94d02533888050cee7e4c60b2 Mon Sep 17 00:00:00 2001
From: Hetarth Jodha <hetarthj7@gmail.com>
Date: Sat, 15 Nov 2025 00:15:39 +0530
Subject: [PATCH] Issue #41161: Update sage -b to use ninja and deprecate sage
 -br

---
 src/bin/sage                          | 14 ++++++++++++--
 src/doc/en/reference/repl/startup.rst | 19 +++++++++++++++++++
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/src/bin/sage b/src/bin/sage
index 59ebb32edfd..e79fc4ce2e2 100755
--- a/src/bin/sage
+++ b/src/bin/sage
@@ -191,7 +191,15 @@ fi
 # build/bin/sage-site. See #29111; but OTOH #34627.
 
 build_sage() {
-    ( cd "$SAGE_ROOT" && make sagelib-no-deps ) || exit $?
+    # Check for the expected editable meson build directory
+    if [ -f "build/build.ninja" ]; then
+        echo "Building Sage with ninja..."
+        ( cd "$SAGE_ROOT" && ninja -C build ) || exit $?
+    else
+        echo "Error: 'sage -b' is for editable meson-based developer builds." >&2
+        echo "Please use 'make' or 'meson' directly for other builds." >&2
+        exit 1
+    fi
 }
 
 # Check for '-i' etc. before sourcing sage-env: running "make"
@@ -212,8 +220,10 @@ case "$1" in
         exit 0
         ;;
     -br|--br)
+        echo "Warning: 'sage -br' is deprecated." >&2
+        echo "In an editable install, just run './sage' to use the latest built code." >&2
         build_sage
-        shift; set -- -r "$@"  # delegate to handling of "-r" below, after sourcing sage-env
+        shift; set -- -r "$@"
         ;;
     -bn|--build-and-notebook)
         build_sage
diff --git a/src/doc/en/reference/repl/startup.rst b/src/doc/en/reference/repl/startup.rst
index 48e4cda756a..fcfd0267365 100644
--- a/src/doc/en/reference/repl/startup.rst
+++ b/src/doc/en/reference/repl/startup.rst
@@ -42,3 +42,22 @@ in this file.
 
 The default location of this file can be changed using the
 environment variable :envvar:`SAGE_STARTUP_FILE`.
+
+.. _sage_subcommands:
+
+Sage Subcommands
+----------------
+
+The ``sage`` script can be used to invoke several subcommands, including:
+
+* ``sage -b``: Rebuilds the Sage library. This is intended for developer-only
+  editable Meson builds. It runs ``ninja -C build`` to recompile. If a
+  non-Meson build is detected, it will error out with a message.
+
+* ``sage -br``: **Deprecated.** This command is no longer supported and
+  will be removed in a future release. Use ``sage -b`` to build and
+  ``./sage`` to run.
+
+* ``sage --python``: Runs the Python interpreter included with Sage.
+
+* ``sage -i <package>``: Installs a Sage package.
\ No newline at end of file