Trac #33426: add more details on conda-based installations of Sage

https://doc.sagemath.org/html/en/installation/conda.html#sec- installation-conda assumes knowledge about Conda. In fact, we have enough details on https://wiki.sagemath.org/Conda, but the link to it is only given at the bottom of https://doc.sagemath.org/html/en/installation/conda.html#sec- installation-conda, and only in context of "Instructions for using Conda for SageMath development" This should be fixed, and some parts of wiki copied there. Also add how to update the conda environment later: `conda env update --file src/environment.yml --prune` See also: - #33088 More updates for installation and developer guides URL: https://trac.sagemath.org/33426 Reported by: dimpase Ticket author(s): Matthias Koeppe Reviewer(s): Dima Pasechnik
sagemath · Apr 9, 2022 · 7ee048c · 7ee048c
2 parents 7acdc3d + 516701d
commit 7ee048c
Show file tree

Hide file tree

Showing 5 changed files with 132 additions and 93 deletions.
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 >   "Creating a Viable Open Source Alternative to
 >   Magma, Maple, Mathematica, and MATLAB"
 
->   Copyright (C) 2005-2021 The Sage Development Team
+>   Copyright (C) 2005-2022 The Sage Development Team
 
 https://www.sagemath.org
 
@@ -148,8 +148,9 @@ read the following step-by-step instructions for building Sage.
 
 The instructions cover all of Linux, macOS, and Cygwin.
 
