Distribution.Simple.Program.Types

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

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]

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

Constructors

ProgramSearchPathDir FilePath | A specific dir
ProgramSearchPathDefault | The system default

simpleProgram :: String -> Program

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

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 |
Read ConfiguredProgram |
Show ConfiguredProgram |
Generic ConfiguredProgram |
Binary ConfiguredProgram |
type Rep ConfiguredProgram |

programPath :: ConfiguredProgram -> FilePath

The full path of a configured program.

suppressOverrideArgs :: ConfiguredProgram -> ConfiguredProgram

Suppress any extra arguments added by the user.

type ProgArg = String

data ProgramLocation

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 |
Read ProgramLocation |
Show ProgramLocation |
Generic ProgramLocation |
Binary ProgramLocation |
type Rep ProgramLocation |

simpleConfiguredProgram :: String -> ProgramLocation -> ConfiguredProgram

Make a simple `ConfiguredProgram`.

    simpleConfiguredProgram "foo" (FoundOnSystem path)