project-cabal/README.md

   1 # Cabal Projects
   2
   3 We have these projects, all in the root:
   4
   5 ```
   6 $ tree -P '*.project' --prune -L 1
   7 .
   8 ├── cabal.bootstrap.project
   9 ├── cabal.meta.project
  10 ├── cabal.project
  11 ├── cabal.release.project
  12 ├── cabal.validate-libonly.project
  13 └── cabal.validate.project
  14 ```
  15
  16 Projects are expected to pass a `build --dry-run` standalone test,
  17 substituting the actual project filename for `cabal.project` in
  18 `--project-file=cabal.project`:
  19
  20 ```
  21 $ cabal build all --enable-tests --enable-benchmarks --dry-run \
  22   --project-file=cabal.project
  23 ```
  24
  25 The `release` project might fail to resolve dependencies with the latest GHC
  26 compiler with its `index-state` pinned but it should build if unpinned, by
  27 removing `index-state` from the project or setting it to `HEAD`:
  28
  29 ```
  30 $ cabal build all --enable-tests --enable-benchmarks \
  31   --project-file=cabal.project.release \
  32   --index-state="hackage.haskell.org HEAD"
  33 ```
  34
  35 ## Configuration
  36
  37 Any project configuration that is not itself a project should use a `.config`
  38 extension and be put into the `project-cabal` folder:
  39
  40 ```
  41 $ tree -P '*.config' project-cabal
  42 project-cabal
  43 ├── constraints.config
  44 ├── ghc-latest.config
  45 ├── ghc-options.config
  46 ├── pkgs
  47 │   ├── benchmarks.config
  48 │   ├── buildinfo.config
  49 │   ├── cabal.config
  50 │   ├── install.config
  51 │   ├── integration-tests.config
  52 │   └── tests.config
  53 └── pkgs.config
  54
  55 2 directories, 10 files
  56 ```
  57
  58 ## Package Groups
  59
  60 We have one `project-cabal/pkgs.config` that includes all package groups.
  61
  62 ```
  63 $ cat project-cabal/pkgs.config
  64 import: pkgs/cabal.config
  65 import: pkgs/install.config
  66 import: pkgs/buildinfo.config
  67 import: pkgs/tests.config
  68 import: pkgs/integration-tests.config
  69 import: pkgs/benchmarks.config
  70 ```
  71
  72 The default and `validate` projects get their packages this way. The `libonly`,
  73 and `validate.libonly` projects import packages from `cabal` and `tests` package
  74 groups. The `release` project also does this but also imports the `install`
  75 package group.
  76
  77 | Project          | pkgs | cabal | tests | install |
  78 |------------------|:---: |:---:  |:---:  |:---:    |
  79 | default          | ✓    |       |       |         |
  80 | libonly          |      | ✓     | ✓     |         |
  81 | release          |      | ✓     | ✓     | ✓       |
  82 | validate         | ✓    |       |       |         |
  83 | validate.libonly |      | ✓     | ✓     |         |
  84
  85 The `meta` project is a one-liner:
  86
  87 ```
  88 $ cat cabal.meta.project
  89 packages: cabal-dev-scripts
  90 ```
  91
  92 ## Extra Config
  93
  94 Additional configuration is imported:
  95
  96 | Project          | ghc-options | ghc-latest | constraints |
  97 |------------------|:---:        |:---:       |:---:        |
  98 | default          | ✓           | ✓          | ✓           |
  99 | libonly          | ✓           |            |             |
 100 | release          |             |            |             |
 101 | validate         | ✓           | ✓          | ✓           |
 102 | validate.libonly | ✓           |            | ✓           |