# Debhelper-based infrastructure for building Octave add-on packages

## Introduction

This package (dh-octave) contains the infrastructure for building
add-on packages for Octave which use the mechanism in pkg.m.  This is
particularly the case of the [Octave-Forge][1] packages.

dh-octave is completely based on [Debhelper][2].  It contains scripts
for automation of the building, the installation, the checking and the
cleaning of the add-on package.  It also generates the appropriate
substitution variables for use in `debian/control`.

[1]: https://octave.sourceforge.io/
[2]: https://github.com/Debian/debhelper

## Usage

For a basic usage of dh-octave, this is the minimal `debian/rules`
file:

```make
#!/usr/bin/make -f
# -*- makefile -*-

%:
	dh $@ --buildsystem=octave --with=octave
```

For executing actions beyond the ones of `pkg install`, the
following Debhelper targets can be used:

- override_dh_auto_build
- override_dh_auto_install
- override_dh_auto_clean

For fine tuning the execution of the unit tests, the following
environment variables are available:

- `DH_OCTAVE_TEST_ENV`

    The value of this variable is prepended to the `octave` command
    used for running the unit tests.  For instance, one can set its
    value to `LD_PRELOAD=` in order to prevent the tests from being
    run in a fakeroot environment.  It can also be another command,
    like 'xfvb-run`.

- `DH_OCTAVE_TEST_OPT`

    This variable alter the behavior of the tests.  Possible values
    are `quiet`, `normal`, and `verbose` (the later is the default).

- `DH_OCTAVE_EXCLUDE_TEST`

    This variable can be used to prevent the execution of certain unit
    tests.  It should contain a space-separated list of file names
    (`*.m` or `*.cc`) for which the unit tests should not be run.

## Building a Debian package from scratch

`dh_octave_make` is a helper script for generating a first version of
a Debian package for an Octave-Forge package.  The command should be
launched from the top directory of the unpacked sources of an
Octave-Forge packages.  A file called `DESCRIPTION` must be present,
from which information about the package is gathered.
`dh_octave_make` generated the the `debian/*` with sensible contents,
although they need further editing.

## Internals of dh-octave

The dh-octave package adds a new buildsystem to the Debhelper system
through the file `buildsystem.pm`.  In this file, the `install` and
`clean` targets of Debhelper are redefined.  Notice that there is no
`build` target in that file, since the building *and* the installation
are done in the `install` target, by running the code in the Octave
script `/usr/share/dh-octave/install-pkg.m`.

The dh-octave package also alters the sequence of Debhelepr commands
through the file `sequence.pm`.  It inserts calls to the `dh_octave_*`
commands in the appropriate places, namely:

| Debhelper target       | where  | dh-octave command      |
| ---------------------- | ------ | ---------------------- |
| `dh_auto_configure`    | before | `dh_octave_version`    |
| `dh_auto_install`      | after  | `dh_octave_check`      |
| `dh_install`           | after  | `dh_octave_substvar`   |
| `dh_installchangelogs` | after  | `dh_octave_changelogs` |

Notice that the commands above are not meant to be called directly by
the user, but are active through the option `--with=octave` of `dh` in
`debian/rules`.