hie-bios-0.14.0: Set up a GHC API session

Safe Haskell | None
Language | Haskell2010

HIE.Bios

Contents

- Find and load a Cradle
- Compiler Options
- Initialising a GHC session from a Cradle
- Loading targets into a GHC session

Description

The HIE Bios

Provides an abstraction over the GHC Api to initialise a GHC session and loading modules in a project.

Defines the `hie.yaml` file specification. This is used to explicitly configure how a project should be built by GHC.

Synopsis

- data Cradle a = Cradle {
  - cradleRootDir :: FilePath
  - cradleOptsProg :: CradleAction a
  - cradleLogger :: LogAction IO (WithSeverity Log)
  }
- data CradleLoadResult r
  - = CradleSuccess r
  - | CradleFail CradleError
  - | CradleNone
- data CradleError = CradleError {
  - cradleErrorDependencies :: [FilePath]
  - cradleErrorExitCode :: ExitCode
  - cradleErrorStderr :: [String]
  }
- findCradle :: FilePath -> IO (Maybe FilePath)
- loadCradle :: LogAction IO (WithSeverity Log) -> FilePath -> IO (Cradle Void)
- loadImplicitCradle :: Show a => LogAction IO (WithSeverity Log) -> FilePath -> IO (Cradle a)
- defaultCradle :: LogAction IO (WithSeverity Log) -> FilePath -> Cradle a
- data ComponentOptions = ComponentOptions {
  - componentOptions :: [String]
  - componentRoot :: FilePath
  - componentDependencies :: [FilePath]
  }
- getCompilerOptions :: FilePath -> LoadStyle -> Cradle a -> IO (CradleLoadResult ComponentOptions)
- initSession :: GhcMonad m => ComponentOptions -> m [Target]
- loadFile :: GhcMonad m => LogAction IO (WithSeverity Log) -> (FilePath, FilePath) -> m (Maybe TypecheckedModule, [TypecheckedModule])

# Find and load a Cradle

data Cradle a #

The environment of a single `Cradle`. A `Cradle` is a unit for the respective build-system.

It contains the root directory of the `Cradle`, the name of the `Cradle` (for debugging purposes), and knows how to set up a GHC session that is able to compile files that are part of this `Cradle`.

A `Cradle` may be a single unit in the "cabal-install" context, or the whole package, comparable to how "stack" works.

Constructors

Cradle |

Fields

- cradleRootDir :: FilePath

  The project root directory.

- cradleOptsProg :: CradleAction a

  The action which needs to be executed to get the correct command line arguments.

- cradleLogger :: LogAction IO (WithSeverity Log)

#### Instances

Instances details

Functor Cradle # |
Instance details Defined in HIE.Bios.Types Methods fmap :: (a -> b) -> Cradle a -> Cradle b # (<$) :: a -> Cradle b -> Cradle a #
Show a => Show (Cradle a) # |
Instance details Defined in HIE.Bios.Types Methods showsPrec :: Int -> Cradle a -> ShowS # show :: Cradle a -> String # showList :: [Cradle a] -> ShowS #

data CradleLoadResult r #

Result of an attempt to set up a GHC session for a `Cradle`. This is the go-to error handling mechanism. When possible, this should be preferred over throwing exceptions.

Constructors

CradleSuccess r | The cradle succeeded and returned these options.
CradleFail CradleError | We tried to load the cradle and it failed.
CradleNone | No attempt was made to load the cradle.

#### Instances

Instances details

Applicative CradleLoadResult # |

Instance details

Defined in HIE.Bios.Types

Methods

pure :: a -> CradleLoadResult a #

(<*>) :: CradleLoadResult (a -> b) -> CradleLoadResult a -> CradleLoadResult b #

liftA2 :: (a -> b -> c) -> CradleLoadResult a -> CradleLoadResult b -> CradleLoadResult c #

(*>) :: CradleLoadResult a -> CradleLoadResult b -> CradleLoadResult b #

