matrix-media-expanded/README.md

54 lines
3 KiB
Markdown
Raw Normal View History

2021-05-31 23:19:51 +00:00
# haskell-template
2022-07-27 19:14:06 +00:00
Get a Haskell development environment up and running quickly, as long as Nix is available on your system[^windows].
[^windows]: On Windows, you may install Nix [under WSL2](https://nixos.wiki/wiki/Nix_Installation_Guide#Windows_Subsystem_for_Linux_.28WSL.29) and use the [Remote - WSL extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) to connect from the native VSCode. This runs your project under Linux while providing a near-native development experience on Windows.
2022-04-06 21:43:03 +00:00
2022-06-19 19:18:51 +00:00
This repository is a Haskell project template that is optimized for a fully reproducible and friendly development environment. It is based on:
- [Nix](https://srid.ca/haskell-nix) + [Flakes](https://serokell.io/blog/practical-nix-flakes) (via [`github:srid/haskell-flake`](https://github.com/srid/haskell-flake)) + GHC 9
2022-04-06 21:43:03 +00:00
- VSCode + [HLS](https://github.com/haskell/haskell-language-server)
- [fourmolu](https://github.com/fourmolu/fourmolu) autoformatting
- [Relude](https://github.com/kowainik/relude#relude) as Prelude.
2022-05-04 21:05:56 +00:00
- `.hlint.yaml` is [from relude](https://github.com/kowainik/relude/blob/main/.hlint.yaml)
2021-05-31 23:19:51 +00:00
2021-05-31 23:37:01 +00:00
## Getting Started
2021-05-31 23:19:51 +00:00
2021-12-04 15:00:57 +00:00
First-time setup:
2022-07-27 19:14:06 +00:00
- [Install Nix](https://nixos.org/download.html) (>= 2.8) & [enable Flakes](https://nixos.wiki/wiki/Flakes) (Using Windows? See footnote[^windows])
2022-08-08 15:29:55 +00:00
- Run `nix develop -i -c haskell-language-server` to sanity check your environment
2021-05-31 23:19:51 +00:00
- [Open as single-folder workspace](https://code.visualstudio.com/docs/editor/workspaces#_singlefolder-workspaces) in Visual Studio Code
2021-12-04 15:00:57 +00:00
- When prompted by VSCode, install the [workspace recommended](https://code.visualstudio.com/docs/editor/extension-marketplace#_workspace-recommended-extensions) extensions
- <kbd>Ctrl+Shift+P</kbd> to run command "Nix-Env: Select Environment" and then select `shell.nix`.
- The extension will ask you to reload VSCode at the end. Do it.
2021-05-31 23:19:51 +00:00
2021-12-04 15:00:57 +00:00
To run the program with auto-recompile:
2022-04-27 22:34:03 +00:00
- Press <kbd>Ctrl+Shift+B</kbd> in VSCode, or run `bin/run` in terminal, to launch Ghcid running your program.
2021-05-31 23:19:51 +00:00
2021-12-06 19:59:18 +00:00
Open `Main.hs`, and expect all HLS IDE features like hover-over tooltip to work out of the box. Try changing the source, and expect Ghcid to re-compile and re-run the app in the terminal below.
---
2021-12-04 15:00:57 +00:00
Renaming the project:
2021-05-31 23:37:01 +00:00
2021-12-04 15:00:57 +00:00
```sh
2022-05-26 11:25:38 +00:00
# First, click the green "Use this template" button on GitHub to create your copy.
2022-03-11 17:23:18 +00:00
git clone <your-clone-url>
cd your-project
2021-12-04 15:00:57 +00:00
NAME=myproject
2022-03-11 17:23:18 +00:00
2021-12-04 15:00:57 +00:00
git mv haskell-template.cabal ${NAME}.cabal
nix run nixpkgs#sd -- haskell-template ${NAME} * */*
git add . && git commit -m rename
```
2021-06-01 12:37:15 +00:00
2021-08-04 14:33:51 +00:00
## Tips
- Run `nix flake update` to update all flake inputs.
2022-05-04 20:28:54 +00:00
- Run `treefmt` in nix shell to autoformat the project. This uses [treefmt](https://github.com/numtide/treefmt), which uses `./treefmt.toml` (where fourmolu and nixpkgs-fmt are specified).
2022-05-17 18:48:03 +00:00
- Run `bin/hoogle` to start Hoogle with packages in your cabal file.
- Run `bin/test` to run the test suite.
2022-05-22 18:53:04 +00:00
- Run the application without installing: `nix run github:srid/haskell-template` (or `nix run .` from checkout)