Binary releases ¶

Binary releases may be available from GitHub on an unpredictable schedule.

A file with an AppImage extension (such as DomTerm-version.AppImage) is a pre-compiled application, which can be treated as the domterm program with various resources bundled in a single file. Just download it; make it executable (chmod +x DomTerm-version.AppImage); and optionally rename it (maybe to domterm) and put it on your PATH. You should be able to run it on most recent GNU/Linux operating systems, as well as compatible ones. Specifically, it runs fine on Windows Subsystem for Linux (WSL 2). The AppImage includes the qt and webview front-ends, but they do depend on GUI libraries that might not be on your platform. On WSL 2, DomTerm defaults to using the edge-app front-end, which works pretty well.

Getting the DomTerm source code ¶

The sources are in a GitHub repository. To download the sources do:

git clone https://github.com/PerBothner/DomTerm

The following instructions assume a Unix-like environment (Linux, BSD, macOS, or WSL on Windows). On other platforms (including plain Windows without WSL) you may be able to use electron-nodepty: Using node for background server (experimental).

Simplified instructions ¶

The following assumes you prioritize simple instructions over download speed, disk space, or maximum functionality.

MacOS ¶

Use HomeBrew to install some prerequisites:

brew install automake libwebsockets asciidoctor pkg-config openssl@3

Optionally one or more of the following (for the Qt, Electron, or Wry frontends):

brew install qt

brew install npm
npm install electron -g

brew install rust jq

Then in the DomTerm source directory do:

autoreconf -i
CXX="g++ -std=c++11" ./configure
make

Choose a frontend and start Domterm:

bin/domterm -Bfrontend

Suggested values of -Bfrontend include -Belectron (Electron - currently recommended); -Bqt; -Bwry (Rust-based Tauri/Wry); -Bfirefox (in Firefox browser); or -Bchrome-app (Chrome browser with reduced clutter). For example to start the Qt frontend do:

bin/domterm -Bqt

Prerequisites ¶

Please help out with instructions for other platforms, especially macOS, *BSD, and native (non-WSL) Windows.

Fedora ¶

On Fedora, you need to first:

sudo dnf install gcc g++ make automake autoconf texinfo patch libwebsockets libwebsockets-devel openssl-devel file-devel libcap-devel asciidoctor zlib-devel

If configuring --with-qt (recommended), also do:

sudo dnf install gcc-c++ qt6-qtbase-devel qt6-qtwebengine-devel qt6-qtwebchannel-devel qt5-qtx11extras-devel

If configuring with --enable-compiled-in-resources (for xxd - only needed at build time):

sudo dnf install vim-common

For Java classes, do:

sudo dnf install java-1.8.0-openjdk-devel

(You can also use Oracle JDK, version 8 or 9.)

If configuring with --with-closure-compiler do:

sudo dnf install closure-compiler

If building the documentation and configuring --with-docbook:

sudo dnf install docbook-style-xsl libxslt

If configuring with --with-webview (experimental) do:

sudo dnf install gtk3-devel webkit2gtk3-devel

If configuring with --with-wry do:

sudo dnf install rust cargo gtk4-devel webkit2gtk4.1-devel libsoup3-devel jq

Ubuntu/Debian ¶

(Tested on Ubuntu 17.10.1)

You need to install the following prerequisites:

sudo apt-get install git gcc make automake pkg-config asciidoctor libmagic-dev zlib1g-dev

If configuring --with-qt (recommended), also do:

sudo apt-get install qt5-default libqt5webengine5 libqt5webchannel5-dev qtwebengine5-dev

In the future you should be able to do apt-get install libwebsockets-dev, but at the time of writing the available package is too old, so you have to build libwebsockets from source - see below.

If you need to build libwebsockets from source:

sudo apt-get install cmake

Otherwise:

sudo apt-get install libwebsockets-dev

If configuring with --with-webview (experimental) do:

sudo apt install libgtk-3-dev libwebkit2gtk-4.0-dev

If configuring with --with-wry (experimental) do:

