|
| 1 | +#+TITLE: Hacking |
| 2 | + |
| 3 | ++ Previous [[./01-Contributors.org][01-Contributors]] |
| 4 | ++ Next ~FIXME~ |
| 5 | + |
| 6 | +* Basic workflow |
| 7 | + |
| 8 | +Entering the development shell using ~nix-shell~ will pull |
| 9 | +in all the dependencies required by all sub-packages. |
| 10 | + |
| 11 | +Both ~default.nix~ and ~shell.nix~ simply import ~<nixpkgs>~ from your |
| 12 | +~NIX_PATH~. If this is by chance broken, try using ~nixpkgs-unstable~ which |
| 13 | +is targeted by our CI, as it is also the basis for ~haskell-updates~ ~nixpkgs~ branch |
| 14 | +where new Hackage packages land. |
| 15 | + |
| 16 | +Not pinning the to specific version of ~nixpkgs~ is intentional so CI can roll |
| 17 | +with the ~unstable~ branch and detect breakage early. |
| 18 | + |
| 19 | +** Using another version of GHC |
| 20 | + |
| 21 | +To use a different version of GHC to the one used |
| 22 | +by your ~pkgs.haskellPackages~, pass, for example ~--argstr compiler ghc963~ |
| 23 | +to either ~nix-shell~ or ~nix-build~ |
| 24 | + |
| 25 | +** ~matrix.nix~ |
| 26 | + |
| 27 | +~nix-build matrix-nix~ can be used to check that all our packages |
| 28 | +built against all supported GHC versions. It pulls the versions |
| 29 | +from [[../.github/workflows/ci.dhall][.github/workflows/ci.dhall]] so there is a single source of truth |
| 30 | +and the compilers don't need to be listed separately again. |
| 31 | + |
| 32 | +* Adding new packages |
| 33 | + |
| 34 | +When adding a new sub-package, following files need to be updated: |
| 35 | ++ ~default.nix~ |
| 36 | ++ ~shell.nix~ |
| 37 | ++ ~cabal.project~ |
| 38 | ++ ~cabal.project.local.ci~ (only if needed) |
| 39 | ++ ~hie.yaml~ |
| 40 | + |
| 41 | +* CI |
| 42 | + |
| 43 | +The GitHub Actions CI uses [[https://github.com/sorki/github-actions-dhall][github-actions-dhall]] and [[../.github/workflows/ci.dhall][.github/workflows/ci.dhall]] |
| 44 | +to generate the [[../.github/workflows/ci.yaml][.github/workflows/ci.yaml]] workflow file |
| 45 | +which does a full matrix build of supported compilers both using ~cabal~ and ~nix~. |
| 46 | + |
| 47 | +** Cachix cache |
| 48 | + |
| 49 | +The CI uses [[https://github.com/cachix/cachix/][cachix]] to not rebuild everything from scratch everytime it runs, it also |
| 50 | +feeds the cache available at https://app.cachix.org/cache/hnix-store which you |
| 51 | +can configure on your system. |
| 52 | + |
| 53 | +** Updating |
| 54 | + |
| 55 | +To update the CI, edit [[../.github/workflows/ci.dhall][.github/workflows/ci.dhall]] and run [[../.github/workflows/ci.sh][.github/workflows/ci.sh]] |
| 56 | +to regenerate the ~yaml~ file. Don't forget to commit both files. |
| 57 | + |
| 58 | +* Changelogs |
| 59 | + |
| 60 | +Since the packages are used by others as dependencies in production environments, |
| 61 | +make sure to add changelog entries for public interface breaking changes. These don't |
| 62 | +need to cover all changes if you are sure that the change only affects packages inside |
| 63 | +~hnix-store~. |
| 64 | + |
| 65 | +* Readmes |
| 66 | + |
| 67 | +Some ~README.md~ files are symlinked to ~README.lhs~ files and also serve as a buildable executables. |
| 68 | +This makes sure they are always up to date and buildable. They are guarded by cabal flags |
| 69 | +and only available in development environment which enables all of them via [[../cabal.project][cabal.project]], which |
| 70 | +also causes them to be built by CI but not to propagate downstream (and polute ~$PATH~ of downstream users). |
| 71 | + |
| 72 | +* ~ghcid~ |
| 73 | + |
| 74 | +~ghcid~ can be used as a lightweight IDE to assist with edit-compile-run-test cycle. You can obtain it quickly using |
| 75 | +~nix-shell -p haskellPackages.ghcid~ |
| 76 | + |
| 77 | +** Running |
| 78 | +*** For a single library |
| 79 | + |
| 80 | +#+begin_src shell |
| 81 | +ghcid -c 'cabal repl hnix-store-core' |
| 82 | +#+end_src |
| 83 | + |
| 84 | +*** For a testsuite or executable |
| 85 | + |
| 86 | +#+begin_src shell |
| 87 | +ghcid -c 'cabal repl test-suite:props' |
| 88 | +# or |
| 89 | +ghcid -c 'cabal repl exe:db-readme' |
| 90 | +#+end_src |
| 91 | + |
| 92 | +Often the specifier like ~exe~ or ~test-suite~ can be omitted when the name is unique. |
| 93 | + |
| 94 | +*** Running a testsuite after a build |
| 95 | + |
| 96 | +If working with the testsuite directly, you can invoke |
| 97 | +#+begin_src shell |
| 98 | +ghcid -c 'cabal repl test-suite:remote' --test 'hspec spec' |
| 99 | +#+end_src |
| 100 | + |
| 101 | +If you are editing a library or you need to run multiple testsuites, you can for example use |
| 102 | + |
| 103 | +#+begin_src shell |
| 104 | +ghcid -c 'cabal repl hnix-store-remote' --test ':! cabal test test-suite:remote && cabal test test-suite:remote-io' |
| 105 | +#+end_src |
| 106 | + |
| 107 | +*** With restarting |
| 108 | + |
| 109 | +~ghcid~ can also restart itself so ~ghci~ picks up new or moved files, following incantation can be invoked |
| 110 | +when working with ~hnix-store-remote~ to combine all of the features |
| 111 | + |
| 112 | +#+begin_src shell |
| 113 | +ghcid -c 'cabal repl hnix-store-remote' \ |
| 114 | + --restart 'hnix-store-remote/hnix-store-remote.cabal' \ |
| 115 | + --test ':! cabal test test-suite:remote && cabal test test-suite:remote-io' |
| 116 | +#+end_src |
0 commit comments