Opened 3 years ago

Closed 13 months ago

Last modified 11 months ago

#25206 closed task (fixed)

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

Reported by: embray Owned by: embray
Priority: blocker Milestone: sage-9.1
Component: documentation Keywords:
Cc: mjo, tscrim, gh-darijgr, soehms, gh-tobiasdiez, dimpase, jhpalmieri, vbraun Merged in:
Authors: Matthias Koeppe Reviewers: Michael Orlitzky
Report Upstream: N/A Work issues:
Branch: d56b24e (Commits, GitHub, GitLab) Commit:
Dependencies: Stopgaps:

Status badges

Description (last modified by mkoeppe)

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:

WSL source material:

  • #28549 Make it possible to build on WSL

See also:

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

Change History (66)

comment:1 Changed 3 years ago by embray

  • Dependencies set to #22450
  • Owner changed from (none) to embray

comment:2 Changed 3 years ago by embray

  • Milestone changed from sage-8.2 to sage-8.3

comment:3 Changed 3 years ago by embray

  • Milestone changed from sage-8.3 to sage-8.4

comment:4 Changed 3 years ago by embray

  • Milestone changed from sage-8.4 to sage-8.5

comment:5 Changed 2 years ago by embray

  • Milestone changed from sage-8.5 to sage-8.7

Retargeting some of my tickets.

comment:6 Changed 2 years ago by embray

  • Milestone changed from sage-8.7 to sage-pending

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

comment:7 Changed 14 months ago by mkoeppe

  • Milestone changed from sage-pending to sage-9.1

README needs some updates regarding Windows

comment:8 Changed 14 months ago by mkoeppe

  • Cc tscrim added

comment:9 Changed 14 months ago by mkoeppe

  • Cc gh-darijgr added

comment:10 Changed 14 months ago by mkoeppe

  • Cc soehms added

comment:11 Changed 14 months ago by mkoeppe

  • Description modified (diff)

comment:12 Changed 14 months ago by mkoeppe

  • Cc gh-tobiasdiez added
  • Summary changed from Update README and installation documentation on Windows to Update README, installation manual and developer's guide on Windows (WSL and Cygwin)

comment:13 Changed 14 months ago by mkoeppe

  • Dependencies #22450 deleted
  • Description modified (diff)

comment:14 Changed 14 months ago by mkoeppe

  • Priority changed from major to critical

comment:15 Changed 14 months ago by mkoeppe

  • Branch set to u/mkoeppe/update_readme__installation_manual_and_developer_s_guide_on_windows__wsl_and_cygwin_

comment:16 Changed 14 months ago by mkoeppe

  • Commit set to 2ba0f401fef9c504a6122579df65a1e553c48df7

First edit.


New commits:

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

comment:17 Changed 14 months ago by mkoeppe

  • Authors set to ...

comment:18 Changed 14 months ago by git

  • Commit changed from 2ba0f401fef9c504a6122579df65a1e553c48df7 to 9d5d53b79c4b8d4b1bb7e7fb2c2a309a4d3eaa78

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

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

comment:19 Changed 14 months ago by git

  • Commit changed from 9d5d53b79c4b8d4b1bb7e7fb2c2a309a4d3eaa78 to 7993a18d52d60ac4ede9a92975a906cba465d763

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

6ded682README, src/doc/en/installation: Update dates
7993a18README.md: Add [Windows] Preparing the Platform (from sage wiki)

comment:20 Changed 14 months ago by mkoeppe

  • Priority changed from critical to blocker

comment:21 Changed 14 months ago by mkoeppe

  • Cc dimpase jhpalmieri added

comment:22 Changed 14 months ago by mkoeppe

I'm also updating the general installation from source instructions some more.

comment:23 Changed 14 months ago by git

  • Commit changed from 7993a18d52d60ac4ede9a92975a906cba465d763 to 37789aa5f35426830c0c0332c53a5159743f62da

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

4943aaeREADME: Add [macOS] Preparing the Platform
37789aasrc/doc/en/installation/source.rst: Correction - the tarball is compressed

