update installation guide

Question

update installation guide

videlec opened this issue 7 years ago · 49 comments

videlec commented 7 years ago

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

mention the brew install (see https://groups.google.com/d/msg/sage-devel/jdLfIKQ1M18/PVQqJUUqAgAJ)?
mention the distribution specifics:
- Archlinux

CC: @slel

Component: documentation

Author: Vincent Delecroix

Branch/Commit: aa02464

Reviewer: Julian Rüth

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

Answer 1 · 2018-08-03T23:29:13.000Z

Author: Vincent Delecroix

Answer 2 · 2018-08-03T23:29:13.000Z

Description changed:

--- 
+++ 
@@ -1,5 +1,7 @@
 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)
 - clearer explanations for OS X (what to choose between `tar.gz`, `app.dmg` or `dmg`)
+- quick command line start (ie `sage` and `sage -n`)

Answer 3 · 2018-08-03T23:29:25.000Z

Branch: u/vdelecroix/25995

Answer 4 · 2018-08-03T23:29:25.000Z

Commit: 2c85617

Answer 5 · 2018-08-03T23:29:25.000Z

New commits:

`2c85617`	`update installation guide`

Answer 6 · 2018-08-04T05:57:31.000Z

Description changed:

--- 
+++ 
@@ -2,6 +2,6 @@
 
 - remove outdated information
 - mention the cygwin windows binaries
