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

(Unix-like environments only)

Though Hugs does not uses packages directly, source packages as
used by the compilers may be converted for use with Hugs using the
src/unix/convert_package script.  Currently this is only done for
packages under fptools/libraries, but should later be extended to
third-party packages.

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.)
*.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.)
*.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 #-}

Document the conversion script's assumptions about package structure.
Document the conversion script's assumptions about package structure.