Maintainer Note: Geben support/maintenance is minimal at the moment (most the previous maintainers no longer use it in day to day work). I've heard good things about: https://github.com/emacs-lsp/dap-mode and recommend giving it a try if able.
Geben is a software package that interfaces Emacs to DBGp protocol with which you can debug running scripts interactively. At this point, the DBGp protocol is supported in several scripting languages with help of custom extensions.
- PHP with Xdebug 2.* / Xdebug 3.*
- Perl, Python, Ruby and Tcl with Komodo Debugger Extensions
Table of Contents
- continuation commands: run/stop/step-in/step-over/step-out
- set/unset/listing breakpoints
- expression evaluation
- STDOUT/STDERR redirection
- backtrace listing
- variable inspection
We recommend installing geben via melpa: M-x package-install geben.
Alternatively clone this repository and add it to your load-path.
To debug PHP scripts, you will need to install PHP, Xdebug and optionally a web server. Please visit their official sites to get packages and instructions of installation and configuration:
To begin testing this out, create a simple PHP file (/tmp/gebenTest.php) as such:
<?php
$x = 1;
echo $x;
$y = 2;
echo $y;You can now hop over to emacs, and enable the geben listener (default port 9000) by running M-x geben.
At this point, you need to run the script with the xdebug configuration set up to point to this listener.
Run this to invoke your script with xdebug dbgp enabled (or add to your CLI php.ini file to ensure it runs with these settings every time):
php -d xdebug.remote_enable=on \
-d xdebug.remote_host=127.0.0.1 \
-d xdebug.remote_port=9000 \
-d xdebug.remote_handler=dbgp \
-d xdebug.idekey=geben \
-d xdebug.remote_autostart=On \
/tmp/gebenTest.php php -d xdebug.mode=debug \
-d xdebug.client_host=127.0.0.1 \
-d xdebug.client_port=9000 \
-d xdebug.remote_handler=dbgp \
-d xdebug.idekey=geben \
-d xdebug.start_with_request=yes \
/tmp/gebenTest.phpAlternatively, you can use export XDEBUG_MODE=debug instead of -d xdebug.mode=debug
You will notice the script does not complete, it pauses in your emacs session. Press SPC to step forward a line at a time.
-
Run Emacs.
-
Start geben
M-x geben -
Access to the target PHP script page with any browser. You may need to add a query parameter
XDEBUG_SESSION_STARTif you configured Xdebug to require manual trigger to start a remote debugging session. e.g. http://www.example.com/test.php?XDEBUG_SESSION_START=1 -
Soon the server and Geben establish a debugging session connection. Then Emacs loads the script source code of the entry page in a buffer.
-
Add a mapping from files on the host to files on the vm/docker image with
M-x customize-variable geben-path-mappingsor set in emacs config with(setq geben-path-mappings '(("<project base on host>" "<project base on vm>")) -
Check those mappings with
C-h v geben-path-mappings. Beware that the mappings only show up after geben was required. -
Open a file you are interested in setting breakpoints on the host machine. Find the line and issue
M-x geben-add-current-line-to-predefined-breakpoints. -
Check that a breakpoint has been set with
C-h v geben-predefined-breakpoints -
Follow process in web
-
To set new breakpoints in an active geben buffer, you can use
borM-x geben-set-breakpoint-line. To set a new breakpoint outside an active geben buffer, open the file on the host system and useM-x geben-add-current-line-to-predefined-breakpointsagain.
Even though Node.js ha(s|d) some dbgp protocol support via the komodo-debug that extension seems to be unmainted and succeded by the newer debug implementations from 7.x forward and geben is not supporting it. We recommend jade to debug node applications with Emacs.
You can control the debugger with several keys.
(define-key geben-mode-map "\C-cb" 'geben-show-breakpoint-list)
(define-key geben-mode-map "\C-cp" 'geben-toggle-pause-at-entry-line-flag)
(define-key geben-mode-map "\C-cf" 'geben-find-file)
(define-key geben-mode-map "\C-c\C-s" 'geben-step-into)
(define-key geben-mode-map "\C-c\C-n" 'geben-step-over)
(define-key geben-mode-map "\C-c\C-c" 'geben-run)
(define-key geben-mode-map "\C-c\C-d" 'geben-unset-breakpoint-line)
(define-key geben-mode-map "\C-c\C-t" 'geben-set-breakpoint-line)
(define-key geben-mode-map "\C-c\C-l" 'geben-where)
;; OR a new convenience function for your init file:
(geben-define-legacy-keybindings) ;; Will do the aforementioned bindings - spc step into/step over
- i step into
- o step over
- r step out
- g run
- c run to cursor
- e eval php expression
- b set a breakpoint at a line (see: defcustom geben-predefined-breakpoints)
- B set a breakpoint interactively
- u unset a breakpoint at a line
- U clear all breakpoints
- C-c b display breakpoint list
- > set redirection mode
- C-u t change redirection mode
- d display backtrace
- t display backtrace
- v display context variables
- C-c f visit script file
- w where
- q stop
When you hit any unbound key of geben-mode, Geben will ask you to
edit the original script file. Say yes and Geben will attempts to
load the script file via TRAMP.
To quit Geben: M-x geben-end
-
Xdebug does not support STDERR command feature so that STDERR redirection feature does not work expectedly.
-
Xdebug does not implement
dbgp:scheme feature so that withstep-incommand into a lambda function (you can create it withcreate_functionin PHP) or mocked function the cursor position is located at an invalid line. Geben could handle this more gracefully. -
Xdebug may tell invalid line number on breaking by
returntype breakpoint. To this case Geben indicates the cursor at the top of the file in where the current breakpoint exists. -
Xdebug unexpectedly breaks on returning from class/instance method if there is a
calltype breakpoint to the method. -
Conditional breakpoints currently cannot be deleted
We always need your support - bug reports, feature requests, and code/documents/design contributions.
To submit one or more of them, please file an issue here or email Matthew Carter m@ahungry.com.
GPLv3