Installation guide: Improve section on prerequisites/recommendations

[mkoeppe]

We move the details regarding required compilers, binutils, etc. from the installation manual to the respective SPKG.rst files (except for the tk stuff, for which we don't have a package - #31206). Most users who install from source do not need this level of detail.

This change will give the simple installation instructions (with prepared package installation commands) more prominence.

Preview of the updated section

Depends on #34266
Depends on #33816

CC: @tobiasdiez @egourgoulhon @Kerl13 @dimpase @jhpalmieri

Component: documentation

Author: Matthias Koeppe, John Palmieri

Branch/Commit: 5b9b5a0

Reviewer: John Palmieri, Matthias Koeppe

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

[mkoeppe]

Dependencies: #34266

[mkoeppe]

Branch: u/mkoeppe/installation_guide__improve_section_on_prerequisites_recommendations

[mkoeppe]

Commit: bd54240

[mkoeppe]

Last 10 new commits:

5713937	sage -package list --has-file, --no-file: Handle disjunctions
8c7e0c4	Merge #33062
4e8ec60	.github/workflows/docker.yml: Remove debian-stretch, fedora-{26,27,27}
a9f4b15	tox.ini (gcc_8), build/pkgs/_gcc8: New
120ab05	tox.ini (envlist): Replace docker-ubuntu-trusty-minimal with docker-ubuntu-trusty-toolchain-gcc_9-minimal
9b38bad	build/pkgs/_gcc{9,10,11}/distros/opensuse.txt: New
ccce5b1	.github/workflows/docker.yml: Use gcc_8 with ubuntu-bionic, linuxmint-19.x
27a0882	.github/workflows/docker.yml: Use gcc_11 with opensuse-15.{3,4}
f2cadff	Merge #34266
bd54240	src/doc/en/installation/source.rst: Move gcc/gfortran details into SPKG.rst

[mkoeppe]

Author: Matthias Koeppe

[sagetrac-git]

Changed commit from bd54240 to eeaa4aa

[sagetrac-git]

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

eeaa4aa

src/doc/en/installation/source.rst: Move _prereq details into SPKG.rst

[sagetrac-git]

Changed commit from eeaa4aa to 2d8eb5c

[sagetrac-git]

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

2d8eb5c

src/doc/en/installation/source.rst: Move python3 venv details to SPKG.rst

[sagetrac-git]

Changed commit from 2d8eb5c to 311d55b

[sagetrac-git]

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

311d55b

README.md: Point to build/pkgs/{gcc,gfortran,_prereq}/SPKG.rst instead of install manual

[sagetrac-git]

Changed commit from 311d55b to 714db9c

[sagetrac-git]

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

714db9c

src/doc/en/installation/source.rst: Get rid of defunct link https://www.sagemath.org/packages/optional/

[sagetrac-git]

Changed commit from 714db9c to 435f275

[sagetrac-git]

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

6b5a210	src/doc/en/installation/source.rst: Move instructions how to check for prereqs to _prereq/SPKG.rst
435f275	src/doc/en/installation/source.rst: Add links to the SPKG.rst files, rewrite prereq/recommended instructions

[sagetrac-git]

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

0bf7d8a

src/doc/en/installation/source.rst: Update timestamp

[sagetrac-git]

Changed commit from 435f275 to 0bf7d8a

[jhpalmieri]

comment:16

It looks pretty good to me, although I haven't gone through every detail, in part because there are various dependencies which either need review or maybe don't exist yet? (Does anything need to be done for #32074, which is a dependency for #34266?)

[mkoeppe]

comment:17

I only made #32074 a dependency so that #34266 does not get accidentally merged into Sage 9.7. I'll remove the dependency as soon as 9.7 is out.

[mkoeppe]

comment:18

And the dependency on #34266 is just because that ticket is updating the documentation regarding GCC requirements, so it's merged here to avoid merge conflicts later.

[jhpalmieri]

Changed branch from u/mkoeppe/installation_guide__improve_section_on_prerequisites_recommendations to u/jhpalmieri/installation_guide__improve_section_on_prerequisites_recommendations

[jhpalmieri]

comment:20

Here are a few small edits. Should something about Apple's M1/M2 be added to the gcc SPKG.rst file, or is it good enough to have the information just for gfortran?

---

New commits:

d2c22bf

trac 34528: minor edits

[jhpalmieri]

comment:24

My understanding is that you only need to use the bootstrap command if you are testing new packages. If you are working solely within the Sage library, you shouldn't need it.

[mkoeppe]

comment:25

That's right.

[mkoeppe]

comment:26

But in the manual we actually do say that it is a hard requirement:

+Sage developers will also need the `system packages required for
+bootstrapping <../reference/spkg/_bootstrap>`_; they cannot be
+installed by Sage.

This sentence appears in the section explaining the prerequisites.

[mkoeppe]

comment:27

We used to explain in a more fine-grained way when _bootstrap is needed, but it turned out to be not clear enough, which led to frustration. We simplified the explanation in #33851.

[mkoeppe]

comment:28

Replying to Tobias Diez:

So these tools are a hard requirement and not a recommendation, right?

I think you missed the paragraph leading to the section with these long generated command-lines:

+The following sections provide the commands to install a large
+recommended set of packages on various systems, which will minimize
+the time it takes to build Sage. This is intended as a convenient
+shortcut, but of course you can choose to take a more fine-grained
+approach.

[jhpalmieri]

comment:29

Assuming that the tests go well in #33816, we can remove the paragraph about m1/m2 from the gfortran SPKG.rst, but I think we should still include something for gcc since that seems to be broken (and also not needed).

[mkoeppe]

comment:30

For gcc, I think we can copy in https://trac.sagemath.org/wiki/ReleaseTours/sage-9.7#SupportforsystemGCColderthan6.3dropped:

[jhpalmieri]

comment:31

I was thinking of this change:

diff --git a/build/pkgs/gcc/SPKG.rst b/build/pkgs/gcc/SPKG.rst
index 87a056f83d..cc6c8153a8 100644
--- a/build/pkgs/gcc/SPKG.rst
+++ b/build/pkgs/gcc/SPKG.rst
@@ -42,6 +42,11 @@ you need a recent version of Xcode.
 (Installing the
 ``gfortran`` SPKG becomes a no-op in this case.)
 
+Building Sage from source on Apple Silicon (M1/M2) requires the use of
+Apple's Command Line Tools, and those tools include a suitable
+compiler. Sage's ``gcc`` SPKG is not suitable for M1/M2; building it
+will likely fail.
+
 License
 -------
 
diff --git a/build/pkgs/gfortran/SPKG.rst b/build/pkgs/gfortran/SPKG.rst
index b6ba9b9bb4..9559b98456 100644
--- a/build/pkgs/gfortran/SPKG.rst
+++ b/build/pkgs/gfortran/SPKG.rst
@@ -20,13 +20,6 @@ need to run::
 
     $ ./configure CC=clang CXX=clang++ FC=flang
 
-Building Sage from source on Apple Silicon (M1/M2) requires the use of
-​the `Homebrew package manager <https://brew.sh>`_ (recommended) or
-conda-forge, which package versions of GCC 12.x (including
-``gfortran``) with the necessary changes for this platform.  These
-changes are not in a released upstream version of GCC, and hence
-the ``gfortran`` SPKG is not suitable for the M1/M2.
-
 License
 -------
 

[mkoeppe]

comment:32

Please go ahead and push it to the ticket. We can make #33816 a dependency.

[mkoeppe]

Changed dependencies from #34266 to #34266, #33816

[sagetrac-git]

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

92f1eda

trac 34528: remove m1/m2 warning from gfortran/SPKG.rst, and add one

[sagetrac-git]

Changed commit from d2c22bf to 92f1eda

[tobiasdiez]

comment:34

Replying to John Palmieri:

My understanding is that you only need to use the bootstrap command if you are testing new packages. If you are working solely within the Sage library, you shouldn't need it.

Thanks for the clarification. I was always under the impression that bootstrap was needed after a git clone, good to know that this is no longer the case.

[mkoeppe]

Changed branch from u/jhpalmieri/installation_guide__improve_section_on_prerequisites_recommendations to u/mkoeppe/installation_guide__improve_section_on_prerequisites_recommendations

[mkoeppe]

comment:36

Replying to Matthias Köppe:

For gcc, I think we can copy in https://trac.sagemath.org/wiki/ReleaseTours/sage-9.7#SupportforsystemGCColderthan6.3dropped

Done, plus some details from #32074

---

New commits:

ec7d50c

build/pkgs/gcc/SPKG.rst: Add info from https://github.com/sagemath/sage/issues/32074

[mkoeppe]

Changed commit from 92f1eda to ec7d50c

[mkoeppe]

Changed author from Matthias Koeppe to Matthias Koeppe, John Palmieri

[jhpalmieri]

Changed branch from u/mkoeppe/installation_guide__improve_section_on_prerequisites_recommendations to u/jhpalmieri/installation_guide__improve_section_on_prerequisites_recommendations

[jhpalmieri]

comment:39

The links don't work for me without this change.

---

New commits:

d364033	Merge branch 'develop' into t/34528/installation_guide__improve_section_on_prerequisites_recommendations
5b9b5a0	trac 34528: fix a few links

[jhpalmieri]

Changed commit from ec7d50c to 5b9b5a0

[jhpalmieri]

Reviewer: John Palmieri, ...

[jhpalmieri]

comment:40

I'm happy with Matthias' contributions; positive review from me.

[mkoeppe]

Changed reviewer from John Palmieri, ... to John Palmieri, Matthias Koeppe

[mkoeppe]

comment:41

Thanks!

[vbraun]

Changed branch from u/jhpalmieri/installation_guide__improve_section_on_prerequisites_recommendations to 5b9b5a0