Cabal-1.22.5.0: A framework for packaging Haskell software

Copyright | Isaac Jones 2006, Duncan Coutts 2007-2009
Maintainer | cabal-devel@haskell.org
Portability | portable
Safe Haskell | None
Language | Haskell98

Distribution.Simple.Program.Types

Contents

- Program and functions for constructing them
- Configured program and related functions

Description

This provides an abstraction which deals with configuring and running programs. A `Program` is a static notion of a known program. A `ConfiguredProgram` is a `Program` that has been found on the current machine and is ready to be run (possibly with some user-supplied default args). Configuring a program involves finding its location and if necessary finding its version. There's reasonable default behavior for trying to find "foo" in PATH, being able to override its location, etc.

Synopsis

- data Program = Program {
  - programName :: String
  - programFindLocation :: Verbosity -> ProgramSearchPath -> IO (Maybe FilePath)
  - programFindVersion :: Verbosity -> FilePath -> IO (Maybe Version)
  - programPostConf :: Verbosity -> ConfiguredProgram -> IO ConfiguredProgram
  }
- type ProgramSearchPath = [ProgramSearchPathEntry]
- data ProgramSearchPathEntry
  - = ProgramSearchPathDir FilePath
  - | ProgramSearchPathDefault
- simpleProgram :: String -> Program
- data ConfiguredProgram = ConfiguredProgram {
  - programId :: String
  - programVersion :: Maybe Version
  - programDefaultArgs :: [String]
  - programOverrideArgs :: [String]
  - programOverrideEnv :: [(String, Maybe String)]
  - programProperties :: Map String String
  - programLocation :: ProgramLocation
  }
- programPath :: ConfiguredProgram -> FilePath
- suppressOverrideArgs :: ConfiguredProgram -> ConfiguredProgram
- type ProgArg = String
- data ProgramLocation
  - = UserSpecified {
    - locationPath :: FilePath
    }
  - | FoundOnSystem {
    - locationPath :: FilePath
    }
- simpleConfiguredProgram :: String -> ProgramLocation -> ConfiguredProgram

# Program and functions for constructing them

data Program Source

Represents a program which can be configured.

Note: rather than constructing this directly, start with `simpleProgram` and override any extra fields.

Constructors

Program |

Fields

programName :: String

  The simple name of the program, eg. ghc

programFindLocation :: Verbosity -> ProgramSearchPath -> IO (Maybe FilePath)

  A function to search for the program if its location was not specified by the user. Usually this will just be a call to `findProgramOnSearchPath`.

  It is supplied with the prevailing search path which will typically just be used as-is, but can be extended or ignored as needed.

programFindVersion :: Verbosity -> FilePath -> IO (Maybe Version)

  Try to find the version of the program. For many programs this is not possible or is not necessary so it's OK to return Nothing.

programPostConf :: Verbosity -> ConfiguredProgram -> IO ConfiguredProgram

  A function to do any additional configuration after we have located the program (and perhaps identified its version). For example it could add args, or environment vars.

type ProgramSearchPath = [ProgramSearchPathEntry] Source

A search path to use when locating executables. This is analogous to the unix `$PATH` or win32 `%PATH%` but with the ability to use the system default method for finding executables (`findExecutable` which on unix is simply looking on the `$PATH` but on win32 is a bit more complicated).

The default to use is `[ProgSearchPathDefault]` but you can add extra dirs either before, after or instead of the default, e.g. here we add an extra dir to search after the usual ones.

    ['ProgramSearchPathDefault', 'ProgramSearchPathDir' dir]

data ProgramSearchPathEntry Source

Constructors

ProgramSearchPathDir FilePath | A specific dir
ProgramSearchPathDefault | The system default

simpleProgram :: String -> Program Source

Make a simple named program.

By default we'll just search for it in the path and not try to find the version name. You can override these behaviours if necessary, eg:

    simpleProgram "foo" { programFindLocation = ... , programFindVersion ... }

# Configured program and related functions

data ConfiguredProgram Source

Represents a program which has been configured and is thus ready to be run.

These are usually made by configuring a `Program`, but if you have to construct one directly then start with `simpleConfiguredProgram` and override any extra fields.

Constructors

ConfiguredProgram |

Fields

programId :: String

  Just the name again

programVersion :: Maybe Version

  The version of this program, if it is known.

programDefaultArgs :: [String]

  Default command-line args for this program. These flags will appear first on the command line, so they can be overridden by subsequent flags.

programOverrideArgs :: [String]

  Override command-line args for this program. These flags will appear last on the command line, so they override all earlier flags.

programOverrideEnv :: [(String, Maybe String)]

  Override environment variables for this program. These env vars will extend/override the prevailing environment of the current to form the environment for the new process.

programProperties :: Map String String

  A key-value map listing various properties of the program, useful for feature detection. Populated during the configuration step, key names depend on the specific program.

programLocation :: ProgramLocation

  Location of the program. eg. `/usr/bin/ghc-6.4`

Instances

Eq ConfiguredProgram Source |
Read ConfiguredProgram Source |
Show ConfiguredProgram Source |
Generic ConfiguredProgram Source |
Binary ConfiguredProgram Source |
type Rep ConfiguredProgram Source |

programPath :: ConfiguredProgram -> FilePath Source

The full path of a configured program.

suppressOverrideArgs :: ConfiguredProgram -> ConfiguredProgram Source

Suppress any extra arguments added by the user.

type ProgArg = String Source

data ProgramLocation Source

Where a program was found. Also tells us whether it's specified by user or not. This includes not just the path, but the program as well.

Constructors

UserSpecified | The user gave the path to this program, eg. --ghc-path=/usr/bin/ghc-6.6

Fields

locationPath :: FilePath

FoundOnSystem | The program was found automatically.

Fields

locationPath :: FilePath

Instances

Eq ProgramLocation Source |
Read ProgramLocation Source |
Show ProgramLocation Source |
Generic ProgramLocation Source |
Binary ProgramLocation Source |
type Rep ProgramLocation Source |

simpleConfiguredProgram :: String -> ProgramLocation -> ConfiguredProgram Source

Make a simple `ConfiguredProgram`.

    simpleConfiguredProgram "foo" (FoundOnSystem path)