ghciwatch

https://mercurytechnologies.github.io/ghciwatch
Admin
ghciwatch loads a GHCi session for a Haskell project and reloads it when source files change.
Tokens:6,278
Snippets:100
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install ghciwatch via Nix

Source: https://mercurytechnologies.github.io/ghciwatch/install.html

Use these commands to install ghciwatch from the nixpkgs repository.

```bash
nix-env -iA ghciwatch
nix profile install nixpkgs#ghciwatch
```

--------------------------------

### Standard cabal repl initialization

Source: https://mercurytechnologies.github.io/ghciwatch/no-load.html

Example of a standard cabal repl session loading all modules in a target.

```bash
$ cabal repl test-dev
Build profile: -w ghc-9.0.2 -O1
In order, the following will be built (use -v for more details):
 - my-simple-package-0.1.0.0 (lib:test-dev) (first run)
Configuring library 'test-dev' for my-simple-package-0.1.0.0..
Preprocessing library 'test-dev' for my-simple-package-0.1.0.0..
GHCi, version 9.0.2: https://www.haskell.org/ghc/  :? for help
[1 of 3] Compiling MyLib            ( src/MyLib.hs, interpreted )
[2 of 3] Compiling MyModule         ( src/MyModule.hs, interpreted )
[3 of 3] Compiling TestMain         ( test/TestMain.hs, interpreted )
Ok, three modules loaded.
ghci>
```

--------------------------------

### Install ghciwatch via Cargo

Source: https://mercurytechnologies.github.io/ghciwatch/install.html

Use the Rust package manager to install the ghciwatch crate directly from crates.io.

```bash
cargo install ghciwatch
```

--------------------------------

### Start a ghciwatch session

Source: https://mercurytechnologies.github.io/ghciwatch/getting-started.html

Initiate a session by specifying the GHCi command and the directories to monitor for changes.

```bash
ghciwatch --command "cabal repl lib:test-dev" \
          --watch src --watch test
```

--------------------------------

### Load cabal v2-repl and watch src

Source: https://mercurytechnologies.github.io/ghciwatch/cli.html

Basic usage to start a GHCi session via cabal and monitor the src directory.

```bash
ghciwatch
```

--------------------------------

### Execute Haskell code in comments

Source: https://mercurytechnologies.github.io/ghciwatch/comment-evaluation.html

Example of using a single-line eval comment to print a string in GHCi.

```haskell
myGreeting :: String
myGreeting = "Hello"

-- $> putStrLn (myGreeting <> " " <> myGreeting)
```

--------------------------------

### Measuring standard cabal repl load time

Source: https://mercurytechnologies.github.io/ghciwatch/no-load.html

Demonstration of the time taken to load a large project using standard cabal repl.

```bash
$ echo :quit | time cabal repl
...
Ok, 9194 modules loaded.
ghci> Leaving GHCi.
________________________________________________________
Executed in  161.07 secs
```

--------------------------------

### Configure ghciwatch for multi-package monitoring

Source: https://mercurytechnologies.github.io/ghciwatch/integration/multiple-packages.html

Use the --watch and --restart-glob flags to trigger restarts when specific dependency files change.

```bash
ghciwatch \
    --watch my-dependency \
    --restart-glob 'my-dependency/src/**/*.hs' \
    --restart-glob 'my-dependency/my-dependency.cabal'
```

--------------------------------

### Load custom GHCi session with multiple watch paths

Source: https://mercurytechnologies.github.io/ghciwatch/cli.html

Specify a custom shell command and multiple directories to monitor for changes.

```bash
ghciwatch --command "cabal v2-repl lib:test-dev" \
          --watch src --watch test
```

--------------------------------

### Run tests after reloads

Source: https://mercurytechnologies.github.io/ghciwatch/cli.html

Configure test execution and startup arguments for the GHCi session.

```bash
ghciwatch --test-ghci TestMain.testMain \
          --after-startup-ghci ':set args "--match=/OnlyRunSomeTests/"'
```

