{"id":15010871,"url":"https://github.com/haskell/hie-bios","last_synced_at":"2025-05-15T06:04:32.059Z","repository":{"id":37788616,"uuid":"191973023","full_name":"haskell/hie-bios","owner":"haskell","description":"Set up a GHC API session for various Haskell Projects","archived":false,"fork":false,"pushed_at":"2025-04-26T13:24:57.000Z","size":607,"stargazers_count":191,"open_issues_count":40,"forks_count":65,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-08T17:05:55.701Z","etag":null,"topics":["haskell"],"latest_commit_sha":null,"homepage":"https://hackage.haskell.org/package/hie-bios","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/haskell.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-06-14T16:13:34.000Z","updated_at":"2025-05-01T20:23:28.000Z","dependencies_parsed_at":"2025-01-17T17:05:14.230Z","dependency_job_id":"61db5496-889b-42b4-b4ea-73b22c8f6110","html_url":"https://github.com/haskell/hie-bios","commit_stats":{"total_commits":306,"total_committers":43,"mean_commits":7.116279069767442,"dds":0.7745098039215687,"last_synced_commit":"8d9e184afc3eea9ef494c88381f7fb305e2d7cb0"},"previous_names":["mpickering/hie-bios"],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haskell%2Fhie-bios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haskell%2Fhie-bios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haskell%2Fhie-bios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haskell%2Fhie-bios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haskell","download_url":"https://codeload.github.com/haskell/hie-bios/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254283337,"owners_count":22045140,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["haskell"],"created_at":"2024-09-24T19:36:46.902Z","updated_at":"2025-05-15T06:04:32.040Z","avatar_url":"https://github.com/haskell.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hie-bios\n\n- [hie-bios](#hie-bios)\n  - [Explicit Configuration](#explicit-configuration)\n    - [Stack](#stack)\n      - [Debugging a `stack` cradle](#debugging-a-stack-cradle)\n      - [Ignoring directories](#ignoring-directories)\n      - [Internal Libraries](#internal-libraries)\n    - [Cabal](#cabal)\n      - [Debugging a `cabal` cradle](#debugging-a-cabal-cradle)\n      - [Ignoring directories](#ignoring-directories-1)\n    - [Bios](#bios)\n      - [Debugging a `bios` cradle](#debugging-a-bios-cradle)\n    - [Direct](#direct)\n      - [Debugging a `direct` cradle](#debugging-a-direct-cradle)\n    - [None](#none)\n  - [Multi-Cradle](#multi-cradle)\n  - [Cradle Dependencies](#cradle-dependencies)\n  - [Configuration specification](#configuration-specification)\n  - [Testing your configuration](#testing-your-configuration)\n  - [Implicit Configuration](#implicit-configuration)\n    - [Priority](#priority)\n    - [`cabal-install`](#cabal-install)\n    - [`stack`](#stack-1)\n    - [`bios`](#bios-1)\n  - [Supporting Bazel and Obelisk](#supporting-bazel-and-obelisk)\n\n`hie-bios` is the way to specify how\n[`haskell-language-server`](https://github.com/haskell/haskell-language-server)\nand [`ghcide`](https://github.com/digital-asset/ghcide) set up a GHC API session.\n\nGiven a Haskell project that is managed by Stack, Cabal, or other package tools,\n`haskell-language-server` needs to know the full set of flags to pass to GHC in\norder to build the project. These flags might contain some compilation options\nlike `-O2`, but a lot of the time they are package dependencies such as\n`-package-id directory-1.3.6.0`, which also need to be built beforehand.\n`hie-bios` satisfies both these needs.\n\nIts design is motivated by the guiding principle:\n\n\u003e It is the responsibility of the build tool to describe the environment\n\u003e which a package should be built in.\n\nUsing this principle, it is possible\nto easily support a wide range of tools including `cabal-install`, `stack`,\n`rules_haskell`, `hadrian` and `obelisk` without major contortions.\n`hie-bios` does not depend on the `Cabal` library nor does it\nread any complicated build products and so on.\n\nHow does a tool specify a session? A session is fully specified by a set of\nstandard GHC flags. Most tools already produce this information if they support\na `repl` command. Launching a repl is achieved by calling `ghci` with the\nright flags to specify the package database. `hie-bios` needs a way to get\nthese flags and then it can set up a GHC API session correctly.\n\nFurther it means that any failure to set up the API session is the responsibility\nof the build tool. It is up to them to provide the correct information if they\nwant the tool to work correctly.\n\n## Explicit Configuration\n\nThe user can place a `hie.yaml` file in the root of the workspace which\ndescribes how to set up the environment. There are several supported ways to setup the environment.\n\n### Stack\n\nTo explicitly state that you want to use `stack`, the basic configuration `hie.yaml` would look like:\n\n```yaml\ncradle:\n  stack:\n```\n\nThis configuration suffices if your whole project can be loaded by the command `stack repl`. As a rule of thumb, this works if the project consists of only one executable, one library and one test-suite.\n\nSome projects have multiple `stack-*.yaml` files for multiple versions of ghc/resolvers. In this case you\ncan specify an alternate relative file to use by using the `stackYaml` option. The path is relative to the\nconfiguration file.\n\n```yaml\ncradle:\n  stack:\n    stackYaml: \"./stack-8.8.3.yaml\"\n```\n\nIf your project is more complicated, you need to specify which [components](https://docs.haskellstack.org/en/stable/build_command/#components) you want to load. A component is, roughly speaking, a library/executable/test-suite or benchmark in `stack`. You can view the components/targets of a stack project by executing the command:\n``` sh\n$ stack ide targets\n```\n\nSince we have two test-suites, one executable and a library, for `hie-bios`, this would output the following:\n\n``` sh\n$ stack ide targets\nhie-bios:lib\nhie-bios:exe:hie-bios\nhie-bios:test:bios-tests\nhie-bios:test:parser-tests\n```\n\nFor an explanation of the target syntax, we refer to the documentation of the [target syntax](https://docs.haskellstack.org/en/stable/build_command/#target-syntax).\n\nTo tell `hie-bios` which component it should load, the following `hie.yaml` can be used:\n\n```yaml\ncradle:\n  stack:\n    component: \"\u003ccomponent name\u003e\"\n```\n\nwhere `\u003ccomponent name\u003e` is the name of the component/target you want to load.\nWhile the component is optional, this is recommended to make sure the correct component is loaded.\n\nWhy is this not enough? Usually, you have multiple components with different dependencies. Your library won't depend on `tasty` or `hspec`, but your test-suite might. With this setup, you would only be able to load files from the given component.\n\nSince you rarely only want to load a single component in a `stack` project, we have special syntax to be able to conveniently specify which directory belongs to which component. It is basically a [multi-cradle](#multi-cradle).\n\n```yaml\ncradle:\n  stack:\n    - path: \"./src\"\n      component: \"hie-bios:lib\"\n    - path: \"./exe\"\n      component: \"hie-bios:exe:hie-bios\"\n    - path: \"./tests/BiosTests.hs\"\n      component: \"hie-bios:test:hie-bios\"\n    - path: \"./tests/ParserTests.hs\"\n      component: \"hie-bios:test:parser-tests\"\n```\n\nHere you can see two important features:\n  * We provide a mapping from a filepath to component.\n    * That way, we specify that a file such as `./src/HIE/Bios.hs` belongs to the component `hie-bios:lib`.\n  * The filepath can be a file.\n    * This is convenient if components are overlapping.\n\nThis way we specified which component needs to be compiled given a source file for our whole project.\n\nIf you use both, multiple components and an alternate `stack.yaml` file, there is a way to specify defaults\nfor the path-specific configurations.\n\n```yaml\ncradle:\n  stack:\n    stackYaml: \"stack-8.3.3.yaml\"\n    components:\n    - path: \"./src\"\n      component: \"hie-bios:lib\"\n    - path: \"./exe\"\n      component: \"hie-bios:exe:hie-bios\"\n    - path: \"./tests/BiosTests.hs\"\n      component: \"hie-bios:test:hie-bios\"\n    - path: \"./tests/ParserTests.hs\"\n      component: \"hie-bios:test:parser-tests\"\n```\n\nA word of warning: Due to current restrictions in the language server, as mentioned in [this bug report](https://github.com/haskell/haskell-language-server/issues/268#issuecomment-667640809) all referenced stack.yaml files must specify the same version of GHC, as only one version of ghcide is loaded at a time per workspace root. This restriction might be lifted in the future.\n\n#### Debugging a `stack` cradle\n\nIf you find that `hie-bios` can't load a certain component or file, run `stack repl` and `stack repl \u003ccomponent name\u003e` to see if `stack` succeeds in building your project. Chances are that there is a problem in your project and if you fix that, `hie-bios` will succeed to load it.\n\nAlso, see notes for [testing your configuration](#testing-your-configuration).\n\nOtherwise, please open an [issue](https://github.com/mpickering/hie-bios/issues/new).\n\n#### Ignoring directories\n\nYou can combine the [multi-cradle](#multi-cradle) with a [none-cradle](#none-cradle) to ignore all source files in a certain directory. The syntax is a bit verbose:\n\n```yaml\ncradle:\n  multi:\n    - path: \"./tests/projects\"\n      config:\n        cradle:\n          none:\n    - path: \"./\"\n      config:\n        cradle:\n          stack:\n            - path: \"./src\"\n              component: \"hie-bios:lib\"\n            - path: \"./exe\"\n              component: \"hie-bios:exe:hie-bios\"\n            - path: \"./tests/BiosTests.hs\"\n              component: \"hie-bios:test:hie-bios\"\n            - path: \"./tests/ParserTests.hs\"\n              component: \"hie-bios:test:parser-tests\"\n```\n\nThis way, we specify that we do not want to load any files in our test project directories.\n\n#### Internal Libraries\n\nInternal libraries are not well supported in `stack`. Since the syntax `stack repl \u003cinternal library name\u003e` [doesn't work](https://github.com/commercialhaskell/stack/issues/4564), `hie-bios` will generally not work with internal libraries using `stack`.\n\n### Cabal\n\nTo use `cabal`, the basic explicit configuration looks similar to `stack`'s configuration.\n\n```yaml\ncradle:\n  cabal:\n```\n\nThe implication of this configuration is a bit different, though. Given a source file to load, we will use `cabal repl \u003cfilename\u003e` to find the component of the given filepath.\n\nThis configuration should work in (almost) every standard project setup, since `cabal` finds the component associated to a given source file.\nHowever, due to an unfortunate [bug](https://github.com/haskell/cabal/issues/6622), this fails on some files with `cabal` versions older than `3.4`.\nSo, to make your project loadable by older `cabal` versions, you can specify a component to load.\nA [component](https://cabal.readthedocs.io/en/latest/nix-local-build.html?highlight=component#cabal-v2-build) is roughly speaking a library, executable, test-suite or benchmark in `cabal`.\nThe `hie.yaml` file looks like this:\n\n```yaml\ncradle:\n  cabal:\n    component: \u003ccomponent name\u003e\n```\n\nThis tells `hie-bios` that whichever source file it tries to load, this source file should be handled as if it belongs to `\u003ccomponent name\u003e`.\n\nAs an example, to load the library of `hie-bios`, the following `hie.yaml` can be used:\n\n```yaml\ncradle:\n  cabal:\n    component: \"lib:hie-bios\"\n```\n\nThe component syntax `\"lib:hie-bios\"` refers to the library of the package `hie-bios`. For a complete reference of the component syntax, we refer to the [documentation](https://cabal.readthedocs.io/en/latest/nix-local-build.html?highlight=component#cabal-v2-build).\n\nNote that `cabal` and `stack` have different ways of specifying their\ncomponents.\n\n\nIf we only specify a single component, then we can only load source files from this component. This is unsatisfactory as we want to be able to navigate our project freely and work on multiple components (test-suite, library, executable, etc...) in parallel.\n\nIn a project such as `hie-bios`, we have more than one component, in particular we have four:\n\n * An executable\n * A library\n * Two test-suites\n\nThe component syntax can easily be extracted from the `hie-bios.cabal` file. Relevant sections are:\n\n```cabal\n...\nName:                   hie-bios\n...\n\nLibrary\n  ...\n  HS-Source-Dirs:       src\n\nExecutable hie-bios\n  ...\n  Main-Is:              Main.hs\n  HS-Source-Dirs:       exe\n\ntest-suite parser-tests\n  ...\n  hs-source-dirs: tests/\n  main-is: ParserTests.hs\n\ntest-suite bios-tests\n  ...\n  hs-source-dirs: tests/\n  main-is: BiosTests.hs\n```\n\nUsing the documentation of cabal, we extract the four component names of the `hie-bios` project:\n\n* `lib:hie-bios`\n* `exe:hie-bios`\n* `test:bios-tests`\n* `test:parser-tests`\n\nSince you rarely only want to load a single component in a `cabal` project, we have special syntax to be able to conveniently specify which directory belongs to which component. It is basically a [multi-cradle](#multi-cradle).\n\n```yaml\ncradle:\n  cabal:\n    - path: \"./src\"\n      component: \"lib:hie-bios\"\n    - path: \"./exe\"\n      component: \"exe:hie-bios\"\n    - path: \"./tests/BiosTests.hs\"\n      component: \"test:hie-bios\"\n    - path: \"./tests/ParserTests.hs\"\n      component: \"test:parser-tests\"\n```\n\nHere you can see two important features:\n  * We provide a mapping from filepath to component.\n    * That way, we specify that a file such as `./src/HIE/Bios.hs` belongs to the component `lib:hie-bios`.\n  * The filepath can be a file.\n    * This is convenient if components are overlapping.\n\nSimilarly to `multi-stack` configurations, you can also specify multiple components using a `components` subkey.\n\n```yaml\ncradle:\n  cabal:\n    components:\n    - path: \"./src\"\n      component: \"lib:hie-bios\"\n    - path: \"./exe\"\n      component: \"exe:hie-bios\"\n    - path: \"./tests/BiosTests.hs\"\n      component: \"test:hie-bios\"\n    - path: \"./tests/ParserTests.hs\"\n      component: \"test:parser-tests\"\n```\n\nThis way we specified which component needs to be compiled given a certain source file for our whole project.\n\nSome projects have multiple `cabal.project` files for multiple versions of ghc or development options. In this case you\ncan specify an alternate relative file to use by using the `cabalProject` option. The path is relative to the\n`hie.yaml`.\n\n```yaml\ncradle:\n  cabal:\n    cabalProject: \"./cabal.project.dev\"\n```\n\nWe can combine the `cabalProject` field with `components`:\n\n```yaml\ncradle:\n  cabal:\n    cabalProject: \"./cabal.project.dev\"\n    components:\n    - path: \"./src\"\n      component: \"lib:hie-bios\"\n    - path: \"./exe\"\n      component: \"exe:hie-bios\"\n    - path: \"./tests/BiosTests.hs\"\n      component: \"test:hie-bios\"\n    - path: \"./tests/ParserTests.hs\"\n      component: \"test:parser-tests\"\n```\n\n#### Debugging a `cabal` cradle\n\nIf you find that `hie-bios` can't load a certain component or file, you may run `cabal repl \u003cfilename\u003e` and `cabal repl \u003ccomponent name\u003e` to see if `cabal` succeeds in building the components. Chances are that there is a problem and if you fix that, `hie-bios` will succeed to load the project.\n\nAlso, see notes for [testing your configuration](#testing-your-configuration).\n\nOtherwise, please open an [issue](https://github.com/mpickering/hie-bios/issues/new).\n\n#### Ignoring directories\n\nYou can combine the [multi-cradle](#multi-cradle) with a [none-cradle](#none-cradle) to ignore all source files in a certain directory. The syntax is a bit verbose:\n\n```yaml\ncradle:\n  multi:\n    - path: \"./tests/projects\"\n      config:\n        cradle:\n          none:\n    - path: \"./\"\n      config:\n        cradle:\n          cabal:\n            - path: \"./src\"\n              component: \"lib:hie-bios\"\n            - path: \"./exe\"\n              component: \"exe:hie-bios\"\n            - path: \"./tests/BiosTests.hs\"\n              component: \"test:hie-bios\"\n            - path: \"./tests/ParserTests.hs\"\n              component: \"test:parser-tests\"\n```\n\nThis way, we specify that we do not want to load any files in our test project directories.\n\n### Bios\n\nAlternatively you can explicitly state a `program` or shell command which should\nbe used to collect the options. This is the most general approach and can be extended to handle arbitrary build systems.\n\nThe path of the `program` attribute is interpreted relative to the current\nworking directory if it isn't absolute. A program is passed the file to\nreturn options for as its first argument, and a shell command will have it\navailable in the `HIE_BIOS_ARG` environment variable.\n\nThere are two important environment variables:\n\n* `HIE_BIOS_OUTPUT`: describes the filepath the options should be written to. If this file does not exist, the `program` should create it.\n* `HIE_BIOS_ARG`: the source file that we want to load. Options returned by the `program` should be able to compile the given source file.\n  * This environment variable is *only* available if a shell program is given.\n\nThe program flow is roughly as follows:\nThe process must consult the `HIE_BIOS_OUTPUT` environment variable and write a\nlist of options to this file, separated by newlines. Once the process finishes\nrunning, `hie-bios` reads this file and uses the arguments to set up the GHC\nsession. This is how GHC's build system is able to support `hie-bios`.\nNote, the `program` is intended to produce the build flags to compile the *whole* component the given source file belongs to. This entails that the `program` lists all of the component's module- and file targets.\n\nA good guiding specification for this file is that the following commands\nshould work for any file in your project.\n\n``` sh\n$ export HIE_BIOS_OUTPUT=./options.txt # this is usually some temporary file\n$ ./\u003cprogram\u003e /path/to/foo.hs\n$ ghci $(cat $HIE_BIOS_OUTPUT | tr '\\n' ' ')\n```\n\nwhere `HIE_BIOS_OUTPUT` is some chosen output file and `HIE_BIOS_ARG` contains the file parameter.\n\nThe `hie.yaml` configuration looks like this:\n\n```yaml\ncradle:\n  bios:\n    program: \"\u003cprogram\u003e\"\n```\n\nAlternatively, you may specify shell code directly.\nThis is helpful, if your `program` executable consists of only a single call to another executable.\n\n```yaml\ncradle:\n  bios:\n    shell: \"\u003cbuild-tool flags $HIE_BIOS_ARG\u003e\"\n```\n\nAdditionally, you may specify the path to ghc. Otherwise, the one in the PATH will be used:\n\n```yaml\ncradle:\n  bios:\n    program: \"\u003cprogram\u003e\"\n    with-ghc: \"\u003cghc\u003e\"\n```\n#### Debugging a `bios` cradle\n\nThe most common error in creating `bios` cradle is to not list all targets of the component. Please make sure, that you always list all targets of the component, associated with the filepath you want to load.\n\nAlso, see notes for [testing your configuration](#testing-your-configuration).\n\n### Direct\n\nThe `direct` cradle allows you to specify exactly the GHC options that should be used to load\na project. This is good for debugging but not a very good approach in general as the set of options\nwill quickly get out of sync with a cabal file.\n\n```yaml\ncradle:\n  direct:\n    arguments: [arg1, arg2]\n```\n\n#### Debugging a `direct` cradle\n\nThe arguments of a `direct` cradle will be passed almost directly to `ghc`. If the command `ghc \u003ccradle arguments\u003e` succeeds, then `hie-bios` can load the project.\n\n### None\n\nThe `none` cradle says that the IDE shouldn't even try to load the project. It\nis most useful when combined with the [multi-cradle](#multi-cradle) which is specified in the next section.\n\n```yaml\ncradle:\n  none:\n```\n\n## Multi-Cradle\n\nFor a multi-component project you can use the multi-cradle to specify how each\nsubdirectory of the project should be handled by the IDE.\n\nThe multi-cradle is a list of relative paths and cradle configurations.\nThe path is relative to the configuration file and specifies the scope of\nthe cradle. For example, this configuration specifies that files in the\n`src` subdirectory should be handled with the `lib:hie-bios` component and\nfiles in the `test` directory using the `test:bios-tests` component.\n\n```yaml\ncradle:\n  multi:\n    - path: \"./src\"\n      config:\n        cradle:\n          cabal:\n            component: \"lib:hie-bios\"\n    - path: \"./test\"\n      config:\n        cradle:\n          cabal:\n            component: \"test:bios-tests\"\n```\n\nIf a file matches multiple prefixes, the most specific one is chosen.\nOnce a prefix is matched, the selected cradle is used to find the options. This\nis usually a specific cradle such as `cabal` or `stack` but it could be another\nmulti-cradle, in which case, matching works in exactly the same way until a\nspecific cradle is chosen.\n\nThis cradle type is experimental and may not be supported correctly by\nsome libraries which use `hie-bios`. It requires some additional care to\ncorrectly manage multiple components.\n\nNote: Remember you can use the multi-cradle to declare that certain directories\nshouldn't be loaded by an IDE, in conjunction with the `none` cradle.\n\n```yaml\ncradle:\n  multi:\n    - path: \"./src\"\n      config: { cradle: {cabal: {component: \"lib:hie-bios\"}} }\n    - path: \"./test\"\n      config: { cradle: {cabal: {component: \"test:bios-tests\"}} }\n    - path: \"./test/test-files\"\n      config: { cradle: { none: } }\n```\n\nFor cabal and stack projects there is a shorthand to specify how to load each component.\n\n```yaml\ncradle:\n  cabal:\n    - path: \"./src\"\n      component: \"lib:hie-bios\"\n    - path: \"./test\"\n      component: \"test:bios-tests\"\n```\n\n```yaml\ncradle:\n  stack:\n    - path: \"./src\"\n      component: \"hie-bios:lib\"\n    - path: \"./test\"\n      component: \"hie-bios:test:bios-tests\"\n```\n\nRemember you can combine this shorthand with more complicated configurations\nas well.\n\n```yaml\ncradle:\n  multi:\n    - path: \"./test/testdata\"\n      config: { cradle: { none:  } }\n    - path: \"./\"\n      config: { cradle: { cabal:\n                            [ { path: \"./src\", component: \"lib:hie-bios\" }\n                            , { path: \"./tests\", component: \"parser-tests\" } ] } }\n```\n\n## Cradle Dependencies\n\nSometimes it is necessary to reload a component, for example when a package\ndependency is added to the project. Each type of cradle defines a list of\nfiles that might cause an existing cradle to no longer provide accurate\ndiagnostics if changed. These are expected to be relative to the root of\nthe cradle.\n\nThis makes it possible to watch for changes to these files and reload the\ncradle appropiately.\nHowever, if there are files that are not covered by\nthe cradle dependency resolution, you can add these files explicitly to\n`hie.yaml`.\nThe file dependencies are not required to actually exist, since it can be useful\nto know when they are created, e.g. if there was no `cabal.project`\nin the project before and now there is, it might change how a file in the\nproject is compiled.\n\nHere's an example of how you would add cradle dependencies that may not be covered\nby the `cabal` cradle.\n\n```yaml\ncradle:\n  cabal:\n    component: \"lib:hie-bios\"\n\ndependencies:\n  - package.yaml\n  - shell.nix\n  - default.nix\n```\n\nFor the `Bios` cradle type, the newline-separated cradle dependencies must be written out\nto the file specified by the `HIE_BIOS_DEPS` environment variable.\n\nPrevious versions implemented a different mechanism for collecting cradle dependencies\nby means of a second program/shell field. This is still supported for backwards\ncompatibility:\n\n```yaml\ncradle:\n  bios:\n    dependency-program: ./dependency.sh\n```\n```yaml\ncradle:\n  bios:\n    dependency-shell: build-tool dependencies $HIE_BIOS_ARG \u003e $HIE_BIOS_OUTPUT\n```\n\n## Configuration specification\n\nThe complete configuration is a subset of\n\n```yaml\ncradle:\n  cabal:\n    component: \"optional component name\"\n  stack:\n    component: \"optional component name\"\n  bios:\n    program: \"program to run\"\n    dependency-program: \"optional program to run\"\n    shell: build-tool flags $HIE_BIOS_ARG\n    dependency-shell: build-tool dependencies $HIE_BIOS_ARG\n    with-ghc: \"optional path to ghc\"\n  direct:\n    arguments: [\"list\",\"of\",\"ghc\",\"arguments\"]\n  none:\n  multi: - path: ./\n           config: { cradle: ... }\n\ndependencies:\n  - someDep\n```\n\n## Testing your configuration\n\nThe given `hie-bios` executable is provided to test your configuration.\n\nThe `flags` command will print out the options that `hie-bios` thinks you will need to load a file.\n\n``` sh\n$ hie-bios flags exe/Main.hs\n```\n\nThe `check` command will try to use these flags to load the module into the GHC API.\n\n``` sh\n$ hie-bios check exe/Main.hs\n```\n\nThe `debug` command prints verbose information about the cradle, such as where the `hie.yaml` file was found, which file is loaded and the options that will eventually be used for loading a session.\n\n``` sh\n$ hie-bios debug exe/Main.hs\n```\n\n## Implicit Configuration\n\nThere are several built in modes which capture the most common Haskell development\nscenarios. If no `hie.yaml` configuration file is found then an implicit\nconfiguration is searched for. It is strongly recommended to just explicitly\nconfigure your project.\n\n### Priority\n\nThe targets are searched for in the following order.\n\n1. A specific `.hie-bios` file.\n2. A `stack` project\n3. A `cabal` project\n4. The direct cradle which has no specific options.\n\n### `cabal-install`\n\nThe workspace root is the first folder containing a `cabal.project` file.\n\nThe arguments are collected by running `cabal v2-repl \u003cfilename\u003e`.\n\nIf `cabal v2-repl \u003cfilename\u003e` fails, then the user needs to configure the correct\ntarget to use by writing a `hie.yaml` file.\n\n### `stack`\n\nThe workspace root is the first folder containing a `stack.yaml` file.\n\nThe arguments are collected by executing `stack repl`. If this fails, the user needs to configure the correct target to use by writing a `hie.yaml` file.\n\n### `bios`\n\nThe most general form is the `bios` mode which allows users to specify\nwhich flags to provide themselves.\n\nThe program will receive the file to return options for as its first argument.\n\nThe program flow is roughly as follows:\nThe process must consult the `HIE_BIOS_OUTPUT` environment variable and write a\nlist of options to the file pointed to by `HIE_BIOS_OUTPUT`, separated by newlines. Once the process finishes running, `hie-bios` reads this file and uses the arguments to set up the GHC\nsession. This is how GHC's build system is able to support `hie-bios`.\nNote, the `program` is intended to produce the build flags to compile the *whole* component the given source file belongs to. This entails that the `program` lists all of the component's module- and file targets.\n\nA good guiding specification for this file is that the following commands\nshould work for any file in your project.\n``` sh\n$ export HIE_BIOS_OUTPUT=./options.txt # this is usually some temporary file\n$ ./.hie-bios /path/to/foo.hs\n$ ghci $(cat $HIE_BIOS_OUTPUT | tr '\\n' ' ')\n```\n\nThis is useful if you are designing a new build system or the other modes\nfail to setup the correct session for some reason. For example, this is\nhow hadrian (GHC's build system) is integrated into `hie-bios`.\n\n## Supporting Bazel and Obelisk\n\nIn previous versions of `hie-bios` there was also support for projects using `rules_haskell` and `obelisk`.\nThis 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaskell%2Fhie-bios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaskell%2Fhie-bios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaskell%2Fhie-bios/lists"}