sudo apt install rustc cargo libgtk-3-dev libwebkit2gtk-4.0-dev

Windows using WSL (Linux for Windows) ¶

For building from source on WSL (Windows Subsystem for Linux) see the instructions below.

Alternatively, you can use of the pre-compiled releases. Download domterm-version-wsl.zip. Then create a directory on a Windows partition, cd to it, and unzip the downloaded file into the partition. For example (assuming your Windows user name is wuser):

cd /mnt/c/wuser
mkdir DomTerm
cd DomTerm
unzip /mnt/c/User/wuser/Downloads/domterm-version-wsl.zip

These library dependencies are needed:

apt-get install libmagic1 zlib1g

Optionally you can create a symlink for domterm:

cd ~/bin
ln -s /mnt/c/wuser/DomTerm/bin/domterm domterm

Installing Electron is highly recommended.

MacOS(using Homebrew) ¶

brew install automake libwebsockets asciidoctor pkg-config

If you want to use the Electron front-end:

brew install npm
npm install electron -g

If you will be using Qt:

brew install qt5
brew link qt5 --force

There are some issues about openssl that I’m not clear about. A reported work-around is to do:

export LDFLAGS="-L/usr/local/opt/openssl/lib -L/usr/local/lib -L/usr/local/opt/expat/lib"
export CFLAGS="-I/usr/local/opt/openssl/include/ -I/usr/local/include -I/usr/local/opt/expat/include"
export CPPFLAGS="-I/usr/local/opt/openssl/include/ -I/usr/local/include -I/usr/local/opt/expat/include"

A cleaner solution/fix would be welcome.

Building libwebsockets, if needed ¶

The domterm server requires libwebsockets version 2.2 or newer. Version 3.2 has reported problems. As of January 2021, the version in Fedora 33 seems fine, but the version in Ubuntu is best not used. If you need to build libwebsockets from source, do the following:

cd $WORKDIR
git clone https://libwebsockets.org/repo/libwebsockets
cd libwebsockets
mkdir build
cd build
cmake -DLWS_WITH_SSL=0 -DLWS_WITHOUT_EXTENSIONS=0 -DLWS_WITH_ZIP_FOPS=1 ..

The -D options are suggested but not required: -DLWS_WITH_SSL=0 avoids a dependency on OpenSSL; while -DLWS_WITH_ZIP_FOPS=1 is required if configuring with --disable-compiled-in-resources (the default).

Finally:

make

When running ./configure in the DomTerm sources, specify --with-libwebsockets=$WORKDIR/libwebsockets/build.

Optional: Electron ¶

The Electron framework provides a nicer domterm front-end than a regular web browser. It is similar to using qtdomterm, but it is easier to install electron on platforms that don’t have qt/qtwebengine packages easily available.

Grab a suitable package from here. Get the zip file with the plainest name (no -symbols or -pdb). For example, at the time of writing the current release is 7.1.2, so for Windows you want electron-v7.1.2-win32-x64.zip. Unzip into a freshly-created directory.

On Windows Subsystem for Linux (WSL), you need to unzip into a directory on a Windows partition, not a Linux partition. For example, assuming the Windows user name is wuser and Electron version number version, do:

cd /mnt/c/User/wuser
mkdir electron-version
cd electron-version
unzip  /mnt/c/User/wuser/Downloads/electron-vversion-win32-x64.zip

So that the domterm executable can find the electron executable, you can create an entry in settings.ini:

command.electron = /path/to/electron/electron

or (on WSL):

command.electron = /mnt/c/User/wuser/electron-version/electron.exe

Alternatively, you can create a symlink in your PATH to electron. For example, on WSL (where ~/bin is in the default PATH):

cd ~/bin
ln -s /mnt/c/User/wuser/electron-version/electron.exe electron

Optional: libclipboard ¶

Using libclipboard is recommended when not using Electron, as it makes Paste work better.

git clone https://github.com/jtanx/libclipboard.git
cd libclipboard
LIBCLIPBOARD_DIR=`pwd`
cmake .
make

Optional: Qt Docking (experimental) ¶

