<@page title="Configuration Files" keywords="configuration file"> <@sect title="Basics">

Configuration files are text files that store setting values. They can use two syntaxes (two formats):

The syntax that a configuration file uses is detected with the file extension. For "properties" configuration files, the file extension must be <@c>cfg or <@c>properties. For TDD files, the preferred file extension is <@c>fmpp, but it can be anything but <@c>cfg and <@c>properties.

When you want to load a configuration file, you specify the path of the file for the front-end somehow (read <@a href='frontends.html'>the documentation of the front-end). But if the configuration file name is one of these standard names:

then it is enough to give the path of the directory that contains the configuration file. (<@c>config.fmpp has higher priority if both file is present.)

<@sect title="The configuration base" anchor="configurationBase">

The configuration base is the directory used as base for resolving relative <@a href="overview.html#realPath">real paths in setting values. Be default, the configuration base is the directory that contains the configuration file. For example, if <@c>/home/me/project1/config.fmpp contains <@c>sourceRoot: src, then the <@s>sourceRoot will be <@c>/home/me/project1/src.

The configuration base can be changed with the <@s>configurationBase meta setting. For example, if in the previous example <@c>config.fmpp contains <@c>configurationBase: ../project2, then the <@s>sourceRoot will be <@c>/home/me/project2/src. The <@s>configurationBase setting applies only for the setting values specified in the same file it is stored in.

Not all relative paths in settings are resolved relatively to the <@s>configurationBase. Relative <@a href="overview.html#virtualPath">virtual paths, for example, are relative to the <@s>sourceRoot or <@s>outputRoot. Relative paths of data files passed to data loaders are relative to the <@s>dataRoot.

If the setting value comes not from a configuration file (such as from a command-line argument), then the front-end specifies what the configuration base is for that setting value (see the documentation of the front-end).

<@sect title="Configuration inheritance" anchor="inheritance">

A configuration file can inherit setting values from another configuration file, with the <@s>inheritConfiguration meta setting. When the FMPP core loads a configuration file, and it finds <@s>inheritConfiguration setting in it, it will automatically load that configuration file too, and then merge its settings with the settings loaded from the inheriting (the first) configuration file. The settings stored in the inheriting configuration file have higher priority than the settings stored in the inherited configuration file. Thus, if both file contains the same setting, then the value stored in the inheriting file will be used, or it will be merged with the other value if the setting supports merging.

The above description is applicable recursively. That is, an inherited configuration file can inherit another configuration file, and that can inherit yet another configuration file, and so on.

<@a href="settings.html#metaSettings">Meta settings (as <@s>inheritConfiguration and <@s>configurationBase) are never inherited. They influence only the file where they are actually present.

A possible usage of configuration inheritance is to customize a common configuration file. See: <@example path='inherit_config' />.

<@sect title="Configuration files with TDD syntax">

These files start in TDD hash mode. For example:

<@prg> sourceRoot: src outputRoot: out data: {tdd(data/style.tdd), birds:csv(data/birds.csv)} removeExtensions: [ftl, t2] datetimeFormat: "MMM d, yyyy hh:mm a zzz" caseSensitive

According the TDD syntax, values of type sequence (as <@s>removeExtensions) was put into square brackets. However, for sequence settings, if the sequence would contain exactly 1 element, then you can just give that element directly:

<@prg> removeExtensions: ftl

and the value will be automatically converted to a sequence that contains the a single string <@c>ftl, as it is known that <@s>removeExtensions must be a sequence. This is a feature of the setting handling mechanism, not TDD, so don't try to use this trick elsewhere.

TDD configuration files always use ISO-8859-1 encoding, if there is no other encoding suggested in the file with <@a href="tdd.html#encoding">TDD's encoding comment.

For more information about TDD, please read <@a href="tdd.html">the chapter about TDD.

<@sect title='Configuration files with "properties" syntax'>

<@e>Attention: "properties" configuration files must use <@c>cfg or <@c>properties file extension.

This is the previous example configuration file with "properties" format:

<@prg> sourceRoot = src outputRoot = out data = tdd(data/style.tdd), birds:csv(data/birds.csv) removeExtensions = ftl, t2 datetimeFormat = MMM d, yyyy hh:mm a zzz caseSensitive

The differences to TDD configuration files are:

Otherwise "properties" configuration files work in the same way as TDD configuration files. For example, they can inherit an other configuration file. It is not a problem if a "properties" configuration file inherits TDD configuration file or the opposite.