Improve wording and formatting of configure's recommendation message

[slel]

Context

Recent work on Sage's build system enables to use many
system packages as possible when building Sage.
See meta-ticket #27330 for an overview.

Part of that effort is to have configure end with
recommendations of extra system packages to install.

Making this recommendation system very precise would not
be sustainable. As a compromise, it recommends installing
packages whenever

• satisfactory versions of these packages
  are not found to be already installed
• some version of that OS has versions of these packages
  that would avoid having to build them

Problem

With the wording of the recommendation hint up to
Sage 9.2.beta12, users can be puzzled when it recommends
installing a package that is already installed.

Solution

Improve the recommendation message and along the way
make it better stand out.

Before this ticket:

configure: hint: installing the following system packages
is recommended and may avoid building some of the above SPKGs
from source:
configure:   $ sudo apt-get update
$ sudo apt-get install libcdd-dev libcdd-tools libnauty-dev

After this ticket:

configure:

    hint: installing the following system packages, if not
    already present, is recommended and may avoid building
    them from source (some may have to be built anyway):

    $ sudo apt-get update
    $ sudo apt-get install libcdd-dev libcdd-tools libnauty-dev

References

See the 2020-09 discussion on sage-release,
in particular these posts:

• https://groups.google.com/d/msg/sage-release/hobZzw74Rv0/xtBCPrGrAgAJ
• https://groups.google.com/d/msg/sage-release/hobZzw74Rv0/1IYw5RG_BQAJ
• https://groups.google.com/d/msg/sage-release/hobZzw74Rv0/MWUqj400BgAJ

See also

See also #30863 whose aim is the same (e.g., do not suggest to sudo apt install sympow if the reason was that the sympow already installed on the system was failing some tests).

Depends on #30606

CC: @egourgoulhon @orlitzky @mkoeppe @slel @tobiasdiez @seblabbe

Component: build: configure

Author: Samuel Lelièvre, Matthias Koeppe

Branch/Commit: 72f0081

Reviewer: Matthias Koeppe, Sébastien Labbé

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

[slel]

Description changed:

--- 
+++ 
@@ -44,14 +44,14 @@
 
     hint: installing the following system packages, if not
     already present, is recommended and may avoid building
-    some of them from source (though some of them may
-    have to be built anyway):
+    them from source (some may have to be built anyway):
 
     $ sudo apt-get update
     $ sudo apt-get install libcdd-dev libcdd-tools libnauty-dev
