HFST: Testing Pre-Release Versions–instructions for early adopters

This file describes usage information for early adopters using SVN or pre-release tarballs.

Installation

INSTALL describes the GNU build system in detail. After first download from SVN a generation of autotools files is required::

    autoreconf -i

For later updates, a regeneration is only necessary if the file configure.ac has changed::

    autoreconf

For systems with broken autoreconf utility, such as some versions of mac os x, it may be easier to use the provided script all along::

    ./autogen.sh

When the autotools system has been generated and is intact, the usual::

	./configure

	make

	(as root) make install

should result in a local installation. If you would rather install in e.g. your home directory (or aren't the system administrator), you can tell ./configure::

        ./configure --prefix=$HOME

When installing to $HOME or other non-standard directory, take care that system linker knows where to look for the libraries.

For further installation instruction refer to file ``INSTALL``, which contains the standard installation instructions for GNU autoconf based software.

Dependencies

Compilation requirements:

• For OpenFST backend:
  • OpenFST library version 1.2 or newer must be installed in running system (on MacOS X: 1.2.2 does not compile, 1.2.4 or later does)
  • compiling against OpenFST library and linking may require recent
  • GCC version and pthread and m libraries, check OpenFST site for details
  • to disable OpenFST support, configure switch ``--without-openfst`` may be used
• For SFST backend:
  • the SFST library version 1.4 or newer must be installed in the running system. The library installation of SFST is done by explicit command ``make libinstall``.
  • SFST requires readline and ncurses, check SFST site for details
  • to disable SFST backend, configure switch ``--without-sfst`` may be used
• For foma backend:
  • the foma library version 0.9.13alpha or newer must be installed in the running system. MacOSX note: only the source tarball compiles, the svn version does not compile.
  • foma requires editline, termcap and zlib libraries to compile, check foma site for details
  • to disable foma backend, configure switch ``--without-foma`` may be used
• Versions loaded from version control systems require a relatively new GNU tool-chain to build:
  • autoconf >=2.62,
  • automake >=1.11,
  • libtool >=2.2,
  • >=gettext-0.17.
• GNU tool-chain is also needed with distributed packages if the user wishes to modify Makefile.am or configure.ac files.
  • GNU flex 2.5.35 or compatible and
  • GNU bison 1.31 (2.4 suggested) or compatible
  • flex 2.5.4-2.5.33 will choke on perfectly valid rules used in hfst
  • bison older than 1.31 do not support name-prefix needed for having multiple parsers in one library

Runtime requirements:

• If the executable is dynamically linked (almost always), the operating system must be able to find hfst libraries, and libraries of backends that are dynamically linked.

Testing

A pre-release version of the system should contain a fair amount of bugs, so make sure to discover and report at least a few. Start by doing the autotools' suggested release dance::

   make check

   make installcheck

   make distcheck

it would be quite extraordinary not to have failures in this test suite, since it's rather picky about things and stuff. All in all, still make a note of all failures here and report them to `bug tracking`_ or the `designated bug mail box`_.

After running these automated tests you should have some uncertainty that something might be working, so you can proceed to testing the actual software. For testing you may perform whatever tasks you may want. A suggested test run may be something like::

  hfst-strings2fst -o lexicon.hfst

  cat

  dog

  mouse

  <CTRL-D>

  hfst-regexp2fst -o rules.hfst

  [a:b | c:d | d:e | e:f | g:h | m:n | o:p | s:t | u:v ]* ;

  <CTRL-D>

  hfst-compose -1 lexicon.hfst -2 rules.hfst -o result.hfst

  hfst-fst2strings result.hfst

  hfst-fst2txt rules.hfst

  hfst-summarize lexicon.hfst

Or whatever. Try to vary parameters and see if you can test all tools in all verbose, silent and non-verbose modes for all formats, only by using instructions available in wiki pages, --help pages and man pages.

Reporting bugs

Bugs can be reported via email to `HFST team bug mail address`_, or preferably to `HFST's bug tracking system at sourceforge`_ When reporting, please include at least following:

• version of software used, if command-line tool ``hfst-toolname --version``
• svn revision, ``svn info``
• steps to reproduce, attach or all related files if possible
• information about platform used (e.g. uname -a). Especially if it's Mac OS X, M$ Windows or other obscure system

.. _HFST team bug mail address: hfst-bugs@helsinki.fi

.. _bug tracking: https://sourceforge.net/tracker/?atid=1061990&group_id=224521&func=browse