Author: FCM team

# FCM: User Guide: Annex: Declarations in FCM 1 extract configuration file

The FCM 1 extract system is deprecated. The documentation for the current extract system can be found at FCM Make.

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.

CFG::TYPE

  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

  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

%<name>

  `%<name>` declares an internal variable <name> that can later be re-used.

  Example:

      %my_variable   foo
      src::bar::base %my_variable
      src::egg::base %my_variable
      src::ham::base %my_variable

INC

  This declares the name of a file containing extract configuration. The lines in the declared file will be included inline to the current configuration file.

  Example:

      inc  ~frva/var_stable_22.0/cfg/ext.cfg
      # ... and then your changes ...

DEST[::ROOTDIR]

  The root path of the destination of this extract. This declaration is compulsory for all extract configuration files.

  Example:

      dest  $HOME/project/my_project

USE

  This declares the location of a previous successful extract, which the current extract will inherit from. If the previous extract is also a build, the subsequent invocation of the build system on the current extract 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 extract ...

RDEST[::ROOTDIR]

  The alternate destination of this extract. This declaration is compulsory if this extract requires mirroring to an alternate destination.

  Example:

      rdest  /home/nwp/da/frva/project/my_project

RDEST::LOGNAME

  The login name of the user on the alternate destination machine. If not specified, the current login name of the user on the local platform is assumed.

  Example:

      rdest::logname  frva

RDEST::MACHINE

  The destination machine for this extract. If not specified, the current host name is assumed.

  Example:

      rdest::machine  tx01

RDEST::MIRROR_CMD
MIRROR

  The extract system can mirror the extracted source to an alternate 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:

      rdest::mirror_cmd  rdist

RDEST::RSH_MKDIR_RSH (RDEST::REMOTE_SHELL)
RDEST::RSH_MKDIR_RSHFLAGS
RDEST::RSH_MKDIR_MKDIR
RDEST::RSH_MKDIR_MKDIRFLAGS

  If `rsync` is used to mirror an extract, the system needs to issue a separate remote shell command to create the container directory of the mirror destination. The default is to issue a shell command in the form `ssh -n -oBatchMode=yes LOGNAME@MACHINE mkdir -p DEST`. These declarations can be used to modify the command.

  Example:

      # Examples using the default settings:
      rdest::rsh_mkdir_rsh         ssh
      rdest::rsh_mkdir_rshflags    -n -oBatchMode=yes
      rdest::rsh_mkdir_mkdir       mkdir
      rdest::rsh_mkdir_mkdirflags  -p

RDEST::RSYNC
RDEST::RSYNCFLAGS

  These declarations are only useful if `rsync` is used to mirror an extract. By default, the system issues the shell command `rsync -a --exclude='.*' --delete-excluded --timeout=900 --rsh='ssh -oBatchMode=yes' SOURCE DEST`. These declarations can be used to modify the command.

  Example:

      # Examples using the default settings:
      rdest::rsync       rsync
      rdest::rsyncflags  -a --exclude='.*' --delete-excluded --timeout=900 \
                         --rsh='ssh -oBatchMode=yes'

REPOS::<pck>::<branch>

  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::base    fcm:var_tr
      repos::var::branch1 fcm:var_br/frsn/r4790_foobar
      repos::var::user    $HOME/var

REVISION::<pck>::<branch>
VERSION::<pck>::<branch>

  The revision to be used for the URL of <branch> in the package <pck>. If specified, the revision must be a revision where the branch exists. If not specified, the revision defaults to last changed revision at the HEAD of the branch. Please note that if the declared branch 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 copies only. Again, please note that both <pck> and <branch> fields are case sensitive.

  Example:

      # Declare the revision with the FCM revision keyword "vn22.0"
      revision::var::base     vn22.0
      # Declare the revision with a {date}
      revision::var::branch1  {2006-01-01}

REVMATCH

  If set to true, the declared revision of a branch must be a changed revision of that branch, (unless the keyword HEAD is used).

  Example:

      revmatch  true

SRC::<pcks>::<branch>

  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 names 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 extract.

  Example:

      src::var::base                    code/VarMod_PF
      src::var/code/VarMod_PF::user   $HOME/var/code/VarMod_PF

EXPSRC::<pcks>::<branch>

  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::base  code
      expsrc::var::user  code

CONFLICT
OVERRIDE

  This declaration can be used to specify the conflict mode, which is relevant when a file is modified by two different branches (or more) relative to the base branch. The conflict mode can be `fail`, `merge` (default) or `override` (or 0, 1 and 2 respectively). If `fail` is specified, the extract fails when a file is modified by two branches (or more) relative to the base branch. If `merge` is specified, the system will attempt to merge the changes. It will fail only on unresolved conflicts. If `override` is specified, the changes in the last branch takes precedence and the changes in the earlier branches will be ignored. Note: the old `override true|false` declaration is deprecated. If declared, `override true` will be equivalent to `conflict override`, and `override false` will be equivalent to `conflict fail`.

  Example:

      conflict  override

BLD::<fields>

  Declare a build configuration file declaration. The label <fields> is the label of the declaration. On a successful extract, <fields> will be added to the build configuration file. Please note that some of the <fields> may be case sensitive.

  Example:

      bld::target   VarScr_AnalysePF
      bld::tool::fc sxmpif90
      bld::tool::cc sxmpic++
      # ... and so on ...