Documentation: Examples of flags generated by a bios cradle

[chris-martin]

I've had a few rough starts understanding what this project is all about. (Some specific manifestations of my confusion are documented at haskell/haskell-language-server#1901, for the curious.) Now that I'm better getting the hang of it, I've been doing some retrospective thinking about what sort of documentation that might have helped me.

I think it would be great if the documentation illustrated the types of cradles by example.

• A cabal file, and the GHC flags that get generated when using it in a "cabal" cradle.
• A simple "bios" cradle, and what its output looks like.

[fendor]

That is indeed a good idea!

I think the README is already a bit overloaded, do you think this information is so crucial it should be in the README or should there be a docs/ directory containing the relevant info?

[chris-martin]

That is a good question. While I ponder, let me ask another: Is there an easy way to ask hie-bios to show me the ghc args that a cradle outputs? Simply telling users how to experiment for themselves might go a long way with minimal addition to the docs.

[fendor]

Yeah, the executable that comes with hie-bios which you can install via cabal intall hie-bios or stack install hie-bios offers an interface for debugging.

> hie-bios --help
hie-bios version 0.8.0 compiled by GHC 8.10.2

Usage: hie-bios COMMAND
  hie-bios is the way to specify how haskell-language-server and ghcide set up a
  GHC API session.Delivers the full set of flags to pass to GHC in order to
  build the project.

Available options:
  -h,--help                Show this help text

Available commands:
  check                    Try to load modules into the GHC API.
  flags                    Print out the options that hie-bios thinks you will
                           need to load a file.
  debug                    Print out the options that hie-bios thinks you will
                           need to load a file.
  config                   Print out the cradle config.
  cradle                   .
  root                     Display the path towards the selected hie.yaml.
  version                  Print version and exit.

You can report issues/contribute at https://github.com/mpickering/hie-bios

E.g.:

> hie-bios debug src/HIE/Bios.hs
Root directory:        /home/hugin/Documents/haskell/hie-bios
Component directory:   /home/hugin/Documents/haskell/hie-bios
GHC options:           -fbuilding-cabal-package -O0 -outputdir /home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/build/x86_64-linux/ghc-8.10.2/hie-bios-0.8.0/build -odir /home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/build/x86_64-linux/ghc-8.10.2/hie-bios-0.8.0/build -hidir /home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/build/x86_64-linux/ghc-8.10.2/hie-bios-0.8.0/build -stubdir /home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/build/x86_64-linux/ghc-8.10.2/hie-bios-0.8.0/build -i -i/home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/build/x86_64-linux/ghc-8.10.2/hie-bios-0.8.0/build -isrc -i/home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/build/x86_64-linux/ghc-8.10.2/hie-bios-0.8.0/build/autogen -i/home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/build/x86_64-linux/ghc-8.10.2/hie-bios-0.8.0/build/global-autogen -I/home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/build/x86_64-linux/ghc-8.10.2/hie-bios-0.8.0/build/autogen -I/home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/build/x86_64-linux/ghc-8.10.2/hie-bios-0.8.0/build/global-autogen -I/home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/build/x86_64-linux/ghc-8.10.2/hie-bios-0.8.0/build -optP-include -optP/home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/build/x86_64-linux/ghc-8.10.2/hie-bios-0.8.0/build/autogen/cabal_macros.h -this-unit-id hie-bios-0.8.0-inplace -hide-all-packages -Wmissing-home-modules -no-user-package-db -package-db /home/hugin/.cabal/store/ghc-8.10.2/package.db -package-db /home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/packagedb/ghc-8.10.2 -package-db /home/hugin/.cache/hie-bios/dist-hie-bios-e7a73b2ffd58a3db6a855ec871bcd65b/build/x86_64-linux/ghc-8.10.2/hie-bios-0.8.0/package.conf.inplace -package-id aeson-1.5.6.0-2075850e0374fbf7e282ba67495988d64c7f4aac29474c848a99e1f9a8303552 -package-id base-4.14.1.0 -package-id base16-bytestring-1.0.1.0-9f11fc286491f106a9ef784dbd62d74f1270ad38dd03d9b8cbaa41c1bbf814c8 -package-id bytestring-0.10.10.0 -package-id conduit-1.3.4.1-54d150862fbd0cc24b8b9a269645e0feee09185e41ff968cd169a070d5f71b33 -package-id conduit-extra-1.3.5-21bb52352b998de2bd9c545988fc034e0aec6197e1879fac4bc532d5ea90c92c -package-id containers-0.6.2.1 -package-id cryptohash-sha1-0.11.100.1-14baaf787c73c6727e20fcfc7a790bc5174c4e306aed060b8c8b6b1ef8651fc8 -package-id deepseq-1.4.4.0 -package-id directory-1.3.6.0 -package-id extra-1.7.9-6f94da3821f2f5df7b0cd80e72f6f8ebd26d26ff383fd20a81fabf8cc11bc903 -package-id file-embed-0.0.14.0-3ddf48073a38149a26bf6bf84c6c26d6f1a6f10460254ac7d5391780bb8d09c6 -package-id filepath-1.4.2.1 -package-id ghc-8.10.2 -package-id hslogger-1.3.1.0-c997b23894a2d45d19be3f5156253479f2c186bee8f9e9cd2613f70091acba49 -package-id process-1.6.9.0 -package-id temporary-1.3-a2f4de1637445b855d4cd15fa2ba342f6f2240f26890409692ddf6040856a06d -package-id text-1.2.3.2 -package-id time-1.9.3 -package-id transformers-0.5.6.2 -package-id unix-compat-0.5.3-c6c5849e8649617a1bd8cefc425ea49ceb3e617460fe5c23a2305e03a8efe5cb -package-id unordered-containers-0.2.14.0-2e0a245e7aafabf17c35bc444786a396306e63a00e99aa8cb8b22059cfb0d1df -package-id vector-0.12.3.0-5cacb8cde54a34ce5fc6fa72c797cbac9526692e6b6615a4135e90a8df4747d9 -package-id yaml-0.11.5.0-a1a1ae625876da4c6b690ef405530d6c0d468fa1fbf8908855650a06ce071c98 -XHaskell2010 HIE.Bios HIE.Bios.Config HIE.Bios.Cradle HIE.Bios.Environment HIE.Bios.Internal.Debug HIE.Bios.Flags HIE.Bios.Types HIE.Bios.Internal.Log HIE.Bios.Ghc.Api HIE.Bios.Ghc.Check HIE.Bios.Ghc.Doc HIE.Bios.Ghc.Gap HIE.Bios.Ghc.Load HIE.Bios.Ghc.Logger HIE.Bios.Wrappers Paths_hie_bios -Wall -hide-all-packages
GHC library directory: CradleSuccess "/home/hugin/.ghcup/ghc/8.10.2/lib/ghc-8.10.2"
GHC version:           CradleSuccess "8.10.2"
Config Location:       /home/hugin/Documents/haskell/hie-bios/hie.yaml
Cradle:                Cradle {cradleRootDir = "/home/hugin/Documents/haskell/hie-bios", cradleOptsProg = CradleAction: Cabal}
Dependencies:          hie-bios.cabal cabal.project cabal.project.local

[chris-martin]

Hm, I see. It might be worth mentioning, in the bios section, that when you're writing a bios program, you may want to try using hie-bios debug on a source file in the context of a cabal project, and look at the "GHC options" part of the output to get an idea of what kind of things should be in the output of a bios program.

Although it's a bit unfortunate how difficult it is to wade through the output of debug to find relevant options. Cabal sure does dump out a lot of stuff.