Cabal-hooks/readme.md

   1 # `Cabal-hooks`\r
   2 \r
   3 This library provides an API for the `Cabal` `Hooks` build type.\r
   4 \r
   5 ## What is the `Hooks` build type?\r
   6 \r
   7 The `Hooks` build type is a new `Cabal` build type that is scheduled to\r
   8 replace the `Custom` build type, providing better integration with\r
   9 the rest of the Haskell ecosystem.\r
  10 \r
  11 The original specification for the `Hooks` build type can be found in\r
  12 the associated [Haskell Foundation Tech Proposal](https://github.com/haskellfoundation/tech-proposals/pull/60).\r
  13 \r
  14 These *setup hooks* allow package authors to customise the configuration and\r
  15 building of a package by providing certain hooks that get folded into the\r
  16 general package configuration and building logic within `Cabal`.\r
  17 \r
  18 ## Defining a package with custom hooks\r
  19 \r
  20 To use the `Hooks` build type, you will need to\r
  21 \r
  22   * Update your `.cabal` file by:\r
  23 \r
  24       - using `cabal-version >= 3.14`,\r
  25       - declaring `build-type: Hooks`,\r
  26       - declaring a `custom-setup` stanza, with a `setup-depends`\r
  27         field which includes a dependency on `Cabal-hooks`.\r
  28   \r
  29   * Define a Haskell module `SetupHooks`, which must be placed\r
  30     at the root of your project and must define a value\r
  31     `setupHooks :: SetupHooks`.\r
  32 \r
  33 That is, your `.cabal` file should contain the following\r
  34 \r
  35 ```cabal\r
  36 -- my-package.cabal\r
  37 cabal-version: 3.14\r
  38 name: my-package\r
  39 build-type: Hooks\r
  40 \r
  41 custom-setup\r
  42   setup-depends:\r
  43     Cabal-hooks >= 0.1 && < 0.2\r
  44 ```\r
  45 \r
  46 and your `SetupHooks.hs` file should look like:\r
  47 \r
  48 ```haskell\r
  49 -- SetupHooks.hs\r
  50 module SetupHooks ( setupHooks ) where\r
  51 \r
  52 -- Cabal-hooks\r
  53 import Distribution.Simple.SetupHooks\r
  54 \r
  55 setupHooks :: SetupHooks\r
  56 setupHooks = ...\r
  57   -- use the API provided by 'Distribution.Simple.SetupHooks'\r
  58   -- to define the hooks relevant to your package\r
  59 ```\r
  60 \r
  61 ## Using the API\r
  62 \r
  63 The [Haddock documentation](https://hackage.haskell.org/package/Cabal-hooks)\r
  64 should help you get started using this library's API.\r