shake-0.19.8: Build system library, like Make, but more accurate dependencies.

Safe Haskell | None
Language | Haskell2010

Development.Shake.Config

Description

A module for parsing and using config files in a Shake build system. Config files consist of variable bindings, for example:

    # This is my Config file
    HEADERS_DIR = /path/to/dir
    CFLAGS = -g -I${HEADERS_DIR}
    CFLAGS = $CFLAGS -O2
    include extra/file.cfg

This defines the variable `HEADERS_DIR` (equal to `/path/to/dir`), and `CFLAGS` (equal to `-g -I/path/to/dir -O2`), and also includes the configuration statements in the file `extra/file.cfg`. The full lexical syntax for configuration files is defined here: https://ninja-build.org/manual.html#_lexical_syntax. The use of Ninja file syntax is due to convenience and the desire to reuse an externally-defined specification (but the choice of configuration language is mostly arbitrary).

To use the configuration file either use `readConfigFile` to parse the configuration file and use the values directly, or `usingConfigFile` and `getConfig` to track the configuration values, so they become build dependencies.

Synopsis

- readConfigFile :: FilePath -> IO (HashMap String String)
- readConfigFileWithEnv :: [(String, String)] -> FilePath -> IO (HashMap String String)
- usingConfigFile :: FilePath -> Rules ()
- usingConfig :: HashMap String String -> Rules ()
- getConfig :: String -> Action (Maybe String)
- getConfigKeys :: Action [String]

# Documentation

readConfigFile :: FilePath -> IO (HashMap String String) #

Read a config file, returning a list of the variables and their bindings. Config files use the Ninja lexical syntax: https://ninja-build.org/manual.html#_lexical_syntax

readConfigFileWithEnv :: [(String, String)] -> FilePath -> IO (HashMap String String) #

Read a config file with an initial environment, returning a list of the variables and their bindings. Config files use the Ninja lexical syntax: https://ninja-build.org/manual.html#_lexical_syntax

usingConfigFile :: FilePath -> Rules () #

Specify the file to use with `getConfig`.

usingConfig :: HashMap String String -> Rules () #

Specify the values to use with `getConfig`, generally prefer `usingConfigFile` unless you also need access to the values of variables outside `Action`.

getConfig :: String -> Action (Maybe String) #

Obtain the value of a configuration variable, returns `Nothing` to indicate the variable has no binding. Any build system using `getConfig` must call either `usingConfigFile` or `usingConfig`. The `getConfig` function will introduce a dependency on the configuration variable (but not the whole configuration file), and if the configuration variable changes, the rule will be rerun. As an example:

    usingConfigFile "myconfiguration.cfg"
    "*.o" %> \out -> do
        cflags <- getConfig "CFLAGS"
        cmd "gcc" [out -<.> "c"] (fromMaybe "" cflags)

getConfigKeys :: Action [String] #

Obtain the configuration keys. Any build system using `getConfigKeys` must call either `usingConfigFile` or `usingConfig`. The `getConfigKeys` function will introduce a dependency on the configuration keys (but not the whole configuration file), and if the configuration keys change, the rule will be rerun. Usually use as part of an action. As an example:

    usingConfigFile "myconfiguration.cfg"
    action $ need =<< getConfigKeys