Skip to content

Commit

Permalink
Merge #34301
Browse files Browse the repository at this point in the history
  • Loading branch information
Matthias Koeppe committed Aug 27, 2022
2 parents c96c7c5 + e3af6c9 commit c39312c
Show file tree
Hide file tree
Showing 4 changed files with 139 additions and 153 deletions.
69 changes: 7 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
<https://cygwin.com/>`_. 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
------------------------------

Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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).
Expand All @@ -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)
Expand Down
13 changes: 5 additions & 8 deletions src/doc/en/installation/binary.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 0 additions & 4 deletions src/doc/en/installation/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://cygwin.com/>`_ and then build SageMath from source
as described in section :ref:`sec-installation-from-sources`.

Linux
=====

Expand Down
206 changes: 127 additions & 79 deletions src/doc/en/installation/source.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

On Linux systems (e.g., Ubuntu, Redhat, etc), ``ar`` and ``ranlib`` are in the
`binutils <https://www.gnu.org/software/binutils/>`_ package.
The other programs are usually located in packages with their respective names.
Expand Down Expand Up @@ -359,43 +357,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 <https://github.com/sagemath/sage/#readme>`_
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
<https://github.com/transcode-open/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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -428,6 +389,133 @@ Also see the `related Github issue <https://github.com/pypa/packaging-problems/i

When the installation is complete, you may be interested in :ref:`sec-launching-wsl-post-installation`.

.. _section_cygwinprereqs:

Cygwin prerequisite installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Previous versions of Sage targeted the Windows platform using `Cygwin
<https://cygwin.com/>`_.

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
<query?status=closed&status=needs_info&status=needs_review&status=needs_work&status=new&status=positive_review&component=porting%3A+Cygwin&milestone=sage-9.8&milestone=sage-9.7&milestone=sage-9.6&milestone=sage-9.5&milestone=sage-9.4&milestone=sage-9.3&milestone=sage-9.2&milestone=sage-9.1&col=id&col=summary&col=milestone&col=status&col=priority&col=changetime&col=author&col=reviewer&desc=1&order=changetime>`
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 <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. 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 <https://github.com/transcode-open/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
^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -787,46 +875,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:

Expand Down

0 comments on commit c39312c

Please sign in to comment.