FCM System User Guide Annex: Declarations in FCM extract configuration file
Author: FCM development team
Keywords: FCM, user guide, annex

# Annex:
Declarations in FCM extract configuration file

The following is a list of supported declarations for the configuration file used by the FCM extract system. Unless otherwise stated, the fields in all declaration labels are not case sensitive.

Label | Content
--- | ---
CFG::TYPE | Description | The configuration file type, the value should always be "ext" for an extract configuration file. This declaration is compulsory for all extract configuration files.
Example |
    cfg::type  ext
CFG::VERSION | Description | The file format version, currently "1.0" - a version is included so that we shall be able to read the configuration file correctly should we decide to change its format in the future.
Example |
    cfg::version  1.0
Label | Content
DEST::ROOTDIR | Description | The "root" path of the destination of this extraction. This declaration is compulsory for all extract configuration files.
Example |
    dest::rootdir  $HOME/project/my_project
RDEST::MACHINE | Description | The destination machine for this extraction. If set, the extraction will be mirrored to a location on this machine.
Example |
    rdest::machine  tx01
RDEST::LOGNAME | Description | The login name of the user on the remote destination machine. If not specified, the current login name of the user on the local platform is assumed.
Example |
    rdest::logname  frva
RDEST::ROOTDIR | Description | The "root" path of the remote destination of this extraction. This declaration is compulsory if this extraction requires mirroring to a remote machine.
Example |
    rdest::rootdir  /home/nwp/da/frva/project/my_project
Label | Content
REPOS::<pck>::<branch> | Description | This declares a URL or a local file system path for the container "repository" of a branch named <branch> in a package named <pck>. The package name <pck> must be the name of a top-level package (i.e. it must not contain the double colon "::" delimiter). The name <branch> is used internally within the extract system, and so is independent of the branch name of the code management system. However, it is usually desirable to use the same name of the actual branch in the code management system. For declaration of a local file system path, the convention is to name the branch "user". Please note that both <pck> and <branch> fields are case sensitive. The declared URL must be a valid Subversion URL or a valid FCM URL keyword.
Example |
    repos::var::trunk        fcm:var_tr
    repos::var::r4790_foobar fcm:var_br/frsn/r4790_foobar
    repos::var::user         $HOME/var
VERSION::<pck>::<branch> | Description | The revision to be used for the URL of <branch> in the package <pck>. If not specified, the revision defaults to "HEAD". Please note that if the delcared "repository" is in the local file system, this declaration must not be used. The value of the declaration can be a FCM revision keyword or any revision argument acceptable by Subversion. You can use a valid revision number, a date between a pair of curly brackets (e.g. {"2005-05-01 12:00"}) or the keyword "HEAD". However, please do not use the keywords "BASE", "COMMITTED" or "PREV" as these are reserved for working copy only. Again, please note that both <pck> and <branch> fields are case sensitive.
Example |
    # Declare the revision with the FCM revision keyword "vn22.0"
    version::var::trunk        vn22.0
    # Declare the revision with a {date}
    version::var::r4790_foobar {2006-01-01}
SRC::<pcks>::<branch> | Description | This declares a source directory for the sub-package <pcks> of <branch>. If the repository is declared as a URL, the source directory must be quoted as a relative path to the URL. If the repository is declared as a path in the local file system, the source directory can be declared as either a relative path to the "repository" or a full path. If the source directory is a relative path and <pcks> is a top-level package, the full name of the sub-package will be determined automatically using the directory names of the relative path as the name of the sub-packages. If the source directory is a full path, the full sub-package name must be specified. The name of the sub-package determines the destination path of the source directory in the extraction.
Example |
    src::var::trunk                   code/VarMod_PF
    src::var::code::VarMod_PF::user   $HOME/var/code/VarMod_PF
EXPSRC::<pcks>::<branch> | Description | This declares an expandable source directory for the sub-package <pcks> of <branch>. This declaration is essentially the same as the SRC declaration, except that the system will attempt to search recursively for sub-directories within the declared source directory.
Example |
    expsrc::var::trunk code
    expsrc::var::user  code
Label | Content
BLD::<fields> | Description | Declare a build configuration file declaration. The label <fields> is the label of the declaration. On a successful extraction, <fields> will be added to the build configuration file. Please note that some of the <fields> may be case sensitive.
Example |
    bld::name     var_stable_22.0
    bld::target   VarScr_AnalysePF
    bld::tool::fc sxmpif90
    bld::tool::cc sxmpic++
    # ... and so on ...