Managing docking (draggable panes and tabes) using a native library has some advantages (compared to GoldenLayout). Specifically, you can drag panes between top-level windows. There are two candidate Qt libraries that are being considered: Qt Advanced Docking System (slightly smaller, more liberal license, nicer defaults - but needs to use a fork for now) and KDDockWidgets (seems slightly more solid, better Wayland support, can be used unpatched). Both are supported in a proof-of-concept way; both need more polishing and testing, which may determine a preference.

To use (my fork of) Qt Advanced Docking System:

sudo dnf install qt5-qtx11extras-devel  # (On Fedora)
git clone https://github.com/PerBothner/Qt-Advanced-Docking-System.git
git checkout multi-main
QT_ADS_DIR=`pwd`/+installed+ #for example
mkdir build
cd build
cmake  -DCMAKE_INSTALL_PREFIX=$QT_ADS_DIR ..
make install

Then

configure --with-qt-docking=$QT_ADS_DIR

To use KDDockWidgets:

git clone https://github.com/KDAB/KDDockWidgets.git
KDDOCK_DIR=`pwd`/+installed+ #for example
mkdir build
cd build
cmake  -DCMAKE_INSTALL_PREFIX=$KDDOCK_DIR ..
make install

configure ... --with-kddockwidgets=$KDDOCK_DIR

Building from source ¶

If building from the git respository, first do:

autoreconf -i

This runs the GNU autotools (aclocal, autoconf, and automake).

Then run the configure script:

./configure configure-options

where configure-options can be:

--prefix=install-prefix

Set the root of the tree into which make install will install the built domterm. The default is /usr/local. The domterm and qtdomterm executables are installed in install-prefix/bin, man pages are installed in install-prefix/share/man, and other “resources” are installed in install-prefix/share/domterm.

On WSL the install-prefix should be on a Windows partition, at least if you want to use the Electron front-end (which is recommended).

--with-libwebsockets[=lws-build]

Build the C application ldomterm, which uses libwebsockets. If lws-build is specified, it should be the path to the build subdirectory of the libwebsockets compiled source tree. (The files lws-build/lib/libwebsockets.a and lws-build/include/libwebsockets.h should exist.)

Libwebsockets version 2.2 or newer is required, as older versions do not support flow control or paging.

This is the recommended “backend” and the default.

--with-java_websocket

--with-java_websocket=/path/to/java_websocket.jar

Build a WebSocket server, using Java WebSockets, which allows using any modern browser as a front-end. This server is no longer recommended or enabled by default.

This options adds the classes in java_websocket.jar to domterm.jar.

--with-asciidoctor

Generates help and man pages using AsciiDoctor. The default is to do so if asciidoctor is in the path.

--with-javafx[=library-name]

Enable using JavaFX to run standalone applications. The library-name does not need to be specified if using Java SE 8. It may be needed for OpenJDK or Java SE 7, in which case it is either a path to jfxrt.jar, or (for convenience if using Java SE 7) the JAVA_HOME.

If using Java 11 or later (which is “modularized”), you might set:

export JDK_JAVA_OPTIONS='--module-path /path/to/javafx-sdk-13.0.1/lib --add-modules javafx.controls,javafx.web'

--without-java

Disable building anything that depends on Java.

--with-qt

Use Qt and QtWebEngine to build qtdomterm, an advanced front-end that supports multiple tabs, screen re-sizing, and other nice features.

For this you need the Qt development tools including QtWebEngine installed.

For Fedora, you also need:

sudo dnf install qt5-qtbase-devel  qt5-qtwebchannel-devel qt5-qtwebengine-devel

--with-closure-compiler=compiler.jar

Use Google Closure Compiler to minimize the size of the JavaScript. (Current only the “simple optimizations” are done. Using the “advanced optimizations” would reduce the JavaScript file size further, but causes some not-yet-resolved problems.)

--with-webview

Build experimental support for the Webview cross-platform framework. This creates a binary bin/dt-webview, which is used if you open a domterm window with the -Bwebview option.

This has only been tested on Fedora and macOS.