-
 ```
 
+
+**References**
 
 See the 2020-09 discussion on sage-release,
 in particular these posts:

[slel]

Branch: public/30624-improve-configure-recommendation-message

[slel]

Commit: 208d572

[slel]

comment:2

Here is a branch.

Illustration on macOS.

Before:

$ source .homebrew-build-env && ./bootstrap -q && ./configure
...
config.status: creating directory local/lib/pkgconfig
config.status: creating directory local/share
config.status: creating directory local/var/lib/sage/installed
configure: notice: the following SPKGs did not find equivalent system packages: cbc coxeter3 gp2c libnauty libsemigroups pari_elldata pari_galpol pari_nftables pari_seadata perl_cpan_polymake_prereq perl_term_readline_gnu python3 tox
checking for the package system in use... -n (ignoring conda because no environment is active)
homebrew
configure: hint: installing the following system packages is recommended and may avoid building some of the above SPKGs from source:
configure:   $ brew install python3
# To automatically take care of homebrew messages regarding
# keg-only packages for the current shell session:
  $ source /opt/s/sage9/.homebrew-build-env
# Add this to your shell profile if you want it to persist between shell sessions.
configure: After installation, re-run configure using:
configure:   $ ./config.status --recheck && ./config.status

After:

$ source .homebrew-build-env && ./bootstrap -q && ./configure
...
config.status: creating directory local/lib/pkgconfig
config.status: creating directory local/share
config.status: creating directory local/var/lib/sage/installed
configure:

    notice: the following SPKGs did not find equivalent system packages:

        cbc coxeter3 gp2c libnauty libsemigroups pari_elldata pari_galpol pari_nftables pari_seadata perl_cpan_polymake_prereq perl_term_readline_gnu python3 tox

checking for the package system in use... -n (ignoring conda because no environment is active)
homebrew
configure:

    hint: installing the following system packages, if not
    already present, is recommended and may avoid having to
    build them (though some may have to be built anyway):

      $ brew install python3

    Homebrew can issue suggestions regarding keg-only packages.
    The following command is to automatically apply these suggestions.
    Run it once to apply the suggestions for the current session.
    Add it to your shell profile to apply them for all future sessions.

      $ source /opt/s/sage92b6/.homebrew-build-env

    After installation, re-run configure using:

      $ ./config.status --recheck && ./config.status

Illustration on Debian.

Before:

$ ./bootstrap -q && ./configure
...
config.status: creating directory local/lib/pkgconfig
config.status: creating directory local/share
config.status: creating directory local/var/lib/sage/installed
configure: notice: the following SPKGs did not find equivalent system packages: coxeter3 gp2c libnauty libsemigroups pari_elldata pari_galpol pari_nftables pari_seadata tox
checking for the package system in use... debian
configure: hint: installing the following system packages is recommended and may avoid building some of the above SPKGs
from source:
configure:   $ sudo apt-get update
  $ sudo apt-get install pari-gp2c libnauty-dev
configure: After installation, re-run configure using:
configure:   $ ./config.status --recheck && ./config.status

After:

$ ./bootstrap -q && ./configure
...
config.status: creating directory local/lib/pkgconfig
config.status: creating directory local/share
config.status: creating directory local/var/lib/sage/installed
configure:

    notice: the following SPKGs did not find equivalent system packages:

        coxeter3 gp2c libnauty libsemigroups pari_elldata pari_galpol pari_nftables pari_seadata tox

checking for the package system in use... debian
configure:

    hint: installing the following system packages, if not
    already present, is recommended and may avoid having to
    build them (though some may have to be built anyway):

      $ sudo apt-get update
  $ sudo apt-get install pari-gp2c libnauty-dev

    After installation, re-run configure using:

      $ ./config.status --recheck && ./config.status

---

New commits:

208d572

t-30624 improve configure recommendation message

[slel]

comment:3

Polishing commits welcome (here or in a follow-up ticket).

I'll update the "before/after" in the ticket description
once the branch gets positive review.

[mkoeppe]

comment:4

This change is not good. # is the shell comment character.
The idea here is that (if PROMPT is not used) that you get a valid shell script as the output.

-        $IF_VERBOSE echo "# To automatically take care of homebrew messages regarding "
-        $IF_VERBOSE echo "# keg-only packages for the current shell session:"
+        $IF_VERBOSE echo ""
+        $IF_VERBOSE echo "    Homebrew can issue suggestions regarding keg-only packages."
+        $IF_VERBOSE echo "    The following command is to automatically apply these suggestions."

[mkoeppe]

comment:5

If you put this ticket on top of #30606, you could add customization of the comment prefix in the same way that #30606 adds customization of the prompt...

[sagetrac-git]

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

14e9395	SagePackageSystem: Rename to sage_spkg (underscore) to make it an allowed optional tag
5c0da17	src/sage/doctest/control.py: Add available package systems to optional tags
c01aa8f	src/sage/features/__init__.py: Mark tests that check for 'sage -i' optional - sage_spkg
5ef159c	30606: fixing docstring """ -> r"""
d344adf	Merge tag '9.2.beta13' into t/30606/sage_features_feature_resolution__if_sage_root_is_available__recommend_system_packages
a854438	DocTestController.__init__: Only add package systems when 'optional' is used
68a8e2a	src/sage/features/__init__.py: Fix patchbot / relint warnings
81ef969	Merge branch 't/30606/sage_features_feature_resolution__if_sage_root_is_available__recommend_system_packages' into t/30624/public/30624-improve-configure-recommendation-message
d8321b6	build/bin/sage-print-system-package-command: Add option --verbose=COMMENT-PREFIX
90ffc55	t-30624 improve configure recommendation message

[sagetrac-git]

Changed commit from 208d572 to 90ffc55

[mkoeppe]

comment:7

Rebased as I suggested. You can now modify the invocations of sage-print-system-package-command to use something like this for the desired effect:

build/bin/sage-print-system-package-command homebrew --verbose='     ' --prompt='               $ ' setup-build-env foo