USE | Description | The declares the location of a previous successful extraction, which the current extraction will base on. If the previous extraction is also a build, the subsequent invocation of the build system on the current extraction will automatically trigger an inherited incremental build based on that build.
Example |
    use  ~frva/var_stable_22.0
    # ... and then the settings for your current extraction ...
INC | Description | This declares the name of a file containing extract configuration. The lines in the declared file will be included inline to the current extract configuration file.
Example |
    inc  ~frva/var_stable_22.0/cfg/ext.cfg
    # ... and then your changes ...
OVERRIDE | Description | If a file is modified by two different branches, this flag can be used to specify either to allow the later branch to override (1) the earlier one or to fail (0) the extraction. If not specified, the default is to fail (0).
Example |
    override  1
MIRROR | Description | The extract system can mirror the extracted source to a remote machine. Currently, it does this using either the rdist or the rsync command. The default is rsync. This declaration can be used to switch to using rdist.
Example |
    mirror  rdist
%<name> | Description | %<name> declares an internal variable <name> that can later be re-used.
Example |
    %my_variable      foo
    src::bar::trunk   %my_variable
    src::egg::trunk   %my_variable
    src::ham::trunk   %my_variable
Label | Content

The following declarations are for reference only. They should not be used in normal operations of the FCM extract system:

Label | Content
--- | ---
DEST::SRCDIR | Description | This declaration is optional and is not normally required. It is the "source" path of the desintation of this extraction. Source directories will be extracted to this directory. The default is to extract source directories to the "src/" sub-directory under the root path of the destination.
Example |
    dest::srcdir  $HOME/project/my_project/src
DEST::CFGDIR | Description | This declaration is optional and is not normally required. It is the "configuration" path of the destination of this extraction. Configuration files such as the expanded extraction configuration file and the build configuration file will be written in this location. The default is to send the configuration files to the "cfg/" sub-directory under the root path of the destination.
Example |
    dest::cfgdir  $HOME/project/my_project/cfg
DEST::CACHEDIR | Description | This declaration is optional and is not normally required. It is the cache directory used by this extraction. Source directories and other configuration files will normally be extracted and written to the cache directory before being copied to the destination. This ensures fast subsequent incremental extractions. It also reduces the load on the repository server. The default is use the ".cache/" sub-directory under the root path of the destination.
Example |
    dest::cachedir  $HOME/project/my_project/.cache
DEST::BLD_CFG | Description | This declaration is optional and is not normally required. It is the destination path of the build configuration file. By default, this file will be named "bld.cfg" and will be placed under the configuration directory, i.e. "cfg/bld.cfg" under the root path of the destination.
Example |
    dest::bld_cfg  $HOME/project/my_project/cfg/bld.cfg
DEST::EXT_CFG | Description | This declaration is optional and is not normally required. It is the destination path of the output expanded extract configuration file. By default, this file will be named "ext.cfg" and will be placed under the configuration directory, i.e. "cfg/ext.cfg" under the root path of the destination.
Example |
    dest::ext_cfg  $HOME/project/my_project/cfg/ext.cfg
RDEST::SRCDIR | Description | This declaration is optional and is not normally required. It is the "source" path of the remote desintation of this extraction. Source directories will be mirrored to this directory. The default is to mirror source directories to the "src/" sub-directory under the root path of the remote destination.
Example |
    rdest::srcdir  /home/nwp/da/frva/project/my_project/src
RDEST::CFGDIR | Description | This declaration is optional and is not normally required. It is the "configuration" path of the remote destination of this extraction. Configuration files such as the expanded extraction configuration file and the build configuration file are mirrored in this location. The default is to send the configuration files to the "cfg/" sub-directory under the root path of the remote destination.
Example |
    rdest::cfgdir  /home/nwp/da/frva/project/my_project/cfg
RDEST::BLD_CFG | Description | This declaration is optional and is not normally required. It is the remote destination path of the build configuration file. By default, this file will be named "bld.cfg" and will be placed under the configuration directory, i.e. "cfg/bld.cfg" under the root path of the remote destination.
Example |
    rdest::bld_cfg  /home/nwp/da/frva/project/my_project/cfg/bld.cfg
RDEST::EXT_CFG | Description | This declaration is optional and is not normally required. It is the remote destination path of the output expanded extract configuration file. By default, this file will be named "ext.cfg" and will be placed under the configuration directory, i.e. "cfg/ext.cfg" under the root path of the remote destination.
Example |
    rdest::ext_cfg  /home/nwp/da/frva/project/my_project/cfg/ext.cfg