Cabal-1.2.3.0: A framework for packaging Haskell softwareSource codeContentsIndex
Distribution.Simple.PreProcess
Portabilityportable
Stabilityalpha
MaintainerIsaac Jones <ijones@syntaxpolice.org>
Description
PreProcessors are programs or functions which input a filename and output a Haskell file. The general form of a preprocessor is input Foo.pp and output Foo.hs (where pp is a unique extension that tells us which preprocessor to use eg. gc, ly, cpphs, x, y, etc.). Once a PreProcessor has been added to Cabal, either here or with UserHooks, if Cabal finds a Foo.pp, it'll run the given preprocessor which should output a Foo.hs.
Synopsis
preprocessSources :: PackageDescription -> LocalBuildInfo -> Bool -> Verbosity -> [PPSuffixHandler] -> IO ()
knownSuffixHandlers :: [PPSuffixHandler]
ppSuffixes :: [PPSuffixHandler] -> [String]
type PPSuffixHandler = (String, BuildInfo -> LocalBuildInfo -> PreProcessor)
data PreProcessor = PreProcessor {
platformIndependent :: Bool
runPreProcessor :: ((FilePath, FilePath) -> (FilePath, FilePath) -> Verbosity -> IO ())
}
mkSimplePreProcessor :: (FilePath -> FilePath -> Verbosity -> IO ()) -> (FilePath, FilePath) -> (FilePath, FilePath) -> Verbosity -> IO ()
runSimplePreProcessor :: PreProcessor -> FilePath -> FilePath -> Verbosity -> IO ()
removePreprocessed :: [FilePath] -> [String] -> [String] -> IO ()
removePreprocessedPackage :: PackageDescription -> FilePath -> [String] -> IO ()
ppCpp :: BuildInfo -> LocalBuildInfo -> PreProcessor
ppCpp' :: [String] -> BuildInfo -> LocalBuildInfo -> PreProcessor
ppGreenCard :: BuildInfo -> LocalBuildInfo -> PreProcessor
ppC2hs :: BuildInfo -> LocalBuildInfo -> PreProcessor
ppHsc2hs :: BuildInfo -> LocalBuildInfo -> PreProcessor
ppHappy :: BuildInfo -> LocalBuildInfo -> PreProcessor
ppAlex :: BuildInfo -> LocalBuildInfo -> PreProcessor
ppUnlit :: PreProcessor
Documentation
preprocessSourcesSource
:: PackageDescription
-> LocalBuildInfo
-> BoolBuild for SDist
-> Verbosityverbosity
-> [PPSuffixHandler]preprocessors to try
-> IO ()
Apply preprocessors to the sources from hsSourceDirs, to obtain a Haskell source file for each module.
knownSuffixHandlers :: [PPSuffixHandler]Source
Standard preprocessors: GreenCard, c2hs, hsc2hs, happy, alex and cpphs.
ppSuffixes :: [PPSuffixHandler] -> [String]Source
Convenience function; get the suffixes of these preprocessors.
type PPSuffixHandler = (String, BuildInfo -> LocalBuildInfo -> PreProcessor)Source
A preprocessor for turning non-Haskell files with the given extension into plain Haskell source files.
data PreProcessor Source

The interface to a preprocessor, which may be implemented using an external program, but need not be. The arguments are the name of the input file, the name of the output file and a verbosity level. Here is a simple example that merely prepends a comment to the given source file:

 ppTestHandler :: PreProcessor
 ppTestHandler =
   PreProcessor {
     platformIndependent = True,
     runPreProcessor = mkSimplePreProcessor $ \inFile outFile verbosity ->
       do info verbosity (inFile++" has been preprocessed to "++outFile)
          stuff <- readFile inFile
          writeFile outFile ("-- preprocessed as a test\n\n" ++ stuff)
          return ExitSuccess

We split the input and output file names into a base directory and the rest of the file name. The input base dir is the path in the list of search dirs that this file was found in. The output base dir is the build dir where all the generated source files are put.

The reason for splitting it up this way is that some pre-processors don't simply generate one output .hs file from one input file but have dependencies on other genereated files (notably c2hs, where building one .hs file may require reading other .chi files, and then compiling the .hs file may require reading a generated .h file). In these cases the generated files need to embed relative path names to each other (eg the generated .hs file mentions the .h file in the FFI imports). This path must be relative to the base directory where the genereated files are located, it cannot be relative to the top level of the build tree because the compilers do not look for .h files relative to there, ie we do not use "-I .", instead we use "-I dist/build" (or whatever dist dir has been set by the user)

Most pre-processors do not care of course, so mkSimplePreProcessor and runSimplePreProcessor functions handle the simple case.

Constructors
PreProcessor
platformIndependent :: Bool
runPreProcessor :: ((FilePath, FilePath) -> (FilePath, FilePath) -> Verbosity -> IO ())
mkSimplePreProcessor :: (FilePath -> FilePath -> Verbosity -> IO ()) -> (FilePath, FilePath) -> (FilePath, FilePath) -> Verbosity -> IO ()Source
runSimplePreProcessor :: PreProcessor -> FilePath -> FilePath -> Verbosity -> IO ()Source
removePreprocessedSource
:: [FilePath]search Location
-> [String]Modules
-> [String]suffixes
-> IO ()
Remove the preprocessed .hs files. (do we need to get some .lhs files too?)
removePreprocessedPackageSource
:: PackageDescription
-> FilePathroot of source tree (where to look for hsSources)
-> [String]suffixes
-> IO ()
ppCpp :: BuildInfo -> LocalBuildInfo -> PreProcessorSource
ppCpp' :: [String] -> BuildInfo -> LocalBuildInfo -> PreProcessorSource
ppGreenCard :: BuildInfo -> LocalBuildInfo -> PreProcessorSource
ppC2hs :: BuildInfo -> LocalBuildInfo -> PreProcessorSource
ppHsc2hs :: BuildInfo -> LocalBuildInfo -> PreProcessorSource
ppHappy :: BuildInfo -> LocalBuildInfo -> PreProcessorSource
ppAlex :: BuildInfo -> LocalBuildInfo -> PreProcessorSource
ppUnlit :: PreProcessorSource
Produced by Haddock version 0.8