diff --git a/README.md b/README.md index 5f6ebb19f8d..0771a11e7ac 100644 --- 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 index efe93c7edbc..25098b0aaf2 100644 --- 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 index 4a50b71da19..158127070d5 100644 --- 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 `_ in ``SAGE_ROOT``. -Additional details can be found in `the Sage installation guide -`_. +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 index eee5d32dd76..153456747eb 100644 --- a/src/doc/en/installation/conda.rst +++ b/src/doc/en/installation/conda.rst @@ -26,6 +26,10 @@ 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 @@ -33,12 +37,128 @@ Create a new conda environment containing SageMath, either with ``mamba`` or ``c 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 `__. + +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 index 838b1caa0c0..f06e9e0d633 100644 --- 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