@c This is part of the Emacs manual.
@c Copyright (C) 2021--2025 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Haiku
@appendix Emacs and Haiku
@cindex Haiku

  Haiku is a Unix-like operating system that originated as a
re-implementation of the operating system BeOS.

  This appendix describes the peculiarities of using Emacs built with
the Application Kit, the windowing system indigenous to Haiku.  The
idiosyncrasies illustrated here do not apply to Emacs on Haiku built
without windowing support, or configured with X11.

@menu
* Haiku Basics::        Basic Emacs usage and installation under Haiku.
* Haiku Fonts::         Various options for displaying fonts on Haiku.
@end menu

@node Haiku Basics
@section Haiku Installation and Startup
@cindex haiku application
@cindex haiku installation

  When Emacs is installed under Haiku, two executables are copied to
the binaries directory, which are identical save for some identifying
file-system metadata.  The first is a normal Emacs executable,
@file{emacs}, whereas the second, @file{Emacs}, incorporates an icon
and an application ``signature'' that abets the system in attributing
both file types and open frames to it, thereby enabling it to receive
file type assignments, and thus to open files directly from the
Tracker.

  Several file attributes are set within @file{Emacs} that prompt the
system to permit only a single copy to run at any given time.  This
invariant is verified upon the establishment of a display connection,
and is enforced by terminating any Emacs process that attempts to
create a display connection when one is already present.

  For this and other reasons, @file{Emacs} is appropriate for starting
a GUI session of Emacs, while @file{emacs} should be used for other
types of Emacs sessions.

@cindex modifier keys and system keymap (Haiku)
  Emacs is incapable of receiving unusual modifier keys such as
@kbd{Hyper} under Haiku, or to receive accented characters produced
from the system Super key map.

  By default, the @key{Super} modifier is reported when the Option key
defined by the operating system is depressed.  Analogously, the
@key{Meta} modifier is assigned to the Command key, and of course
@key{Control} to the system Control key and @key{Shift} to the system
Shift key.  On a standard PC keyboard, Haiku should map these keys to
positions familiar to those using a GNU system, but this may require
some adjustment to your system's configuration to work.

  You can customize the relation between modifier keys known to the
system and those known to Emacs by means of the variables below.

@cindex modifier key customization (Haiku)
@table @code
@vindex haiku-meta-keysym
@item haiku-meta-keysym
The system modifier key that will be treated as the Meta key by Emacs.
It defaults to @code{command}.

@vindex haiku-control-keysym
@item haiku-control-keysym
The system modifier key that will be treated as the Control key by
Emacs.  It defaults to @code{control}.

@vindex haiku-super-keysym
@item haiku-super-keysym
The system modifier key that will be treated as the Super key by
Emacs.  It defaults to @code{option}.

@vindex haiku-shift-keysym
@item haiku-shift-keysym
The system modifier key that will be treated as the Shift key by
Emacs.  It defaults to @code{shift}.
@end table

The value of each variable can be one of the symbols @code{command},
@code{control}, @code{option}, @code{shift}, or @code{nil}.
@code{nil} or any other value will cause the default value to be used
instead.

@cindex tooltips (haiku)
@cindex haiku tooltips
  On Haiku, Emacs defaults to using the system tooltip mechanism.
Tooltips thus generated are sometimes more responsive, but will not be
able to display text properties or faces.  If you need those features,
customize the variable @code{use-system-tooltips} to @code{nil} value,
whereupon Emacs will use its own implementation of tooltips instead.

@cindex X resources on Haiku
  Unlike the X window system, Haiku does not provide a system-wide
resource database.  Since many important options are specified via X
resources (@pxref{X Resources}), an emulation is provided: upon
startup, Emacs will load a file named @file{GNU Emacs} inside the user
configuration directory (normally @file{/boot/home/config/settings}),
which should be a flattened system message where keys and values are
both strings, and correspond to attributes and their values
respectively.  Such a file may be created with the
@command{xmlbmessage} tool.

@cindex crashes, Haiku
@cindex haiku debugger
@vindex haiku-debug-on-fatal-error
  If the variable @code{haiku-debug-on-fatal-error} is non-@code{nil}, Emacs
will launch the system debugger when a fatal signal is received.  It
defaults to @code{t}.  If GDB cannot be used on your system, please
attach the report generated by the system debugger when reporting a
bug.

@node Haiku Fonts
@section Font Backends and Selection under Haiku
@cindex font backend selection (Haiku)

  Emacs supports several different font backends when built with Haiku
windowing support, though the subset supported is subject to the list
of dependencies present and enabled when Emacs was configured.  You
can specify which font backends to utilize by providing @w{@code{-xrm
Emacs.fontBackend:@var{backend}}} on the command line used to invoke
Emacs, where @var{backend} is one of the backends listed below, or on
a per-frame basis by changing the @code{font-backend} frame parameter.

  Two of these backends, @code{ftcr} and @code{ftcrhb} are identical
to their counterparts on the X Window System.  There is also a
Haiku-specific backend named @code{haiku}, that uses the App Server to
draw fonts, but presently cannot display color fonts or Emoji.
