hie-bios

hie-bios is the way to specify how hie and ghcide sets up a GHC API session.

Given a Haskell project that is managed by Stack, Cabal, or other package tools, hie needs to know the full set of flags to pass to GHC in order to build the project. hie-bios satisfies this need.

Its design is motivated by the guiding principle:

It is the responsibility of the build tool to describe the environment which a package should be built in.

Using this principle, it is possible to easily support a wide range of tools including cabal-install, stack, rules_haskell, hadrian and obelisk without major contortions. hie-bios does not depend on the Cabal library nor does not read any complicated build products and so on.

How does a tool specify a session? A session is fully specified by a set of standard GHC flags. Most tools already produce this information if they support a repl command. Launching a repl is achieved by calling ghci with the right flags to specify the package database. hie-bios needs a way to get these flags and then it can set up GHC API session correctly.

Futher it means that any failure to set up the API session is the responsibility of the build tool. It is up to them to provide the correct information if they want the tool to work correctly.

Explicit Configuration

The user can place a hie.yaml file in the root of the workspace which describes how to setup the environment. For example, to explicitly state that you want to use stack then the configuration file would look like:

cradle: {stack: {component: "haskell-ide-engine:lib" }}

While the component is optional, this is recommended to make sure the correct component is loaded.

To use cabal, the explicit configuration looks similar. Note that cabal and stack have different way of specifying their components.

cradle: {cabal: {component: "lib:haskell-ide-engine"}}

Or you can explicitly state the program which should be used to collect the options by supplying the path to the program. It is interpreted relative to the current working directory if it is not an absolute path. The bios program should consult the HIE_BIOS_OUTPUT env var and write a list of options to this file separated by newlines. Once the program finishes running hie-bios reads this file and uses the arguments to set up the GHC session. This is how GHC's build system is able to support hie-bios.

cradle: {bios: {program: ".hie-bios"}}

The direct cradle allows you to specify exactly the GHC options that should be used to load a project. This is good for debugging but not a very good approach in general as the set of options will quickly get out of sync with a cabal file.

cradle: {direct: [arg1, arg2]}

The none cradle says that the IDE shouldn't even try to load the project. It is most useful when combined with the multi-cradle which is specified in the next section.

cradle: {none: }

Multi-Cradle

For a multi-component project you can use the multi-cradle to specify how each subdirectory of the project should be handled by the IDE.

The multi-cradle is a list of relative paths and cradle configurations. The path is relative to the configuration file and specifies the scope of the cradle. For example, this configuration specificies that files in the src subdirectory should be handled with the lib:hie-bios component and files in the test directory using the test component.

cradle:
  multi:
    - path: "./src"
      config: { cradle: {cabal: {component: "lib:hie-bios"}} }
    - path: "./test"
      config: { cradle: {cabal: {component: "test"}} }

If a file matches multiple prefixes, the most specific one is chosen. Once a prefix is matched, the selected cradle is used to find the options. This is usually a specific cradle such as cabal or stack but it could be another multi-cradle, in which case, matching works in exactly the same way until a specific cradle is chosen.

This cradle type is experimental and may not be supported correctly by some libraries which use hie-bios. It requires some additional care to correctly manage multiple components.

Note: Remember you can use the multi-cradle to declare that certain directories shouldn't be loaded by an IDE, in conjunction with the none cradle.

cradle:
  multi:
    - path: "./src"
      config: { cradle: {cabal: {component: "lib:hie-bios"}} }
    - path: "./test"
      config: { cradle: {cabal: {component: "test"}} }
    - path: "./test/test-files"
      config: { cradle: { none: } }

For cabal and stack projects there is a shorthand to specify how to load each component.

cradle:
  cabal:
    - path: "./src"
      component: "lib:hie-bios"
    - path: "./test"
      component: "test:bios-tests"

cradle:
  stack:
    - path: "./src"
      component: "hie-bios:lib"
    - path: "./test"
      component: "hie-bios:test:bios-tests"

Remember you can combine this shorthand with more complicated configuration as well.

cradle:
  multi:
    - path: "./test/testdata"
      config: { cradle: { none:  } }
    - path: "./"
      config: { cradle: { cabal:
                            [ { path: "./src", component: "lib:hie-bios" }
                            , { path: "./tests", component: "parser-tests" } ] } }

Cradle Dependencies

Sometimes it is necessary to reload a component, for example when a package dependency is added to the project. Each type of cradle defines a list of files that might cause an existing cradle to no longer provide accurate diagnostics if changed. These are expected to be relative to the root of the cradle.

This makes it possible to watch for changes to these files and reload the cradle appropiately. However, if there are files that are not covered by the cradle dependency resolution, you can add these files explicitly to hie.yaml. These files are not required to actually exist, since it can be useful to know when these files are created, e.g. if there was no cabal.project in the project before and now there is, it might change how a file in the project is compiled.

Here's an example of how you would add cradle dependencies that may not be covered by the cabal cradle.

cradle:
  cabal:
    component: "lib:hie-bios"

dependencies:
  - package.yaml
  - shell.nix
  - default.nix

For the Bios cradle type, there is an optional field to specify a program to obtain cradle dependencies from:

cradle:
  bios:
    program: ./flags.sh
    dependency-program: ./dependency.sh

The program ./dependency.sh is executed with no paramaters and it is expected to output on stdout on each line exactly one filepath relative to the root of the cradle, not relative to the location of the program.

Configuration specification

The complete configuration is a subset of

cradle:
  cabal:
    component: "optional component name"
  stack:
    component: "optional component name"
  bios:
    program: "program to run"
    dependency-program: "optional program to run"
  direct:
    arguments: ["list","of","ghc","arguments"]
  none:
  multi: - path: ./
           config: { cradle: ... }

dependencies:
  - someDep

Testing your configuration

The provided hie-bios executable is provided to test your configuration.

The flags command will print out the options that hie-bios thinks you will need to load a file.

hie-bios flags exe/Main.hs

The check command will try to use these flags to load the module into the GHC API.

hie-bios check exe/Main.hs

Implicit Configuration

There are several built in modes which captures most common Haskell development scenarios. If no hie.yaml configuration file is found then an implicit configuration is searched for. It is strongly recommended to just explicitly configure your project.

Priority

The targets are searched for in following order.

A specific hie-bios file.
A stack project
A cabal project
The direct cradle which has no specific options.

`cabal-install`

The workspace root is the first folder containing a cabal.project file.

The arguments are collected by running cabal v2-repl.

If cabal v2-repl fails, then the user needs to configure the correct target to use by writing a hie.yaml file.

`stack`

The workspace root is the first folder containing a stack.yaml file.

The arguments are collected by executing stack repl.

`bios`

The most general form is the bios mode which allows a user to specify themselves which flags to provide.

In this mode, an executable file called .hie-bios is placed in the root of the workspace directory. The script takes one argument, the filepath to the current file we want to load into the session. The script returns a list of GHC arguments separated by newlines which will setup the correct session.

A good guiding specification for this file is that the following command should work for any file in your project.

ghci $(./hie-bios /path/to/foo.hs | tr '\n' ' ') /path/to/foo.hs

This is useful if you are designing a new build system or the other modes fail to setup the correct session for some reason. For example, this is how hadrian (GHC's build system) is integrated into hie-bios.

Supporting Bazel and Obelisk

In previous versions of hie-bios there was also support for projects using rules_haskell and obelisk. This was removed in the 0.3 release as they were unused and broken. There is no conceptual barrier to adding back support but it requires a user of these two approaches to maintain them.

csasarak/hie-bios