diff --git a/README.md b/README.md index 150567670..f1a3041cd 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,4 @@ -Home to the community effort to provide a common service backend for any IDE -making use of Haskell in general and GHC in particular. - -## Status - -This is currently a blank canvas. There has been a fair amount of discussion -about what needs to be done/exist, this is the place where it should all come -together. - -Right now there is a google group/mailing list for -[haskell-ide](https://groups.google.com/forum/#!forum/haskell-ide) and an empty -IRC channel at #haskell-ide-engine on freenode. - -The initial discussions have taken place in a number of email threads/IRC -channels, this should become the place where these discussions happen in future. - -If anyone wants to be a member of this project, contact @alanz or @hvr to add -you to it. - +# haskell-ide-engine [![Available on Hackage][badge-hackage]][hackage] [![License BSD3][badge-license]][license] [![Build Status][badge-travis]][travis] @@ -28,46 +10,85 @@ you to it. [badge-license]: https://img.shields.io/badge/license-BSD3-green.svg?dummy [license]: https://github.com/haskell/haskell-ide-engine/blob/master/LICENSE -## Next steps -After lots of discussion around layers and licensing, it looks like the way -forward is as follows +This project aims to be the __universal IDE interface__ to __all haskell tools__, proving a __full-featured and easy to query ide-backend__. -### BIOS layer +Features: -ghc-mod stays an AGPL project, and is used for its "awesome sauce" in terms of -the BIOS functions that it does so well. This interface is -[straightforward to use](http://alanz.github.io/haskell%20refactorer/2015/10/02/ghc-mod-for-tooling), -and if a license-constrained user wants to do something else it is also easy to -replace, if there is strong control of the operating environment. + - [ ] cabal / stack project `Configuration` and `Compilation` + - [ ] Errors Checking, Warnings, Linter, Dead code detection + - [ ] Refactoring tools, Code beautify, Auto-apply suggestion + - [ ] Code generation + - [ ] Run testing Suite, check coverage + - [ ] Autocompletion + - [ ] Get type at point + - [ ] Jump to definition, find Usages, Browse documentation, Generate ctags + - [ ] REPL -### Plugin layer -A layer providing a point to integrate tools and existing functions, probably -including ghci. +### Is this _again_ an other `ghc-mod` or `ide-backend` like project ? -### IDE interfacing layer +No: -This provides a set of logical channels that can be integrated into standard -IDEs. The details still need to be worked out, but I would imagine something -like a channel for querying information about a project, one for a ghci session, -and whatever others are needed. These logical channels can then run over -whatever transport is appropriate to the specific IDE being integrated. + > Both the ghc-mod and ide-backend maintainers have agreed to contribute code to this new repository and then rebase the old repos on this. The reason we're using a new repo instead of modifying one of the existing ones is so that the existing projects experience no disruption during this migration process. If this was a new set of people starting a new project without support from existing projects, I'd agree with you. But Alan's reached out to existing players already, which is an important distinction. -According to [#2](https://github.com/haskell/haskell-ide-engine/issues/2) it seems the -consensus is toward (re) using the Idris protocol, as the languages are similar -enough and it offers cross-IDE support already. +This project doesn't start from scratch: -The Plugin and IDE layers are very fuzzy at this point, and there has been some -discussion on IRC around it. These layers may well live in a single repository -(this one), as two separate layers or just be a feature of how -haskell-ide-engine is built. +1. See why [we should superseed previous tools](/docs/Challenges) +2. Check the [list of existting tools / features ](/docs/Tools.md) +3. See more [other tools / ide for inpiration](/docs/Inspirations.md) -## Documentation +## It's time to join the project ! + +:heart: Haskell tooling dream is near, we need your help ! :heart: + + - Register in our [google group mailing list](https://groups.google.com/forum/#!forum/haskell-ide) + - Join our IRC channel at `#haskell-ide-engine` on `freenode`. + - Fork this repo and hack as much as you can. + - Ask @alanz or @hvr to join the project. + +------------- + + +## Architecture -Rather than use the wiki we will put the documentation in the -[docs](https://github.com/haskell/haskell-ide-engine/tree/master/docs) directory here, -so collaborators can either edit or provide pull requests. +1. __BIOS layer__: + + ghc-mod stays an AGPL project, and is used for its "awesome sauce" in terms of + the BIOS functions that it does so well. This interface is + [straightforward to use](http://alanz.github.io/haskell%20refactorer/2015/10/02/ghc-mod-for-tooling), + and if a license-constrained user wants to do something else it is also easy to + replace, if there is strong control of the operating environment. + +2. __Plugin layer__: + + A layer providing a point to integrate tools and existing functions, probably + including ghci. + +3. __IDE interfacing layer__: + + This provides a set of logical channels that can be integrated into standard + IDEs. The details still need to be worked out, but I would imagine something + like a channel for querying information about a project, one for a ghci session, + and whatever others are needed. These logical channels can then run over + whatever transport is appropriate to the specific IDE being integrated. + + According to [#2](https://github.com/haskell/haskell-ide-engine/issues/2) it seems the + consensus is toward (re) using the Idris protocol, as the languages are similar + enough and it offers cross-IDE support already. + + The Plugin and IDE layers are very fuzzy at this point, and there has been some + discussion on IRC around it. These layers may well live in a single repository + (this one), as two separate layers or just be a feature of how + haskell-ide-engine is built. + +You can see more info [in the docs folder](/docs) at the root of the project, especially: + + - The [Architecture discussion](/docs/Architecture.md) + - The [Protocol discussion](/docs/Protocol.md) + - The [Design discussion](/docs/Design.md) + + +## Documentation - * [Inspirations](https://github.com/haskell/haskell-ide-engine/blob/master/docs/Inspirations.md) - * [Tools](https://github.com/haskell/haskell-ide-engine/blob/master/docs/Tools.md) that could/should be integrated into haskell-ide-engine +All the documentation is [in the docs folder](/docs) at the root of the project. diff --git a/docs/Challenges.md b/docs/Challenges.md index 6fdfee8e7..e29edf487 100644 --- a/docs/Challenges.md +++ b/docs/Challenges.md @@ -1,27 +1,28 @@ # Challenges encountered by existing tooling -## ghc-mod +### ghc-mod -- Relying on files/binary data that Cabal uses which were never meant to be part of an API or protocol meant breakage was frequent and needing a specific version of ghc-mod to be matched with a specific version of Cabal. + 1. Relying on files/binary data that Cabal uses which were never meant to be part of an API or protocol meant breakage was frequent and needing a specific version of ghc-mod to be matched with a specific version of Cabal. + 2. A bit slow, especially on larger projects. + 3. Related to `1.`, hard for new people to get installed and working with their editor + projects. -- A bit slow, especially on larger projects. +:memo: Don't rely on files/binary data that Cabal uses +:memo: It must be fast to be pleasant to use -- Related to #1, hard for new people to get installed and working with their editor + projects. +### ide-backend / stack-ide -## ide-backend / stack-ide + 1. For various reasons mainly related to its original usecase, all of the information yielded by compilation gets sent to a separate process than ide-backend-server (ghc). While it's nice to have a datatype for all the info yielded by a compilation, this seems wasteful from a performance perspective. It also means extending ide-backend with new features requires a lot more boilerplate than it ought to. -- For various reasons mainly related to its original usecase, all of the information yielded by compilation gets sent to a separate process than ide-backend-server (ghc). While it's nice to have a datatype for all the info yielded by a compilation, this seems wasteful from a performance perspective. It also means extending ide-backend with new features requires a lot more boilerplate than it ought to. + 2. Another one of the reasons to have this multiple process architecture was to be able to accept mutations of the configuration of GHC (changing flags, etc), and intelligently either get GHC to update its flags or restart the ide-backend-server. This turned out to be very tricky, and we had lots of different issues and it's still imperfect. -- Another one of the reasons to have this multiple process architecture was to be able to accept mutations of the configuration of GHC (changing flags, etc), and intelligently either get GHC to update its flags or restart the ide-backend-server. This turned out to be very tricky, and we had lots of different issues and it's still imperfect. Let's just force a backend restart if you change ghc or RTS options. +:memo: Let's just force a backend restart if you change ghc or RTS options. -- With stack-ide, we ended up wrapping the pure API with another layer of datatypes for conversion to JSON. This meant the dataflow from the backend looked like: GHC types -> internal datatypes with explicit sharing -> byte serialized representation sent to ide-backend user -> public datatypes with sharing reified -> ide-backend function call -> stack-ide json datatype + 3. With stack-ide, we ended up wrapping the pure API with another layer of datatypes for conversion to JSON. This meant the dataflow from the backend looked like: GHC types -> internal datatypes with explicit sharing -> byte serialized representation sent to ide-backend user -> public datatypes with sharing reified -> ide-backend function call -> stack-ide json datatype -Lets avoid a lot of layers. +:memo: Lets avoid a lot of layers. ## Flycheck -- Works pretty well/reliably (for @bitemyapp anyway), but a bit slow. Basically fires off a `stack build` (or `cabal build`) or `hlint` from the command line and parses stdout. - -- Emacs-only - -- Easier to get working reliably than ghc-mod + 1. Works pretty well/reliably (for @bitemyapp anyway), but a bit slow. Basically fires off a `stack build` (or `cabal build`) or `hlint` from the command line and parses stdout. + 2. Emacs-only + 3. Easier to get working reliably than `ghc-mod`