comment:24 Changed 14 months ago by git

  • Commit changed from 37789aa5f35426830c0c0332c53a5159743f62da to 368a25208cf3e91580f911eabcb94eccde56c08c

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

368a252README.md: Expand on unpacking, and on Windows unpacking issues

comment:25 Changed 14 months ago by git

  • Commit changed from 368a25208cf3e91580f911eabcb94eccde56c08c to 0cd2d05b4db8611c8dee346cc16351cccd58b3e9

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

0cd2d05README.md: Move Docker earlier, Contributing later

comment:26 Changed 14 months ago by git

  • Commit changed from 0cd2d05b4db8611c8dee346cc16351cccd58b3e9 to 5bd6f101b6ddeaac75e2f8bc53556e9f3e507d86

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

d584238README.md: Merge the short and the long installation instructions
5bd6f10README.md: Get rid of the load-average discussion

comment:27 Changed 14 months ago by mkoeppe

  • Status changed from new to needs_review

I'm setting this to review already even though I want to make a few more changes tomorrow.

Feedback in particular on the discussion of the Windows issues in README.md would be welcome.

comment:28 Changed 14 months ago by mkoeppe

  • Authors changed from ... to Matthias Koeppe

comment:29 Changed 14 months ago by mkoeppe

TBD:

comment:30 Changed 14 months ago by gh-timokau

For what its worth, the Nix package should also work fine on WSL. I have not tested that though and I'm not able to offer any real support for that since I have no machine to test it on. Not sure if that belongs in this documentation.

comment:31 Changed 14 months ago by git

  • Commit changed from 5bd6f101b6ddeaac75e2f8bc53556e9f3e507d86 to ec2ffda2b1cbb0e29a49885d36a133f53fe54699

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

ec2ffdaREADME.md: Mention bootstrapping

comment:32 Changed 14 months ago by git

  • Commit changed from ec2ffda2b1cbb0e29a49885d36a133f53fe54699 to ca90c545efc70d57e82853b36ff8c4187e72979c

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

ca90c54README.md: Improve discussion on configure options, env vars

comment:33 Changed 14 months ago by git

  • Commit changed from ca90c545efc70d57e82853b36ff8c4187e72979c to 8057d194b373714e464451a4611d75017b6082ab

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

