## Adding libraries to hslibs

The GHC Team

    glasgow-haskell-&lcub;users,bugs&rcub;@dcs.gla.ac.uk

January 2000

## How to add a library

The main `hslibs` directory contains a subdirectory for each set of libraries. Each library directory should contain:

The source code

  Haskell files in the main directory, and C files in a `cbits` subdirectory (this should exist whether or not you actually have any C source). In a large library, the Haskell code may also be placed in subdirectories.

Documentation

  In the `doc` directory, preferably in DocBook format. See for more details.

A `Makefile`

  This should have the following format:

      # -----------------------------------------------------------------------------=
      # $Id: newlib.sgml,v 1.3 2001/07/05 13:01:15 rrt Exp $
      #
      # (c) The Furballs 2005
      #

      TOP = ..
      include $(TOP)/mk/boilerplate.mk

      PACKAGE = foo
      PACKAGE_DEPS = bar baz
      HAS_CBITS = YES
      SRCS_FROM_SUBDIRS = wibble

      EXTRA_CIA_OPTS += -fwarn-martian-invasions

      include $(TOP)/mk/target.mk

  The first two lines and last line are standard boilerplate. In between come the name of the library, other hslibs it needs, and whether it contains a C sub-library (in the `cbits` directory). Next comes a list of any subdirectories with Haskell source in, and finally, a list of any special compiler options that might be needed (see the building guide for the full mind-numbing range of implausibly useful things you can do here).

A cbits `Makefile`

  (In the `cbits` directory.) This should look like:

      # -----------------------------------------------------------------------------
      # $Id: newlib.sgml,v 1.3 2001/07/05 13:01:15 rrt Exp $
      #
      # (c) The Furballs 2005
      #

      TOP=../..
      include $(TOP)/mk/boilerplate.mk

      PACKAGE=lang
      IS_CBITS_LIB=YES

      ifeq "$(TARGETPLATFORM)" "i386-unknown-cygwin32"
      C_SRCS += .secret/Propaganda.c
      endif

      include $(TOP)/mk/target.mk

  As before, the first two lines and last lines are standard boilerplate to plumb in the rest of the build system. The setting of `PACKAGE` should be the same as for the parent directory, and `IS_CBITS_LIB` should be set to `YES`; after that come any special settings.

## How to add documentation for a library

Each library's directory should contain a `doc` subdirectory. The main documentation file should be called `lib.sgml` where `lib` is the name of the library directory.

To add documentation for a library to the main library manual, some new lines must be spliced into the top-level file `hslibs/doc/hslibs.sgml`. First, the library directory needs a line in the list of directories at the top of the file, of the form

    <!ENTITY text SYSTEM "../text/doc/lib.sgml" >

Next, if the documentation for the library is split up over several files, a new section needs to be added to the bottom of the DTD declaration of `hslibs.sgml`, along the lines of

    <!-- lib -->
            <!ENTITY sub1            SYSTEM "../lib/doc/sub1.sgml">
            <!ENTITY sub2            SYSTEM "../lib/doc/sub2.sgml">
            ...

Finally, the library needs to be referenced by its entity name in the body of `hslibs.sgml`, as `&lib`.

## A template for library documentation

At the moment, there is no standard form for libraries' documentation. The only requirement is that each should be a chapter: that is, the main file `lib.sgml` should not have a DTD line at the top, but start with `Chapter` and end with `Chapter`.