From 14fb2fb567a21fc0c17457572a3a9ac183edc637 Mon Sep 17 00:00:00 2001 From: Javier Sagredo Date: Thu, 7 May 2026 02:44:09 +0200 Subject: [PATCH] Update README --- README.md | 70 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index bea650a..4c77a2a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # classgraph -A GHC TypeChecker plugin and browser visualizer for Haskell typeclass +A GHC typechecker plugin and browser visualizer for Haskell typeclass hierarchies. Drop the plugin onto a project, render the captured data as a self-contained interactive HTML page, and explore the inheritance DAG, class instances, type families, and superclass requirements with @@ -11,7 +11,7 @@ xdot-style highlighting. (built with the plugin) (.classgraph/*.json) │ ▼ - classgraph-view ──────► oc.html + classgraph-view ──────► classgraph.html (one self-contained file) ``` @@ -22,11 +22,14 @@ xdot-style highlighting. - [Using the plugin in your own project](#using-the-plugin-in-your-own-project) - [Option A — `build-depends`](#option-a--build-depends-simplest-okay-for-small-projects) - [Option B — `-fplugin-library`](#option-b---fplugin-library-recommended-for-real-projects) + - [Optional: Haddocks in the side panel](#optional-haddocks-in-the-side-panel) - [Combining dumps from multiple packages](#combining-dumps-from-multiple-packages) - [Viewer reference](#viewer-reference) + - [Jumping to source from the panel](#jumping-to-source-from-the-panel) - [Schema, data flow, design notes](#schema-data-flow-design-notes) - [Known limitations](#known-limitations) - [Building from source](#building-from-source) +- [License](#license) ## What you get @@ -74,16 +77,16 @@ families, an open family used in a superclass context, a closed family, a data family, an orphan instance, equality contexts, etc.). ```bash -cabal build classgraph # build the plugin library -cabal build demo # builds with -fplugin=Classgraph.Plugin +cabal build classgraph # build the plugin library +cabal build demo # builds with -fplugin=Classgraph.Plugin cabal run classgraph-view -- \ --input examples/demo/.classgraph \ --output classgraph-demo.html -xdg-open classgraph-demo.html # or `open` on macOS +xdg-open classgraph-demo.html # or `open` on macOS ``` -That should pop a single HTML file ~700 KB containing 14 classes, 29 -instances, 4 families, and 5 family instances, ready to be explored. +That should produce a single HTML file ~780 KB containing 16 classes, +32 instances, 6 families, and 11 family instances, ready to be explored. ## Using the plugin in your own project @@ -287,6 +290,31 @@ a clickable link that opens the file at the right line in your editor. Schemes that take a column (`vscode`, `cursor`, `txmt`, `emacs`) get one; `idea`, `emacs-org`, and `file` ignore it. +**Source roots are inferred automatically.** The plugin records source +paths as GHC saw them (usually relative to each package's source dir), +so the viewer needs an absolute prefix to make `vscode://` / +`cursor://` /etc URLs resolvable. `classgraph-view` does this for you: + +- For each `--input DIR`, the *parent* of `DIR` is used as the source + root for every package whose dumps live there. So + `--input ~/code/my-app/.classgraph/` means `~/code/my-app/` is the + root for the `my-app` package. +- Repeat `--input` for multi-package merges; each package gets the + root inferred from its own input dir. +- Override per-package with `--source-root PKG=PATH` (repeatable): + + ```bash + cabal run classgraph-view -- \ + --input ~/code/foo/.classgraph \ + --input ~/code/bar/sub/.classgraph \ + --source-root bar=~/code/bar \ + --output combined.html + ``` + +The "Source root override" field in the panel is a global fallback +applied only when no inferred root exists for the file's package — +useful when you've been handed an HTML file built elsewhere. + #### Setting up the Emacs schemes The two Emacs variants build: @@ -430,31 +458,6 @@ xdg-mime default emacs-uri.desktop x-scheme-handler/emacs **3. Pick `Emacs (emacs://)` from the dropdown.** Same UX as above, plus the column is passed through. -**Source roots are inferred automatically.** The plugin records source -paths as GHC saw them (usually relative to each package's source dir), -so the viewer needs an absolute prefix to make `vscode://` / -`cursor://` /etc URLs resolvable. `classgraph-view` does this for you: - -- For each `--input DIR`, the *parent* of `DIR` is used as the source - root for every package whose dumps live there. So - `--input ~/code/my-app/.classgraph/` means `~/code/my-app/` is the - root for the `my-app` package. -- Repeat `--input` for multi-package merges; each package gets the - root inferred from its own input dir. -- Override per-package with `--source-root PKG=PATH` (repeatable): - - ```bash - cabal run classgraph-view -- \ - --input ~/code/foo/.classgraph \ - --input ~/code/bar/sub/.classgraph \ - --source-root bar=~/code/bar \ - --output combined.html - ``` - -The "Source root override" field in the panel is a global fallback -applied only when no inferred root exists for the file's package — -useful when you've been handed an HTML file built elsewhere. - ## Schema, data flow, design notes For a deeper walkthrough of where every piece of information comes @@ -462,7 +465,6 @@ from — including how the type-family resolution chains in the instance view are computed, and what's deterministic vs. best-effort — see [`docs/INTERNALS.md`](docs/INTERNALS.md). - The plugin runs in `typeCheckResultAction` (post-typecheck, so all classes / instances / family equations are fully resolved). For each compiled module it writes one JSON file under the configured directory @@ -547,7 +549,7 @@ To run the demo end-to-end: ```bash cabal build demo -cabal run classgraph-view -- --input examples/demo/.classgraph -o demo.html +cabal run classgraph-view -- --input examples/demo/.classgraph -o classgraph-demo.html ``` To regenerate dumps for a real target (e.g. my-app) using -- 2.54.0