changelog.d/issue-9702

   1 synopsis: Working directory support for Cabal\r
   2 packages: Cabal-syntax Cabal cabal-install\r
   3 prs: #9718\r
   4 issues: #9702\r
   5 \r
   6 description: {\r
   7 \r
   8 The Cabal library is now able to handle a passed-in working directory, instead\r
   9 of always relying on the current working directory of the parent process.\r
  10 \r
  11 In order to achieve this, the `SymbolicPath` abstraction was fleshed out, and\r
  12 all fields of `PackageDescription` that, if relative, should be interpreted\r
  13 with respect to e.g. the package root, use `SymbolicPath` instead of `FilePath`.\r
  14 \r
  15 This means that many library functions in `Cabal` take an extra argument of type\r
  16 `Maybe (SymbolicPath CWD (Dir "Package))`, which is an optional (relative or\r
  17 absolute) path to the package root (if relative, relative to the current working\r
  18 directory). In addition, many functions that used to manipulate `FilePath`s now\r
  19 manipulate `SymbolicPath`s, require explicit conversion using e.g. `getSymbolicPath`.\r
  20 \r
  21 To illustrate with file searching, the `Cabal` library defines:\r
  22 \r
  23 ```haskell\r
  24 findFileCwd\r
  25   :: forall dir1 dir2 file\r
  26    . Verbosity\r
  27   -> Maybe (SymbolicPath CWD (Dir dir1))\r
  28   -- ^ working directory\r
  29   -> [SymbolicPath dir1 (Dir dir2)]\r
  30   -- ^ search directories\r
  31   -> RelativePath dir2 File\r
  32   -- ^ filename\r
  33   -> IO (SymbolicPath dir1 File)\r
  34 ```\r
  35 \r
  36 See Note [Symbolic paths] in `Distribution.Utils.Path` for further information\r
  37 on the design of this API.\r
  38 }\r
  39 \r