1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
# 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
[Octave-Forge][1] packages.
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://octave.sourceforge.io/
[2]: https://github.com/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-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` 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`.
|
