Skip to content
This repository was archived by the owner on Oct 7, 2020. It is now read-only.

[RFC] New readme for the project #23

Merged
merged 15 commits into from
Nov 6, 2015
Merged

[RFC] New readme for the project #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
0e54acd
initial reorganisation
rvion Nov 5, 2015
8573512
misc
rvion Nov 5, 2015
bf70cc7
_
rvion Nov 5, 2015
d8a6d22
fix the quote
rvion Nov 5, 2015
4a50815
better titles
rvion Nov 5, 2015
57597ae
add links to docs
rvion Nov 5, 2015
4a314fd
better aims list
rvion Nov 5, 2015
0289790
fix markdown
rvion Nov 5, 2015
c8e49c9
attempt to bring badges on first line
rvion Nov 5, 2015
5ec763f
revert
rvion Nov 5, 2015
580a0e3
invite people to join the project
rvion Nov 5, 2015
5b00ea4
improve readability
rvion Nov 5, 2015
71cc9f0
clarify architecture
rvion Nov 5, 2015
0a49ce4
rephrase presentation
rvion Nov 5, 2015
f58f1d5
You'll find -> Features
rvion Nov 5, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 71 additions & 50 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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]
Expand All @@ -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.
29 changes: 15 additions & 14 deletions docs/Challenges.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`