Trac #33787: Installation manual: Update section "system-wide install"

(split out from #30207)

https://doc.sagemath.org/html/en/installation/source.html#installation-
in-a-multiuser-environment should be updated:

- Don't edit the script
- Just symlink to the `sage` script in venv

We also add a link from the README to an optional step described only in
the installation manual.

URL: https://trac.sagemath.org/33787
Reported by: mkoeppe
Ticket author(s): Matthias Koeppe
Reviewer(s): John Palmieri

Makefile

@@ -197,7 +197,7 @@ micro_release:
 	@echo "Removing unnecessary files & directories - make will not be functional afterwards anymore"
 	@# We keep src/sage for some doctests that it expect it to be there and
 	@# also because it does not add any weight with rdfind below.
-	@# We need src/sage/bin/ for the scripts that invoke Sage
+	@# We need src/bin/ for the scripts that invoke Sage
 	@# We need sage, the script to start Sage
 	@# We need local/, the dependencies and the built Sage library itself.
 	@# We keep VERSION.txt.

README.md

@@ -413,15 +413,18 @@ in the Installation Guide.
     get a list by typing  `./sage --optional` or by visiting the
     [packages documentation page](https://doc.sagemath.org/html/en/reference/spkg/).
 
-18. Optional: Create a symlink to the `sage` executable somewhere in your
-    `PATH`, so you can start Sage by typing `sage` from anywhere rather
-    than having to either type the full path or navigate to the Sage
+18. Optional: Create a symlink to the installed `sage` script in a
+    directory in your `PATH`, for example ``/usr/local``. This will
+    allow you to start Sage by typing `sage` from anywhere rather than
+    having to either type the full path or navigate to the Sage
     directory and type `./sage`. This can be done by running:
 
-        $ ln -s $HOME/sage/sage-x.y/sage /usr/local/bin
+        $ sudo ln -s $(./sage -sh -c 'ls $SAGE_ROOT/venv/bin/sage') /usr/local/bin
 
-    The `$HOME/sage/sage-x.y/` part may need adapting. One way to decide
-    how to adapt it is to run `print(SAGE_ROOT)` in a Sage session.
+19. Optional: Set up SageMath as a Jupyter kernel in an existing Jupyter notebook
+    or JupyterLab installation, as described in [section
+    "Launching SageMath"](https://doc.sagemath.org/html/en/installation/launching.html)
+    in the installation manual.
 
 Troubleshooting
 ---------------
@@ -580,17 +583,10 @@ Relocation
 
 It is not supported to move the `SAGE_ROOT` or `SAGE_LOCAL` directory
 after building Sage.  If you do move the directories, you will have to
-build Sage again from scratch.
-
-If you copy the `sage` script or make a symbolic link to it, you
-should modify the script to reflect this (as instructed at the top of
-the script). It is important that the path to Sage does not have any
-spaces and non-ASCII characters in it.
+run ``make distclean`` and build Sage again from scratch.
 
 For a system-wide installation, you have to build Sage as a "normal" user
-and then as root you can change permissions. Afterwards, you need to start up
-Sage as root at least once prior to using the system-wide Sage as a
-normal user. See the [Installation Guide](https://doc.sagemath.org/html/en/installation/source.html#installation-in-a-multiuser-environment)
+and then as root you can change permissions. See the [Installation Guide](https://doc.sagemath.org/html/en/installation/source.html#installation-in-a-multiuser-environment)
 for further information.
 
 Redistribution

sage

@@ -137,9 +137,6 @@ fi
 # Run the actual Sage script
 if [ -x "$SAGE_ROOT/src/bin/sage" ]; then
     exec "$SAGE_ROOT/src/bin/sage" "$@"
-elif [ -x "$SAGE_ROOT/local/bin/sage" ]; then # if in a stripped binary
-    # Note in this case we assume that SAGE_LOCAL is the "local" subdirectory
-    exec "$SAGE_ROOT/local/bin/sage" "$@"
 else
     echo >&2 "$0: no Sage installation found in \$SAGE_ROOT=$SAGE_ROOT"
     exit 1

src/doc/en/installation/launching.rst

@@ -117,6 +117,8 @@ For further reading you can have a look at the other documents in the
 SageMath documentation at http://doc.sagemath.org/.
 
 
+.. _sec-launching-system-jupyter:
+
 Setting up SageMath as a Jupyter kernel in an existing Jupyter notebook or JupyterLab installation
 --------------------------------------------------------------------------------------------------
 

src/doc/en/installation/source.rst

@@ -1202,60 +1202,35 @@ Installation in a Multiuser Environment
 This section addresses the question of how a system administrator can install
 a single copy of Sage in a multi-user computer network.
 
-System-wide install
-~~~~~~~~~~~~~~~~~~~
+#. Using ``sudo``, create the installation directory, for example,
+   ``/opt/sage/sage-x.y``. We refer to it as ``SAGE_LOCAL`` in the
+   instructions below. Do not try to install into a directory that
+   already contains other software, such as ``/usr/local``::
 
-In the instructions below, we assume that ``/path/to/sage-x.y`` is
-the directory where you want to install Sage.
+       $ sudo mkdir -p SAGE_LOCAL
 
-#. First of all, extract the Sage source tarball in ``/path/to``
-   (this will create the directory ``/path/to/sage-x.y``).
-   After extracting, you can change the directory name if you do not
-   like ``sage-x.y``.
+#. Make the directory writable for you and readable by everyone::
 
-#. Change the ownership of the ``/path/to/sage-x.y`` directory tree
-   to your normal user account (as opposed to ``root``). This is because
-   Sage will refuse to compile as ``root``. ::
+       $ sudo chown $(id -un) SAGE_LOCAL
+       $ sudo chmod 755 SAGE_LOCAL
 
-       $ chown -R user:group /path/to/sage-x.y
+#. Build and install Sage, following the instructions in `README.md
+   <https://github.com/sagemath/sage/#readme>`_, using the
+   ``configure`` option ``--prefix=SAGE_LOCAL``.
 
-#. Using your normal user account, build Sage.
-   See the :ref:`build-from-source-step-by-step` above.
+   Do not use ``sudo`` for this step; building Sage must be done using
+   your normal user account.
 
-#. Make a symbolic link to the ``sage`` script in :file:`/usr/local/bin`::
+#. Optionally, create a symbolic link to the installed ``sage`` script
+   in a directory that is in the users' :envvar:`PATH`, for example
+   ``/usr/local/bin``::
 
-       $ ln -s /path/to/sage-x.y/sage /usr/local/bin/sage
+       $ sudo ln -s SAGE_LOCAL/bin/sage /usr/local/bin/sage
 
-   Alternatively, copy the Sage script::
+#. Optionally, change permissions to prevent accidental changes to
+   the installation by yourself::
 
-       $ cp /path/to/sage-x.y/sage /usr/local/bin/sage
+       $ sudo chown -R root SAGE_LOCAL
 
-   If you do this, make sure you edit the line:
 
-   .. CODE-BLOCK:: bash
-
-       #SAGE_ROOT=/path/to/sage-version
-
-   at the beginning of the copied ``sage`` script according to the direction
-   given there to something like:
-
-   .. CODE-BLOCK:: bash
-
-       SAGE_ROOT=<SAGE_ROOT>
-
-   (note that you have to change ``<SAGE_ROOT>`` above!).
-   It is recommended not to edit the original ``sage`` script, only the copy at
-   :file:`/usr/local/bin/sage`.
-
-#. Optionally, you can test Sage by running::
-
-       $ make testlong
-
-   or ``make ptestlong`` which tests files in parallel using multiple
-   processes.
-   You can also omit ``long`` to skip tests which take a long time.
-
-
-
-
-**This page was last updated in April 2022 (Sage 9.6).**
+**This page was last updated in May 2022 (Sage 9.7).**