Update README.md and Installation Manual for 9.1, integrate instructions for Windows (WSL and Cygwin) in manuals

[embray]

Followup to #22450 to improve any hard-coded (e.g. in the official Sage docs, as opposed to on a the wiki) documentation concerning installing Sage for Windows, in particular to emphasize the native binary.

Cygwin source material:

• https://trac.sagemath.org/wiki/Cygwin64Port

WSL source material:

• Make it possible to build on WSL #28549 Make it possible to build on WSL

See also:

• Add script package _recommended and generate "recommended system packages" info #29557: Add script package _recommended and generate "recommended system packages" info

CC: @orlitzky @tscrim @darijgr @soehms @tobiasdiez @dimpase @jhpalmieri @vbraun

Component: documentation

Author: Matthias Koeppe

Branch: d56b24e

Reviewer: Michael Orlitzky

Issue created by migration from https://trac.sagemath.org/ticket/25206

[embray]

Dependencies: #22450

[embray]

comment:5

Retargeting some of my tickets.

[embray]

comment:6

Removing most of the rest of my open tickets out of the 8.7 milestone, which should be closed.

[mkoeppe]

comment:7

README needs some updates regarding Windows

[mkoeppe]

Changed dependencies from #22450 to none

[mkoeppe]

Branch: u/mkoeppe/update_readme__installation_manual_and_developer_s_guide_on_windows__wsl_and_cygwin_

[mkoeppe]

Commit: 2ba0f40

[mkoeppe]

comment:16

First edit.

---

New commits:

2ba0f40

src/doc/en/installation/source.rst: Mention WSL, remove mention of outdated platforms

[mkoeppe]

Author: ...

[sagetrac-git]

Changed commit from 082e238 to 7683168

[mkoeppe]

comment:50

OK I'll just stop here.

[mkoeppe]

comment:51

Needs review

[sagetrac-git]

Changed commit from 7683168 to 75fb70d

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

75fb70d

src/doc/en/developer/packaging.rst: Get rid of links to outdated sage wiki pages

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

3f353fb

src/doc/en/installation/source.rst: Add recommended ubuntu packages from wiki

[sagetrac-git]

Changed commit from 75fb70d to 3f353fb

[mkoeppe]

comment:55

(last change)

[orlitzky]

Reviewer: Michael Orlitzky

[orlitzky]

comment:56

LGTM, now quit changing it =P

[mkoeppe]

comment:57

Thanks!

[vbraun]

comment:58

[dochtml] OSError: /var/lib/buildbot/slave/sage_git/build/src/doc/en/installation/troubles.rst:4: WARNING: Duplicate explicit target name: "sage-support mailing list".

[mkoeppe]

comment:59

Sorry, fix coming shortly

[sagetrac-git]

Changed commit from 3f353fb to d56b24e

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

d56b24e

Fix doc markup

[vbraun]

Changed branch from u/mkoeppe/update_readme__installation_manual_and_developer_s_guide_on_windows__wsl_and_cygwin_ to d56b24e

[tobiasdiez]

comment:63

Thanks for updating the help. I just followed the instructions and came up with the following detailed step-by-step procedure to get sage running under Windows using WLS (which is the updated version from #28549). I think it would be worthwhile to add it to the documentation to make it easier for Windows-folks to contribute. However, I'm not sure which files to edit (in fact, I'm not even able to find the readme edited in this PR).

Prerequisites

• Install WSL 2 (Ubuntu 20.04 LTS)
• Activate OpenSSH as described in https://stackoverflow.com/a/40720527/873661

Git (run everything in the Windows command line / Powershell console)

• Clone repository (preserving symlinks)

  git clone -c core.symlinks=true git://github.com/sagemath/sage.git
  cd sage
  

* Correct line endings (necessary if global core.autocrlf is set to true; this should be obsolete with #29733):

git config --local core.autocrlf false
git rm --cached -r .
git reset --hard

* Setup remote trac (nessary if you want to contribute)
  
  Follow the instructions to set-up the ssh key https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent and then follow http://doc.sagemath.org/html/en/developer/trac.html#trac-authentication-through-ssh and http://doc.sagemath.org/html/en/developer/manual_git.html#chapter-manual-git

git remote add trac git://trac.sagemath.org/sage.git -t master
git remote set-url --push trac [email protected]:sage.git

* Switch to development branch

git checkout develop

## Build sage (run everything from Ubuntu bash)
* Switch to Ubuntu: ` wsl `
* Install prerequisites as described in [corresponding script for Linux](http://doc.sagemath.org/html/en/installation/source.html#linux-recommended-installation). (Without the Python 3.7 dependencies, which apt-get couldn't find.)

sudo apt-get update

sudo apt-get install as in the link

* Make sure you are still in the sage folder
* Set how many cores you want to use for building (important, otherwise it will take ages)

export MAKE="make -j4"

* Build

make

* Test sage

./sage
2+2

* Register git credentials (necessary if you want to commit from WSL)

git config --global user.name ""
git config --global user.email

## Develop (using VS Code)
* Start Visual Studio Code.
* Install "Remote-WSL" extension.
* Press F1, enter Remote-WSL: New Window, and hit enter.
* Use the File menu to open your folder.
* For running & debuging, follow https://code.visualstudio.com/remote-tutorials/wsl/edit-and-debug
* Use `./sage -br` to trigger a rebuild of sage.

[tobiasdiez]

Changed commit from d56b24e to none

[embray]

comment:64

I was about to note in the wiki page that by default when you install the ccache package on Cygwin it does not configure the system to use ccache. Of course it's possible to install the Sage ccache package but this is unnecessary. So the documentation should be updated to explain how to configure ccache on Cygwin. Should I open a new ticket for that?

[mkoeppe]

comment:65

Replying to @embray:

I was about to note in the wiki page that by default when you install the ccache package on Cygwin it does not configure the system to use ccache. Of course it's possible to install the Sage ccache package but this is unnecessary. So the documentation should be updated to explain how to configure ccache on Cygwin. Should I open a new ticket for that?

Yes, that would be great

[slel]

comment:66

Note: a follow-up ticket was opened by @embray:

• Cygwin: add ccache configuration instructions to installation manual #29751: Cygwin: add ccache configuration instructions to installation manual