Commit 0cdc5a8d authored by Michael Hanke's avatar Michael Hanke

More docs.

parent 6bef4c55
......@@ -4,6 +4,7 @@ set -e
set -u
# init
version='0.0.13'
scriptname=$(basename $0)
mode=""
build_cmd=""
......@@ -17,7 +18,30 @@ makefile_mode=0
print_description()
{
cat << EOT
$scriptname is a helper to build MEX extensions on Debian systems.
The is a small helper that eases building and installing MEX extensions for
Matlab toolbox packages in Debian binary packages. Because these packages
cannot build-depend on Matlab (for obvious reasons) they need to compile their
extensions at installation time using a local Matlab installation. The helper
is somewhat flexible by supporting custom build, install and clean commands, as
well as source and destination directories. It also deals with moving
extensions into library directories and automatically symlinks them into the
toolbox directory.
There are two major modes: 'install' to build, install and symlink extensions
(useful in postinst) and 'clean' to remove installed extensions and symlinks
(useful in prerm).
The command to build the extensions is invoked in the source directory. By
default, this is /usr/src/matlab/<package name>, but can be overridden with
the --src-dir option. Any optional 'install' (--install-cmd) and 'clean'
(--clean-cmd) are invoked in the source directory too.
Moreover, this helper will also take any installed extensions from a default
installation path /usr/share/matlab/site/m/<package name>, move them into
/usr/lib/matlab/site/<package name> and symlink back to the original location.
These locations can be configured with the --m-dir and --mex-dir options
respectively. Again, this step is optional and is only performed if a package
actually installs extensions inot this location.
EOT
}
......@@ -26,14 +50,15 @@ EOT
print_version()
{
cat << EOT
$scriptname
$scriptname $version
Copyright (C) 2010 Michael Hanke <michael.hanke@gmail.com>
Copyright (C) 2010-2011 Michael Hanke <michael.hanke@gmail.com>
Licensed under GNU Public License version 3 or later.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Written by Michael Hanke.
EOT
}
......@@ -42,32 +67,12 @@ print_help()
cat << EOT
Usage: $scriptname [OPTIONS] <package name> <mode>
The is a small helper that eases building and installing MEX extensions for
Matlab toolbox packages. These packages need to compile their extensions at
installation time. The helper is somewhat flexible by supporting custom
build, install and clean commands, well as source and destination directories.
It also deals with moving extensions into library directories and automatically
symlinks them into the toolbox directory.
There are two major modes: 'install' to build, install and symlink extensions
(useful in postinst) and 'clean' to remove installed extensions and symlinks
(useful in prerm).
The command to build the extensions is invoked in the source directory. By
default, this is /usr/src/matlab/<package name>, but can be overridden with
the --src-dir option. Any optional 'install' (--install-cmd) and 'clean'
(--clean-cmd) are invoked in the source directory too.
Moreover, this helper will also take any installed extensions from a default
installation path /usr/share/matlab/site/m/<package name>, move them into
/usr/lib/matlab/site/<package name> and symlink back to the original location.
These locations can be configured with the --m-dir and --mex-dir options
respectively.
Options:
-h, --help
Print short description and usage summary.
-h
Print usage summary and option list.
--help
Print full help.
--version
Print version information and exit.
......@@ -96,9 +101,49 @@ Options:
Set default commands for 'build-cmd' (make), 'install-cmd'
(make install DESTDIR=\$m_dir) and 'clean-cmd' (make distclean) if no
specific command has been provided via the respective options.
EOT
}
print_examples()
{
cat << EOT
Examples:
The following call can be used in a package's postinst script if it comes with
a Matlab script 'build_matlab.m' that builds and installs its extension into
the desired locations. The --src-dir option is used to point to a non-standard
location of the extension sources.
debian-matlab-mexhelper somepackagename install \
--src-dir /usr/src/dynare-matlab/mex/sources \
--build-cmd 'matlab -nodesktop -nodisplay -nojvm -r build_matlab'
If a package installs extension sources into the standard location and builds
its extensions using a Makefile that support the DESTDIR for installing the
built extensions and a 'distclean' target it is sufficient to run the
following.
debian-matlab-mexhelper somepackagename install --make
Otherwise it is also possible to fully customize all commands.
debian-matlab-mexhelper difficultpackage install \
--build-cmd 'make -C src all toolbox MEXBIN="matlab-mex"' \
--install-cmd 'make -C src install && find . ! -wholename "./src" -name "*.mex?*" -print0 | xargs -0 -I {} cp -v --parent {} /usr/share/difficultpackage' \
--clean-cmd 'make -C src distclean toolbox-distclean && find . -name "*.mex?*" -delete'
If a package uses $scriptname to install extensions into the standard location
it can also be used to remove all MEX extensions and created symlinks when a
package is removed from a system. To achieve this simply put the following call
into a package's prerm script.
debian-matlab-mexhelper packagename clean
EOT
}
# Parse commandline options (taken from the getopt examples from the Debian util-linux package)
# Note that we use `"$@"' to let each command-line parameter expand to a
# separate word. The quotes around `$@' are essential!
......@@ -115,7 +160,8 @@ eval set -- "$CLOPTS"
while true ; do
case "$1" in
-h|--help) print_description; print_help; exit 0;;
-h) print_help; exit 0;;
--help) print_description; print_help; print_examples; exit 0;;
--version) print_version; exit 0;;
--build-cmd) shift; build_cmd=$1; shift;;
--install-cmd) shift; install_cmd=$1; shift;;
......
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' 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-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 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 adaptor 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 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.
......@@ -9,8 +9,10 @@ matlab (0.0.13) unstable; urgency=low
* Do not attempt to move MEX extensions from the M-DIR into the MEX-DIR
if they were not installed into the intended locations.
* Add runtime dependency on sudo.
* Improve documentation: Added examples to manpage, added README.Developers
for package maintainers.
-- Michael Hanke <mih@debian.org> Mon, 03 Jan 2011 20:34:51 -0500
-- Michael Hanke <mih@debian.org> Tue, 04 Jan 2011 10:12:42 -0500
matlab (0.0.12) unstable; urgency=low
......@@ -94,14 +96,14 @@ matlab (0.0.3) UNRELEASED; urgency=low
-- Michael Hanke <michael.hanke@gmail.com> Sat, 20 Nov 2010 09:22:59 -0500
matlab (0.0.2) UNRELEASEDe; urgency=low
matlab (0.0.2) UNRELEASED; urgency=low
* ENH: revert to calling matlab to figure out its version if bin/mex
lacks that information (necessary for older Matlabs such as R12.1)
-- Yaroslav Halchenko <debian@onerussian.com> Thu, 28 Oct 2010 17:15:27 -0400
matlab (0.0.1) UNRELEASEDe; urgency=low
matlab (0.0.1) UNRELEASED; urgency=low
* Initial release.
* Add package conflict to 'texlive-lang-polish' that also provides
......
debian/README.Developers
debian/README.Developers
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment