Next: The domterm command, Previous: Features and screenshots, Up: DomTerm [Contents]
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).
Please help out with instructions for other platforms, especially MacOS, *BSD, and native (non-WSL) Windows.
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 zlib-devel
If configuring --with-qt
(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.)
If configuring with --with-closure-compiler
do:
sudo dnf install closure-compiler
If building the documentation and not condiguring --without-docbook
:
sudo dnf install docbook-style-xsl libxslt
If configuring with --with-webview
(experimental) do:
sudo dnf install gtk3-devel webkit2gtk3-devel
(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-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
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.
brew install automake json-c 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.
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://github.com/warmcat/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
.
The json-c library is needed by the domterm
C application.
If it is not installed in the system location or you
want to link it as a static library, do the following:
git clone https://github.com/json-c/json-c.git cd json-c JSON_C_DIR=`pwd` mkdir build && cd build cmake -DCMAKE_INSTALL_PREFIX=$JSON_C_DIR/dist .. make install
Then add --with-json-c=$JSON_C_DIR/dist
to the configure
command.
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
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` mkdir build && cd build cmake -DCMAKE_INSTALL_PREFIX=$LIBCLIPBOARD_DIR/dist .. make install
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) and KDDockWidgets (seems slightly more solid, better Wayland support). Both are supported in a proof-of-concept way; both need more polishing and testing, which may determine a preference.
To use Qt Advanced Docking System:
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
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-json-c[=$JSON_C_DIR/dist]
If the json-c library (needed by the C ldomterm application) is not in the default system location, or you want to link it as a static library.
--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 --webview
option.
This has only been tested on Fedora and MacOS.
--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/dist
.
--without-docbook
Don’t use DocBook for generating HTML documentation. The result is plain HTML without a navigation bar.
--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
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 command.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
.
Next: The domterm command, Previous: Features and screenshots, Up: DomTerm [Contents]