System.Plugins.Make

An interface to a Haskell compiler, providing the facilities of a compilation manager.

The MakeStatus type

data MakeStatus

The MakeStatus type represents success or failure of compilation. Compilation can fail for the usual reasons: syntax errors, type errors and the like. The MakeFailure constructor returns any error messages produced by the compiler. MakeSuccess returns a MakeCode value, and the path to the object file produced.

Constructors

MakeSuccess MakeCode FilePath

compilation was successful

MakeFailure Errors

compilation failed

Instances

Eq MakeStatus

Show MakeStatus

The MakeCode type

data MakeCode

The MakeCode type is used when compilation is successful, to distinguish two cases: * The source file needed recompiling, and this was done * The source file was already up to date, recompilation was skipped

Constructors

ReComp

recompilation was performed

NotReq

recompilation was not required

Instances

Eq MakeCode

Show MakeCode

Compiling Haskell modules

make :: FilePath -> [Arg] -> IO MakeStatus

One-shot unconditional compilation of a single Haskell module. make behaves like 'ghc -c'. Extra arguments to ghc may be passed in the args parameter, they will be appended to the argument list. make always recompiles its target, whether or not it is out of date.

A side-effect of calling make is to have GHC produce a .hi file containing a list of package and objects that the source depends on. Subsequent calls to load will use this interface file to load module and library dependencies prior to loading the object itself.

makeAll :: FilePath -> [Arg] -> IO MakeStatus

makeAll recursively compiles any dependencies it can find using GHC's --make flag. Dependencies will be recompiled only if they are visible to ghc -- this may require passing appropriate include path flags in the args parameter. makeAll takes the top-level file as the first argument.

makeWith

Arguments

:: FilePath

a src file

-> FilePath

a syntax stub file

-> [Arg]

any required args

-> IO MakeStatus

path to an object file

This is a variety of make that first calls merge to combine the plugin source with a syntax stub. The result is then compiled. This is provided for EDSL authors who wish to add extra syntax to a user's source. It is important to note that the module and types from the second file argument are used to override any of those that appear in the first argument. For example, consider the following source files:

 module A where
 a :: Integer
 a = 1

and

 module B where
 a :: Int

Calling makeWith A B [] will merge the module name and types from module B into module A, generating a third file:

 {-# LINE 1 "A.hs" #-}
 module MxYz123 where
 {-# LINE 3 "B.hs" #-}
 a :: Int
 {-# LINE 4 "A.hs" #-}
 a = 1

Handling reecompilation

hasChanged :: Module -> IO Bool

hasChanged returns True if the module or any of its dependencies have older object files than source files. Defaults to True if some files couldn't be located.

hasChanged' :: [String] -> Module -> IO Bool

recompileAll :: Module -> [Arg] -> IO MakeStatus

recompileAll is like makeAll, but rather than relying on ghc --make, we explicitly check a module's dependencies using our internal map of module dependencies. Performance is thus better, and the result is more accurate.

recompileAll' :: [String] -> Module -> [Arg] -> IO MakeStatus

Merging together Haskell source files

data MergeStatus

An equivalent status for the preprocessor phase

Constructors

MergeSuccess MergeCode Args FilePath

the merge was successful

MergeFailure Errors

failure, and any errors returned

Instances

Eq MergeStatus

Show MergeStatus

type MergeCode = MakeCode

Merging may be avoided if the source files are older than an existing merged result. The MergeCode type indicates whether merging was performed, or whether it was unneccessary.

type Args = [Arg]

A list of String arguments

type Errors = [String]

Convience synonym

merge :: FilePath -> FilePath -> IO MergeStatus

Merge to source files into a temporary file. If we've tried to merge these two stub files before, then reuse the module name (helps recompilation checking)

The merging operation is extremely useful for providing extra default syntax. An EDSL user then need not worry about declaring module names, or having required imports. In this way, the stub file can also be used to provide syntax declarations that would be inconvenient to require of the plugin author.

merge will include any import and export declarations written in the stub, as well as any module name, so that plugin author's need not worry about this compulsory syntax. Additionally, if a plugin requires some non-standard library, which must be provided as a -package flag to GHC, they may specify this using the non-standard GLOBALOPTIONS pragma. Options specified in the source this way will be added to the command line. This is useful for users who wish to use GHC flags that cannot be specified using the conventional OPTIONS pragma. The merging operation uses the parser hs-plugins was configured with, either Language.Haskell or the HSX parser, to parse Haskell source files.

mergeTo :: FilePath -> FilePath -> FilePath -> IO MergeStatus

mergeTo behaves like merge, but we can specify the file in which to place output.

mergeToDir :: FilePath -> FilePath -> FilePath -> IO MergeStatus

mergeToDir behaves like merge, but lets you specify a target directory.

Cleaning up temporary files

makeClean :: FilePath -> IO ()

makeClean : assuming we some element of [f.hs,f.hi,f.o], remove the .hi and .o components. Silently ignore any missing components. /Does not remove .hs files/. To do that use makeCleaner. This would be useful for merged files, for example.

makeCleaner :: FilePath -> IO ()

Low-level compilation primitives

build

Arguments

:: FilePath

path to .hs source

-> FilePath

path to object file

-> [String]

any extra cmd line flags

-> IO [String]

Lower-level than make. Compile a .hs file to a .o file If the plugin needs to import an api (which should be almost everyone) then the ghc flags to find the api need to be provided as arguments