Opened 3 years ago

Closed 3 years ago

#25995 closed enhancement (fixed)

update installation guide

Reported by: vdelecroix Owned by:
Priority: major Milestone: sage-8.4
Component: documentation Keywords:
Cc: slelievre 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 saraedum)

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 3 years ago by vdelecroix

  • Authors set to Vincent Delecroix
  • Description modified (diff)

comment:2 Changed 3 years ago by vdelecroix

  • Branch set to u/vdelecroix/25995
  • Commit set to 2c85617ca7c104c410eeeb07ca51efeaf934a019

New commits:

2c85617update installation guide

comment:3 Changed 3 years ago by vdelecroix

  • Description modified (diff)

comment:4 Changed 3 years ago by vdelecroix

  • Description modified (diff)

comment:5 follow-up: Changed 3 years ago by 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

comment:6 in reply to: ↑ 5 Changed 3 years ago by vdelecroix

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 3 years ago by slelievre

Searching the Sage repo on GitHub for "readme":

reveals three files

The last one might the one kcrisman has in mind.

comment:8 Changed 3 years ago by slelievre

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

I found these two too:

comment:9 Changed 3 years ago by vdelecroix

  • Description modified (diff)

comment:10 Changed 3 years ago by vdelecroix

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 3 years ago by kcrisman

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 3 years ago by git

  • Commit changed from 2c85617ca7c104c410eeeb07ca51efeaf934a019 to 698a5158f4ec1fab96df92456a3f5ecb2b76c702

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 3 years ago by vdelecroix

  • Status changed from new to needs_review

Ready for a relecture!

comment:14 Changed 3 years ago by vdelecroix

  • Description modified (diff)

comment:15 Changed 3 years ago by vdelecroix

  • Description modified (diff)

comment:16 follow-up: Changed 3 years ago by 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?

comment:17 Changed 3 years ago by saraedum

  • Branch changed from u/vdelecroix/25995 to u/saraedum/25995

comment:18 Changed 3 years ago by saraedum

  • Commit changed from 698a5158f4ec1fab96df92456a3f5ecb2b76c702 to d419cc81efe3b8f33e72cced987db572982a94d7
  • Description modified (diff)
  • Reviewers set to 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 ; follow-ups: Changed 3 years ago by 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 $^ $@

comment:20 in reply to: ↑ 19 Changed 3 years ago by vdelecroix

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 3 years ago by vdelecroix

  • Branch changed from u/saraedum/25995 to u/vdelecroix/25995
  • Commit changed from d419cc81efe3b8f33e72cced987db572982a94d7 to 5a2da4c15ce9c6dd746b18b2c5e2c4f088d0670c

New commits:

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

comment:22 Changed 3 years ago by git

  • Commit changed from 5a2da4c15ce9c6dd746b18b2c5e2c4f088d0670c to 6b202a4c17650309ac59b218427a6ab56ead315e

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

6b202a4fix ReST syntax

comment:23 Changed 3 years ago by git

  • Commit changed from 6b202a4c17650309ac59b218427a6ab56ead315e to aa0246481ea722eceee29b22bcda7eb4b0afab56

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

aa02464move linux instructions in a separate file

comment:24 follow-up: Changed 3 years ago by vdelecroix

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 ; follow-up: Changed 3 years ago by 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?

comment:26 in reply to: ↑ 24 Changed 3 years ago by saraedum

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 3 years ago by vdelecroix

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 follow-up: Changed 3 years ago by saraedum

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

comment:29 in reply to: ↑ 28 Changed 3 years ago by vdelecroix

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 follow-up: Changed 3 years ago by 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.

comment:31 in reply to: ↑ 30 Changed 3 years ago by vdelecroix

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 3 years ago by jhpalmieri

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 3 years ago by saraedum

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

comment:34 Changed 3 years ago by kcrisman

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

comment:35 Changed 3 years ago by saraedum

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 3 years ago by vdelecroix

Could we set to positive review then?

comment:37 Changed 3 years ago by saraedum

  • Status changed from needs_review to positive_review

comment:38 Changed 3 years ago by vdelecroix

Great news! Thank you :-)

comment:39 Changed 3 years ago by vbraun

  • Branch changed from u/vdelecroix/25995 to aa0246481ea722eceee29b22bcda7eb4b0afab56
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.