@@ -1,6 +1,28 @@ +# Copyright (C) 2008 Rocky Bernstein rocky@gnu.org +# +# zshdb is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free +# Software Foundation; either version 2, or (at your option) any later +# version. +# +# zshdb is distributed in the hope that it will be useful, but WITHOUT ANY +# WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# +# You should have received a copy of the GNU General Public License along +# with zshdb; see the file COPYING. If not, write to the Free Software +# Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + SUBDIRS = command emacs lib test -pkgdata_DATA = dbg-pre.sh dbg-main.sh dbg-opts.sh +pkgdata_DATA = \ + dbg-pre.sh \ + dbg-main.sh \ + dbg-opts.sh + +# Set up the install target +bin_SCRIPTS = zshdb EXTRA_DIST = $(pkgdata_DATA) Makefile.am @@ -0,0 +1,132 @@ +0. INTRODUCTION +This is a port and cleanup of my bash debugger bashdb +(http://bashdb.sf.net). + +The command syntax generally follows that of the GNU debugger gdb. + +However this debugger depends on a number bug fixes and of debugging +support features that are neither part of the POSIX 1003.1 standard +and are not in current "stable" zsh releases. In particular, the +"functrace" function needs to always report filenames and absolute line +numbers. Also both "functrace" and "funcstack" should include source'd +files in their arrays. + +1. SETUP + +Although debuggers are useful for novice, right now code setup is not +really but novices. Some assembly is required. + +To get the code, install git and run in a zsh shell: + + git-clone git://github.com/rocky/zshdb.git + cd zshdb + ./autogen.sh # Add configure options. See ./configure --help + +If you've got a suitable zsh installed, then + make && make test + +To simplify demonstration/testing there is a little program testing.sh +in the same directory zshdb lives in the source code which gets run +when zshdb is run without any options. so to run this demo code: + ./zshdb # in the zshdb project + +Or try on a real program such as perhaps: + ./zshdb /etc/zsh/zshrc # substitute .../zshrc with your favorite zsh script + +If you are happy (which I doubt), install via: + sudo make install + +and uninstall with + sudo make uninstall # ;-) + +See INSTALL for generic configure installation instructions. + +2. WHAT'S HERE, WHAT'S NOT and WHY NOT + +Usually when folks write programs such as a debugger, initially there +will be a number of useful commands minimally done. Since I sort of +know where I want to wind up (somewhere along the lines of bashdb), +initially I've been focusing on the skeleton and framework rather than +the features no matter how useful they may be. So for example, Unit +tests and a some integration tests work, even though there no command +to set breakpoints. + +What's missing falls into a two categories: + + * Stuff that can be ported in a straightforward way from bashdb + * Stuff that needs additional zsh support + +Of the things which can be ported in a straight-forward way, however +some of them I want to revise and simplify. In some cases, the fact +that zsh has associative arrays simplifies code. On other cases, the +code I wrote needs refactoring and better modularization. + +Writing documentation is important, but an extensive guide will have +to wait. For now one can consult the reference guide that comes with +bashdb: http://bashdb.sf.net/bashdb.html There is some minimal help to +get a list of commands and some help for each. + +3. WHAT'S NOT HERE YET IN DETAIL + +3.a) source listing commands + +Commands to list the source code and show the command that is about to +be run is missing. There are a couple reasons for this. First, I use +the emacs interface and that shows me source code lines. To use this: + + M-x load-library (with zshdb/emacs/zshdb.el in source) + M-x zshdb (name of program when prompted) + +The other reason listing is not around is that bash doesn't have +assocative arrays in 3.x and this would simplify the code. Indpendent +of that, the code needs to be modularized better. In ruby-debug and +pydb, this is its own module. Also possible is that zsh could add more +support for showing the command to be executed. Ruby has a neat +mechanism that causes the source as an array of lines to be stored +when a certain associative array is defined. Finally bashdb adds a +builtin to speed up reading files into an array. (zsh has mapfile, but +that is not enough.) + +3.b) breakpoints + +This is probably a straight-forward port of code from bashdb. Possibly +some simplification with associative arrays. + +3.c) next (step over function calls) + +This can be implemented without support from zsh, but probably +debugging support would be faster with the code added to zsh. So I'm +punting on this for now. + +3.d) Showing frame arguments + +Like next, this can done with or without support from zsh, abeit +faster with help from zsh. Changing scope when changing frames however +has to be done with zsh support. + +3.e) Information persisting when a subshell is left + +One of the challenges of POSIX shells is to be able to pass +information back from a subshell or nested shell back to a +parent. bashdb uses a journal file for this and tests SHLVL and +BASH_SUBSHELL; zshdb lacks the latter. BASH_SUBSHELL is probably a +simple thing to add though. + +Adding breakpoints and debugger settings will make this problem more apparent. + +3.f) Skipping code + +Under discussion in the zsh-workers mailing list. Not hard to add when +that gets worked out. + +3.g) Setting $0 + +3.h) lots of other stuff including... + + display expressions, signal handling, invoking the debugger directly + from a script, command history, command completion. + + None of this is rocket science. Should be pretty straight-forward to + add. + + README @@ -1,4 +1,6 @@ #!/bin/zsh autoreconf -i && \ -autoconf && \ -./configure +autoconf && { + print "Running configure with $@" + ./configure $@ +} autogen.sh @@ -20,27 +20,27 @@ # Number of statements to skip before entering the debugger if greater than 0 typeset -i _Dbg_skip_ignore=0 -add_help skip \ -'skip [ nnn] skip once or nnn times.' +# add_help skip \ +# 'skip [ nnn] skip once or nnn times.' -# Skip command -# $1 is an optional additional count. -_Dbg_do_skip() { +# # Skip command +# # $1 is an optional additional count. +# _Dbg_do_skip() { - _Dbg_not_running && return 1 +# _Dbg_not_running && return 1 - local count=${1:-1} +# local count=${1:-1} - if [[ $count == [0-9]* ]] ; then - _Dbg_skip_count=${count:-1} - else - _Dbg_msg "Argument ($count) should be a number or nothing." - _Dbg_skip_count=0 - return 0 - fi - _Dbg_write_journal "_Dbg_skip_count=$_Dbg_skip_count" - return 2 -} +# if [[ $count == [0-9]* ]] ; then +# _Dbg_skip_count=${count:-1} +# else +# _Dbg_msg "Argument ($count) should be a number or nothing." +# _Dbg_skip_count=0 +# return 0 +# fi +# _Dbg_write_journal "_Dbg_skip_count=$_Dbg_skip_count" +# return 2 +# } add_help step \ 'step [ nnn] step (into functions) once or nnn times.' command/stepping.sh @@ -8,6 +8,7 @@ Runs zsh <script_file> under a debugger. options: -h | --help print this help -q | --quiet Do not print introductory and quiet messages. + -A | --annotate LEVEL set annotation level. -B | --basename basename only on source listings. (Needed in regression tests) -L libdir | --library libdir @@ -30,7 +31,8 @@ local o_cmdfile='' o_nx='' o_basename='' local temp zparseopts -D -- \ - B=o_basename \ + A:=o_annotate -annotate:=o_annotate \ + B=o_basename -basename=o_basename \ L:=temp -library:=temp \ V=o_version -version=o_version \ h=o_help -help=o_help \ dbg-opts.sh @@ -152,21 +152,6 @@ _Dbg_onecmd() { h | he | hel | help | '?' ) _Dbg_do_help $args ;; -# # next/skip-step N times (default 1) -# n | ne | nex | next ) -# _Dbg_last_next_step_cmd="$_Dbg_cmd" -# _Dbg_last_next_step_args="$args" -# # _Dbg_do_next_step_skip $_Dbg_cmd "$args" -# if [[ $_Dbg_cmd == sk* ]] ; then -# _Dbg_inside_skip=1 -# _Dbg_last_cmd='skip' -# return 1 -# else -# _Dbg_last_cmd='next' -# return 2 -# fi -# ;; - # print globbed or substituted variables p | pr | pri | prin | print ) _Dbg_do_print "$args" @@ -187,12 +172,12 @@ _Dbg_onecmd() { return $? ;; - # skip N times (default 1) - sk | ski | skip ) - _Dbg_last_cmd='skip' - _Dbg_do_skip $@ - return $? - ;; +# # skip N times (default 1) +# sk | ski | skip ) +# _Dbg_last_cmd='skip' +# _Dbg_do_skip $@ +# return $? +# ;; # Run a debugger comamnd file so | sou | sour | sourc | source ) lib/processor.sh @@ -1,4 +1,4 @@ -#!@ZSH_PROG@ +#!@ZSH_PROG@ -f # -*- shell-script -*- # Original $0. Note we can't set this in an include. @@ -8,11 +8,11 @@ typeset -r _Dbg_orig_0=$0 typeset -r _Dbg_pname=${0##*/} ## Stuff set by autoconf/configure ### -prefix=@prefix@ # cygwin gets PKGDATADIR wrong -typeset _Dbg_libdir=${prefix}/share/zshdb +typeset prefix=@prefix@ +typeset _Dbg_libdir=@datarootdir@/zshdb ### -[[ ! -d _Dbg_libdir ]] && _Dbg_libdir='.' +[[ ! -d $_Dbg_libdir ]] && _Dbg_libdir='.' # Parse just the libdir option local -a libdir zparseopts -a libdir -E L: -library: zshdb.in fb6731c8ffa85141696d1db5871405d06439ba7c R. Bernstein rocky@gnu.org http://github.com/rocky/zshdb/commit/17daff2236ddac66eba2f7428892cf1f0e27cf5a 17daff2236ddac66eba2f7428892cf1f0e27cf5a 2008-08-09T07:44:12-07:00 2008-08-09T07:44:12-07:00 Disable skip command. get configured libdir set properly on zshdb start-up. b51e8b49ea3aa41698beedded7092a213a413de6 R. Bernstein rocky@gnu.org