An empty line, a line with only space characters and a line beginning with a # character is a comment line. For example:
# This is a comment.
# This is also a comment.
Also, if a line contains a space character followed by a # character then this, and any following characters, are treated as an end of line comment and are ignored.
The general syntax of a declaration consists of a label, a set of modifiers, a list of name-spaces, and a value:
label{mod:mod-value}[ns] = value
label{mod:mod-value} = value
label[ns] = value
label = value
label = value\
value # "value value"
label = value\
\value # "valuevalue"
The label is compulsory. It defines the declaration, and may have one or more characters in the alpha-numeric, the underscore, the minus sign and the full stop. The label cannot be substituted with a variable.
The modifier is an optional part of the syntax, but may be a compulsory part of some declarations. The modifiers are embedded between a pair of curly braces and must come after the label, but before the name-spaces and the equal sign. It should be a comma-separated list of colon-separated key-value pairs, (i.e. {key1: value1, key2: value2, ...}). The value in each modifier is optional - if a key is set without a value, its value is assumed to be 1. The contents of the modifiers can be substituted using a variable.
The name-space is an optional part of the syntax, but may be a compulsory part of some declarations. The name-spaces are embedded between a pair of square braces and must come after the label and/or modifiers but before the equal sign. It should be a space-separated list of names. If a name contains space, the space character can be escaped using a backslash character or the name can be quoted. The contents of the name-spaces can be substituted using a variable.
The first non-space character after the equal sign begins the value of the declaration. If there is nothing after the equal sign, the value is an empty string. The contents of the value can be substituted using a variable. Trailing space characters are ignored. The end of line can be escaped using a backslash, and the value of the declaration will continue from the next non-comment line. If the first non-space character on that line is a backslash then the line contents up to and including that backslash are ignored.
A variable is used to substitute commonly used values in a declaration. It can refer to an environment variable or can be defined locally using the syntax:
$var = value # Sets "var" variable to "value"
$var{?} = value # Sets "var" variable to "value" only if "var" is not defined
# E.g.:
$projects = foo bar baz
$long_path = src/path/is/very/very/very/long
$UMDIR{?} = /projects/um1
# time passes...
extract.ns = $projects
extract.path-excl[$projects egg ham] = doc man ${long_path}_longer
build.prop{cc.defs} = foo=\$foo # escape substitution
The name of a variable must begin with an alphabet or an underscore and followed by 0 or more alpha-numeric or underscore characters, (i.e. it must match this regular expression: ^[A-Za-z_][A-Za-z0-9_]*$).
Locally defined variables only apply in the context of the configuration file and are not passed down, for instance, to the compiler. If there is an environment variable with the same identifier, its value is normally overridden (within the context of the configuration file) by any local setting. However, if a ? modifier is given, it assigns the value to the variable only if the variable is not already defined (either as an environment variable or locally). Substitution can be escaped using a backslash character in front of the dollar sign. Any attempt to reference an undefined variable will trigger an exception.
Note: $HERE is a reserved variable to indicate the parent directory of the current configuration file. (The system ignores the $HERE environment variable, if there is one.) Any attempt to assign a value to $HERE will trigger an exception.
An include declaration specifies the logical locations of a
list of configuration files, where contents are to be included inline:
include{type:type} = location ...
# E.g.:
include = fcm:foo/path/to/config/file
include = svn://server/path/to/config/file@1234
include{type:svn} = http://server/path/to/config/file
include = /path/to/config/file $HERE/another-config-file
include = $HERE/another-config-file
include = ~/path/to/config/file ~fred/path/to/config/file
If the value of an include declaration is a relative path,
the system will search the directory containing the current configuration
file for the include file. More include search paths can be specified using
the include-path declaration. E.g.:
# Define or replace include search paths
include-path=/path/to/some/cfg /path/to/more/cfg
# Append to include search paths
include-path{+}=host2:/path/to/cfg
include-path{type:svn,+}=https://host1/path/to/cfg
# ... Include files can now be relative paths
include=foo.cfg bar.cfg
Some commands, e.g. fcm make, accept one or more
--config-file-path=PATH command line option, which can be used
to pre-define the include search paths when they read their configuration
files.
Currently, the location can be a path in the file system, a Subversion URL,
a FCM keyword pointing to a Subversion URL, or a location in the file system
of a remote host accessible via passphrase-less SSH. The system will attempt
to make an intelligent guess of the location type. To allow for future
expansion, both the include and the include-path
declarations accept a type:TYPE modifier (where TYPE can currently
be fs for a file system path or svn for a Subversion
location) to allow the location type to be defined where it is ambiguous.
The keyword configuration files are mainly used to define FCM location
keywords and related settings. The fcm command searches for
keyword configuration files from the following locations:
fcm is installed.The following are declarations recognised by the keyword configuration files:
description: Associates a namespace with a location, and allows the use of fcm:namespace as a substitute of the location.
modifier: primary: Optional. If specified, the location is a primary location, i.e. the system will create the _tr, _br, _tg, -tr, -br and -tg keywords for this location.
modifier: type: Optional. Specifies the type of the location. The system currently supports svn for a Subversion location and fs for a file system location. If not specified, the system will make an intelligent guess based on the given value.
namespace: The namespace to be associated with the location.
value: A valid location of a type supported by the system.
example:
location{primary}[var] = svn://fcm5/VAR_svn/VAR
location{primary, type:svn}[egg] = http://chicken/egg
description: Associates a keyword with a revision of a location in a version control system.
namespace: The namespace of a location (already defined
using the location declaration), followed by a colon and the
namespace of the revision.
value: A valid revision of the location.
example:
revision[um:vn7.5] = 18479 revision[egg:free-range] = 1
description: Specifies a regular expression to capture
components in the scheme-specific part of a version control system
location (already defined using the location{primary}
declaration). These components can then be used in the
browser.loc-tmpl template string.
namespace: Optional. The namespace of a location. If not specified, the declaration applies globally.
value: A valid regular expression.
example:
browser.comp-pat = (?msx-i:\A // ([^/]+) /+ ([^/]+)_svn /*(.*) \z) # default browser.comp-pat[egg] = (?msx-i:\A//([^/]+)/(.*)\z)
description: Specifies a template string, in which the
components captured by the browser.comp.pat regular
expression are used to fill in the numbered fields. The template should
have one more field than the number of components captured by
browser.comp-pat. The final field is used to place the
revision, which is generated via the browser.rev-tmpl.
namespace: Optional. The namespace of a location. If not specified, the declaration applies globally.
value: A valid template.
example:
browser.loc-tmpl = http://{1}/projects/{2}/intertrac/source:/{3}{4} # default
browser.loc-tmpl[egg] = http://{1}/intertrac/source:/{3}{4}
description: Specifies a template string, which should have a single numbered field for filling in the revision number.
namespace: Optional. The namespace of a location. If not specified, the declaration applies globally.
value: A valid template.
example:
browser.rev-tmpl = @{1} # default
The external configuration files are used to define the name of external
commands used by the FCM system. The fcm command searches for
external configuration files from the following locations:
fcm is installed.The following are declarations recognised by the external configuration files:
description: Specifies the command to invoke the web browser. (default=firefox)
example:
browser = konqueror
description: The shell command used by the extract system of FCM Make to perform a 3-way merge. (default=diff3)
example:
diff3 = diff3
description: The options used by the 3-way merge shell command. (default=-E -m)
example:
diff3.flags = -E -m
description: Specifies the command to invoke the graphic diff tool. (default=xxdiff)
example:
graphic-diff = tkdiff
description: Specifies the command to invoke the graphic merge tool. (default=xxdiff)
example:
graphic-merge = xxdiff
description: The secure remote shell command to execute commands on a remote host. (default=ssh)
example:
ssh = ssh
description: The options used by the secure shell command to execute commands on a remote host. (default=-n -oBatchMode=yes)
example:
ssh.flags = -n -oBatchMode=yes
description: The rsync command.
(default=rsync)
example:
rsync = rsync
description: The options used by the rsync
command. (default=-a --exclude=.* --delete-excluded --timeout=900
--rsh=ssh\ -oBatchMode=yes)
example:
rsync.flags = -a --exclude=.* --delete-excluded --timeout=900 --rsh=ssh\ -oBatchMode=yes
A typical FCM make configuration consists of some top level declarations to define the make, and specific declarations for each step. The top level declarations are described below, and the specific declarations for each type of step will be described in the sub-sections to follow.
Note:
# Sets the Fortran compiler flags for the root name-space
build.prop{fc.flags} = -O3
# build.prop{fc.flags}[/] = -O3
# Sets the C/Fortran compiler flags for the "foo/bar" name-space
build.prop{cc.flags, fc.flags}[foo/bar] = -g -C
# build.prop{cc.flags}[foo/bar] = -g -C
# build.prop{fc.flags}[/] = -O3
# build.prop{fc.flags}[foo/bar] = -g -C
# Sets the Fortran compiler flags for the root and "foo/bar" name-spaces
build.prop{fc.flags}[/ foo/bar] = -O2
# build.prop{cc.flags}[foo/bar] = -g -C
# build.prop{fc.flags}[/] = -O2
# build.prop{fc.flags}[foo/bar] = -O2
# Sets the Fortran compiler flags for the "foo/bar" name-spaces
build.prop{fc.flags}[foo/bar] = -O1
# build.prop{cc.flags}[foo/bar] = -g -C
# build.prop{fc.flags}[/] = -O2
# build.prop{fc.flags}[foo/bar] = -O1
build.prop{fc}) can be modified in:
fcm is
installed.The syntax is identical to a normal FCM make configuration file declaration except that:
For further details, please refer to the chapter on FCM Make.
description: Specifies a description string for the current make.
value: A string.
example:
description = Release 2.71.82
description: Specifies the output destination of the make system. If not specified, the system assumes the output destination to be the current working directory. This setting is not inherited.
value: A writable directory path.
example:
dest = path # E.g.: dest = $HERE
description: Specifies the NAME of the make, so that the
command will search for fcm-makeNAME.cfg
instead of
fcm-make.cfg
, and will write context files in
.fcm-makeNAME/
and log files as
fcm-makeNAME.log
, etc.
value: A file name friendly string.
example:
name = -friend
description: Specifies the minimum FCM version and optionally the maximum FCM version that can be used on the current configuration. If specified, FCM make fails immediately if its version does not meet the criteria.
value: The minimum version required, and optionally the maximum version required.
example:
# Requires minimum FCM release at 2016.02.0 require-version = 2016.02.0 # Requires minimum FCM release at 2016.02.0, and maximum at 2038.01.0 require-version = 2016.02.0 2038.01.0
description: Specifies a list of steps for the make system
to invoke. Each specified step can either be the ID of a known
sub-system, i.e. extract, mirror,
preprocess and build, or an ID defined using
the step.class declaration. (See below.)
value: A list of steps for the make system to invoke.
example:
steps = id-1 id-2 ... # E.g.: steps = extract mirror
description: Defines custom step IDs. This allows built-in steps to be renamed, or re-used in multiple steps.
namespace: Specifies the step IDs.
value: An ID of a known sub-system, i.e. extract, mirror, preprocess and build.
example:
step.class[id ...] = id-of-class # E.g.: step.class[build-qxrecon build-ieee] = build
description: Specifies inheritance locations. It is worth
noting that this declaration is cumulative, i.e. a use
declaration adds more inheritance locations rather than overrides the
inheritance locations of any previous use declarations.
value: A list of paths where this make can inherit items and properties from.
example:
use = path1 path2 ... E.g.: use = /path/to/inherit
All declarations are prefixed with extract.*. Where
appropriate, replace the leading extract with the appropriate
step ID. With the exception of the extract.location{diff}
declaration, any attempt to specify any extract declarations in an inherited
extract will result in an exception.
description: Specifies a list of names of the projects to extract.
value: A space-delimited list of names of the projects to extract.
example:
extract.ns = gen ops um var ver
description: Specifies the location of the base source tree a project. If the base source tree is not specified for a Subversion project, the system will try to use trunk@HEAD.
modifier: type: Specifies the type of the locations. The system currently supports svn for a Subversion location, ssh for a file system on a remote host accessible via SSH and RSYNC, and fs for a file system location. (default=svn if the location is recognised as a Subversion URL, ssh if the location has the form [USER@]HOST:PATH and HOST is a valid remote host, fs otherwise)
namespace: A space-delimited list of project IDs.
value: A location, which can be a full path in the file system, or a relative location of the project root.
example:
extract.location[um] = trunk@vn7.5 extract.location[gen ops var] = trunk@HEAD
description: Specifies the location(s) of one or more diff source trees of a project. It is OK to add more diff source trees in an inheriting extract.
modifier: type: -as above-
namespace: A project ID.
value: A space-delimited list of locations. A location can be a full path in the file system, or a relative location of the project root.
example:
extract.location{diff}[gen] = \
branches/dev/fred/r12345_678 \
branches/dev/free/r12345_678@123
description: Specifies the project locations for an extract, if they are not already defined in the keyword configuration.
modifier: type: -as above-
namespace: A project ID.
value: A project location. The location can be a path in the file system, a Subversion URL or a FCM keyword pointing to a Subversion URL.
example:
extract.location{primary}[egg] = svn://server2/egg
extract.location{primary,type:svn}[foo] = http://server1/foo
description: Specifies the paths in a project tree to exclude/include. (A path-incl takes precedence over a path-excl declaration.)
namespace: A space-delimited list of project IDs.
value: A space-delimited list of paths in a project tree.
example:
extract.path-excl[foo] = / # everything extract.path-incl[foo] = bin lib src/code
description: Specifies the root paths in the source trees
of the projects to be extracted. By default, the root path is the
root of a source tree. If this setting is specified, the system will only
extract source files under the specified root path. The system will also
adjust the name-space of each source file to be relative to the specified
root path. The extract.path-excl and
extract.path-incl declarations will apply from the level of
the specified root path.
namespace: A space-delimited list of project IDs.
value: A relative path in the project source trees.
example:
extract.path-root[gen] = src/code
description: Sets or modifies a property.
modifier: diff3: The shell command to perform a 3-way merge. If not specified, use the diff3 setting of the FCM external configuration.
modifier: diff3.flags: The options used by the 3-way merge shell command. If not specified, use the diff3.flags setting of the FCM external configuration.
value: The value of the property.
example:
extract.prop{diff3} = diff3
extract.prop{diff3.flags} = -E -m
All declarations are prefixed with mirror.*. Where appropriate, replace the leading mirror with the appropriate ID.
description: Specifies the mirror target. This setting is not inherited.
value: The mirror target.
example:
mirror.target = fred@server:/path/of/dest # Or if the current user ID is "fred" # Or if the user ID for "server" is configured under "~/.ssh/config" mirror.target = server:/path/of/dest # Or if mirroring to a path accessible only by user ID "bob" mirror.target = bob@localhost:/path/of/dest # Or if the current user ID is "fred" and local host is "server" mirror.target = /path/of/dest
description: Sets or modifies a property.
modifier: See below.
value: The value of the property.
example:
mirror.prop{rsync} = cnysr
The following is a list of properties accepted by the
mirror.prop declaration:
rsync command. If not specified, use the rsync setting of the FCM external configuration.rsync command. If not specified,
use the rsync.flags setting of the FCM
external configuration.All declarations are prefixed with build.*. Where appropriate, replace the leading build with the appropriate ID.
description: Specifies one or more source files and/or directories.
namespace: Optional. Specifies the namespace of the specified paths.
value: A list of space-delimited file system paths.
example:
build.source[foo] = $HOME/foo $DATADIR/foo
description: Specifies the name-spaces in the source tree
to exclude/include. (A build.ns-incl takes precedence over a
build.ns-excl declaration.)
value: A list of space-delimited items. Each item is a name-space to exclude/include.
example:
build.ns-excl = / # exclude everything build.ns-incl = foo bar/baz # include items in these name-spaces
description: Selects targets to build according to their keys, categories and tasks.
modifier: key (default if no modifier specified), category or task
namespace: Not allowed if modifier is key. Optional if modifier is category or task. If specified, setting only applies to given name-spaces. Otherwise, setting applies to all name-spaces.
value: A list of space-delimited items (according to the modifier).
example:
build.target{category}[etc/namelists etc/configs] = etc
build.target{category}[src/hello src/greet src/world] = bin lib
build.target{task}[src/public] = archive install
build.target = egg.sh mince.py
description: Rename targets.
value: A list of space-delimited items. Each item should be the (automatic) key of a target, followed by a colon and its preferred key.
example:
build.target-rename = hello.exe:hello
description: Sets or modifies a property.
modifier: The name of one (or more) property. See below.
namespace: Optional. A list of space-delimited namespaces to which this setting applies. The namespaces can be target names, when used with target properties (dependency properties are regarded as source properties), or the hierarchical namespaces of source files. If not specified, the setting applies to the global/root namespace. N.B. Not all build properties accept a namespace. See below for detail.
value: The value of the property.
example:
build.prop{fc} = gfortran
build.prop{cc.flags,fc.flags} = -C -g
build.prop{fc.flags}[foo/bar] = -C -g -W
build.prop{fc.flags}[egg ham bacon] = -C -W
build.prop{fc.flag-define} = -D%s
build.prop{cc.defs,fc.defs}[gen] = LOWERCASE UNDERSCORE
build.prop{fc.libs}[myprog.exe] = netcdf grib
The following is a list of properties accepted by the
build.prop declaration. The default value is an empty string
unless given otherwise. Properties that do not accept a namespace are marked
with an asterisk (*).
fcm make is invoked with the --archive
option, sub-directories in categories containing intermediate build files
will be put into TAR-GZIP files. E.g. with the default setting,
include/ and o/ will become
include.tar.gz and o.tar.gz respectively.
(default=include o)USE and
INCLUDE statements that are protected by !$
sentinels as normal dependency statements.The preprocess system uses the same declarations as the build system (see
FCM Make Configuration: Build), although their
prefixes should be replaced with preprocess.* or the appropriate
step ID. The following is a list of modifiers accepted by the
preprocess.prop declaration. The default value of a property is
an empty string unless given otherwise. Properties that do not accept a
namespace are marked with an asterisk (*).