Foreign.Hoppy.Setup

Implementations of Cabal setup programs for use in packages of generated bindings.

Much like the default Setup.hs that Cabal recommends for packages,

import Distribution.Simple
main = defaultMain

this module provides simplified configuration of packages for generated bindings. Suppose you have a project named foobar that is composed of Cabal packages named "foobar-generator" for the code generator, "foobar-cpp" for the C++ gateway, and "foobar" for the Haskell gateway. The C++ gateway package can use the following code:

import Foreign.Hoppy.Setup (ProjectConfig (..), cppMain)

main =
  cppMain $
  ProjectConfig
  { generatorExecutableName = "foobar-generator"
  , cppPackageName = "foobar-cpp"
  , cppPackagedSourcesLocation = Nothing
  , cppSourcesDir = GenerateInAutogenDir ""
  , hsSourcesDir = GenerateInAutogenDir ""
  }

The Haskell gateway uses the same code, except calling hsMain instead of cppMain. This causes all (C++, Haskell) generated sources to be placed in the "autogen" directories provided by Cabal, which keeps the source directory clean. See the documentation of the fields of ProjectConfig for more information on how to set up your project's build process.

The gateway packages need to set build-type: Custom in their .cabal files to use these setup files.

Documentation

data ProjectConfig

Configuration parameters for a project using Hoppy.

Constructors

ProjectConfig

Fields

• interfaceResult :: Either String Interface

  The interface to run the generator with. This result is returned from Foreign.Hoppy.Generator.Spec.interface and some may have failed; the string is a message indicating the problem.

• cppPackageName :: String

  The name of the C++ gateway package.

  When using separate Cabal packages for the C++ and Haskell gateway packages, this must be nonempty. When using a single combined gateway package with combinedMain, this must be empty.

• cppPackagedSourcesLocation :: Maybe FilePath

  If the C++ gateway package includes C++ files needed for compliation (either sources or headers), then this should point to the base directory holding these files, relative to the root of the project. The project root itself may be specified with Just "".

  When present, this is passed to the C++ package's makefile in the environment variable HOPPY_CPP_PKG_DIR. A value of Just "" is passed with HOPPY_CPP_PKG_DIR set to the base directory of the Cabal package (equivalent to Just ".").

  This is also added automatically as a system include path (i.e. gcc -I) for the C++ compiler when compiling the test program for enum autodetection.

• cppGeneratedSourcesLocation :: GenerateLocation

  Specifies the directory where C++ sources will be generated.

  This is passed to the C++ package's makefile in the environment variable HOPPY_CPP_GEN_DIR.

data GenerateLocation

Where to generate sources for binding packages.

Constructors

GenerateInAutogenDir FilePath

Generate sources in the package's autogen directory provided by Cabal. This is preferrable as it keeps the source directory clean.

Sources are generated below the given FilePath if nonempty, otherwise sources are generated directly in the autogen directory.

GenerateInSourcesDir FilePath

Generate sources in the package's root source directory, i.e. the directory with the .cabal file.

Sources are generated below the given FilePath if nonempty, otherwise sources are generated directly in the root directory.

combinedMain :: ProjectConfig -> IO ()

A main implementation to be used in the Setup.hs of a single Hoppy binding package that combined both the C++ and Haskell gateway code in one package.

combinedMain project = defaultMainWithHooks $ combinedUserHooks project

combinedUserHooks :: ProjectConfig -> UserHooks

Cabal user hooks for a combined gateway package. When overriding overriding fields in the result, be sure to call the previous hook.

The following hooks are defined:

• postConf: Runs the generator to generate C++ and Haskell sources.

cppMain :: ProjectConfig -> IO ()

A main implementation to be used in the Setup.hs of a C++ gateway package.

cppMain project = defaultMainWithHooks $ cppUserHooks project

cppUserHooks :: ProjectConfig -> UserHooks

Cabal user hooks for a C++ gateway package. When overriding fields in the result, be sure to call the previous hook.

The following hooks are defined:

• postConf: Runs the generator program to generate C++ sources. Checks if a configure script exists in the C++ gateway root, and calls it if so (without arguments).
• buildHook: Runs make with no arguments from the C++ gateway root.
• copyHook and instHook: Runs make install libdir=$libdir where $libdir is the directory into which to install the built shared library.
• cleanHook: Removes files created by the generator, then calls make clean.

hsMain :: ProjectConfig -> IO ()

A main implementation to be used in the Setup.hs of a Haskell gateway package.

hsMain project = defaultMainWithHooks $ hsUserHooks project

hsUserHooks :: ProjectConfig -> UserHooks

Cabal user hooks for a Haskell gateway package. When overriding fields in the result, be sure to call the previous hook.

The following hooks are defined:

• postConf: Finds the shared library directory for the installed C++ gateway package, and writes this path to a dist/build/hoppy-cpp-libdir file. Runs the generator program to generate Haskell sources.
• preBuild, preTest, preCopy, preInst, preReg: Reads the C++ library directory from dist/build/hoppy-cpp-libdir and adds it to the library search path (extraLibDirs).
• cleanHook: Removes files created by the generator.