[cvs pull from ross; haddock documentation
ijones@syntaxpolice.org**20050210153546] {
hunk ./Distribution/PreProcess.hs 66
--- |A preprocessor must fulfill this basic interface. It can be an
--- external program, or just a function.
+-- |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 inFile outFile verbose
+-- > = do when (verbose > 0) $
+-- > putStrLn (inFile++" has been preprocessed to "++outFile)
+-- > stuff <- readFile inFile
+-- > writeFile outFile ("-- preprocessed as a test\n\n" ++ stuff)
+-- > return ExitSuccess
+--
hunk ./Distribution/PreProcess.hs 269
+-- |Standard preprocessors: GreenCard, c2hs, hsc2hs, happy, alex and cpphs.
hunk ./Distribution/Simple.hs 51
+ module Distribution.Version,
hunk ./Distribution/Simple.hs 53
- Version(..), VersionRange(..),
- orLaterVersion, orEarlierVersion, betweenVersionsInclusive,
- Extension(..), Dependency(..),
- defaultMain, defaultMainNoRead, defaultMainWithHooks,
- UserHooks(..), Args, defaultUserHooks, emptyUserHooks,
+ module Distribution.Extension,
+ -- * Simple interface
+ defaultMain, defaultMainNoRead,
+ -- * Customization
+ UserHooks(..), Args,
+ defaultMainWithHooks, defaultUserHooks, emptyUserHooks,
hunk ./Distribution/Simple.hs 85
-import Distribution.Extension (Extension(..))
-import Distribution.Version (Version(..), VersionRange(..), Dependency(..),
- orLaterVersion, orEarlierVersion,
- betweenVersionsInclusive)
+import Distribution.Extension
+import Distribution.Version
hunk ./Distribution/Simple.hs 110
+-- | Hooks allow authors to add specific functionality before and after
+-- a command is run, and also to specify additional preprocessors.
hunk ./Distribution/Simple.hs 116
- hookedPreProcessors :: [ PPSuffixHandler ], -- ^Add custom preprocessors
+ hookedPreProcessors :: [ PPSuffixHandler ],
+ -- ^Custom preprocessors in addition to 'knownSuffixHandlers'.
hunk ./Distribution/Simple.hs 148
--- |Reads the package description file using IO.
+-- |A simple implementation of @main@ for a Cabal setup script.
+-- It reads the package description file using IO, and performs the
+-- action specified on the command line.
hunk ./Distribution/Simple.hs 158
+-- | A customizable version of 'defaultMain'.
hunk ./Distribution/Simple.hs 171
--- |Accept description as input rather than using IO to read it.
+-- |Like 'defaultMain', but accepts the package description as input
+-- rather than using IO to read it.
hunk ./doc/Cabal.xml 5
- Distribution.PreProcess'>
hunk ./doc/Cabal.xml 43
- does not work very well; if the executables depend on the library,
- they must explicitly list the modules they use from that
- library.
+ does not work very well; if the executables depend on the library,
+ they must explicitly list all the modules they directly or
+ indirectly import from that library.
hunk ./doc/Cabal.xml 80
- Suppose you have a directory hierarchy containing the files
- that make up your package. You will need to add two more files
- to the root directory of the package:
+
+ Suppose you have a directory hierarchy containing the source
+ files that make up your package. You will need to add two more
+ files to the root directory of the package:
hunk ./doc/Cabal.xml 135
+ A package containing executable programs
+
+Name: TestPackage
+Version: 0.0
+License: BSD3
+Author: Angela Author
+Build-Depends: HUnit
+
+Executable: program1
+Main-Is: Main.hs
+Hs-Source-Dir: prog1
+
+Executable: program2
+Main-Is: Main.hs
+Hs-Source-Dir: prog2
+Hidden-Modules: Utils
+ with Setup.hs the same as above.
+
+
+
hunk ./doc/Cabal.xml 166
-Hidden-Modules: A, B
hunk ./doc/Cabal.xml 167
+Hidden-Modules: A, B
hunk ./doc/Cabal.xml 171
-Hidden-Modules: C
hunk ./doc/Cabal.xml 172
-Hidden-Modules: Utils
+Hidden-Modules: A, C, Utils
hunk ./doc/Cabal.xml 338
-
hunk ./doc/Cabal.xml 339
+
+
+ Module names may correspond to Haskell source files, i.e.
+ with names ending in .hs
+ or .lhs
, or to inputs for
+ various Haskell preprocessors. The simple build infrastructure
+ understands
+ .gc
(GreenCard),
+ .chs
(c2hs),
+ .hsc
(hsc2hs),
+ .y
and
+ .ly
(happy),
+ .x
(alex)
+ and
+ .cpphs
(cpphs).
+ In such cases the appropriate preprocessor will be run
+ automatically as required.
+
+
hunk ./doc/Cabal.xml 360
+
hunk ./doc/Cabal.xml 363
+
hunk ./doc/Cabal.xml 367
+
hunk ./doc/Cabal.xml 673
- Customizing the simple build infrastructure using
- hooks. See for details.
+ You can customize the simple build infrastructure using
+ hooks. These allow you to perform
+ additional actions before and after each command is run,
+ and also to specify additional preprocessors. See &Simple;
+ for the details.
hunk ./doc/Cabal.xml 682
- though this is unlikely to be very portable.
-
- Cabal supports this with a trivial setup library &Make;,
+ though this is unlikely to be very portable.
+ Cabal supports this with a trivial setup library &Make;,
hunk ./doc/Cabal.xml 699
- Writing your own setup script conforming to the
- interface of , possibly using the
- Cabal library for part of the work. One option is to copy
- the source of Distribution.Simple, and alter it for your
- needs. Good luck.
+ You can write your own setup script conforming to the
+ interface of , possibly using the
+ Cabal library for part of the work. One option is to copy the
+ source of Distribution.Simple, and alter it for your needs.
+ Good luck.
hunk ./doc/Cabal.xml 1004
-
-
-
-
- Preprocessors and Customization
-
- As mentioned in , there
- are a number of ways to customize your packages. Preprocessors
- like cpp allow you to call out to external programs to alter your
- source files. "User Hooks" allow you to add your own
- functionality before and after a command is run. (see also
- &Simple;)
-
-
- PreProcessors
-
- Some more complex packages may require the use of
- preprocessors. There is a set of "built-in" preprocessors in
- the module Distribution.PreProcess, including Greencard, C2hs,
- Hsc2hs, Alex, Happy, and cpphs.
-
- The behavior of preprocessors is pretty straightforward.
- If your package includes module "P", Cabal will first try to
- find P.hs or P.lhs. Failing that, it looks for suffixes
- relating to known preprocessors, such as P.cpphs. If it finds
- P.cpphs, Cabal will generate P.hs from that and build it.
-
- If you want to use a preprocessor that's not defined in
- Distribution.PreProcess.knownSuffixHandlers, you may define your
- own and provide them as hooks (see ). A
- "SuffixHandler" has the following type.
-
-type PPSuffixHandler
- = (String, -- The extension
- BuildInfo -> LocalBuildInfo -> PreProcessor)
-
-type PreProcessor = FilePath -- Location of source to preprocess
- -> FilePath -- Output filename
- -> Int -- verbose
- -> IO ExitCode
-
-
- For more information see &PreProcess;.
-
- You might therefore create your own preprocessor which,
- for example prepends a comment to the given source file. This
- definition would appear in your Setup.lhs file.
-
-
- A Custom PreProcessor
-
-ppTestHandler :: FilePath -- ^InFile
- -> FilePath -- ^OutFile
- -> Int -- ^verbose
- -> IO ExitCode
-ppTestHandler inFile outFile verbose
- = do when (verbose > 0) $
- putStrLn (inFile++" has been preprocessed to "++outFile)
- stuff <- readFile inFile
- writeFile outFile ("-- preprocessed as a test\n\n" ++ stuff)
- return ExitSuccess
-
-
- This preprocessor must then be hooked into your Setup
- file with the function defaultMainWithHooks.
- See for more details.
-
-
-