mirror of
https://github.com/marcosh/crem.git
synced 2024-09-11 12:36:19 +03:00
improve readme
This commit is contained in:
parent
7f51d0b7af
commit
8025e592df
30
README.md
30
README.md
@ -2,6 +2,10 @@
|
||||
|
||||
`crem` stands for **c**ompositional **r**epresentable **e**xecutable **m**achines
|
||||
|
||||
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](/docs) folder.
|
||||
|
||||
## development
|
||||
|
||||
This is a Haskell Cabal project that uses Nix for development. Nix is optional but recommended.
|
||||
@ -62,7 +66,9 @@ nix build -L .#crem.ghc92
|
||||
|
||||
## project setup
|
||||
|
||||
- `flake.nix`
|
||||
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, ....
|
||||
@ -73,12 +79,12 @@ It also allows us to create other controlled environments, such as container ima
|
||||
|
||||
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`
|
||||
### `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 gurantee reproducibility.
|
||||
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.
|
||||
@ -89,21 +95,21 @@ One way of doing this is with the command:
|
||||
nix build . --update-input nixpkgs
|
||||
```
|
||||
|
||||
- `shell.nix`
|
||||
### `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 automaticaly propagated to the `shell.nix`.
|
||||
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`
|
||||
### `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](https://haskell-language-server.readthedocs.io/en/latest/configuration.html).
|
||||
|
||||
- `package.yaml`
|
||||
### `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.
|
||||
This file contains the Cabal package specification in `yaml` format read by [hpack](https://github.com/sol/hpack#readme). 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:
|
||||
```sh
|
||||
@ -113,16 +119,14 @@ 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`
|
||||
### `crem.cabal`
|
||||
|
||||
This file is automatically generated from the `package.yaml` file and should not be committed to Git history.
|
||||
|
||||
### tool-specific files
|
||||
|
||||
- `fourmolu.yaml`
|
||||
### `fourmolu.yaml`
|
||||
|
||||
Configuration file for the [`fourmolu`](https://github.com/fourmolu/fourmolu) formatting tool.
|
||||
|
||||
- `.hspec`
|
||||
### `.hspec`
|
||||
|
||||
Using a dedicated file to specify options for [`hspec`](https://hspec.github.io) allows passing options only to it. Using `cabal test --test-options` would pass options to all test stanzas instead.
|
||||
|
Loading…
Reference in New Issue
Block a user