Improve wording and formatting of configure's recommendation message

[slelievre]

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

[slelievre]

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

[slelievre]

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]

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]

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

[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

[mkoeppe]

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

[mkoeppe]

Your turn, Samuel...

[slelievre]

Neither of the "notice: ...", "hint: ...", or "After installation, ..." parts start with "# ".

So I tried to also avoid "# " for the text on linking Homebrew's keg-only packages.

Thanks for showing me the correct way to do that.

[mkoeppe]

Samuel, do you plan to work on this?

[egourgoulhon]

FWIW, I've installed Sage 9.3.beta0 from scratch on Ubuntu 20.04; configure ends with the following recommendations:

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 texlive-generic-extra texlive-xetex latexmk pandoc dvipng 
default-jdk ffmpeg libavdevice-dev libcdd-dev libcdd-tools libec-dev eclib-tools 
libgc-dev libgiac-dev xcas pari-gp2c lcalc liblfunction-dev libnauty-dev nauty 
pari-gp2c libpari-dev pari-doc pari-elldata pari-galdata pari-galpol pari-seadata 
sympow

Now, as mentioned in ​https://trac.sagemath.org/ticket/29557#comment:56, texlive-generic-extra does not exist on Ubuntu 20.04 (there is texlive-latex-extra, which is already installed on my system). Moreover the recommended packages texlive-xetex, latexmk, pandoc, dvipng, default-jdk, ffmpeg, libavdevice-dev, libcdd-dev and libcdd-tools are already installed on my system.

[mkoeppe]

Updates of the package list and similar improvements -- please in #30930 or other tickets, not here.

Let's keep this ticket narrowly focused on what is already on the branch.

[mkoeppe]

Samuel, please let me know if I can help with anything else to get this ticket finished.

[slelievre]

What you did is good. Maybe set to needs_review and review as is?

[mkoeppe]

The new options that I introduced for you (comment:7) are not used yet.

[git]

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

​2016d4d	build/bin/sage-print-system-package-command: Add option --verbose=COMMENT-PREFIX
​0e77878	t-30624 improve configure recommendation message
​e617074	m4/sage_spkg_collect.m4: Use new sage-print-system-package-command options to get indentation right
​72f0081	build/bin/sage-print-system-package-command (homebrew): Make wording regarding keg-only packages more specific

[mkoeppe]

Ready for review

[slabbe]

I just tested the branch on Ubuntu 18.04, I obtain:

configure:

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

        _recommended boost coxeter3 gp2c igraph isl libsemigroups pari_elldata pari_galpol pari_nftables pari_seadata
        
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  texlive-generic-extra texlive-xetex latexmk pandoc dvipng default-jdk ffmpeg libavdevice-dev libboost-dev pari-gp2c libigraph-dev libisl-dev

    After installation, re-run configure using:

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

Should _recommended be listed in the first list?

[slabbe]

Should _recommended be listed in the first list?

If the answer to that question is yes, please change the status of this ticket to positive review.

[slabbe]

Should _recommended be listed in the first list?

I just observed that this is the current behavior on 9.3.beta2. So, this is independent of this ticket.

[mkoeppe]

Thank you!

[mkoeppe]

Replying to slabbe:

I just tested the branch on Ubuntu 18.04, I obtain:

configure:

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

        _recommended boost coxeter3 gp2c igraph isl libsemigroups pari_elldata pari_galpol pari_nftables pari_seadata

Should `_recommended` be listed in the first list?

I am making some changes in this direction - suppressing display of packages starting with underscore - in #29124