--------------------------------

### Define multiple packages in cabal.project

Source: https://mercurytechnologies.github.io/ghciwatch/integration/multiple-packages.html

Specify the package structure in your project configuration file.

```text
packages:
  my-package.cabal
  my-dependency/my-dependency.cabal
```

--------------------------------

### Measuring cabal repl load time with --repl-no-load

Source: https://mercurytechnologies.github.io/ghciwatch/no-load.html

Demonstration of the reduced time taken to load a project when using the --repl-no-load flag.

```bash
$ echo ":quit" | time cabal repl --repl-no-load
...
ghci> Leaving GHCi.
________________________________________________________
Executed in   11.41 secs
```

--------------------------------

### Regenerate cabal files with hpack

Source: https://mercurytechnologies.github.io/ghciwatch/cli.html

Run a shell command before startup and restart the session when package.yaml changes.

```bash
ghciwatch --before-startup-shell hpack \
          --restart-glob '**/package.yaml'
```

--------------------------------

### Set GHCi Arguments via Hook

Source: https://mercurytechnologies.github.io/ghciwatch/print.html

Use the --after-startup-ghci hook to configure GHCi session arguments, such as filtering HSpec items.

```bash
--after-startup-ghci ':set args "--match=/MyModule/"'
```

--------------------------------

### ghciwatch CLI Usage

Source: https://mercurytechnologies.github.io/ghciwatch/print.html

The ghciwatch command-line interface allows users to specify the GHCi command, watch paths, and configure reload behavior.

```APIDOC
## ghciwatch

### Description
Starts a GHCi session and watches for file changes to trigger reloads.

### Usage
`ghciwatch [--command SHELL_COMMAND] [--watch PATH] [OPTIONS ...]`

### Options
- **--command** (string) - A shell command which starts a GHCi REPL.
- **--watch** (string) - A path to watch for changes. Can be specified multiple times.
- **--error-file** (string) - A file to write compilation errors to.
- **--enable-eval** (flag) - Evaluate Haskell code in comments.
- **--extra-module-search-path** (string) - An extra directory for module path conversion. Can be given multiple times.
- **--clear** (flag) - Clear the screen before reloads and restarts.
- **--no-interrupt-reloads** (flag) - Don't interrupt reloads when files change.
- **--completions** (string) - Generate shell completions (bash, elvish, fish, powershell, zsh).
- **--test-ghci** (string) - Run tests after reloads.
- **--after-startup-ghci** (string) - Commands to run after startup.
- **--before-startup-shell** (string) - Shell command to run before startup.
- **--restart-glob** (string) - Glob pattern to trigger a full restart.
- **--reload-glob** (string) - Glob pattern to trigger a reload.
```

--------------------------------

### Configure hie.yaml for HLS

Source: https://mercurytechnologies.github.io/ghciwatch/integration/multiple-components.html

Specify the component for the HLS cradle to resolve ambiguity when files belong to multiple components.

```yaml
cradle:
  cabal:
    component: test-dev
```

--------------------------------

### Configure package.yaml for test-dev component

Source: https://mercurytechnologies.github.io/ghciwatch/integration/multiple-components.html

Define the internal test-dev library and conditional dependencies in your package.yaml to aggregate source directories.

```yaml
spec-version: 0.36.0
name: my-simple-package
version: 0.1.0.0

flags:
  local-dev:
    description: Turn on development settings, like auto-reload templates.
    manual: true
    default: false

library:
  source-dirs: src

tests:
  test:
    main: Main.hs
    source-dirs:
      - test-main
    ghc-options: -threaded -rtsopts -with-rtsopts=-N
    when:
    - condition: flag(local-dev)
      then:
        dependencies:
        - test-dev
      else:
        dependencies:
        - my-simple-package
        - test-lib

internal-libraries:
  test-lib:
    source-dirs:
      - test

  test-dev:
    source-dirs:
      - test
      - src
    when:
    - condition: flag(local-dev)
      then:
        buildable: true
      else:
        buildable: false
```

