Skip to content
This repository has been archived by the owner on Jan 30, 2023. It is now read-only.

Commit

Permalink
README.md, src/doc/en/installation: Move all Cygwin instructions to o…
Browse files Browse the repository at this point in the history 
…ne section of the installation manual
  • Loading branch information
Matthias Koeppe committed Aug 11, 2022
1 parent 393808c commit fe98ca1
Show file tree
Hide file tree
Showing 2 changed files with 133 additions and 140 deletions.
67 changes: 6 additions & 61 deletions README.md
View file
Original file line number Diff line number Diff line change
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
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.

Installing prerequisites
~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -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 <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 @@ -376,6 +337,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, `known issues with several packages
<https://trac.sagemath.org/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 @@ -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:

Expand Down

0 comments on commit fe98ca1

Please sign in to comment.