DMPACK User Guide

Installation

This section describes the steps to build the DMPACK library and programs from source, either with POSIX Make or the Fortran Package Manager (FPM). At the moment, support for the Fortran Package Manager is experimental, and using GNU/BSD Make is recommended. Display the available build targets of the Makefile:

$ make help

Or, output the selected build options:

$ make options PREFIX=/opt

See section System Configuration on how to configure the operating system following the installation. You must at least prepare POSIX message queues in order to run DMPACK.

The shared libraries libgcc.so, libgfortran.so, and libquadmath.so have to be present on the target system if the DMPACK programs have been compiled with GNU Fortran.

Paths used by default
Path	Description
`/usr/local/bin/`	DMPACK programs.
`/usr/local/etc/dmpack/`	DMPACK configuration files.
`/usr/local/include/dmpack/`	DMPACK module files.
`/usr/local/lib/`	DMPACK libraries.
`/usr/local/man/man1/`	DMPACK man pages.
`/usr/local/share/dmpack/`	DMPACK examples, scripts, style sheets.
`/var/dmpack/`	DMPACK databases.
`/var/www/`	WWW root directory.

Linux

On Debian, install the compilers and the build environment first:

$ sudo apt-get install gcc gfortran git make pkg-config

The Git client is optional. The third-party dependencies have to be installed with development headers:

$ sudo apt-get install --no-install-recommends curl ghostscript gnuplot groff \
  libblas-dev libcurl4 libcurl4-openssl-dev libfcgi-bin libfcgi-dev libhdf5-103-1 \
  libhdf5-dev liblapack-dev liblua5.4 liblua5.4-dev libmodbus5 libmodbus-dev \
  libpcre2-8-0 libpcre2-dev libsqlite3-0 libsqlite3-dev libstrophe0 libstrophe-dev \
  libzstd1 libzstd-dev lua5.4 sqlite3 zlib1g zlib1g-dev

Instead of package gnuplot, you may prefer the no-X11 flavour gnuplot-nox if raster graphic formats are not required (limiting the output formats essentially to SVG). Depending on the Linux distribution, the names of the HDF5 and Lua packages may differ. Optionally, install FFmpeg, GraphicsMagick, and GhostScript fonts for camera access and image manipulation:

$ sudo apt-get install --no-install-recommends ffmpeg graphicsmagick gsfonts

In the next step, build DMPACK with make(1) or fpm(1).

Note

Building Dependencies from Source

If third-party libraries are not available in the required minimum version, like on Ubuntu 22.04 LTS or Debian 12, you may want to build the missing dependencies from source, for instance:

If the libraries are installed to a non-default directory, overwrite the specific linker flag. For example, if SQLite 3 has been installed to /opt, pass argument LIBSQLITE3:

$ make linux LIBSQLITE3="-Wl,-rpath=/opt/lib -L/opt/lib -lsqlite3"

For the other libraries, pass LIBCURL, LIBMODBUS, LIBSTROPHE, and LIBZSTD respectively.

Note

Other Compilers

If Intel oneAPI Fortran or LLVM Flang is used, it is necessary to build HDF5 from source, because the versions in the Linux package repositories have been compiled with GNU Fortran and are therefore incompatible. See section HDF5 for hints regarding the build process. Pass the library installation path additionally to -lhdf5 -lhdf5_fortran as argument LIBHDF5 and the path to the module files as argument INCHDF5.

Make

Clone the DMPACK repository with Git, using command-line argument --recursive:

$ git clone --depth 1 --recursive https://github.com/dabamos/dmpack
$ cd dmpack/

If Git is not available, download the archive of the master branch instead and run the shell script fetchvendor.sh to fetch the missing submodules:

$ curl -O -L -s https://github.com/dabamos/dmpack/archive/refs/heads/master.zip
$ unzip master.zip
$ cd dmpack-master/
$ sh fetchvendor.sh

Then, execute build target linux of the Makefile to compile the source:

$ make linux

On 64-bit ARM platforms, like those of the Raspberry Pi 3/4/5 series, select build target linux_aarch64 instead:

$ make linux_aarch64

Install the DMPACK libraries and programs system-wide to /usr/local:

$ sudo make install

Or, to install to directory /opt, run:

$ sudo make install PREFIX=/opt