This works ok though with some rough edges.

--with-wry

--with-wry=git-clone-path/wry

--with-wry={dependency}

Build support for the Wry cross-platform framework. This creates a binary bin/dt-wry. which is used if you open a domterm window with the -Bwry option. If --enable-debug is specified, does a debug build, which is needed to get a web instructore. (Shift-ClickRight then Inspect element.)

Wry works similar to WebView, but is part of the Tauri project and is written in Rust. A major advantage of Wry is that it is very actively maintained.

--with-libclipboard=libclipboard_dir

Using the libclipboard library is recommended if if you a non-Electron front-end, as it makes Paste menu items work better.

If you followed the installation instructions above then libclipboard_dir should be $LIBCLIPBOARD_DIR.

--with-docbook

Use DocBook for generating HTML documentation. This used to be the default but is no longer recommended with texinfo 6.8.

--with-xterm.js[=git-clone]

--with-xterm.js=npm

--with-xterm.js=path

Build experimental support for using the xterm.js terminal emulator in addition to the DomTerm emulator. The main advantage of xterm.js is that it is very fast; however, it is missing many of the features of DomTerm. See here for more information.

If the value of the option is git-clone or unspecified, then the xtermjs source code checked out (cloned) from GitHub into a xtermjs subdirectory, and built there. If the value of the option is npm, then the latest xterm.js release is downloaded by the npm command. Specifying a path uses an existing checked-out tree.

--enable-debug

Build for development and better debugging. Sets CFLAGS="-O0 -g" CXXFLAGS="-O0 -g". If --with-wry, build Wry with the debug profile. If --with-xterm.js, build the xterm.js modules with the development options.

--enable-compiled-in-resources

This feature causes the html, JavaScript and css files needed by DomTerm to be compiled into the executable. Otherwise, they are served from the compressed domterm.jar.

Then just:

make

To test it, you can try either:

bin/domterm

or

bin/qtdomterm

Either starts up a useable terminal emulator in a fresh window. (The latter is equivalent to bin/domterm --qt.)

Optionally, you can install the built files into the configured install-prefix directory:

make install

Building an AppImage ¶

After running configure, do:

make appimage/DomTerm.AppImage
chmod +x appimage/DomTerm.AppImage

You can run appimage/DomTerm.AppImage with the same options as the domterm command. It is a single file, which makes it easy to move and install. (It is reasonable to rename the DomTerm.AppImage to domterm.)

For better portability of the resulting DomTerm.AppImage you should build it on a machine with a slightly older libraries, and libwebsockets should be linked statically. You might also consider configuring --with-asciidoctor --with-webview --with-libclipboard=$LIBCLIPBOARD_DIR. The functionality of --with-webview and --with-libclipboard are more likely to break if libraries are incompatible, but they’re separate executables so shouldn’t break core functionality.

Windows using Linux for Windows ¶

Microsoft Windows is now supported using Windows Subsystem for Linux (WSL). This has been tested using the Ubuntu distrubution: Follow the above Ubuntu instructions for getting prerequsities (without the optional qt packages), including (currently) building libwebsockets from source.

Other distributions should work but have not been tested.

If you want to use the Electron front-end, install electron as described above. Electron is a Windows executable, and it needs to be able to read the “electron application” files in share/domterm/electron. Hence, if you run domterm in-place (without make install), the clone’d source directory must be on a Windows partition. Alternatively, if you run domterm as installed by make install, then the install-prefix must be on a Windows partition.

If you want want to use a web browser, the newer (Chrome-based) Edge works pretty well. In face --browser=edge-app is the default on WSL. Win32 versions of both Firefox and Google Chrome also work pretty well. The default location (for Firefox c:\Program Files (x86)\Mozilla Firefox\firefox.exe) should work out-of-the-box. Otherwise specify command.firefox or command.chrome in settings.ini. (Internet Explorer wll probably never be supported.)

Domterm looks for the user settings file in c:\Users\USER\AppData\Roaming\DomTerm\settings.ini.

The DomTerm.AppImage (see above) single-file application works well (at least on WSL2).