logfloat-0.13.0.1: INSTALL

logfloat-0.12
=============

In general, logfloat is a simple package and should be easy to
install. The specifics are a bit murky however, since we use CPP
and the FFI and want to retain portability, and due to the rapid
evolution of Cabal and other development tools. This document will
walk you through the ins and outs for all supported configurations.

If you run into issues about missing <math.h> or similar, then see
the FFI Problems section. If you want to compile Haddock documentation,
then see that section.


Building for GHC (6.8 and above)
================================

Installation under GHC is simple using the standard Cabal build
loop:

    runhaskell Setup.hs configure
    runhaskell Setup.hs build
    runhaskell Setup.hs copy
    runhaskell Setup.hs register

The logfloat package is no longer supported for GHC 6.6, though it
could probably be made to work with it by changing LANGUAGE pragma
into the appropriate OPTIONS_GHC equivalents. Since it's not supported
anymore, more significant changes may have become necessary as well.


Building for Hugs (September 2006)
==================================

Installation under Hugs is unfortunately more complicated due to
some option-passing bugs in Cabal. You should be able to build
things with these modifications to the usual Cabal build loop:

    runhaskell Setup.hs configure --hugs  \
        --with-cpphs="`which cpphs-hugs`" \
        --ffihugs-options="-98 +o"        \
        --ffihugs-option=-F'cpp -P -traditional -D__HUGS__=200609 -D__USE_FFI__'
    runhaskell Setup.hs build
    runhaskell Setup.hs copy
    runhaskell Setup.hs register

Hugs installs cpphs under the name "cpphs-hugs" by default. The
`which` command will try to resolve the location, assuming it's on
your $PATH. If it isn't, then change the --with-cpphs= flag to point
to where cpphs is installed on your system.

Some additional details about difficulties with building
for Hugs can be found in this blog post and the bug reports:

    http://winterkoninkje.livejournal.com/60707.html
    http://hackage.haskell.org/trac/hackage/ticket/526
    http://hackage.haskell.org/trac/hackage/ticket/527

And while previous versions of Cabal could build this package (with
the above commandline to work around those bugs), Hugs support is
broken in Cabal 1.8 (including at least 1.8.0.2 through 1.8.0.6):

    http://hackage.haskell.org/trac/hackage/ticket/633


FFI Problems
============

The logfloat package uses the FFI to access functions in libm to
improve accuracy. These functions are part of the ISO C 1999 standard
and are supported on most systems, however they're not part of the
ANSI C standard nor the System V standard and so they might be
unavailable on some systems. If you encounter errors during build
about not being able to find <math.h>, not having prototypes for
functions, or linking errors, then you are probably on such a system.

In order to use pure Haskell and disable the FFI, pass -f-useFFI
during the configure phase to disable the useFFI flag. (If compiling
for Hugs, also be sure *not* to pass -D__USE_FFI__ to the cpp filter
for ffihugs.) This will degrade the accuracy of certain operations,
but should still compile cleanly.

If you run into errors like "error: 'log1p' redeclared as different
kind of symbol" this is due to a bug in GHC 6.10.1 where you can't
use both -fvia-C and the FFI. This bug should be circumvented for
the moment, but resolving it is still a work in progress. See the
bug report (which is resolved in GHC 6.10.2):

    http://hackage.haskell.org/trac/ghc/ticket/3117


Windows FFI
===========

The logfloat package builds and installs cleanly on Windows XP using
GHC 6.10.1 (without needing Cygwin nor Mingw/Msys). The C functions
reside in libmingwex.a which is bundled with GHC on WinXP.

However, it does not work from the GHCi debugger and gives errors
like "can't load .so/.DLL for: m (addDLL: could not load DLL)". If
you know how to fix this issue or have further details on Windows
compatability, please contact the maintainer.


Haddock Documentation
=====================

In Cabal 1.2 there is a bug in the handling of building Haddock
documentation when CPP is involved. These issues have been fixed
in Cabal 1.6, but here are the instructions if you're on older
systems.

In Cabal 1.2 the cpp-options field is not passed to Haddock, and
therefore any macros defined there are not seen, which can cause
Haddock to fail. The old workaround was to define CPP macros in the
ghc-options field which *does* get passed to Haddock. This is now
considered bad style and is forbidden by Hackage. It appears that
passing --haddock-option=... or --ghc-option=... flags during
configure does not have the same effect as defining the field.

Therefore, in order to properly compile Haddock documentation on
Cabal 1.2, you should go into logfloat.cabal and uncomment the
ghc-options fields which declare CPP macros -D__USE_FFI__ and
-D__HUGS__=200609. If you know of a better workaround for this
configuration, contact the maintainer.