.github/workflows | ||
.vscode | ||
decision-log | ||
docs | ||
doctest | ||
examples/Crem/Example | ||
hobbit-game | ||
nix | ||
spec | ||
src/Crem | ||
.envrc | ||
.gitattributes | ||
.gitignore | ||
.hspec | ||
flake.lock | ||
flake.nix | ||
fourmolu.yaml | ||
hie.yaml | ||
package.yaml | ||
README.md | ||
shell.nix |
crem
crem
stands for compositional representable executable machines
It allows creating state machines (Mealy machines in fact), compose them to build bigger machines out of smaller ones and then run them and draw their flow and their state space.
Further documentation can be found in the docs folder.
development
This is a Haskell Cabal project that uses Nix for development. Nix is optional but recommended.
environment
A Nix shell is available with all the required tools. To enter the shell, issue
# default GHC
nix develop
# custom GHC
nix develop .#ghc90
nix develop .#ghc92
Or, without flakes:
# default GHC
nix-shell
GHC version
The project has a default GHC version that is specified in the flake. At the moment that version is 9.0, because the HLS plugin Wingman currently only builds up to this version.
It is also possible to use other GHC versions to build the project and enter development shells. This allows us to easily test multiple versions.
Building
In a development shell, you can simply build the project with Cabal:
cabal build
This provides us fast incremental builds, ease of debugging, etc.
It is also possible to build the project without entering the development shell. This allows us to build the same way as the CI/CD environment, build with different GHC versions, build container images, etc.
To do this, run
# default GHC
nix build
# custom GHC
nix build .#crem.ghc90
nix build .#crem.ghc92
To view the compilation logs, you can append -L
:
nix build -L
nix build -L .#crem.ghc92
project setup
In this section we document all the files relevant for the project setup.
flake.nix
This file specifies our project's dependencies and outputs/artefacts. Some common dependencies for a Haskell project are the GHC and Cabal, but during development we also use HLS, hpack, .... Nix flake dependencies are called inputs, and are usually Git repositories (e.g. from GitHub, GitLab, ...), but they can be any web-accessible resource.
By using Nix and Nixpkgs, the developers do not have to have those tools installed on their machines, manage their versions, etc. It also allows us to create other controlled environments, such as container images for CI/CD.
The project should still build without Nix, because Nix does not change any project files. This means you must have Cabal and system libraries installed manually.
flake.lock
This file is automatically generated and updated by Nix, when evaluating the flake.nix
file.
It contains the timestamps and hashes of each input at the time of last update.
An input coupled with a timestamp and hash of its contents is called a pinned input. Pinning inputs allows us to guarantee reproducibility.
We can specify unpinned inputs in flake.nix
; for example, our nixpkgs
input is not pinned to a specific commit. The branch nixpkgs-unstable
changes almost every day.
However, the flake.lock
file contains a timestamp and hash of a specific commit in the nixpkgs
repository. This is regenerated for every input every time we run nix flake upadate
, to the latest commit in the branch/tag we specified in the flake.
We can also update just a single input (e.g. just nixpkgs
) and leave the others pinned.
One way of doing this is with the command:
nix build . --update-input nixpkgs
shell.nix
Nix flakes are a new feature. Some Nix installations do not support them. However, it is still useful to provide a development shell for developers with older Nix versions.
This file allows us to replicate the development shell provided in flake.nix
without duplicating the code. This way changes to the flake.nix
are automatically propagated to the shell.nix
.
Some tools also don't yet support flakes. An important example is Visual Studio Code with the Nix Environment Selector plugin: it works with shell.nix
, but not flake.nix
.
hie.yaml
This file instructs the Haskell Language Server how your project should be built. Find more information at https://haskell-language-server.readthedocs.io/en/latest/configuration.html.
package.yaml
This file contains the Cabal package specification in yaml
format read by hpack. It is more abstract and easier to maintain than the Cabal file format.
To generate a .cabal
file from a package.yaml
file, run the following command:
hpack
Note that Cabal does not understand package.yaml
files, and requires us to generate a .cabal
file before running cabal
.
Nix (or more precisely, Cabal2nix) uses a .cabal
file if it is present, otherwise the package.yaml
file. Because package.yaml
is our single source of truth, we would prefer that Nix uses it instead of the generated .cabal
. This is why we don't commit the .cabal
file.
crem.cabal
This file is automatically generated from the package.yaml
file and should not be committed to Git history.
fourmolu.yaml
Configuration file for the fourmolu
formatting tool.
.hspec
Using a dedicated file to specify options for hspec
allows passing options only to it. Using cabal test --test-options
would pass options to all test stanzas instead.