-
Notifications
You must be signed in to change notification settings - Fork 39
Quick Start Guide
- IntelliJ IDEA Community Edition or Ultimate >= 13.1.5
- Stack or Cabal >= 1.18
Warning: You cannot use multiple Haskell plugins at the same time. If you have installed a Haskell language plugin for IntelliJ be sure to uninstall it before installing this one.
You can install the plugin using the JetBrains plugin repository -
- Preferences > Plugins > Browse repositories > HaskForce
Alternatively, you can download the latest zip archive from the releases page and install it from -
- Preferences > Plugins > Install plugin from disk.
Note that pre-releases are non-production builds. If you encounter any issues please report them in our issues tracker.
- Choose New Project, select the Haskell option, then click Next.
- Choose your build tool. You are given the choice of using Stack or Cabal. HaskForce will attempt to find these for you, but you may need to set the paths to the executables.
- Configure the Cabal package. HaskForce will generate a
.cabalfile andSetup.hsfile for you. If you would rather do this manually, you can uncheck Initialize Cabal package. - Enter the project name and location and click Finish.
- Either choose Import Project from the splash screen or go to File > New > Project from Existing Sources...
- Locate and select the root directory of your project and click OK.
- Choose Stack as your external model.
- Ensure that the paths to
stackand your project'sstack.yamlare correct and click Next. - Select the projects that you want HaskForce to manage and click Finish.
- Create a new project using the steps from above and set the project location to the root of your existing project. Be sure to uncheck Initialize Cabal package if your project already has a Cabal file.
- Use Tools > Discover Cabal packages if you have any sub-projects. This will find existing Cabal files in your project and allow you to choose which ones you would like to import.
IntelliJ projects generally require an SDK to be configured, and HaskForce is no exception. However, because Haskell revolves more around tooling as opposed to a particular installation of the language, the plugin will auto-create a standard Haskell SDK for you. Note that any path specified for a Haskell SDK is accepted since the location of GHC, Stack, etc. will be determined by your compiler and tool configurations. SDK existence is simply required to specify the project type as Haskell and enable certain IDE features, such as building.
Note: This is not supported for Stack projects. Use stack on the command line instead.
- Choose Tools > Add Cabal Package.
- Fill out the info for your new Cabal package.
- Upon clicking OK, HaskForce will initialize the Cabal package and create a Cabal file for you.
HaskForce can integrate with tools such as HLint, Stylish-Haskell, hindent, and ghc-mod. Install the tools you wish to use:
cabal install hlint stylish-haskell hindent ghc-mod
And then configure them from Project Preferences > Haskell Tools. The Auto Find button will attempt to find this executable for you. These are configured on a per-project basis. You can set the defaults for all projects using File > Other Settings > Default Settings.
Note that for ghc-mod >= 5.4, ghc-modi has been deprecated. HaskForce will automatically configure it as ghc-mod legacy-interactive when applying the settings, but if you are upgrading you may need to do this yourself.
You can use the Haskell Tools Console to view the commands sent to and the output and/or errors received from your external tools like hlint, ghc-mod, and ghc-modi (which includes ghc-mod legacy-interactive). This is useful when debugging issues with your external tools' configuration or integration with HaskForce.
You can view the console by hovering over (or clicking) the tool pane icon in the bottom-left corner of the IDE, then choosing Haskell Tools Console.
Currently you can jump to the declaration of any top-level function or data/newtype declaration. There are some complex cases where this doesn't work perfectly (e.g. complicated, nested imports) but for most use cases it works well. Jumping to local definitions is currently under development.
One possible approach is to create a lib/ directory in your project, followed by stack unpack. For example, if you wish to be able to navigate to source of Scotty:
$ mkdir lib
$ cd lib
$ stack unpack scotty
Now you should be able to navigate to declaration/source using goto declaration, i.e:
usage
HaskForce currently implements the following autocompletion features -
-
Reference completion - This completion is based on the references captured from the functions you have defined at the top-level, along with data/newtype declarations. This works mostly in conjunction with the Jump to Declaration section above.
-
GHC-Mod completion - This completion is more complex and gets you many more features. It does require you to set the paths to ghc-mod and optionally ghc-modi in your external tool settings. With GHC-Mod you get completion of -
- Language extensions in
LANGUAGEpragmas. - GHC flags in
OPTIONS_GHCpragmas. - Module names in imports.
- Language extensions in
-
GHC-Modi completion - Same as above, except you get -
- Name import completion -
import Data.ByteString (reareadFile) - Qualified name completion -
Data.ByteString.reareadFile - Prelude and imported name completion -
foo = getLgetLine
- Name import completion -
Note that retrieving completion information can be expensive so it is cached frequently. If you find that your completion cache needs to be updated, you can use Code > Haskell Completion Cache Reload. This is currently mapped to Ctrl+Shift+Space (Command+Shift+Space on OSX).
Error checking is supplied with ghc-mod or ghc-modi. Error reporting turnaround time can be nearly 4 times faster with ghc-modi, so in most cases that is probably the best route. If IntelliJ is slow to respond at times, you may want to lower ghc-modi's Timeout in the Haskell Tools settings.
Please note that the ghc-mod tools currently have experimental support for multiple cabal components. If you have trouble with error checking in test suites, they can be Test suite components can be enabled simply by reconfiguring with tests enabled (this can be done via Preferences > Compiler > Haskell Compiler > Enable Tests and a rebuild or manually on the command line with cabal configure --enable-tests).
HaskForce relies on ghc-mod to tell give it warnings about missing top-level signatures to provide you the suggestions to add them. If you have ghc-mod configured and you are not getting suggestions to automatically
add type signatures, you may need to supply the -fwarn-missing-signatures flag to GHC. This can be done
in a few different ways -
-
Added
ghc-options: -fwarn-missing-signaturesto your Cabal file. This is probably the most desirable approach. -
Using a
{-# OPTIONS_GHC -fwarn-missing-signatures #-}pragma at the top of the Haskell source file. This is probably mostly useful for debugging the issue or just getting the warning in specific files. -
Adding
-g -fwarn-missing-signaturesto the flags list when configuring ghc-mod and ghc-modi in the Haskell Tools settings. This might be an option for you if, for whatever reason, you can't or shouldn't change theghc-optionsin the Cabal file.
There are two supported builders: Stack and Cabal. Normally, your builder is configured when you create or import your project. You can also configure it by going to Build, Execution, Deployment > Compiler > Haskell Compiler and choosing either Build with Stack or Build with Cabal.
After building your application, errors should be reported in the Messages pane. You can jump to the source locations of the errors by double clicking on the messages.
Note: Run configurations are not supported for stack at the moment. This is for cabal projects only.
HaskForce currently supports two run types: cabal run and cabal test. You can find these via the Edit Configurations menu. Use the Program Arguments parameter to specify alternative run configurations from the cabal file or other command line arguments.