Plan for guile-debugging integration

Plan for guile-debugging integration

[Neil Jerram]

Hi all,

I'm going to start merging my guile-debugging work into Guile CVS
(HEAD), and thought it would be good to say briefly how I plan to do
this.

guile-debugging consists of some Scheme code, some Elisp code, and
some documentation, so the points of interest are really just where
the code should go, how the documentation will be integrated, and what
testing there will be.

1. Scheme code

The Scheme files fall into two categories: those which implement new
debugging infrastructure (steps.scm, trace.scm, traps.scm, trc.scm,
breakpoints.scm) and those which implement the Emacs interface
(gds-client.scm, gds-server.scm).

By default I'd add these under (ice-9) - but perhaps we should
consider something else?  Please let me know if you have ideas.

2. Elisp code

These files (gds-scheme.el, gds-server.el, gds.el) implement the Emacs
interface.  Guile CVS already has an "emacs" subdir, so I think it
makes sense to add these here.

3. Documentation

This is the interesting part, in my view.  As part of this merge I
want to achieve three things.

- Complete the documentation of existing debugging infrastructure:
  stacks, frames, (ice-9 debug) and the command line debugger.

- Merge the documentation of new debugging stuff and of the Emacs
  interface from guile-debugging into the Guile reference manual.

- Remedy the lack of basic documentation on using the Guile REPL.

I should also say that I plan to document my Guile/Emacs interface as
the "official" or recommended one.  If you are concerned about that,
please let me know asap.

Proposed doc changes in more detail...

* New "Using Guile interactively" node, under "Programming in Scheme"

Basic intro to using the REPL; readline; value history; what happens
when an error is hit; backtrace; command line debugger (== existing
"Interactive Debugger" node + "Additional Commands" from
guile-debugging.texi).

* New "Using Guile in Emacs" node, under "Programming in Scheme"

Everything about the "GDS" Guile/Emacs interface.  (From the "GDS"
node in guile-debugging.texi.)

* Changes to the "Debugging Features" node

"Debug Last Error" and "Interactive Debugger" move to underneath the
"Using Guile interactively" node.

"Intro to Breakpoints" stays here but is renamed "Breakpoints".
"Tracing" stays here.  The details under these nodes are updated to
reflect latest guile-debugging.

New "Examples" node, == the "Example" node in guile-debugging.texi.

* Changes to the "Debugging Infrastructure", under "API Reference".

Incorporate reference material from the "Traps", "Breakpoints" and
Appendix A nodes in guile-debugging.texi.

Complete existing documentation on stacks and frames.

Make sure overall structure is coherent.

4. Testing

I can add debugging infrastructure tests using our usual test
framework, so I'll do that.

I don't know how to regressibly test any of the Emacs interface stuff
though.  Please let me know if you have ideas.

5. Anything else?

If there are other facets of the integration that I have overlooked,
please feel free to point them out.

Regards,
     Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: Plan for guile-debugging integration

[Ludovic Courtès]

Hi Neil,

Neil Jerram <neil@ossau.uklinux.net> writes:

> 1. Scheme code
>
> The Scheme files fall into two categories: those which implement new
> debugging infrastructure (steps.scm, trace.scm, traps.scm, trc.scm,
> breakpoints.scm) and those which implement the Emacs interface
> (gds-client.scm, gds-server.scm).
>
> By default I'd add these under (ice-9) - but perhaps we should
> consider something else?  Please let me know if you have ideas.

Maybe you could create a sub-directory, like `(ice-9 debugging)'?

> 3. Documentation
>
> This is the interesting part, in my view.  As part of this merge I
> want to achieve three things.
>
> - Complete the documentation of existing debugging infrastructure:
>   stacks, frames, (ice-9 debug) and the command line debugger.
>
> - Merge the documentation of new debugging stuff and of the Emacs
>   interface from guile-debugging into the Guile reference manual.
>
> - Remedy the lack of basic documentation on using the Guile REPL.

This is a really good idea!

> I should also say that I plan to document my Guile/Emacs interface as
> the "official" or recommended one.  If you are concerned about that,
> please let me know asap.

No, but we need to make sure it does not lack too many features compared
with the implementation-neutral `scheme-mode' that comes with Emacs, and
perhaps also compared to `quack.el'.  Regarding this, I have two (minor)
requests that I'll post in a separate mail.

Overall, your plan looks very good to me.  And I'm sure users will all
find it very pleasant.  :-)

Thanks for working on this!

Ludovic.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: Plan for guile-debugging integration

[Neil Jerram]

ludovic.courtes@laas.fr (Ludovic Courtès) writes:

> Neil Jerram <neil@ossau.uklinux.net> writes:
>
>> 1. Scheme code
>>
>> By default I'd add these under (ice-9) - but perhaps we should
>> consider something else?  Please let me know if you have ideas.
>
> Maybe you could create a sub-directory, like `(ice-9 debugging)'?

