build/make/Makefile.in: Rename make targets SPKG-clean to SPKG-uninstall

[mkoeppe]

Cleaning means to remove build artifacts from the directory @builddir@ (= SAGE_ROOT).
But these targets uninstall packages from @prefix@=$SAGE_LOCAL.

Hence we rename SPKG-clean targets to SPKG-uninstall (but keep SPKG-clean as an alias.) This also unifies the targets between normal and script packages (the latter used -uninstall already).

We also add implicit rules that allow users to uninstall packages that no longer exist in the source tree. This is preparation for #34203. To test this, switch to the branch of #33530 and build one of the packages added, for example make fastjsonschema. Switch back to current develop and try to remove it (does not work). Switch to the branch here and run make fastjsonschema-uninstall (works).

Related:

• "make distclean" should not run "./configure" #29310 - introduced make doc-uninstall
• "make doc-clean" should remove inventory, doctrees #33705 make doc-clean should remove inventory, doctrees
• Install script and pip packages via sage-spkg #29386 Install script packages via sage-spkg
• Remove ./configure --enable-SPKG options for pip packages (for which this is not implemented) #29626 ./configure --enable-SPKG does not work for optional pip packages
• pip-installable packages sagemath-doc-src, sagemath-doc-inventory, sagemath-doc-html, sagemath-doc-pdf #29868 pip-installable packages sage-doc-html, sage-doc-pdf

CC: @dimpase @embray @jhpalmieri @seblabbe @orlitzky @haraldschilly

Component: build

Author: John Palmieri, Matthias Koeppe

Branch/Commit: 72695aa

Reviewer: Matthias Koeppe, John Palmieri

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

[mkoeppe]

Description changed:

--- 
+++ 
@@ -2,3 +2,4 @@
 But these targets *uninstall* packages from `@prefix@=$SAGE_LOCAL`.
 
 
+Likewise "doc-output-clean" should be renamed to "doc-uninstall".

[mkoeppe]

Description changed:

--- 
+++ 
@@ -3,3 +3,8 @@
 
 
 Likewise "doc-output-clean" should be renamed to "doc-uninstall".
+
+
+Also useful would be phony targets of the form `SPKG-deps` that would install all prerequisite targets of `SPKG`, but not `SPKG` itself.
+
+Also related: #29626 ./configure --enable-SPKG does not work for optional pip packages

[mkoeppe]

Dependencies: #29793

[jhpalmieri]

comment:6

There is no reason for any deprecation here, is there? I have a branch that I'm testing out now to do the change "clean -> uninstall", but not the new phony targets SPKG-deps.

[jhpalmieri]

Branch: u/jhpalmieri/clean2uninstall

[jhpalmieri]

comment:8

Here is a branch to test out. I wasn't sure about the instruction when docbuilding fails:

    Note: incremental documentation builds sometimes cause spurious
    error messages. To be certain that these are real errors, run
    "make doc-clean" first and try again.

There could be artifacts that make doc-uninstall won't clean up, so I think I want to keep this as make doc-clean. I don't know if it should also suggest running ./bootstrap, but that's a separate issue.

---

New commits:

5203e50

trac 29097: change "make SPKG-clean" to "make SPKG-uninstall".

[jhpalmieri]

Commit: 5203e50

[orlitzky]

comment:9

There could be artifacts that make doc-uninstall won't clean up, so I think I want to keep this as make doc-clean

Right now doc-clean does both doc-src-clean doc-output-clean. I suggest,

0. Rename doc-output-clean to doc-uninstall (already done).
1. Drop doc-clean
2. Rename doc-src-clean to doc-clean
3. Change the suggestion to run both doc-clean and doc-uninstall

That way the targets wind up with the right names, and the suggestion doesn't effectively change.

NB: in this hunk the doc-src-clean was dropped (I don't know which is correct):

-doc-html-no-plot: doc-clean $(DOC_DEPENDENCIES)
+doc-html-no-plot: doc-uninstall $(DOC_DEPENDENCIES)

[jhpalmieri]

comment:10

Replying to @orlitzky:

There could be artifacts that make doc-uninstall won't clean up, so I think I want to keep this as make doc-clean

Right now doc-clean does both doc-src-clean doc-output-clean. I suggest,

0. Rename doc-output-clean to doc-uninstall (already done).
1. Drop doc-clean
2. Rename doc-src-clean to doc-clean
3. Change the suggestion to run both doc-clean and doc-uninstall

That way the targets wind up with the right names, and the suggestion doesn't effectively change.

My only reluctance is that I am very used to typing make doc-clean when working with tickets involving docbuilding. I don't know how many others are in the same habit, but we would all have to change that habit.

NB: in this hunk the doc-src-clean was dropped (I don't know which is correct):

-doc-html-no-plot: doc-clean $(DOC_DEPENDENCIES)
+doc-html-no-plot: doc-uninstall $(DOC_DEPENDENCIES)

This should be okay: the reason to clean the docs when toggling doc-html-no-plot is because inclusion (or not) of plots is cached in the doc output (in local/share/doc/sage/inventory or maybe .../doctrees). So doc-uninstall should be good enough. It works for me, at least.

[mkoeppe]

comment:11

For the doc-... cleaning/uninstalling targets, I would like to understand first whether everything that we put in $SAGE_LOCAL/share/doc/sage/ should really be installed there.

Are doctrees and inventory needed in the installation at all? Do other Python packages install inventory files? Or is this just something that is reused and updated in an incremental docbuild?

[mkoeppe]

Description changed:

--- 
+++ 
@@ -8,3 +8,5 @@
 Also useful would be phony targets of the form `SPKG-deps` that would install all prerequisite targets of `SPKG`, but not `SPKG` itself.
 
 Also related: #29626 ./configure --enable-SPKG does not work for optional pip packages
+
+See also: #29868 pip-installable packages `sage-doc-html`, `sage-doc-pdf`

[jhpalmieri]

comment:13

The inventory files are intended to allow for cross-references among different pieces of the documentation: see https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html and set_intersphinx_mapping in src/sage/docs/conf.py. It allows the tutorial (for example) to refer to the reference manual. For example, the reference :ref:`sage.rings.padics.tutorial` in tour_numtheory.rst in the tutorial points to the reference manual, and I think this uses the inventory files to construct the link when building the documentation.

According to https://www.sphinx-doc.org/en/master/man/sphinx-build.html, the doctrees are used to cache the parsed source files before writing output. Once the output has been written, they aren't needed, so I guess they could be moved somewhere else, and I'm guessing the same for the inventory files, but I think they are all needed when building the docs.

[mkoeppe]

Changed dependencies from #29793 to #29793, #29868

[mkoeppe]

Changed dependencies from #29793, #29868 to #29793, #29868, #29386

[mkoeppe]

Description changed:

--- 
+++ 
@@ -1,5 +1,7 @@
 Cleaning means to remove build artifacts from the directory `@builddir@` (= SAGE_ROOT).
 But these targets *uninstall* packages from `@prefix@=$SAGE_LOCAL`.
+
+(Part of this has been done in #29386.)
 
 
 Likewise "doc-output-clean" should be renamed to "doc-uninstall".