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]
- cradleErrorLoadingFiles :: [FilePath]
}
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 Source #

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 Source #
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) Source #
Instance details Defined in HIE.Bios.Types Methods showsPrec :: Int -> Cradle a -> ShowS # show :: Cradle a -> String # showList :: [Cradle a] -> ShowS #

data CradleLoadResult r Source #

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 Source #
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 Source #
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 Source #
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 Source #
Instance details Defined in HIE.Bios.Types Methods fmap :: (a -> b) -> CradleLoadResult a -> CradleLoadResult b # (<$) :: a -> CradleLoadResult b -> CradleLoadResult a #
Monad CradleLoadResult Source #
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) Source #
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) Source #
Instance details Defined in HIE.Bios.Types Methods (==) :: CradleLoadResult r -> CradleLoadResult r -> Bool # (/=) :: CradleLoadResult r -> CradleLoadResult r -> Bool #

data CradleError Source #

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.
cradleErrorLoadingFiles :: [FilePath]
files that were attempted to be loaded by the cradle. This can be useful if we are loading multiple files at once, e.g. in a cabal cradle with the multi-repl feature.

Instances

Instances details

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

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

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

Given root/hie.yaml load the Cradle.

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

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

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

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

Compiler Options

data ComponentOptions Source #

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

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

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

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.