Yes, good idea; I'll do that.

>> I should also say that I plan to document my Guile/Emacs interface as
>> the "official" or recommended one.  If you are concerned about that,
>> please let me know asap.
>
> No, but we need to make sure it does not lack too many features compared
> with the implementation-neutral `scheme-mode' that comes with Emacs, and

No problem there, because my mode builds on top of scheme-mode.

> perhaps also compared to `quack.el'.

I haven't looked at quack for a while, but I will do so again soon.

> Overall, your plan looks very good to me.  And I'm sure users will all
> find it very pleasant.  :-)

I hope so.  Thanks for your comments!

Regards,
     Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: Plan for guile-debugging integration

[Ludovic Courtès]

Hi,

Neil Jerram <neil@ossau.uklinux.net> writes:

> ludovic.courtes@laas.fr (Ludovic Courtès) writes:
>
>> Neil Jerram <neil@ossau.uklinux.net> writes:
>>
>>> 1. Scheme code
>>>
>>> By default I'd add these under (ice-9) - but perhaps we should
>>> consider something else?  Please let me know if you have ideas.
>>
>> Maybe you could create a sub-directory, like `(ice-9 debugging)'?
>
> Yes, good idea; I'll do that.

Actually, it might be time for a more rational name space...  ;-)

Keisuke (at least) had come up with the idea of a `system' module
directory.  So you would put the debugging material under `(system
debugging)' rather than adding yet another thing under `ice-9'.

What do you think?  Are people fond of `ice-9'?  :-)

Thanks,
Ludovic.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: Plan for guile-debugging integration

[Neil Jerram]

ludovic.courtes@laas.fr (Ludovic Courtès) writes:

> Actually, it might be time for a more rational name space...  ;-)
>
> Keisuke (at least) had come up with the idea of a `system' module
> directory.  So you would put the debugging material under `(system
> debugging)' rather than adding yet another thing under `ice-9'.
>
> What do you think?  Are people fond of `ice-9'?  :-)

[...silence...]

It seems people aren't that bothered. :-)

I think we should we wait until there's a big enough mass of Guile
stuff out there that the current organization becomes a problem.  When
we have a real problem to solve, we'll probably have a better idea
about the solution.

Regards,
     Neil



_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: Plan for guile-debugging integration

[Kevin Ryde]

Neil Jerram <neil@ossau.uklinux.net> writes:
>
> It seems people aren't that bothered. :-)

Oh, well, the obscurity of ice-9 has the advantage that nobody will
use it by accident and get name clashes :-).

ludovic.courtes@laas.fr (Ludovic Courtès) writes:
>
> Are people fond of `ice-9'?  :-)

It's pretty silly, but I'm sure it's one of those things where
changing would gain nothing.  Perhaps when time machines and cheap and
easy to use it could be retrospectively made less bizarre :-).


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: Plan for guile-debugging integration

[Ludovic Courtès]

Hi,

Neil Jerram <neil@ossau.uklinux.net> writes:

> I think we should we wait until there's a big enough mass of Guile
> stuff out there that the current organization becomes a problem.  When
> we have a real problem to solve, we'll probably have a better idea
> about the solution.

Well, there is no real problem to solve, just the fact that `ice-9' is a
silly name.  :-)

Plus the fact that it contains a zillion of unrelated modules, all at
the same level.  I'd be more in favor of a three-level hierarchy which
would typically be something like `(PACKAGE SUB-SYSTEM FEATURE)'.  So,
for Guile, everything would be under `system':

  system
    debugging
    reader     <-- I use that for `guile-reader'
    il
    vm

Removing `ice-9' may not be feasible (for compatibility reasons).
However, using a cleaner name space for *new* modules (like yours) looks
appealing.

Unless people really aren't bothered at all.  ;-)

Thanks,
Ludovic.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel