E. Troubleshooting

Although IDLWAVE usually installs and works without difficulty, a few
common problems and their solutions are documented below.

Whenever an IDL error occurs or a breakpoint is hit, I get
errors or strange behavior when I try to type anything into some of my
IDLWAVE buffers.

This is a feature, not an error. You're in Electric Debug
Mode (see section 5.4.6 Electric Debug Mode). You should see *Debugging*
in the mode-line. The buffer is read-only and all debugging and
examination commands are available as single keystrokes: C-? lists
these shortcuts. Use q to quit the mode, and customize the
variable idlwave-shell-automatic-electric-debug if you prefer not
to enter electric debug on errors or breakpoints... but you really
should try it before you disable it!

I'm getting errors like `Symbol's value as variable is void:
cl-builtin-gethash on completion or routine info.'

This error arises if you upgraded Emacs from 20.x to 21.x without
re-installing IDLWAVE. Old Emacs and new Emacs are not byte-compatible
in compiled lisp files. Presumably, you kept the original .elc files in
place, and this is the source of the error. If you recompile (or just
"make; make install") from source, it should resolve this problem.
Another option is to recompile the `idlw*.el' files by hand using
M-x byte-compile-file. Why not take the opportunity to grab the
latest IDLWAVE version at the
maintainers webpage

M-TAB doesn't complete words, it switches
windows on my desktop.

Your system is trapping M-TAB and using it for its own
nefarious purposes: Emacs never sees the keystrokes. On many Unix
systems, you can reconfigure your window manager to use another key
sequence for switching among windows. Another option is to use the
equivalent sequence ESC-TAB.

When stopping at breakpoints or errors, IDLWAVE does not
seem to highlight the relevant line in the source.

IDLWAVE scans for error and halt messages and highlights the stop
location in the correct file. However, if you've changed the system
variable `!ERROR_STATE.MSG_PREFIX', it is unable to parse these
message correctly. Don't do that.

IDLWAVE doesn't work correctly when using ENVI.

Though IDLWAVE was not written with ENVI in mind, it works just fine
with it, as long as you update the prompt it's looking for (`IDL>
' by default). You can do this with the variable
idlwave-shell-prompt-pattern (see section 5.1 Starting the Shell), e.g.,
in your `.emacs':

(setq idlwave-shell-prompt-pattern "^\\(ENVI\\|IDL\\)> ")

Attempts to set breakpoints fail: no breakpoint is
indicated in the IDLWAVE buffer.

IDL changed its breakpoint reporting format starting with IDLv5.5. The
first version of IDLWAVE to support the new format is IDLWAVE v4.10. If
you have an older version and are using IDL >v5.5, you need to upgrade,
and/or make sure your recent version of IDLWAVE is being found on the
Emacs load-path (see the next entry). You can list the version being
used with C-h v idlwave-mode-version RET.

I installed a new version of IDLWAVE, but the old
version is still being used or IDLWAVE works, but when I
tried to install the optional modules `idlw-roprompt.el' or
`idlw-complete-structtag', I get errors like `Cannot open
load file'.

The problem is that your Emacs is not finding the version of IDLWAVE you
installed. Many Emacsen come with an older bundled copy of IDLWAVE
(e.g. v4.7 for Emacs 21.x), which is likely what's being used instead.
You need to make sure your Emacs load-path contains the directory
where IDLWAVE is installed (`/usr/local/share/emacs/site-lisp', by
default), before Emacs' default search directories. You can
accomplish this by putting the following in your `.emacs':

(setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path))

You can check on your load-path value using C-h v
load-path RET.

IDLWAVE is screwing up the formatting of my `.idl' files.

Actually, this isn't IDLWAVE at all, but `idl-mode', an unrelated
programming mode for CORBA's Interface Definition Language (you should
see `(IDL)', not `(IDLWAVE)' in the mode-line). One
solution: don't name your file `.idl', but rather `.pro'.
Another solution: make sure `.idl' files load IDLWAVE instead of
`idl-mode' by adding the following to your `.emacs':

(setcdr (rassoc 'idl-mode auto-mode-alist) 'idlwave-mode)

IDLWAVE is disregarding my `IDL_PATH' which I set
under MacOSX

If you run Emacs directly as an Aqua application, rather than from the
console shell, the environment is set not from your usual shell
configuration files (e.g. `.cshrc'), but from the file
`~/.MacOSX/environment.plist'. Either include your path settings
there, or start Emacs and IDLWAVE from the shell.

The routine info for my local routines is out of date!

IDLWAVE collects routine info from various locations (see section A.2 Routine Information Sources). Routines in files visited in a buffer or
compiled in the shell should be up to date. For other routines, the
information is only as current as the most recent scan. If you have a
rapidly changing set of routines, and you'd like the latest routine
information to be available for it, one powerful technique makes use of
the library catalog tool, `idlwave_catalog'. Simply add a line to
your `cron' file (`crontab -e' will let you edit this on some
systems), like this:

45 3 * * 1-5 (cd /path/to/myidllib; /path/to/idlwave_catalog MyLib)

where `MyLib' is the name of your library. This will
rescan all `.pro' files at or below `/path/to/myidllib' every
week night at 3:45am. You can even scan site-wide libraries with this
method, and the most recent information will be available to all users.