Notes for developers
--------------------

If you are working on a package that needs to build MEX extensions for Matlab
you might want to follow the following steps to achieve this with relatively
little effort.

Since an official Debian package cannot build-depend on Matlab, MEX extensions
have to be built when a package is installed on a particular system. To
guarantee that a local Matlab is installed, a binary package may simply depend
on the 'matlab-support' package that represents one or more local Matlab
installations in the Debian package management system.

For maximum comfort, install all sources for MEX extensions into

  /usr/src/matlab/<package name>

Analogous to Octave, the 'matlab-support-dev' package ships a little Makefile
snippet defining the MATLAB_MEX_SRCDIR variable that points to
/usr/src/matlab/. The script can be included into debian/rules like this

  include /usr/share/matlab/debian/defs.make

To get the extensions built one needs to add a helper call to the package's
postinst script. Such postinst script might look like this:

-----------------------------------------------------------------------------
#!/bin/sh
set -e

case "$1" in
    configure)
        debian-matlab-mexhelper somepackagename install \
            --build-cmd 'matlab -nodesktop -nodisplay -nojvm -r build_matlab'
    ;;

    abort-upgrade|abort-remove|abort-deconfigure)
    ;;

    *)
        echo "postinst called with unknown argument \`$1'" >&2
        exit 1
    ;;
esac

#DEBHELPER#
-----------------------------------------------------------------------------

The call to 'debian-matlab-mexhelper' is fully customizable for arbitrary
commands to build and install extensions, as well as to clean up the source
tree afterwards. The matlab-support package offers default installation
directories for Matlab MEX extensions and M-files (hence complete toolboxes)
under /usr/lib/matlab/site and /usr/share/matlab/site/m respectively. The
aforementioned Makefile snippet defines the MATLAB_MEX_BINDIR and MATLAB_MDIR
variables that point to these locations. When Matlab toolboxes including MEX
extensions are installed into MATLAB_MDIR the debian-matlab-mexhelper helper
can also automatically move binary extensions to the respective
MATLAB_MEX_BINDIR and symlink them back into the actual installation directory.

Please take a look at the manpage for 'debian-matlab-mexhelper' for a
comprehensive list of options and a number of examples for common use cases.

Because 'debian-matlab-mexhelper' builds and installs extension files, as well
as symlinks (in some cases) this additional content has to be taken care of
separately when removing a package from the system. In this simplest case,
a package maintainer installs extensions into the aforementioned 'standard'
locations and adds a prerm script like this:

-----------------------------------------------------------------------------
#!/bin/sh
set -e

case "$1" in
    remove|upgrade|deconfigure)
        debian-matlab-mexhelper somepackagename clean
    ;;

    failed-upgrade)
    ;;

    *)
        echo "prerm called with unknown argument \`$1'" >&2
        exit 1
    ;;
esac

#DEBHELPER#
-----------------------------------------------------------------------------

Caveats
-------

While the matlab-support package tries to offer some integration of a local
Matlab installation into a Debian system this integration is not and cannot be
complete. For example, if a potentially required license manager is not running
the build process will fail and in turn cause the package installation itself
to fail -- leaving the package broken. A log file will be available for
inspection. The matlab-support package supports building extensions under a
user other than 'root', in case specific permissions for contacting a license
manager are required.

Moreover, Matlab lacks the concept of a 'package' (in contrast to Octave) that
can be used to enable/disable packages at runtime to deal with namespace
collisions. For this reason, no Matlab toolbox (installed by a Debian package)
is automatically added to Matlab's search path. Sysadmins or users have to
perform this final configuration step manually.

For desktop integration, it is known that newer MATLAB are setting WMClass
information based on the version (e.g., "MATLAB R2018b"). Current settings in
matlab.desktop will not work well.
