Opened 4 years ago

Closed 4 years ago

#25995 closed enhancement (fixed)

update installation guide

Reported by: Vincent Delecroix Owned by:
Priority: major Milestone: sage-8.4
Component: documentation Keywords:
Cc: Samuel Lelièvre Merged in:
Authors: Vincent Delecroix Reviewers: Julian Rüth
Report Upstream: N/A Work issues:
Branch: aa02464 (Commits, GitHub, GitLab) Commit: aa0246481ea722eceee29b22bcda7eb4b0afab56
Dependencies: Stopgaps:

Status badges

Description (last modified by Julian Rüth)

Update the instructions in the installation guide

  • remove outdated information
  • mention the cygwin windows binaries
  • mention package manager installation: Debian >= 9, Ubuntu >= 18.04, archlinux, Fedora >= 27, ... (see https://wiki.sagemath.org/Distribution)
  • get rid of src/bin/sage-README-osx.txt and instead move its content in the installation guide in order to have clear OS X explanations (ie what to choose between tar.gz, app.dmg or dmg and do we deal with them).
  • quick command line howto (ie sage and sage -n) and pointers to do the first steps in Sage
  • mention Docker
  • mention conda
  • mention NixOS

Some possibilities

Change History (39)

comment:1 Changed 4 years ago by Vincent Delecroix

Authors: Vincent Delecroix
Description: modified (diff)

comment:2 Changed 4 years ago by Vincent Delecroix

Branch: u/vdelecroix/25995
Commit: 2c85617ca7c104c410eeeb07ca51efeaf934a019

New commits:

2c85617update installation guide

comment:3 Changed 4 years ago by Vincent Delecroix

Description: modified (diff)

comment:4 Changed 4 years ago by Vincent Delecroix

Description: modified (diff)

comment:5 Changed 4 years ago by Karl-Dieter Crisman

+OS X dmg
+--------
+
+A possible alternive on OS X is to use ``app.dmg`` or ``dmg`` files. Such
+installation will automtically create shortcuts on your desktops. Simply
+follow the section "Download Guide" above and download the ``dmg`` file
+corresponding to your system.
+
+TO BE FINISHED

And earlier you also have something about which one is best. There is a separate readmeosx file somewhere which will answer many of your questions here; the short version is that app.dmg is better for those wanting a GUI, dmg is better for those only wanting command line access. tar.gz is definitely not preferred for mac

comment:6 in reply to:  5 Changed 4 years ago by Vincent Delecroix

Replying to kcrisman:

+OS X dmg
+--------
+
+A possible alternive on OS X is to use ``app.dmg`` or ``dmg`` files. Such
+installation will automtically create shortcuts on your desktops. Simply
+follow the section "Download Guide" above and download the ``dmg`` file
+corresponding to your system.
+
+TO BE FINISHED

And earlier you also have something about which one is best. There is a separate readmeosx file somewhere which will answer many of your questions here; the short version is that app.dmg is better for those wanting a GUI, dmg is better for those only wanting command line access. tar.gz is definitely not preferred for mac

The only README.txt I found is on the sagemath website when going to "Download" and then "Mac OSX". It does not tell anything about the three different format of installation.

comment:7 Changed 4 years ago by Samuel Lelièvre

Searching the Sage repo on GitHub for "readme":

reveals three files

The last one might the one kcrisman has in mind.

comment:8 Changed 4 years ago by Samuel Lelièvre

Oops, I missed some. Searching again for "mac"

I found these two too:

comment:9 Changed 4 years ago by Vincent Delecroix

Description: modified (diff)

comment:10 Changed 4 years ago by Vincent Delecroix

Thanks Samuel! It is definitely src/bin/sage-README-osx.txt and this file will be removed by this ticket (or more precisely, replace its content with "go read the installation manual").

comment:11 Changed 4 years ago by Karl-Dieter Crisman

Whoah Nelly! But note that that file actually shows up in the dmg created (if you open it it appears in a nice Mac-specific Finder way). So be careful about this, and be sure to have someone test with a Mac on a app dmg, possibly also regular dmg.

comment:12 Changed 4 years ago by git

Commit: 2c85617ca7c104c410eeeb07ca51efeaf934a019698a5158f4ec1fab96df92456a3f5ecb2b76c702

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

606d86325995: update installation guide
698a51525995: move sage-README-osx.txt

comment:13 Changed 4 years ago by Vincent Delecroix

Status: newneeds_review

Ready for a relecture!

comment:14 Changed 4 years ago by Vincent Delecroix

Description: modified (diff)

comment:15 Changed 4 years ago by Vincent Delecroix

Description: modified (diff)

comment:16 Changed 4 years ago by Julian Rüth

This content of this file has been moved to the installation guide. That's not correct, is it? It has been moved to the mac-app README hasn't it? Should we just delete this file?

comment:17 Changed 4 years ago by Julian Rüth

Branch: u/vdelecroix/25995u/saraedum/25995

comment:18 Changed 4 years ago by Julian Rüth

Commit: 698a5158f4ec1fab96df92456a3f5ecb2b76c702d419cc81efe3b8f33e72cced987db572982a94d7
Description: modified (diff)
Reviewers: Julian Rüth

I added a few more things that I know about. I made quite a few minor changes, mostly related to the correct spelling/casing of trademarks and fixed some sentences that I stumbled upon.

Something that I am still not sure about: Should we consistently call this thing Sage or SageMath? Currently it's still a bit of a mix though I replaced most instances of Sage with SageMath…something that we might want to revert.

Anyway, I don't think we should strive for perfection here. This had already been quite an improvement :)


New commits:

e958968Merge remote-tracking branch 'trac/u/vdelecroix/25995' into HEAD
b7df26fFix spelling and grammar
55d3489Mac OS X is now called macOS
91a9c7ecygwin is called Cygwin afaik
4fef756archlinux is called Arch Linux
0a26102sagemath is called SageMath
e6841c9Jupyter's notebook is called the Jupyter Notebook afaik
34f6a7fOS X is now called macOS
12997aeSageMath is also available on NixOS and conda
d419cc8Add conda installation guide

comment:19 in reply to:  16 ; Changed 4 years ago by Vincent Delecroix

Replying to saraedum:

This content of this file has been moved to the installation guide. That's not correct, is it? It has been moved to the mac-app README hasn't it? Should we just delete this file?

No! This file is distributed together with the macOS applications. You can see that in 25995

  • src/mac-app/Makefile

    diff --git a/src/mac-app/Makefile b/src/mac-app/Makefile
    index 3f2dc22..4b8a5b3 100644
    a b $(TARGET)/Applications: 
    9999        ln -s /Applications/ $(TARGET)/Applications
    100100
    101101# Add the readme file
    102 $(TARGET)/README.txt: $(SAGE_ROOT)/src/bin/sage-README-osx.txt
     102$(TARGET)/README.txt: sage-README-osx.txt
    103103        cp $^ $@

comment:20 in reply to:  19 Changed 4 years ago by Vincent Delecroix

Replying to vdelecroix:

Replying to saraedum:

This content of this file has been moved to the installation guide. That's not correct, is it? It has been moved to the mac-app README hasn't it? Should we just delete this file?

Let just write that this file has moved then...

comment:21 Changed 4 years ago by Vincent Delecroix

Branch: u/saraedum/25995u/vdelecroix/25995
Commit: d419cc81efe3b8f33e72cced987db572982a94d75a2da4c15ce9c6dd746b18b2c5e2c4f088d0670c

New commits:

5a2da4cfix sentence in the old sage-README-osx.txt

comment:22 Changed 4 years ago by git

Commit: 5a2da4c15ce9c6dd746b18b2c5e2c4f088d0670c6b202a4c17650309ac59b218427a6ab56ead315e

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

6b202a4fix ReST syntax

comment:23 Changed 4 years ago by git

Commit: 6b202a4c17650309ac59b218427a6ab56ead315eaa0246481ea722eceee29b22bcda7eb4b0afab56

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

aa02464move linux instructions in a separate file

comment:24 Changed 4 years ago by Vincent Delecroix

I moved the Linux instructions and updated the fact that you absolutely need the documentation (otherwise ? is just broken).

I think this is in good enough shape for now. What do you think?

In the future we might want to update instructions for optional packages (Arch Linux provide some with pacman and pip install does work).

comment:25 in reply to:  19 ; Changed 4 years ago by Julian Rüth

Replying to vdelecroix:

Replying to saraedum:

This content of this file has been moved to the installation guide. That's not correct, is it? It has been moved to the mac-app README hasn't it? Should we just delete this file?

No! This file is distributed together with the macOS applications. You can see that in 25995

  • src/mac-app/Makefile

    diff --git a/src/mac-app/Makefile b/src/mac-app/Makefile
    index 3f2dc22..4b8a5b3 100644
    a b $(TARGET)/Applications: 
    9999        ln -s /Applications/ $(TARGET)/Applications
    100100
    101101# Add the readme file
    102 $(TARGET)/README.txt: $(SAGE_ROOT)/src/bin/sage-README-osx.txt
     102$(TARGET)/README.txt: sage-README-osx.txt
    103103        cp $^ $@

I don't understand. The file in src/bin/ is not distributed with the macOS app anymore. So why do we need it?

comment:26 in reply to:  24 Changed 4 years ago by Julian Rüth

Replying to vdelecroix:

I moved the Linux instructions and updated the fact that you absolutely need the documentation (otherwise ? is just broken).

Sure. It's fine to tell people to install documentation. Note that the ? bug is fixed in #25786 which needs review :).

I think this is in good enough shape for now. What do you think?

Yes, it looks good to me. Have you had a look at the generated HTML?

In the future we might want to update instructions for optional packages (Arch Linux provide some with pacman and pip install does work).

Sounds good. But let's put this into another ticket.

comment:27 in reply to:  25 Changed 4 years ago by Vincent Delecroix

Replying to saraedum:

Replying to vdelecroix:

Replying to saraedum:

This content of this file has been moved to the installation guide. That's not correct, is it? It has been moved to the mac-app README hasn't it? Should we just delete this file?

No! This file is distributed together with the macOS applications. You can see that in 25995

  • src/mac-app/Makefile

    diff --git a/src/mac-app/Makefile b/src/mac-app/Makefile
    index 3f2dc22..4b8a5b3 100644
    a b $(TARGET)/Applications: 
    9999        ln -s /Applications/ $(TARGET)/Applications
    100100
    101101# Add the readme file
    102 $(TARGET)/README.txt: $(SAGE_ROOT)/src/bin/sage-README-osx.txt
     102$(TARGET)/README.txt: sage-README-osx.txt
    103103        cp $^ $@

I don't understand. The file in src/bin/ is not distributed with the macOS app anymore. So why do we need it?

I tought it was (my modification in the Makefile is just changing the path). I don't have a mac and I will not try to find one to test it. Let me post something on sage-devel.

comment:28 Changed 4 years ago by Julian Rüth

I can test it on a mac if you want me to.

comment:29 in reply to:  28 Changed 4 years ago by Vincent Delecroix

Replying to saraedum:

I can test it on a mac if you want me to.

If you have time to do so, please do! See also this post on sage-devel.

comment:30 Changed 4 years ago by John Palmieri

I'm not quite sure what the question is here, but here are my comments: first, running make from src/mac-app works for me with this branch. Second, I think you could just delete the (now very small) file src/bin/sage-README-osx.txt, since you've moved the important parts to src/mac-app/, and that's the natural place for that information.

comment:31 in reply to:  30 Changed 4 years ago by Vincent Delecroix

Replying to jhpalmieri:

I'm not quite sure what the question is here, but here are my comments: first, running make from src/mac-app works for me with this branch. Second, I think you could just delete the (now very small) file src/bin/sage-README-osx.txt, since you've moved the important parts to src/mac-app/, and that's the natural place for that information.

Thanks for checking! Does the sage-README-osx.txt is inside the mac-app produced?

I will delete the one in src/bin following your advice.

comment:32 Changed 4 years ago by John Palmieri

The correct README.txt file is produced in the top-level of the .dmg file. (And the tiny sage-README-osx.txt file in src/bin is present in the app, also.)

comment:33 Changed 4 years ago by Julian Rüth

Hm…I don't see what could possibly break™, but let me try to build it anyway.

comment:34 Changed 4 years ago by Karl-Dieter Crisman

Thanks esp. to jhpalmieri for checking out that this all is still working!

comment:35 Changed 4 years ago by Julian Rüth

Sorry, I can't test this on my macOS as I cannot upgrade to a version that is supports xcode (and I don't want to hack around to install an old xcode.)

comment:36 Changed 4 years ago by Vincent Delecroix

Could we set to positive review then?

comment:37 Changed 4 years ago by Julian Rüth

Status: needs_reviewpositive_review

comment:38 Changed 4 years ago by Vincent Delecroix

Great news! Thank you :-)

comment:39 Changed 4 years ago by Volker Braun

Branch: u/vdelecroix/25995aa0246481ea722eceee29b22bcda7eb4b0afab56
Resolution: fixed
Status: positive_reviewclosed
Note: See TracTickets for help on using tickets.