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

Safe Haskell | Safe-Inferred
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
  }
- data CradleLoadResult r
  - = CradleSuccess r
  - | CradleFail CradleError
  - | CradleNone
- data CradleError = CradleError {
  - cradleErrorDependencies :: [FilePath]
  - cradleErrorExitCode :: ExitCode
  - cradleErrorStderr :: [String]
  }
- findCradle :: FilePath -> IO (Maybe FilePath)
- loadCradle :: FilePath -> IO (Cradle Void)
- loadImplicitCradle :: Show a => FilePath -> IO (Cradle a)
- defaultCradle :: FilePath -> Cradle a
- data ComponentOptions = ComponentOptions {
  - componentOptions :: [String]
  - componentRoot :: FilePath
  - componentDependencies :: [FilePath]
  }
- getCompilerOptions :: LogAction IO (WithSeverity Log) -> FilePath -> 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.

#### 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

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)
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 #
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
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.

loadCradle :: FilePath -> IO (Cradle Void) #

Given root/hie.yaml load the Cradle.

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

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

defaultCradle :: 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 :: LogAction IO (WithSeverity Log) -> FilePath -> 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.