Document that SAGE_DEBUG is three-state

[vbraun]

Currently, SAGE_DEBUG is documented as

If it is unset (the default) or set to “yes”, then debugging is turned on.

This is fine if you just add gcc -g, but the utility of having a real Python debug build shows that there should be more to debugging than just adding symbols. However, this has a real performance impact and should not be the default. So I propose that SAGE_DEBUG have three possible values:

• SAGE_DEBUG=no means no debugging symbols (no gcc -g), which mostly saves disk space.
• SAGE_DEBUG=yes builds debug versions if possible (in particular, Python and Singular). These will be notable slower.
• Anything else (including unset SAGE_DEBUG) is the same as the old default, compile with debugging symbols but no debugging options that influence performance.

CC: @nexttime

Component: documentation

Author: Volker Braun

Reviewer: Jeroen Demeyer

Merged: sage-5.6.beta2

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

[vbraun]

Author: Volker Braun

[vbraun]

comment:2

I've posted to sage-devel since this might be of interest to a larger audience: https://groups.google.com/d/topic/sage-devel/Lmo6mmDylj4/discussion

[nbruin]

comment:3

Ah, 'anything else' sounds like a great 3rd case.

Is there any standard on whether "yes/no", "!Yes/No", "true/false", "on/off" etc. is preferred? I always end up having to google the environment variables and then hope and check later that the value I used had the desired effect.

[vbraun]

comment:4

I think all documented environment variables use yes/no for a binary setting. In Python we always use !True/False since those are Python bools.

[nexttime]

comment:5

Component: Documentation?

[vbraun]

comment:6

You want to file it under something else? It is just a doc patch.

[simon-king-jena]

comment:7

Is this ticket about fixing documentation of SAGE_DEBUG, or is it about proper behaviour/use of SAGE_DEBUG? If it is the latter, then I suggest one should also raise the singular-spkg from #13731 to a new patch level and replace/add the environment variable SINGULAR_XALLOC by SAGE_DEBUG.

[vbraun]

comment:8

I intended it just as a discussion and fix for the docstring. But if you want to add a new singular spkg then thats fine with me, too.

[nexttime]

comment:9

Replying to @vbraun:

You want to file it under something else? It is just a doc patch.

Well, the documentation is certainly wrong (or not up-to-date), as the default is actually rather no. (We decided to add debug symbols by default since that doesn't have a performance impact -- except for larger files and hence probably slower start-up/loading, but one can strip these symbols later. SAGE_DEBUG=yes in contrast does -- depending on the spkg -- e.g. disable optimization, add extra code [probably with some runtime overhead] , so at least may have a major performance impact.)

W.r.t. the component: I just meant changing the meaning certainly extends to more than a documentation change (cf. the ticket's title; otherwise I'd call it "Clarify SAGE_DEBUG", say).

Actually, what you propose is IMHO what we already have (or should^TM have)... ;-)

So just correcting or clarifying the documentation may indeed be sufficient. :-) (But I'd then change the ticket's title, as mentioned.)

[nexttime]

comment:11

Ok...

s/notable/notably/

s/to pinpoint/to e.g. pinpoint/

[nexttime]

comment:12

Not sure whether the Sage Developer's Guide (on spkgs) is up-to-date right now.

[nexttime]

comment:13

We should probably also mention that (or how) debug symbols can be stripped afterwards...

[vbraun]

comment:14

Fixed. I grepped the docs and this is the only place that mentions SAGE_DEBUG. No idea how to strip besides doing it yourself, and that definitely shouldn't be covered in the install guide.

[nexttime]

comment:15

Replying to @vbraun:

Fixed. I grepped the docs and this is the only place that mentions SAGE_DEBUG.

Oh. I thought it was at least in some spkg-installtemplate.

No idea how to strip besides doing it yourself, and that definitely shouldn't be covered in the install guide.

There used to be sage [-]-strip, but that got removed at some point because it did more than just stripping debug symbols (which also failed on some -- presumably MacOS X -- systems) IIRC.

(We now -- or still -- have the "micro-release" make target though, see also $SAGE_LOCAL/bin/sage-micro_release...)

[jdemeyer]

comment:16

The patch needs a proper commit message.

[vbraun]

comment:17

Fixed

[jdemeyer]

Reviewer: Jeroen Demeyer

[jdemeyer]

comment:18

Fine for me. Actually changing packages to be consistent with this documentation should be done in separate tickets.

[nexttime]

comment:19

Replying to @jdemeyer:

changing packages to be consistent with this documentation should be done in separate tickets.

Of course.

[jdemeyer]

Merged: sage-5.6.beta2

[jdemeyer]

Attachment: trac_13865_SAGE_DEBUG_documentation.patch.gz

Updated patch

[jdemeyer]

comment:21

Rebased to #13032.