Document sage-dist-helpers

[jhpalmieri]

Document the bash functions sdh_make and friends in the Sage developer's guide. (Currently they are only documented in their source file, build/bin/sage-dist-helpers.)

Component: documentation

Author: John Palmieri

Branch/Commit: 33abf8f

Reviewer: Dima Pasechnik

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

[jhpalmieri]

Branch: u/jhpalmieri/sdh-docs

[jhpalmieri]

Commit: bbd044a

[jhpalmieri]

New commits:

bbd044a

trac 28721: document the functions in sage-dist-helpers.

[dimpase]

comment:3

The pattern sdh_XYZ || sdh_die ... one sees in few places is not necessary, and sdh_XYZ alone suffices, isn't it?

By looking at the code of e.g. sdh_configure
one sees that sdh_die is actually called in sdh_configure, and so chaining them
as above is pointless (the part after || won't be called).

This should be mentioned in the docs.

[embray]

comment:4

By the way, there was already a ticket for this task at #24023.

Something I wanted to do for that was to have a way to automatically include the in-line docs in sage-dist-helpers into the Sphinx docs, but I would have needed to write a plugin, and didn't get to do it.

[embray]

comment:5

In any case, this is definitely good enough for now, thank you for taking care of it.

[jhpalmieri]

comment:6

Replying to @embray:

By the way, there was already a ticket for this task at #24023.

Oops, sorry.

Something I wanted to do for that was to have a way to automatically include the in-line docs in sage-dist-helpers into the Sphinx docs, but I would have needed to write a plugin, and didn't get to do it.

Maybe we can leave #24023 open for that.

[embray]

comment:7

Replying to @jhpalmieri:

Replying to @embray:

By the way, there was already a ticket for this task at #24023.

Oops, sorry.

No problem. Personally I sometimes even prefer opening separate tickets for specific solutions to a problem from the ticket for the problem itself.

Something I wanted to do for that was to have a way to automatically include the in-line docs in sage-dist-helpers into the Sphinx docs, but I would have needed to write a plugin, and didn't get to do it.

Maybe we can leave #24023 open for that.

That makes sense.

[sagetrac-git]

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

33abf8f

trac 28721: do not combine sdh_BLAH with sdh_die

[sagetrac-git]

Changed commit from bbd044a to 33abf8f

[jhpalmieri]

comment:9

Replying to @dimpase:

The pattern sdh_XYZ || sdh_die ... one sees in few places is not necessary, and sdh_XYZ alone suffices, isn't it?

By looking at the code of e.g. sdh_configure
one sees that sdh_die is actually called in sdh_configure, and so chaining them
as above is pointless (the part after || won't be called).

This should be mentioned in the docs.

I added a note about this.

[dimpase]

Reviewer: Dima Pasechnik

[dimpase]

comment:10

Thanks. Looks good to me; the still missing part is package de-installation, and the related JSON files, but it can be on another ticket.

[dimpase]

comment:11

specifically about JSON files, de-installation is handled by build/sage_bootstrap/uninstall.py, and there are good docs there, but I don't know where these JSON files are written.

I have a vague recollection I knew it once, but it's not clear to me now, without digging through the whole command chain and makefiles... :-(

[jhpalmieri]

comment:12

Seems to be written by build/bin/sage-spkg, starting at line 1000:

PKG_NAME_INSTALLED="$SAGE_SPKG_INST/$PKG_NAME"
cat > "$PKG_NAME_INSTALLED" << __EOF__
{
    "package_name": "$PKG_BASE",
    "package_version": "$PKG_VER",
    "install_date": "$(date)",
    "system_uname": "$(uname -a)",
    "sage_version": "$(cat "${SAGE_ROOT}/VERSION.txt")",
    "test_result": "$TEST_SUITE_RESULT",
    "files": [
        $FILE_LIST
    ]
}
__EOF__

The file manifest is constructed at line 899-900:

    # Generate installed file manifest
    FILE_LIST="$(cd "$PREFIX" && find . -type f -o -type l | sed 's|^\./||' | sort)"

[vbraun]

Changed branch from u/jhpalmieri/sdh-docs to 33abf8f