--------------------------------

### Run Asynchronous Shell Hook

Source: https://mercurytechnologies.github.io/ghciwatch/print.html

Prefix a shell hook with 'async:' to execute the command asynchronously without blocking ghciwatch.

```bash
--after-reload-shell 'async:tags'
```

--------------------------------

### Protecting stdout buffering for Tasty

Source: https://mercurytechnologies.github.io/ghciwatch/integration/tasty.html

Use this wrapper to ensure stdout buffering is restored after running Tasty tests, preventing ghciwatch from hanging.

```haskell
module TestMain where

import Control.Exception (bracket)
import System.IO (hGetBuffering, hSetBuffering, stdout)
import Test.Tasty (TestTree, defaultMain, testGroup)

-- | Run an `IO` action, restoring `stdout`'s buffering mode after the action
-- completes or errors.
protectStdoutBuffering :: IO a -> IO a
protectStdoutBuffering action =
  bracket
    (hGetBuffering stdout)
    (\bufferMode -> hSetBuffering stdout bufferMode)
    (const action)

main :: IO ()
main = protectStdoutBuffering $ defaultMain $ mytestgroup
```

--------------------------------

### Chaining multiple lifecycle hooks

Source: https://mercurytechnologies.github.io/ghciwatch/lifecycle-hooks.html

Lifecycle hooks can be defined multiple times to execute commands in sequence.

```bash
ghciwatch --test-ghci TestMain.testMain \
          --test-ghci 'if myGreeting /= "Hello, world!" then error else ()'
```

--------------------------------

### Set local-dev flag in cabal.project.local

Source: https://mercurytechnologies.github.io/ghciwatch/integration/multiple-components.html

Enable the local-dev flag to target the test-dev component during local development.

```text
package my-simple-package
  flags: +local-dev
```

--------------------------------

### Reload on persistentmodels changes

Source: https://mercurytechnologies.github.io/ghciwatch/cli.html

Add specific file patterns to trigger a session reload.

```bash
ghciwatch --watch config/modelsFiles \
          --reload-glob '**/*.persistentmodels'
```

--------------------------------

### Run tests with eval comments

Source: https://mercurytechnologies.github.io/ghciwatch/comment-evaluation.html

Using eval comments to trigger Hspec tests on file reload for faster execution.

```haskell
module MyLibSpec (spec) where

import Test.Hspec
import MyLib (myGreeting)

-- $> import Test.Hspec  -- May be necessary for some setups.
-- $> hspec spec

spec :: Spec
spec = do
  describe "myGreeting" $ do
    it "is hello" $ do
      myGreeting `shouldBe` "Hello"
```

--------------------------------

### Exclude files from reloads

Source: https://mercurytechnologies.github.io/ghciwatch/cli.html

Use glob patterns to ignore specific files or directories from triggering reloads.

```bash
ghciwatch --reload-glob '!src/**/README.md'
```

--------------------------------

### Multi-line eval comment grammar

Source: https://mercurytechnologies.github.io/ghciwatch/comment-evaluation.html

Formal grammar definition for multi-line eval comments.

```text
[ \t]*        # Leading whitespace
"{- $>"       # Eval comment marker
([ \t]* \n)?  # Optional newline
([^\n]* \n)*  # Lines of Haskell code
[ \t]*        # Optional whitespace
"<$ -}"       # Eval comment end marker
```

--------------------------------

### Single-line eval comment grammar

Source: https://mercurytechnologies.github.io/ghciwatch/comment-evaluation.html

Formal grammar definition for single-line eval comments.

```text
[ \t]*     # Leading whitespace
"-- $>"    # Eval comment marker
[ \t]*     # Optional whitespace
[^\n]+ \n  # Rest of line
```
Tokens:
Raw