-More detailed instructions are contained in the [Installation
-Guide](https://doc.sagemath.org/html/en/installation).
+More details, providing a background for these instructions, can be found
+in the [section "Install from Source Code"](https://doc.sagemath.org/html/en/installation/source.html).
+in the Installation Guide.
 
 1.  Decide on the source/build directory (`SAGE_ROOT`):
 

diff --git a/src/doc/en/constructions/interface_issues.rst b/src/doc/en/constructions/interface_issues.rst
@@ -348,25 +348,6 @@ reloaded into Sage:
     Hello World
     16
 
-.. index:: installation of Sage
-
-.. _section-installALL:
-
-Installation for the impatient
-==============================
-
-We shall explain the basic steps for installing the most recent
-version of Sage (which is the "source" version, not the "binary").
-
-
-#. Download ``sage-*.tar`` (where ``*`` denotes the version number)
-   from the website and save into a directory, say ``HOME``. Type
-   ``tar zxvf sage-*.tar`` in ``HOME``.
-
-#. cd ``sage-*`` (we call this ``SAGE_ROOT``) and type ``make``. Now be
-   patient because this process make take 2 hours or so.
-
-
 .. index:: Python and Sage
 
 Python language program code for Sage commands

diff --git a/src/doc/en/developer/walk_through.rst b/src/doc/en/developer/walk_through.rst
@@ -86,8 +86,11 @@ to the develop branch (latest development release)::
 
 Next, compile Sage, following the instruction in the file
 `README.md <https://github.com/sagemath/sage/#readme>`_ in ``SAGE_ROOT``.
-Additional details can be found in `the Sage installation guide
-<http://doc.sagemath.org/html/en/installation/source.html>`_.
+Additional details can be found in the
+`section on installation from source <../installation/source.html>`_
+in the Sage installation guide.
+If you wish to use conda-forge, see the `section on conda
+<../installation/conda.html>`_.
 
 .. NOTE::
 

diff --git a/src/doc/en/installation/conda.rst b/src/doc/en/installation/conda.rst
@@ -26,19 +26,139 @@ which uses a faster dependency solver than `conda`.
 
     conda install mamba
 
+
+Installing all of SageMath from conda (not for development)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Create a new conda environment containing SageMath, either with ``mamba`` or ``conda``:
 
 .. code-block:: shell
 
     mamba create -n sage sage python=X
     conda create -n sage sage python=X
 
-where ``X`` is version of Python, e.g. ``3.8``.
+where ``X`` is version of Python, e.g. ``3.9``.
 
 To use Sage from there,
 
 * Enter the new environment: ``conda activate sage``
 * Start SageMath: ``sage``
 
-Instructions for using Conda for SageMath development are on
-`the Conda page of the Sage wiki <https://wiki.sagemath.org/Conda>`__.
+
+Using conda to provide system packages for the Sage distribution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If Conda is installed (check by typing ``conda info``), there are two ways to
+prepare for installing SageMath from source:
+
+  - If you are using a git checkout::
+
+      $ ./bootstrap
+
+  - Create a new empty environment and activate::
+
+      $ conda create -n sage-build
+      $ conda activate sage-build
+
+  - Install standard packages recognized by sage's ``spkg-configure`` mechanism::
+
+      $ conda env update --file environment.yml -n sage-build
+
+  - Or install all standard and optional packages recognized by sage::
+
+      $ conda env update --file environment-optional.yml -n sage-build
+
+  - Then the SageMath distribution will be built using the compilers provided by Conda
+    and using many packages installed by Conda::
+
+      $ ./bootstrap
+      $ ./configure --prefix=$CONDA_PREFIX
+      $ make
+
+Using conda to provide all dependencies for the Sage library (experimental)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can build and install the Sage library from source, using conda to
+provide all of its dependencies. This bypasses most of the build
+system of the Sage distribution and is the fastest way to set up an
+environment for Sage development.
+
+Note that this is still an experimental feature and may not work as
+intended.
+
+Here we assume that you are using a git checkout.
+
+  - Optionally, set the build parallelism for the Sage library. Use
+    whatever the meaningful value for your machine is - no more than
+    the number of cores::
+
+      $ export SAGE_NUM_THREADS=24
+
+  - As a recommended step, install the ``mamba`` package manager.  If
+    you skip this step, replace ``mamba`` by ``conda`` in the
+    following steps::
+
+      $ conda install mamba
+
+  - Create and activate a new conda environment that provides the
+    bootstrapping prerequisites. You can replace 3.9 by another Python
+    version::
+
+      $ mamba create -n sage-build python=3.9 \
+            gettext autoconf automake libtool pkg-config
+      $ conda activate sage-build
+
+  - Run ``bootstrap``; this generates the files ``src/environment*.yml`` used
+    in the next step::
+
+      $ ./bootstrap
+
+  - Populate the conda environment with the dependencies of Sage::
+
+      $ mamba env update -n sage-build -f src/environment.yml  # alternatively, use
+
+    Alternatively, you can use ``src/environment-optional.yml``, which will
+    install some additional packages.
+
+  - Activate the conda environment again::
+
+      $ conda activate sage-build
+
+  - Run the ``configure`` script::
+
+      $ ./configure --with-python=$CONDA_PREFIX/bin/python             \
+                    --prefix=$CONDA_PREFIX                             \
+                    $(for pkg in $(./sage -package list :standard:     \
+                                     --has-file spkg-configure.m4      \
+                                     --has-file distros/conda.txt); do \
+                          echo --with-system-$pkg=force;               \
+                      done)
+
+  - Install the build prerequisites of the Sage library::
+
+      $ pip install --no-build-isolation -v -v --editable pkgs/sage-conf pkgs/sage-setup
+
+  - Install the Sage library::
+
+      $ pip install --no-build-isolation -v -v --editable src
+
+  - Verify that Sage has been installed::
+
+      $ sage -c 'print(version())'
+      SageMath version 9.6.beta5, Release Date: 2022-03-12
+
+Note that ``make`` is not used at all.  All dependencies
+(including all Python packages) are provided by conda.
+
+Thus, you will get a working version of Sage much faster.  However,
+note that this will invalidate the use of any Sage-the-distribution
+commands such as ``sage -i``. Do not use them.
+
+By using ``pip install --editable`` in the above steps, the Sage
+library is installed in editable mode.  This means that when you only
+edit Python files, there is no need to rebuild the library; it
+suffices to restart Sage.
+
+After editing any Cython files, rebuild by repeating the command::
+
+  $ pip install --no-build-isolation -v -v --editable src
diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst
@@ -412,72 +412,6 @@ On other systems, check the documentation for your particular operating system.
 
 .. _section_conda_compilers:
 
-Using conda to provide system dependencies
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If Conda is installed (check by typing ``conda info``), there are two ways to
-prepare for installing SageMath from source:
-
-  - If you are using a git checkout::
-
-      $ ./bootstrap
-
-  - Create a new empty environment and activate::
-
-      $ conda create -n sage-build
-      $ conda activate sage-build
-
-  - Install standard packages recognized by sage's ``spkg-configure`` mechanism::
-
-      $ conda env update --file environment.yml -n sage-build
-
-  - Or install all standard and optional packages recognized by sage::
-
-      $ conda env update --file environment-optional.yml -n sage-build
-
-  - Then SageMath will be built using the compilers provided by Conda::
-
-      $ ./bootstrap
-      $ ./configure --prefix=$CONDA_PREFIX
-      $ make
-
-Using conda to provide all SPKGs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Note that this is an experimental feature and may not work as intended.
-
-  - If you are using a git checkout::
-
-      $ ./bootstrap
-
-  - Create a new empty environment and activate::
-
-      $ conda create -n sage
-      $ conda activate sage
-
-  - Install standard packages::
-
-      $ conda env update --file src/environment.yml -n sage
-
-  - Or install all standard and optional packages::
-
-      $ conda env update --file src/environment-optional.yml -n sage
-
-  - Then SageMath will be built using the compilers provided by Conda::
-
-      $ ./bootstrap
-      $ ./configure --prefix=$CONDA_PREFIX
-      $ cd src
-      $ python setup.py install
-
-Note that ``make`` is not used at all.  All dependencies
-(including all Python packages) are provided by conda.
-
-Thus, you will get a working version of Sage much faster.  However,
-note that this will invalidate the use of Sage-the-distribution
-commands such as ``sage -i`` because sage-the-distribution does not
-know about the dependencies unlike in the previous section where
-it did.
 
 
 Notes on using conda