page about wowcamldebug
[homepage.git] / hacking / software / wowcamldebug.mdwn
1 # WOnderful (g)Vim oCAML DEBUGger
2 <small>(If you're wondering about the second "W" in the name ... Yes!: it's a
3 typo, it should be a "V", but the name is prettier with the "W" ;-) )</small>
4
5 After trying hard to learn the few emacs keybindings I need in order to use the
6 OCaml debugger inside emacs ... I resigned and decided to make
7 [`ocamldebug`](http://caml.inria.fr/pub/docs/manual-ocaml/manual030.html) work
8 with [(g)vim](http://www.vim.org) too. **WOWcamldebug** is the result.
9
10 [[table header="no" class="flow" format="dsv" data="""
11 [[img wowcamldebug-screenshot1.png size="375x179" class="flow" alt="wowcamldebug console"]]
12 [[img wowcamldebug-screenshot2.png size="375x392" class="flow" alt="wowcamldebug editor"]]
13 """]]
14
15 WOWcamldebug is a front end that permits to *use the OCaml debugger within
16 (g)vim*.  You can run it as you usually run ocamldebug and it will execute both
17 the ocamldebugger itself, permitting usual interaction, and a gvim window which
18 will be kept in sync with the current debugging position. The current debugging
19 line is highlighted and the cursor is positioned at the current event position
20 on that line.
21
22 Communication is possible in both directions: from ocamldebug to gvim and vice
23 versa. You can simply avoid caring about wowcamldebug and use your ocamldebug
24 terminal as usual. Alternatively you can use gvim and the provided (not that
25 fancy ...) toolbar for ocamldebug interaction which permits the usual ocamldebug
26 motion commands (next, step, backstep and previous) and more fancy actions like
27 printing the identifier at cursor position. 
28
29 In order to **install** WOWcamldebug you need to download the
30 [[tarball|wowcamldebug-0.3.tar.gz]]; follow the instructions in the INSTALL file
31 for build and installation. **Using** WOWcamldebug is trivial, just invoke it as
32 you would have invoked `ocamldebug` itself. Some additional options are provided
33 (e.g. `-source`) and documented via the `-help` command line option.
34
35 Warning in order to use editor → debugger communication (all the gvim
36 toollbar and menu commands need that) you will need one of:
37
38 * vim built with Python support
39 * the [[wowtell.ml]] utility (included in the distribution tarball)
40
41 which of the two methods is used is decided at runtime, with preference for the
42 Python support, if available.
43
44 ## News
45 * [19/08/2005] Fixed a setpgid issue which inhibit proper starting of
46 wowcamldebug. Version 0.3 is out including this fix only.
47 * [09/02/2004] Finally WOWcamldebug has a release: version 0.2 is out! New
48 features includes:
49   * many bug fixes (like CTRL-D and CTRL-C ocamldebug's support)
50   * gvim (ugly) toolbar, improved key bindings and more available commands
51   * support for print and display command in gvim with "print identifier at
52   position" semantics
53   * ocamldebug feedback in gvim's status line
54 * [06/02/2004] Added support for `-source` command line option. Using it is now
55 possible to specify an ocamldebug script file to be sources at startup
56 * [19/10/2003] Added support for editor → debugger communications. All commands
57 are available via gvim menus: a standard menu with commands for debugger control
58 and a contextual one (right click) with command for adding breakpoint at the
59 pointed line
60
61 ## Download
62 * Download [[wowcamldebug-0.3.tar.gz]], it is distributed freely under the terms
63 of the GNU General Public License
64
65 ## TODO
66 * add side markers for brekpoints (cfr. agide)
67 * discover why current position highlight doesn't work on "let" keywords
68 * strange CTRL-C behaviour: `break_debugger` function is invoked once for each
69 CTRL-C pressed, but ocamldebug prints "Interrupted" once the first time CTRL-C
70 is pressed, twice the second one and so on ...
71 * better display of current event: when clicking away to print values is easy to
72 forget where the current event was
73 * feedback of ocamldebug questions on gvim side
74
75 ## BUGS
76 * wowcamldebug can't distinguish between ocamldebug output and debugged
77 program output. Programs writing on stdout one of the ocamldebug prompts (see
78 variable "prompts" below) can mess up debugging status.  I know no solutions for
79 this bug yet, feel free to suggest one ...
80