From 8e363efb604416f41e6a91e0a6337317c6a9cdac Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Mon, 4 Apr 2022 11:12:59 -0700 Subject: [PATCH 01/21] src/doc/en/installation/source.rst: Update conda sections from https://wiki.sagemath.org/Conda --- src/doc/en/installation/source.rst | 98 +++++++++++++++++++++++------- 1 file changed, 75 insertions(+), 23 deletions(-) diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst index 838b1caa0c0..d62ea5ccc58 100644 --- a/src/doc/en/installation/source.rst +++ b/src/doc/en/installation/source.rst @@ -412,8 +412,8 @@ On other systems, check the documentation for your particular operating system. .. _section_conda_compilers: -Using conda to provide system dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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: @@ -435,49 +435,101 @@ prepare for installing SageMath from source: $ conda env update --file environment-optional.yml -n sage-build - - Then SageMath will be built using the compilers provided by Conda:: + - 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 SPKGs -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Using conda to provide all dependencies for the Sage library (experimental) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Note that this is an experimental feature and may not work as intended. +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. - - If you are using a git checkout:: +Note that this is still an experimental feature and may not work as +intended. - $ ./bootstrap +Here we assume that you are using a git checkout. - - Create a new empty environment and activate:: + - 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:: - $ conda create -n sage - $ conda activate sage + $ export SAGE_NUM_THREADS=24 - - Install standard packages:: + - As a recommended step, install the ``mamba`` package manager. If + you skip this step, replace ``mamba`` by ``conda`` in the + following steps:: - $ conda env update --file src/environment.yml -n sage + $ conda install mamba - - Or install all standard and optional packages:: + - Create and activate a new conda environment that provides the + bootstrapping prerequisites. You can replace 3.9 by another Python + version:: - $ conda env update --file src/environment-optional.yml -n sage + $ mamba create -n sage-build python=3.9 \ + gettext autoconf automake libtool pkg-config + $ conda activate sage-build - - Then SageMath will be built using the compilers provided by Conda:: + - Run ``bootstrap``; this generates the files ``src/environment*.yml`` used + in the next step:: $ ./bootstrap - $ ./configure --prefix=$CONDA_PREFIX - $ cd src - $ python setup.py install + + - 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 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. +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 + Notes on using conda From 10015e6100ce83a6118c7b781ac71dd5a38de3de Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Mon, 4 Apr 2022 12:06:46 -0700 Subject: [PATCH 02/21] src/doc/en/installation/conda.rst: Move everything on conda (except disabling it) here from source.rst --- src/doc/en/installation/conda.rst | 126 ++++++++++++++++++++++++++++- src/doc/en/installation/source.rst | 118 --------------------------- 2 files changed, 123 insertions(+), 121 deletions(-) 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 d62ea5ccc58..f06e9e0d633 100644 --- a/src/doc/en/installation/source.rst +++ b/src/doc/en/installation/source.rst @@ -412,124 +412,6 @@ On other systems, check the documentation for your particular operating system. .. _section_conda_compilers: -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 - Notes on using conda From 6432a0281b76a3b77c0e93c55acabd36ccd5625d Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Mon, 4 Apr 2022 12:11:53 -0700 Subject: [PATCH 03/21] src/doc/en/developer/walk_through.rst: Link also to ../installation/conda.html --- src/doc/en/developer/walk_through.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) 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:: From d190d13502ebdfcba4e6c650fe8d6ede9fb2b94c Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Mon, 4 Apr 2022 13:53:10 -0700 Subject: [PATCH 04/21] src/doc/en/constructions/interface_issues.rst: Remove outdated short installation instructions --- src/doc/en/constructions/interface_issues.rst | 19 ------------------- 1 file changed, 19 deletions(-) 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 From 516701dbc7dd9738fb9d77ee3ac210c3919c8cb3 Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Mon, 4 Apr 2022 14:09:43 -0700 Subject: [PATCH 05/21] README.md: Use more specific link to 'Install from Source Code' section --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) 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`): From b6f0404faf0cfc03baaebb07aa180d3310419c4f Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 12:29:39 -0700 Subject: [PATCH 06/21] src/doc/en/installation/index.rst: Point to conda section in the manual, not the wiki --- src/doc/en/installation/conda.rst | 7 +++++++ src/doc/en/installation/index.rst | 8 ++++---- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/src/doc/en/installation/conda.rst b/src/doc/en/installation/conda.rst index 153456747eb..2b2cda9bd12 100644 --- a/src/doc/en/installation/conda.rst +++ b/src/doc/en/installation/conda.rst @@ -27,6 +27,8 @@ which uses a faster dependency solver than `conda`. conda install mamba +.. _sec-installation-conda-binary: + Installing all of SageMath from conda (not for development) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -45,6 +47,8 @@ To use Sage from there, * Start SageMath: ``sage`` +.. _sec-installation-conda-source: + Using conda to provide system packages for the Sage distribution ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -75,6 +79,9 @@ prepare for installing SageMath from source: $ ./configure --prefix=$CONDA_PREFIX $ make + +.. _sec-installation-conda-develop: + Using conda to provide all dependencies for the Sage library (experimental) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/src/doc/en/installation/index.rst b/src/doc/en/installation/index.rst index 4eb3a660e09..529daa4eb41 100644 --- a/src/doc/en/installation/index.rst +++ b/src/doc/en/installation/index.rst @@ -29,8 +29,8 @@ SageMath release. - Then build SageMath from source as described in section :ref:`sec-installation-from-sources`. - - Alternatively, follow the instructions in the SageMath wiki on - `Conda for Sage Developers `_; + - Alternatively, follow the instructions in section + :ref:`sec-installation-conda-develop`; these describe an experimental method that gets all required packages, including Python packages, from conda-forge. @@ -67,8 +67,8 @@ SageMath release. - Then build SageMath from source as described in section :ref:`sec-installation-from-sources`. - - Alternatively, follow the instructions in the SageMath wiki on - `Conda for Sage Developers `_; + - Alternatively, follow the instructions in section + :ref:`sec-installation-conda-develop`; these describe an experimental method that gets all required packages, including Python packages, from conda-forge. From 6cf090ebcf03e4b5600d40419716dec3a39330c2 Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 12:52:18 -0700 Subject: [PATCH 07/21] README.md: Point first to the decision tree in the installation guide; remove mention of binaries --- README.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 0771a11e7ac..b2ac8e5ba90 100644 --- a/README.md +++ b/README.md @@ -19,17 +19,14 @@ for modules and functions list the authors. Getting Started --------------- -If you downloaded a [binary](https://www.sagemath.org/download.html) -(i.e. a version of SageMath prepared for a specific operating system), -Sage is ready to start -- just open a terminal in the directory where -you extracted the binary archive and type: - - $ ./sage - -(Note that the first run will take more time, as Sage needs to get itself ready.) - -If you downloaded the [sources](https://www.sagemath.org/download-source.html), -please read below on how to build Sage and work around common issues. +The [Sage Installation Guide](https://doc.sagemath.org/html/en/installation/index.html) +provides a decision tree that guides you to the type of installation +that will work best for you. + +If you have already cloned the git repository or downloaded the +[sources](https://www.sagemath.org/download-source.html) in the form +of a tarball, please read the self-contained instructions below on how +to build Sage and work around common issues. If you have questions or encounter problems, please do not hesitate to email the [sage-support mailing list](https://groups.google.com/group/sage-support) From 296fd12e8b5316fa9117a009a27c062e28ceb03f Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 12:52:39 -0700 Subject: [PATCH 08/21] README.md: Prefer WSL to Cygwin --- README.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index b2ac8e5ba90..e99c549a31d 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ Supported Platforms ------------------- Sage attempts to support all major Linux distributions, recent versions of -macOS, and Windows (using Cygwin, Windows Subsystem for Linux, or +macOS, and Windows (using Windows Subsystem for Linux, Cygwin, or virtualization). Detailed information on supported platforms for a specific version of Sage @@ -59,8 +59,17 @@ and follow the instructions on [Windows] Preparing the Platform -------------------------------- -The 64-bit version of Cygwin, also known as Cygwin64, is the current -target for Sage support on Windows. +The preferred way to run Sage on Windows is using the [Windows Subsystem for +Linux](https://docs.microsoft.com/en-us/windows/wsl/faq), which allows +you to install a standard Linux distribution such as Ubuntu within +your Windows. Then all instructions for installation in Linux apply. + +As an alternative, you can also run Linux on Windows using Docker (see +above) or other virtualization solutions. + +Finally, Sage also works on the 64-bit version of `Cygwin +`_. If you wish to use Cygwin, use the following +instructions to get started. 1. Download [cygwin64](https://cygwin.com/install.html) (do not get the 32-bit version; it is not supported by Sage). @@ -109,14 +118,6 @@ target for Sage support on Windows. $ install apt-cyg /usr/local/bin $ rm -f apt-cyg -An alternative to Cygwin is to use [Windows Subsystem for -Linux](https://docs.microsoft.com/en-us/windows/wsl/faq), which allows -you to install a standard Linux distribution such as Ubuntu within -your Windows. Then all instructions for installation in Linux apply. - -As another alternative, you can also run Linux on Windows using Docker -(see above) or other virtualization solutions. - [macOS] Preparing the Platform ------------------------------ From 9140ee7b387b22159fcec47bd8b85672cb402716 Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 12:58:58 -0700 Subject: [PATCH 09/21] README.md [macOS]: Only need the Xcode CLT, not actual Xcode; remove instructions for ancient macOS --- README.md | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index e99c549a31d..9413192e5b5 100644 --- a/README.md +++ b/README.md @@ -121,17 +121,9 @@ instructions to get started. [macOS] Preparing the Platform ------------------------------ -Make sure you have installed the most current version of Xcode -supported on your version of macOS. If you don't, either go to -https://developer.apple.com/, sign up, and download the free Xcode -package, or get it from Apple's app store. - -You also need to install the "command line tools": After installing -Xcode, run `xcode-select --install` from a terminal window; then click -"Install" in the pop-up window. (When using Mountain Lion or earlier, -you need to install the command line tools from Xcode: run Xcode; then -from the File menu, choose "Preferences", then the "Downloads" tab, -and then "Install" the Command Line Tools.) +You will need the Xcode Command Line Tools. Open a terminal window +and run `xcode-select --install`; then click "Install" in the pop-up +window. Optionally, you can consider installing Homebrew ("the missing package manager for macOS") from https://brew.sh/, which can provide libraries From 9cef218fd4ee492eda468d12120f65f138d362f4 Mon Sep 17 00:00:00 2001 From: Yuan Zhou Date: Tue, 5 Apr 2022 16:39:00 -0400 Subject: [PATCH 10/21] typos in developer's guide, indicate sage directory --- src/doc/en/developer/walk_through.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/en/developer/walk_through.rst b/src/doc/en/developer/walk_through.rst index 158127070d5..bea22fd5c4c 100644 --- a/src/doc/en/developer/walk_through.rst +++ b/src/doc/en/developer/walk_through.rst @@ -116,7 +116,7 @@ Sage source code and which you can upload to trac tickets. To begin with, type the command ``git branch``. You will see the following:: - [user@localhost]$ git branch + [user@localhost sage]$ git branch * develop master @@ -144,7 +144,7 @@ to it. For this, you have to use ``git checkout``:: Now if you use the command ``git branch``, you will see the following:: - [user@localhost]$ git branch + [user@localhost sage]$ git branch develop * last_twin_prime master From 9df503518c30002e2badb5de9e443c6cf79f09ed Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 13:34:21 -0700 Subject: [PATCH 11/21] src/doc/en/installation/source.rst: Remove instructions for ancient OS X versions --- src/doc/en/installation/source.rst | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst index f06e9e0d633..b0b18ed1410 100644 --- a/src/doc/en/installation/source.rst +++ b/src/doc/en/installation/source.rst @@ -265,23 +265,15 @@ On macOS systems, you need a recent version of `Command Line Tools `_. It provides all the above requirements. +Run the command ``xcode-select --install`` from a Terminal window and click "Install" +in the pop-up dialog box. + If you have already installed `Xcode `_ (which at the time of writing is freely available in the Mac App Store, or through https://developer.apple.com/downloads/ provided you registered for an Apple Developer account), you can install the command line tools from there as well. -- With OS X Mavericks or Yosemite, run the command - ``xcode-select --install`` from a Terminal window and click "Install" - in the pop-up dialog box. - -- Using OS X Mountain Lion or earlier, run Xcode, open its "Downloads" - preference pane and install the command line tools from there. - -- On pre-Lion macOS systems, the command line tools are not available as a - separate download and you have to install the full-blown Xcode supporting your - system version. - If you have not installed `Xcode `_ you can get these tools as a relatively small download, but it does require a registration. @@ -1308,4 +1300,4 @@ the directory where you want to install Sage. -**This page was last updated in December 2021 (Sage 9.5).** +**This page was last updated in April 2022 (Sage 9.6).** From 0bb7e3620b871344d3bce41c67d469e18d5d6b74 Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 14:03:46 -0700 Subject: [PATCH 12/21] README.md, src/doc/en/installation/source.rst: Update Python versions --- README.md | 4 ++-- src/doc/en/installation/source.rst | 14 ++++++++------ 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 9413192e5b5..f3cac26daff 100644 --- a/README.md +++ b/README.md @@ -221,8 +221,8 @@ in the Installation Guide. ``ExtUtils::MakeMaker``), `ranlib`, `git`, `tar`, `bc`. - Python 3.4 or later, or Python 2.7, a full installation including - `urllib`; but ideally version 3.7.x, 3.8.x, or 3.9.x, which will - avoid having to build Sage's own copy of Python 3. + `urllib`; but ideally version 3.7.x, 3.8.x, 3.9.x, or 3.10.x, which + will avoid having to build Sage's own copy of Python 3. We have collected lists of system packages that provide these build prerequisites. See, in the folder diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst index b0b18ed1410..d5900560188 100644 --- a/src/doc/en/installation/source.rst +++ b/src/doc/en/installation/source.rst @@ -147,24 +147,26 @@ Python for venv ^^^^^^^^^^^^^^^ By default, Sage will try to use system's `python3` to set up a virtual -environment, a.k.a. `venv `_ +environment, a.k.a. `venv `_ rather than building a Python 3 installation from scratch. -Use the configure option ``--without-system-python3`` in case you want Python 3 +Use the ``configure`` option ``--without-system-python3`` in case you want Python 3 built from scratch. -Sage will accept versions 3.7.x to 3.9.x. +Sage will accept versions 3.7.x to 3.10.x. You can also use ``--with-python=/path/to/python3_binary`` to tell Sage to use ``/path/to/python3_binary`` to set up the venv. Note that setting up venv requires a number of Python modules to be available within the Python in question. Currently, -for Sage 9.2, these modules are as follows: sqlite3, ctypes, math, hashlib, crypt, -readline, socket, zlib, distutils.core - they will be checked for by configure. +for Sage 9.2, these modules are as follows: ``sqlite3``, ``ctypes``, ``math``, +``hashlib``, ``crypt``, ``readline``, ``socket``, ``zlib``, ``distutils.core`` - +they will be checked for by the ``configure`` script. Other notes ^^^^^^^^^^^ -After extracting the Sage tarball, the subdirectory :file:`upstream` +After extracting the Sage source tarball, the subdirectory :file:`upstream` contains the source distributions for everything on which Sage depends. + If cloned from a git repository, the upstream tarballs will be downloaded, verified, and cached as part of the Sage installation process. We emphasize that all of this software is included with Sage, so you do not From 42b8e47672fa710ff85de9700f6380053482b929 Mon Sep 17 00:00:00 2001 From: Yuan Zhou Date: Tue, 5 Apr 2022 18:03:08 -0400 Subject: [PATCH 13/21] fix a typo in developer/tools document --- src/doc/en/developer/tools.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/en/developer/tools.rst b/src/doc/en/developer/tools.rst index 77966e4f203..bc255c64c28 100644 --- a/src/doc/en/developer/tools.rst +++ b/src/doc/en/developer/tools.rst @@ -36,7 +36,7 @@ The tox configuration ``SAGE_ROOT/src/tox.ini`` can be invoked by using the comm you can just type ``tox`` instead.) This configuration provides an entry point for various testing/linting methods, -known as "tox environments". We can type ``./sage --advanced`` so see what is +known as "tox environments". We can type ``./sage --advanced`` to see what is available:: $ ./sage --advanced From b46c95330f6dc55e547dc9a85783195e16ac7432 Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 15:46:41 -0700 Subject: [PATCH 14/21] README: Document --enable-editable and --enable-download-from-upstream-url --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index f3cac26daff..130ce6739e0 100644 --- a/README.md +++ b/README.md @@ -280,6 +280,25 @@ in the Installation Guide. $ ./configure --help + Some notable options for Sage developers are the following: + + - Use `./configure --enable-editable` to configure the Sage distribution + to install the Sage library in "develop" ("editable", "in-place") mode + instead of using the Sage library's custom incremental build system. + + It has the benefit that to try out changes to Python files, one does not + need to run `./sage -b` any more; restarting Sage is enough. It may also + have benefits in certain develop environments that get confused by + sagelib's custom build system. + + Note that in an editable install, the source directory will be cluttered + with build artifacts (but they are `.gitignored`). This is normal. + + - Use `./configure --enable-download-from-upstream-url` to allow + downloading packages from their upstream URL if they cannot (yet) be + found on the Sage mirrors. This is useful for trying out ticket branches + that make package upgrades. + 9. Optional, but highly recommended: Set some environment variables to customize the build. From a3ffe84a836b5da8d7cd15c13eaef639b240f8cf Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 16:12:43 -0700 Subject: [PATCH 15/21] README.md: Instructions for Apple Silicon --- README.md | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 130ce6739e0..cb852581421 100644 --- a/README.md +++ b/README.md @@ -121,13 +121,34 @@ instructions to get started. [macOS] Preparing the Platform ------------------------------ -You will need the Xcode Command Line Tools. Open a terminal window -and run `xcode-select --install`; then click "Install" in the pop-up -window. - -Optionally, you can consider installing Homebrew ("the missing package -manager for macOS") from https://brew.sh/, which can provide libraries -such as `gfortran`, `gmp`, etc. +If you wish to use conda, please see the [section on +conda](https://doc.sagemath.org/html/en/installation/conda.html) in the Sage +Installation Manual for guidance instead of the following instructions. + +In installations without conda, we strongly recommend to use Homebrew ("the +missing package manager for macOS") from https://brew.sh/, which provides +the ``gfortran`` compiler and many libraries. + +If your Mac uses the Apple Silicon (M1, arm64) architecture: + +- Using Homebrew is required because it provides a version of ``gfortran`` + with necessary changes for this platform that are not in a released upstream + version of GCC. (The ``gfortran`` package that comes with the Sage + distribution is not suitable for the M1.) + +- If you set up your Mac by transfering files from an older Mac, make sure + that the directory ``/usr/local`` does not contain an old copy of Homebrew + (or other software) for the x86_64 architecture that you may have copied + over. Note that Homebrew for the M1 is installed in ``/opt/homebrew``, not + ``/usr/local``. + +If your Mac uses the Intel (x86_64) architecture: + +- If you do not wish to install Homebrew, you will need to install the latest + version of Xcode Command Line Tools. Open a terminal window and run + `xcode-select --install`; then click "Install" in the pop-up window. + If the Xcode Command Line Tools are already installed, you may want to + check if they need to be updated by typing `softwareupdate -l`. Instructions to Build from Source --------------------------------- From d7708df1528d4e50301c7e2c1a4ed31ca5a1fe72 Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 16:21:41 -0700 Subject: [PATCH 16/21] README.md: Restructure macOS prep instructions --- README.md | 41 +++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index cb852581421..3c04c604a57 100644 --- a/README.md +++ b/README.md @@ -121,34 +121,39 @@ instructions to get started. [macOS] Preparing the Platform ------------------------------ -If you wish to use conda, please see the [section on -conda](https://doc.sagemath.org/html/en/installation/conda.html) in the Sage -Installation Manual for guidance instead of the following instructions. - -In installations without conda, we strongly recommend to use Homebrew ("the -missing package manager for macOS") from https://brew.sh/, which provides -the ``gfortran`` compiler and many libraries. - If your Mac uses the Apple Silicon (M1, arm64) architecture: -- Using Homebrew is required because it provides a version of ``gfortran`` - with necessary changes for this platform that are not in a released upstream - version of GCC. (The ``gfortran`` package that comes with the Sage - distribution is not suitable for the M1.) - - If you set up your Mac by transfering files from an older Mac, make sure that the directory ``/usr/local`` does not contain an old copy of Homebrew (or other software) for the x86_64 architecture that you may have copied over. Note that Homebrew for the M1 is installed in ``/opt/homebrew``, not ``/usr/local``. +- If you wish to use conda, please see the [section on + conda](https://doc.sagemath.org/html/en/installation/conda.html) in the Sage + Installation Manual for guidance. + +- Otherwise, using Homebrew ("the missing package manager for macOS") from + https://brew.sh/ required because it provides a version of ``gfortran`` with + necessary changes for this platform that are not in a released upstream + version of GCC. (The ``gfortran`` package that comes with the Sage + distribution is not suitable for the M1.) + If your Mac uses the Intel (x86_64) architecture: -- If you do not wish to install Homebrew, you will need to install the latest - version of Xcode Command Line Tools. Open a terminal window and run - `xcode-select --install`; then click "Install" in the pop-up window. - If the Xcode Command Line Tools are already installed, you may want to - check if they need to be updated by typing `softwareupdate -l`. +- If you wish to use conda, please see the [section on + conda](https://doc.sagemath.org/html/en/installation/conda.html) in the Sage + Installation Manual for guidance. + +- Otherwise, we strongly recommend to use Homebrew ("the missing package + manager for macOS") from https://brew.sh/, which provides the ``gfortran`` + compiler and many libraries. + +- Otherwise, if you do not wish to install Homebrew, you will need to install + the latest version of Xcode Command Line Tools. Open a terminal window and + run `xcode-select --install`; then click "Install" in the pop-up window. If + the Xcode Command Line Tools are already installed, you may want to check if + they need to be updated by typing `softwareupdate -l`. Instructions to Build from Source --------------------------------- From 2e1d22d63fa6b4968ede6f2f69ac15d3a7a1a064 Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 16:48:31 -0700 Subject: [PATCH 17/21] src/doc/en/installation/source.rst: Remove instructions for Solaris, AIX, HP-UX --- src/doc/en/installation/source.rst | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst index d5900560188..906cad5599a 100644 --- a/src/doc/en/installation/source.rst +++ b/src/doc/en/installation/source.rst @@ -433,27 +433,6 @@ Specific notes for ``make`` and ``tar`` On macOS, the system-wide BSD ``tar`` supplied will build Sage, so there is no need to install the GNU ``tar``. -On Solaris or OpenSolaris, the Sun/Oracle versions of ``make`` and ``tar`` are -unsuitable for building Sage. -Therefore, you must have the GNU versions of ``make`` and ``tar`` installed and -they must be the first ``make`` and ``tar`` in your :envvar:`PATH`. - -On Solaris 10, a version of GNU ``make`` may be found at -:file:`/usr/sfw/bin/gmake`, -but you will need to copy it somewhere else and rename it to ``make``. -The same is true for GNU ``tar``; a version of GNU ``tar`` may be found at -:file:`/usr/sfw/bin/gtar`, -but it will need to be copied somewhere else and renamed to ``tar``. -It is recommended to create a directory :file:`$HOME/bins-for-sage` and to put -the GNU versions of ``tar`` and ``make`` in that directory. -Then ensure that :file:`$HOME/bins-for-sage` is first in your :envvar:`PATH`. -That's because Sage also needs :file:`/usr/ccs/bin` in your :envvar:`PATH` to -execute programs like ``ar`` and ``ranlib``, but :file:`/usr/ccs/bin` has the -Sun/Oracle versions of ``make`` and ``tar`` in it. - -If you attempt to build Sage on AIX or HP-UX, you will need to install both -GNU ``make`` and GNU ``tar``. - .. _section_compilers: Using alternative compilers From 9ca39a275edec33fbc256193e2823c90218cf208 Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 17:36:05 -0700 Subject: [PATCH 18/21] README.md: Point to developer guide for git details --- README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3c04c604a57..93b1d566829 100644 --- a/README.md +++ b/README.md @@ -196,7 +196,7 @@ in the Installation Guide. - [Cygwin] Avoid building in home directories of Windows domain users or in paths with capital letters. -2. Download/unpack the sources. +2. Download/unpack or clone the sources. - Go to https://www.sagemath.org/download-source.html, select a mirror, and download the file :file:`sage-x.y.tar.gz`. @@ -214,12 +214,16 @@ in the Installation Guide. $ cd sage-x.y/ # adapt x.y - - [Git] Alternatively, clone the Sage git repository: + - [Git] Alternatively, and required for Sage development, clone the Sage + git repository: $ ORIG=https://github.com/sagemath/sage.git $ git clone -c core.symlinks=true --branch develop --tags $ORIG - This will create the directory `sage`. + This will create the directory `sage`. (See the section + [Setting up git](https://doc.sagemath.org/html/en/developer/git_setup.html) + and the following sections in the Sage Developer's Guide + for more information.) Change into it and pick the branch you need, typically the latest development branch: From f1e1166e90ec89a10be2754808e015dfdc82936b Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 17:42:56 -0700 Subject: [PATCH 19/21] src/doc/en/installation/source.rst: Point to README.md for step-by-step instructions --- src/doc/en/installation/source.rst | 34 +++++++----------------------- 1 file changed, 8 insertions(+), 26 deletions(-) diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst index 906cad5599a..34b44aea2e3 100644 --- a/src/doc/en/installation/source.rst +++ b/src/doc/en/installation/source.rst @@ -14,41 +14,23 @@ Install from Source Code .. contents:: Table of contents :depth: 2 -More familiarity with computers may be required to build Sage from -the :wikipedia:`source code `. -If you do have all the :ref:`pre-requisite tools `, -the process should be completely -painless, basically consisting in extracting the source tarball and typing -``make``. It can take your computer a while to build Sage from the source code, -although the procedure is fully automated and should need no human -intervention. +Some familiarity with the use of the Unix command line may be required to +build Sage from the :wikipedia:`source code `. Building Sage from the source code has the major advantage that your install will be optimized for your particular computer and should therefore offer better performance and compatibility than a binary install. + Moreover, it offers you full development capabilities: you can change absolutely any part of Sage or the programs on which it depends, and recompile the modified parts. -`Download the Sage source code `_ -or get it from the `git repository `_. -Note: if you are installing Sage for development, you should rather follow -the instructions in -`The Sage Developer's Guide `_. - -It is also possible to download a -`binary distribution `_ -for some operating systems, rather than compiling from source. - -Supported platforms -------------------- - -Sage runs on all major :wikipedia:`Linux ` -distributions, `macOS `_ , and Windows -(via the `Cygwin `_ Linux API layer). +See the file `README.md `_ +in ``SAGE_ROOT`` for information on supported platforms and +step-by-step instructions. -Other installation options for Windows are using the Windows Subsystem -for Linux (WSL), or with the aid of a :wikipedia:`virtual machine `. +The following sections provide some additional details. Most users +will not need to read them. .. _section-prereqs: From 3f6c6e00e6cc8a4d593ab4d0a80ab0cb22bfebc1 Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Tue, 5 Apr 2022 20:04:41 -0700 Subject: [PATCH 20/21] src/doc/en/developer/workspace.rst: Link to Trac #30500 --- src/doc/en/developer/coding_basics.rst | 2 +- src/doc/en/developer/workspace.rst | 11 ++++++++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/src/doc/en/developer/coding_basics.rst b/src/doc/en/developer/coding_basics.rst index 3dc549e71a7..76989fa5923 100644 --- a/src/doc/en/developer/coding_basics.rst +++ b/src/doc/en/developer/coding_basics.rst @@ -1283,7 +1283,7 @@ whitespace, see https://www.emacswiki.org/emacs/DeletingWhitespace for various solutions. If you use another editor, we recommend to configure it so you do not -add tabs to files. +add tabs to files. See :ref:`section-ide`. Global Options diff --git a/src/doc/en/developer/workspace.rst b/src/doc/en/developer/workspace.rst index 238f171fd82..fcca167149a 100644 --- a/src/doc/en/developer/workspace.rst +++ b/src/doc/en/developer/workspace.rst @@ -6,10 +6,19 @@ Setting up your workspace ========================= +.. _section-ide: + +Configuring text editors and IDEs for use with Sage +=================================================== + +In Meta-ticket :trac:`30500` we are collecting instructions how to configure +various text editors and IDEs for use with Sage. + + .. _section-gitpod: Gitpod -================= +====== `Gitpod `_ is a free service that will let you build and run Sage from an online development environment based on VS Code. From 8716d800b03eb0ce2a19b5dfcc51c7282c9bfcff Mon Sep 17 00:00:00 2001 From: Matthias Koeppe Date: Wed, 6 Apr 2022 10:35:44 -0700 Subject: [PATCH 21/21] src/doc/en/installation/source.rst: Update required venv Python extension modules from build/pkgs/python3/spkg-configure.m4 --- src/doc/en/installation/source.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst index 34b44aea2e3..dc24eb9f0dd 100644 --- a/src/doc/en/installation/source.rst +++ b/src/doc/en/installation/source.rst @@ -139,8 +139,8 @@ Sage will accept versions 3.7.x to 3.10.x. You can also use ``--with-python=/path/to/python3_binary`` to tell Sage to use ``/path/to/python3_binary`` to set up the venv. Note that setting up venv requires a number of Python modules to be available within the Python in question. Currently, -for Sage 9.2, these modules are as follows: ``sqlite3``, ``ctypes``, ``math``, -``hashlib``, ``crypt``, ``readline``, ``socket``, ``zlib``, ``distutils.core`` - +for Sage 9.6, these modules are as follows: ``sqlite3``, ``ctypes``, ``math``, +``hashlib``, ``crypt``, ``socket``, ``zlib``, ``distutils.core``, ``ssl`` - they will be checked for by the ``configure`` script. Other notes