| 1 | <!DOCTYPE html> |
|---|
| 2 | <html> |
|---|
| 3 | <head> |
|---|
| 4 | <title>FCM: User Guide: Annex: Declarations in FCM 1 extract configuration |
|---|
| 5 | file</title> |
|---|
| 6 | <meta name="author" content="FCM team" /> |
|---|
| 7 | <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
|---|
| 8 | <link rel="icon" href="../etc/fcm-icon.png" type="image/png" /> |
|---|
| 9 | <link rel="shortcut icon" href="../etc/fcm-icon.png" type="image/png" /> |
|---|
| 10 | <link href="../etc/bootstrap/css/bootstrap.min.css" rel="stylesheet" media="screen" /> |
|---|
| 11 | <link href="../etc/fcm.css" rel="stylesheet" media="screen" /> |
|---|
| 12 | </head> |
|---|
| 13 | <body> |
|---|
| 14 | <div class="navbar navbar-inverse"> |
|---|
| 15 | <div class="container-fluid"> |
|---|
| 16 | <div class="navbar-header"> |
|---|
| 17 | <a class="navbar-brand" href=".."><span class="fcm-version">FCM</span></a> |
|---|
| 18 | </div> |
|---|
| 19 | <div class="collapse navbar-collapse"> |
|---|
| 20 | <ul class="nav navbar-nav"> |
|---|
| 21 | <li><a href="../installation/">Installation</a></li> |
|---|
| 22 | |
|---|
| 23 | <li><a class="active" href="#">User Guide</a></li> |
|---|
| 24 | </ul> |
|---|
| 25 | </div> |
|---|
| 26 | </div> |
|---|
| 27 | </div> |
|---|
| 28 | |
|---|
| 29 | <div class="page-header"> |
|---|
| 30 | <div class="fcm-page-content pull-right well well-sm"></div> |
|---|
| 31 | <h1>FCM: User Guide: Annex: Declarations in FCM 1 extract configuration |
|---|
| 32 | file</h1> |
|---|
| 33 | </div> |
|---|
| 34 | |
|---|
| 35 | <div class="container"> |
|---|
| 36 | <div class="row"> |
|---|
| 37 | <div class="col-md-12"> |
|---|
| 38 | |
|---|
| 39 | <p><em>The FCM 1 extract system is deprecated. The documentation for the |
|---|
| 40 | current extract system can be found at <a href="make.html">FCM |
|---|
| 41 | Make</a>.</em></p> |
|---|
| 42 | |
|---|
| 43 | <p>The following is a list of supported declarations for the configuration |
|---|
| 44 | file used by the FCM extract system. Unless otherwise stated, the fields in |
|---|
| 45 | all declaration labels are not case sensitive.</p> |
|---|
| 46 | |
|---|
| 47 | <dl> |
|---|
| 48 | <dt>CFG::TYPE</dt> |
|---|
| 49 | |
|---|
| 50 | <dd> |
|---|
| 51 | <p>The configuration file type, the value should always be |
|---|
| 52 | <samp>ext</samp> for an extract configuration file. This declaration is |
|---|
| 53 | compulsory for all extract configuration files.</p> |
|---|
| 54 | |
|---|
| 55 | <p>Example:</p> |
|---|
| 56 | <pre> |
|---|
| 57 | cfg::type ext |
|---|
| 58 | </pre> |
|---|
| 59 | </dd> |
|---|
| 60 | |
|---|
| 61 | <dt>CFG::VERSION</dt> |
|---|
| 62 | |
|---|
| 63 | <dd> |
|---|
| 64 | <p>The file format version, currently <samp>1.0</samp> - a version is |
|---|
| 65 | included so that we shall be able to read the configuration file |
|---|
| 66 | correctly should we decide to change its format in the future.</p> |
|---|
| 67 | |
|---|
| 68 | <p>Example:</p> |
|---|
| 69 | <pre> |
|---|
| 70 | cfg::version 1.0 |
|---|
| 71 | </pre> |
|---|
| 72 | </dd> |
|---|
| 73 | |
|---|
| 74 | <dt>%<name></dt> |
|---|
| 75 | |
|---|
| 76 | <dd> |
|---|
| 77 | <p><code>%<name></code> declares an internal variable |
|---|
| 78 | <var><name></var> that can later be re-used.</p> |
|---|
| 79 | |
|---|
| 80 | <p>Example:</p> |
|---|
| 81 | <pre> |
|---|
| 82 | %my_variable foo |
|---|
| 83 | src::bar::base %my_variable |
|---|
| 84 | src::egg::base %my_variable |
|---|
| 85 | src::ham::base %my_variable |
|---|
| 86 | </pre> |
|---|
| 87 | </dd> |
|---|
| 88 | |
|---|
| 89 | <dt>INC</dt> |
|---|
| 90 | |
|---|
| 91 | <dd> |
|---|
| 92 | <p>This declares the name of a file containing extract configuration. The |
|---|
| 93 | lines in the declared file will be included inline to the current |
|---|
| 94 | configuration file.</p> |
|---|
| 95 | |
|---|
| 96 | <p>Example:</p> |
|---|
| 97 | <pre> |
|---|
| 98 | inc ~frva/var_stable_22.0/cfg/ext.cfg |
|---|
| 99 | # ... and then your changes ... |
|---|
| 100 | </pre> |
|---|
| 101 | </dd> |
|---|
| 102 | |
|---|
| 103 | <dt>DEST[::ROOTDIR]</dt> |
|---|
| 104 | |
|---|
| 105 | <dd> |
|---|
| 106 | <p>The <em>root</em> path of the destination of this extract. This |
|---|
| 107 | declaration is compulsory for all extract configuration files.</p> |
|---|
| 108 | |
|---|
| 109 | <p>Example:</p> |
|---|
| 110 | <pre> |
|---|
| 111 | dest $HOME/project/my_project |
|---|
| 112 | </pre> |
|---|
| 113 | </dd> |
|---|
| 114 | |
|---|
| 115 | <dt>USE</dt> |
|---|
| 116 | |
|---|
| 117 | <dd> |
|---|
| 118 | <p>This declares the location of a previous successful extract, which the |
|---|
| 119 | current extract will inherit from. If the previous extract is also a |
|---|
| 120 | build, the subsequent invocation of the build system on the current |
|---|
| 121 | extract will automatically trigger an inherited incremental build based |
|---|
| 122 | on that build.</p> |
|---|
| 123 | |
|---|
| 124 | <p>Example:</p> |
|---|
| 125 | <pre> |
|---|
| 126 | use ~frva/var_stable_22.0 |
|---|
| 127 | # ... and then the settings for your current extract ... |
|---|
| 128 | </pre> |
|---|
| 129 | </dd> |
|---|
| 130 | |
|---|
| 131 | <dt>RDEST[::ROOTDIR]</dt> |
|---|
| 132 | |
|---|
| 133 | <dd> |
|---|
| 134 | <p>The alternate destination of this extract. This declaration is |
|---|
| 135 | compulsory if this extract requires mirroring to an alternate |
|---|
| 136 | destination.</p> |
|---|
| 137 | |
|---|
| 138 | <p>Example:</p> |
|---|
| 139 | <pre> |
|---|
| 140 | rdest /home/nwp/da/frva/project/my_project |
|---|
| 141 | </pre> |
|---|
| 142 | </dd> |
|---|
| 143 | |
|---|
| 144 | <dt>RDEST::LOGNAME</dt> |
|---|
| 145 | |
|---|
| 146 | <dd> |
|---|
| 147 | <p>The login name of the user on the alternate destination machine. If |
|---|
| 148 | not specified, the current login name of the user on the local platform |
|---|
| 149 | is assumed.</p> |
|---|
| 150 | |
|---|
| 151 | <p>Example:</p> |
|---|
| 152 | <pre> |
|---|
| 153 | rdest::logname frva |
|---|
| 154 | </pre> |
|---|
| 155 | </dd> |
|---|
| 156 | |
|---|
| 157 | <dt>RDEST::MACHINE</dt> |
|---|
| 158 | |
|---|
| 159 | <dd> |
|---|
| 160 | <p>The destination machine for this extract. If not specified, the current |
|---|
| 161 | host name is assumed.</p> |
|---|
| 162 | |
|---|
| 163 | <p>Example:</p> |
|---|
| 164 | <pre> |
|---|
| 165 | rdest::machine tx01 |
|---|
| 166 | </pre> |
|---|
| 167 | </dd> |
|---|
| 168 | |
|---|
| 169 | <dt> |
|---|
| 170 | RDEST::MIRROR_CMD<br /> |
|---|
| 171 | <del>MIRROR</del> |
|---|
| 172 | </dt> |
|---|
| 173 | |
|---|
| 174 | <dd> |
|---|
| 175 | <p>The extract system can mirror the extracted source to an alternate |
|---|
| 176 | machine. Currently, it does this using either the <code>rdist</code> or |
|---|
| 177 | the <code>rsync</code> command. The default is <samp>rsync</samp>. This |
|---|
| 178 | declaration can be used to switch to using <samp>rdist</samp>.</p> |
|---|
| 179 | |
|---|
| 180 | <p>Example:</p> |
|---|
| 181 | <pre> |
|---|
| 182 | rdest::mirror_cmd rdist |
|---|
| 183 | </pre> |
|---|
| 184 | </dd> |
|---|
| 185 | |
|---|
| 186 | <dt> |
|---|
| 187 | RDEST::RSH_MKDIR_RSH (<del>RDEST::REMOTE_SHELL</del>)<br /> |
|---|
| 188 | RDEST::RSH_MKDIR_RSHFLAGS<br /> |
|---|
| 189 | RDEST::RSH_MKDIR_MKDIR<br /> |
|---|
| 190 | RDEST::RSH_MKDIR_MKDIRFLAGS |
|---|
| 191 | </dt> |
|---|
| 192 | |
|---|
| 193 | <dd> |
|---|
| 194 | <p>If <code>rsync</code> is used to mirror an extract, the system needs to |
|---|
| 195 | issue a separate remote shell command to create the container directory of |
|---|
| 196 | the mirror destination. The default is to issue a shell command in the |
|---|
| 197 | form <samp>ssh -n -oBatchMode=yes LOGNAME@MACHINE mkdir -p DEST</samp>. |
|---|
| 198 | These declarations can be used to modify the command.</p> |
|---|
| 199 | |
|---|
| 200 | <p>Example:</p> |
|---|
| 201 | <pre> |
|---|
| 202 | # Examples using the default settings: |
|---|
| 203 | rdest::rsh_mkdir_rsh ssh |
|---|
| 204 | rdest::rsh_mkdir_rshflags -n -oBatchMode=yes |
|---|
| 205 | rdest::rsh_mkdir_mkdir mkdir |
|---|
| 206 | rdest::rsh_mkdir_mkdirflags -p |
|---|
| 207 | </pre> |
|---|
| 208 | </dd> |
|---|
| 209 | |
|---|
| 210 | <dt> |
|---|
| 211 | RDEST::RSYNC<br /> |
|---|
| 212 | RDEST::RSYNCFLAGS |
|---|
| 213 | </dt> |
|---|
| 214 | |
|---|
| 215 | <dd> |
|---|
| 216 | <p>These declarations are only useful if <code>rsync</code> is used to |
|---|
| 217 | mirror an extract. By default, the system issues the shell command |
|---|
| 218 | <samp>rsync -a --exclude='.*' --delete-excluded --timeout=900 --rsh='ssh |
|---|
| 219 | -oBatchMode=yes' SOURCE DEST</samp>. These declarations can be used to |
|---|
| 220 | modify the command.</p> |
|---|
| 221 | |
|---|
| 222 | <p>Example:</p> |
|---|
| 223 | <pre> |
|---|
| 224 | # Examples using the default settings: |
|---|
| 225 | rdest::rsync rsync |
|---|
| 226 | rdest::rsyncflags -a --exclude='.*' --delete-excluded --timeout=900 \ |
|---|
| 227 | --rsh='ssh -oBatchMode=yes' |
|---|
| 228 | </pre> |
|---|
| 229 | </dd> |
|---|
| 230 | |
|---|
| 231 | <dt>REPOS::<pck>::<branch></dt> |
|---|
| 232 | |
|---|
| 233 | <dd> |
|---|
| 234 | <p>This declares a URL or a local file system path for the container |
|---|
| 235 | <em>repository</em> of a branch named <branch> in a package named |
|---|
| 236 | <pck>. The package name <pck> must be the name of a top-level |
|---|
| 237 | package (i.e. it must not contain the double colon <code>::</code> |
|---|
| 238 | delimiter). The name <branch> is used internally within the extract |
|---|
| 239 | system, and so is independent of the branch name of the code management |
|---|
| 240 | system. However, it is usually desirable to use the same name of the |
|---|
| 241 | actual branch in the code management system. For declaration of a local |
|---|
| 242 | file system path, the convention is to name the branch <samp>user</samp>. |
|---|
| 243 | Please note that both <pck> and <branch> fields are case |
|---|
| 244 | sensitive. The declared URL must be a valid Subversion URL or a valid FCM |
|---|
| 245 | URL keyword.</p> |
|---|
| 246 | |
|---|
| 247 | <p>Example:</p> |
|---|
| 248 | <pre> |
|---|
| 249 | repos::var::base fcm:var_tr |
|---|
| 250 | repos::var::branch1 fcm:var_br/frsn/r4790_foobar |
|---|
| 251 | repos::var::user $HOME/var |
|---|
| 252 | </pre> |
|---|
| 253 | </dd> |
|---|
| 254 | |
|---|
| 255 | <dt> |
|---|
| 256 | REVISION::<pck>::<branch><br /> |
|---|
| 257 | <del>VERSION::<pck>::<branch></del> |
|---|
| 258 | </dt> |
|---|
| 259 | |
|---|
| 260 | <dd> |
|---|
| 261 | <p>The revision to be used for the URL of <branch> in the package |
|---|
| 262 | <pck>. If specified, the revision must be a revision where the |
|---|
| 263 | branch exists. If not specified, the revision defaults to last changed |
|---|
| 264 | revision at the HEAD of the branch. Please note that if the declared |
|---|
| 265 | <em>branch</em> is in the local file system, this declaration must not be |
|---|
| 266 | used. The value of the declaration can be a FCM revision keyword or any |
|---|
| 267 | revision argument acceptable by Subversion. You can use a valid revision |
|---|
| 268 | number, a date between a pair of curly brackets (e.g. <samp>{"2005-05-01 |
|---|
| 269 | 12:00"}</samp>) or the keyword HEAD. However, please do not use the |
|---|
| 270 | keywords BASE, COMMITTED or PREV as these are reserved for working copies |
|---|
| 271 | only. Again, please note that both <pck> and <branch> fields |
|---|
| 272 | are case sensitive.</p> |
|---|
| 273 | |
|---|
| 274 | <p>Example:</p> |
|---|
| 275 | <pre> |
|---|
| 276 | # Declare the revision with the FCM revision keyword "vn22.0" |
|---|
| 277 | revision::var::base vn22.0 |
|---|
| 278 | # Declare the revision with a {date} |
|---|
| 279 | revision::var::branch1 {2006-01-01} |
|---|
| 280 | </pre> |
|---|
| 281 | </dd> |
|---|
| 282 | |
|---|
| 283 | <dt>REVMATCH</dt> |
|---|
| 284 | |
|---|
| 285 | <dd> |
|---|
| 286 | <p>If set to true, the declared revision of a branch must be a changed |
|---|
| 287 | revision of that branch, (unless the keyword HEAD is used).</p> |
|---|
| 288 | |
|---|
| 289 | <p>Example:</p> |
|---|
| 290 | <pre> |
|---|
| 291 | revmatch true |
|---|
| 292 | </pre> |
|---|
| 293 | </dd> |
|---|
| 294 | |
|---|
| 295 | <dt>SRC::<pcks>::<branch></dt> |
|---|
| 296 | |
|---|
| 297 | <dd> |
|---|
| 298 | <p>This declares a source directory for the sub-package <pcks> of |
|---|
| 299 | <branch>. If the repository is declared as a URL, the source |
|---|
| 300 | directory must be quoted as a relative path to the URL. If the repository |
|---|
| 301 | is declared as a path in the local file system, the source directory can |
|---|
| 302 | be declared as either a relative path to the <em>repository</em> or a |
|---|
| 303 | full path. If the source directory is a relative path and <pcks> is |
|---|
| 304 | a top-level package, the full name of the sub-package will be determined |
|---|
| 305 | automatically using the directory names of the relative path as the names |
|---|
| 306 | of the sub-packages. If the source directory is a full path, the full |
|---|
| 307 | sub-package name must be specified. The name of the sub-package |
|---|
| 308 | determines the destination path of the source directory in the |
|---|
| 309 | extract.</p> |
|---|
| 310 | |
|---|
| 311 | <p>Example:</p> |
|---|
| 312 | <pre> |
|---|
| 313 | src::var::base code/VarMod_PF |
|---|
| 314 | src::var/code/VarMod_PF::user $HOME/var/code/VarMod_PF |
|---|
| 315 | </pre> |
|---|
| 316 | </dd> |
|---|
| 317 | |
|---|
| 318 | <dt>EXPSRC::<pcks>::<branch></dt> |
|---|
| 319 | |
|---|
| 320 | <dd> |
|---|
| 321 | <p>This declares an expandable source directory for the sub-package |
|---|
| 322 | <pcks> of <branch>. This declaration is essentially the same |
|---|
| 323 | as the SRC declaration, except that the system will attempt to search |
|---|
| 324 | recursively for sub-directories within the declared source directory.</p> |
|---|
| 325 | |
|---|
| 326 | <p>Example:</p> |
|---|
| 327 | <pre> |
|---|
| 328 | expsrc::var::base code |
|---|
| 329 | expsrc::var::user code |
|---|
| 330 | </pre> |
|---|
| 331 | </dd> |
|---|
| 332 | |
|---|
| 333 | <dt> |
|---|
| 334 | CONFLICT<br /> |
|---|
| 335 | <del>OVERRIDE</del> |
|---|
| 336 | </dt> |
|---|
| 337 | |
|---|
| 338 | <dd> |
|---|
| 339 | <p>This declaration can be used to specify the conflict mode, which is |
|---|
| 340 | relevant when a file is modified by two different branches (or more) |
|---|
| 341 | relative to the base branch. The conflict mode can be <samp>fail</samp>, |
|---|
| 342 | <samp>merge</samp> (default) or <samp>override</samp> (or 0, 1 and 2 |
|---|
| 343 | respectively). If <samp>fail</samp> is specified, the extract fails when |
|---|
| 344 | a file is modified by two branches (or more) relative to the base branch. |
|---|
| 345 | If <samp>merge</samp> is specified, the system will attempt to merge the |
|---|
| 346 | changes. It will fail only on unresolved conflicts. If |
|---|
| 347 | <samp>override</samp> is specified, the changes in the last branch takes |
|---|
| 348 | precedence and the changes in the earlier branches will be ignored. Note: |
|---|
| 349 | the old <code>override true|false</code> declaration is deprecated. If |
|---|
| 350 | declared, <code>override true</code> will be equivalent to <code>conflict |
|---|
| 351 | override</code>, and <code>override false</code> will be equivalent to |
|---|
| 352 | <code>conflict fail</code>.</p> |
|---|
| 353 | |
|---|
| 354 | <p>Example:</p> |
|---|
| 355 | <pre> |
|---|
| 356 | conflict override |
|---|
| 357 | </pre> |
|---|
| 358 | </dd> |
|---|
| 359 | |
|---|
| 360 | <dt>BLD::<fields></dt> |
|---|
| 361 | |
|---|
| 362 | <dd> |
|---|
| 363 | <p>Declare a build configuration file declaration. The label |
|---|
| 364 | <fields> is the label of the declaration. On a successful extract, |
|---|
| 365 | <fields> will be added to the build configuration file. Please note |
|---|
| 366 | that some of the <fields> may be case sensitive.</p> |
|---|
| 367 | |
|---|
| 368 | <p>Example:</p> |
|---|
| 369 | <pre> |
|---|
| 370 | bld::target VarScr_AnalysePF |
|---|
| 371 | bld::tool::fc sxmpif90 |
|---|
| 372 | bld::tool::cc sxmpic++ |
|---|
| 373 | # ... and so on ... |
|---|
| 374 | </pre> |
|---|
| 375 | </dd> |
|---|
| 376 | </dl> |
|---|
| 377 | |
|---|
| 378 | </div> |
|---|
| 379 | </div> |
|---|
| 380 | </div> |
|---|
| 381 | |
|---|
| 382 | <hr/> |
|---|
| 383 | <div class="container-fluid text-center"> |
|---|
| 384 | <div class="row"><div class="col-md-12"> |
|---|
| 385 | <address><small> |
|---|
| 386 | © British Crown Copyright 2006-16 |
|---|
| 387 | <a href="http://www.metoffice.gov.uk">Met Office</a>. |
|---|
| 388 | See <a href="../etc/fcm-terms-of-use.html">Terms of Use</a>.<br /> |
|---|
| 389 | This document is released under the British <a href= |
|---|
| 390 | "http://www.nationalarchives.gov.uk/doc/open-government-licence/" rel= |
|---|
| 391 | "license">Open Government Licence</a>.<br /> |
|---|
| 392 | </small></address> |
|---|
| 393 | </div></div> |
|---|
| 394 | </div> |
|---|
| 395 | |
|---|
| 396 | <script type="text/javascript" src="../etc/jquery.min.js"></script> |
|---|
| 397 | <script type="text/javascript" src="../etc/bootstrap/js/bootstrap.min.js"></script> |
|---|
| 398 | <script type="text/javascript" src="../etc/fcm.js"></script> |
|---|
| 399 | <script type="text/javascript" src="../etc/fcm-version.js"></script> |
|---|
| 400 | </body> |
|---|
| 401 | </html> |
|---|
