Configuration.Utils.Setup

This module contains a Setup.hs script that hooks into the cabal build process at the end of the configuration phase and generates a module with package information for each component of the cabal package.

The modules are created in the autogen build directory where also the Path_ module is created by cabal's simple build setup. This is usually the directory ./dist/build/autogen.

For a library component the module is named just PkgInfo. For all other components the module is named PkgInfo_COMPONENT_NAME where COMPONENT_NAME is the name of the component with - characters replaced by _.

For instance, if a cabal package contains a library and an executable that is called my-app, the following modules are created: PkgInfo and PkgInfo_my_app.

Usage as Setup Script

There are three ways how this module can be used:

1. Copy the code of this module into a file called Setup.hs in the root directory of your package.

2. If the configuration-tools package is already installed in the system where the build is done, following code can be used as Setup.hs script:

   module Main (main) where
   
   import Configuration.Utils.Setup

3. For usage within a more complex Setup.hs script you shall import this module qualified and use the mkPkgInfoModules function. For example:

   module Main (main) where
   
   import qualified Configuration.Utils.Setup as ConfTools
   
   main :: IO ()
   main = defaultMainWithHooks (ConfTools.mkPkgInfoModules simpleUserHooks)
   

With all methods the field Build-Type in the package description (cabal) file must be set to Custom:

Build-Type: Custom

Integration With Configuration.Utils

You can integrate the information provided by the PkgInfo modules with the command line interface of an application by importing the respective module for the component and using the runWithPkgInfoConfiguration function from the module Configuration.Utils as show in the following example:

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE FlexibleInstances #-}

module Main
( main
) where

import Configuration.Utils
import PkgInfo

instance FromJSON (() -> ()) where parseJSON _ = pure id

mainInfo :: ProgramInfo ()
mainInfo = programInfo "Hello World" (pure id) ()

main :: IO ()
main = runWithPkgInfoConfiguration mainInfo pkgInfo . const $ putStrLn "hello world"

With that the resulting application supports the following additional command line options:

--version, -v

prints the version of the application and exits.

--info, -i

prints a short info message for the application and exits.

--long-info

print a detailed info message for the application and exits. Beside component name, package name, version, revision, and copyright the message also contain information about the compiler that was used for the build, the build architecture, build flags, the author, the license type, and a list of all direct and indirect dependencies along with their licenses and copyrights.

--license

prints the text of the lincense of the application and exits.

Documentation

main :: IO ()

Include this function when your setup doesn't contain any extra functionality.

mkPkgInfoModules :: UserHooks -> UserHooks

Modifies the given record of hooks by adding functionality that creates a package info module for each component of the cabal package.

This function is intended for usage in more complex Setup.hs scripts. If your setup doesn't contain any other function you can just import the main function from this module.

The modules are created in the autogen build directory where also the Path_ module is created by cabal's simple build setup. This is usually the directory ./dist/build/autogen.

For a library component the module is named just PkgInfo. For all other components the module is named PkgInfo_COMPONENT_NAME where COMPONENT_NAME is the name of the component with - characters replaced by _.