8057d19README.md: Rework discussion of system packages, refer to build/pkgs/*.txt

comment:34 Changed 14 months ago by mkoeppe

Changes to README.md are complete

comment:35 Changed 14 months ago by mkoeppe

  • Summary changed from Update README, installation manual and developer's guide on Windows (WSL and Cygwin) to Update README.md and Installation Manual for 9.1, integrate instructions for Windows (WSL and Cygwin) in manuals

comment:36 Changed 14 months ago by mkoeppe

TBD:

  • Add from README.md to the Installation Manual.

comment:37 Changed 14 months ago by mkoeppe

  • Description modified (diff)

comment:38 Changed 14 months ago by git

  • Commit changed from 8057d194b373714e464451a4611d75017b6082ab to 78f631365a47d219458c0a29e78e0d1ec4ea25dd

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

78f6313README.md: More on the configure messages recommending system packages

comment:39 Changed 14 months ago by dimpase

your Cygwin home directory does not contain spaces

~/vectorspace.txt will spell doom :P

make it the path to your Cygwin home directory does not contain spaces

comment:40 Changed 14 months ago by mkoeppe

nontrivial spaces

comment:41 Changed 14 months ago by git

  • Commit changed from 78f631365a47d219458c0a29e78e0d1ec4ea25dd to 93087c36ce75b09a0a5d704b1e63ae9603a4fc48

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

93087c3README.md: clarify spaces

comment:42 follow-up: Changed 14 months ago by mjo

  • Cc mjo added

Just a few small things:

  1. "lineendings" should be two words.
  2. This is ambiguous: "This will build Sage based on Python 2 rather than based on Python 3, which is the default since sage 9.0."
  3. Pretty please don't use 1. 1. 1. 1. for ordered lists, not everyone reads the README on github.

comment:43 Changed 14 months ago by git

  • Commit changed from 93087c36ce75b09a0a5d704b1e63ae9603a4fc48 to 8c2a41552695a6cb684858167549b6899aae6ae1

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

c799719README.md: Renumber lists
8c2a415small edit

comment:44 in reply to: ↑ 42 Changed 14 months ago by mkoeppe

Thanks!

comment:45 Changed 14 months ago by git

  • Commit changed from 8c2a41552695a6cb684858167549b6899aae6ae1 to 0088e04cf3fbeb0218e3fa36fb2b8beecef7a049

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

0088e04README.md: Merge discussion of compilers into Installation Manual, remove from README.md

comment:46 Changed 14 months ago by git

  • Commit changed from 0088e04cf3fbeb0218e3fa36fb2b8beecef7a049 to 50db31839663dde6c17a0ac0ac24ccdb69030db7

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

50db318src/doc/en/installation/source.rst: Remove outdated Cygwin stuff

comment:47 Changed 14 months ago by mkoeppe

TODO in src/doc/en/installation/source.rst:

section "Using alternative compilers" should be merged into "Fortran and compiler suites".

comment:48 Changed 14 months ago by git

  • Commit changed from 50db31839663dde6c17a0ac0ac24ccdb69030db7 to 082e238f04b56911bf02bd35c402dba4a293645e

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

082e238src/doc/en/installation/troubles.rst: Refer to version-specific installation FAQ instead of outdated wiki faq

comment:49 Changed 14 months ago by git

  • Commit changed from 082e238f04b56911bf02bd35c402dba4a293645e to 76831681b397a1911168b5641f15e2b8935e8ab6

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

7683168Improve troubleshooting instructions

comment:50 Changed 14 months ago by mkoeppe

OK I'll just stop here.

comment:51 Changed 14 months ago by mkoeppe

Needs review

comment:52 Changed 14 months ago by git

  • Commit changed from 76831681b397a1911168b5641f15e2b8935e8ab6 to 75fb70d252bc19ae414a869da9f85aeb50c84b70

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

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

comment:53 Changed 14 months ago by mkoeppe

  • Cc vbraun added

comment:54 Changed 14 months ago by git

  • Commit changed from 75fb70d252bc19ae414a869da9f85aeb50c84b70 to 3f353fb0475580123b40779c44010f0c1ba01d09

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

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

comment:55 Changed 14 months ago by mkoeppe

(last change)

comment:56 Changed 14 months ago by mjo

  • Reviewers set to Michael Orlitzky
  • Status changed from needs_review to positive_review

LGTM, now quit changing it =P

comment:57 Changed 14 months ago by mkoeppe

Thanks!

comment:58 Changed 14 months ago by vbraun

  • Status changed from positive_review to needs_work
[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".

comment:59 Changed 14 months ago by mkoeppe

Sorry, fix coming shortly

comment:60 Changed 13 months ago by git

  • Commit changed from 3f353fb0475580123b40779c44010f0c1ba01d09 to d56b24e0031e02dc6e00859a832f4988cee333cf

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

d56b24eFix doc markup

comment:61 Changed 13 months ago by mkoeppe

  • Status changed from needs_work to positive_review

comment:62 Changed 13 months ago by vbraun

  • Branch changed from u/mkoeppe/update_readme__installation_manual_and_developer_s_guide_on_windows__wsl_and_cygwin_ to d56b24e0031e02dc6e00859a832f4988cee333cf
  • Resolution set to fixed
  • Status changed from positive_review to closed

comment:63 Changed 13 months ago by gh-tobiasdiez

  • Commit d56b24e0031e02dc6e00859a832f4988cee333cf deleted

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

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 git@trac.sagemath.org: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. (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 "<your name>"
    git config --global user.email <your email>
    

Develop (using VS Code)

Last edited 13 months ago by gh-tobiasdiez (previous) (diff)

comment:64 follow-up: Changed 13 months ago by 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?

comment:65 in reply to: ↑ 64 Changed 13 months ago by mkoeppe

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

comment:66 Changed 11 months ago by slelievre

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

  • #29751: Cygwin: add ccache configuration instructions to installation manual
Note: See TracTickets for help on using tickets.