Path /opt/bin must be added to the global PATH environment variable to run DMPACK programs from the command-line.

Note

Intel oneAPI Compilers

If your prefer Intel oneAPI over GCC, run:

$ make linux CC=icx FC=ifx \
  FFLAGS="-O2 -mtune=native -I/opt/include" \
  CFLAGS="-O2 -mtune=native" \
  LIBFLAGS="-fpic" \
  MODFLAGS="-module ./include -I./include" \
  PPFLAGS="" \
  LIBHDF5="-Wl,-rpath=/opt/lib -L/opt/lib -lhdf5 -lhdf5_fortran"

In this particular case, the HDF5 libraries are installed to /opt/lib, and the HDF5 module files to /opt/include. Change the paths to the actual locations.

FPM

To build DMPACK using the Fortran Package Manager, change to the cloned or downloaded repository, and run:

$ export FFLAGS="-D__linux__ `pkg-config --cflags hdf5` -ffree-line-length-0"
$ fpm test --flag "$FFLAGS"
$ fpm build --profile release --flag "$FFLAGS"
$ fpm install

The library and programs will be installed to directory ~/.local by default. If the compilation fails with an error message stating that -llua-5.4 cannot be found, update the library names in the build manifests:

$ sed -i "s/lua-5/lua5/g" fpm.toml
$ sed -i "s/lua-5/lua5/g" build/dependencies/fortran-lua54/fpm.toml

FreeBSD

First, install the build and run-time dependencies:

$ doas pkg install archivers/zstd comms/libmodbus databases/sqlite3 devel/git \
  devel/pcre2 devel/pkgconf ftp/curl graphics/GraphicsMagick lang/gcc \
  lang/lua54 math/gnuplot math/lapack multimedia/ffmpeg net-im/libstrophe \
  print/ghostscript10 science/hdf5 textproc/groff www/fcgi

Instead of math/gnuplot, you may want to install package math/gnuplot-lite which does not depend on X11 (but lacks the raster graphic terminals). The packages graphics/GraphicsMagick and multimedia/ffmpeg are optional. The web applications additionally require a web server:

$ doas pkg install www/lighttpd

If you want to generate the man pages and the User Guide from source, also install Pygments and AsciiDoctor:

$ doas pkg install devel/rubygem-pygments.rb textproc/rubygem-asciidoctor

Make

The repository has to be cloned recursively using command-line argument --recursive:

$ git clone --depth 1 --recursive https://github.com/dabamos/dmpack
$ cd dmpack/

If Git is not available, download the archive of the master branch and run the shell script fetchvendor.sh to fetch the submodules:

$ curl -O -L -s https://github.com/dabamos/dmpack/archive/refs/heads/master.zip
$ unzip master.zip
$ cd dmpack-master/
$ sh fetchvendor.sh

Execute the Makefile with build target freebsd:

$ make freebsd

Install the library and all programs system-wide to /usr/local:

$ doas make install

You can change the installation prefix with argument PREFIX. To install to directory /opt instead, run:

$ doas make install PREFIX=/opt

In this case, path /opt/bin must be included in the global PATH environment variable.

Note

LLVM Compilers

If you prefer LLVM 20 over GCC, you must compile HDF5 from source, as the module files provided in the FreeBSD package repository have been built with GNU Fortran. See section HDF5 for hints. Assumed that the HDF5 library is installed to /opt, run:

$ make freebsd CC=clang20 FC=flang20 \
  FFLAGS="-O2 -march=native -I/opt/include" \
  LDFLAGS="-L/usr/local/lib" \
  LIBHDF5="-Wl,-rpath=/opt/lib -L/opt/lib -lhdf5 -lhdf5_fortran"

FPM

Either clone the repository with Git, or download the archive of the master branch. Then, run:

$ export FFLAGS="-D__FreeBSD__ -I/usr/local/include -ffree-line-length-0"
$ fpm test --flag "$FFLAGS"
$ fpm build --profile release --flag "$FFLAGS"
$ fpm install

The Fortran Package Manager will fetch all third-party dependencies automatically, but the configuration and shared files have to be installed manually. The library and programs will be installed to ~/.local by default.

Updates

Update the cloned source code repository and its submodules with Git:

$ git pull
$ git submodule update --remote
$ make purge
$ make [freebsd|linux|linux_aarch64]
$ sudo make install PREFIX=/opt