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