Cabal-3.12.1.0: A framework for packaging Haskell software

Copyright | (c) 2003-2005 Isaac Jones Malcolm Wallace
License | BSD3
Maintainer | cabal-devel@haskell.org
Portability | portable
Safe Haskell | None
Language | Haskell2010

Distribution.Simple.PreProcess

Description

This module defines `PPSuffixHandler`, which is a combination of a file extension and a function for configuring a `PreProcessor`. It also defines a bunch of known built-in preprocessors like `cpp`, `cpphs`, `c2hs`, `hsc2hs`, `happy`, `alex` etc and lists them in `knownSuffixHandlers`. On top of this it provides a function for actually preprocessing some sources given a bunch of known suffix handlers. This module is not as good as it could be, it could really do with a rewrite to address some of the problems we have with pre-processors.

Synopsis

- preprocessComponent :: PackageDescription -> Component -> LocalBuildInfo -> ComponentLocalBuildInfo -> Bool -> Verbosity -> [PPSuffixHandler] -> IO ()
- preprocessExtras :: Verbosity -> Component -> LocalBuildInfo -> IO [FilePath]
- knownSuffixHandlers :: [PPSuffixHandler]
- ppSuffixes :: [PPSuffixHandler] -> [Suffix]
- type PPSuffixHandler = (Suffix, BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor)
- newtype Suffix = Suffix String
- builtinHaskellSuffixes :: [Suffix]
- builtinHaskellBootSuffixes :: [Suffix]
- data PreProcessor = PreProcessor {
  - platformIndependent :: Bool
  - ppOrdering :: Verbosity -> [FilePath] -> [ModuleName] -> IO [ModuleName]
  - runPreProcessor :: (FilePath, FilePath) -> (FilePath, FilePath) -> Verbosity -> IO ()
  }
- mkSimplePreProcessor :: (FilePath -> FilePath -> Verbosity -> IO ()) -> (FilePath, FilePath) -> (FilePath, FilePath) -> Verbosity -> IO ()
- runSimplePreProcessor :: PreProcessor -> FilePath -> FilePath -> Verbosity -> IO ()
- ppCpp :: BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor
- ppCpp' :: [String] -> BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor
- ppGreenCard :: BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor
- ppC2hs :: BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor
- ppHsc2hs :: BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor
- ppHappy :: BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor
- ppAlex :: BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor
- ppUnlit :: PreProcessor
- platformDefines :: LocalBuildInfo -> [String]
- unsorted :: Verbosity -> [FilePath] -> [ModuleName] -> IO [ModuleName]

# Documentation

preprocessComponent :: PackageDescription -> Component -> LocalBuildInfo -> ComponentLocalBuildInfo -> Bool -> Verbosity -> [PPSuffixHandler] -> IO () Source #

Apply preprocessors to the sources from `hsSourceDirs` for a given component (lib, exe, or test suite).

XXX: This is terrible

preprocessExtras :: Verbosity -> Component -> LocalBuildInfo -> IO [FilePath] Source #

Find any extra C sources generated by preprocessing that need to be added to the component (addresses issue #238).

knownSuffixHandlers :: [PPSuffixHandler] Source #

Standard preprocessors: GreenCard, c2hs, hsc2hs, happy, alex and cpphs.

ppSuffixes :: [PPSuffixHandler] -> [Suffix] Source #

Convenience function; get the suffixes of these preprocessors.

type PPSuffixHandler = (Suffix, BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor) Source #

A preprocessor for turning non-Haskell files with the given `Suffix` (i.e. file extension) into plain Haskell source files.

newtype Suffix Source #

A suffix (or file extension).

Mostly used to decide which preprocessor to use, e.g. files with suffix `"y"` are usually processed by the `"happy"` build tool.

Constructors

Suffix String |

#### Instances

Instances details

Pretty Suffix Source # |
Instance details Defined in Distribution.Simple.PreProcess.Types Methods pretty :: Suffix -> Doc Source # prettyVersioned :: CabalSpecVersion -> Suffix -> Doc Source #
Structured Suffix Source # |
Instance details Defined in Distribution.Simple.PreProcess.Types Methods structure :: Proxy Suffix -> Structure Source # structureHash' :: Tagged Suffix MD5
Binary Suffix Source # |
Instance details Defined in Distribution.Simple.PreProcess.Types Methods put :: Suffix -> Put # get :: Get Suffix # putList :: [Suffix] -> Put #
IsString Suffix Source # |
Instance details Defined in Distribution.Simple.PreProcess.Types Methods fromString :: String -> Suffix #
Generic Suffix Source # |

Instance details

Defined in Distribution.Simple.PreProcess.Types

Associated Types

type Rep Suffix |
Instance details Defined in Distribution.Simple.PreProcess.Types type Rep Suffix = D1 ('MetaData "Suffix" "Distribution.Simple.PreProcess.Types" "Cabal-3.12.1.0-cda0" 'True) (C1 ('MetaCons "Suffix" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)))

Methods

from :: Suffix -> Rep Suffix x #

to :: Rep Suffix x -> Suffix #

Show Suffix Source # |
Instance details Defined in Distribution.Simple.PreProcess.Types Methods showsPrec :: Int -> Suffix -> ShowS # show :: Suffix -> String # showList :: [Suffix] -> ShowS #
Eq Suffix Source # |
Instance details Defined in Distribution.Simple.PreProcess.Types Methods (==) :: Suffix -> Suffix -> Bool # (/=) :: Suffix -> Suffix -> Bool #
Ord Suffix Source # |
Instance details Defined in Distribution.Simple.PreProcess.Types Methods compare :: Suffix -> Suffix -> Ordering # (<) :: Suffix -> Suffix -> Bool # (<=) :: Suffix -> Suffix -> Bool # (>) :: Suffix -> Suffix -> Bool # (>=) :: Suffix -> Suffix -> Bool # max :: Suffix -> Suffix -> Suffix # min :: Suffix -> Suffix -> Suffix #
type Rep Suffix Source # |
Instance details Defined in Distribution.Simple.PreProcess.Types type Rep Suffix = D1 ('MetaData "Suffix" "Distribution.Simple.PreProcess.Types" "Cabal-3.12.1.0-cda0" 'True) (C1 ('MetaCons "Suffix" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)))

builtinHaskellSuffixes :: [Suffix] Source #

builtinHaskellBootSuffixes :: [Suffix] Source #

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

Fields

- platformIndependent :: Bool
- ppOrdering :: Verbosity -> [FilePath] -> [ModuleName] -> IO [ModuleName]

  This function can reorder all modules, not just those that the require the preprocessor in question. As such, this function should be well-behaved and not reorder modules it doesn't have dominion over!

  Since: Cabal-3.8.1.0

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

ppCpp :: BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor Source #

ppCpp' :: [String] -> BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor Source #

ppGreenCard :: BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor Source #

ppC2hs :: BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor Source #

ppHsc2hs :: BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor Source #

ppHappy :: BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor Source #

ppAlex :: BuildInfo -> LocalBuildInfo -> ComponentLocalBuildInfo -> PreProcessor Source #

ppUnlit :: PreProcessor Source #

platformDefines :: LocalBuildInfo -> [String] Source #

unsorted :: Verbosity -> [FilePath] -> [ModuleName] -> IO [ModuleName] Source #

Just present the modules in the order given; this is the default and it is appropriate for preprocessors which do not have any sort of dependencies between modules.