Delegate the bulk of README to srid.ca
This commit is contained in:
Sridhar Ratnakumar
parent
5984ff88c1
commit
dc693ae217
1 changed files with 6 additions and 95 deletions
101
README.md
101
README.md
|
|
@ -1,10 +1,6 @@
|
||||||
# haskell-template
|
# haskell-template
|
||||||
|
|
||||||
Get a Haskell development environment up and running quickly, as long as Nix is available on your system[^windows].
|
Get a Haskell development environment up and running quickly. Thanks to Nix, this template is optimized for a fully reproducible and friendly development environment. It is based on:
|
||||||
|
|
||||||
[^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.
|
|
||||||
|
|
||||||
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
|
- [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
|
||||||
- VSCode + [HLS](https://github.com/haskell/haskell-language-server)
|
- VSCode + [HLS](https://github.com/haskell/haskell-language-server)
|
||||||
|
|
@ -14,35 +10,9 @@ This repository is a Haskell project template that is optimized for a fully repr
|
||||||
|
|
||||||
## Getting Started
|
## Getting Started
|
||||||
|
|
||||||
First-time setup:
|
*tldr: Install Nix, enable Flakes, open in VSCode.*
|
||||||
|
|
||||||
- [Install Nix](https://nixos.org/download.html) (>= 2.8) & [enable Flakes](https://nixos.wiki/wiki/Flakes) (Using Windows? See footnote[^windows])
|
For details, see: https://srid.ca/haskell-template/start
|
||||||
- Run `nix develop -i -c haskell-language-server` to sanity check your environment
|
|
||||||
- [Open as single-folder workspace](https://code.visualstudio.com/docs/editor/workspaces#_singlefolder-workspaces) in Visual Studio Code
|
|
||||||
- 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.
|
|
||||||
|
|
||||||
To run the program with auto-recompile:
|
|
||||||
|
|
||||||
- Press <kbd>Ctrl+Shift+B</kbd> in VSCode, or run `bin/run` in terminal, to launch Ghcid running your program.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Renaming the project:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# First, click the green "Use this template" button on GitHub to create your copy.
|
|
||||||
git clone <your-clone-url>
|
|
||||||
cd your-project
|
|
||||||
NAME=myproject
|
|
||||||
|
|
||||||
git mv haskell-template.cabal ${NAME}.cabal
|
|
||||||
nix run nixpkgs#sd -- haskell-template ${NAME} * */*
|
|
||||||
git add . && git commit -m rename
|
|
||||||
```
|
|
||||||
|
|
||||||
## Tips
|
## Tips
|
||||||
|
|
||||||
|
|
@ -50,69 +20,10 @@ git add . && git commit -m rename
|
||||||
- Run `nix --option sandbox false build .#check -L` to run the flake checks.
|
- Run `nix --option sandbox false build .#check -L` to run the flake checks.
|
||||||
- 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).
|
- 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).
|
||||||
- Run `bin/hoogle` to start Hoogle with packages in your cabal file.
|
- Run `bin/hoogle` to start Hoogle with packages in your cabal file.
|
||||||
- Run `bin/test` to run the test suite.
|
|
||||||
- Run the application without installing: `nix run github:srid/haskell-template` (or `nix run .` from checkout)
|
- Run the application without installing: `nix run github:srid/haskell-template` (or `nix run .` from checkout)
|
||||||
|
- Common workflows
|
||||||
## Common workflows
|
- Adding tests: http://srid.ca/haskell-template/tests
|
||||||
|
- Adding Garnix CI: http://srid.ca/haskell-template/garnix
|
||||||
### Adding tests
|
|
||||||
|
|
||||||
1. Split any logic code out of `Main.hs` into, say, a `Lib.hs`.
|
|
||||||
1. Correspondingly, add `other-modules: Lib` to the "shared" section of your cabal file.
|
|
||||||
1. Add `tests/Spec.hs` (example below):
|
|
||||||
```haskell
|
|
||||||
module Main where
|
|
||||||
|
|
||||||
import Lib qualified
|
|
||||||
import Test.Hspec (describe, hspec, it, shouldContain)
|
|
||||||
|
|
||||||
main :: IO ()
|
|
||||||
main = hspec $ do
|
|
||||||
describe "Lib.hello" $ do
|
|
||||||
it "contains the world emoji" $ do
|
|
||||||
toString Lib.hello `shouldContain` "🌎"
|
|
||||||
```
|
|
||||||
1. Add the tests stanza to the cabal file:
|
|
||||||
```cabal
|
|
||||||
test-suite tests
|
|
||||||
import: shared
|
|
||||||
main-is: Spec.hs
|
|
||||||
type: exitcode-stdio-1.0
|
|
||||||
hs-source-dirs: tests
|
|
||||||
build-depends: hspec
|
|
||||||
```
|
|
||||||
1. Update `hie.yaml` accordingly; for example, by adding,
|
|
||||||
```yaml
|
|
||||||
- path: "tests"
|
|
||||||
component: "test:tests"
|
|
||||||
```
|
|
||||||
1. Add `bin/test` and `chmod a+x` it:
|
|
||||||
```sh
|
|
||||||
#!/usr/bin/env bash
|
|
||||||
set -xe
|
|
||||||
|
|
||||||
exec nix develop -i -c ghcid -c "cabal repl test:tests" -T :main
|
|
||||||
```
|
|
||||||
1. Commit your changes to Git, and test it out by running `bin/test`.
|
|
||||||
|
|
||||||
### Adding Garnix CI
|
|
||||||
|
|
||||||
To use [Garnix](https://garnix.io/) instead of Github Actions, you may provide a `garnix.yaml` like the below:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
builds:
|
|
||||||
include:
|
|
||||||
- "packages.x86_64-linux.*"
|
|
||||||
- "packages.aarch64-darwin.*"
|
|
||||||
- "checks.x86_64-linux.*"
|
|
||||||
- "checks.aarch64-darwin.*"
|
|
||||||
- "devShells.x86_64-linux.default"
|
|
||||||
- "devShells.aarch64-darwin.default"
|
|
||||||
exclude:
|
|
||||||
# https://github.com/srid/haskell-flake/issues/21
|
|
||||||
- "checks.*.default-hls"
|
|
||||||
- "packages.*.check"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Discussions
|
## Discussions
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue