github/semantic
1
1
Fork 0
mirror of https://github.com/github/semantic.git synced 2024-11-28 01:47:01 +03:00
Code Issues Projects Releases Wiki Activity
9be9cb3f53
semantic/docs/development.md
joshvera 9be9cb3f53 Add development.md
2019-05-31 16:05:29 -04:00

5.9 KiB
Raw Blame History

Development Guide

semantic is built using the stack build system and the ghc compiler. It’s packaged using Cabal, and uses dependencies from Hackage.

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.
stack Stack is used to develop Haskell projects. It is a layer on top of cabal and ghc that aims to make it much easier to build cross-platform Haskell projects. It lets us use different versions of ghc and has snapshots of packages that are known to work together. It defers to cabal for much of its work. Historically, we used cabal directly, but ran into a variety of tooling issues that brought us back to stack. Officially, stack uses stackage as its package archive, and cabal-install uses hackage.
hackage Hackage is the most widely used package archive of open source libraries and programs. cabal-install is used to download and install packages.
ghci ghci is GHC's interactive environment. This is where Haskell expressions can be interactively evaluated and programs can be interpreted.

Running a REPL

Running stack ghci semantic 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”: Use the hie-wrapper setting.
    • 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": image
      • 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: image
  1. Install a font with ligatures (this will require per-font configuration):
  1. 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.