# 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 uses the mechanism provided by
Octave's `pkg.m`.  This is particularly true for the
add-ons hosted at [Octave Packages][1].

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

[1]: https://gnu-octave.github.io/packages/
[2]: https://salsa.debian.org/debian/debhelper

## Usage

For basic usage of dh-octave, first build-depend on the virtual
package dh-sequence-octave. If a specific feature is needed, add a
versioned dependency on dh-octave. Second, use this is the minimal
`debian/rules` file:

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

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

This will essentially run the Octave command `pkg install` on the top-level
directory of the unpacked sources, as well as some specialized scripts for
installing the appropriate changelog and example files, and computing
substvars relevant to the package being built.

The following Debhelper targets can be used to perform additional actions:

- override_dh_auto_build
- override_dh_auto_install
- override_dh_auto_clean

The environment variables listed below are available for fine-tuning the
execution of the unit tests. They can also be set in the file
`debian/checkvars`, which is sourced by the script `dh_octave_check` and
should be in the shell format (lines containing `VAR=value`).

- `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 alters the behavior of the tests.  Possible values
    are `quiet`, `normal`, and `verbose` (the latter 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`) which specifies the files for which the unit tests should not
    be run.

The following environment variable is used in the `clean-docdir` script:

- `DH_OCTAVE_KEEP_DOC`

    This variable contains a list of documentation file paths, separated by
    spaces, that should be kept in the installed directory
    `/usr/share/octave/packages/<package>-<version>/doc/`. The file paths
    must be relative to this the `doc` directory. By default, only the
    `*.qhc` and `*.qch` files are kept.

## Building a Debian package from scratch

`dh_octave_make` is a helper script used to generate an initial version of
a Debian package for an Octave add-on package.  The command should be
launched from the top directory of the unpacked sources of an
Octave add-on package.  A file called `DESCRIPTION` must be present,
from which information about the package is gathered.
`dh_octave_make` generates the `debian/*` files with sensible
contents, though they typically require further editing.

## Internals of dh-octave

The dh-octave package adds a new build system to the Debhelper system
through the file `buildsystem.pm`. This file redefines the `install` and
`clean` targets of Debhelper. Note 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 Debhelper commands
through the file `sequence.pm`.  It inserts calls to the `dh_octave_*`
commands at the appropriate places, namely:

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

Note that these commands are not intended for direct use by the user.
Instead, they are activated by the build-dependency on dh-sequence-octave
or by using the option `--with=octave` of `dh` in `debian/rules`.
