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