@node Bugs and limits
@chapter Bugs and limits

@cindex bugs
@cindex limitations
@cindex known issues

This chapter documents known issues and limitations.  Some are inherited
from the original 1993 codebase; others are architectural limitations
that would require significant rewriting to fix.

@section Fixed in 1.6.x

These bugs existed for years and are now resolved:

@table @strong
@item UTF-8 display garbled (Debian #1137613)
Fixed in v1.6.0.  The 1993 byte-based screen buffer stored each byte of
a UTF-8 sequence as a separate cell, causing border misalignment and
garbled display.  The @code{SCREENCELL} buffer model decodes UTF-8 via
@code{mbrtowc()} and stores one character per cell.

@item Terminal resize not detected (Debian #1137649)
Fixed in v1.6.0.  xwpe now handles @code{KEY_RESIZE} from ncurses to
detect terminal size changes, reallocate buffers, and repaint.

@item Color dialog crash (Debian #228820)
Fixed in v1.5.31.  Dragging the mouse outside the colour table in
@samp{Options @result{} Adjust Colors} caused a segfault due to an
unclamped array index.

@item FTBFS with GCC 15 (Debian #1098180)
Fixed in v1.5.31 (via @code{-std=gnu17}) and permanently in v1.6.1
(automake sets @code{-std=gnu17} automatically).  GCC 15 defaults to
C23 where @code{f()} means @code{f(void)}, breaking K&R-style
declarations.

@item Terminal not reset on exit
Fixed in v1.5.31.  The terminal state is now properly saved and restored
on clean exit.

@item Display artefacts after closing menus and popups
Fixed in v1.6.2.  The SCREENCELL migration (v1.6.0) changed screen
cells from 2 to 8 bytes, but the popup save/restore system still used
uninitialised @code{malloc}'d buffers.  Random heap data appeared as
CJK characters or misplaced borders after closing menus, compile
windows, or dialogs.  Fix: @code{calloc}'d buffers + @code{altschirm}
invalidation on restore.

@item SEGFAULT when pressing F9 or navigating menus
Fixed in v1.6.2.  The @code{e_t_refresh} function accessed the
special-character table @code{sp_chr[]} with negative indices.
@code{SCREENCELL} uses @code{int} for characters (can be negative),
while the old @code{char} buffer was always 0--255.

@item Error navigation broken with modern GCC
Fixed in v1.6.2.  The @code{gnu_intstr} pattern expected 1990s
backtick quoting and only matched errors containing ``before''.
Updated to the standard @code{file:line:column:} format used by
GCC since 4.8 (2013).

@item Compiler output truncated at blank lines
Fixed in v1.6.2.  @code{print_to_end_of_buffer} stopped at the first
blank line, discarding subsequent errors.  Compilers that emit blank
lines between errors (gfortran, clang) only showed the first error.

@item Compiler exit code ignored
Fixed in v1.6.2.  The exit code was hardcoded to 0 since the Payne
era, so xwpe never detected compilation failures.

@item Non-GNU compilers received invalid flags
Fixed in v1.6.2.  @code{e_comp} hardcoded @code{-c} and @code{-o}
for all compilers.  Free Pascal and javac failed with ``Illegal
parameter''.  Now skipped for non-GNU compiler styles.

@item Default compilers outdated (f77, pc)
Fixed in v1.6.2.  Fortran now defaults to @command{gfortran} with
modern extensions (.f90/.f95/.f03/.f08).  Pascal defaults to
@command{fpc} with .pas/.pp.  Java (@command{javac}) added as 5th
default compiler.

@item Pipe file descriptor leak in debugger (30-year-old bug)
Fixed in v1.6.2.  After @code{fork()} in @code{e_exec_deb}, the
parent kept the write-end of the stdout pipe open.  This made
@code{read()} unable to detect EOF when the debugger exited, causing
busy loops in all debugger backends.  The bug survived 30 years
because gdb rarely exits unexpectedly; it was exposed by jdb's
fragile JVM startup timing.  Fix: close child's pipe ends in parent,
parent's pipe ends in child.

@item SIGPIPE crash on debugger exit
Fixed in v1.6.2.  When the debugger exited before xwpe sent the
@code{quit} command, @code{write()} to the closed pipe triggered
SIGPIPE which killed xwpe.  Now ignored in @code{e_d_quit_basic}.

@item User Screen (Ctrl-G P) broken since Payne era
Fixed in v1.6.2.  A @code{#ifndef NCURSES} guard unconditionally
disabled the User Screen when compiled with ncurses.  Restored
Kruse's original logic.  Program output now captured via pty (gdb)
or pipe (jdb) into a memory buffer and displayed on demand.

@item Debugger screen flicker on every step
Fixed in v1.6.2.  The original design toggled between alternate and
normal screen (@code{smcup}/@code{rmcup}) on every F7/F8 step.
Replaced with pty-based output capture: no screen switching, no
flicker.

@item Non-GNU compilers failed in link step
Fixed in v1.6.2.  @code{e_p_make} passed gcc-style @code{-o} flags
to all compilers during linking.  Free Pascal and javac link
internally.  Now skips the link step for non-GNU compiler styles.
@end table

@section Known open issues

@table @strong
@item Scala hover/completion need an LTS JDK for Metals (auto-handled)
Metals' presentation compiler (hover, completion, go-to-definition) runs on the
JVM Metals itself uses, @emph{not} the project's @code{//> using jvm} build JVM.
On a too-new JDK (>=@tie{}24, e.g.@: OpenJDK@tie{}26) the Scala@tie{}3
compiler crashes at start-up (@code{asTerm called on not-a-Term}), so those
actions silently return empty while diagnostics/definition still work.  xwpe
mitigates this automatically: it pins @env{JAVA_HOME} to an installed LTS JDK
(17/21) for Metals and reports it (@pxref{Language servers}).  The residual
limitation: if @emph{no} LTS JDK is installed, you must install one and/or set
@env{JAVA_HOME} yourself.

@item X11 mode does not display UTF-8
The X11 binaries (@command{xwpe}, @command{xwe}) use
@code{XDrawImageString} which does not support multi-byte characters.
UTF-8 text appears garbled or truncated in X11 mode.  Terminal mode
(@command{wpe}, @command{we}) works correctly.

@item Resize does not scale editor proportionally
When the terminal is resized larger in programming mode, the editor
window keeps its original size instead of expanding to fill the available
space.  The @code{KEY_RESIZE} handler expands windows at terminal edges
but does not recalculate the 2/3 ratio for the initial editor window.

@item Debugging leaks memory
The exact source of the leak is unknown.  It has been present since at
least the Payne era (documented in the 1.5.x CHANGELOG).

@item @command{make install} installs X11 binaries unconditionally
Even when compiled @option{--without-x}, the install target creates
the @command{xwpe} and @command{xwe} symlinks.  These will work (they
just run in terminal mode) but their presence is misleading.

@item Esc key requires 3 presses on Linux console
On the Linux console (and some other terminal types), the @key{ESC} key
must be pressed three times to trigger the escape function.  This is
because xwpe uses @key{ESC} as the prefix for Alt-key sequences, and
the terminal sends the same byte for both.

@item No error on disk full
xwpe does not detect or report write failures due to a full disk.

@item Maximum column and cut/paste interaction
Changing the maximum column setting and then using cut and paste can
crash xwpe.

@item Check Headers does not handle all cases
The ``Check Headers'' feature for C projects does not correctly handle
comments or @code{#ifndef} include guards.

@item Mouse click does not switch active window
Clicking with the mouse on a window (editor or Messages) does not
switch focus to that window.  Workaround: use @key{F6} to cycle
between windows.

@item Cursor jumps to Messages after successful compilation
After F9 with no errors, the cursor moves to the Messages window
instead of staying in the editor.  Workaround: press @key{F6} to
return to the editor.

@item Cross-compiler .o files cause link errors
When switching between languages (e.g.@: Pascal to C++), leftover
@file{.o} files from the previous compiler cause link errors.
Workaround: delete @file{.o} and @file{.e} files manually before
switching languages.

@item In-app help coverage
The in-app help file (@file{help.xwpe_eng}) covers the core interface
but not the v1.6.x features in detail.  For comprehensive
documentation, use this Texinfo manual (@command{info xwpe}).

@item GNU @command{screen} drops the mouse -- use @command{tmux}
xwpe uses the modern SGR mouse protocol (@code{ESC[<...M}).
@command{tmux} forwards it, so the mouse (pointer, click, window
drag/resize) works inside a tmux session.  GNU @command{screen}
(depending on its version and @env{TERM}) does @emph{not} pass SGR
mouse through, so clicks and drags arrive as raw bytes that get typed
into the editor instead of moving the cursor.  This is a
@command{screen} limitation, not an xwpe bug: the same xwpe works with
the mouse in the same terminal @emph{outside} @command{screen}.  Use
@command{tmux}, or run xwpe directly with no multiplexer.  Keyboard-only
use is unaffected in either.

@item macOS captures the function keys (@key{F8}/@key{F9}@dots{})
On macOS the top-row keys default to Mission Control, brightness and
volume, so @key{F9} (Make) and @key{F8} (step) never reach xwpe.  Either
enable @samp{Use F1, F2, etc.@: keys as standard function keys} in
@samp{System Settings @result{} Keyboard}, or use the equivalents that
do not rely on the top row: @kbd{Alt-M} (Make), @kbd{Alt-C} (Compile),
and the @kbd{Ctrl-G} debug prefix (@kbd{Ctrl-G S} steps like @key{F8},
@kbd{Ctrl-G R} runs/continues, @kbd{Ctrl-G P} shows program output).
The @kbd{Alt-} keys themselves need Option-as-Meta enabled in the
terminal (@pxref{Installation}).
@end table

@section Debian BTS history

@cindex Debian bugs

xwpe has been in Debian since 2002.  The following Debian bugs are
tracked or were resolved by the v1.6.x restoration:

@multitable @columnfractions .12 .50 .38
@headitem Bug @tab Title @tab Status
@item #228820 @tab SEGV in colour dialog @tab Fixed v1.5.31
@item #1098180 @tab FTBFS with GCC 15 @tab Fixed v1.5.31/v1.6.1
@item #1137613 @tab UTF-8 garbled @tab Fixed v1.6.0
@item #1137649 @tab Terminal resize not detected @tab Fixed v1.6.0
@item #1137650 @tab Info viewer stale content @tab Fixed v1.6.0
@item #214735 @tab Can't debug (archived) @tab Fixed v1.6.2
@item #264169 @tab FTBFS gcc-3.4 (archived) @tab Fixed v1.6.1
@item #155339 @tab gdb dependency missing (archived) @tab Documented (Suggests)
@item #634813 @tab Hardcoded architectures @tab Fixed by R. Millan
@end multitable

@section Reporting bugs

Report bugs at @uref{https://codeberg.org/mendezr/xwpe/issues}.

For Debian-specific bugs, use @command{reportbug xwpe} or file at
@uref{https://bugs.debian.org/xwpe}.
