diff --git a/README.md b/README.md index fd467aa85f8..7df0d64900f 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 Windows Subsystem for Linux, Cygwin, or +macOS, and Windows (using Windows Subsystem for Linux or virtualization). Detailed information on supported platforms for a specific version of Sage @@ -67,57 +67,6 @@ 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). - -2. Run the `setup-x86_64.exe` graphical installer. Pick the default - options in most cases. At the package selection screen, use the - search bar to find and select at least the following packages: - `bzip2`, `coreutils`, `curl`, `gawk`, `gzip`, `tar`, `wget`, `git`. - -3. Start the Cygwin terminal and ensure you get a working bash prompt. - -4. Make sure the path of your Cygwin home directory does not contain - space characters. - - By default, your username in Cygwin is the same as your username in - Windows. This might contain spaces and other traditionally - non-UNIX-friendly characters, e.g., if it is your full name. You - can check this as follows: - - $ whoami - Erik M. Bray - - This means your default home directory on Cygwin contains this - username verbatim; in the above example, `/home/Erik M. Bray`. - It will save some potential trouble if you change your Cygwin home - directory to contain only alphanumeric characters, for example, - `/home/embray`. The easiest way to do this is to first create - the home directory you want to use instead, then create an - `/etc/passwd` file specifying that directory as your home, as follows: - - $ whocanibe=embray - $ mkdir /home/$whocanibe - $ mkpasswd.exe -l -u "$(whoami)" | sed -r 's,/home/[^:]+,/home/'$whocanibe, > /etc/passwd - - After this, close all Cygwin terminals (ensure nothing in - `C:\cygwin64` is running), then start a new Cygwin terminal and - your home directory should have moved. - - There are [other ways to do - this](https://stackoverflow.com/questions/1494658/how-can-i-change-my-cygwin-home-folder-after-installation), - but the above seems to be the simplest that's still supported. - -5. Install the package manager `apt-cyg`: - - $ curl -OL https://rawgit.com/transcode-open/apt-cyg/master/apt-cyg - $ install apt-cyg /usr/local/bin - $ rm -f apt-cyg - [macOS] Preparing the Platform ------------------------------ @@ -162,7 +111,7 @@ Like many other software packages, Sage is built from source using `./configure`, followed by `make`. However, we strongly recommend to read the following step-by-step instructions for building Sage. -The instructions cover all of Linux, macOS, and Cygwin. +The instructions cover all of Linux, macOS, and WSL. 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). @@ -193,9 +142,6 @@ in the Installation Guide. capitalization when changing into :envvar:`SAGE_ROOT` can lead to build errors for dependencies requiring exact capitalization in path names. - - [Cygwin] Avoid building in home directories of Windows domain - users or in paths with capital letters. - 2. Download/unpack or clone the sources. - Go to https://www.sagemath.org/download-source.html, select a mirror, @@ -236,12 +182,12 @@ in the Installation Guide. line endings are used. Therefore it is crucial that you unpack the source tree from the - Cygwin (or WSL) `bash` using the Cygwin (or WSL) `tar` utility - and not using other Windows tools (including mingw). Likewise, - when using `git`, it is recommended (but not necessary) to use - the Cygwin (or WSL) version of `git`. + WSL `bash` using the WSL `tar` utility and not using other + Windows tools (including mingw). Likewise, when using `git`, it + is recommended (but not necessary) to use the WSL version of + `git`. -3. [Linux, Cygwin] Install the required minimal build prerequisites. +3. [Linux, WSL] Install the required minimal build prerequisites. - Compilers: `gcc`, `gfortran`, `g++` (GCC 6.3 to 12.x and recent versions of Clang (LLVM) are supported). @@ -259,7 +205,6 @@ in the Installation Guide. [build/pkgs/_prereq/distros](build/pkgs/_prereq/distros), the files [arch.txt](build/pkgs/_prereq/distros/arch.txt), - [cygwin.txt](build/pkgs/_prereq/distros/cygwin.txt), [debian.txt](build/pkgs/_prereq/distros/debian.txt) (also for Ubuntu, Linux Mint, etc.), [fedora.txt](build/pkgs/_prereq/distros/fedora.txt) diff --git a/src/doc/en/installation/binary.rst b/src/doc/en/installation/binary.rst index db9c4d3e69a..5fcce7d5943 100644 --- a/src/doc/en/installation/binary.rst +++ b/src/doc/en/installation/binary.rst @@ -25,12 +25,9 @@ This has been discontinued, and the old binaries that are still available there are no longer supported. -Microsoft Windows (Cygwin) --------------------------- +Microsoft Windows +----------------- -SageMath on Windows requires a 64-bit Windows (which is likely to be the case -on a modern computer). If you happen to have a 32-bit Windows, you can consider -the alternatives mentioned at the end of :ref:`installation-guide`. - -To install SageMath on Windows, just download the installer (see the above -"Download Guide" section) and run it. +SageMath used to provide pre-built binaries for Windows based on Cygwin. +This has been discontinued, and the old binaries that can be found +are no longer supported. Use Windows Subsystem for Linux instead. diff --git a/src/doc/en/installation/index.rst b/src/doc/en/installation/index.rst index 6a0b439ac66..8ec84509af2 100644 --- a/src/doc/en/installation/index.rst +++ b/src/doc/en/installation/index.rst @@ -80,10 +80,6 @@ Windows can use any of the installation methods described below for Linux. - - Alternatively, in particular if you cannot use WSL, install - `Cygwin `_ and then build SageMath from source - as described in section :ref:`sec-installation-from-sources`. - Linux ===== diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst index f670cd925b9..39ccff55e52 100644 --- a/src/doc/en/installation/source.rst +++ b/src/doc/en/installation/source.rst @@ -168,8 +168,6 @@ On Redhat-derived systems not all perl components are installed by default and you might have to install the ``perl-ExtUtils-MakeMaker`` package. -On Cygwin, the ``lapack`` and ``liblapack-devel`` packages are required. - Installing prerequisites ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -307,43 +305,6 @@ Some additional optional packages are taken care of by: .. literalinclude:: homebrew-optional.txt -.. _section_cygwinprereqs: - -Cygwin prerequisite installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sage can be built only on the 64-bit version of Cygwin. See -the file `README.md `_ -in ``SAGE_ROOT`` for the most up-to-date instructions for building Sage -on Cygwin. - -Although it is possible to install Sage's dependencies using the Cygwin -graphical installer, it is recommended to install the `apt-cyg -`_ command-line package -installer, which is used for the remainder of these instructions. To -run ``apt-cyg``, you must have already installed (using the graphical -installer) the following packages at a minimum:: - - bzip2 coreutils gawk gzip tar wget - -With the exception of ``wget`` most of these are included in the default -package selection when you install Cygwin. Then, to install ``apt-cyg`` -run:: - - $ curl -OL https://rawgit.com/transcode-open/apt-cyg/master/apt-cyg - $ install apt-cyg /usr/local/bin - $ rm -f apt-cyg - -To install the current set of system packages known to work for building -Sage, run: - -.. literalinclude:: cygwin.txt - -Optional packages that are also known to be installable via system packages -include: - -.. literalinclude:: cygwin-optional.txt - Ubuntu on Windows Subsystem for Linux (WSL) prerequisite installation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -376,6 +337,133 @@ Also see the `related Github issue `_. + +As of Sage 9.7, we no longer recommend attempting to build Sage on +Cygwin and instead suggest that users on Windows 10 and 11 switch to +installing Sage using Windows Subsystem for Linux (WSL), which gives a +better performance and user/developer experience than Cygwin. + +Users on hardware configurations that do not support running WSL, as +well as users on legacy versions of Windows such as Windows 8 may find +it necessary to build Sage on Cygwin. + +.. WARNING:: + + As of Sage 9.7, :trac:`known issues with several packages + ` + will prevent a successful installation. Users need to be prepared + to contribute to Sage by fixing these issues. + +Use the following instructions to get started. + +1. Download `the 64-bit version of Cygwin `_ + (do not get the 32-bit version; it is not supported by Sage). + +2. Run the ``setup-x86_64.exe`` graphical installer. Pick the default + options in most cases. At the package selection screen, use the + search bar to find and select at least the following packages: + ``bzip2``, ``coreutils``, ``curl``, ``gawk``, ``gzip``, ``tar``, ``wget``, ``git``. + +3. Start the Cygwin terminal and ensure you get a working bash prompt. + +4. Make sure the path of your Cygwin home directory does not contain + space characters. Also avoid building in home directories of Windows domain + users or in paths with capital letters. + + By default, your username in Cygwin is the same as your username in + Windows. This might contain spaces and other traditionally + non-UNIX-friendly characters, e.g., if it is your full name. You + can check this as follows: + + $ whoami + Erik M. Bray + + This means your default home directory on Cygwin contains this + username verbatim; in the above example, `/home/Erik M. Bray`. + It will save some potential trouble if you change your Cygwin home + directory to contain only alphanumeric characters, for example, + `/home/embray`. The easiest way to do this is to first create + the home directory you want to use instead, then create an + `/etc/passwd` file specifying that directory as your home, as follows: + + $ whocanibe=embray + $ mkdir /home/$whocanibe + $ mkpasswd.exe -l -u "$(whoami)" | sed -r 's,/home/[^:]+,/home/'$whocanibe, > /etc/passwd + + After this, close all Cygwin terminals (ensure nothing in + `C:\cygwin64` is running), then start a new Cygwin terminal and + your home directory should have moved. + + There are [other ways to do + this](https://stackoverflow.com/questions/1494658/how-can-i-change-my-cygwin-home-folder-after-installation), + but the above seems to be the simplest that's still supported. + +5. (Optional) Although it is possible to install Sage's dependencies using the + Cygwin graphical installer, it is recommended to install the + `apt-cyg `_ + command-line package installer, which is used for the remainder of + these instructions. To install ``apt-cyg``, run:: + + $ curl -OL https://rawgit.com/transcode-open/apt-cyg/master/apt-cyg + $ install apt-cyg /usr/local/bin + $ rm -f apt-cyg + +6. Then, to install the current set of system packages known to work for building + Sage, run the following command (or use the graphical installer to + select and install these packages): + + .. literalinclude:: cygwin.txt + + Optional packages that are also known to be installable via system packages + include: + + .. literalinclude:: cygwin-optional.txt + +.. NOTE:: + + On Cygwin, at any point in time after building/installing software, + it may be required to "rebase" ``dll`` files. + Sage provides some scripts, located in :file:`$SAGE_LOCAL/bin`, to do so: + + - ``sage-rebaseall.sh``, a shell script which calls Cygwin's + ``rebaseall`` program. It must be run within a ``dash`` shell + from the :envvar:`SAGE_ROOT` directory after all other Cygwin + processes have been shut down and needs write-access to the + system-wide rebase database located at + :file:`/etc/rebase.db.i386`, which usually means administrator + privileges. It updates the system-wide database and adds Sage + dlls to it, so that subsequent calls to ``rebaseall`` will take + them into account. + + - ``sage-rebase.sh``, a shell script which calls Cygwin's ``rebase`` program + together with the ``-O/--oblivious`` option. + It must be run within a shell from :envvar:`SAGE_ROOT` directory. + Contrary to the ``sage-rebaseall.sh`` script, it neither updates the + system-wide database, nor adds Sage dlls to it. + Therefore, subsequent calls to ``rebaseall`` will not take them into account. + + - ``sage-rebaseall.bat`` (respectively ``sage-rebase.bat``), an MS-DOS batch + file which calls the ``sage-rebaseall.sh`` (respectively ``sage-rebase.sh``) + script. + It must be run from a Windows command prompt, after adjusting + :envvar:`SAGE_ROOT` to the Windows location of Sage's home directory, and, if + Cygwin is installed in a non-standard location, adjusting + :envvar:`CYGWIN_ROOT` as well. + + Some systems may encounter this problem frequently enough to make building or + testing difficult. + If executing the above scripts or directly calling ``rebaseall`` does not solve + rebasing issues, deleting the system-wide database and then regenerating it + from scratch, e.g., by executing ``sage-rebaseall.sh``, might help. + + Other platforms ^^^^^^^^^^^^^^^ @@ -735,46 +823,6 @@ General procedure #. Have fun! Discover some amazing conjectures! -Rebasing issues on Cygwin -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Building on Cygwin will occasionally require "rebasing" ``dll`` files. -Sage provides some scripts, located in :file:`$SAGE_LOCAL/bin`, to do so: - -- ``sage-rebaseall.sh``, a shell script which calls Cygwin's ``rebaseall`` - program. - It must be run within a ``dash`` shell from the :envvar:`SAGE_ROOT` directory - after all other Cygwin processes have been shut down and needs write-access - to the system-wide rebase database located at :file:`/etc/rebase.db.i386`, - which usually means administrator privileges. - It updates the system-wide database and adds Sage dlls to it, so that - subsequent calls to ``rebaseall`` will take them into account. -- ``sage-rebase.sh``, a shell script which calls Cygwin's ``rebase`` program - together with the ``-O/--oblivious`` option. - It must be run within a shell from :envvar:`SAGE_ROOT` directory. - Contrary to the ``sage-rebaseall.sh`` script, it neither updates the - system-wide database, nor adds Sage dlls to it. - Therefore, subsequent calls to ``rebaseall`` will not take them into account. -- ``sage-rebaseall.bat`` (respectively ``sage-rebase.bat``), an MS-DOS batch - file which calls the ``sage-rebaseall.sh`` (respectively ``sage-rebase.sh``) - script. - It must be run from a Windows command prompt, after adjusting - :envvar:`SAGE_ROOT` to the Windows location of Sage's home directory, and, if - Cygwin is installed in a non-standard location, adjusting - :envvar:`CYGWIN_ROOT` as well. - -Some systems may encounter this problem frequently enough to make building or -testing difficult. -If executing the above scripts or directly calling ``rebaseall`` does not solve -rebasing issues, deleting the system-wide database and then regenerating it -from scratch, e.g., by executing ``sage-rebaseall.sh``, might help. - -Finally, on Cygwin, one should also avoid the following: - -- building in home directories of Windows domain users; -- building in paths with capital letters - (see :trac:`13343`, although there has been some success doing so). - .. _section_make: