#+title: hcel

hcel is a fork of [[https://github.com/alexwl/haskell-code-explorer][Haskell Code Explorer]], it works with GHC-9.2.2 with
Cabal-3.6.2.0, and possibly other adjacent versions.

It also comes with an emacs binding.

* Install

#+begin_src sh
cabal install
#+end_src

* Usage

You'll need to index a package before serving it.

A typical indexing workflow is as follows, take sqlite-simple as an
example:

#+begin_src sh
cabal unpack sqlite-simple
cd sqlite-simple-x.y.z.w
cabal configure --enable-testsuites --enable-benchmarks
cabal build all
haskell-code-indexer -p .
#+end_src

After indexing the ./dist-newstyle directory is no longer by hcel and
can be removed to save space.  To launch the app, run

#+begin_src sh
haskell-code-server -p /path/to/package1 -p /path/to/package2 ...
#+end_src

and the app will be available at localhost:3000.

You can also hook up a local hoogle for documentation lookup:

#+begin_src sh
hoogle server
# configure a reverse proxy to hook it up with a domain say https://hoogle.localhost with self-signed cert, then run
haskell-code-server -p /path/to/package1 -p /path/to/package2 --use-hoogle-api --hoogle-api https://hoogle.localhost/ --disable-hoogle-api-cert-check
#+end_src

For the readme of the original version, see README.md.original in the
project tree, also available at
https://g.ypei.me/hcel.git/tree/README.md.original.

* Difference from the original version

The indexer of this version looks for all build targets, including
testsuites and benchmarks, in the .cabal file, therefore you'll need
to build them all before indexing, otherwise the indexer will complain
about missing files.

* Emacs binding
You may find an emacs client under the ~lisp~ directory.  It covers
 almost all features in the js client, and more:

- Jump to definition (using xref)
- Find references (based on compilation mode)
- Search identifiers in a package or globally (based on compilation mode)
- Highlight the identifier at point
- Browse packages, modules and identifiers in an outline mode
- Eldoc integration, showing type and documentation of the identifier
  at point, or the selected expression.
- Syntax highlight (requires haskell-mode)

To use, start a server, and set the endpoint:

#+begin_src elisp
(require 'hc)
(setq hcel-endpoint "localhost:8080")
#+end_src

To start, run command ~hcel~ to enter the outline mode.

* Contact and Copyright

The original haskell-code-explorer is written by Alexey Kiryushin
(alexey.a.kiryushin@gmail.com), hosted at [[https://github.com/alexwl/haskell-code-explorer][github]].

This fork is maintained by Yuchen Pei (id@ypei.org).

The original work is under the [[https://www.gnu.org/licenses/license-list.html#Expat][expat license]], while the changes by
Yuchen Pei are covered by [[https://www.gnu.org/licenses/agpl-3.0.en.html][GNU AGPLv3+]].  You may find the license text
in a file named COPYING.agpl3 in the project tree.  As a combination,
this work as a whole is covered by the terms of [[https://www.gnu.org/licenses/agpl-3.0.en.html][GNU AGPLv3+]] ([[https://www.gnu.org/licenses/gpl-faq.html#WhatDoesCompatMean][why?]]).