@node Installation
@chapter Installation

@cindex installation
@cindex building from source
@cindex Debian package
@cindex dependencies

@section Build dependencies

@cindex ncursesw
@cindex libncurses-dev
@cindex pkg-config

xwpe requires:

@table @code
@item libncurses-dev
Wide character ncurses library (required).  Provides the terminal display
API including UTF-8 support.

@item libx11-dev
X11 client library (optional).  Needed for the X11 binaries
(@command{xwpe}, @command{xwe}).  Pass @option{--without-x} to
@command{configure} to disable.

@item libgpm-dev
General Purpose Mouse library (optional, Linux only).  Enables mouse
support in the terminal binaries.  Pass @option{--without-gpm} to disable.

@item zlib1g-dev
Compression library (required).  Used by the built-in info viewer to
read compressed info pages.

@item autoconf, automake, pkgconf
Autotools and pkg-config (required only when building from git).
Release tarballs include pre-generated @command{configure} and
@command{Makefile.in}.
@end table

On Debian and Ubuntu:

@example
sudo apt install build-essential autoconf automake pkgconf \
  libncurses-dev libx11-dev libgpm-dev zlib1g-dev
@end example

@section Building from source

@subsection From a release tarball

@example
tar xf xwpe-@value{VERSION}.tar.gz
cd xwpe-@value{VERSION}
./configure
make
sudo make install
@end example

@subsection From git

@example
git clone https://codeberg.org/mendezr/xwpe.git
cd xwpe
autoreconf -fi
./configure
make
sudo make install
@end example

@subsection On macOS (Homebrew + XQuartz)

@cindex macOS
@cindex Homebrew
@cindex XQuartz

xwpe builds on macOS with Homebrew.  The terminal @command{wpe} needs no
X server; the X11 @command{xwpe} needs @uref{https://www.xquartz.org/,
XQuartz}.  Homebrew's @code{ncurses} is keg-only, so point
@env{PKG_CONFIG_PATH} at it before @command{configure}:

@example
brew install autoconf automake pkg-config ncurses libvterm json-c texinfo
export PKG_CONFIG_PATH="$(brew --prefix ncurses)/lib/pkgconfig:$PKG_CONFIG_PATH"
autoreconf -fi && ./configure && make && sudo make install
@end example

For the X11 build add @code{cairo pango libx11 libxft} and install
XQuartz.  The repository's @file{contrib/setup.sh} automates the whole
dependency-install-and-build for both Debian/Ubuntu and macOS; see the
README's @samp{Building & installing} section for the full list and the
keyboard notes (the Option key must be set to send Alt/Meta; the function
keys are grabbed by macOS -- use the @kbd{Alt-}@var{letter} equivalents).

@subsection On the BSDs (FreeBSD / OpenBSD / NetBSD)

@cindex FreeBSD
@cindex OpenBSD
@cindex NetBSD
@cindex BSD

Since 1.6.6 xwpe builds the full X11 editor on FreeBSD 14, OpenBSD 7.x and
NetBSD 9, and the console mouse in @command{wpe} works over SSH on all three.
Install the dependencies with the platform's package manager and configure with
@option{--without-gpm} (GPM is the Linux raw-console mouse daemon; the
xterm-style console mouse @command{wpe} uses does not need it).  X11 is in the
base system.

@example
# FreeBSD: pkg install autoconf automake pkgconf cairo pango json-c libvterm
# OpenBSD: pkg_add  autoconf automake cairo pango json-c libvterm  (curses is base)
# NetBSD:  pkgin install autoconf automake pkgconf cairo pango json-c libvterm03 ncurses
autoreconf -fi && ./configure --without-gpm && make
@end example

