.. index:: Emacs, IDE; Emacs

*****
Emacs
*****

Emacs is a powerful editor and much more. Being a GNU project it also
comes with a GDB integration that also works with the Calypsi
debugger.

You will need to use the GDB-MI mode for Emacs which is based on the MI
(Machine Interface) protocol. Old GDB integrations for Emacs will
not work with Calypsi debugger.


Starting
========

It is easy to start the Calypsi debugger on a recent Emacs, simply use
the ``M-x gdb`` command. Emacs will then prompt for the command line
to use. Enter something like:

.. code-block:: sh

  dbnut -i mi --load-module /path-to/41cx.mod mybinary

Replace ``/path-to/`` with the path to your HP-41 operating system
image. Here we are using an image for the HP-41CX.

We also need to provide the path to the ELF/DWARF binary you have
built with the Calypsi tool chain, which is the image to debug.
In order to have proper debugging information you need to build with
the ``-g`` option.


Stopping
========

Simply issue the ``quit`` command on the debugger command line inside
Emacs.


Many windows mode
=================

Out of the box Emacs/GDB is typically used with a command line window
[#window]_ and a source window.

With GDB-MI  it may be a good idea to issue the command
``M-x gdb-many-windows`` which configures Emacs with a set of useful
windows for debugging. Here you will find a command line window that
works like the usual console mode (with command completion and
everything). A register window that updates as you step around is
also available. To top it off, your source buffer now shows the line
you are at with a solid arrow. You can set breakpoints by clicking in
the fringe of the source buffer.


.. image:: images/emacs-session.png
   :width: 90%


More information
^^^^^^^^^^^^^^^^

The official documentation can be opened inside Emacs using the
``M-x info`` command.

Select ``Gdb`` (takes you to *Debugging with GDB*), then select
``Emacs`` (takes you to *Using GDB under GNU Emacs*). Here you should
also find a link to ``GDB Graphical Interface`` which describes the
Many Windows mode in detail.


.. rubric:: Footnotes
.. [#window]
   A window in Emacs is a view to a buffer. (A buffer often
   corresponds to an open file, but it does not have to be tied to a
   file.)