(<*) :: CradleLoadResult a -> CradleLoadResult b -> CradleLoadResult a #

Functor CradleLoadResult # |
Instance details Defined in HIE.Bios.Types Methods fmap :: (a -> b) -> CradleLoadResult a -> CradleLoadResult b # (<$) :: a -> CradleLoadResult b -> CradleLoadResult a #
Monad CradleLoadResult # |
Instance details Defined in HIE.Bios.Types Methods (>>=) :: CradleLoadResult a -> (a -> CradleLoadResult b) -> CradleLoadResult b # (>>) :: CradleLoadResult a -> CradleLoadResult b -> CradleLoadResult b # return :: a -> CradleLoadResult a #
Foldable CradleLoadResult # |

Instance details

Defined in HIE.Bios.Types

Methods

fold :: Monoid m => CradleLoadResult m -> m #

foldMap :: Monoid m => (a -> m) -> CradleLoadResult a -> m #

foldMap' :: Monoid m => (a -> m) -> CradleLoadResult a -> m #

foldr :: (a -> b -> b) -> b -> CradleLoadResult a -> b #

foldr' :: (a -> b -> b) -> b -> CradleLoadResult a -> b #

foldl :: (b -> a -> b) -> b -> CradleLoadResult a -> b #

foldl' :: (b -> a -> b) -> b -> CradleLoadResult a -> b #

foldr1 :: (a -> a -> a) -> CradleLoadResult a -> a #

foldl1 :: (a -> a -> a) -> CradleLoadResult a -> a #

toList :: CradleLoadResult a -> [a] #

null :: CradleLoadResult a -> Bool #

length :: CradleLoadResult a -> Int #

elem :: Eq a => a -> CradleLoadResult a -> Bool #

maximum :: Ord a => CradleLoadResult a -> a #

minimum :: Ord a => CradleLoadResult a -> a #

sum :: Num a => CradleLoadResult a -> a #

product :: Num a => CradleLoadResult a -> a #

Traversable CradleLoadResult # |
Instance details Defined in HIE.Bios.Types Methods traverse :: Applicative f => (a -> f b) -> CradleLoadResult a -> f (CradleLoadResult b) # sequenceA :: Applicative f => CradleLoadResult (f a) -> f (CradleLoadResult a) # mapM :: Monad m => (a -> m b) -> CradleLoadResult a -> m (CradleLoadResult b) # sequence :: Monad m => CradleLoadResult (m a) -> m (CradleLoadResult a) #
Show r => Show (CradleLoadResult r) # |
Instance details Defined in HIE.Bios.Types Methods showsPrec :: Int -> CradleLoadResult r -> ShowS # show :: CradleLoadResult r -> String # showList :: [CradleLoadResult r] -> ShowS #
Eq r => Eq (CradleLoadResult r) # |
Instance details Defined in HIE.Bios.Types Methods (==) :: CradleLoadResult r -> CradleLoadResult r -> Bool # (/=) :: CradleLoadResult r -> CradleLoadResult r -> Bool #

data CradleError #

Constructors

CradleError |

Fields

- cradleErrorDependencies :: [FilePath]

  Dependencies of the cradle that failed to load. Can be watched for changes to attempt a reload of the cradle.

- cradleErrorExitCode :: ExitCode

  ExitCode of the cradle loading mechanism.

- cradleErrorStderr :: [String]

  Standard error output that can be shown to users to explain the loading error.

#### Instances

Instances details

Exception CradleError # |
Instance details Defined in HIE.Bios.Types Methods toException :: CradleError -> SomeException # fromException :: SomeException -> Maybe CradleError # displayException :: CradleError -> String # backtraceDesired :: CradleError -> Bool #
Show CradleError # |
Instance details Defined in HIE.Bios.Types Methods showsPrec :: Int -> CradleError -> ShowS # show :: CradleError -> String # showList :: [CradleError] -> ShowS #
Eq CradleError # |
Instance details Defined in HIE.Bios.Types Methods (==) :: CradleError -> CradleError -> Bool # (/=) :: CradleError -> CradleError -> Bool #