-- mention package manager installation (Debian >= 9, Ubuntu >= 18.04, archlinux)
-- clearer explanations for OS X (what to choose between `tar.gz`, `app.dmg` or `dmg`)
+- mention package manager installation: Debian >= 9, Ubuntu >= 18.04, archlinux, Fedora, ... (see https://wiki.sagemath.org/Distribution)
+- clearer explanations for OS X (what to choose between `tar.gz`, `app.dmg` or `dmg`) and mention the possible brew install (see https://groups.google.com/d/msg/sage-devel/jdLfIKQ1M18/PVQqJUUqAgAJ)
 - quick command line start (ie `sage` and `sage -n`)

Answer 7 · 2018-08-04T06:01:12.000Z

Description changed:

--- 
+++ 
@@ -2,6 +2,7 @@
 
 - remove outdated information
 - mention the cygwin windows binaries
-- mention package manager installation: Debian >= 9, Ubuntu >= 18.04, archlinux, Fedora, ... (see https://wiki.sagemath.org/Distribution)
+- mention package manager installation: Debian >= 9, Ubuntu >= 18.04, archlinux, Fedora >= 27, ... (see https://wiki.sagemath.org/Distribution)
 - clearer explanations for OS X (what to choose between `tar.gz`, `app.dmg` or `dmg`) and mention the possible brew install (see https://groups.google.com/d/msg/sage-devel/jdLfIKQ1M18/PVQqJUUqAgAJ)
-- quick command line start (ie `sage` and `sage -n`)
+- mention the various docker images around
+- quick command line howto (ie `sage` and `sage -n`) and pointers to do the first steps in Sage

Answer 8 · 2018-08-04T16:27:04.000Z

comment:5

+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

Answer 9 · 2018-08-07T00:54:18.000Z

comment:6

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.

Answer 10 · 2018-08-07T09:33:00.000Z

comment:7

Searching the Sage repo on GitHub for "readme":

search: https://github.com/sagemath/sage/search?q=readme

reveals three files

The last one might the one kcrisman has in mind.

Answer 11 · 2018-08-07T09:50:01.000Z

comment:8

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

search: https://github.com/sagemath/sage/search?q=mac

I found these two too:

Answer 12 · 2018-08-07T19:39:29.000Z

Description changed:

--- 
+++ 
@@ -3,6 +3,7 @@
 - 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)
-- clearer explanations for OS X (what to choose between `tar.gz`, `app.dmg` or `dmg`) and mention the possible brew install (see https://groups.google.com/d/msg/sage-devel/jdLfIKQ1M18/PVQqJUUqAgAJ)
+- 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).
+- should we mention the brew install (see https://groups.google.com/d/msg/sage-devel/jdLfIKQ1M18/PVQqJUUqAgAJ)?
 - mention the various docker images around
 - quick command line howto (ie `sage` and `sage -n`) and pointers to do the first steps in Sage

Answer 13 · 2018-08-07T19:44:30.000Z

comment:10

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").

Answer 14 · 2018-08-07T20:57:44.000Z

comment:11

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.

Answer 15 · 2018-08-12T15:12:43.000Z

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

`606d863`	`25995: update installation guide`
`698a515`	`25995: move sage-README-osx.txt`

Answer 16 · 2018-08-12T15:12:43.000Z

Changed commit from 2c85617 to 698a515

Answer 17 · 2018-08-12T15:12:58.000Z

comment:13

Ready for a relecture!

Answer 18 · 2018-08-12T15:13:41.000Z

Description changed:

--- 
+++ 
@@ -4,6 +4,8 @@
 - 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).
-- should we mention the brew install (see https://groups.google.com/d/msg/sage-devel/jdLfIKQ1M18/PVQqJUUqAgAJ)?
+- quick command line howto (ie `sage` and `sage -n`) and pointers to do the first steps in Sage
+
+Some possibilities
+- mention the brew install (see https://groups.google.com/d/msg/sage-devel/jdLfIKQ1M18/PVQqJUUqAgAJ)?
 - mention the various docker images around
-- quick command line howto (ie `sage` and `sage -n`) and pointers to do the first steps in Sage

Answer 19 · 2018-08-12T18:27:32.000Z

Description changed:

--- 
+++ 
@@ -9,3 +9,5 @@
 Some possibilities
 - mention the brew install (see https://groups.google.com/d/msg/sage-devel/jdLfIKQ1M18/PVQqJUUqAgAJ)?
 - mention the various docker images around
+- mention the distribution specifics:
+  - [Archlinux](https://wiki.archlinux.org/index.php/SageMath)

Answer 20 · 2018-08-22T02:48:09.000Z

comment:16

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?

Answer 21 · 2018-08-22T03:33:00.000Z

Changed branch from u/vdelecroix/25995 to u/saraedum/25995

Answer 22 · 2018-08-22T03:37:05.000Z

Changed commit from 698a515 to d419cc8

Answer 23 · 2018-08-22T03:37:05.000Z

comment:18

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:

`e958968`	`Merge remote-tracking branch 'trac/u/vdelecroix/25995' into HEAD`
`b7df26f`	`Fix spelling and grammar`
`55d3489`	`Mac OS X is now called macOS`
`91a9c7e`	`cygwin is called Cygwin afaik`
`4fef756`	`archlinux is called Arch Linux`
`0a26102`	`sagemath is called SageMath`
`e6841c9`	`Jupyter's notebook is called the Jupyter Notebook afaik`
`34f6a7f`	`OS X is now called macOS`
`12997ae`	`SageMath is also available on NixOS and conda`
`d419cc8`	`Add conda installation guide`

Answer 24 · 2018-08-22T03:37:05.000Z

Description changed:

--- 
+++ 
@@ -5,9 +5,11 @@
 - 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
 - mention the brew install (see https://groups.google.com/d/msg/sage-devel/jdLfIKQ1M18/PVQqJUUqAgAJ)?
-- mention the various docker images around
 - mention the distribution specifics:
   - [Archlinux](https://wiki.archlinux.org/index.php/SageMath)

Answer 25 · 2018-08-22T03:37:05.000Z

Reviewer: Julian Rüth

Answer 26 · 2018-08-22T13:28:26.000Z

comment:19

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

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

Answer 27 · 2018-08-22T13:29:52.000Z

comment:20

Replying to @videlec:

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...

Answer 28 · 2018-08-22T13:35:57.000Z

Changed commit from d419cc8 to 5a2da4c

Answer 29 · 2018-08-22T13:35:57.000Z

Changed branch from u/saraedum/25995 to u/vdelecroix/25995

Answer 30 · 2018-08-22T13:35:57.000Z

New commits:

`5a2da4c`	`fix sentence in the old sage-README-osx.txt`

Answer 31 · 2018-08-22T13:40:34.000Z

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

`6b202a4`	`fix ReST syntax`

Answer 32 · 2018-08-22T13:40:34.000Z

Changed commit from 5a2da4c to 6b202a4

Answer 33 · 2018-08-22T13:56:07.000Z

Changed commit from 6b202a4 to aa02464

Answer 34 · 2018-08-22T13:56:07.000Z

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

`aa02464`	`move linux instructions in a separate file`

Answer 35 · 2018-08-22T13:57:50.000Z

comment:24

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).

Answer 36 · 2018-08-23T16:47:14.000Z

comment:25

Replying to @videlec:

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
diff --git a/src/mac-app/Makefile b/src/mac-app/Makefile
index 3f2dc22..4b8a5b3 100644
--- a/src/mac-app/Makefile
+++ b/src/mac-app/Makefile
@@ -99,7 +99,7 @@ $(TARGET)/Applications:
 	ln -s /Applications/ $(TARGET)/Applications
 
 # Add the readme file
-$(TARGET)/README.txt: $(SAGE_ROOT)/src/bin/sage-README-osx.txt
+$(TARGET)/README.txt: sage-README-osx.txt
 	cp $^ $@

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

Answer 37 · 2018-08-23T16:50:27.000Z

comment:26

Replying to @videlec:

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.

Answer 38 · 2018-08-23T16:53:57.000Z

comment:27

Replying to @saraedum:

Replying to @videlec:
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
diff --git a/src/mac-app/Makefile b/src/mac-app/Makefile
index 3f2dc22..4b8a5b3 100644
--- a/src/mac-app/Makefile
+++ b/src/mac-app/Makefile
@@ -99,7 +99,7 @@ $(TARGET)/Applications:
 	ln -s /Applications/ $(TARGET)/Applications
 
 # Add the readme file
-$(TARGET)/README.txt: $(SAGE_ROOT)/src/bin/sage-README-osx.txt
+$(TARGET)/README.txt: sage-README-osx.txt
 	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.

Answer 39 · 2018-08-23T16:56:13.000Z

comment:28

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

Answer 40 · 2018-08-23T16:57:54.000Z

comment:29

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.

Answer 41 · 2018-08-23T18:36:05.000Z

comment:30

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.

Answer 42 · 2018-08-23T18:39:24.000Z

comment:31

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.

Answer 43 · 2018-08-23T18:42:40.000Z

comment:32

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.)

Answer 44 · 2018-08-23T22:59:36.000Z

comment:33

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

Answer 45 · 2018-08-24T00:12:16.000Z

comment:34

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

Answer 46 · 2018-08-24T00:26:57.000Z

comment:35

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.)

Answer 47 · 2018-09-01T15:07:57.000Z

comment:36

Could we set to positive review then?

Answer 48 · 2018-10-03T12:54:14.000Z

comment:38

Great news! Thank you :-)

Answer 49 · 2018-10-04T21:54:16.000Z

Changed branch from u/vdelecroix/25995 to aa02464