Converting source packages for use with Hugs
============================================

(Unix-like environments only)

Though Hugs does not uses packages directly, source packages that
work with the compilers may be converted for use with Hugs using the
hugs-package script.  This script is used while building Hugs to convert
several packages under fptools/libraries and can also be used on any
package directory with the expected structure (see below).  To add a
package to your installation, say

	hugs-package pkg-dir

To put a converted package in another directory (e.g. for bundling
the package), say

	hugs-package pkg-dir target-dir

The script uses the environment variable HUGSDIR in a similar way to Hugs.
Other environment variables that may be set are CC, cpp, hsc2hs, greencard,
ffihugs and runhugs, all naming programs.

Package directory structure
---------------------------

A package directory is assumed to contain a directory hierarchy
reflecting the module hierarchy, e.g. with module A.B.C in the source
file <package-directory>/A/B/C.hs and so on.  The following filename
suffixes are recognized:

.hs or .lhs
	Haskell source, to be sent through the C preprocessor with
	__HUGS__ defined.  The file may also #include HsFFi.h, config.h,
	MachDeps.h and any header files in <package-directory>/include
.y or .ly
	Happy source, to be processed with happy with the result sent
	through the C preprocessor as above.
.hsc
	input for hsc2hs and then the C preprocessor.
	(If NAME_hsc_make.c, the output of hsc2hs --no-compile, is present,
	it will be used instead.)
.gc
	input for GreenCard.

In addition to Haskell source modules, the package directory may
optionally contain the following:

cbits/
	a directory containing C source files to be linked with Haskell
	files by ffihugs.
include/
	a directory of C header files used by foreign declarations and
	files in cbits.
hugs/exclude
	a list of names of modules to be skipped by the conversion script.
	(Only the first word in each line is used, and blank lines and
	lines starting with # are ignored, leaving room for explanations.)
package.conf.in
	a package configuration file, to be preprocessed with cpp.
	The script uses the extra_libraries and extra_ld_opts fields.
	(It should also follow dependencies, but doesn't yet.)
package.conf
	a package configuration file (not to be preprocessed).

The conversion script runs ffihugs where required.  It sets the include
path, and also adds auxiliary files generated by hsc2hs and GreenCard.
C files from cbits required by a module may be specified with a CBITS
"pragma" in the source file:

	{-# CBITS file.c another.c #-}