All three BSDs already package xwpe at 1.5.30a -- FreeBSD
@uref{https://www.freshports.org/devel/xwpe/, devel/xwpe}, OpenBSD
@uref{https://openports.pl/path/editors/xwpe, editors/xwpe} and NetBSD pkgsrc
@uref{https://pkgsrc.se/editors/xwpe, editors/xwpe} -- and an update to 1.6.6
follows the release tag.

@section Configure options

@cindex configure options

@table @option
@item --without-x
Disable X11 support.  Only the terminal binaries (@command{we},
@command{wpe}) will be built.

@item --without-gpm
Disable GPM mouse support.  Mouse will still work in X11 mode.

@item --prefix=@var{dir}
Install to @var{dir} instead of @file{/usr/local}.
@end table

@section What gets installed

@cindex install locations

@table @file
@item @var{prefix}/bin/we
The main binary (text editor, terminal mode).

@item @var{prefix}/bin/wpe
Symlink to @command{we} (programming environment, terminal mode).

@item @var{prefix}/bin/xwpe
Symlink to @command{we} (programming environment, X11 mode).

@item @var{prefix}/bin/xwe
Symlink to @command{we} (text editor, X11 mode).

@item @var{prefix}/lib/xwpe/help.xwpe
In-app help file (English).

@item @var{prefix}/lib/xwpe/help.key
Key binding reference for the help system.

@item @var{prefix}/lib/xwpe/syntax_def
Syntax highlighting definitions.

@item @var{prefix}/share/info/xwpe.info
The Texinfo manual (this document).  Read with @command{info xwpe}.

@item @var{prefix}/share/man/man1/
Man pages: @file{we.1}, @file{wpe.1}, @file{xwe.1}, @file{xwpe.1}.

@item @var{prefix}/share/applications/xwpe.desktop
Desktop entry file for X11 desktop environments.
@end table

@section Installing the Debian package

@cindex Debian

If xwpe is available in your Debian or Ubuntu release:

@example
sudo apt install xwpe
@end example

This installs the binaries to @file{/usr/bin/}, help files to
@file{/usr/lib/xwpe/}, and man pages to @file{/usr/share/man/man1/}.

@section Post-install check

After installation, verify that xwpe works:

@example
wpe
@end example

You should see a menu bar at the top (@samp{#  File  Edit  Search ...}),
an editor area in the center, and a status line at the bottom.  Press
@key{F10} to activate the menu, or @kbd{Ctrl-Q} to quit.

If the terminal shows garbled output, check that your terminal is set to
UTF-8 encoding and that @code{libncursesw} (not @code{libncurses}) is
linked.  Run @command{ldd $(which wpe) | grep ncurses} to verify.

@section On the bare Linux console (Terminus font)
@cindex console font
@cindex Terminus
@cindex setfont
@cindex setupcon

@command{wpe} draws its window borders and scrollbars with Unicode
box-drawing and block characters.  Inside a graphical terminal emulator
(@command{xterm}, GNOME Terminal, Konsole, kitty, @dots{}) these come from
the emulator's own font, so nothing extra is needed.  On a @emph{bare Linux
text console} (@kbd{Ctrl-Alt-F2}), however, the kernel can only display the
glyphs present in the loaded console font, and the default is often too small
a set -- the borders then fall back to plain @samp{|} and @samp{-}.

Load a console font with good Unicode coverage; @code{Terminus}
(@code{fonts-terminus} on Debian) is the broadest the distributions ship:

@example
# temporary, for the current console:
sudo setfont Uni3-Terminus32x16     # or Uni3-Terminus16 for a smaller font
@end example

To make it permanent, set it in @file{/etc/default/console-setup} and run
@command{setupcon}:

@example
CHARMAP="UTF-8"
FONTFACE="Terminus"
FONTSIZE="16x32"                    # 8x16 for the smaller font
@end example

@quotation Note
Even Terminus, a 512-glyph console font, lacks the small geometric symbols
xwpe uses for the window maximize/close boxes, so those may stay blank on the
bare console.  Making the console chrome degrade to plain ASCII when the VT
cannot show a glyph is planned; a terminal emulator is unaffected.
@end quotation
