semantic/docs/development.md

Development Guide

semantic is compiled with the ghc compiler and built/packaged with cabal. It uses Cabal's Nix-style local builds and uses dependencies from Hackage. We recommend using ghcup to sandbox your installation of GHC.

Tool	Explanation
ghc	The Glasgow Haskell Compiler is the open source compiler and interactive environment for the Haskell programming language.
cabal	Cabal is a system for building and packaging Haskell libraries and programs. It is similar to having make files instead of having to type several complicated calls to ghc to compile and link a project.
hackage	Hackage is the most widely used package archive of open source libraries and programs. cabal-install is used to download and install packages.
ghcup	ghcup takes care of managing different versions of GHC on your system. We aggressively track new versions of GHC; sandboxing makes upgrading to new versions safe and easy.
ghci	ghci is GHC's interactive environment. This is where Haskell expressions can be interactively evaluated and programs can be interpreted.

Nix-style local builds

semantic is a complicated app with a very large dependency tree. Because managing large dependency trees in a system-wide ghc installation is difficult, especially when developing on multiple Haskell projects, cabal enables "local" builds: each dependency is linked in per-project, not globally. In practice, this means that you should prefix your commands with the new- prefix: cabal new-build builds the project, new-clean purges its build artifacts, etc. (With versions of the cabal command line tool newer than 2.6, local builds become the default, with the v1- prefix required to yield old behavior.)

Running a REPL

Running cabal new-repl semantic:lib will boot a GHCi with the right environment for Semantic set up.

See the 💡ProTips for more info.

Configuring Atom

You may want to customize Atom to support your haskelling:

1. Install Haskell-specific packages:

• language-haskell provides syntax highlighting for .hs, .cabal, and other Haskell files.
• stylish-haskell can be used via atom-beautify for source code formatting.
• align-regexp is convenient for aligning blocks of text by some pattern.
• Either ide-haskell-hie or ide-haskell:
  • ide-haskell-hie uses atom-ide-ui and haskell-ide-engine (instructions below) to provide linting, errors, warnings, types on hover, autocompletion, etc.
    • git clone https://github.com/haskell/haskell-ide-engine.git somewhere convenient and cd into it.
    • Run make to build and install ghc-specific versions of hie into ~/.local/bin. This will allow you to use hie with projects using different versions of ghc (currently 8.0.2, 8.2.1, and 8.2.2). Alternatively, stack install will build with the current supported version of ghc (8.2.2 at time of writing) and copy it to ~/.local/bin/hie.
    • Make sure that ~/.local/bin/ is on your PATH.
    • If you went with the ghc-specific install route (make), then configure ide-haskell-hie to “Use the hie-wrapper”: .
  • ide-haskell also provides errors, warnings, types, etc. using ghc-mod and other tools:
    • stack install ghc-mod hlint happy — this installs ghc-mod and hlint executables on your system required for the haskell-ghc-mod Atom package below.
    • Install haskell-ghc-mod, and ide-haskell-cabal
    • If you don't launch Atom from your shell, set the additional paths for the the haskell-ghc-mod package in Atom to include /Users/$USER/.local/bin/ and /usr/local/bin. This is done by going to Atom -> Preferences -> Packages -> haskell-ghc-mod -> Settings and editing "Additional Paths":
    • autocomplete-haskell: Autocompletion
    • ide-haskell-hasktags: Symbols
      • stack install hasktags
      • Run hasktags --ignore-close-implementation --ctags app src; sort tags
      • Set the full path for the ide-haskell-hasktags package in Atom to point to /Users/$USER/.local/bin/hasktags by going to Atom -> Preferences -> Packages -> ide-haskell-hasktags -> Settings:

2. Install a font with ligatures (this will require per-font configuration):

• Hasklig
• Monoid
• FiraCode

3. Find Documentation

• For the most part our dependencies have documentation on hackage. You can find individual packages there.
• Hayoo and Hoogle can search package documentation on hackage by package name, symbol name, and even symbol type.
• Dash can install documentation from hackage, search by API, and integrations exist for Atom, emacs, and other tools.

💡ProTip!

See 💡ProTip!.md for more.