Introduction

Debian is the name of a popular Linux distribution, and is also the name of the package management system of the Debian distribution and its derivatives (such as Ubuntu)

Debian packages have the file extension of .deb

Prerequisites

Before creating a Debian package of Earthworm, we will need to install the prerequisites needed for any Earthworm compile (see EarthwormCompile).

Install the Debian packaging tools:

sudo apt install build-essential

Package configuration

In the top level of the Earthworm directory, there is a directory labelled 'debian'

In this directory, you will find a file named rules. This is the file that specifies the actual build process used in creating the package:

#!/usr/bin/make -f
# You must remove unused comment lines for the released package.
export DH_VERBOSE = 1

export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic -Wextra -Wno-sign-compare -Wno-unknown-pragmas -Wno-pragmas -Wformat
export JAVA_HOME=/usr/lib/jvm/default-java
export CLASSPATH=/usr/share/java/csv.jar:/usr/share/java/debug-disable.jar:/usr/share/java/itext.jar
export EW_HOME=/opt/earthworm
export EW_VERSION=earthworm-7.10
export PATH := $(PATH):$(EW_HOME)/$(EW_VERSION)/bin
export EWBITS := 64
export WARNFLAGS:=-Wall -Wextra -Wno-sign-compare -Wno-unknown-pragmas -Wno-pragmas -Wformat
export GLOBALFLAGS:=-m$(EWBITS) -g -D_LINUX -Dlinux -D_INTEL -D_USE_SCHED -D_USE_PTHREADS -D_USE_TERMIOS -D_FILE_OFFSET_BITS=64 -I$(EW_HOME)/$(EW_VERSION)/include $(WARNFLAGS)
export PLATFORM:=LINUX

export LINK_LIBS:=-lm -lpthread

export CFLAGS:=$(GLOBALFLAGS)
export CXXFLAGS:=$(GLOBALFLAGS)

FC=gfortran
export FC
export FFLAGS:=$(TARGET)-O -g -Wuninitialized -Werror=line-truncation -ffpe-trap=invalid,zero,overflow -fbacktrace

%:
	dh $@ --with javahelper --sourcedirectory=src

clean:
	cd src; make clean_unix; make clean_bin_unix

build:
	cd src; make unix

install: build
	dh_testdir
	dh_testroot
	dh_prep
	dh_installdirs
	cp -R --parents /opt/earthworm/earthworm-7.10/bin /opt/earthworm/earthworm-7.10/debian/earthworm/
	cp -R --parents /opt/earthworm/earthworm-7.10/doc /opt/earthworm/earthworm-7.10/debian/earthworm/
	cp -R --parents /opt/earthworm/earthworm-7.10/environment /opt/earthworm/earthworm-7.10/debian/earthworm/
	cp -R --parents /opt/earthworm/earthworm-7.10/include /opt/earthworm/earthworm-7.10/debian/earthworm/
	cp -R --parents /opt/earthworm/earthworm-7.10/include_cpp /opt/earthworm/earthworm-7.10/debian/earthworm/
	cp -R --parents /opt/earthworm/earthworm-7.10/lib /opt/earthworm/earthworm-7.10/debian/earthworm/
	cp -R --parents /opt/earthworm/earthworm-7.10/params /opt/earthworm/earthworm-7.10/debian/earthworm/
	cp -R --parents /opt/earthworm/earthworm-7.10/src /opt/earthworm/earthworm-7.10/debian/earthworm/
	cp /opt/earthworm/earthworm-7.10/README.txt /opt/earthworm/earthworm-7.10/debian/earthworm/opt/earthworm/earthworm-7.10/README.txt
	cp /opt/earthworm/earthworm-7.10/help.txt /opt/earthworm/earthworm-7.10/debian/earthworm/opt/earthworm/earthworm-7.10/help.txt
	cp /opt/earthworm/earthworm-7.10/release_notes.working /opt/earthworm/earthworm-7.10/debian/earthworm/opt/earthworm/earthworm-7.10/release_notes.v7.10
	mkdir /opt/earthworm/earthworm-7.10/debian/earthworm/opt/earthworm/earthworm-7.10/debian
	cp /opt/earthworm/earthworm-7.10/debian/changelog /opt/earthworm/earthworm-7.10/debian/earthworm/opt/earthworm/earthworm-7.10/debian/changelog
	cp /opt/earthworm/earthworm-7.10/debian/compat /opt/earthworm/earthworm-7.10/debian/earthworm/opt/earthworm/earthworm-7.10/debian/compat
	cp /opt/earthworm/earthworm-7.10/debian/control /opt/earthworm/earthworm-7.10/debian/earthworm/opt/earthworm/earthworm-7.10/debian/control
	cp /opt/earthworm/earthworm-7.10/debian/copyright /opt/earthworm/earthworm-7.10/debian/earthworm/opt/earthworm/earthworm-7.10/debian/copyright
	cp /opt/earthworm/earthworm-7.10/debian/rules /opt/earthworm/earthworm-7.10/debian/earthworm/opt/earthworm/earthworm-7.10/debian/rules

binary: build install
	dh_testdir
	dh_testroot
	dh_installdebconf
	dh_installinfo -a
	dh_link
	dh_strip
	dh_fixperms
	dh_installdeb
	dh_gencontrol
	dh_md5sums
	dh_builddeb

Normally, when we build or run Earthworm, we source a shell script containing environment variables in order to set up the environment appropriately. In the case of this particular rules file, we can see that is done at the top of the file.

After the initialization of the environment, we have the following sections: clean, build, install, and binary. Upon close inspection, we can see that install actually references build, and binary calls both build and install.

Building the Debian package

First, make sure the Earthworm repository you are building does not contain any binaries, which may end up being copied over to the Debian package we are creating and will prevent us from creating our Debian package. Ideally, you will be attempting to build and package a new checkout of the Earthworm repository, but if not, make sure to run 'make clean_unix' and 'make clean_bin_unix' after sourcing the appropriate environmental variables for the EW installation.

Before running any of the commands listed below, make sure you are in the top-level Earthworm directory, with debian as a subdirectory

Next, check the documentation for the tool debchange via man debchange. Use debchange to update the changelog as appropriate

Next, we will build the Debian package using the following two commands:

fakeroot debian/rules clean
fakeroot debian/rules binary

NOTE: If you look up the official build documentation located at ​https://www.debian.org/doc/manuals/maint-guide/build.en.html, you will see other build tools recommended such as dpkg-buildpackage, which is a wrapper for the previous two commands as well as some other commands. You may have further work to do if your goal is to use this tool instead of the build process listed above, which has been confirmed to work.

Installing the Debian package(s)

Run

sudo apt install earthworm_7.10-1ubuntu2_amd64.deb

to install the standard binary package (NOTE: the name of your package will change according to the version number specified in the debian/ directory)

If desired, a 'debug' package may also be installed to make symbol information available when running a process under a debugger (such as GDB). This is optional, and could be used to debug an issue with binaries provided with a particular package:

sudo apt install earthworm-dbgsym_7.10-1ubuntu2_amd64.ddeb

(Again, the exact package name will vary according to the version number, but there should be a an obvious correlation to the name of the 'standard' binary package)

More Information

Official documentation provided for Debian package maintainers may be found here: ​https://www.debian.org/doc/manuals/maint-guide/start.en.html