I. COMPILING & INSTALLING

I believe that the process is quite simple. 
Just run the following commands:

./configure
make 
make install

If it fails during this process, you'd check if the following packages are
installed:

libtool 1.4 or higher
automake 1.4p5 or higher
autoconf 2.13 or higher
gcc 2.96 or higher
glibc 2.2 or higher

If configure fails to run, you may try to rebuild it using buildconf script.


By default dbg-cli executable is installed into /usr/local/bin/ 
dbgbaselib.a and necessary headers in /usr/local/lib and /usr/local/include
respectively. if you don't want dbg to be installed in /usr/local/ 
please supply --prefix argument to configure.


II. RUNNING

Starting with 2.11.32 I added support for initialization file ~/.dbgcli_init
where you can enter the commands to be run each time you start dbg-cli.
You may want to have there command such as set mode on, set mapurlroot 
http://localhost/, set cgiexec /usr/local/bin/php, etc.
Command line arguments supperceed the commands from the initialization file
as they have effect after the commands ran.
Run dbg-cli --help to see the command list arguments supported.

PLEASE NOTE, that dbg-cli runs php as CGI process and it may behave a little
differently than when invoked from the command line. 
I highly recommend to run phpinfo() and check where your php looks for 
php.ini. In nothing was specified for php's configure, it will look for 
php.ini in PREFIX/lib. If php can't locate php.ini, it will not load 
debugger module and subsequently it will fail to run debug session.

III. INTERFACE

After you ran dbg-cli, you may want to open a script and step though it

dbg>file myfile.php
dbg>run
dbg>step

If you want to debug your script under an Apache (or any other php-enabled WEB) 
you should use the following commands:

set mode -- Set HTTP mode of debugging.
set mapurlroot -- Set URL root for mapping.
set maplocalroot -- Set local root for mapping.
set mapremoteroot -- Set remote root for mapping.

For example:
>set mode on
>set mapurlroot http://localhost/
>set mapremoteroot /usr/local/apache/htdocs/
>set maplocalroot /usr/local/apache/htdocs/
>file /usr/local/apache/htdocs/myfile.php
>run
>break /usr/local/apache/htdocs/myfile.php:12
>cont

Alternatively, you may want to turn dbg-cli to listening mode by running 
listen command, then launch your favorite web browser and enter an URL with
DBGSESSID argument, for example
http://myhost/mydir/myscript.php?DBGSESSID=1@clienthost:7869
(I presume you issued port 7869 command before)
listen accepts one argument - number of seconds to wait.



IV.COMMANDS SUMMARY

IV.1 DEBUGGER COMMANDS, MISC

info                   - show various information
info files             - list all source file names being debugged
                         work during debug sessions only
info sources           - alias for info files (for DDD compatibility)
info source            - print current file name
info program           - stub for DDD compatibility
info breakpoints [num] - list all breakpoints or breakpoint number num, if specified.

set                    - group of commands to set various parameters
set port num           - set TCP/IP port for the dbg listener, 10001 or 7869 will be 
                         used by default or whatever port num specified.
set mode [on|off]      - set HTTP debugging mode (by default CGI mode is used)
set cgiexec /dir/php   - set full file name of php binary to be used for CGI sessions
set mapurlroot url     - set url to be used as root url for mapping in HTTP mode
set maplocalroot dir   - set dir to be used as local root for mapping in HTTP mode
set mapremoteroot dir  - set dir to be used as remot root for mapping in HTTP mode
                         See http://support.nusphere.com/viewtopic.php?t=2135
			 for mapping explained article
			 
show                   - group of command that displays settings
show port              - print dbg listener port value (0-default)
show mode              - print working mode (On means HTTP, otherwise CGI)
show cgiexec           - print php executable filename 
show mapurlroot        - print root url used for HTTP mapping
show maplocalroot      - print local root directory used for HTTP mapping
show mapremoteroot     - print remote root directory used for HTTP mapping

file filename          - specify filename to debug
run                    - start debug session
kill                   - stop debug session (Ctrl-C is handled too)
quit                   - quit the program
q                      - alias for quit
listen [sec]           - wait for debug session initiated in the other program (browser)
                         Sec specifies number of seconds to wait, otherwise dbg-cli will
			 wait until session comes or Ctrl-C is hit.
help                   - list all commands and their short description
pwd                    - print current directory
			 
IV.2 DEBUGGER COMMANDS, STEPPING
step                   - perform one single step (run until execution reaches another 
                         line)			 
next                   - step over current function call, if any is being debugged.
                         Otherwise performs exactly like step
finish                 - run until return from the current function
cont                   - continue execution until program finish or a breakpoint it 
                         reached
			 
IV.3 DEBUGGER COMMANDS, EXECUTION STACK
bt [num]               - print backtrace (list of nested functions) or innermost 
                         num stack frames (outermost if num is negative)
where [num]            - alias for bt 
up [num]               - select upper stack location (skip num positions)
down [num]             - select below stack location (skip num positions)
frame [num]            - select absolute stack frame position num (if specified) and 
                         print current stack frame
			 
IV.4 DEBUGGER COMMANDS, BREAKPOINTS
break filename:line    - set breakpoint at specified file/line number
tbreak filename:line   - set temporary breakpoint at specified file/line number
                         temporary breakpoint fires only once or it will be removed
			 when any other breakpoint is fired
enable num             - enable breakpoint number num
disable num            - disable breakpoint number num
delete num             - remove breakpoint number num
condition num [cond]   - set or remove condition statement cond for breakpoint number
                         num

IV.5 DEBUGGER COMMANDS, VALUES
display [expr]         - add watch, a statement to be evaluated and printed each time
                         execution stops in the debugger.
			 display all watches, if expr is not specified
undisplay [n1[ n2 ..]] - remove watched statements number n1, n2 etc
print expr             - evaluate expression in current stack frame and print value
print output           - dump out all output produced be the program being debugged
list [auto]            - dump out current context (source lines) being debugged
                         dump the context each time program is stopped in the debugged, 
			 if auto is specified.


V. TROUBLESHOOTING

If you got "session startup timeout expired" you'd first check if dbg.so 
extension is added to php.ini as follows:

####################################
extension=dbg.so
[debugger]
debugger.enabled=On
debugger.profiler_enabled=On
####################################

also, some people reported that even with settings shown above dbg-cli still
times out. In this case please make sure php finds its php.ini. See php 
documention on how it searches for php.ini

You may also want to check phpinfo() to see if DBG is loaded correctly and 
enabled. Take care, dbg.so is version depended and therefore you'd install 
dbg.so compatible with php installed in your system.

I ran tests myself and god feedback confirming that dbg-cli and dbg modules 
are working fine under RedHat 7.2, 7.3, 9, Mandrake 9.1, SuSe 9.3, 10,
Fedora Core2, 4 and 5, Sun Solaris 8, FreeBSD 4.11 and Win32 (Xp and W2k).


VI. FEEDBACK

You can post your comments at NuSphere public forum board:
http://support.nusphere.com/


Enjoy.
