|
|
|
|
|
| Description |
| An interface to a Haskell compiler, providing the facilities of a
compilation manager.
|
|
| Synopsis |
|
|
|
|
| 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 | |  Instances | |
|
|
| 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 | |
|
|
| 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 |
| :: 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 | | | Instances | |
|
|
| 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 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 |
| :: 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
|
|
|
| Produced by Haddock version 0.8 |