findCradle :: FilePath -> IO (Maybe FilePath) #

Given `root/foo/bar.hs`, return `root/hie.yaml`, or wherever the yaml file was found.

Note, `findCradle` used to **not** work for directories and required a Haskell file. This has been fixed since `0.14.0`. However, `loadCradle` and `loadImplicitCradle` still require a Haskell source file and won't work properly with a directory parameter.

loadCradle :: LogAction IO (WithSeverity Log) -> FilePath -> IO (Cradle Void) #

Given root/hie.yaml load the Cradle.

loadImplicitCradle :: Show a => LogAction IO (WithSeverity Log) -> FilePath -> IO (Cradle a) #

Given root/foo/bar.hs, load an implicit cradle

defaultCradle :: LogAction IO (WithSeverity Log) -> FilePath -> Cradle a #

Default cradle has no special options, not very useful for loading modules.

# Compiler Options

data ComponentOptions #

Option information for GHC

Constructors

ComponentOptions |

Fields

- componentOptions :: [String]

  Command line options.

- componentRoot :: FilePath

  Root directory of the component. All `componentOptions` are either absolute, or relative to this directory.

- componentDependencies :: [FilePath]

  Dependencies of a cradle that might change the cradle. Contains both files specified in hie.yaml as well as specified by the build-tool if there is any. FilePaths are expected to be relative to the `cradleRootDir` to which this CradleAction belongs to. Files returned by this action might not actually exist. This is useful, because, sometimes, adding specific files changes the options that a Cradle may return, thus, needs reload as soon as these files are created.

#### Instances

Instances details

Show ComponentOptions # |
Instance details Defined in HIE.Bios.Types Methods showsPrec :: Int -> ComponentOptions -> ShowS # show :: ComponentOptions -> String # showList :: [ComponentOptions] -> ShowS #
Eq ComponentOptions # |
Instance details Defined in HIE.Bios.Types Methods (==) :: ComponentOptions -> ComponentOptions -> Bool # (/=) :: ComponentOptions -> ComponentOptions -> Bool #
Ord ComponentOptions # |

Instance details

Defined in HIE.Bios.Types

Methods

compare :: ComponentOptions -> ComponentOptions -> Ordering #

(<) :: ComponentOptions -> ComponentOptions -> Bool #

(<=) :: ComponentOptions -> ComponentOptions -> Bool #

(>) :: ComponentOptions -> ComponentOptions -> Bool #

(>=) :: ComponentOptions -> ComponentOptions -> Bool #

max :: ComponentOptions -> ComponentOptions -> ComponentOptions #

min :: ComponentOptions -> ComponentOptions -> ComponentOptions #

getCompilerOptions #

Arguments

:: FilePath | The file we are loading it because of
-> LoadStyle | previous files we might want to include in the build
-> Cradle a |
-> IO (CradleLoadResult ComponentOptions) |

Initialize the `DynFlags` relating to the compilation of a single file or GHC session according to the provided `Cradle`.

# Initialising a GHC session from a Cradle

initSession :: GhcMonad m => ComponentOptions -> m [Target] #

Start a GHC session and set some sensible options for tooling to use. Creates a folder in the cache directory to cache interface files to make reloading faster.

# Loading targets into a GHC session

loadFile #

Arguments

:: GhcMonad m |
=> LogAction IO (WithSeverity Log) |
-> (FilePath, FilePath) | Target file to load.
-> m (Maybe TypecheckedModule, [TypecheckedModule]) | Typechecked module and modules that had to be loaded for the target.

Load a target into the GHC session with the default messager which outputs updates in the same format as normal GHC.

The target is represented as a tuple. The tuple consists of the original filename and another file that contains the actual source code to compile.

If the message should configured, use `loadFileWithMessage`.

If the loading succeeds, the typechecked module is returned together with all the typechecked modules that had to be loaded in order to typecheck the given target.