Getting the DomTerm source code

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

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

Alternatively, it may be easier to grab one of the sporadic releases. A file named domterm-version.tar.gz is a GNU-style release; it includes some generated files (such as the configure script), for convenience. A file named domterm-version-wsl.zip contains compiled installable files for WSL (Windows Subsystem for Linux).

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 make automake autoconf texinfo patch libwebsockets libwebsockets-devel json-c json-c-devel openssl-devel file-devel libcap-devel asciidoctor

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

sudo dnf install gcc-c++ qt5-qtbase-devel qt5-qtwebengine-devel qt5-qtwebchannel-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.)

Ubuntu/Debian

(Tested on Ubuntu 17.10.1)

You need to install the following prerequisites:

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

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

sudo apt-get install qt5-qmake 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

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 libjson-c2 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
brew install json-c
brew install libwebsockets
brew install asciidoctor

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. As of January 2018, the version in Fedora 27 in fine, but the version in Ubuntu is too old. If you need to build libwebsockets from source, do the following:

cd $WORKDIR
git clone https://github.com/warmcat/libwebsockets
cd libwebsockets
mkdir build
cd build
cmake -DLWS_WITH_SSL=0 -DLWS_WITH_ZIP_FOPS=1 ..

The -D optional 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 1.8.2, so for Windows you want electron-v1.8.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

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:

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

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.

It is also recommended that you 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, Win32 versions of both Firefox and Google Chrome 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 commmand.chrome in settings.ini.

Note that the Microsft Edge browser does not work (for reason not yet known). (Internet Explorer wll probably never be supported.)

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